@aiworker/sdk 1.24.0

package/DOCUMENTATION.md

@@ -0,0 +1,120 @@
+# AiWorker SDK
+
+Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`, `sdk/ui.mdx`, and `sdk/example.mdx`; the user page is `extensions.mdx`. Each has a copy under every locale folder.
+
+## Purpose
+
+`packages/sdk` owns the guest contract. `@aiworker/sdk` is the guest-facing entry: types, limits, `connectHost`, and pure helpers, with no schema library, so a bundled panel stays a few kilobytes. `@aiworker/sdk/schemas` is the host-facing entry: the zod parse of an untrusted guest's manifest (`parseManifest`, `parseManifestJson`) and messages (`guestMessageSchema`, `hostMessageSchema`). Guest-only drawing lives under `@aiworker/sdk/ui`. Host and guest import from here. Do not copy these types into `packages/ui`.
+
+## Entrypoints
+
+- `src/index.ts`: public exports. Host and guest protocol.
+- `src/parse.ts`: `package.json` / bare-block parse. Fails closed.
+- `src/host-version.ts`: `engines.aiworker` parse and compare. Install uses this against `AIWORKER_VERSION`.
+- `src/protocol.ts`: envelope parse for host and guest messages.
+- `src/host.ts`: iframe client. Posts to `parent`. Ignores messages whose `source` is not `parent`. In-flight RPCs time out at `GUEST_REQUEST_TIMEOUT_MS` (20s) as `HOST_TIMEOUT`. `onDirectory` / `onSession` / `onSessionLifecycle` / `onItem` replay and stay current after later pushes, same as connection and settings. `onResolve` holds one handler for host `resolve` requests and answers each with `resolve-result` (the clamped chip, `null`, or the thrown error's message; no handler answers with an error). `setBadge` posts `badge` with the count clamped to 0..`GUEST_BADGE_MAX`.
+- `scripts/bundle-guest.ts`: official IIFE build, exposed as the `openchamber-guest-bundle` bin. Run `bunx openchamber-guest-bundle panel/main.ts panel/main.js` from the guest folder; paths resolve against the current directory. Needs Bun. Any bundler with an IIFE target is an equivalent substitute.
+- `dist/`: the published output (`bun run --cwd packages/sdk build`, `tsc -p tsconfig.build.json`). `package.json` `exports` point here so Node loads the SDK from `node_modules` (packaged Electron, `aiworker serve`). Inside the monorepo, Vite aliases and tsconfig `paths` resolve `@aiworker/sdk` to `src/` so builds and type-checks never depend on a stale `dist`. The server under Bun and Node uses `dist`; the root `postinstall` builds it. The package ships to npm from the release workflow with `bun publish`, right before `@aiworker/web`; `scripts/bump-version.mjs` bumps it with the app, so the SDK version always equals the AiWorker version it was released with.
+- `GUEST_SERVICES.md`: local service contract (`contributes.service`, `serviceRequest`, grant, loopback).
+- `src/ui/`: guest drawing kit. Building blocks only (`mountButton`, `mountTextField`, `mountSearchField`, `mountSelect`, `mountCheckbox`, `mountSwitch`, `mountTabs`, `mountBadge`, `mountList`, `mountEmpty`, `mountSpinner`, `mountBanner`, `mountSeparator`, `mountProgress`, `mountMenu`, `mountText`); the guest composes screens. See `src/ui/DOCUMENTATION.md`. Import `@aiworker/sdk/ui`. Do not import this from `packages/ui`. Kit changes follow package semver, not `apiVersion`.
+
+## Invariants
+
+- `scripts/bump-version.mjs` refreshes `bun.lock` after bumping package versions; include both in the release commit. Bun resolves `workspace:*` in published archives from lockfile versions, and a frozen install can succeed with stale versions. `scripts/bump-version.test.mjs` covers the bump, frozen install, and packed dependency versions together.
+
+- Extension activity uses `useConfigStore.isConnected` plus live status records and directory `sessionStatusReady` authority. `useUIStore.eventStreamStatus` is an unmaintained diagnostic field, not a connection gate; its default `idle` must not hide known running or idle sessions as `unknown`.
+
+- `contributes.page` is `true` or `{ entry, title? }`, requires `panel.entry`, and adds a user-opened full-screen page. `resolvePageEntry` resolves shorthand; the server validates its HTML/scripts and exposes `pageEntry`/`pageTitle`. `PluginPane surface="page"` uses the same sandbox. `useUIStore.openGuestPageId` is transient and mutually exclusive with other main pages. The sidebar menu opens it; `close()` or explicit session navigation closes it. Pages are not context-rail surfaces.
+- `workspace.ts` owns project/worktree/session snapshots and storage types; `workspace-schemas.ts` validates their wire contracts. The existing `sessions` grant covers lists, subscriptions, opening sessions, and targeted creation. `lib/guests/workspace.ts` projects shared project, topology, session, and live-status stores; reads perform no network or git discovery. A registered observer is shared per runtime/extension/query and stops with its last listener. `PluginPane` limits each frame to 32 subscriptions and clears them on unmount, grant withdrawal, and runtime switch. Initial snapshots and updates have explicit loading/error coverage. `HostClient.onProjects/onWorktrees/onSessions` return promises of unsubscribe functions, so approval failures reach the caller.
+- `storage` is instance-owned JSON under the guest's namespace, without a new capability. `storage.js` serializes authorization, read-modify-write, and removal per namespace; writes use unique temporary files and rename. Missing keys differ from stored null; corrupt files and failed writes fail without clearing data. Limits and public result shapes live in `API.md`. For project data, extensions namespace keys with project IDs.
+
+- Manifest `apiVersion` is `1`. Wire envelope `v` stays `1`. Any other value is `unsupported-api-version`. Optional `engines.aiworker` is `1.22.0` or `>=1.22.0`. Install refuses with `host-too-old` when this AiWorker build is older. Package installs also need a semver `version` on `package.json` (`1.0.0`); the catalog exposes it and Settings → Extensions shows `v1.0.0` on the card. Already-installed packages without `version` still list; new installs without it fail as `invalid-manifest`.
+- `panel.entry` is optional; `panel.id/name/icon` remain the identity on Settings and approval cards. `hasGuestPage` means a visible panel, not an execution runtime. `background.entry` provides independent package-local `.html` for on-demand code without a rail icon. Without a panel, actions must explicitly use `mode: "background"`; `page` and enabled `attach` fail as `invalid-panel`. A background-only extension can declare commands, services, integrations and capabilities, with the existing grants. Without either entry, only tools are allowed, HTML/JS serving is refused, and `examples/tools-only` remains the reference. Settings shows "No panel" whenever the visible entry is absent.
+- Panel `id` is kebab-case. `icon` is a Remixicon kebab-case name (`RiWindowLine` → `window`, `RiGitMergeLine` → `git-merge`) or a package `.svg` path (`icon.svg`). URLs and absolute paths fail parse. `entry` stays inside the package (no `..`, no absolute, no URL). The rail paints a Remixicon from the host sprite, or a `currentColor` mask for a package SVG. Package SVGs often fill the 24×24 viewBox; the rail scales that mask so it matches Remixicon optical size. A Remixicon name the sprite does not carry falls back to `apps`.
+- Extra manifest keys are dropped, not forwarded.
+- Theme text fields are required on `apiVersion: 1`: `primaryText`, `successText`, `warningText`, `errorText`, `infoText`. Host calculation and UI-kit application are documented in `src/ui/DOCUMENTATION.md`. Keep the wire schema, TypeScript contract and iframe mapping in sync.
+- `connectHost` rejects when `parent === self`. A silent host rejects in-flight RPCs as `HOST_TIMEOUT` after 20s. Dispose rejects the rest as `HOST_UNAVAILABLE`.
+- Failed `result` may carry `code`. Known guest codes are `HOST_UNAVAILABLE`, `HOST_TIMEOUT`, `HOST_REJECTED`, `DISCONNECTED`, `DISABLED`, `BAD_PATH`, `NO_INTEGRATION`, `NO_SESSION`, `SESSION_BUSY`, `NO_SERVICE`, `SERVICE_FAILED`, `NOT_GRANTED`, `NO_DIRECTORY`, `NOT_FOUND`, `FILE_TOO_LARGE`, `DENIED`, `NO_MODEL`, `MODEL_FAILED`. Anything else becomes `HOST_REJECTED`. The `error` string stays.
+- `parseManifest` takes a typed document. File or network bytes go through `parseManifestJson`. Both return a result and do not throw on junk.
+- The host parses iframe `event.data` with `guestMessageSchema` (`@aiworker/sdk/schemas`). The guest reads host pushes with `readHostMessage` in `contract.ts`: envelope and discriminant only, because the sender is the verified parent frame. `protocol.ts` asserts the hand-written `HostMessage` / `GuestMessage` types against the zod schemas at compile time, so the two cannot drift.
+- `ready.item` is `GuestItem | null`: the composer chip (`AttachIssueRequest`, unchanged, `kind` still `issue` / `pull`), or a `GuestMessageItem` / `GuestSessionItem` from a declared action, discriminated by `kind: 'message' | 'session'` and carrying the manifest `action` id. A message item's `text` is what `formatMessageRecordText` renders for the export, capped at `GUEST_ITEM_MESSAGE_TEXT_MAX` (200 000). A session item carries `messages` only when the action declared `payload: ["messages"]` and `conversation` is granted; `buildGuestSessionItem` in `packages/ui/src/lib/guests/actions.ts` drops the oldest messages until the serialized item is under `GUEST_ITEM_SESSION_MAX` (2 000 000) and sets `truncated`. The host schema refuses a larger item. `isGuestAttachItem` / `isGuestMessageItem` / `isGuestSessionItem` narrow it.
+- `contributes.actions` is 1 to 8 entries (`GUEST_ACTIONS_MAX`), each a unique kebab-case `id`, `label` of 1 to `GUEST_ACTION_LABEL_MAX` (40) characters, optional `icon` with the `panel.icon` rules (falls back to the panel icon), and `where`. `roles` is only legal on `where: "message"` (default both roles); `payload` is only legal on `where: "session"` and only knows `"messages"`. Anything else is `invalid-actions`. Declaring a `messages` payload adds the `conversation` capability (`guestActionsNeedConversation`); actions without it need no capability. The public catalog row carries `actions` as declared.
+- `contributes.commands` is 1 to 8 entries (`GUEST_COMMANDS_MAX`) with a unique `name` matching `GUEST_COMMAND_NAME` (`/^[a-z][a-z0-9-]{0,23}$/`) and an optional `description` of 1 to `GUEST_COMMAND_DESCRIPTION_MAX` (80) characters; else `invalid-commands`. The host owns collisions: a name the composer already has (built-in, OpenCode command, skill, or an earlier guest) is dropped with a console warning. The public catalog row carries `commands` as declared.
+- `contributes.tools` is 1 to 16 entries (`GUEST_TOOLS_MAX`) that say how the extension's tool calls look in the chat, without code. `match` is the full tool name as OpenCode reports it, un-normalized (`mcp.jira.search`, `jira_search`), 1 to `GUEST_TOOL_MATCH_MAX` (128) characters of `[A-Za-z0-9_.:-]`, with one `*` allowed at the end as a suffix wildcard (`mcp.jira.*`; `*` alone is refused). Optional `name` (1 to `GUEST_TOOL_NAME_MAX`, 40) is the header title when `title` is absent or renders empty; `icon` is a Remixicon name or a package `.svg` path with the `panel.icon` rules (the chat draws the SVG as a `currentColor` mask at the glyph size through `resolveGuestToolIcon`, fetched as an authenticated asset under `/api/guests/<id>/<path>`; a Remixicon the sprite lacks leaves the host's own tool icon); `title` and `subtitle` are templates of up to `GUEST_TOOL_TEMPLATE_MAX` (200) characters with `{input.path}`, `{output.path}`, and `{metadata.path}` placeholders (dotted paths, array indexes allowed; a missing path is an empty string; a value is stringified and cut at `GUEST_TOOL_TEMPLATE_VALUE_MAX`, 200). `output` is `auto` (the host's own detection, the default), `text`, `json` (the JSON summary/tree/raw views), `markdown` (the assistant markdown renderer), `code` with `language` (1 to 32), or `table` with `columns` (1 to 16 dotted paths; rows are the output array or `output.items`). `language` outside `code` and `columns` outside `table` (or a `table` without `columns`) fail closed; anything else wrong is `invalid-tools`. The public catalog row carries `tools` as declared; the host applies them only for an active guest, an exact `match` beats a wildcard from any extension, and among equals the first extension in the catalog wins. The registry lives in `packages/ui/src/lib/guests/tool-presentation.ts` and is consulted by the existing chat tool renderers; VS Code and mobile keep the catalog empty, so nothing changes there.
+- Host → guest `resolve` is `{ id, payload: { command, args } }`; the guest answers `resolve-result` with the same `id` and `{ item }` (a clamped `AttachIssueRequest` or `null`) or `{ error }` (1 to `GUEST_RESOLVE_ERROR_MAX` characters). The host waits `GUEST_REQUEST_TIMEOUT_MS`, then treats silence as a failure and never sends a `result` for a `resolve-result`. `badge` is `{ count }` with `count` an integer 0..999 or `null`; the host schema drops anything else.
+- `ready` always carries `session` (`{ id, title, busy }` or `null`), `surface` (`panel` on the rail, `dialog` in the attach window), `connection` (`{ connected, account }`), and `settings` (declared keys only). Title falls back to `id` when the host record has no title. `busy` is live `session_status` `busy` or `retry`. Missing status is `busy: false`, not an empty success that clears a previous snapshot. `model` is `providerID/id` when the host session record has both. `agent` is the session agent name when present. `surface` is which host chrome mounted the iframe. It is not `openSurface`. `item` is the attached item the surface was opened for (the user clicked that item's chip on the composer; the same `AttachIssueRequest` shape the guest handed to `attach`, with `text` filled from the chip's context) or `null` from the rail icon and the + menu. The host also pushes `item` when it changes while the frame is up; `onItem` replays the latest value. `ready.theme.tokens` is the host colour bag: surfaces (`background`, `elevated`, `mutedSurface`, `subtle`), text (`foreground`, `elevatedForeground`, `muted`), interaction (`border`, `hover`, `active`, `selection`, `selectionForeground`, `focus`), `primary` / `primaryForeground`, the four status colours, `font`, `mono`, and `radius`. `applyHostReady` writes it onto the iframe. The host also pushes `connection` and `settings` the same way as `session`. Access tokens never appear in `ready` or a result.
+- `writeClipboard` text is 1–32000 characters. `compose` text is 1–16000 after trim. Compose default mode is `append`. Compose writes the chat composer. It does not send.
+- `contributes.capabilities` is a list of `prompt`, `sessions`, `files`, and/or `model` (`DECLARED_GUEST_CAPABILITIES`). `model` gates `generate`: `{ prompt, system?, maxOutputTokens? }` → `{ text }`, posted with a `GUEST_GENERATE_TIMEOUT_MS` (90s) timeout instead of the usual 20s because the model answers slowly; the host answers `NO_MODEL` when the small-model service resolves nothing (or only Claude Code) and `MODEL_FAILED` when the provider call fails. `requestedGuestCapabilities` adds `conversation`, `service`, `network`, and `filesystem` from a session action with `payload: ["messages"]`, `contributes.service`, `contributes.integration`, and `contributes.filesystem`; the user approves that whole list once at install (`PUT /api/guests/:id/capabilities`), and a package that later asks for more is re-approved. `hasGuestCapability` gates `prompt({ send })`, `startSession`, `request`, `serviceRequest`, and the four file calls; a refusal is `NOT_GRANTED` (`NO_SERVICE` for the service).
+- `contributes.filesystem` is 1 to 16 globs, each 1 to 256 characters, starting with `/` or `~/`, with no `..`, empty segment, NUL, or backslash (`isGuestFilesystemPattern`; parse failure is `invalid-filesystem`). `**` spans directories, `*` and `?` stay inside one segment, and a pattern ending in `/**` also matches the directory itself. The public catalog row carries the list as `filesystem` so the approval dialog can show it.
+- `readFile` / `writeFile` / `listDir` / `stat` are `file-read` / `file-write` / `file-list` / `file-stat` on the wire. `guestFileScope` decides the grant: a relative path is `project` (capability `files`, joined to the open project; none open is `NO_DIRECTORY`), `/…` or `~/…` is `filesystem` (must match a declared pattern). The server compares canonical paths, so a symlink out of either tree is `BAD_PATH`, as is any `..` segment. Results are `{ content }`, `{ written: true }`, `{ entries: { name, kind }[] }`, and `{ kind, size, mtime }` where `kind` may be `missing`. `GUEST_FILE_PATH_MAX` (1024), `GUEST_FILE_CONTENT_MAX` (2 000 000 characters, read and write), `GUEST_FILE_LIST_MAX` (2000 entries). The client refuses an empty, oversized, NUL, or backslash path as `BAD_PATH` and oversized content as `FILE_TOO_LARGE` before posting; the host schema accepts only what `isGuestFilePath` does, so a dropped message cannot turn into `HOST_TIMEOUT`. Nothing about the write is logged, not even the path.
+- `contributes.attach` is `true`, `false`, `"panel"`, `"dialog"`, or `{ "mode": "panel" | "dialog", "entry"?: string }`. `true` and `"panel"` add a + menu row that opens the rail. `"dialog"` opens a host window that mounts the same iframe. The object form's `entry` is an HTML page inside the package (same path rules as `panel.entry`, install checks it exists and that its scripts are built) that the dialog loads instead of `panel.entry`; it is only accepted with `mode: "dialog"`, and `resolveAttachEntry(contributes)` returns it or `null`. The public catalog row carries it as `attachEntry`. Clicking the guest's chip on the composer reopens that guest with the chip as `ready.item`: a dialog guest in the attach window, a panel guest on the rail. New Worktree shows the same dialog-mode guests next to GitHub and Linear. Omitted or `false` stays off those menus. Public 1.0 is web and desktop. VS Code and mobile mark the guest catalog `unsupported`. They do not show the row.
+- `contributes.integration` needs either a panel or background entry. Exactly one of `oauth`, `token`, or `host` is required. The public catalog slice is name, description, `auth`, `apiOrigin` (the one origin `request` may call; the approval dialog shows it, it is not a secret), token scheme, and setting field defs. OAuth URLs stay on the server. Client id, secret, and pasted tokens are not in the package. `host.provider: "linear"` binds the first-party Linear connection. `apiOrigin` is `https://api.linear.app` only.
+- `attach` puts `{ providerId, id, title, url }` on the composer as a chip, exclusive with GitHub and Linear. `kind` is `issue` or `pull` and defaults to `issue`. `author` is a login. `branches` is `{ head, base }` on a pull. Avatar URLs stay off this payload. It does not invent a GitHub `number`. `text` is optional model context, 1–16000 after trim. `data` is optional plain JSON the guest chose (`JsonValue`); the host stores it on the chip, the queued context part, and the session snapshot, and hands it back byte-identical as `ready.item.data` / `onItem`. It never reaches the model or the chip text. Serialized size is capped at `GUEST_ATTACH_DATA_MAX` (16 000 characters): `clampAttachRequest` drops a larger value, the host schema refuses it. `connectHost.attach` clamps id/title/url/text/author/branches to the protocol max so the host schema does not drop the message. The rail and the attach window both write `pendingGuestIssue` on the composer store. Send writes `guest-issue` or `guest-pr` and a session snapshot. `close` dismisses the attach window and is a no-op on the rail.
+- `startSession` extends the existing operation with `projectId`, root/existing/new worktree selection, optional new name/base, and `navigation` defaulting to `preserve`. It calls the owning session creation action with that navigation policy, so registration/message initialization/global cache updates still happen while selection stays unchanged. Worktree creation reuses `createWorktreeWithDefaults` and the configured bootstrap wait. It preserves a created worktree on bootstrap/session failure and returns that partial result. It captures send selection before async creation, rechecks runtime and grants before subsequent mutations, and distinguishes session creation from first-message and linked-item persistence outcomes. See `API.md` for the exact result. Web and desktop only.
+- `prompt` is `{ text, send? }`. `send` omitted or `false` replace-composes on the current session. `send: true` sends on that session with the same model path as `startSession`. No session is `NO_SESSION`. A busy session on send is `SESSION_BUSY`. Compose still works while busy. The result is `{ sent }`. The guest does not pick a model or agent.
+- `sessionLink` is the same attach fields on the current session. It does not create a session. No project or no session is a refusal.
+- `onSessionLifecycle` is a host push. Live `session_status` `busy` and `retry` are `started`. `idle` is `completed`. An unknown status type is `failure`. That is not abort or crash. A late listener gets the last phase, from `ready.session.busy` when no dedicated push has arrived.
+- `oauthStart` opens the provider authorize URL, or the first-party Linear authorize URL for a host Linear guest. `oauthDisconnect` drops that guest's tokens, or the Linear connection for a host Linear guest. Token guests have no authorize URL. `request` is `{ method, path, query?, body? }`. `path` must start with `/`, stay on the declared `apiOrigin`, and never include a scheme. The host attaches `Authorization`. Token guests send the pasted token as is (`token.scheme` omitted or `raw`), as `Bearer <token>` (`token.scheme: "bearer"`), or as `Basic base64(username:token)` (`token.scheme: "basic"`; the Integrations card asks for a username, `token.usernameLabel` names that field, and the server stores the encoded pair as the access token so requests never need the username again). OAuth and host Linear send Bearer. The result is `{ status, body }`. A 409 `DISCONNECTED` or 400 `BAD_PATH` / `NO_INTEGRATION` lands on the guest as `HostRequestError.code`. Silence for 20s is `HOST_TIMEOUT`. The guest parses JSON. A host Linear guest may also `GET /api/linear/issues/get` through that same `request` call. The host answers from the first-party Linear route, which already asks Linear for public file URLs. Guest request itself does not know Linear.
+- `contributes.service` names a host-spawned entry on `apiVersion: 1`. `serviceRequest` / `serviceStatus` proxy to that process on loopback. See `GUEST_SERVICES.md`. Permissions are grant UI only in phase 1. No `host.docker`.
+
+## Host hole
+
+Built-in extension source and registration rules live in `packages/extensions/DOCUMENTATION.md`. The server assigns `source: 'bundled'` only from its app-owned registry and automatically grants the package's declared capabilities. Built-ins use the same SDK, sandbox and enabled-state checks as user extensions; the `openchamber-builtin-` namespace is reserved. Their account cards appear under Built-in integrations, and their persisted disabled state and data survive app updates.
+
+Relay panels use `lib/guests/relay-document.ts`: fetch package HTML and its statically referenced scripts, styles, CSS imports/URLs, images, fonts, and nested documents through `runtimeFetch`, then render self-contained `srcDoc` with the same `sandbox="allow-scripts"`. A normal iframe URL bypasses the client-side tunnel and can load the local host UI instead. Local resource paths stay under that guest's package; missing files, import cycles, or resource limits fail the load. The loader allows 500 referenced files, 40 MiB of fetched bytes and 64 MiB of embedded text. Runtime-created relative URLs are not intercepted: bundle those assets into the IIFE or use explicit external URLs/SDK operations. Existing authored CSP is preserved. Direct iframe URLs retain their existing path.
+
+`useGuestIconSource` loads package SVGs through authenticated `runtimeFetch` in direct and relay modes, then exposes revocable blob URLs to CSS masks. It uses the package path rather than the original URL token, so cold-start token readiness and token expiry cannot strand an icon. Cache identity follows runtime, package path and extension version; late responses are discarded and old blobs revoked. Unknown icons and SVGs that are loading or failed use the shared `FALLBACK_GUEST_ICON`, the `apps` glyph.
+
+Git installation accepts HTTPS, `ssh://` and scp-style SSH addresses. `POST /api/guests` accepts optional `gitIdentityId`; the server stores only that ID in the git origin, and resolves the profile again for clones and update fetches. Global/omitted identity uses the server process's Git/SSH configuration and agent. The Settings picker loads identities from the active runtime, discards stale loads, and never reuses a desktop's cached profiles on a remote server. SSH parsing, public-host validation and pinned connection options belong to `packages/web/server/lib/guests/clone.js`.
+
+Catalog loading and installation retain typed request diagnostics in `lib/guests/request-failure.ts`: fixed API route, method, HTTP status, or a transport/invalid-response classification. Settings shows catalog diagnostics and passes install diagnostics to the toast description so Copy includes them. Response bodies, headers, credentials, and arbitrary transport error messages are excluded. Catalog failures preserve a previously loaded list; diagnostics clear on success or runtime switch, and late failures from a retired runtime are ignored.
+
+`lib/guests/useGuestFrameUrl.ts` owns iframe URL lifetime. It retains the scoped token's expiry, renews on an expired navigation, and remints after enable/version/runtime changes. Expiry alone never reloads a healthy document. Recovery is bounded until the guest's next `hello`; mint failure leaves the existing load-failed UI rather than mounting an unauthenticated URL. Late mint responses from a retired owner are discarded. Guest capability grants and provider OAuth are separate from this host file-loading authorization.
+
+`GET /api/guests` plus `PluginPane` on the desktop/web rail. The iframe URL carries a token minted for `guest:<id>` scope (`resolveGuestFrameUrl`), valid only for `GET /api/guests/<id>/*`; the session-wide URL token never enters a guest frame. Settings → Extensions installs a folder, a local `.zip`, or an https git / zip URL into that AiWorker instance's data dir (`extensions.json`). Settings → Integrations shows a host card for each installed guest that declared `integration`. OAuth and pasted tokens live in `guest-auth.json`. Host Linear uses `linear-auth.json`. VS Code and mobile set the catalog to `unsupported`. That is not an empty success. A guest must ship a classic IIFE (`panel/main.js`). No runtime compiles guest TypeScript. The iframe cannot load ESM.
+
+**Folder install** stores the realpath in `extensions.json` with `source: "path"`. Uninstall drops the catalog row and extension-owned storage. The user's folder stays.
+
+**Zip / git install** copies into `{dataDir}/extensions/{id}` with `source: "zip"` or `"git"`. Only git installs update: Settings → Extensions compares the installed `package.json` `version` with the origin's and offers Update when the origin is newer, so bump `version` to ship one; a `#tag` or `#branch` on the install URL pins that channel. The archive is not kept open. The host reads it (local file or https download, 20MB cap), extracts with a small allowlist unzip (store/deflate only; no zip64, encryption, or `..` paths; 500 files / 40MB uncompressed), unwraps a single root folder when `package.json` sits inside it, inspects the manifest, then renames staging to `{dataDir}/extensions/{id}`. Runtime serves and spawns from that copy. Uninstall deletes the copy. The original `.zip` on disk is untouched.
+
+The iframe is `sandbox="allow-scripts"` with no `allow-same-origin`, so its origin is opaque. Host posts to that frame's `contentWindow` with target `*`. The string `null` is not a legal `postMessage` targetOrigin. Receive still accepts only `event.source === contentWindow`. Guest `connectHost` posts `hello` to `parent` with `*`. The host answers `hello` and also pushes `ready` on iframe `load`, because a cached panel can fire `hello` while React is swapping the listener.
+
+File calls go through `POST /api/guests/:id/files` with the `x-opencode-directory` header of the open project (`lib/guests/files.ts`). `PluginPane` answers `NOT_GRANTED` and `NO_DIRECTORY` itself, mirroring the server, so a refused call costs no round trip; the server is still the authority.
+
+Clipboard writes run in the host (`copyTextToClipboard`). Compose uses `useInputStore.setPendingInputText`. Attach writes the composer chip. The iframe has no clipboard, no composer, and no chip. The + menu and the attach window chrome are host. Guest JS is not in that React tree.
+
+Actions, commands, and the badge are host chrome too. `useGuestActions` (`packages/ui/src/hooks/useGuestSurfaces.ts`) lists active guests' actions for message and session menus, empty on VS Code and mobile. A click builds the item with `buildGuestMessageItem` / `buildGuestSessionItem`; failed conversation loading is a toast, never an empty conversation. `runGuestAction` dispatches the declared mode. In default `open` mode, `openGuestWithItem` routes like a chip click: the attach window for `attach: "dialog"` through `useGuestDialogStore`, otherwise the rail through `useGuestItemStore`. Background mode is documented below.
+
+`useGuestCommands` lists commands minus reserved names. The composer routes `/name args` through `submit/guestCommands.ts` to `runGuestCommand`, which asks a mounted pane's registered resolver or mounts a hidden `PluginPane` through `GuestHosts`. The pane registers after hello/load, posts `resolve`, and settles on `resolve-result` or the 20s deadline. A returned chip uses `useInputStore.setPendingGuestIssue`. `badge` writes the memory-only `useGuestBadgeStore`; the rail paints the count and opening the panel clears it. A paused or unapproved guest contributes no actions, commands, tool presentations, or badge.
+
+Add a type when the host grows that hole, not before. Any new `connectHost` method ships with a `PluginPane` / `answerGuestMessage` branch in the same change.
+
+Rebuild every example bundle after an SDK change (`bunx openchamber-guest-bundle` per entry, see `examples/README.md`); the built files are checked in.
+
+## Guest toasts
+
+`ToastRequest` adds optional `copy: boolean | { text: string }`, `dismiss: boolean`, and `persistent: boolean`. The client checks message/copy length before sending; the host schema validates the complete payload. `HostBridgeEffects.toast` receives the request intact. `lib/guests/toast.tsx` owns toast creation and per-toast dismissal; `components/layout/GuestToastActions.tsx` renders the buttons and clipboard success/failure state. Copy keeps the toast open. Persistent toasts always include OK, including when the guest passes `dismiss: false`.
+
+Toast acknowledgement means displayed, not clicked. Button closures retain only text and toast identity, not the guest's lifetime or runtime. They survive action completion, iframe teardown, and runtime switches. Labels resolve through the host's reactive i18n context. The SDK and schema limits use the existing `GUEST_TOAST_MAX` and `GUEST_CLIPBOARD_TEXT_MAX`; custom copy text is not trimmed. See `API.md` for the author contract.
+
+## Background actions
+
+`contributes.actions[].mode` is `open` or `background`, defaulting to `open`. The manifest parser and UI catalog parser preserve it; server catalog projection already carries actions unchanged. Existing `onItem` routing stays with open-mode actions. `runGuestAction` revalidates the captured declaration, active grants, target role, and runtime before dispatch. Session actions also discard history loaded across a runtime switch.
+
+`lib/guests/run-action.ts` owns temporary invocation state, a 20-second loading/execution deadline, and an eight-frame limit. Each click gets a distinct `PluginPane` from `GuestHosts`, preferring `backgroundEntry` and falling back to `entry`, with `surface: 'background'` and `headless`. It never registers as a slash-command resolver, consumes a parked item, clears a badge, opens a tab, or changes session selection. The pane pins session/directory context to the clicked target. Composer-writing methods retain their existing current-composer behavior.
+
+The catalog carries `backgroundEntry` independently of the visible `entry`. Both HTML files and their built scripts are checked at install. The serving route's `hasRuntime` gate permits code when either exists; storage applies that same entry check plus enabled/approval gates. Background-only chips cannot reopen a rail panel, so the composer shows a no-panel notice while retaining the existing browser action.
+
+Slash commands use the background entry whenever it is declared. A visible pane then does not register a resolver; only the temporary command host does, with `ready.surface: 'background'`. Panel-only extensions retain resolver reuse. Resolver registrations are retired when the frame URL or entry changes and refuse calls after runtime/grant/version changes. `examples/hello-kit/background` is the reference for a separate entry; omit that example's visible entry and page to make it background-only.
+
+Both `MainLayout` and the separate-window `MiniChatLayout` mount `GuestHosts`; a message action must have an execution host in the window that owns its catalog and session state.
+
+The SDK adds `HostActionMessage`, `GuestActionResultMessage`, `GuestActionItem`, `ActionResultPayload`, and `HostClient.onAction`. Wire `action` carries one message/session item and an invocation ID; `action-result` carries that ID and a discriminated success/error payload. Error text shares `GUEST_RESOLVE_ERROR_MAX`. `ready.item` stays null; a one-shot `takeMessage` prevents hello/load/context updates from executing an action twice. The handler must be registered synchronously and await its work before returning. Host schema validation plus the frame's source and invocation ID reject unrelated replies.
+
+The runner cancels on runtime/catalog invalidation and marks the operation inactive synchronously, so queued messages cannot mutate host state during React teardown. Timeout, completion, frame-load failure, or host unmount clears the invocation and subscriptions. Unmount cleanup yields one microtask for Strict Mode's effect reattachment. Already accepted remote effects are not rolled back; no automatic retry. Web/desktop use the existing direct or relay frame loader; VS Code and mobile remain unsupported. `examples/hello-kit` demonstrates a background message-length toast.
+
+## Not here yet
+
+`issues.search` / `issues.get` on the host, a public OAuth broker, a second `host.provider`, file watching or globbing from the guest (it gets `listDir` and `stat`, not a search). `attach` is the chip. `startSession` creates a session and writes that snapshot. `sessionLink` writes that snapshot on the current session. `prompt` writes or sends on that session. `onSessionLifecycle` is the live phase. Search and the task list live in the guest. `@aiworker/sdk/ui` is the drawing kit: buttons, fields, select, list, tabs, badges, banners, menu, and `mountText`. No issue page, card, attach picker, or PR window; the guest composes those from the blocks. `mountText` lifts `![alt](https://…)` and `[label](https://…)` and hands link clicks to `onOpenUrl`. `ready.theme.tokens` carries the host surface and interactive colors. Call `applyHostReady` before mount.
+
+Local services ship on `apiVersion: 1` (`contributes.service`, `serviceRequest`, grant UI, platform socket bindings + override). Contract detail: `GUEST_SERVICES.md`. Declared `sockets` / `exec` are shown on the grant card and do not confine the process; there is no sandbox for services. VS Code and mobile do not load guests or services yet.

package/GUEST_SERVICES.md

@@ -0,0 +1,166 @@
+# Guest local services
+
+Implemented on manifest `apiVersion: 1`. Wire envelope `AIWORKER_SDK_API_VERSION` stays `1`.
+
+This is the contract for guests that need a local process (Docker CLI, Engine sockets, kubectl, DB sockets). The iframe stays sandboxed. The host owns spawn and the loopback proxy.
+
+## Why services exist
+
+HTML guests in a sandboxed iframe reach the network only through `connectHost.request` onto a declared HTTPS `apiOrigin`. That fits cloud trackers. It cannot open `/var/run/docker.sock`, run `docker`, or hold a long-lived local daemon.
+
+Services keep the iframe. They add a host-owned child process from the same package. The panel never sees the socket. The service does.
+
+Do not put `docker` (or any product name) on `connectHost`. The SDK knows panel, service, and a loopback proxy. The package owns the integration.
+
+Declare the AiWorker floor with `engines.aiworker` (`1.22.0` or `>=1.22.0`). Install refuses when this host is older. Put a semver `version` on `package.json` (`1.0.0`); install requires it and Settings → Extensions shows `v1.0.0` on the card.
+
+## Model
+
+```
+panel (iframe) --serviceRequest--> host --HTTP 127.0.0.1:port--> service process --> socket / CLI
+                     ^
+                     spawn / kill / grant
+```
+
+1. Package still ships `panel/index.html` and a classic IIFE `panel/main.js`.
+2. Optional `contributes.service` names a built entry the host can spawn.
+3. After the user allows the service in Settings → Extensions, the first `serviceRequest` starts that entry with the app runtime (`process.execPath` + `ELECTRON_RUN_AS_NODE` on desktop). A system `node` on PATH is not required.
+4. The host binds `127.0.0.1` on an ephemeral port and passes `AIWORKER_SERVICE_PORT` and `AIWORKER_SERVICE_TOKEN` in the service env. The service does not inherit the host environment: only PATH, HOME, temp, locale, and the Windows system variables are copied. API keys, the UI password, and other host secrets never reach it.
+5. The panel calls `serviceRequest({ method, path, query?, body? })`. The host proxies only to that guest's loopback listener. Same stay-on-origin rule as `request`, but the origin is the service the host started.
+6. The service talks to Docker, kubectl, or anything else. That logic stays in the package.
+
+## Permissions: `exec` vs `sockets`
+
+| Declare | Means | Service does |
+|---|---|---|
+| `exec` | Named binaries on PATH | `child_process` / CLI |
+| `sockets` | Unix socket or named pipe | Dial Engine API (or similar) itself |
+
+Use `exec` when the integration shells out (like a modern Docker CLI panel). Use `sockets` when the service opens the daemon endpoint. Do not list a socket path in Needs for a CLI-only service.
+
+## Manifest
+
+```json
+{
+  "apiVersion": 1,
+  "engines": {
+    "aiworker": ">=1.22.0"
+  },
+  "contributes": {
+    "panel": {
+      "id": "docker-sock",
+      "name": "Docker (socket)",
+      "icon": "icon.svg",
+      "entry": "panel/index.html"
+    },
+    "service": {
+      "entry": "service/main.js",
+      "runtime": "host",
+      "permissions": {
+        "sockets": [{
+          "id": "docker",
+          "candidates": {
+            "linux": ["/var/run/docker.sock", "/run/user/1000/docker.sock"],
+            "darwin": ["~/.docker/run/docker.sock", "~/.colima/default/docker.sock"],
+            "win32": ["//./pipe/docker_engine"]
+          }
+        }]
+      }
+    },
+    "attach": false
+  }
+}
+```
+
+A CLI service looks the same except `permissions.exec: ["docker"]` and no `sockets`.
+
+Socket entry shapes:
+
+- `string` — legacy one path for every platform; public id is that string
+- `{ id, path }` — same path on linux / darwin / win32
+- `{ id, candidates: { linux?, darwin?, win32? } }` — per-OS lists; `~` expands
+
+Parse rules:
+
+- `apiVersion` is `1`. Wire `v` on postMessage stays `1`.
+- `engines.aiworker` is optional. Values are `1.22.0` or `>=1.22.0` only. Install returns `host-too-old` when this AiWorker build is older.
+- `contributes.panel` stays required. Same id / name / icon / entry rules as any guest.
+- `contributes.service` is optional. A guest without `service` is HTML-only.
+- `service.entry` is a relative path inside the package. Ship compiled JS; the host never compiles TypeScript.
+- `service.runtime` phase 1 accepts only `"host"`.
+- `service.permissions.sockets` and `service.permissions.exec` are shown to the user in the approval dialog. They describe intent and do not confine the process: a service runs with the user's full access. Declaring `contributes.service` adds the `service` capability to the package's request list; the user approves the whole list once when the package is installed (Settings → Extensions), and the first `serviceRequest` is refused with `NO_SERVICE` until then.
+- The catalog adds `service.socketBindings`: `{ id, candidates, resolved, override }` for this host. The user can override a path in Extensions. Override empty clears it and the next spawn re-resolves.
+- `contributes.integration` remains valid next to `service`. Cloud `request` and `serviceRequest` may both exist on one guest.
+
+Extra keys still drop, not forward.
+
+## Host hole
+
+| Method | Role |
+|---|---|
+| `serviceRequest` | `{ method, path, query?, body? }` → `{ status, body }`. Proxy to this guest's service loopback only. `path` starts with `/`, no scheme. |
+| `serviceStatus` | `stopped` \| `starting` \| `ready` \| `failed`. |
+
+Do not add: raw unix socket from the panel, arbitrary `spawn`, arbitrary filesystem, `host.docker`.
+
+Error codes:
+
+- `NO_SERVICE` — no service declared, not granted, not started, or already torn down
+- `DISABLED` — extension paused in Settings → Extensions (service stopped; tokens/grants stay)
+- `SERVICE_FAILED` — process crashed or never became ready
+- Existing: `HOST_TIMEOUT`, `HOST_REJECTED`, `HOST_UNAVAILABLE`, `BAD_PATH`
+
+Server routes (authenticated UI session):
+
+- `POST /api/guests/:id/service/request`
+- `GET /api/guests/:id/service/status`
+- `PUT /api/guests/:id/capabilities` — `{ granted }`, the full requested list or `[]` to withdraw
+- `PUT /api/guests/:id/service/sockets` — `{ id, path }` (`path` empty or null clears the override). Stops a running service so the next request respawns with the new env.
+
+The panel never receives `AIWORKER_SERVICE_TOKEN` and never dials the port itself. Opaque iframe origin stays. Only the host proxy talks to loopback.
+
+VS Code and mobile stay `unsupported` for the guest catalog. They do not spawn services.
+
+## Service process contract
+
+Env the host sets:
+
+- `AIWORKER_SERVICE_PORT` — port to bind on `127.0.0.1`
+- `AIWORKER_SERVICE_TOKEN` — shared secret
+- `AIWORKER_SERVICE_SOCKETS` — JSON map `{ [socketId]: absolutePath }` for every binding that resolved (override or first existing candidate)
+
+Inbound auth: every request, including ready, must send:
+
+```
+Authorization: Bearer <AIWORKER_SERVICE_TOKEN>
+```
+
+Ready signal: host polls `GET /health` until HTTP 200 (15s timeout), then marks `ready`.
+
+Listen only on `127.0.0.1`. Do not bind `0.0.0.0`.
+
+Ship `service/main.js` already built. Same packaging rule as `panel/main.js`.
+
+## Lifecycle
+
+| Event | Host behavior |
+|---|---|
+| Install | Catalog row includes public `service` (`runtime`, `permissions`, `socketBindings`, `granted: false`) and `capabilities.requested` containing `service`. No spawn yet. |
+| Approve | `PUT .../capabilities` writes `capabilityGrants[id]` in `extensions.json`; the list must equal what the package requests. |
+| Socket override | `PUT .../service/sockets` writes `serviceSocketOverrides`. Running service for that guest stops. |
+| First `serviceRequest` | Grant missing → `NO_SERVICE`. Else spawn with resolved sockets, wait for `/health`, proxy. |
+| Panel open | Status via `serviceStatus`. Dead service restarts on the next `serviceRequest`. |
+| Uninstall | SIGTERM, then kill after timeout. Clear grant and socket overrides. Path-install does not delete the user's folder. |
+| Host quit | Kill every guest service. |
+| Crash | Status `failed`. Panel sees `SERVICE_FAILED` / status. Manual retry, not silent loops. |
+
+## Security invariants
+
+- Panel → host → service loopback only. No panel → socket.
+- `serviceRequest` path must stay on that service (host-allocated port for that guest id).
+- Every service requires an explicit grant before proxy.
+- Permissions text is advisory. Phase 1 does not enforce an OS sandbox around those lists: an allowed service can run any command, use git, and read or write any file the user can. The approval dialog says so in plain words.
+
+## Example
+
+`examples/service-echo` is a checked-in service extension: a Node HTTP server on loopback that the panel calls through `serviceRequest` and whose status it shows. Bundle the service with `--node`, install the folder from Settings → Extensions, allow the local service in the approval dialog, then open the rail panel. Streaming from a service to the panel (shell into a container, log tails) is deferred; it needs a streaming call on the SDK first.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bohdan Triapitsyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# @aiworker/sdk
+
+Build extensions for [AiWorker](https://openchamber.dev). An extension can show a panel on the right-hand rail or run actions in the background without a panel. It can read the current project and session, show toasts, put text in the chat box, attach a task to a session, and, once the user approves it, start sessions and send prompts. This package is the contract between the extension and the app.
+
+Full guide: [Build an extension](https://openchamber.dev/docs/sdk/). Reference: [Host API](https://openchamber.dev/docs/sdk/host/) and [UI kit](https://openchamber.dev/docs/sdk/ui/). Extensions with a local process: [GUEST_SERVICES.md](./GUEST_SERVICES.md).
+
+Extensions load in AiWorker web and desktop. VS Code and mobile do not load them yet.
+
+## Install
+
+```bash
+npm install @aiworker/sdk
+```
+
+The package ships compiled JavaScript with type declarations, so any bundler works. Its version matches the AiWorker release it shipped with, so `@aiworker/sdk@1.24.0` is the contract of AiWorker 1.24.0.
+
+## Preview builds
+
+Preview packages are for testing unreleased SDK changes against a matching development build of AiWorker. They do not imply compatibility with the published app of the same base version.
+
+```bash
+npm install @aiworker/sdk@preview
+```
+
+Maintainers can run **Publish SDK preview** in GitHub Actions, select the source branch, and enter a positive preview number. For example, `1` publishes `1.23.2-preview.1` under the `preview` npm tag. Each publication needs an unused number. The workflow uses the existing `NPM_TOKEN` secret and publishes only the SDK. It changes the version in its temporary checkout, without creating commits or release tags or changing `latest`.
+
+The workflow must exist on the default branch before GitHub exposes its manual trigger. Once it does, select `bohdan/dev` to publish that branch's SDK. Enable `dry_run` to validate without publishing. Validation installs the packed SDK in an isolated project and checks its imports, TypeScript declarations, and extension bundler before publishing that same archive.
+
+## What you ship
+
+A folder with three files:
+
+- `package.json` with an `aiworker` block (the manifest)
+- `panel/index.html`, the page AiWorker shows
+- `panel/main.js`, your script built into one classic file (an IIFE; the page runs in a sandboxed iframe and cannot load ES modules)
+
+AiWorker never compiles your code. Build `panel/main.js` yourself. The package includes a bundler command that runs on Bun; esbuild with `--format=iife --platform=browser` does the same job.
+
+```bash
+bunx openchamber-guest-bundle panel/main.ts panel/main.js
+```
+
+Then install the folder from Settings → Extensions → Add. Folder installs run from your folder, so edit, rebuild, and reload. A `.zip` or an https git or zip link is copied into AiWorker's data folder instead; ship the built files only. Git installs can update from Settings → Extensions when the repository's `version` is newer than the installed one, so bump `version` to ship an update; `https://…/panel.git#v1` pins a tag or branch.
+
+A complete three-file example is on the [Build an extension](https://openchamber.dev/docs/sdk/) page. Six examples are at [roweb.cn/roweb/aihander/tree/main/packages/sdk/examples](https://roweb.cn/roweb/aihander/tree/main/packages/sdk/examples).
+
+## Manifest
+
+Git installs also accept SSH addresses such as `git@github.com:owner/extension.git` and `ssh://git@github.com/owner/extension.git`. The fingerprint menu in Settings → Extensions selects Global Identity or a Git identity on the active server. That identity is reused for update checks and updates. On a remote instance, SSH keys and any unlocked SSH agent must be available to the server process, not just your desktop. See [Extensions](https://docs.aiworker.dev/extensions/) for details.
+
+```json
+{
+  "name": "@acme/hello",
+  "version": "1.0.0",
+  "aiworker": {
+    "apiVersion": 1,
+    "engines": { "aiworker": ">=1.24.0" },
+    "contributes": {
+      "panel": {
+        "id": "acme-hello",
+        "name": "Hello",
+        "icon": "window",
+        "entry": "panel/index.html"
+      },
+      "attach": "dialog",
+      "capabilities": ["prompt", "sessions"],
+      "actions": [
+        { "id": "create-task", "label": "Create task from message", "where": "message", "roles": ["assistant"] },
+        { "id": "summarize", "label": "Summarize session", "where": "session", "payload": ["messages"] }
+      ],
+      "commands": [{ "name": "task", "description": "Attach a task by id" }],
+      "tools": [{ "match": "mcp.tasks.*", "name": "Tasks", "icon": "checkbox-circle", "title": "{input.id}", "output": "table", "columns": ["id", "title", "status"] }],
+      "integration": {
+        "name": "Acme",
+        "description": "Tasks from Acme",
+        "token": {
+          "apiOrigin": "https://api.acme.example",
+          "account": { "path": "/me", "name": "login" },
+          "scheme": "bearer"
+        },
+        "settings": [{ "id": "list-id", "label": "List ID" }]
+      }
+    }
+  }
+}
+```
+
+- `version` is required semver. Settings → Extensions shows it on the card.
+- `apiVersion` is `1`. Anything else is refused.
+- `engines.aiworker` is optional (`1.24.0` or `>=1.24.0`). Older AiWorker builds refuse the install.
+- `panel.id` is kebab-case and unique. `icon` is a Remixicon name (`RiWindowLine` becomes `window`) or an SVG inside the folder. `entry` is the visible panel's HTML file. Leave `entry` out to have no rail icon or panel. Add `background.entry` for executable actions and commands; with neither entry, the extension can only declare `tools`, as in `examples/tools-only`.
+- `background: { "entry": "background/index.html" }` supplies separate sandboxed HTML for background actions and slash commands. Its scripts must be built. It runs on demand, not continuously or at installation. A panel can coexist with it.
+- `attach` is optional. `"dialog"` opens the page in a window from the + menu next to the chat box; `true` or `"panel"` opens the rail panel instead. `ctx.surface` tells the page which one it is in. The object form `{ "mode": "dialog", "entry": "panel/attach.html" }` gives the window its own page. When the user clicks the attached chip, the page opens again with that item in `ctx.item` (`null` from the + menu), so it can show the item instead of the list.
+- `actions` is optional: menu entries on messages (`where: "message"`, optionally only `roles: ["assistant"]`) and on sessions (`where: "session"`). By default, picking one opens your page with that message or session in `ctx.item` (`kind: "message"` with the text, or `kind: "session"`; add `payload: ["messages"]` to get the conversation too). Set `mode: "background"` to call `onAction` without opening UI, as shown below. Up to 8.
+- `commands` is optional: slash commands for the chat box, up to 8. `/task DEMO-2` calls your `host.onResolve` handler instead of the model; return a chip to attach it, or `null` for nothing. A name the app already has is ignored.
+- `tools` is optional: how your tool calls look in the chat, up to 16, no code. `match` is the tool name OpenCode reports (`mcp.tasks.*` matches every tool under that prefix); `name` and `icon` (a Remixicon name or an SVG inside the folder, like `panel.icon`) set the header, `title` and `subtitle` are templates like `{input.id}` or `{output.total} open`, and `output` picks the body: `text`, `json`, `markdown`, `code` (with `language`), or `table` (with `columns`, rows from the output array or `output.items`). Leave `output` out to keep the app's own detection.
+- `capabilities` lists what needs the user's approval: `prompt` to send messages, `sessions` to create sessions and worktrees, `files` to read and write inside the open project, `model` for one-off text generation with the user's Small Model (`host.generate`, no session involved). An `integration` adds `network`, a `service` adds `service`, `filesystem` patterns (like `["~/.config/opencode/opencode.json"]`) add `filesystem`, which lets `readFile`, `writeFile`, `listDir`, and `stat` reach those paths outside the project, and a session action with `payload: ["messages"]` adds `conversation`. The user approves the whole list once at install. Calls outside it fail with `NOT_GRANTED`.
+- `integration` is optional. It adds a card at Settings → Integrations. `token` takes a pasted API token (`scheme: "bearer"` for `Authorization: Bearer`, `"basic"` for a username and token pair as Jira Cloud wants), `oauth` runs an authorize flow with a pasted client id, and `host: { "provider": "linear" }` reuses the Linear account already connected in AiWorker. The page never sees the token; AiWorker makes the calls through `host.request`.
+- `service` is optional. It declares a local process AiWorker starts next to the extension. It runs with the user's full access and no sandbox, so declare one only when the page cannot do the job. See [GUEST_SERVICES.md](./GUEST_SERVICES.md).
+
+## Actions without opening a panel
+
+Set `mode: "background"` on a message or session action to run it without opening the rail or a dialog:
+
+```json
+{ "id": "message-length", "label": "Show message length", "where": "message", "mode": "background" }
+```
+
+Register `onAction` immediately after `connectHost` in your background script, or your panel script when no background entry is declared:
+
+```ts
+const host = connectHost();
+host.onAction(async (item) => {
+  if (item.kind === 'message' && item.action === 'message-length') {
+    await host.toast({
+      kind: 'info',
+      message: `Message length: ${item.text.length} characters.`,
+      copy: true,
+      dismiss: true,
+      persistent: true,
+    });
+  }
+});
+```
+
+Each click runs in a fresh hidden iframe. Await all work inside the handler, including the toast. AiWorker removes the iframe when the handler finishes and reports thrown errors as toasts. Loading and execution together have a 20-second limit. A runtime switch, disabling the extension, or withdrawing approval also ends the invocation. Completed side effects are not rolled back or retried.
+
+`ctx.surface` is `"background"`; skip drawing your UI in that case. `ctx.item` stays `null`, so the action runs only through `onAction`, without repeated `onItem` snapshots. The session and directory context stay with the clicked target even if the user changes chats. AiWorker loads `background.entry` when declared and falls back to `panel.entry` for existing extensions. Omit `mode`, or use `"open"`, to open a visible panel or dialog. See `examples/hello-kit` for separate panel and background scripts.
+
+To remove the panel and its rail icon entirely, use this `contributes` block:
+
+```json
+{
+  "panel": { "id": "message-tools", "name": "Message Tools", "icon": "apps" },
+  "background": { "entry": "background/index.html" },
+  "actions": [
+    { "id": "message-length", "label": "Show message length", "where": "message", "mode": "background" }
+  ]
+}
+```
+
+The `panel` object retains the extension's identity for Settings and approval dialogs; only `panel.entry` creates a visible panel. Without it, every action must use `mode: "background"`, and `attach` and `page` cannot open a view. Slash commands call `onResolve` in the background entry, with `ctx.surface` also set to `"background"`. Capabilities, services, integrations, storage, and file access use the same approval checks. An attached chip can still be sent to the model or opened with its browser button; clicking to reopen the extension shows a no-panel notice.
+
+This addition requires a matching AiWorker build. For unreleased SDK preview builds, use the app built from the same revision.
+
+## Toast buttons
+
+`host.toast` accepts three optional fields:
+
+- `copy: true` adds Copy for the displayed message. Use `copy: { text: "..." }` to copy a different value, up to 32,000 characters. Whitespace in that value is preserved.
+- `dismiss: true` adds OK to close the toast.
+- `persistent: true` keeps the toast on screen until dismissed and always adds OK, even if `dismiss` is false.
+
+Copy keeps the toast open and shows Copied on success. A failed copy shows an error beside the button so the user can retry. AiWorker translates the buttons and handles clicks itself, so they work after a background action's iframe has closed. `await host.toast(...)` waits only for the host to show the toast, not for a button click. Omit these fields for an ordinary timed toast.
+
+## In the page
+
+For a full-screen board, add `"page": true` under `contributes`, or `"page": { "entry": "panel/page.html", "title": "Board" }` for separate HTML. Users open it from the Extension pages menu above the session list. `ctx.surface` is `"page"`. The extension cannot open the page itself.
+
+With `sessions` approved, use `listProjects()`, `listWorktrees(projectId)`, and `listSessions(projectId)`. Subscribe through `await onProjects(listener)`, `await onWorktrees(projectId, listener)`, or `await onSessions(projectId, listener)` and retain the returned unsubscribe function. Snapshots distinguish loading, ready, and error; session activity and observed turn outcomes are separate from your task status.
+
+`startSession` accepts `projectId` and `worktree: { kind: "new", name: "fix-login", baseBranch: "main" }` or `{ kind: "existing", directory }`. It preserves the current screen by default. `openSession(sessionId)` explicitly opens the chat. `host.storage.get/set/delete/keys` stores your own JSON on the connected server without a file-access grant. See [API.md](./API.md) for limits and partial results. The `tasks-demo` page exercises these methods together.
+
+```ts
+import { connectHost, HostRequestError } from '@aiworker/sdk';
+
+const host = connectHost();
+
+host.onReady((ctx) => {
+  document.body.dataset.theme = ctx.theme.mode;
+});
+
+host.onSession((session) => {
+  document.querySelector('#session')!.textContent = session?.title ?? '';
+});
+
+try {
+  const user = await host.request({ method: 'GET', path: '/me' });
+} catch (error) {
+  if (error instanceof HostRequestError && error.code === 'DISCONNECTED') {
+    await host.oauthStart();
+  }
+}
+
+await host.toast({ kind: 'info', message: 'Hello' });
+await host.compose({ text: 'Ask about the latest diff' });
+await host.attach({
+  providerId: 'acme-hello',
+  id: 'TICKET-1',
+  title: 'Login is broken',
+  url: 'https://example.com/TICKET-1',
+});
+await host.startSession({
+  providerId: 'acme-hello',
+  id: 'TICKET-1',
+  title: 'Login is broken',
+  url: 'https://example.com/TICKET-1',
+  worktree: true,
+  text: 'Optional first message',
+});
+await host.prompt({ text: 'Fix the login', send: true });
+await host.setBadge(3); // number on the rail icon; null clears it
+const { text } = await host.generate({ prompt: task.description, system: 'One-line summary only.' }); // capability model
+
+host.onResolve(({ command, args }) => {
+  // the user typed /task DEMO-2
+  const task = findTask(args.trim());
+  return task ? { providerId: 'acme-hello', id: task.id, title: task.title, url: task.url } : null;
+});
+
+host.onItem((item) => {
+  if (item?.kind === 'message') showMessage(item.text);      // "Create task from message"
+  if (item?.kind === 'session') showSummary(item.messages);  // "Summarize session"
+});
+```
+
+Every method, its limits, and the error codes are on the [Host API](https://openchamber.dev/docs/sdk/host/) page.
+
+## UI kit
+
+`@aiworker/sdk/ui` has buttons, fields, a searchable dropdown, checkboxes, tabs, badges, lists, empty states, spinners, banners, separators, progress bars, menus, and safe text, all drawn with the app's colours and fonts. Apply `applyHostReady` on every `onReady`, but mount controls and register listeners once. Repeated snapshots must not erase inputs or drafts. Every mount returns `{ update, dispose }`. Use `update` to pass changed values back to controls, including `tabs.update({ activeId })` and `select.update({ value })` inside `onChange`. See the [UI kit examples](https://docs.aiworker.dev/sdk/ui/) for input state and tab switching.
+
+```ts
+import { applyHostReady, mountList } from '@aiworker/sdk/ui';
+
+let mounted = false;
+host.onReady((ctx) => {
+  applyHostReady(ctx, document.documentElement);
+  if (mounted) return;
+  mounted = true;
+  mountList(document.querySelector('#root')!, {
+    items: tasks.map((task) => ({ id: task.id, leading: task.key, title: task.title })),
+    onSelect: (id) => {
+      const task = tasks.find((item) => item.id === id);
+      if (task) void host.attach({ providerId: 'acme-hello', id, title: task.title, url: task.url });
+    },
+  });
+});
+```
+
+AiWorker supplies thin, theme-aware native scrollbars inside extension documents, including nested lists, tabs, and textareas. The UI kit includes the same defaults for development previews. Existing installed bundles get the host stylesheet without rebuilding. Custom rendering hosts can use `GUEST_SCROLLBAR_CSS` from `@aiworker/sdk`. Authors can override these default rules; an extension's CSP still applies.
+
+## Schemas
+
+`@aiworker/sdk/schemas` exports the zod schemas for the manifest and the messages, for tools that validate extensions. The main entry has no zod dependency, so a page bundle stays small.
+
+## Scope
+
+This package covers the page, the manifest, the messages, and the UI kit. The page gets no terminal, no git, no files outside what it declared, and no access to AiWorker's React tree. A declared `service` is different: it is a real process with the user's rights, so it can do anything the user can, and the approval dialog says so. `apiVersion` 1 is frozen; new methods arrive with the app's releases and this package's version.

package/dist/api-version.d.ts

@@ -0,0 +1,6 @@
+/** Wire envelope `v`. Guest postMessage and host pushes use this. */
+export declare const AIWORKER_SDK_CHANNEL = "aiworker.sdk";
+export declare const AIWORKER_SDK_API_VERSION = 1;
+/** Manifest `apiVersion` values this host accepts. Service and sockets ship on `1`. */
+export declare const AIWORKER_SDK_MANIFEST_API_VERSIONS: readonly [1];
+export type AiWorkerManifestApiVersion = (typeof AIWORKER_SDK_MANIFEST_API_VERSIONS)[number];

package/dist/api-version.js

@@ -0,0 +1,5 @@
+/** Wire envelope `v`. Guest postMessage and host pushes use this. */
+export const AIWORKER_SDK_CHANNEL = 'aiworker.sdk';
+export const AIWORKER_SDK_API_VERSION = 1;
+/** Manifest `apiVersion` values this host accepts. Service and sockets ship on `1`. */
+export const AIWORKER_SDK_MANIFEST_API_VERSIONS = [1];