@openchamber/sdk 1.24.0 → 1.24.1

package/API.md

@@ -25,8 +25,8 @@ Two entrypoints:
 | Must exist                                                                       | When                                            | Failure code       |
 | -------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------ |
 | Semver `version` on `package.json` (`1.0.0`)                                     | Always on install                               | `invalid-manifest` |
-| `panel.entry` HTML file                                                          | When `panel.entry` is set (a tools-only package may omit it) | `invalid-manifest` |
-| Every relative `<script src="…">` `.js` from that HTML (usually `panel/main.js`) | When `panel.entry` is set                       | `missing-build`    |
+| `panel.entry` or `background.entry` HTML file | Every declared entry | `invalid-manifest` |
+| Every relative `<script src="…">` `.js` from that HTML | Every declared entry | `missing-build` |
 | File named by `panel.icon`                                                       | Only when icon ends in `.svg` (e.g. `icon.svg`) | `invalid-manifest` |
 | File named by `service.entry` (e.g. `service/main.js`)                               | When `contributes.service` is set                 | `missing-build`    |
 
@@ -73,6 +73,7 @@ Each returns an unsubscribe function. Late subscribers get the last known value
 | `onSettings(listener)`         | `GuestSettings`         | Declared integration fields only (`Record<string, string>`)  |
 | `onItem(listener)`             | `GuestItem              | null`                                                        | The item this surface was opened for: the chip (`AttachIssueRequest`), a message (`GuestMessageItem`), or a session (`GuestSessionItem`); `null` from the rail icon or + menu |
 | `onResolve(handler)`           | `{ command, args }` → `Promise<AttachIssueRequest \| null>` | Answers a `contributes.commands` slash command. Return the chip to attach, `null` for nothing (the user sees a short notice), or throw (the message reaches the user). One handler at a time |
+| `onAction(handler)` | `GuestActionItem` → `void \| Promise<void>` | Runs a `mode: "background"` message or session action. Register synchronously after `connectHost`. Await every operation; the frame is removed when the handler settles. Throw to report an error. One handler at a time; returns an unsubscribe function |
 
 
 `HostReadyContext`
@@ -85,7 +86,7 @@ Each returns an unsubscribe function. Late subscribers get the last known value
 | `locale`       | `string`                 | Host language tag                                                                        |
 | `directory`    | `string                  | null`                                                                                    |
 | `session`      | snapshot or `null`       | Title falls back to `id`. `busy` is live status. `model` is `providerID/id` when present |
-| `surface`      | `'panel'                 | 'dialog'`                                                                                |
+| `surface` | `'panel' \| 'dialog' \| 'page' \| 'background'` | Where the host mounted this frame |
 | `connection`   | `{ connected, account }` | Integration link state                                                                   |
 | `settings`     | `Record<string, string>` | Declared keys only                                                                       |
 | `item`         | `GuestItem               | null`                                                                                    | Set when the user clicked this guest's chip on the composer, or ran one of this guest's `contributes.actions`. Narrow with `isGuestMessageItem` / `isGuestSessionItem` / `isGuestAttachItem` |
@@ -130,7 +131,7 @@ Access tokens never appear in `ready` or in request results.
 
 | Method            | Arguments                         | Returns                        | Behavior                                                                              |
 | ----------------- | --------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------- |
-| `toast`           | `{ kind: 'info'                   | 'success'                      | 'error', message }`                                                                   |
+| `toast` | `{ kind: 'info' \| 'success' \| 'error', message, copy?, dismiss?, persistent? }` | `Promise<void>` | Show a toast, optionally with host-owned Copy and OK buttons; see Toast buttons below |
 | `openUrl`         | `url: string`                     | `Promise<void>`                | Open URL in the host                                                                  |
 | `openSurface`     | `surfaceId: string`               | `Promise<void>`                | Switch host chrome to that surface                                                    |
 | `writeClipboard`  | `text: string`                    | `Promise<void>`                | Copy in the host (1–32000 chars)                                                      |
@@ -216,6 +217,30 @@ Storage belongs to the extension on the connected server and needs no extra capa
 
 `request` **/** `serviceRequest` **rules:** `method` is `GET` | `POST` | `PUT` | `PATCH` | `DELETE`. `path` must start with `/`, no scheme, stay on the declared origin (cloud API or service loopback). Guest parses `body` as JSON when needed.
 
+### Toast buttons
+
+`ToastRequest.copy` is an optional boolean or `{ text: string }`. `true` copies the displayed message; an object supplies the clipboard value. `false` or omission adds no Copy button. The custom text must contain 1 to `GUEST_CLIPBOARD_TEXT_MAX` characters, with whitespace preserved. The displayed message is trimmed and must contain 1 to `GUEST_TOAST_MAX` characters. The client rejects invalid text lengths as `HOST_REJECTED` before sending; the host independently validates the wire payload.
+
+`dismiss: true` adds OK. `persistent: true` disables automatic expiry and always adds OK regardless of `dismiss`, so every persistent toast can be closed. Omitted or false `persistent` retains the host's usual duration.
+
+Copy leaves the toast open, reports success on the button, and shows a retryable error when the clipboard fails. OK dismisses only its own toast. Buttons use the host's locale and clipboard helper. They retain only the supplied text and toast identity, work after guest disposal or a runtime switch, and never call back into the extension. The `toast` promise resolves after display acknowledgement, without waiting for a click. Web and desktop use the same behavior; extension support on other runtimes is unchanged.
+
+### Background actions
+
+`contributes.actions[].mode` accepts `"open"` or `"background"`. Omitted mode keeps the existing panel/dialog routing and `onItem` delivery. Background actions load `background.entry` when declared, otherwise `panel.entry`. They never use separate attach-dialog HTML. They run on web and desktop, including connections through the private relay; VS Code and mobile still do not load extensions.
+
+`contributes.background` is `{ entry: "<package-local .html>" }`. It starts on demand for an action or command and adds no visible UI. With a background entry, `panel.entry` may be omitted: there is no rail icon, attach picker, or full-screen page, but background actions, slash commands, storage and granted APIs work. Identity remains in `panel.id/name/icon`. Open-mode actions, `page`, and enabled `attach` require `panel.entry`; invalid combinations fail as `invalid-panel`. Without either entry, the extension remains tools-only. Invalid background paths or a missing entry field fail as `invalid-background`.
+
+When both entries exist, the visible panel cannot register the slash-command resolver: the hidden background entry handles `onResolve` and receives `surface: "background"`. Existing panel-only commands retain their current behavior. Clicking an attached chip from a background-only extension shows a no-panel notice; its browser action remains available.
+
+Every background click mounts a fresh sandboxed iframe and sends one `action` request with an invocation `id` and a `GuestActionItem` payload. `host.onAction` receives that message or session item and sends `action-result` with `{ ok: true }` when the handler finishes, or `{ ok: false, error }` when it throws. The error is limited to `GUEST_RESOLVE_ERROR_MAX` characters. The host validates the reply and accepts only the matching invocation from that frame. It sends no acknowledgement for `action-result`.
+
+`ready.surface` is `"background"` and `ready.item` is `null`. Context updates never replay the action. The session and directory context remain scoped to the clicked target; the item itself is the snapshot captured at click time. Calls that explicitly write the composer still write the currently visible composer. `close()` is a no-op in a background frame; returning from the handler completes the action.
+
+The 20-second deadline covers loading and execution. At most eight background invocations may run concurrently. Completion, failure, timeout, disabling, lost approval, extension update/removal, runtime switch, and host unmount release the frame and its listeners. Late messages are ignored. Already completed or server-accepted effects are not undone, and the host does not automatically retry actions. A background action has the same declared capabilities as its extension. It does not hide the extension's rail icon.
+
+See [Actions without opening a panel](./README.md#actions-without-opening-a-panel) for a toast example.
+
 ### 1.3 Error codes (`HostRequestError.code`)
 
 
@@ -259,6 +284,7 @@ Storage belongs to the extension on the connected server and needs no extra capa
 | Request response                 | 256 000   |
 | Request timeout                  | 20 000 ms |
 | `resolve` answer (host waits)    | 20 000 ms |
+| Background action loading and execution | 20 000 ms |
 | Badge count                      | 999       |
 | Message item `text`              | 200 000   |
 | Session item (serialized)        | 2 000 000 |
@@ -400,10 +426,11 @@ Used by the OpenChamber host and by tools that validate packages. Guests rarely
 | `engines.openchamber` | Optional. Only `1.22.0` or `>=1.22.0`. Older host → `host-too-old`                                                                                                                   |
 | `panel.id`            | kebab-case                                                                                                                                                                           |
 | `panel.icon`          | Remixicon kebab name (`window`) **or** package `.svg` path. Remixicon needs no file. An `.svg` path must exist on disk or install fails (`invalid-manifest`). No URLs/absolute paths |
-| `panel.entry`         | Optional. Path inside package. No `..`, absolute, or URL. HTML must exist; its relative `.js` scripts must exist (`missing-build` if not). Omit it for a page-less extension: then only `tools` (plus `engines` and `version`) may be declared; `attach`, `actions`, `commands`, `service`, `integration`, `capabilities`, or `filesystem` without an entry fail parse as `invalid-panel`. A page-less extension has no rail icon, + menu row, or frame; the Extensions card says "No panel". `hasGuestPage(contributes)` tells the two apart |
+| `panel.entry` | Optional visible-panel HTML path inside the package. No `..`, absolute path, or URL. Its scripts must be built. Omitting it removes the rail icon and visible views; `background.entry` can still run code. With neither entry, only `tools` plus package identity/version/engines are allowed. `hasGuestPage` means a visible panel, not background execution |
+| `background.entry` | Optional package-local `.html` path. Loaded on demand for background actions and slash commands, preferred over `panel.entry` for these calls. Adds no rail icon. The file and its built scripts must exist. Malformed declarations are `invalid-background` |
 | `attach`              | `true` / `"panel"` → + menu opens rail; `"dialog"` → host window; omit/`false` → off menus. Object form `{ "mode": "panel" \| "dialog", "entry"?: "panel/attach.html" }`: `entry` (dialog only, same path rules as `panel.entry`, must exist with built scripts) is the page the dialog loads instead of `panel.entry` |
 | `capabilities`        | Optional list of `prompt`, `sessions`, `files`, `model`. `files` is read **and** write inside the open project; `model` is `generate`. Approved once at install                     |
-| `actions`             | Optional, 1–8 entries, unique kebab-case `id`, `label` 1–40 chars, optional `icon` (same rules as `panel.icon`, falls back to it), `where: "message" \| "session"`. Message actions may narrow `roles` to `["user"]` / `["assistant"]` (default both); session actions may ask for `payload: ["messages"]`, which adds the `conversation` capability. Bad shape is `invalid-actions`. The entry shows in that message's or session's menu and opens the guest with the item as `ready.item` (the attach window for `attach: "dialog"`, otherwise the rail) |
+| `actions` | Optional, 1–8 entries, unique kebab-case `id`, `label` 1–40 chars, optional `icon` with the `panel.icon` rules, `where: "message" \| "session"`, optional `mode: "open" \| "background"`. Message actions may narrow `roles` to `["user"]` / `["assistant"]`, default both. Session actions may request `payload: ["messages"]`, adding the `conversation` capability. Invalid shape is `invalid-actions`. Default `open` mode opens the guest with `ready.item`, using the attach dialog for `attach: "dialog"` and the rail otherwise. `background` calls `onAction` in a temporary hidden frame; see Background actions above |
 | `commands`            | Optional, 1–8 entries, unique `name` matching `/^[a-z][a-z0-9-]{0,23}$/`, optional `description` 1–80 chars (`invalid-commands`). `/name args` in the chat box calls `onResolve` instead of the model and attaches what it returns. A name the composer already has (built-in, OpenCode command, skill) is ignored with a console warning |
 | `tools`               | Optional, 1–16 entries that say how the extension's tool calls look in the chat. `match` is the full tool name OpenCode reports (`mcp.jira.search`, `jira_search`), 1–128 chars of `[A-Za-z0-9_.:-]`, with `*` allowed once at the end as a suffix wildcard (`mcp.jira.*`). Optional `name` (1–40, the header title when `title` is absent or renders empty), `icon` (Remixicon name or package `.svg` path, same rules as `panel.icon`; the SVG is drawn in the text colour at the glyph size), `title` / `subtitle` templates (1–200, `{input.path}` / `{output.path}` / `{metadata.path}` placeholders, a missing path renders empty, values are cut at 200), `output` `"auto"` (default) \| `"text"` \| `"json"` \| `"markdown"` \| `"code"` \| `"table"`, `language` (code only), `columns` (table only, 1–16 dotted paths; rows are the output array or `output.items`). Bad shape is `invalid-tools`. An exact `match` beats a wildcard from any extension; among equals the first extension wins. Only an enabled, fully approved extension's rules apply |
 | `filesystem`          | Optional, 1–16 globs, each 1–256 chars, starting with `/` or `~/`; `**` spans folders, `*` / `?` stay in one segment; no `..`, empty segment, or backslash (`invalid-filesystem`). Declaring it adds the `filesystem` capability and the dialog lists the globs |
@@ -422,7 +449,7 @@ Extra keys are dropped, not forwarded.
 | `parseManifestJson(json)` (`@openchamber/sdk/schemas`) | String → same result                                      |
 | `resolveAttachMode(attach)`                        | Normalize to `'panel'                                     |
 | `resolveAttachEntry(contributes)`                  | Dialog page from the object form, or `null` when the dialog reuses `panel.entry` |
-| `hasGuestPage(contributes)`                        | `true` when `panel.entry` is set; a page-less package may only declare `tools` |
+| `hasGuestPage(contributes)` | `true` when `panel.entry` is set; background-only and tools-only packages return `false` |
 | `resolveIntegrationAuth` / `resolveIntegrationApi` | Auth kind and API origin                                  |
 | `toPublicIntegration` / `toPublicService`            | Catalog-safe public slices                                |
 | `isGuestPackageSvgIcon`                            | Whether icon is a package SVG path                        |

package/DOCUMENTATION.md

@@ -20,6 +20,8 @@ Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`
 
 ## 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.
@@ -27,7 +29,7 @@ Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`
 - `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.openchamber` is `1.22.0` or `>=1.22.0`. Install refuses with `host-too-old` when this OpenChamber 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. `id`, `name`, and `icon` stay required: they identify the extension on the Extensions card and in the approval dialog. A package without `entry` is page-less (`hasGuestPage(contributes)` is `false`): it never mounts an iframe, so parse refuses `attach` (other than `false`), `actions`, `commands`, `service`, `integration`, a non-empty `capabilities`, and `filesystem` as `invalid-panel` (the message names the offending keys and says they need `panel.entry`). `tools`, `engines`, and `version` are all it may carry. Install skips the HTML and built-script checks, the catalog row has no `entry`, the served-file route refuses HTML and JS for that id (its SVG icons still serve), and the UI gives it no rail surface, attach row, action, command, or frame; the Extensions card shows "No panel" after the version. `examples/tools-only` is the reference.
+- `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.
@@ -46,7 +48,7 @@ Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`
 - `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` is optional. Panel stays required. 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.
+- `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.
@@ -81,12 +83,36 @@ File calls go through `POST /api/guests/:id/files` with the `x-opencode-director
 
 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 the actions of active guests (empty on VS Code and mobile); the message hover row and touch sheet, the sidebar session menu, and the header session menus add them after the built-ins. A click builds the item (`buildGuestMessageItem` / `buildGuestSessionItem`; the session conversation is loaded the same way Export as Markdown loads it, and a failed load is a toast, not an empty conversation) and `openGuestWithItem` routes it exactly like a chip click: the attach window for `attach: "dialog"` (through `useGuestDialogStore`, rendered by `GuestHosts` in `MainLayout`), otherwise the rail with `useGuestItemStore`. `useGuestCommands` lists commands minus reserved names; the composer routes `/name args` (`submit/guestCommands.ts`) to `runGuestCommand`, which asks the registered resolver of a mounted pane (`lib/guests/resolve.ts`) or mounts a hidden headless `PluginPane` through `GuestHosts` for the call. `PluginPane` registers its resolver once the guest said `hello` or the iframe loaded, posts `resolve`, and settles on `resolve-result` or the 20s deadline. A returned chip goes through `useInputStore.setPendingGuestIssue`, the same slot a panel `attach` uses. `badge` writes `useGuestBadgeStore` (memory only); the rail paints it like the git count and the pane clears it when the panel opens. A paused or not fully approved guest contributes no actions, commands, tool presentations, or badge.
+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. `@openchamber/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.

package/README.md

@@ -1,6 +1,6 @@
 # @openchamber/sdk
 
-Build extensions for [OpenChamber](https://openchamber.dev). An extension is a small web page that OpenChamber shows on its right-hand rail. 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 that page and the app.
+Build extensions for [OpenChamber](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).
 
@@ -88,15 +88,71 @@ Git installs also accept SSH addresses such as `git@github.com:owner/extension.g
 - `version` is required semver. Settings → Extensions shows it on the card.
 - `apiVersion` is `1`. Anything else is refused.
 - `engines.openchamber` is optional (`1.24.0` or `>=1.24.0`). Older OpenChamber 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 HTML file inside the folder. Leave `entry` out for an extension that only declares `tools`: it gets no rail icon or page, just its tool rules in the chat (`examples/tools-only`).
+- `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"`). 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). Up to 8.
+- `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 OpenChamber. The page never sees the token; OpenChamber makes the calls through `host.request`.
 - `service` is optional. It declares a local process OpenChamber 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. OpenChamber 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. OpenChamber 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 OpenChamber 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. OpenChamber 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.

package/dist/contract.d.ts

@@ -51,7 +51,7 @@ export type SessionSnapshot = {
     agent?: string;
 };
 /** Which host chrome mounted this iframe. Not `openSurface`. */
-export type GuestHostSurface = 'panel' | 'dialog' | 'page';
+export type GuestHostSurface = 'panel' | 'dialog' | 'page' | 'background';
 export type GuestConnection = {
     connected: boolean;
     account: string;
@@ -208,6 +208,14 @@ export type GuestSessionItem = {
     truncated?: boolean;
 };
 export type GuestItem = AttachIssueRequest | GuestMessageItem | GuestSessionItem;
+/** The captured target of a background action. Delivered once through `onAction`, not `onItem`. */
+export type GuestActionItem = GuestMessageItem | GuestSessionItem;
+export type ActionResultPayload = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
 export declare const isGuestMessageItem: (item: GuestItem | null) => item is GuestMessageItem;
 export declare const isGuestSessionItem: (item: GuestItem | null) => item is GuestSessionItem;
 /** The composer chip: what the guest handed to `attach`, with `text` filled from the chip. */
@@ -231,6 +239,14 @@ export type ToastKind = 'info' | 'success' | 'error';
 export type ToastRequest = {
     kind: ToastKind;
     message: string;
+    /** Show Copy. `true` copies the message; an object supplies different text, up to 32,000 characters. */
+    copy?: boolean | {
+        text: string;
+    };
+    /** Show an OK button that dismisses the toast. */
+    dismiss?: boolean;
+    /** Keep the toast until dismissed. Always includes OK, even when `dismiss` is false. */
+    persistent?: boolean;
 };
 export type ComposeRequest = {
     text: string;
@@ -395,6 +411,11 @@ export type HostResolveMessage = Envelope & {
     id: string;
     payload: ResolveRequest;
 };
+export type HostActionMessage = Envelope & {
+    type: 'action';
+    id: string;
+    payload: GuestActionItem;
+};
 export type HostResultMessage = Envelope & {
     type: 'result';
     id: string;
@@ -409,7 +430,7 @@ export type HostResultMessage = Envelope & {
 export type HostMessage = (Envelope & {
     type: 'workspace';
     payload: GuestWorkspaceUpdate;
-}) | HostReadyMessage | HostDirectoryMessage | HostSessionMessage | HostConnectionMessage | HostSettingsMessage | HostSessionLifecycleMessage | HostItemMessage | HostResolveMessage | HostResultMessage;
+}) | HostReadyMessage | HostDirectoryMessage | HostSessionMessage | HostConnectionMessage | HostSettingsMessage | HostSessionLifecycleMessage | HostItemMessage | HostResolveMessage | HostActionMessage | HostResultMessage;
 type GuestCall<Type extends string, Payload = never> = Envelope & {
     type: Type;
     id: string;
@@ -454,11 +475,17 @@ export type GuestResolveResultMessage = Envelope & {
     id: string;
     payload: ResolveResultPayload;
 };
+/** Completes a host `action`. The host sends no `result` back. */
+export type GuestActionResultMessage = Envelope & {
+    type: 'action-result';
+    id: string;
+    payload: ActionResultPayload;
+};
 export type GuestMessage = GuestCall<'workspace-read', GuestWorkspaceQuery> | GuestCall<'workspace-subscribe', GuestWorkspaceSubscription> | GuestCall<'workspace-unsubscribe', {
     subscriptionId: string;
 }> | GuestCall<'storage', GuestStorageRequest> | GuestCall<'open-session', {
     sessionId: string;
-}> | GuestHelloMessage | GuestToastMessage | GuestOpenUrlMessage | GuestOpenSurfaceMessage | GuestClipboardWriteMessage | GuestComposeMessage | GuestAttachMessage | GuestStartSessionMessage | GuestPromptMessage | GuestSessionLinkMessage | GuestCloseMessage | GuestOauthStartMessage | GuestOauthDisconnectMessage | GuestRequestMessage | GuestServiceRequestMessage | GuestServiceStatusMessage | GuestFileReadMessage | GuestFileWriteMessage | GuestFileListMessage | GuestFileStatMessage | GuestGenerateMessage | GuestBadgeMessage | GuestResolveResultMessage;
+}> | GuestHelloMessage | GuestToastMessage | GuestOpenUrlMessage | GuestOpenSurfaceMessage | GuestClipboardWriteMessage | GuestComposeMessage | GuestAttachMessage | GuestStartSessionMessage | GuestPromptMessage | GuestSessionLinkMessage | GuestCloseMessage | GuestOauthStartMessage | GuestOauthDisconnectMessage | GuestRequestMessage | GuestServiceRequestMessage | GuestServiceStatusMessage | GuestFileReadMessage | GuestFileWriteMessage | GuestFileListMessage | GuestFileStatMessage | GuestGenerateMessage | GuestBadgeMessage | GuestActionResultMessage | GuestResolveResultMessage;
 export declare const isServiceStatusResult: (value: HostResultPayload | undefined) => value is ServiceStatusResult;
 export declare const isGuestRequestResult: (value: HostResultPayload | undefined) => value is GuestRequestResult;
 export declare const isFileReadResult: (value: HostResultPayload | undefined) => value is FileReadResult;

package/dist/contract.js

@@ -198,7 +198,7 @@ export const isFileStatResult = (value) => Boolean(value && 'kind' in value && '
 export const isGenerateResult = (value) => Boolean(value && 'text' in value && String(value.text) === value.text && !('status' in value));
 const HOST_PUSH_TYPES = new Set([
     'workspace',
-    'ready', 'directory', 'session', 'connection', 'settings', 'session-lifecycle', 'item', 'resolve',
+    'ready', 'directory', 'session', 'connection', 'settings', 'session-lifecycle', 'item', 'resolve', 'action',
 ]);
 const asWireRecord = (data) => (Object(data) === data ? data : null);
 const isNonEmptyString = (value) => (String(value) === value && value.length > 0);

package/dist/host.d.ts

@@ -1,6 +1,6 @@
 import { type GuestProjectsSnapshot, type GuestWorktreesSnapshot, type GuestSessionsSnapshot } from './workspace.ts';
 import type { JsonValue } from './contract.ts';
-import { type AttachIssueRequest, type ComposeRequest, type PromptRequest, type PromptResult, type SessionLifecycleEvent, type StartSessionRequest, type GuestConnection, type GuestItem, type GuestMessage, type GuestRequest, type GuestRequestResult, type GuestSettings, type HostReadyContext, type HostRequestErrorCode, type ResolveRequest, type SessionSnapshot, type StartSessionResult, type ToastRequest, type ServiceStatusResult, type FileListResult, type FileReadResult, type FileStatResult, type FileWriteResult, type GenerateRequest, type GenerateResult } from './contract.ts';
+import { type AttachIssueRequest, type GuestActionItem, type ComposeRequest, type PromptRequest, type PromptResult, type SessionLifecycleEvent, type StartSessionRequest, type GuestConnection, type GuestItem, type GuestMessage, type GuestRequest, type GuestRequestResult, type GuestSettings, type HostReadyContext, type HostRequestErrorCode, type ResolveRequest, type SessionSnapshot, type StartSessionResult, type ToastRequest, type ServiceStatusResult, type FileListResult, type FileReadResult, type FileStatResult, type FileWriteResult, type GenerateRequest, type GenerateResult } from './contract.ts';
 export type HostFrame = {
     addEventListener: Window['addEventListener'];
     removeEventListener: Window['removeEventListener'];
@@ -49,6 +49,12 @@ export type HostClient = {
      * toast. One handler at a time; the returned function removes it.
      */
     onResolve: (handler: (request: ResolveRequest) => Promise<AttachIssueRequest | null> | AttachIssueRequest | null) => () => void;
+    /**
+     * Run a `mode: "background"` action. Register synchronously after connectHost.
+     * Await all work, including toast calls: the hidden frame is removed when
+     * this handler settles. Throw to report failure. One handler at a time.
+     */
+    onAction: (handler: (item: GuestActionItem) => void | Promise<void>) => () => void;
     toast: (request: ToastRequest) => Promise<void>;
     openUrl: (url: string) => Promise<void>;
     openSurface: (surfaceId: string) => Promise<void>;

package/dist/host.js

@@ -1,6 +1,6 @@
 import { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL } from "./api-version.js";
 import { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_VALUE_BYTES } from "./workspace.js";
-import { GUEST_FILE_CONTENT_MAX, GUEST_FILE_PATH_MAX, GUEST_GENERATE_OUTPUT_TOKENS_MAX, GUEST_GENERATE_PROMPT_MAX, GUEST_GENERATE_SYSTEM_MAX, GUEST_GENERATE_TIMEOUT_MS, GUEST_REQUEST_TIMEOUT_MS, GUEST_RESOLVE_ERROR_MAX, isGuestFilePath, isGuestRequestPath, clampAttachRequest, clampBadgeCount, clampPromptRequest, clampStartSessionRequest, readHostMessage, isGenerateResult, isFileListResult, isFileReadResult, isFileStatResult, isJsonValue, isFileWriteResult, isServiceStatusResult, isGuestRequestResult, isPromptResult, isStartSessionResult, } from "./contract.js";
+import { GUEST_FILE_CONTENT_MAX, GUEST_CLIPBOARD_TEXT_MAX, GUEST_TOAST_MAX, GUEST_FILE_PATH_MAX, GUEST_GENERATE_OUTPUT_TOKENS_MAX, GUEST_GENERATE_PROMPT_MAX, GUEST_GENERATE_SYSTEM_MAX, GUEST_GENERATE_TIMEOUT_MS, GUEST_REQUEST_TIMEOUT_MS, GUEST_RESOLVE_ERROR_MAX, isGuestFilePath, isGuestRequestPath, clampAttachRequest, clampBadgeCount, clampPromptRequest, clampStartSessionRequest, readHostMessage, isGenerateResult, isFileListResult, isFileReadResult, isFileStatResult, isJsonValue, isFileWriteResult, isServiceStatusResult, isGuestRequestResult, isPromptResult, isStartSessionResult, } from "./contract.js";
 export class HostRequestError extends Error {
     code;
     constructor(code, message) {
@@ -32,6 +32,7 @@ export const connectHost = (options = {}) => {
     const settingsListeners = new Set();
     const itemListeners = new Set();
     let resolveHandler = null;
+    let actionHandler = null;
     const pending = new Map();
     const workspaceListeners = new Map();
     let disposed = false;
@@ -135,6 +136,23 @@ export const connectHost = (options = {}) => {
             emit(itemListeners, message.payload.item);
             return;
         }
+        if (message.type === 'action') {
+            const answer = (payload) => {
+                if (!disposed)
+                    post({ channel: OPENCHAMBER_SDK_CHANNEL, v: OPENCHAMBER_SDK_API_VERSION,
+                        type: 'action-result', id: message.id, payload });
+            };
+            const handler = actionHandler;
+            if (!handler) {
+                answer({ ok: false, error: 'This extension does not handle background actions.' });
+                return;
+            }
+            Promise.resolve().then(() => handler(message.payload)).then(() => answer({ ok: true }), (error) => {
+                const text = (error instanceof Error ? error.message : String(error)).trim();
+                answer({ ok: false, error: (text || 'Action failed.').slice(0, GUEST_RESOLVE_ERROR_MAX) });
+            });
+            return;
+        }
         if (message.type === 'resolve') {
             const answer = (payload) => {
                 post({
@@ -239,6 +257,11 @@ export const connectHost = (options = {}) => {
         return result;
     };
     return {
+        onAction: (handler) => {
+            actionHandler = handler;
+            return () => { if (actionHandler === handler)
+                actionHandler = null; };
+        },
         listProjects: async () => {
             const result = await readWorkspace({ kind: 'projects' });
             if (result.kind !== 'projects')
@@ -344,13 +367,22 @@ export const connectHost = (options = {}) => {
                     resolveHandler = null;
             };
         },
-        toast: (payload) => request({
-            channel: OPENCHAMBER_SDK_CHANNEL,
-            v: OPENCHAMBER_SDK_API_VERSION,
-            type: 'toast',
-            id: nextId(ids),
-            payload,
-        }),
+        toast: (payload) => {
+            const message = payload.message.trim();
+            if (!message || message.length > GUEST_TOAST_MAX) {
+                return Promise.reject(new HostRequestError('HOST_REJECTED', `Toast message must contain 1 to ${GUEST_TOAST_MAX} characters.`));
+            }
+            if (payload.copy && payload.copy !== true && (!payload.copy.text.length || payload.copy.text.length > GUEST_CLIPBOARD_TEXT_MAX)) {
+                return Promise.reject(new HostRequestError('HOST_REJECTED', `Toast copy text must contain 1 to ${GUEST_CLIPBOARD_TEXT_MAX} characters.`));
+            }
+            return request({
+                channel: OPENCHAMBER_SDK_CHANNEL,
+                v: OPENCHAMBER_SDK_API_VERSION,
+                type: 'toast',
+                id: nextId(ids),
+                payload: { ...payload, message },
+            });
+        },
         openUrl: (url) => request({
             channel: OPENCHAMBER_SDK_CHANNEL,
             v: OPENCHAMBER_SDK_API_VERSION,
@@ -588,6 +620,7 @@ export const connectHost = (options = {}) => {
             workspaceListeners.clear();
             disposed = true;
             resolveHandler = null;
+            actionHandler = null;
             target.removeEventListener('message', onMessage);
             for (const waiter of pending.values()) {
                 clearTimeout(waiter.timer);

package/dist/index.d.ts

@@ -5,9 +5,9 @@ export { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_VALUE_BYTE
 export type { OpenChamberManifestApiVersion } from './api-version.ts';
 export { compareOpenChamberVersions, hostMeetsOpenChamberEngine, openChamberEngineMinimum, OPENCHAMBER_ENGINE_PATTERN, parseOpenChamberVersion, } from './host-version.ts';
 export { DECLARED_GUEST_CAPABILITIES, GUEST_ACTIONS_MAX, GUEST_ACTION_LABEL_MAX, GUEST_CAPABILITIES, GUEST_COMMANDS_MAX, GUEST_COMMAND_DESCRIPTION_MAX, GUEST_COMMAND_NAME, GUEST_TOOLS_MAX, GUEST_TOOL_COLUMNS_MAX, GUEST_TOOL_COLUMN_MAX, GUEST_TOOL_LANGUAGE_MAX, GUEST_TOOL_MATCH, GUEST_TOOL_MATCH_MAX, GUEST_TOOL_NAME_MAX, GUEST_TOOL_OUTPUTS, GUEST_TOOL_TEMPLATE_MAX, GUEST_TOOL_TEMPLATE_VALUE_MAX, guestActionsNeedConversation, GUEST_FILESYSTEM_PATTERN_MAX, GUEST_FILESYSTEM_PATTERNS_MAX, HOST_LINEAR_API_ORIGIN, isGuestFilesystemPattern, hasGuestCapability, hasGuestPage, isGuestApproved, isGuestPackageSvgIcon, requestedGuestCapabilities, resolveAttachEntry, resolvePageEntry, resolveAttachMode, resolveIntegrationApi, resolveIntegrationAuth, toPublicService, toPublicIntegration, } from './manifest.ts';
-export type { ServiceContribution, ServicePermissions, GuestActionContribution, GuestActionPayload, GuestActionRole, GuestActionWhere, GuestCommandContribution, GuestToolContribution, GuestToolOutput, AttachContribution, AttachContributionObject, AttachMode, DeclaredGuestCapability, GuestAuthorization, GuestCapability, IntegrationAuth, IntegrationContribution, IntegrationHost, IntegrationHostProvider, IntegrationOAuth, IntegrationOAuthAccount, IntegrationSettingField, IntegrationToken, IntegrationTokenScheme, OpenChamberContributes, OpenChamberEngines, OpenChamberManifest, PanelContribution, PageContribution, ParseManifestErrorCode, ParseManifestFailure, ParseManifestResult, ParseManifestSuccess, PublicService, PublicServicePermissions, PublicGuestCapabilities, PublicIntegration, PublicIntegrationToken, PublicSocketBinding, ResolvedGuestApi, SocketBinding, SocketPlatform, } from './manifest.ts';
+export type { ServiceContribution, ServicePermissions, GuestActionContribution, GuestActionPayload, GuestActionRole, GuestActionWhere, GuestCommandContribution, GuestToolContribution, GuestToolOutput, AttachContribution, AttachContributionObject, AttachMode, DeclaredGuestCapability, GuestAuthorization, GuestCapability, IntegrationAuth, IntegrationContribution, IntegrationHost, IntegrationHostProvider, IntegrationOAuth, IntegrationOAuthAccount, IntegrationSettingField, IntegrationToken, IntegrationTokenScheme, OpenChamberContributes, OpenChamberEngines, OpenChamberManifest, PanelContribution, BackgroundContribution, PageContribution, ParseManifestErrorCode, ParseManifestFailure, ParseManifestResult, ParseManifestSuccess, PublicService, PublicServicePermissions, PublicGuestCapabilities, PublicIntegration, PublicIntegrationToken, PublicSocketBinding, ResolvedGuestApi, SocketBinding, SocketPlatform, } from './manifest.ts';
 export { connectHost, HostRequestError } from './host.ts';
 export type { HostClient, HostClientOptions, HostFrame } from './host.ts';
 export { clampAttachRequest, clampBadgeCount, clampPromptRequest, clampStartSessionRequest, guestFileScope, isAttachData, isJsonValue, isFileListResult, isFileReadResult, isFileStatResult, isGenerateResult, isFileWriteResult, isGuestFilePath, isGuestAttachItem, isGuestMessageItem, isGuestSessionItem, isServiceStatusResult, isGuestRequestPath, isGuestRequestResult, isHostRequestErrorCode, isPromptResult, isStartSessionResult, readHostMessage, resolveHostRequestErrorCode, } from './contract.ts';
-export type { BadgeRequest, GuestBadgeMessage, GuestItem, GuestItemRole, GuestMessageItem, GuestResolveResultMessage, GuestSessionItem, GuestSessionItemMessage, HostResolveMessage, ResolveRequest, ResolveResultPayload, FileListEntry, FileListRequest, FileListResult, FileReadRequest, FileReadResult, FileStatRequest, FileStatResult, FileWriteRequest, FileWriteResult, GenerateRequest, GenerateResult, GuestFileEntryKind, GuestFileListMessage, GuestFileReadMessage, GuestFileScope, GuestFileStatKind, GuestFileStatMessage, GuestGenerateMessage, GuestFileWriteMessage, ServiceStatus, ServiceStatusResult, HostRequestErrorCode, AttachBranches, AttachIssueRequest, AttachThreadKind, JsonValue, HostResultPayload, PromptRequest, PromptResult, SessionLifecycleEvent, SessionLifecyclePhase, StartSessionRequest, StartSessionResult, StartSessionSent, ComposeRequest, GuestServiceRequestMessage, GuestServiceStatusMessage, GuestAttachMessage, GuestClipboardWriteMessage, GuestCloseMessage, GuestComposeMessage, GuestConnection, GuestHelloMessage, GuestMessage, GuestOauthDisconnectMessage, GuestOauthStartMessage, GuestOpenSurfaceMessage, GuestOpenUrlMessage, GuestRequest, GuestRequestMessage, GuestRequestMethod, GuestPromptMessage, GuestSessionLinkMessage, GuestStartSessionMessage, GuestRequestResult, GuestSettings, GuestToastMessage, GuestHostSurface, HostConnectionMessage, HostDirectoryMessage, HostItemMessage, HostMessage, HostReadyContext, HostReadyMessage, HostResultMessage, HostSessionLifecycleMessage, HostSessionMessage, HostSettingsMessage, HostTheme, HostThemeMode, HostThemeTokens, SessionSnapshot, ToastKind, ToastRequest, } from './contract.ts';
+export type { BadgeRequest, ActionResultPayload, GuestActionItem, GuestActionResultMessage, HostActionMessage, GuestBadgeMessage, GuestItem, GuestItemRole, GuestMessageItem, GuestResolveResultMessage, GuestSessionItem, GuestSessionItemMessage, HostResolveMessage, ResolveRequest, ResolveResultPayload, FileListEntry, FileListRequest, FileListResult, FileReadRequest, FileReadResult, FileStatRequest, FileStatResult, FileWriteRequest, FileWriteResult, GenerateRequest, GenerateResult, GuestFileEntryKind, GuestFileListMessage, GuestFileReadMessage, GuestFileScope, GuestFileStatKind, GuestFileStatMessage, GuestGenerateMessage, GuestFileWriteMessage, ServiceStatus, ServiceStatusResult, HostRequestErrorCode, AttachBranches, AttachIssueRequest, AttachThreadKind, JsonValue, HostResultPayload, PromptRequest, PromptResult, SessionLifecycleEvent, SessionLifecyclePhase, StartSessionRequest, StartSessionResult, StartSessionSent, ComposeRequest, GuestServiceRequestMessage, GuestServiceStatusMessage, GuestAttachMessage, GuestClipboardWriteMessage, GuestCloseMessage, GuestComposeMessage, GuestConnection, GuestHelloMessage, GuestMessage, GuestOauthDisconnectMessage, GuestOauthStartMessage, GuestOpenSurfaceMessage, GuestOpenUrlMessage, GuestRequest, GuestRequestMessage, GuestRequestMethod, GuestPromptMessage, GuestSessionLinkMessage, GuestStartSessionMessage, GuestRequestResult, GuestSettings, GuestToastMessage, GuestHostSurface, HostConnectionMessage, HostDirectoryMessage, HostItemMessage, HostMessage, HostReadyContext, HostReadyMessage, HostResultMessage, HostSessionLifecycleMessage, HostSessionMessage, HostSettingsMessage, HostTheme, HostThemeMode, HostThemeTokens, SessionSnapshot, ToastKind, ToastRequest, } from './contract.ts';
 export { EMPTY_GUEST_CONNECTION, GUEST_BADGE_MAX, GUEST_ITEM_MESSAGE_TEXT_MAX, GUEST_ITEM_SESSION_MAX, GUEST_RESOLVE_ERROR_MAX, GUEST_FILE_CONTENT_MAX, GUEST_FILE_ENTRY_KINDS, GUEST_FILE_LIST_MAX, GUEST_FILE_PATH_MAX, GUEST_GENERATE_OUTPUT_TOKENS_MAX, GUEST_GENERATE_PROMPT_MAX, GUEST_GENERATE_SYSTEM_MAX, GUEST_GENERATE_TEXT_MAX, GUEST_GENERATE_TIMEOUT_MS, GUEST_FILE_STAT_KINDS, SERVICE_STATUS_VALUES, HOST_REQUEST_ERROR_CODES, SESSION_LIFECYCLE_PHASES, START_SESSION_SENT, GUEST_ACCOUNT_MAX, GUEST_SESSION_AGENT_MAX, GUEST_SESSION_MODEL_MAX, GUEST_ATTACH_AUTHOR_MAX, GUEST_ATTACH_BRANCH_MAX, GUEST_ATTACH_DATA_MAX, GUEST_ATTACH_ID_MAX, GUEST_ATTACH_TEXT_MAX, GUEST_ATTACH_TITLE_MAX, GUEST_ATTACH_URL_MAX, GUEST_CLIPBOARD_TEXT_MAX, GUEST_TOAST_MAX, GUEST_COMPOSE_TEXT_MAX, GUEST_REQUEST_BODY_MAX, GUEST_REQUEST_PATH_MAX, GUEST_REQUEST_RESPONSE_MAX, GUEST_REQUEST_TIMEOUT_MS, GUEST_SETTING_VALUE_MAX, } from './contract.ts';

package/dist/manifest.d.ts

@@ -2,8 +2,8 @@ import type { OpenChamberManifestApiVersion } from './api-version.ts';
 export declare const PANEL_ID: RegExp;
 /**
  * The extension's identity on the rail, the Extensions card, and the approval
- * dialog. `entry` is the panel page; without it the extension has no page and
- * may only declare `tools` (see `hasGuestPage`).
+ * dialog. `entry` is the optional visible panel page. Code can instead run
+ * from `background.entry` without adding a rail icon.
  */
 export type PanelContribution = {
     id: string;
@@ -11,6 +11,10 @@ export type PanelContribution = {
     icon: string;
     entry?: string;
 };
+/** Sandboxed HTML loaded on demand for background actions and slash commands. */
+export type BackgroundContribution = {
+    entry: string;
+};
 export type AttachMode = 'panel' | 'dialog';
 /**
  * Object form of `contributes.attach`. `entry` is an HTML page inside the
@@ -42,7 +46,7 @@ export declare const GUEST_COMMAND_DESCRIPTION_MAX = 80;
 /** A slash command name: lower-case, digits and dashes, up to 24 characters. */
 export declare const GUEST_COMMAND_NAME: RegExp;
 /**
- * A menu entry on a message or a session. Clicking it opens the guest with
+ * A menu entry on a message or a session. By default it opens the guest with
  * the message or session as `ready.item`. `roles` narrows a message action
  * to user or assistant messages (default both); `payload: ["messages"]` on
  * a session action asks for the conversation and needs the `conversation`
@@ -54,6 +58,8 @@ export type GuestActionContribution = {
     /** Remixicon name or package `.svg` path, same as `panel.icon`. Falls back to the panel icon. */
     icon?: string;
     where: GuestActionWhere;
+    /** `background` calls `host.onAction` in a temporary hidden frame. Default: `open`. */
+    mode?: 'open' | 'background';
     roles?: GuestActionRole[];
     payload?: GuestActionPayload[];
 };
@@ -231,6 +237,7 @@ export declare const GUEST_FILESYSTEM_PATTERN_MAX = 256;
 export declare const isGuestFilesystemPattern: (value: string) => boolean;
 export type OpenChamberContributes = {
     panel: PanelContribution;
+    background?: BackgroundContribution;
     attach?: AttachContribution;
     page?: PageContribution;
     capabilities?: DeclaredGuestCapability[];
@@ -254,10 +261,8 @@ export type PublicGuestCapabilities = {
 };
 export declare const requestedGuestCapabilities: (contributes: Pick<OpenChamberContributes, "capabilities" | "integration" | "service" | "filesystem" | "actions">) => GuestCapability[];
 /**
- * Whether the package ships a panel page. A page-less package (no
- * `panel.entry`) never mounts an iframe: no rail surface, attach row, action,
- * command, service, integration, or capability; parse refuses those without
- * an entry. `tools` is the only contribution it may carry.
+ * Whether the package ships a visible panel. Background-only extensions can
+ * execute code but have no rail surface, attach picker, or full-screen page.
  */
 export declare const hasGuestPage: (contributes: Pick<OpenChamberContributes, "panel">) => boolean;
 export declare const isGuestApproved: (capabilities: PublicGuestCapabilities) => boolean;
@@ -277,7 +282,7 @@ export type OpenChamberManifest = {
     engines?: OpenChamberEngines;
     contributes: OpenChamberContributes;
 };
-export type ParseManifestErrorCode = 'not-object' | 'missing-openchamber' | 'unsupported-api-version' | 'invalid-engines' | 'invalid-version' | 'missing-panel' | 'invalid-panel' | 'invalid-panel-id' | 'invalid-panel-name' | 'invalid-panel-icon' | 'invalid-panel-entry' | 'invalid-attach' | 'invalid-page' | 'invalid-capabilities' | 'invalid-integration' | 'invalid-service' | 'invalid-filesystem' | 'invalid-actions' | 'invalid-commands' | 'invalid-tools';
+export type ParseManifestErrorCode = 'not-object' | 'missing-openchamber' | 'unsupported-api-version' | 'invalid-engines' | 'invalid-version' | 'missing-panel' | 'invalid-panel' | 'invalid-panel-id' | 'invalid-panel-name' | 'invalid-panel-icon' | 'invalid-panel-entry' | 'invalid-background' | 'invalid-attach' | 'invalid-page' | 'invalid-capabilities' | 'invalid-integration' | 'invalid-service' | 'invalid-filesystem' | 'invalid-actions' | 'invalid-commands' | 'invalid-tools';
 export type ParseManifestFailure = {
     ok: false;
     code: ParseManifestErrorCode;

package/dist/manifest.js

@@ -119,10 +119,8 @@ export const requestedGuestCapabilities = (contributes) => {
     return GUEST_CAPABILITIES.filter((capability) => declared.has(capability));
 };
 /**
- * Whether the package ships a panel page. A page-less package (no
- * `panel.entry`) never mounts an iframe: no rail surface, attach row, action,
- * command, service, integration, or capability; parse refuses those without
- * an entry. `tools` is the only contribution it may carry.
+ * Whether the package ships a visible panel. Background-only extensions can
+ * execute code but have no rail surface, attach picker, or full-screen page.
  */
 export const hasGuestPage = (contributes) => Boolean(contributes.panel.entry);
 export const isGuestApproved = (capabilities) => (capabilities.requested.every((capability) => capabilities.granted.includes(capability)));

package/dist/parse.d.ts

@@ -12,6 +12,9 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             icon: z.ZodString;
             entry: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
+        background: z.ZodOptional<z.ZodObject<{
+            entry: z.ZodString;
+        }, z.core.$strip>>;
         attach: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
             panel: "panel";
             dialog: "dialog";
@@ -104,6 +107,10 @@ export declare const openChamberManifestSchema: z.ZodObject<{
                 message: "message";
                 session: "session";
             }>;
+            mode: z.ZodOptional<z.ZodEnum<{
+                background: "background";
+                open: "open";
+            }>>;
             roles: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                 user: "user";
                 assistant: "assistant";
@@ -150,6 +157,9 @@ export declare const packageManifestSchema: z.ZodObject<{
                 icon: z.ZodString;
                 entry: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
+            background: z.ZodOptional<z.ZodObject<{
+                entry: z.ZodString;
+            }, z.core.$strip>>;
             attach: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodEnum<{
                 panel: "panel";
                 dialog: "dialog";
@@ -242,6 +252,10 @@ export declare const packageManifestSchema: z.ZodObject<{
                     message: "message";
                     session: "session";
                 }>;
+                mode: z.ZodOptional<z.ZodEnum<{
+                    background: "background";
+                    open: "open";
+                }>>;
                 roles: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                     user: "user";
                     assistant: "assistant";

package/dist/parse.js

@@ -149,6 +149,7 @@ const actionSchema = z.object({
     label: z.string().trim().min(1).max(GUEST_ACTION_LABEL_MAX),
     icon: z.string().trim().refine(isPanelIcon).optional(),
     where: z.enum(['message', 'session']),
+    mode: z.enum(['open', 'background']).optional(),
     roles: z.array(z.enum(['user', 'assistant'])).min(1).max(2).optional(),
     payload: z.array(z.enum(['messages'])).max(1).optional(),
 }).refine((value) => value.where === 'message' || value.roles === undefined, { path: ['roles'] })
@@ -178,6 +179,9 @@ const toolSchema = z.object({
 const toolsSchema = z.array(toolSchema).min(1).max(GUEST_TOOLS_MAX);
 const contributesSchema = z.object({
     panel: panelSchema,
+    background: z.object({
+        entry: z.string().trim().refine((value) => isSafeAssetPath(value) && value.toLowerCase().endsWith('.html')),
+    }).optional(),
     attach: attachSchema.optional(),
     page: z.union([z.literal(true), z.object({
             entry: z.string().trim().refine(isSafeAssetPath),
@@ -192,12 +196,9 @@ const contributesSchema = z.object({
     tools: toolsSchema.optional(),
 });
 /**
- * Everything that only makes sense with an iframe to mount. Without
- * `panel.entry` there is nothing to open from the rail, the + menu, a menu
- * action, or a slash command, and nothing to hand a capability, a service,
- * an integration, or a filesystem grant to; only `tools` stays meaningful.
+ * Contributions that need either the panel or background execution frame.
  */
-const pageOnlyContributions = (contributes) => {
+const runtimeContributions = (contributes) => {
     const declared = [];
     if (contributes.page !== undefined)
         declared.push('page');
@@ -225,13 +226,28 @@ export const openChamberManifestSchema = z.object({
     contributes: contributesSchema.superRefine((contributes, ctx) => {
         if (hasGuestPage(contributes))
             return;
-        const needsPage = pageOnlyContributions(contributes);
-        if (needsPage.length === 0)
+        if (contributes.background) {
+            const needsPanel = [];
+            if (contributes.page !== undefined)
+                needsPanel.push('page');
+            if (contributes.attach !== undefined && contributes.attach !== false)
+                needsPanel.push('attach');
+            if (contributes.actions?.some((action) => action.mode !== 'background'))
+                needsPanel.push('actions with mode "open"');
+            if (needsPanel.length > 0)
+                ctx.addIssue({
+                    code: 'custom', path: ['panel'],
+                    message: `${needsPanel.join(', ')} needs panel.entry; background-only actions must declare mode "background".`,
+                });
+            return;
+        }
+        const needsRuntime = runtimeContributions(contributes);
+        if (needsRuntime.length === 0)
             return;
         ctx.addIssue({
             code: 'custom',
             path: ['panel'],
-            message: `${needsPage.map((key) => `contributes.${key}`).join(', ')} needs panel.entry; an extension without a page may only declare tools.`,
+            message: `${needsRuntime.map((key) => `contributes.${key}`).join(', ')} needs panel.entry or background.entry; an extension without either may only declare tools.`,
         });
     }),
 });
@@ -293,6 +309,9 @@ const failureFromIssue = (issue) => {
     if (path === 'contributes.page' || path.startsWith('contributes.page.')) {
         return fail('invalid-page', 'contributes.page must be true or { entry: "<package HTML>", title?: "Page title" }.');
     }
+    if (path === 'contributes.background' || path.startsWith('contributes.background.')) {
+        return fail('invalid-background', 'contributes.background needs an entry ending in .html inside the package.');
+    }
     if (path === 'contributes.attach' || path.startsWith('contributes.attach.')) {
         return fail('invalid-attach', 'contributes.attach must be true, false, "panel", "dialog", or { "mode": "panel" | "dialog", "entry"?: "<html inside the package, dialog only>" }.');
     }

package/dist/protocol.d.ts

@@ -143,6 +143,7 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
             panel: "panel";
             dialog: "dialog";
             page: "page";
+            background: "background";
         }>;
         connection: z.ZodObject<{
             connected: z.ZodBoolean;
@@ -751,8 +752,53 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
     } | {
         text: string;
     } | undefined;
-}>>]>;
+}>>, z.ZodObject<{
+    type: z.ZodLiteral<"action">;
+    id: z.ZodString;
+    payload: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"message">;
+        action: z.ZodString;
+        sessionId: z.ZodString;
+        sessionTitle: z.ZodString;
+        directory: z.ZodNullable<z.ZodString>;
+        messageId: z.ZodString;
+        role: z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"session">;
+        action: z.ZodString;
+        sessionId: z.ZodString;
+        sessionTitle: z.ZodString;
+        directory: z.ZodNullable<z.ZodString>;
+        messages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            role: z.ZodEnum<{
+                user: "user";
+                assistant: "assistant";
+            }>;
+            text: z.ZodString;
+            createdAt: z.ZodNumber;
+        }, z.core.$strip>>>;
+        truncated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>]>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>]>;
 export declare const guestMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"action-result">;
+    id: z.ZodString;
+    payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+    }, z.core.$strip>, z.ZodObject<{
+        ok: z.ZodLiteral<false>;
+        error: z.ZodString;
+    }, z.core.$strip>], "ok">;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"workspace-read">;
     id: z.ZodString;
     payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -831,6 +877,11 @@ export declare const guestMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             success: "success";
         }>;
         message: z.ZodString;
+        copy: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            text: z.ZodString;
+        }, z.core.$strip>]>>;
+        dismiss: z.ZodOptional<z.ZodBoolean>;
+        persistent: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
     channel: z.ZodLiteral<"openchamber.sdk">;
     v: z.ZodLiteral<1>;

package/dist/protocol.js

@@ -146,7 +146,7 @@ const readyPayloadSchema = z.object({
     locale: z.string().min(1),
     directory: z.string().nullable(),
     session: sessionSnapshotSchema,
-    surface: z.enum(['panel', 'dialog', 'page']),
+    surface: z.enum(['panel', 'dialog', 'page', 'background']),
     connection: guestConnectionSchema,
     settings: guestSettingsSchema,
     item: guestItemSchema,
@@ -253,9 +253,24 @@ export const hostMessageSchema = z.union([
         }),
     }),
     hostResultSchema,
+    z.object({
+        ...envelope,
+        type: z.literal('action'),
+        id: z.string().min(1),
+        payload: z.union([messageItemSchema, sessionItemSchema]),
+    }),
 ]);
 const filePathSchema = z.string().min(1).max(GUEST_FILE_PATH_MAX).refine(isGuestFilePath);
 export const guestMessageSchema = z.discriminatedUnion('type', [
+    z.object({
+        ...envelope,
+        type: z.literal('action-result'),
+        id: z.string().min(1),
+        payload: z.discriminatedUnion('ok', [
+            z.object({ ok: z.literal(true) }),
+            z.object({ ok: z.literal(false), error: z.string().trim().min(1).max(GUEST_RESOLVE_ERROR_MAX) }),
+        ]),
+    }),
     z.object({ ...envelope, type: z.literal('workspace-read'), id: z.string().min(1), payload: guestWorkspaceQuerySchema }),
     z.object({ ...envelope, type: z.literal('workspace-subscribe'), id: z.string().min(1), payload: z.object({ subscriptionId: z.string().min(1).max(128), query: guestWorkspaceQuerySchema }) }),
     z.object({ ...envelope, type: z.literal('workspace-unsubscribe'), id: z.string().min(1), payload: z.object({ subscriptionId: z.string().min(1).max(128) }) }),
@@ -272,6 +287,9 @@ export const guestMessageSchema = z.discriminatedUnion('type', [
         payload: z.object({
             kind: z.enum(['info', 'success', 'error']),
             message: z.string().trim().min(1).max(GUEST_TOAST_MAX),
+            copy: z.union([z.boolean(), z.object({ text: z.string().min(1).max(GUEST_CLIPBOARD_TEXT_MAX) })]).optional(),
+            dismiss: z.boolean().optional(),
+            persistent: z.boolean().optional(),
         }),
     }),
     z.object({

package/dist/ui/menu.js

@@ -51,8 +51,12 @@ export const mountMenu = (root, initial) => {
         setActive(actions(props.items).some((item) => item.id === activeId) ? activeId : null);
     };
     const close = () => {
-        closePopup?.();
+        // Removing a focused row fires `focusout` synchronously from inside the disposer, and
+        // that handler calls `close` again. Clearing the slot first makes the re-entry a no-op
+        // instead of a second `popup.remove()` that throws before the pick reaches `onChange`.
+        const dispose = closePopup;
         closePopup = null;
+        dispose?.();
         activeId = null;
         triggerNode?.setAttribute('aria-expanded', 'false');
     };

package/dist/ui/select.js

@@ -63,8 +63,12 @@ export const mountSelect = (root, initial) => {
         setActive(options.some((option) => option.id === activeId) ? activeId : options[0]?.id ?? null);
     };
     const close = () => {
-        closePopup?.();
+        // Removing a focused row fires `focusout` synchronously from inside the disposer, and
+        // that handler calls `close` again. Clearing the slot first makes the re-entry a no-op
+        // instead of a second `popup.remove()` that throws before the pick reaches `onChange`.
+        const dispose = closePopup;
         closePopup = null;
+        dispose?.();
         query = '';
         search.value = '';
         trigger.setAttribute('aria-expanded', 'false');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openchamber/sdk",
-  "version": "1.24.0",
+  "version": "1.24.1",
   "description": "Contract for OpenChamber guests: manifest parse and iframe host bridge.",
   "private": false,
   "license": "MIT",