@openchamber/sdk 2.1.1 → 2.2.0

package/API.md

@@ -218,6 +218,22 @@ Projects contain `id`, `name`, `directory`. Worktrees contain `directory`, `name
 
 `activity` is `unknown`, `idle`, `running`, `retrying`, `waiting-permission`, or `waiting-question` (the agent put a form to the user and is waiting on the answer). `outcome` is the last observed `completed` or `failed` turn, or `null` when unknown or working. Outcomes are in memory for the latest 2,000 observed sessions, reset on runtime switch, and are not reconstructed from persisted history. A later idle event preserves an observed failure until another run starts. `completed` never means the extension's task is Done. Blocking-request contents and approve/reply actions are not exposed.
 
+### Running shells
+
+These methods need the `shells` capability. They expose the running shell commands in a scope — one session and its subagents, a registered project, or every session — and let the extension read their output and stop them. OpenChamber answers from its local store; no network read happens per request.
+
+| Method | Result |
+| --- | --- |
+| `onRunningShells(scope, listener)` | subscription: the running shell commands in scope — one session and its subagents (`{ kind: 'session', sessionId }`), a registered project (`{ kind: 'project', projectId }`), or every session (`{ kind: 'global' }`) — oldest first, with each command's `background` flag, plus the ones that ended since OpenChamber started watching |
+| `readShellOutput(shellId, { cursor?, tailBytes? })` | one page of a running or ended command's output; `tailBytes` is capped at 65536 |
+| `stopShell(shellId)` | sends the agent the stop note first, then removes the command |
+
+Await subscription registration to handle refusal, then retain its returned unsubscribe function. Each subscription sends an initial snapshot, then changes, and counts against the same 32-subscription limit as the workspace subscriptions. The snapshot is `{ kind: 'shells', scope, shells, ended }`, where `scope` echoes the subscription's scope; each shell is `{ id, sessionID, command, startedAt, background }`, at most 200, oldest first. `background` is `true` for a job the turn does not wait for, and `false` while the turn that ran it is blocked on it.
+
+`ended` holds the commands in scope that OpenChamber saw running and saw end, oldest end first, at most 200 with the newest kept. Each adds `status`, `endedAt`, and `exit` when the command exited with a code. `status` is `exited`, `timeout`, `killed` (a signal), `stopped` (by a user: Stop in the app, `stopShell`, or aborting the turn that waited on it), or `unknown` (the end fell into a reconnect and OpenChamber only saw the command gone). The list lives in memory: it starts empty when the app loads and resets on a runtime switch, so keep anything you show across reloads in extension storage.
+
+`readShellOutput` returns `{ output, cursor, skipped }`; omit `cursor` to start `tailBytes` before the end, and `skipped` says earlier output was dropped. OpenCode keeps an ended command's output until it evicts the command (the latest 25 ended commands per directory); a stopped command's output is removed with it. A shell OpenChamber has not seen, a stopped one, and one whose output OpenCode no longer keeps are `NOT_FOUND`; `stopShell` on a shell that is not running is `NOT_FOUND` too. An unapproved `shells` capability is `NOT_GRANTED`.
+
 ### Extension storage
 
 `host.storage.get(key, options?)` returns JSON or `undefined` for a missing key. JSON `null` is a stored value. `set(key, value, options?)` and `delete(key, options?)` return `Promise<void>`; `keys(options?)` returns `Promise<string[]>` in sorted order.
@@ -449,7 +465,7 @@ Used by the OpenChamber host and by tools that validate packages. Guests rarely
         "entry": "panel/index.html"
       },
       "attach": "dialog",
-      "capabilities": ["prompt", "sessions", "files"],
+      "capabilities": ["prompt", "sessions", "files", "shells"],
       "filesystem": ["~/.config/opencode/opencode.json", "/tmp/acme/**"],
       "actions": [
         { "id": "create-task", "label": "Create task from message", "icon": "add-circle", "where": "message", "roles": ["assistant"] },
@@ -475,7 +491,7 @@ Used by the OpenChamber host and by tools that validate packages. Guests rarely
 | `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                     |
+| `capabilities`        | Optional list of `prompt`, `sessions`, `files`, `model`, `shells`. `files` is read **and** write inside the open project; `model` is `generate`; `shells` is the running-shell methods. Approved once at install                     |
 | `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 |

package/DOCUMENTATION.md

@@ -33,6 +33,7 @@ Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`
 - `contributes.fileEditors` is 1 to `GUEST_FILE_EDITORS_MAX` (8) editors, each `{ id, title, match, entry }` (`FileEditorContribution`, `src/file-editor.ts`): unique kebab-case `id`, `title` 1 to `GUEST_FILE_EDITOR_TITLE_MAX` (60), `match` 1 to `GUEST_FILE_EDITOR_PATTERNS_MAX` (16) file-name globs (`isFileEditorPattern`: 1 to 128 characters, no `/`, `\` or NUL, not only wildcards; `matchesFileEditorPattern` compares the name case-insensitively, `*` any run, `?` one character), `entry` package-local `.html`, optional `content` `text` (default) or `binary` (`FileEditorContentKind`); anything else is `invalid-file-editors`. Like the status section, editors are frames of their own: without `panel.entry` or `background.entry` a package may still declare `capabilities`, `service`, `integration`, and `filesystem`, and `page`, `attach`, `actions`, `commands` are `invalid-panel`. The server checks each entry's HTML and built scripts at install, carries `fileEditors` on the catalog row, and counts them as runtime entries for serving and storage (`hasGuestFrame` in `server/lib/guests/catalog.js`). The host owns the file. Wire: host → guest `file-open { path, name, readOnly, encoding: 'text', content } | { ..., encoding: 'binary', bytes }` (a push, sent on `hello` and iframe load, never on other host-state pushes; `connectHost` drops a repeat of the same file), `file-snapshot { id, payload: { purpose: 'save' | 'handoff' } }` answered by guest `file-snapshot-result { id, payload: { snapshot: { content, version } | { bytes, version } } | { error } }` with no `result` back, and `file-saved { version }`; guest → host fire-and-forget `file-change { dirty, edited }`, `file-save`, and `file-unsupported` (no `id`, no answer). Bytes are a `Uint8Array<ArrayBuffer>`, copied by structured clone, so the host schema's `z.instanceof(Uint8Array)` holds in the receiving realm; `sameFileEditorDocument` compares them byte for byte for the repeat-push check. Content on both sides is capped at `GUEST_FILE_EDITOR_CONTENT_MAX` (20 000 000 characters or bytes, `fileEditorPayloadSize`); the guest refuses an oversized snapshot with an error instead of letting the host schema drop it. `onFileOpen` registration installs one capturing `keydown` listener that turns Cmd/Ctrl+S into `file-save`, because key events inside the frame never reach the host. `createFileSaveTracker` is the pure dirty bookkeeping: a written snapshot's version is marked saved, so edits made during the write stay dirty. The host side is `packages/ui/src/lib/guests/file-editor-channel.ts` (one channel per mounted editor; disconnect rejects every outstanding snapshot request), `PluginPane surface="file"`, and `components/views/files/GuestFileEditor.tsx`; the Files view contract is in that folder's `DOCUMENTATION.md`. VS Code and mobile keep the catalog empty, so files there stay with the host's own viewers.
 - `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.
+- `shells.ts` owns the running-shell contract: the `shells` declared capability, the snapshot and result types, and `GUEST_SHELL_ID_MAX` (128), `GUEST_SHELLS_MAX` (200), and `GUEST_SHELL_OUTPUT_TAIL_MAX` (65536). Wire: guest `shells-subscribe` `{ subscriptionId, scope }` with scope `{ kind: 'session', sessionId }`, `{ kind: 'project', projectId }`, or `{ kind: 'global' }`, `shells-unsubscribe` `{ subscriptionId }`, `shell-output` `{ shellId, cursor?, tailBytes? }`, and `shell-stop` `{ shellId }`; host push `shells` `{ subscriptionId, snapshot }` where the snapshot carries `kind: 'shells'`, an echo of the requested `scope`, the running `shells`, and `ended` (`GuestEndedShell`: a running shell plus `status` from `GUEST_SHELL_END_STATUSES`, `endedAt`, optional integer `exit`). `lib/guests/shells.ts` projects `useBackgroundShellsStore` (the requested scope: a session and its subagents, a registered project's sessions matched by directory rather than by `projectID`, or every session; running oldest start first, ended oldest end first keeping the newest `GUEST_SHELLS_MAX`) from memory, so a read never hits the network or git; `observeGuestShells` shares one observer per runtime and scope. The store's `ended` list is the app's own observation of `shell.exited` / `shell.deleted` (see `sync/DOCUMENTATION.md`), so it is empty after a reload. `readGuestShellOutput` reads a running or ended shell in the directory it ran in, and answers `NOT_FOUND` for a shell the store never saw, a `stopped` one (OpenCode unlinks its output on removal), and an OpenCode 404 (evicted past the 25 retained exited commands per directory); other failures pass through. `PluginPane` wires the four effects, checks the `shells` grant per call, counts shell subscriptions against the frame's 32-subscription limit, and answers `stopShell` on a shell that is not running with `NOT_FOUND`. `opencodeClient.stopBackgroundShell` writes the agent's cancellation note before it kills the command and kills nothing when the note fails.
 - `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. Device scope is an explicit SDK opt-in only when ready features advertise `deviceStorage`; it uses the host runtime key plus guest ID and server-issued installation `storageId`, and has no instance fallback. Different runtime identities remain separate even if a server duplicates a storage ID. URL-based runtime keys separate address aliases; saved-host and relay keys retain their existing identity rules. IndexedDB limits are 2 MiB per namespace and 16 MiB of serialized preference data across the database; browser metadata has separate overhead. A confirmed uninstall makes the namespace inaccessible, but an offline profile retains its bytes until site data is removed. Device storage does not promise secret or SSO storage. 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`.
@@ -51,7 +52,7 @@ Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`
 - 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, `page` full screen, `background` hidden, `status` in the Work Status panel, `file` as a Files view editor), `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`, `filesystem`, and `origins` from a session action with `payload: ["messages"]`, `contributes.service`, `contributes.integration`, `contributes.filesystem`, and `contributes.origins`; 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.capabilities` is a list of `prompt`, `sessions`, `files`, `model`, and/or `shells` (`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`, `filesystem`, and `origins` from a session action with `payload: ["messages"]`, `contributes.service`, `contributes.integration`, `contributes.filesystem`, and `contributes.origins`; 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`, the four file calls, and the three shell 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.

package/dist/contract.d.ts

@@ -1,5 +1,6 @@
 import { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL } from './api-version.ts';
 import type { FileEditorChange, FileEditorDocument, FileSnapshotRequest, FileSnapshotResultPayload } from './file-editor.ts';
+import type { GuestRunningShellsSnapshot, GuestShellOutputRequest, GuestShellOutputResult, GuestShellStopResult, GuestShellsSubscription } from './shells.ts';
 import type { GuestSessionWorktree, GuestStorageRequest, GuestStorageResult, GuestWorkspaceQuery, GuestWorkspaceSnapshot, GuestWorkspaceSubscription, GuestWorkspaceUpdate, GuestWorktree } from './workspace.ts';
 import type { GuestStatusControl, GuestStatusControlEvent } from './status-controls.ts';
 import type { GuestPopoverClosedEvent, GuestPopoverContext, GuestPopoverRequest } from './popover.ts';
@@ -166,7 +167,7 @@ export type GenerateRequest = {
 export type GenerateResult = {
     text: string;
 };
-export type HostResultPayload = GuestStorageResult | GuestWorkspaceSnapshot | GuestRequestResult | StartSessionResult | PromptResult | ServiceStatusResult | FileReadResult | FileWriteResult | FileListResult | FileStatResult | GenerateResult;
+export type HostResultPayload = GuestStorageResult | GuestWorkspaceSnapshot | GuestShellOutputResult | GuestShellStopResult | GuestRequestResult | StartSessionResult | PromptResult | ServiceStatusResult | FileReadResult | FileWriteResult | FileListResult | FileStatResult | GenerateResult;
 export declare const isStartSessionResult: (value: HostResultPayload | undefined) => value is StartSessionResult;
 export declare const isPromptResult: (value: HostResultPayload | undefined) => value is PromptResult;
 export declare const EMPTY_GUEST_CONNECTION: GuestConnection;
@@ -490,10 +491,17 @@ export type HostResultMessage = Envelope & {
     error: string;
     code: HostRequestErrorCode;
 });
+export type HostShellsMessage = Envelope & {
+    type: 'shells';
+    payload: {
+        subscriptionId: string;
+        snapshot: GuestRunningShellsSnapshot;
+    };
+};
 export type HostMessage = (Envelope & {
     type: 'workspace';
     payload: GuestWorkspaceUpdate;
-}) | HostReadyMessage | HostDirectoryMessage | HostSessionMessage | HostConnectionMessage | HostSettingsMessage | HostSessionLifecycleMessage | HostItemMessage | HostStatusControlEventMessage | HostPopoverClosedMessage | HostResolveMessage | HostActionMessage | HostFileOpenMessage | HostFileSnapshotMessage | HostFileSavedMessage | HostResultMessage;
+}) | HostShellsMessage | HostReadyMessage | HostDirectoryMessage | HostSessionMessage | HostConnectionMessage | HostSettingsMessage | HostSessionLifecycleMessage | HostItemMessage | HostStatusControlEventMessage | HostPopoverClosedMessage | HostResolveMessage | HostActionMessage | HostFileOpenMessage | HostFileSnapshotMessage | HostFileSavedMessage | HostResultMessage;
 type GuestCall<Type extends string, Payload = never> = Envelope & {
     type: Type;
     id: string;
@@ -577,9 +585,17 @@ export type GuestFileSaveMessage = Envelope & {
 export type GuestFileUnsupportedMessage = Envelope & {
     type: 'file-unsupported';
 };
+export type GuestShellsSubscribeMessage = GuestCall<'shells-subscribe', GuestShellsSubscription>;
+export type GuestShellsUnsubscribeMessage = GuestCall<'shells-unsubscribe', {
+    subscriptionId: string;
+}>;
+export type GuestShellOutputMessage = GuestCall<'shell-output', GuestShellOutputRequest>;
+export type GuestShellStopMessage = GuestCall<'shell-stop', {
+    shellId: string;
+}>;
 export type GuestMessage = GuestCall<'workspace-read', GuestWorkspaceQuery> | GuestCall<'workspace-subscribe', GuestWorkspaceSubscription> | GuestCall<'workspace-unsubscribe', {
     subscriptionId: string;
-}> | GuestCall<'storage', GuestStorageRequest> | GuestCall<'open-session', {
+}> | GuestShellsSubscribeMessage | GuestShellsUnsubscribeMessage | GuestShellOutputMessage | GuestShellStopMessage | 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 | GuestResizeMessage | GuestOpenCommitMessage | GuestStatusControlsMessage | GuestPopoverOpenMessage | GuestPopoverCloseMessage | GuestPopoverAnchorMessage | GuestActionResultMessage | GuestResolveResultMessage | GuestFileSnapshotResultMessage | GuestFileChangeMessage | GuestFileSaveMessage | GuestFileUnsupportedMessage;
 export declare const isServiceStatusResult: (value: HostResultPayload | undefined) => value is ServiceStatusResult;

package/dist/contract.js

@@ -210,6 +210,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',
+    'shells',
     'ready', 'directory', 'session', 'connection', 'settings', 'session-lifecycle', 'item', 'resolve', 'action',
     'status-control-event', 'popover-closed',
     'file-open', 'file-snapshot', 'file-saved',

package/dist/host-version.d.ts

@@ -1,6 +1,6 @@
 /** `1.22.0` or `>=1.22.0`. Ranges beyond a floor are not accepted. */
 export declare const OPENCHAMBER_ENGINE_PATTERN: RegExp;
-export type OpenChamberVersionParts = {
+type OpenChamberVersionParts = {
     major: number;
     minor: number;
     patch: number;
@@ -14,3 +14,4 @@ export declare const openChamberEngineMinimum: (engine: string) => string | null
  * Unknown host versions fail closed when an engine is declared.
  */
 export declare const hostMeetsOpenChamberEngine: (hostVersion: string, engine: string) => boolean;
+export {};

package/dist/host.d.ts

@@ -4,6 +4,7 @@ import type { JsonValue } from './contract.ts';
 import { type GuestPopoverClosedEvent, type GuestPopoverRequest } from './popover.ts';
 import { type FileEditorChange, type FileEditorDocument, type FileEditorSnapshot, type FileSnapshotPurpose } from './file-editor.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';
+import { type GuestRunningShellsSnapshot, type GuestShellOutputResult, type GuestShellStopResult, type GuestShellsScope } from './shells.ts';
 export type HostFrame = {
     addEventListener: Window['addEventListener'];
     removeEventListener: Window['removeEventListener'];
@@ -26,6 +27,12 @@ export type HostClient = {
     onProjects: (listener: (snapshot: GuestProjectsSnapshot) => void) => Promise<() => void>;
     onWorktrees: (projectId: string, listener: (snapshot: GuestWorktreesSnapshot) => void) => Promise<() => void>;
     onSessions: (projectId: string, listener: (snapshot: GuestSessionsSnapshot) => void) => Promise<() => void>;
+    onRunningShells: (scope: GuestShellsScope, listener: (snapshot: GuestRunningShellsSnapshot) => void) => Promise<() => void>;
+    readShellOutput: (shellId: string, options?: {
+        cursor?: number;
+        tailBytes?: number;
+    }) => Promise<GuestShellOutputResult>;
+    stopShell: (shellId: string) => Promise<GuestShellStopResult>;
     openSession: (sessionId: string) => Promise<void>;
     storage: {
         get: (key: string, options?: GuestStorageOptions) => Promise<JsonValue | undefined>;

package/dist/host.js

@@ -4,6 +4,7 @@ import { isGuestStatusControls } from "./status-controls.js";
 import { isGuestPopoverRequest } from "./popover.js";
 import { GUEST_FILE_EDITOR_CONTENT_MAX, GUEST_FILE_EDITOR_VERSION_MAX, fileEditorPayloadSize, sameFileEditorDocument, } from "./file-editor.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, clampFrameHeight, isGuestCommitSha, clampPromptRequest, clampStartSessionRequest, readHostMessage, isGenerateResult, isFileListResult, isFileReadResult, isFileStatResult, isJsonValue, isFileWriteResult, isServiceStatusResult, isGuestRequestResult, isPromptResult, isStartSessionResult, } from "./contract.js";
+import { GUEST_SHELL_ID_MAX, GUEST_SHELL_OUTPUT_TAIL_MAX } from "./shells.js";
 // Structural, not `instanceof KeyboardEvent`: the frame's own realm owns that
 // constructor, and non-browser runtimes have none.
 const isKeyEvent = (event) => 'key' in event && 'metaKey' in event && 'ctrlKey' in event;
@@ -59,6 +60,7 @@ export const connectHost = (options = {}) => {
     let saveShortcutInstalled = false;
     const pending = new Map();
     const workspaceListeners = new Map();
+    const shellsListeners = new Map();
     let disposed = false;
     const ids = { value: 0 };
     let lastReady = null;
@@ -103,6 +105,12 @@ export const connectHost = (options = {}) => {
                 emit([listener], message.payload.snapshot);
             return;
         }
+        if (message.type === 'shells') {
+            const listener = shellsListeners.get(message.payload.subscriptionId);
+            if (listener)
+                emit([listener], message.payload.snapshot);
+            return;
+        }
         if (message.type === 'ready') {
             lastReady = message.payload;
             lastLifecycle = lifecycleFromSession(message.payload.session);
@@ -372,6 +380,28 @@ export const connectHost = (options = {}) => {
             post({ ...envelope, type: 'workspace-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
         };
     };
+    const subscribeShells = async (scope, listener) => {
+        if (scope.kind === 'session')
+            requireIdentity(scope.sessionId);
+        if (scope.kind === 'project')
+            requireIdentity(scope.projectId);
+        const subscriptionId = nextId(ids);
+        shellsListeners.set(subscriptionId, listener);
+        try {
+            await request({ ...envelope, type: 'shells-subscribe', id: nextId(ids), payload: { subscriptionId, scope } });
+        }
+        catch (error) {
+            shellsListeners.delete(subscriptionId);
+            if (!disposed)
+                post({ ...envelope, type: 'shells-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
+            throw error;
+        }
+        return () => {
+            if (!shellsListeners.delete(subscriptionId) || disposed)
+                return;
+            post({ ...envelope, type: 'shells-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
+        };
+    };
     const storage = async (payload) => {
         if ('key' in payload && (payload.key.length === 0 || payload.key.length > GUEST_STORAGE_KEY_MAX)) {
             throw new HostRequestError('HOST_REJECTED', 'Storage key must contain 1 to 128 characters.');
@@ -432,6 +462,31 @@ export const connectHost = (options = {}) => {
             listener(snapshot); }),
         onSessions: (projectId, listener) => subscribeWorkspace({ kind: 'sessions', projectId }, (snapshot) => { if (snapshot.kind === 'sessions')
             listener(snapshot); }),
+        onRunningShells: (scope, listener) => subscribeShells(scope, listener),
+        readShellOutput: async (shellId, options) => {
+            requireIdentity(shellId, GUEST_SHELL_ID_MAX);
+            const cursor = options?.cursor;
+            if (cursor !== undefined && (!Number.isInteger(cursor) || cursor < 0)) {
+                throw new HostRequestError('HOST_REJECTED', 'Shell output cursor must be a non-negative integer.');
+            }
+            const tailBytes = options?.tailBytes;
+            if (tailBytes !== undefined && (!Number.isInteger(tailBytes) || tailBytes < 1 || tailBytes > GUEST_SHELL_OUTPUT_TAIL_MAX)) {
+                throw new HostRequestError('HOST_REJECTED', `Shell output tailBytes must be an integer between 1 and ${GUEST_SHELL_OUTPUT_TAIL_MAX}.`);
+            }
+            const result = await send({ ...envelope, type: 'shell-output', id: nextId(ids), payload: { shellId, cursor, tailBytes } });
+            const output = result;
+            if (!output || typeof output.output !== 'string' || !Number.isFinite(output.cursor)) {
+                throw new HostRequestError('HOST_REJECTED', 'Host did not return shell output.');
+            }
+            return output;
+        },
+        stopShell: async (shellId) => {
+            requireIdentity(shellId, GUEST_SHELL_ID_MAX);
+            const result = (await send({ ...envelope, type: 'shell-stop', id: nextId(ids), payload: { shellId } }));
+            if (result?.stopped !== true)
+                throw new HostRequestError('HOST_REJECTED', 'Host did not stop the shell.');
+            return { stopped: true };
+        },
         openSession: async (sessionId) => {
             requireIdentity(sessionId);
             await request({ ...envelope, type: 'open-session', id: nextId(ids), payload: { sessionId } });
@@ -856,6 +911,10 @@ export const connectHost = (options = {}) => {
                 post({ ...envelope, type: 'workspace-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
             }
             workspaceListeners.clear();
+            for (const subscriptionId of shellsListeners.keys()) {
+                post({ ...envelope, type: 'shells-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
+            }
+            shellsListeners.clear();
             disposed = true;
             resolveHandler = null;
             actionHandler = null;

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { GUEST_SCROLLBAR_CSS, GUEST_SCROLLBAR_SCRIPT } from './scrollbar-style.t
 export { guestFramePolicy } from './frame-policy.ts';
 export type { GuestLoadState, GuestProject, GuestWorktree, GuestSessionActivity, GuestSessionRecord, GuestDirectoryCoverage, GuestProjectsSnapshot, GuestWorktreesSnapshot, GuestSessionsSnapshot, GuestWorkspaceSnapshot, GuestWorkspaceQuery, GuestWorkspaceSubscription, GuestWorkspaceUpdate, GuestStorageRequest, GuestStorageResult, GuestStorageOptions, GuestStorageScope, GuestSessionWorktree } from './workspace.ts';
 export { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_VALUE_BYTES, GUEST_STORAGE_TOTAL_BYTES, GUEST_DEVICE_STORAGE_TOTAL_BYTES } from './workspace.ts';
+export type { GuestRunningShell, GuestEndedShell, GuestShellEndStatus, GuestRunningShellsSnapshot, GuestShellsScope, GuestShellsSubscription, GuestShellOutputRequest, GuestShellOutputResult, GuestShellStopResult, } from './shells.ts';
+export { GUEST_SHELL_END_STATUSES, GUEST_SHELL_ID_MAX, GUEST_SHELLS_MAX, GUEST_SHELL_OUTPUT_TAIL_MAX, } from './shells.ts';
 export { GUEST_STATUS_CONTROLS_MAX, GUEST_STATUS_CONTROL_ID, GUEST_STATUS_CONTROL_LABEL_MAX, GUEST_STATUS_CONTROL_OPTIONS_MAX, GUEST_STATUS_CONTROL_VALUE_MAX } from './status-controls.ts';
 export type { GuestStatusControl, GuestStatusControlEvent, GuestStatusControlOption } from './status-controls.ts';
 export type { OpenChamberManifestApiVersion } from './api-version.ts';
@@ -16,7 +18,7 @@ export type { HostClient, HostClientOptions, HostFrame } from './host.ts';
 export { GUEST_POPOVER_COORDINATE_MAX, GUEST_POPOVER_DATA_DEPTH_MAX, GUEST_POPOVER_DATA_MAX, GUEST_POPOVER_HEIGHT_MAX, GUEST_POPOVER_HEIGHT_MIN, GUEST_POPOVER_ID, GUEST_POPOVER_SIDES, GUEST_POPOVER_WIDTH_MAX, GUEST_POPOVER_WIDTH_MIN, GUEST_POPOVER_CLOSE_REASONS, isGuestPopoverRequest, } from './popover.ts';
 export type { GuestPopoverAnchor, GuestPopoverClosedEvent, GuestPopoverContext, GuestPopoverRequest, GuestPopoverSide } from './popover.ts';
 export { clampAttachRequest, clampBadgeCount, clampFrameHeight, isGuestCommitSha, GUEST_COMMIT_SHA, 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, ActionResultPayload, GuestActionItem, GuestActionResultMessage, HostActionMessage, HostFileOpenMessage, HostFileSnapshotMessage, HostFileSavedMessage, GuestFileSnapshotResultMessage, GuestFileChangeMessage, GuestFileSaveMessage, GuestFileUnsupportedMessage, GuestBadgeMessage, GuestResizeMessage, GuestOpenCommitMessage, GuestStatusControlsMessage, GuestPopoverAnchorMessage, GuestPopoverCloseMessage, GuestPopoverOpenMessage, OpenCommitRequest, ResizeRequest, 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, HostStatusControlEventMessage, HostPopoverClosedMessage, HostMessage, HostReadyContext, HostReadyMessage, HostResultMessage, HostSessionLifecycleMessage, HostSessionMessage, HostSettingsMessage, HostTheme, HostThemeMode, HostThemeTokens, SessionSnapshot, ToastKind, ToastRequest, } from './contract.ts';
+export type { BadgeRequest, ActionResultPayload, GuestActionItem, GuestActionResultMessage, HostActionMessage, HostFileOpenMessage, HostFileSnapshotMessage, HostFileSavedMessage, GuestFileSnapshotResultMessage, GuestFileChangeMessage, GuestFileSaveMessage, GuestFileUnsupportedMessage, GuestBadgeMessage, GuestResizeMessage, GuestOpenCommitMessage, GuestStatusControlsMessage, GuestPopoverAnchorMessage, GuestPopoverCloseMessage, GuestPopoverOpenMessage, OpenCommitRequest, ResizeRequest, 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, GuestShellOutputMessage, GuestShellsSubscribeMessage, GuestShellsUnsubscribeMessage, GuestShellStopMessage, GuestAttachMessage, GuestClipboardWriteMessage, GuestCloseMessage, GuestComposeMessage, GuestConnection, GuestHelloMessage, GuestMessage, GuestOauthDisconnectMessage, GuestOauthStartMessage, GuestOpenSurfaceMessage, GuestOpenUrlMessage, GuestRequest, GuestRequestMessage, GuestRequestMethod, GuestPromptMessage, GuestSessionLinkMessage, GuestStartSessionMessage, GuestRequestResult, GuestSettings, GuestToastMessage, GuestHostSurface, HostConnectionMessage, HostDirectoryMessage, HostItemMessage, HostStatusControlEventMessage, HostPopoverClosedMessage, HostMessage, HostReadyContext, HostReadyMessage, HostResultMessage, HostSessionLifecycleMessage, HostSessionMessage, HostSettingsMessage, HostShellsMessage, HostTheme, HostThemeMode, HostThemeTokens, SessionSnapshot, ToastKind, ToastRequest, } from './contract.ts';
 export { EMPTY_GUEST_CONNECTION, GUEST_BADGE_MAX, GUEST_FRAME_HEIGHT_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';
 export { BROWSER_CONTROL_ACTIONS, BROWSER_PROVIDER_ACTION_TIMEOUT_MS, BROWSER_PROVIDER_IDLE_MS, BROWSER_PROVIDER_OPEN_TIMEOUT_MS, BROWSER_PROVIDER_PATH, BROWSER_PROVIDER_RESPONSE_MAX, BROWSER_SCROLL_DIRECTIONS, BROWSER_VIEWPORT_MODES, isBrowserControlAction, readBrowserProviderRequest, } from './service-providers.ts';
 export type { BrowserCaptureData, BrowserCaptureParameters, BrowserClickData, BrowserClickParameters, BrowserConsoleProblem, BrowserControlAction, BrowserElementBounds, BrowserInspectData, BrowserInspectParameters, BrowserNavigationData, BrowserOpenData, BrowserOpenParameters, BrowserProviderContext, BrowserProviderData, BrowserProviderRequest, BrowserProviderResult, BrowserResizeData, BrowserResizeParameters, BrowserScrollData, BrowserScrollDirection, BrowserScrollParameters, BrowserSnapshotData, BrowserSnapshotElement, BrowserSnapshotParameters, BrowserTab, BrowserTabTarget, BrowserTypeData, BrowserTypeParameters, BrowserViewportMode, BrowserViewportSummary, } from './service-providers.ts';

package/dist/index.js

@@ -2,6 +2,7 @@ export { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL, OPENCHAMBER_SDK_M
 export { GUEST_SCROLLBAR_CSS, GUEST_SCROLLBAR_SCRIPT } from "./scrollbar-style.js";
 export { guestFramePolicy } from "./frame-policy.js";
 export { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_VALUE_BYTES, GUEST_STORAGE_TOTAL_BYTES, GUEST_DEVICE_STORAGE_TOTAL_BYTES } from "./workspace.js";
+export { GUEST_SHELL_END_STATUSES, GUEST_SHELL_ID_MAX, GUEST_SHELLS_MAX, GUEST_SHELL_OUTPUT_TAIL_MAX, } from "./shells.js";
 export { GUEST_STATUS_CONTROLS_MAX, GUEST_STATUS_CONTROL_ID, GUEST_STATUS_CONTROL_LABEL_MAX, GUEST_STATUS_CONTROL_OPTIONS_MAX, GUEST_STATUS_CONTROL_VALUE_MAX } from "./status-controls.js";
 export { compareOpenChamberVersions, hostMeetsOpenChamberEngine, openChamberEngineMinimum, OPENCHAMBER_ENGINE_PATTERN, parseOpenChamberVersion, } from "./host-version.js";
 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, GUEST_ORIGINS_MAX, GUEST_SERVICE_PROVIDES, GUEST_SURFACE_DOCKS, GUEST_SURFACE_DOCK_DEFAULT, GUEST_SURFACE_DOCK_SIZE_DEFAULT, GUEST_SURFACE_DOCK_SIZE_MAX, GUEST_SURFACE_DOCK_SIZE_MIN, GUEST_STATUS_SECTION_HEIGHT_DEFAULT, GUEST_STATUS_SECTION_HEIGHT_MAX, GUEST_STATUS_SECTION_HEIGHT_MIN, GUEST_STATUS_SECTION_TITLE_MAX, clampStatusSectionHeight, HOST_LINEAR_API_ORIGIN, isGuestFilesystemPattern, hasGuestCapability, hasGuestPage, isGuestApproved, isGuestPackageSvgIcon, requestedGuestCapabilities, resolveAttachEntry, resolvePageEntry, resolveStatusSectionEntry, resolveAttachMode, resolveIntegrationApi, resolveIntegrationAuth, serviceProvides, toPublicService, toPublicIntegration, } from "./manifest.js";

package/dist/manifest.d.ts

@@ -273,15 +273,15 @@ export declare const serviceProvides: (service: Pick<ServiceContribution, "provi
 /**
  * What a guest may do beyond drawing its own panel. The user approves the
  * full list once, when the package is installed; a later package that asks
- * for more is re-approved. `prompt`, `sessions`, `files`, and `model` are
- * declared under `contributes.capabilities`; `service`, `network`,
+ * for more is re-approved. `prompt`, `sessions`, `files`, `model`, and
+ * `shells` are declared under `contributes.capabilities`; `service`, `network`,
  * `filesystem` and `origins` follow from `contributes.service`,
  * `contributes.integration`, `contributes.filesystem` and `contributes.origins`. `model` is one-off text generation with the
  * user's Small Model (`host.generate`), outside any session.
  */
-export declare const GUEST_CAPABILITIES: readonly ["prompt", "sessions", "files", "model", "conversation", "service", "network", "filesystem", "origins"];
+export declare const GUEST_CAPABILITIES: readonly ["prompt", "sessions", "files", "model", "shells", "conversation", "service", "network", "filesystem", "origins"];
 export type GuestCapability = (typeof GUEST_CAPABILITIES)[number];
-export declare const DECLARED_GUEST_CAPABILITIES: readonly ["prompt", "sessions", "files", "model"];
+export declare const DECLARED_GUEST_CAPABILITIES: readonly ["prompt", "sessions", "files", "model", "shells"];
 /** The capabilities a manifest may ask for directly. */
 export type DeclaredGuestCapability = (typeof DECLARED_GUEST_CAPABILITIES)[number];
 /** How many `contributes.origins` a package may declare. */

package/dist/manifest.js

@@ -96,14 +96,14 @@ export const serviceProvides = (service, role) => Boolean(service?.provides?.inc
 /**
  * What a guest may do beyond drawing its own panel. The user approves the
  * full list once, when the package is installed; a later package that asks
- * for more is re-approved. `prompt`, `sessions`, `files`, and `model` are
- * declared under `contributes.capabilities`; `service`, `network`,
+ * for more is re-approved. `prompt`, `sessions`, `files`, `model`, and
+ * `shells` are declared under `contributes.capabilities`; `service`, `network`,
  * `filesystem` and `origins` follow from `contributes.service`,
  * `contributes.integration`, `contributes.filesystem` and `contributes.origins`. `model` is one-off text generation with the
  * user's Small Model (`host.generate`), outside any session.
  */
-export const GUEST_CAPABILITIES = ['prompt', 'sessions', 'files', 'model', 'conversation', 'service', 'network', 'filesystem', 'origins'];
-export const DECLARED_GUEST_CAPABILITIES = ['prompt', 'sessions', 'files', 'model'];
+export const GUEST_CAPABILITIES = ['prompt', 'sessions', 'files', 'model', 'shells', 'conversation', 'service', 'network', 'filesystem', 'origins'];
+export const DECLARED_GUEST_CAPABILITIES = ['prompt', 'sessions', 'files', 'model', 'shells'];
 /** How many `contributes.origins` a package may declare. */
 export const GUEST_ORIGINS_MAX = 8;
 /** How many `contributes.filesystem` patterns a package may declare. */

package/dist/parse.d.ts

@@ -44,6 +44,7 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             requiresProject: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>]>>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            shells: "shells";
             sessions: "sessions";
             prompt: "prompt";
             files: "files";
@@ -123,8 +124,8 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             label: z.ZodString;
             icon: z.ZodOptional<z.ZodString>;
             where: z.ZodEnum<{
-                message: "message";
                 session: "session";
+                message: "message";
             }>;
             mode: z.ZodOptional<z.ZodEnum<{
                 background: "background";
@@ -218,6 +219,7 @@ export declare const packageManifestSchema: z.ZodObject<{
                 requiresProject: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>]>>;
             capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                shells: "shells";
                 sessions: "sessions";
                 prompt: "prompt";
                 files: "files";
@@ -297,8 +299,8 @@ export declare const packageManifestSchema: z.ZodObject<{
                 label: z.ZodString;
                 icon: z.ZodOptional<z.ZodString>;
                 where: z.ZodEnum<{
-                    message: "message";
                     session: "session";
+                    message: "message";
                 }>;
                 mode: z.ZodOptional<z.ZodEnum<{
                     background: "background";

package/dist/protocol.d.ts

@@ -92,6 +92,48 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strip>;
     channel: z.ZodLiteral<"openchamber.sdk">;
     v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shells">;
+    payload: z.ZodObject<{
+        subscriptionId: z.ZodString;
+        snapshot: z.ZodObject<{
+            kind: z.ZodLiteral<"shells">;
+            scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"session">;
+                sessionId: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"project">;
+                projectId: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"global">;
+            }, z.core.$strict>], "kind">;
+            shells: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                sessionID: z.ZodString;
+                command: z.ZodString;
+                startedAt: z.ZodNumber;
+                background: z.ZodBoolean;
+            }, z.core.$strict>>;
+            ended: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                sessionID: z.ZodString;
+                command: z.ZodString;
+                startedAt: z.ZodNumber;
+                background: z.ZodBoolean;
+                status: z.ZodEnum<{
+                    exited: "exited";
+                    timeout: "timeout";
+                    killed: "killed";
+                    stopped: "stopped";
+                    unknown: "unknown";
+                }>;
+                exit: z.ZodOptional<z.ZodNumber>;
+                endedAt: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strip>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"ready">;
     payload: z.ZodObject<{
@@ -459,7 +501,13 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
                 data: z.ZodOptional<z.ZodJSONSchema>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
-    }, z.core.$strip>], "kind">, z.ZodUnion<readonly [z.ZodObject<{
+    }, z.core.$strip>], "kind">, z.ZodObject<{
+        output: z.ZodString;
+        cursor: z.ZodNumber;
+        skipped: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodObject<{
+        stopped: z.ZodLiteral<true>;
+    }, z.core.$strip>, z.ZodUnion<readonly [z.ZodObject<{
         sessionId: z.ZodString;
         sent: z.ZodEnum<{
             failed: "failed";
@@ -511,9 +559,9 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
         }>;
     }, z.core.$strip>, z.ZodObject<{
         status: z.ZodEnum<{
+            stopped: "stopped";
             ready: "ready";
             failed: "failed";
-            stopped: "stopped";
             starting: "starting";
         }>;
     }, z.core.$strip>, z.ZodObject<{
@@ -641,7 +689,7 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
     } | {
         sent: "failed" | "sent" | "no-model" | "skipped";
     } | {
-        status: "ready" | "failed" | "stopped" | "starting";
+        status: "stopped" | "ready" | "failed" | "starting";
     } | {
         content: string;
     } | {
@@ -657,6 +705,12 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
         mtime: number;
     } | {
         text: string;
+    } | {
+        output: string;
+        cursor: number;
+        skipped: boolean;
+    } | {
+        stopped: true;
     };
     error?: undefined;
     code?: undefined;
@@ -778,7 +832,7 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
     } | {
         sent: "failed" | "sent" | "no-model" | "skipped";
     } | {
-        status: "ready" | "failed" | "stopped" | "starting";
+        status: "stopped" | "ready" | "failed" | "starting";
     } | {
         content: string;
     } | {
@@ -794,6 +848,12 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
         mtime: number;
     } | {
         text: string;
+    } | {
+        output: string;
+        cursor: number;
+        skipped: boolean;
+    } | {
+        stopped: true;
     } | undefined;
 }>>, z.ZodObject<{
     type: z.ZodLiteral<"action">;
@@ -915,6 +975,49 @@ export declare const guestMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>;
     channel: z.ZodLiteral<"openchamber.sdk">;
     v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shells-subscribe">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        subscriptionId: z.ZodString;
+        scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"session">;
+            sessionId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"project">;
+            projectId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"global">;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shells-unsubscribe">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        subscriptionId: z.ZodString;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shell-output">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        shellId: z.ZodString;
+        cursor: z.ZodOptional<z.ZodNumber>;
+        tailBytes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shell-stop">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        shellId: z.ZodString;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"storage">;
     id: z.ZodString;

package/dist/protocol.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { guestSessionWorktreeSchema, guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceQuerySchema, guestWorkspaceSnapshotSchema } from "./workspace-schemas.js";
 import { guestStatusControlEventSchema, guestStatusControlsSchema } from "./status-control-schemas.js";
 import { guestPopoverClosedEventSchema, guestPopoverDataSchema, guestPopoverRequestSchema } from "./popover-schemas.js";
+import { GUEST_SHELL_END_STATUSES, GUEST_SHELL_ID_MAX, GUEST_SHELLS_MAX, GUEST_SHELL_OUTPUT_TAIL_MAX } from "./shells.js";
 import { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL } from "./api-version.js";
 import { SERVICE_STATUS_VALUES, ATTACH_PROVIDER_ID, GUEST_ACCOUNT_MAX, GUEST_ATTACH_AUTHOR_MAX, GUEST_BADGE_MAX, GUEST_FRAME_HEIGHT_MAX, GUEST_COMMIT_SHA, GUEST_ITEM_MESSAGE_TEXT_MAX, GUEST_ITEM_SESSION_MAX, GUEST_RESOLVE_ERROR_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_COMPOSE_TEXT_MAX, GUEST_FILE_CONTENT_MAX, GUEST_FILE_ENTRY_KINDS, GUEST_FILE_LIST_MAX, GUEST_GENERATE_OUTPUT_TOKENS_MAX, GUEST_GENERATE_PROMPT_MAX, GUEST_GENERATE_SYSTEM_MAX, GUEST_GENERATE_TEXT_MAX, GUEST_FILE_PATH_MAX, GUEST_FILE_STAT_KINDS, GUEST_REQUEST_BODY_MAX, GUEST_REQUEST_PATH_MAX, GUEST_REQUEST_RESPONSE_MAX, GUEST_SESSION_AGENT_MAX, GUEST_SESSION_MODEL_MAX, GUEST_SETTING_VALUE_MAX, GUEST_TOAST_MAX, SESSION_LIFECYCLE_PHASES, SETTING_KEY, START_SESSION_SENT, isGuestFilePath, isGuestRequestPath, resolveHostRequestErrorCode, } from "./contract.js";
 import { GUEST_FILE_EDITOR_CONTENT_MAX, GUEST_FILE_EDITOR_VERSION_MAX } from "./file-editor.js";
@@ -98,9 +99,19 @@ const fileStatResultPayloadSchema = z.object({
 const generateResultPayloadSchema = z.object({
     text: z.string().max(GUEST_GENERATE_TEXT_MAX),
 });
+const shellOutputResultPayloadSchema = z.object({
+    output: z.string(),
+    cursor: z.number(),
+    skipped: z.boolean(),
+});
+const shellStopResultPayloadSchema = z.object({
+    stopped: z.literal(true),
+});
 const hostResultPayloadSchema = z.union([
     guestStorageResultSchema,
     guestWorkspaceSnapshotSchema,
+    shellOutputResultPayloadSchema,
+    shellStopResultPayloadSchema,
     startSessionResultPayloadSchema,
     requestResultPayloadSchema,
     promptResultPayloadSchema,
@@ -214,8 +225,36 @@ const hostResultSchema = z.object({
         code: resolveHostRequestErrorCode(message.code),
     };
 });
+const guestRunningShellSchema = z.object({
+    id: z.string().min(1).max(GUEST_SHELL_ID_MAX),
+    sessionID: z.string().min(1).max(1024),
+    command: z.string(),
+    startedAt: z.number().nonnegative(),
+    background: z.boolean(),
+}).strict();
+const guestEndedShellSchema = guestRunningShellSchema.extend({
+    status: z.enum(GUEST_SHELL_END_STATUSES),
+    exit: z.number().int().optional(),
+    endedAt: z.number().nonnegative(),
+}).strict();
+const guestShellsScopeSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('session'), sessionId: z.string().min(1).max(1024) }).strict(),
+    z.object({ kind: z.literal('project'), projectId: z.string().min(1).max(1024) }).strict(),
+    z.object({ kind: z.literal('global') }).strict(),
+]);
+const guestRunningShellsSnapshotSchema = z.object({
+    kind: z.literal('shells'),
+    scope: guestShellsScopeSchema,
+    shells: z.array(guestRunningShellSchema).max(GUEST_SHELLS_MAX),
+    ended: z.array(guestEndedShellSchema).max(GUEST_SHELLS_MAX),
+}).strict();
 export const hostMessageSchema = z.union([
     z.object({ ...envelope, type: z.literal('workspace'), payload: z.object({ subscriptionId: z.string().min(1).max(128), snapshot: guestWorkspaceSnapshotSchema }) }),
+    z.object({
+        ...envelope,
+        type: z.literal('shells'),
+        payload: z.object({ subscriptionId: z.string().min(1).max(128), snapshot: guestRunningShellsSnapshotSchema }),
+    }),
     z.object({
         ...envelope,
         type: z.literal('ready'),
@@ -332,6 +371,10 @@ export const guestMessageSchema = z.discriminatedUnion('type', [
     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) }) }),
+    z.object({ ...envelope, type: z.literal('shells-subscribe'), id: z.string().min(1), payload: z.object({ subscriptionId: z.string().min(1).max(128), scope: guestShellsScopeSchema }).strict() }),
+    z.object({ ...envelope, type: z.literal('shells-unsubscribe'), id: z.string().min(1), payload: z.object({ subscriptionId: z.string().min(1).max(128) }).strict() }),
+    z.object({ ...envelope, type: z.literal('shell-output'), id: z.string().min(1), payload: z.object({ shellId: z.string().min(1).max(GUEST_SHELL_ID_MAX), cursor: z.number().int().nonnegative().optional(), tailBytes: z.number().int().positive().max(GUEST_SHELL_OUTPUT_TAIL_MAX).optional() }).strict() }),
+    z.object({ ...envelope, type: z.literal('shell-stop'), id: z.string().min(1), payload: z.object({ shellId: z.string().min(1).max(GUEST_SHELL_ID_MAX) }).strict() }),
     z.object({ ...envelope, type: z.literal('storage'), id: z.string().min(1), payload: guestStorageRequestSchema }),
     z.object({
         ...envelope,

package/dist/shells.d.ts

@@ -0,0 +1,69 @@
+export declare const GUEST_SHELL_ID_MAX = 128;
+export declare const GUEST_SHELLS_MAX = 200;
+export declare const GUEST_SHELL_OUTPUT_TAIL_MAX = 65536;
+/** A shell command still running on behalf of a session. */
+export type GuestRunningShell = {
+    id: string;
+    sessionID: string;
+    command: string;
+    startedAt: number;
+    /** True for a job the turn does not wait for; false while the turn that ran it is blocked on it. */
+    background: boolean;
+};
+export declare const GUEST_SHELL_END_STATUSES: readonly ["exited", "timeout", "killed", "stopped", "unknown"];
+/**
+ * How a shell command ended: `exited` on its own (see `exit`), `timeout`,
+ * `killed` by a signal, `stopped` by a user (Stop, or aborting the turn that
+ * waited on it), or `unknown` when
+ * OpenChamber missed the end (a reconnect) and only saw the command gone.
+ */
+export type GuestShellEndStatus = (typeof GUEST_SHELL_END_STATUSES)[number];
+/** A shell command OpenChamber saw running that has since ended. */
+export type GuestEndedShell = GuestRunningShell & {
+    status: GuestShellEndStatus;
+    /** Exit code, when the command exited and OpenCode reported one. */
+    exit?: number;
+    endedAt: number;
+};
+/**
+ * Which running shells a subscription covers: one session and its subagents,
+ * every session of a registered project, or every session the app sees.
+ */
+export type GuestShellsScope = {
+    kind: 'session';
+    sessionId: string;
+} | {
+    kind: 'project';
+    projectId: string;
+} | {
+    kind: 'global';
+};
+export type GuestRunningShellsSnapshot = {
+    kind: 'shells';
+    /** Echo of the scope the subscription asked for. */
+    scope: GuestShellsScope;
+    shells: GuestRunningShell[];
+    /**
+     * Commands in scope that ended since OpenChamber started watching, oldest
+     * end first. Kept in memory only: empty after an app reload or runtime
+     * switch, and capped at `GUEST_SHELLS_MAX`, newest kept.
+     */
+    ended: GuestEndedShell[];
+};
+export type GuestShellsSubscription = {
+    subscriptionId: string;
+    scope: GuestShellsScope;
+};
+export type GuestShellOutputRequest = {
+    shellId: string;
+    cursor?: number;
+    tailBytes?: number;
+};
+export type GuestShellOutputResult = {
+    output: string;
+    cursor: number;
+    skipped: boolean;
+};
+export type GuestShellStopResult = {
+    stopped: true;
+};

package/dist/shells.js

@@ -0,0 +1,4 @@
+export const GUEST_SHELL_ID_MAX = 128;
+export const GUEST_SHELLS_MAX = 200;
+export const GUEST_SHELL_OUTPUT_TAIL_MAX = 65536;
+export const GUEST_SHELL_END_STATUSES = ['exited', 'timeout', 'killed', 'stopped', 'unknown'];

package/package.json

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