web-app-sdk

Orkas Web App SDK

Build browser interfaces against the host SDK. Keep credentials, account identity, file paths and permission decisions in Orkas. Do not import Electron, forward arbitrary IPC or copy the Agent runtime into the app.

Find the actual contract

Read the API reference before choosing methods. It contains the executable registry's input schemas, result shapes, examples and unsupported families. Read the starter HTML and its manifest when starting a bundle or checking integration. These files are copyable inputs, not an executable Skill script.

The model's own tools are not Web APIs. tools.list in a running app lists only eligible existing executors; never invent SDK methods from host tool names.

Build and discover

1. Put orkas-app.json at the app bundle root. Set sdkVersion: 1 and declare only needed families from storage, appFiles, files, ai, library, connectors.
2. Load <script src="/__orkas/sdk.js"></script> before app code. Use window.orkasApp. Local bundles and external HTTP(S) scripts, styles and assets are supported in running apps and previews.
3. Call capabilities.list() to check support, declaration, availability and authorization separately. Use capabilities.describe({method}) for the current schema. Never treat a declaration or discovery result as consent.
4. Use api.<group>.<method>(arguments, {signal, onProgress}). Both options are optional; AI progress delivers text deltas. Render untrusted results with textContent, not HTML. Inspect tool isError and AI stopReason.
5. Deliver through the existing interactive-result or saved-app workflow and verify there. A loose HTML export or ordinary browser has no Orkas bridge.

Capability boundaries

• Storage: JSON values private to this account and app source. Set scope: "cloud" for business data to participate in the account's existing cloud sync; use scope: "local" for caches. Omitted scope remains local for old apps. There is no automatic migration from local or browser storage.
• App files: declare appFiles for relative-path text/binary files in the app's private sandbox. Its default scope is cloud; choose local for caches. Read/write/list/remove affect only this app. Source code is separate. Reopening keeps data; copied/re-saved apps have independent sandboxes. Cloud sync requires the same account and sync enabled on each device. Saved means persisted on this device, not uploaded. Conflicts use Orkas Settings; there is no SDK sync-status API. Keep explicit export for important data. Preview redirects both scopes to disposable storage; it cannot prove sync.
• Files: native selection returns an opaque handle to a read-only snapshot, not a path or permission to edit the original. Release handles after reading. Picker/save cancellation returns null. Text export creates a new file; an existing destination is refused. Orkas managed data cannot be selected.
• AI: configured model, supplied prompt only; no implicit conversation, project, Agent, tools or Skill context. Ordinary generation needs no separate app permission dialog. Requests can incur model charges; usage reports tokens, not price. Show partial output as incomplete when stopReason is max_tokens.
• Library: eligible global Library operations without a separate app consent. There is no inferred project binding from the source conversation.
• Connectors: discover tools.list(), then call its list_connector_tools executor to obtain enabled connector/action schemas before invoking call_connector_tool. Existing operation permissions apply: sensitive actions use the Orkas dialog; Trusted runs available actions without confirmation. Allow for this use covers the approved connector account and sensitive action class until this app instance closes. Other apps and reopened instances do not inherit it. External writes and fees are possible; inspect business errors. Connector installation is not exposed.

Use browser fetch/XHR, EventSource or WebSocket for external APIs; no SDK network method or manifest capability is needed. Browser CORS, mixed-content and endpoint authentication still apply. External scripts run with the app's declared SDK abilities. Handle failures and cancellation without replaying uncertain writes. Automated html_preview allows Web resources but isolates storage and disables account services; verify business actions in the running app.

Read unsupported in the reference for excluded families and reasons. Shell, task/Agent execution, Skill execution, project/history/ memory access, media generation and editing selected original files have no v1 adapter.

Failure and lifecycle

Catch each action's failure and show a useful recovery state. A denied action must leave the UI usable for an explicit retry. Never automatically replay AI or tool calls after uncertain failure: spending or a remote write may already have occurred. Aborting does not undo a completed external action.

Close, navigation away from the app, account switch, source change and permissions.revoke() invalidate the instance. Reopen for fresh grants. Do not persist file handles. When the host/model is unavailable, explain how to reopen in Orkas or configure a model; do not substitute fabricated results or direct provider requests.

File and JSON-store byte limits follow PC's 200 MiB ceiling. The SDK adds no quotas on file count, aggregate file bytes, storage-key count, instance count, cumulative requests or concurrent calls. Owning services retain their limits; AI output defaults to the configured model. Tool results are application data and do not use model-context token budgets. Initial host discovery times out after 10 seconds; after connecting, operations use the owning service's timeout and cancellation.

Language and interface quality

Use host.getContext().language for the app UI when no explicit app-language requirement overrides it. Apply it to visible labels, errors, empty states, accessible names and document lang, not just the model's reply. Preview returns the same selected host language; its unavailable services need preview-specific recovery rather than repeated configuration requests.

Use semantic HTML and accessible names for the actual controls and feedback. When a requested explanatory region is a note, expose role="note"; a CSS class named note alone has no accessibility semantics. Verify the rendered role and text through the visible interaction flow, including cancellation and export.

Verify delivery

Exercise the app's visible controls in Orkas: discover, use its declared capabilities, cancel/deny, recover explicitly, close/reopen and export. Check that an unrequested capability fails without side effects and that a second app cannot read the first app's state. Use local model fixtures for engineering tests; perform a billable test only within the user's explicit spending authorization.