@openchamber/sdk 2.0.2 → 2.0.4

package/API.md

@@ -74,6 +74,9 @@ Each returns an unsubscribe function. Late subscribers get the last known value
 | `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 |
+| `onFileOpen(listener)` | `FileEditorDocument` | File editors only: `{ path, name, readOnly, encoding: 'text', content }` or `{ ..., encoding: 'binary', bytes }` (a `Uint8Array`) of the file this frame edits. Replays the last file; the same file pushed again is not repeated. Registering also sends Cmd/Ctrl+S inside the frame to the host's save |
+| `onFileSnapshot(handler)` | `'save' \| 'handoff'` → `FileEditorSnapshot \| Promise<FileEditorSnapshot>` | File editors only: return the whole edited file (`{ content, version }` for a text editor, `{ bytes, version }` for a binary one) and a version of the state it came from. `save` writes it; `handoff` moves it into the host's source view. Throwing fails that save. One handler at a time |
+| `onFileSaved(listener)` | `version: string` | File editors only: the snapshot with that version is on disk. Answer with `reportFileChange({ dirty, edited: false })` so edits made during the write stay unsaved |
 
 
 `HostReadyContext`
@@ -86,7 +89,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' \| 'page' \| 'background'` | Where the host mounted this frame |
+| `surface` | `'panel' \| 'dialog' \| 'page' \| 'background' \| 'status' \| 'file'` | 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` |
@@ -154,6 +157,9 @@ Access tokens never appear in `ready` or in request results.
 | `openCommit`      | `sha: string`                     | `Promise<void>`                | Show that commit of the open project in the host's Diff view (commit scope). 7–64 hex characters; the host reads the commit itself. `NO_DIRECTORY` without a project, `NOT_FOUND` for an unknown commit, `UNSUPPORTED` where the host has no Diff view |
 | `setHeight`       | `height: number`                  | `Promise<void>`                | Content height in CSS px. The Work Status section sizes its frame to it, clamped to 24–320; taller content scrolls inside. A page docked to a shared surface grows or shrinks its dock to it (a width for a `left`/`right` dock), from 24 px up to half the panel. Other surfaces ignore it |
 | `generate`        | `{ prompt, system?, maxOutputTokens? }` | `Promise<{ text }>`      | One-off text from the user's Small Model (capability `model`). No session, no history; the host picks the model. Waits up to 90 s |
+| `reportFileChange` | `{ dirty, edited }`              | `void`                         | File editors only. `dirty` against the last saved version; `edited` when the document itself changed, which holds autosave back until edits stop |
+| `requestFileSave` | —                                 | `void`                         | File editors only. Save now, as Cmd/Ctrl+S does |
+| `reportFileUnsupported` | —                           | `void`                         | File editors only. This file cannot be opened here; the host shows its source and a notice |
 | `dispose`         | —                                 | `void`                         | Remove listener, reject pending RPCs                                                  |
 
 
@@ -217,6 +223,12 @@ Storage belongs to the extension on the connected server and needs no extra capa
 
 `contributes.statusSection: true` reuses `panel.entry`; `{ entry: 'status/index.html', title?: 'Recent commits', height?: 160 }` uses separate package HTML (`.html`, inside the package, built scripts checked at install). The object form needs no `panel.entry`, so an extension can ship only a section and no rail icon. `title` is 1 to 60 characters and replaces `panel.name` on the section header; the icon is `panel.icon`. `height` (24 to 320, default 120) is the frame height before your page calls `setHeight`. The section appears in the chat's Work Status panel and in its section chooser, where the user can hide it or move it. `ctx.surface` is `status`. The frame runs only while the panel is shown and the section is expanded, so keep no state in it that you cannot rebuild. It gets the same sandbox, directory, session, theme, grants, and service as a panel. A status-only package may declare `capabilities`, `service`, `integration`, and `filesystem`; `page`, `attach`, `actions`, and `commands` still need `panel.entry` or `background.entry`. Web and desktop only.
 
+### File editors
+
+`contributes.fileEditors` lists up to 8 editors: `{ id: 'canvas', title: 'Excalidraw', match: ['*.excalidraw', '*.excalidraw.md'], entry: 'editor/index.html' }`. `match` holds 1 to 16 file-name patterns, compared case-insensitively with the name only (no `/`); `*` is any run of characters, `?` one, and a pattern must have at least one character that is not a wildcard. `entry` is package `.html` with built scripts, checked at install. `content` is `"text"` (the default) or `"binary"`: a text editor claims only text files and gets the text with `\n` line endings (the host restores the file's own on write); a binary editor claims any matching file, gets its bytes as a `Uint8Array`, returns bytes, and has no source view, and the host saves its unsaved changes before it moves to or from fullscreen. When the user opens a matching file in Files, the viewer loads your page instead of its own preview; the first enabled, approved extension in the list wins, ahead of the built-in viewers. `ctx.surface` is `file`.
+
+The host keeps the file. It hands you the text (`onFileOpen`), asks for the edited text when it saves or when the user switches to the source view or fullscreen (`onFileSnapshot`), and tells you which snapshot reached the disk (`onFileSaved`). Saving, autosave, the unsaved-changes prompt, line endings, and external changes are the host's. Your page never reads or writes the file and needs no `files` capability for it. Report every change with `reportFileChange`; `createFileSaveTracker(version)` does the dirty bookkeeping. A file you cannot open goes back with `reportFileUnsupported`. Files over 20 000 000 characters (text) or bytes (binary) stay with the host's own view, and a snapshot over that is refused. An editor that hands back the wrong kind (text from a binary editor or bytes from a text one) fails the save. The page is reloaded, with the file handed over again, when the file changes on disk, the user discards changes, or the editor moves to or from fullscreen. A file-editor-only package may declare `capabilities`, `service`, `integration`, and `filesystem`; `page`, `attach`, `actions`, and `commands` still need `panel.entry` or `background.entry`. Web and desktop only; `examples/checklist-editor` is a complete editor.
+
 `sent` **values** (`startSession` / `prompt`): `sent` | `no-model` | `skipped` | `failed`. After `no-model` / `failed` on `startSession`, the session still exists.
 
 **File path rules** (`readFile` / `writeFile` / `listDir` / `stat`): a relative path (`README.md`, `src/x.ts`, `.`) is joined to the project that is open when the call runs and needs the `files` capability; no open project is `NO_DIRECTORY`. A path starting with `/` or `~/` is outside the project, must match one of the package's `contributes.filesystem` globs, and needs the `filesystem` capability. Any `..` segment, a backslash, or a symlink that leads out of the allowed tree is `BAD_PATH`. The host compares canonical (realpath) paths, so `/tmp/x` on macOS is checked as `/private/tmp/x` and a pattern's literal prefix is canonicalized the same way. Content over 2 000 000 characters is `FILE_TOO_LARGE` in both directions; an OS permission refusal is `DENIED`.
@@ -440,6 +452,7 @@ Used by the OpenChamber host and by tools that validate packages. Guests rarely
 | `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 |
+| `fileEditors`         | Optional, 1–8 editors: unique kebab-case `id`, `title` 1–60 chars, `match` 1–16 file-name patterns (no `/`, not only wildcards), `entry` package `.html` with built scripts, optional `content` `"text"` (default) or `"binary"` (`invalid-file-editors`). See File editors above |
 | `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 |
 | `integration`         | Optional. Exactly one of `oauth`, `token`, or `host` (`provider: "linear"` only)                                                                                                     |
 | `service`               | Optional. `entry` must be a built `.js` file on disk. `provides: ["browser"]` makes it the agent's browser when the user selects it; `surface: true` gives it a host-drawn live panel the user can take over (no `panel.entry` then). Neither needs a panel or background entry. See [GUEST_SERVICES.md](https://github.com/openchamber/openchamber/blob/main/packages/sdk/GUEST_SERVICES.md) |
@@ -525,6 +538,9 @@ Frozen on `apiVersion` 1 — named in docs, no host hole yet:
 - Keyboard shortcuts, raw git remotes, magic prompts
 - Second `host.provider` beyond Linear
 - Arbitrary filesystem access from the page (only the open project with `files`, or declared `contributes.filesystem` globs), terminal, pairing, or host React components. A declared `service` is outside these limits: it is a process with the user's rights and no sandbox
+- Network access from the page. Pages run under a Content Security Policy: scripts, styles, images, fonts, media and workers come from the package itself or `data:`/`blob:`, and `fetch` reaches only the package's own files. Ship fonts and images inside the package. To talk to an outside service, use `request` (the integration's `apiOrigin`) or declare up to 8 https origins in `contributes.origins`, for example `"origins": ["https://fonts.example.com"]`. The user approves that list at install, and again when an update adds to it. Approved origins are open to `fetch`, images, fonts, styles and media, never to scripts or workers. A `fetch` whose response you read also needs that server to allow CORS for the `null` origin, since the page's origin is opaque
+
+A navigation of the page itself to another address is refused in the desktop app; don't rely on it anywhere.
 
 Do not go around the guest contract through `RuntimeAPIs`.
 

package/DOCUMENTATION.md

@@ -15,6 +15,7 @@ Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`
 - `src/host.ts`: iframe client. Posts to `parent`. Ignores messages whose `source` is not `parent`. In-flight RPCs time out at `GUEST_REQUEST_TIMEOUT_MS` (20s) as `HOST_TIMEOUT`. `onDirectory` / `onSession` / `onSessionLifecycle` / `onItem` replay and stay current after later pushes, same as connection and settings. `onResolve` holds one handler for host `resolve` requests and answers each with `resolve-result` (the clamped chip, `null`, or the thrown error's message; no handler answers with an error). `setBadge` posts `badge` with the count clamped to 0..`GUEST_BADGE_MAX`.
 - `scripts/bundle-guest.ts`: official IIFE build, exposed as the `openchamber-guest-bundle` bin. Run `bunx openchamber-guest-bundle panel/main.ts panel/main.js` from the guest folder; paths resolve against the current directory. Needs Bun. Any bundler with an IIFE target is an equivalent substitute.
 - `dist/`: the published output (`bun run --cwd packages/sdk build`, `tsc -p tsconfig.build.json`). `package.json` `exports` point here so Node loads the SDK from `node_modules` (packaged Electron, `openchamber serve`). Inside the monorepo, Vite aliases and tsconfig `paths` resolve `@openchamber/sdk` to `src/` so builds and type-checks never depend on a stale `dist`. The server under Bun and Node uses `dist`; the root `postinstall` builds it. The package ships to npm from the release workflow with `bun publish`, right before `@openchamber/web`; `scripts/bump-version.mjs` bumps it with the app, so the SDK version always equals the OpenChamber version it was released with.
+- `src/file-editor.ts`: the `contributes.fileEditors` contract: limits, file-name pattern check and match, the document/snapshot/change types, and `createFileSaveTracker`. Zod-free, so a guest editor bundles it.
 - `GUEST_SERVICES.md`: local service contract (`contributes.service`, `serviceRequest`, grant, loopback).
 - `src/service-providers.ts`: contracts a service fulfils for a host role (`contributes.service.provides`). Today only `browser`: the ten `browser.*` actions, their parameter and answer types, the limits, `BrowserProviderContext` (the calling project and chat, filled by the host from the tool call; `null` fields mean unknown), and `readBrowserProviderRequest` (a zod-free boundary parse for the service side). `src/service-provider-schemas.ts` is the host's zod parse of the answer, exported from `@openchamber/sdk/schemas`. A providing service needs no panel or background entry (`runtimeContributions` in `parse.ts`). The host side is `packages/web/server/lib/browser-control/provider.js`.
 - `src/service-surface.ts`: the shared-surface contract (`contributes.service.surface`): loopback paths and headers, input event types, limits, and the zod-free `readSurfaceInputBatch` / `readSurfaceControlNotice` / `readSurfaceResizeRequest` for the service side. `src/service-surface-schemas.ts` (host entry) holds the viewer↔host socket messages (`surfaceViewerMessageSchema`, `surfaceHostMessageSchema`) shared by `packages/ui/src/lib/guests/surface-client.ts` and `packages/web/server/lib/guests/surface.js`, plus the service answer schemas. A surface service needs no entry of its own; with `panel.entry` that page is docked to one edge of the picture, `panel.dock` (`GUEST_SURFACE_DOCKS`) and `panel.size` px (`GUEST_SURFACE_DOCK_SIZE_*`), only valid with both. The rail panel is `packages/ui/src/components/layout/GuestSurfacePane.tsx` (host-drawn canvas, not an iframe); `ContextPanel` lays the page iframe (kept mounted) beside the pane (mounted only while shown) per `DOCK_LAYOUT`, and `lib/guests/surfaces.ts#guestSurfaceDocking` decides. Viewer identity is host-set: input carries `x-surface-viewer` and `x-surface-frame-seq` (the service's own number of the frame that viewer last drew; a 409 refuses it as stale), control notices carry `viewer`, and page `serviceRequest`s from a window with a live viewer (`packages/ui/src/lib/guests/surface-viewers.ts`) also carry `x-surface-viewer-controls`.
@@ -29,6 +30,7 @@ Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`
 - `contributes.statusSection` is `true` or `{ entry, title?, height? }` (`StatusSectionContribution`). `true` reuses `panel.entry` and fails as `invalid-status-section` without one; the object form's `entry` is package-local `.html`, `title` 1 to `GUEST_STATUS_SECTION_TITLE_MAX` (60), `height` `GUEST_STATUS_SECTION_HEIGHT_MIN`..`MAX` (24..320). `resolveStatusSectionEntry` resolves shorthand. The object form is a frame of its own: without `panel.entry` or `background.entry` it permits `capabilities`, `service`, `integration`, and `filesystem`, and refuses `page`, `attach`, `actions`, and `commands` as `invalid-panel`, because those are opened or invoked elsewhere. The server validates the HTML/scripts, exposes `statusEntry`/`statusTitle`/`statusHeight`, and counts `statusEntry` as a runtime entry for serving and storage. The host mounts `PluginPane surface="status"` inside the Work Status panel (`components/chat/work-status/WorkStatusExtensionSection.tsx`, see that folder's `DOCUMENTATION.md`): the same sandbox, guest-scoped token, context, grants, approval, and pause gates as a panel. Guest `resize` (`host.setHeight`, `ResizeRequest { height }`, integer 0..`GUEST_FRAME_HEIGHT_MAX`) is a request answered with an empty result on every surface; only `status` sizes its frame from it, through `clampStatusSectionHeight`, and a page docked to a shared surface sizes its dock from it (`DockedGuestPage` in `ContextPanel`: thickness across the dock edge, at least `GUEST_SURFACE_DOCK_SIZE_MIN`, at most half the panel through CSS). Each frame's `setHeight` reaches only its own pane. A status frame never registers a command resolver, clears a badge, or closes rail tabs.
 - `openCommit(sha)` posts `open-commit { sha }`. `sha` is 7 to 64 hex characters (`GUEST_COMMIT_SHA`); the client refuses anything else as `HOST_REJECTED` before posting and the host schema drops it. The host (`lib/guests/open-commit.ts`) reads the commit itself with `git.getGitLog(directory, { maxCount: 1, to: sha })` in the frame's current directory, checks the returned hash starts with the requested one (`NOT_FOUND` otherwise), selects it in `useCommitSelectionStore` under the Diff view's key (directory, current branch, git runtime key), and opens the context panel's Diff tab in `commit` scope. No project is `NO_DIRECTORY`. VS Code and mobile answer `UNSUPPORTED` explicitly; they load no guests today, so this is the contract for when they do. No capability is needed: it only shows the user their own history.
 - Scrollbars in guest documents follow the app's overlay behavior: hidden at rest, shown on hover and for one second after the element last scrolled. `GUEST_SCROLLBAR_CSS` does the hiding and hover; `installGuestScrollbarActivity` (one capturing passive `scroll` listener per document) marks the scrolling element with `data-oc-scrolling`. The server appends both to every served guest HTML as `GUEST_SCROLLBAR_SCRIPT` (the function's own source), so already installed bundles get it without a rebuild; the UI kit installs it too for previews. An authored CSP that blocks inline scripts keeps the hover-only behavior. Forced-colors mode keeps system colors.
+- `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.
 - `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.
@@ -47,9 +49,9 @@ Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`
 - `contributes.commands` is 1 to 8 entries (`GUEST_COMMANDS_MAX`) with a unique `name` matching `GUEST_COMMAND_NAME` (`/^[a-z][a-z0-9-]{0,23}$/`) and an optional `description` of 1 to `GUEST_COMMAND_DESCRIPTION_MAX` (80) characters; else `invalid-commands`. The host owns collisions: a name the composer already has (built-in, OpenCode command, skill, or an earlier guest) is dropped with a console warning. The public catalog row carries `commands` as declared.
 - `contributes.tools` is 1 to 16 entries (`GUEST_TOOLS_MAX`) that say how the extension's tool calls look in the chat, without code. `match` is the full tool name as OpenCode reports it, un-normalized (`mcp.jira.search`, `jira_search`), 1 to `GUEST_TOOL_MATCH_MAX` (128) characters of `[A-Za-z0-9_.:-]`, with one `*` allowed at the end as a suffix wildcard (`mcp.jira.*`; `*` alone is refused). Optional `name` (1 to `GUEST_TOOL_NAME_MAX`, 40) is the header title when `title` is absent or renders empty; `icon` is a Remixicon name or a package `.svg` path with the `panel.icon` rules (the chat draws the SVG as a `currentColor` mask at the glyph size through `resolveGuestToolIcon`, fetched as an authenticated asset under `/api/guests/<id>/<path>`; a Remixicon the sprite lacks leaves the host's own tool icon); `title` and `subtitle` are templates of up to `GUEST_TOOL_TEMPLATE_MAX` (200) characters with `{input.path}`, `{output.path}`, and `{metadata.path}` placeholders (dotted paths, array indexes allowed; a missing path is an empty string; a value is stringified and cut at `GUEST_TOOL_TEMPLATE_VALUE_MAX`, 200). `output` is `auto` (the host's own detection, the default), `text`, `json` (the JSON summary/tree/raw views), `markdown` (the assistant markdown renderer), `code` with `language` (1 to 32), or `table` with `columns` (1 to 16 dotted paths; rows are the output array or `output.items`). `language` outside `code` and `columns` outside `table` (or a `table` without `columns`) fail closed; anything else wrong is `invalid-tools`. The public catalog row carries `tools` as declared; the host applies them only for an active guest, an exact `match` beats a wildcard from any extension, and among equals the first extension in the catalog wins. The registry lives in `packages/ui/src/lib/guests/tool-presentation.ts` and is consulted by the existing chat tool renderers; VS Code and mobile keep the catalog empty, so nothing changes there.
 - Host → guest `resolve` is `{ id, payload: { command, args } }`; the guest answers `resolve-result` with the same `id` and `{ item }` (a clamped `AttachIssueRequest` or `null`) or `{ error }` (1 to `GUEST_RESOLVE_ERROR_MAX` characters). The host waits `GUEST_REQUEST_TIMEOUT_MS`, then treats silence as a failure and never sends a `result` for a `resolve-result`. `badge` is `{ count }` with `count` an integer 0..999 or `null`; the host schema drops anything else.
-- `ready` always carries `session` (`{ id, title, busy }` or `null`), `surface` (`panel` on the rail, `dialog` in the attach window, `page` full screen, `background` hidden, `status` in the Work Status panel), `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.
+- `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`, and `filesystem` from a session action with `payload: ["messages"]`, `contributes.service`, `contributes.integration`, and `contributes.filesystem`; the user approves that whole list once at install (`PUT /api/guests/:id/capabilities`), and a package that later asks for more is re-approved. `hasGuestCapability` gates `prompt({ send })`, `startSession`, `request`, `serviceRequest`, and the four file calls; a refusal is `NOT_GRANTED` (`NO_SERVICE` for the service).
+- `contributes.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.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.
@@ -66,7 +68,7 @@ Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`
 
 Built-in extension source and registration rules live in `packages/extensions/DOCUMENTATION.md`. The server assigns `source: 'bundled'` only from its app-owned registry and automatically grants the package's declared capabilities. Built-ins use the same SDK, sandbox and enabled-state checks as user extensions; the `openchamber-builtin-` namespace is reserved. Their account cards appear under Built-in integrations, and their persisted disabled state and data survive app updates.
 
-Relay panels use `lib/guests/relay-document.ts`: fetch package HTML and its statically referenced scripts, styles, CSS imports/URLs, images, fonts, and nested documents through `runtimeFetch`, then render self-contained `srcDoc` with the same `sandbox="allow-scripts"`. A normal iframe URL bypasses the client-side tunnel and can load the local host UI instead. Local resource paths stay under that guest's package; missing files, import cycles, or resource limits fail the load. The loader allows 500 referenced files, 40 MiB of fetched bytes and 64 MiB of embedded text. Runtime-created relative URLs are not intercepted: bundle those assets into the IIFE or use explicit external URLs/SDK operations. Existing authored CSP is preserved. Direct iframe URLs retain their existing path.
+Relay panels use `lib/guests/relay-document.ts`: fetch package HTML and its statically referenced scripts, styles, CSS imports/URLs, images, fonts, and nested documents through `runtimeFetch`, then render self-contained `srcDoc` with the same `sandbox="allow-scripts"`. A normal iframe URL bypasses the client-side tunnel and can load the local host UI instead. Local resource paths stay under that guest's package; missing files, import cycles, or resource limits fail the load. The loader allows 500 referenced files, 40 MiB of fetched bytes and 64 MiB of embedded text. Runtime-created relative URLs are not intercepted: bundle those assets into the IIFE or use SDK operations. The relay document gets `guestFramePolicy(null)` as its first `<meta>` (a `srcDoc` has no response headers), so it cannot connect anywhere. Existing authored CSP is preserved and only narrows it further. Direct iframe URLs retain their existing path.
 
 `useGuestIconSource` loads package SVGs through authenticated `runtimeFetch` in direct and relay modes, then exposes revocable blob URLs to CSS masks. It uses the package path rather than the original URL token, so cold-start token readiness and token expiry cannot strand an icon. Cache identity follows runtime, package path and extension version; late responses are discarded and old blobs revoked. Unknown icons and SVGs that are loading or failed use the shared `FALLBACK_GUEST_ICON`, the `apps` glyph.
 
@@ -82,7 +84,7 @@ Catalog loading and installation retain typed request diagnostics in `lib/guests
 
 **Zip / git install** copies into `{dataDir}/extensions/{id}` with `source: "zip"` or `"git"`. Only git installs update: Settings → Extensions compares the installed `package.json` `version` with the origin's and offers Update when the origin is newer, so bump `version` to ship one; a `#tag` or `#branch` on the install URL pins that channel. The archive is not kept open. The host reads it (local file or https download, 20MB cap), extracts with a small allowlist unzip (store/deflate only; no zip64, encryption, or `..` paths; 500 files / 40MB uncompressed), unwraps a single root folder when `package.json` sits inside it, inspects the manifest, then renames staging to `{dataDir}/extensions/{id}`. Runtime serves and spawns from that copy. Uninstall deletes the copy. The original `.zip` on disk is untouched.
 
-The iframe is `sandbox="allow-scripts"` with no `allow-same-origin`, so its origin is opaque. Host posts to that frame's `contentWindow` with target `*`. The string `null` is not a legal `postMessage` targetOrigin. Receive still accepts only `event.source === contentWindow`. Guest `connectHost` posts `hello` to `parent` with `*`. The host answers `hello` and also pushes `ready` on iframe `load`, because a cached panel can fire `hello` while React is swapping the listener.
+The iframe is `sandbox="allow-scripts"` with no `allow-same-origin`, so its origin is opaque. Host posts to that frame's `contentWindow` with target `*`. The string `null` is not a legal `postMessage` targetOrigin. Receive still accepts only `event.source === contentWindow`. Every guest document also runs under `guestFramePolicy` (`src/frame-policy.ts`): the server sends it with `sandbox allow-scripts` on each served file, the relay loader as a `<meta>`. It keeps the guest off the network: scripts, styles, images, fonts, media, workers and nested frames load only from the package (`'self'`) or `data:`/`blob:`, and `connect-src` is the guest's own `/api/guests/<id>/` path (named by the request's `Host`, since a sandboxed document has no origin for `'self'`; `'none'` in relay). `'self'` for connections would reach the whole OpenChamber API. External data goes through the host (`request` to the declared, approved `apiOrigin`) or to `contributes.origins`: 1 to `GUEST_ORIGINS_MAX` (8) plain https origins (literal hostnames, so no `*` or other CSP syntax can widen them), granted as the `origins` capability. Its scope is the sorted list (`grant-scope.js`), so an update that adds an origin is unapproved until the dialog runs again. Approved origins join `connect-src`, `img-src`, `font-src`, `style-src` and `media-src`, never `script-src`/`worker-src`/`frame-src`: code from elsewhere could change after approval. The server reads them from the effective grants when it serves a file; relay frames get them from `PluginPane` (`approvedOrigins`, part of the frame key so an approval reloads the frame). External CDN assets not declared there do not load; bundle them. Guest files are served with `Access-Control-Allow-Origin: null`, because fonts and fetch from the opaque-origin frame are CORS requests. A guest navigating its own frame elsewhere is refused by the desktop shell (`packages/electron/guest-frame-navigation.mjs`, `will-frame-navigate`); the web runtime has no such hook. Guest `connectHost` posts `hello` to `parent` with `*`. The host answers `hello` and also pushes `ready` on iframe `load`, because a cached panel can fire `hello` while React is swapping the listener.
 
 File calls go through `POST /api/guests/:id/files` with the `x-opencode-directory` header of the open project (`lib/guests/files.ts`). `PluginPane` answers `NOT_GRANTED` and `NO_DIRECTORY` itself, mirroring the server, so a refused call costs no round trip; the server is still the authority.
 

package/dist/contract.d.ts

@@ -1,4 +1,5 @@
 import { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL } from './api-version.ts';
+import type { FileEditorChange, FileEditorDocument, FileSnapshotRequest, FileSnapshotResultPayload } from './file-editor.ts';
 import type { GuestSessionWorktree, GuestStorageRequest, GuestStorageResult, GuestWorkspaceQuery, GuestWorkspaceSnapshot, GuestWorkspaceSubscription, GuestWorkspaceUpdate, GuestWorktree } from './workspace.ts';
 export type HostThemeMode = 'light' | 'dark';
 export type HostThemeTokens = {
@@ -54,7 +55,7 @@ export type SessionSnapshot = {
  * Which host chrome mounted this iframe. Not `openSurface`. `status` is the
  * extension's section in the chat's Work Status panel.
  */
-export type GuestHostSurface = 'panel' | 'dialog' | 'page' | 'background' | 'status';
+export type GuestHostSurface = 'panel' | 'dialog' | 'page' | 'background' | 'status' | 'file';
 export type GuestConnection = {
     connected: boolean;
     account: string;
@@ -434,6 +435,24 @@ export type HostActionMessage = Envelope & {
     id: string;
     payload: GuestActionItem;
 };
+/** The file a `file` surface edits; pushed after `ready` and again whenever the frame reconnects. */
+export type HostFileOpenMessage = Envelope & {
+    type: 'file-open';
+    payload: FileEditorDocument;
+};
+/** Host → guest request. The guest answers with `file-snapshot-result` carrying the same `id`. */
+export type HostFileSnapshotMessage = Envelope & {
+    type: 'file-snapshot';
+    id: string;
+    payload: FileSnapshotRequest;
+};
+/** The snapshot with this `version` is on disk. */
+export type HostFileSavedMessage = Envelope & {
+    type: 'file-saved';
+    payload: {
+        version: string;
+    };
+};
 export type HostResultMessage = Envelope & {
     type: 'result';
     id: string;
@@ -448,7 +467,7 @@ export type HostResultMessage = Envelope & {
 export type HostMessage = (Envelope & {
     type: 'workspace';
     payload: GuestWorkspaceUpdate;
-}) | HostReadyMessage | HostDirectoryMessage | HostSessionMessage | HostConnectionMessage | HostSettingsMessage | HostSessionLifecycleMessage | HostItemMessage | HostResolveMessage | HostActionMessage | HostResultMessage;
+}) | HostReadyMessage | HostDirectoryMessage | HostSessionMessage | HostConnectionMessage | HostSettingsMessage | HostSessionLifecycleMessage | HostItemMessage | HostResolveMessage | HostActionMessage | HostFileOpenMessage | HostFileSnapshotMessage | HostFileSavedMessage | HostResultMessage;
 type GuestCall<Type extends string, Payload = never> = Envelope & {
     type: Type;
     id: string;
@@ -501,11 +520,30 @@ export type GuestActionResultMessage = Envelope & {
     id: string;
     payload: ActionResultPayload;
 };
+/** Answers a host `file-snapshot` by `id`. The host sends no `result` back. */
+export type GuestFileSnapshotResultMessage = Envelope & {
+    type: 'file-snapshot-result';
+    id: string;
+    payload: FileSnapshotResultPayload;
+};
+/** A file editor's state changed. Fire and forget. */
+export type GuestFileChangeMessage = Envelope & {
+    type: 'file-change';
+    payload: FileEditorChange;
+};
+/** The user asked to save (Cmd/Ctrl+S inside the frame). Fire and forget. */
+export type GuestFileSaveMessage = Envelope & {
+    type: 'file-save';
+};
+/** The editor cannot open this file; the host shows its source instead. Fire and forget. */
+export type GuestFileUnsupportedMessage = Envelope & {
+    type: 'file-unsupported';
+};
 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 | GuestResizeMessage | GuestOpenCommitMessage | GuestActionResultMessage | GuestResolveResultMessage;
+}> | GuestHelloMessage | GuestToastMessage | GuestOpenUrlMessage | GuestOpenSurfaceMessage | GuestClipboardWriteMessage | GuestComposeMessage | GuestAttachMessage | GuestStartSessionMessage | GuestPromptMessage | GuestSessionLinkMessage | GuestCloseMessage | GuestOauthStartMessage | GuestOauthDisconnectMessage | GuestRequestMessage | GuestServiceRequestMessage | GuestServiceStatusMessage | GuestFileReadMessage | GuestFileWriteMessage | GuestFileListMessage | GuestFileStatMessage | GuestGenerateMessage | GuestBadgeMessage | GuestResizeMessage | GuestOpenCommitMessage | GuestActionResultMessage | GuestResolveResultMessage | GuestFileSnapshotResultMessage | GuestFileChangeMessage | GuestFileSaveMessage | GuestFileUnsupportedMessage;
 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

@@ -211,6 +211,7 @@ export const isGenerateResult = (value) => Boolean(value && 'text' in value && S
 const HOST_PUSH_TYPES = new Set([
     'workspace',
     'ready', 'directory', 'session', 'connection', 'settings', 'session-lifecycle', 'item', 'resolve', 'action',
+    'file-open', 'file-snapshot', 'file-saved',
 ]);
 const asWireRecord = (data) => (Object(data) === data ? data : null);
 const isNonEmptyString = (value) => (String(value) === value && value.length > 0);

package/dist/file-editor.d.ts

@@ -0,0 +1,109 @@
+/** Editors one package may declare. */
+export declare const GUEST_FILE_EDITORS_MAX = 8;
+/** Characters in an editor's `title`. */
+export declare const GUEST_FILE_EDITOR_TITLE_MAX = 60;
+/** File-name patterns one editor may list. */
+export declare const GUEST_FILE_EDITOR_PATTERNS_MAX = 16;
+/** Characters in one file-name pattern. */
+export declare const GUEST_FILE_EDITOR_PATTERN_MAX = 128;
+/**
+ * Characters of file text, or bytes of a binary file, the host hands to an
+ * editor and accepts back. Larger than `GUEST_FILE_CONTENT_MAX`: drawings with
+ * embedded images and office documents run to several megabytes. A larger
+ * file stays with the host's own view.
+ */
+export declare const GUEST_FILE_EDITOR_CONTENT_MAX = 20000000;
+/** Characters in the version a snapshot carries. */
+export declare const GUEST_FILE_EDITOR_VERSION_MAX = 256;
+export type FileEditorContribution = {
+    /** Kebab-case, unique within the package. */
+    id: string;
+    /** Shown where the host names the editor. */
+    title: string;
+    /** File-name globs, matched case-insensitively against the name only: `*` is any run, `?` one character. */
+    match: string[];
+    /** Package-local `.html` the Files view loads for a matching file. */
+    entry: string;
+    /**
+     * `text` (the default) hands over the file as a string and only claims text
+     * files. `binary` hands over its bytes and claims any matching file, binary
+     * or not; the host has no source view for it.
+     */
+    content?: FileEditorContentKind;
+};
+export type FileEditorContentKind = 'text' | 'binary';
+/**
+ * A file-name glob: no path separators or NUL, and at least one character
+ * that is not a wildcard, so no editor can claim every file.
+ */
+export declare const isFileEditorPattern: (value: string) => boolean;
+/** Whether `fileName` (a name, not a path) matches one file-editor pattern. */
+export declare const matchesFileEditorPattern: (fileName: string, pattern: string) => boolean;
+/** What the host hands the editor: the file it opened. */
+export type FileEditorDocument = {
+    /** Path as the host shows it; for display, never for reading. */
+    path: string;
+    name: string;
+    /** True when the host will not save this file; the editor should not offer edits. */
+    readOnly: boolean;
+} & (
+/** The file's text with `\n` line endings; the host restores the file's own on write. */
+{
+    encoding: 'text';
+    content: string;
+}
+/** The file's bytes, exactly as on disk. */
+ | {
+    encoding: 'binary';
+    bytes: Uint8Array<ArrayBuffer>;
+});
+/**
+ * The edited file and the version of the editor's state it came from: text
+ * for a `text` editor, bytes for a `binary` one.
+ */
+export type FileEditorSnapshot = {
+    /** Opaque to the host; handed back through `onFileSaved` once this snapshot is on disk. */
+    version: string;
+} & ({
+    content: string;
+} | {
+    bytes: Uint8Array<ArrayBuffer>;
+});
+/** Characters of text or bytes a snapshot or document carries. */
+export declare const fileEditorPayloadSize: (value: {
+    content: string;
+} | {
+    bytes: Uint8Array<ArrayBuffer>;
+}) => number;
+/** Whether two documents are the same file with the same content, byte for byte. */
+export declare const sameFileEditorDocument: (left: FileEditorDocument, right: FileEditorDocument) => boolean;
+/**
+ * Why the host wants a snapshot: `save` writes it to disk, `handoff` moves it
+ * into the host's source view or to the other place the editor is shown.
+ */
+export type FileSnapshotPurpose = 'save' | 'handoff';
+export type FileSnapshotRequest = {
+    purpose: FileSnapshotPurpose;
+};
+export type FileSnapshotResultPayload = {
+    snapshot: FileEditorSnapshot;
+} | {
+    error: string;
+};
+/** The editor's state after a change: `dirty` against what was saved, `edited` when the document itself changed. */
+export type FileEditorChange = {
+    dirty: boolean;
+    edited: boolean;
+};
+/**
+ * Tracks whether an editor differs from what was last written. The host
+ * writes one snapshot and reports that snapshot's version saved, so edits
+ * made while the write ran leave the editor dirty instead of being recorded as
+ * saved but never written.
+ */
+export declare const createFileSaveTracker: (initialVersion: string | null) => {
+    /** A new live version; `edited` is true when it differs from the previous one. */
+    observe: (version: string) => FileEditorChange;
+    /** Records a written version; returns whether the live state is still dirty. */
+    markSaved: (version: string) => boolean;
+};

package/dist/file-editor.js

@@ -0,0 +1,91 @@
+// File editors (`contributes.fileEditors`): the host's Files view opens files
+// whose names match an editor's patterns in that editor's frame. The host owns
+// the file: it reads it, hands the text to the frame, asks for the edited text
+// when it saves, and keeps saving, autosave, the unsaved-changes prompt, and
+// external-change handling. The editor never touches the disk.
+/** Editors one package may declare. */
+export const GUEST_FILE_EDITORS_MAX = 8;
+/** Characters in an editor's `title`. */
+export const GUEST_FILE_EDITOR_TITLE_MAX = 60;
+/** File-name patterns one editor may list. */
+export const GUEST_FILE_EDITOR_PATTERNS_MAX = 16;
+/** Characters in one file-name pattern. */
+export const GUEST_FILE_EDITOR_PATTERN_MAX = 128;
+/**
+ * Characters of file text, or bytes of a binary file, the host hands to an
+ * editor and accepts back. Larger than `GUEST_FILE_CONTENT_MAX`: drawings with
+ * embedded images and office documents run to several megabytes. A larger
+ * file stays with the host's own view.
+ */
+export const GUEST_FILE_EDITOR_CONTENT_MAX = 20_000_000;
+/** Characters in the version a snapshot carries. */
+export const GUEST_FILE_EDITOR_VERSION_MAX = 256;
+/**
+ * A file-name glob: no path separators or NUL, and at least one character
+ * that is not a wildcard, so no editor can claim every file.
+ */
+export const isFileEditorPattern = (value) => (value.length > 0
+    && value.length <= GUEST_FILE_EDITOR_PATTERN_MAX
+    && !/[/\\\0]/.test(value)
+    && /[^*?]/.test(value));
+const patternExpressions = new Map();
+const patternExpression = (pattern) => {
+    const cached = patternExpressions.get(pattern);
+    if (cached)
+        return cached;
+    const source = pattern
+        .split('')
+        .map((character) => {
+        if (character === '*')
+            return '.*';
+        if (character === '?')
+            return '.';
+        return character.replace(/[\\^$.|+()[\]{}]/g, '\\$&');
+    })
+        .join('');
+    const expression = new RegExp(`^${source}$`, 'is');
+    patternExpressions.set(pattern, expression);
+    return expression;
+};
+/** Whether `fileName` (a name, not a path) matches one file-editor pattern. */
+export const matchesFileEditorPattern = (fileName, pattern) => (isFileEditorPattern(pattern) && patternExpression(pattern).test(fileName));
+/** Characters of text or bytes a snapshot or document carries. */
+export const fileEditorPayloadSize = (value) => ('bytes' in value ? value.bytes.byteLength : value.content.length);
+/** Whether two documents are the same file with the same content, byte for byte. */
+export const sameFileEditorDocument = (left, right) => {
+    if (left.path !== right.path || left.readOnly !== right.readOnly)
+        return false;
+    if (left.encoding === 'text' || right.encoding === 'text') {
+        return left.encoding === 'text' && right.encoding === 'text' && left.content === right.content;
+    }
+    if (left.bytes.byteLength !== right.bytes.byteLength)
+        return false;
+    for (let index = 0; index < left.bytes.byteLength; index += 1) {
+        if (left.bytes[index] !== right.bytes[index])
+            return false;
+    }
+    return true;
+};
+/**
+ * Tracks whether an editor differs from what was last written. The host
+ * writes one snapshot and reports that snapshot's version saved, so edits
+ * made while the write ran leave the editor dirty instead of being recorded as
+ * saved but never written.
+ */
+export const createFileSaveTracker = (initialVersion) => {
+    let saved = initialVersion;
+    let live = initialVersion;
+    return {
+        /** A new live version; `edited` is true when it differs from the previous one. */
+        observe: (version) => {
+            const edited = version !== live;
+            live = version;
+            return { edited, dirty: version !== saved };
+        },
+        /** Records a written version; returns whether the live state is still dirty. */
+        markSaved: (version) => {
+            saved = version;
+            return live !== version;
+        },
+    };
+};

package/dist/frame-policy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The Content Security Policy every guest document runs under, on top of the
+ * `sandbox="allow-scripts"` iframe. It keeps the guest off the network: its
+ * own package files load, and `data:`/`blob:` URLs it builds itself, nothing
+ * else. Reaching the outside world is the host's job (`request` to the one
+ * declared `apiOrigin`, which the user approved), so a guest cannot send what
+ * it was shown (conversation, files, model output) anywhere on its own.
+ *
+ * `connectSource` is where `fetch`/XHR/WebSocket may go: the guest's own
+ * package path on the server, or null for none. `'self'` would reach the
+ * whole OpenChamber API, which a server without a UI password answers.
+ *
+ * `origins` are the `contributes.origins` the user approved: the guest may
+ * exchange data with them directly (fetch, images, fonts, styles, media).
+ * Never scripts or workers: code loaded from elsewhere could change after
+ * the extension was approved.
+ *
+ * Inline and eval stay allowed: they run code, they do not open connections.
+ */
+export declare const guestFramePolicy: (connectSource: string | null, origins?: readonly string[]) => string;

package/dist/frame-policy.js

@@ -0,0 +1,37 @@
+/**
+ * The Content Security Policy every guest document runs under, on top of the
+ * `sandbox="allow-scripts"` iframe. It keeps the guest off the network: its
+ * own package files load, and `data:`/`blob:` URLs it builds itself, nothing
+ * else. Reaching the outside world is the host's job (`request` to the one
+ * declared `apiOrigin`, which the user approved), so a guest cannot send what
+ * it was shown (conversation, files, model output) anywhere on its own.
+ *
+ * `connectSource` is where `fetch`/XHR/WebSocket may go: the guest's own
+ * package path on the server, or null for none. `'self'` would reach the
+ * whole OpenChamber API, which a server without a UI password answers.
+ *
+ * `origins` are the `contributes.origins` the user approved: the guest may
+ * exchange data with them directly (fetch, images, fonts, styles, media).
+ * Never scripts or workers: code loaded from elsewhere could change after
+ * the extension was approved.
+ *
+ * Inline and eval stay allowed: they run code, they do not open connections.
+ */
+export const guestFramePolicy = (connectSource, origins = []) => {
+    const approved = origins.length > 0 ? ` ${origins.join(' ')}` : '';
+    const local = "'self' data: blob:";
+    const connect = [connectSource, ...origins].filter((source) => Boolean(source));
+    return [
+        "default-src 'none'",
+        `script-src 'unsafe-inline' 'unsafe-eval' 'wasm-unsafe-eval' ${local}`,
+        `style-src 'unsafe-inline' ${local}${approved}`,
+        `img-src ${local}${approved}`,
+        `font-src ${local}${approved}`,
+        `media-src ${local}${approved}`,
+        `worker-src ${local}`,
+        `frame-src ${local}`,
+        `connect-src ${connect.length > 0 ? connect.join(' ') : "'none'"}`,
+        "object-src 'none'",
+        "form-action 'none'",
+    ].join('; ');
+};

package/dist/host.d.ts

@@ -1,5 +1,6 @@
 import { type GuestProjectsSnapshot, type GuestWorktreesSnapshot, type GuestSessionsSnapshot } from './workspace.ts';
 import type { JsonValue } from './contract.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';
 export type HostFrame = {
     addEventListener: Window['addEventListener'];
@@ -113,6 +114,27 @@ export type HostClient = {
      * chrome and ignore it.
      */
     setHeight: (height: number) => Promise<void>;
+    /**
+     * The file a `file` surface edits (`contributes.fileEditors`). Replays the
+     * last file; called again when the host reconnects the frame. Registering
+     * also routes Cmd/Ctrl+S inside the frame to the host's save.
+     */
+    onFileOpen: (listener: (file: FileEditorDocument) => void) => () => void;
+    /**
+     * Answer the host when it needs the edited text: to save it (`save`) or to
+     * move it into its source view (`handoff`). Return the whole file and a
+     * version of the state it came from; a thrown error fails the save. One
+     * handler at a time.
+     */
+    onFileSnapshot: (handler: (purpose: FileSnapshotPurpose) => Promise<FileEditorSnapshot> | FileEditorSnapshot) => () => void;
+    /** The snapshot with this version is on disk; edits made since keep the file dirty. */
+    onFileSaved: (listener: (version: string) => void) => () => void;
+    /** Report the editor's state after a change. `edited` delays autosave until edits stop. */
+    reportFileChange: (change: FileEditorChange) => void;
+    /** Ask the host to save now, as Cmd/Ctrl+S does. */
+    requestFileSave: () => void;
+    /** This file cannot be opened here; the host shows its source instead. */
+    reportFileUnsupported: () => void;
     dispose: () => void;
 };
 export declare class HostRequestError extends Error {

package/dist/host.js

@@ -1,6 +1,11 @@
 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_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";
+// 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;
+const isSaveShortcut = (event) => ((event.metaKey || event.ctrlKey) && !event.altKey && !event.shiftKey && event.key.toLowerCase() === 's');
 export class HostRequestError extends Error {
     code;
     constructor(code, message) {
@@ -33,6 +38,11 @@ export const connectHost = (options = {}) => {
     const itemListeners = new Set();
     let resolveHandler = null;
     let actionHandler = null;
+    const fileOpenListeners = new Set();
+    const fileSavedListeners = new Set();
+    let fileSnapshotHandler = null;
+    let lastFile = null;
+    let saveShortcutInstalled = false;
     const pending = new Map();
     const workspaceListeners = new Map();
     let disposed = false;
@@ -153,6 +163,47 @@ export const connectHost = (options = {}) => {
             });
             return;
         }
+        if (message.type === 'file-open') {
+            // The host pushes on both `hello` and iframe load; the same file twice
+            // must not make the editor reload what the user may already be editing.
+            const next = message.payload;
+            if (lastFile && sameFileEditorDocument(lastFile, next))
+                return;
+            lastFile = next;
+            emit(fileOpenListeners, message.payload);
+            return;
+        }
+        if (message.type === 'file-saved') {
+            emit(fileSavedListeners, message.payload.version);
+            return;
+        }
+        if (message.type === 'file-snapshot') {
+            const answer = (payload) => {
+                if (!disposed)
+                    post({ channel: OPENCHAMBER_SDK_CHANNEL, v: OPENCHAMBER_SDK_API_VERSION,
+                        type: 'file-snapshot-result', id: message.id, payload });
+            };
+            const fail = (text) => answer({ error: (text.trim() || 'Could not read the edited file.').slice(0, GUEST_RESOLVE_ERROR_MAX) });
+            const handler = fileSnapshotHandler;
+            if (!handler) {
+                fail('This extension does not edit files.');
+                return;
+            }
+            Promise.resolve().then(() => handler(message.payload.purpose)).then((snapshot) => {
+                if (fileEditorPayloadSize(snapshot) > GUEST_FILE_EDITOR_CONTENT_MAX) {
+                    fail(`The file is over ${GUEST_FILE_EDITOR_CONTENT_MAX} ${'bytes' in snapshot ? 'bytes' : 'characters'}.`);
+                    return;
+                }
+                if (snapshot.version.length > GUEST_FILE_EDITOR_VERSION_MAX) {
+                    fail(`The snapshot version is over ${GUEST_FILE_EDITOR_VERSION_MAX} characters.`);
+                    return;
+                }
+                answer({ snapshot: 'bytes' in snapshot
+                        ? { bytes: snapshot.bytes, version: snapshot.version }
+                        : { content: snapshot.content, version: snapshot.version } });
+            }, (error) => fail(error instanceof Error ? error.message : String(error)));
+            return;
+        }
         if (message.type === 'resolve') {
             const answer = (payload) => {
                 post({
@@ -208,6 +259,21 @@ export const connectHost = (options = {}) => {
     };
     const request = (message) => (send(message).then(() => undefined));
     const envelope = { channel: OPENCHAMBER_SDK_CHANNEL, v: OPENCHAMBER_SDK_API_VERSION };
+    // Fire-and-forget notices: nothing to wait for, and nothing to post to
+    // without a host frame.
+    const notify = (message) => {
+        if (!disposed && target.parent !== target)
+            post(message);
+    };
+    const requestFileSave = () => notify({ ...envelope, type: 'file-save' });
+    // Capture phase, so an editor library that binds Cmd/Ctrl+S itself does not
+    // swallow the host's save.
+    const onSaveShortcut = (event) => {
+        if (!isKeyEvent(event) || !isSaveShortcut(event))
+            return;
+        event.preventDefault();
+        requestFileSave();
+    };
     const requireIdentity = (value, maximum = 1024) => {
         if (!value.trim() || value.length > maximum)
             throw new HostRequestError('HOST_REJECTED', `Identity must contain 1 to ${maximum} characters.`);
@@ -627,6 +693,34 @@ export const connectHost = (options = {}) => {
             id: nextId(ids),
             payload: { height: clampFrameHeight(height) },
         }),
+        onFileOpen: (listener) => {
+            fileOpenListeners.add(listener);
+            if (!saveShortcutInstalled) {
+                saveShortcutInstalled = true;
+                target.addEventListener('keydown', onSaveShortcut, true);
+            }
+            if (lastFile)
+                listener(lastFile);
+            return () => {
+                fileOpenListeners.delete(listener);
+            };
+        },
+        onFileSnapshot: (handler) => {
+            fileSnapshotHandler = handler;
+            return () => {
+                if (fileSnapshotHandler === handler)
+                    fileSnapshotHandler = null;
+            };
+        },
+        onFileSaved: (listener) => {
+            fileSavedListeners.add(listener);
+            return () => {
+                fileSavedListeners.delete(listener);
+            };
+        },
+        reportFileChange: (change) => notify({ ...envelope, type: 'file-change', payload: { dirty: change.dirty, edited: change.edited } }),
+        requestFileSave,
+        reportFileUnsupported: () => notify({ ...envelope, type: 'file-unsupported' }),
         dispose: () => {
             for (const subscriptionId of workspaceListeners.keys()) {
                 post({ ...envelope, type: 'workspace-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
@@ -635,6 +729,11 @@ export const connectHost = (options = {}) => {
             disposed = true;
             resolveHandler = null;
             actionHandler = null;
+            fileSnapshotHandler = null;
+            fileOpenListeners.clear();
+            fileSavedListeners.clear();
+            if (saveShortcutInstalled)
+                target.removeEventListener('keydown', onSaveShortcut, true);
             target.removeEventListener('message', onMessage);
             for (const waiter of pending.values()) {
                 clearTimeout(waiter.timer);

package/dist/index.d.ts

@@ -1,15 +1,18 @@
 export { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL, OPENCHAMBER_SDK_MANIFEST_API_VERSIONS } from './api-version.ts';
 export { GUEST_SCROLLBAR_CSS, GUEST_SCROLLBAR_SCRIPT } from './scrollbar-style.ts';
+export { guestFramePolicy } from './frame-policy.ts';
 export type { GuestLoadState, GuestProject, GuestWorktree, GuestSessionActivity, GuestSessionRecord, GuestDirectoryCoverage, GuestProjectsSnapshot, GuestWorktreesSnapshot, GuestSessionsSnapshot, GuestWorkspaceSnapshot, GuestWorkspaceQuery, GuestWorkspaceSubscription, GuestWorkspaceUpdate, GuestStorageRequest, GuestStorageResult, GuestSessionWorktree } from './workspace.ts';
 export { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_VALUE_BYTES, GUEST_STORAGE_TOTAL_BYTES } from './workspace.ts';
 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, 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.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, 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.ts';
 export type { GuestServiceProvides, GuestSurfaceDock, 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, StatusSectionContribution, ParseManifestErrorCode, ParseManifestFailure, ParseManifestResult, ParseManifestSuccess, PublicService, PublicServicePermissions, PublicGuestCapabilities, PublicIntegration, PublicIntegrationToken, PublicSocketBinding, ResolvedGuestApi, SocketBinding, SocketPlatform, } from './manifest.ts';
+export { GUEST_FILE_EDITORS_MAX, GUEST_FILE_EDITOR_CONTENT_MAX, GUEST_FILE_EDITOR_PATTERNS_MAX, GUEST_FILE_EDITOR_PATTERN_MAX, GUEST_FILE_EDITOR_TITLE_MAX, GUEST_FILE_EDITOR_VERSION_MAX, createFileSaveTracker, fileEditorPayloadSize, isFileEditorPattern, matchesFileEditorPattern, } from './file-editor.ts';
+export type { FileEditorChange, FileEditorContentKind, FileEditorContribution, FileEditorDocument, FileEditorSnapshot, FileSnapshotPurpose, FileSnapshotRequest, FileSnapshotResultPayload, } from './file-editor.ts';
 export { connectHost, HostRequestError } from './host.ts';
 export type { HostClient, HostClientOptions, HostFrame } from './host.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, GuestBadgeMessage, GuestResizeMessage, GuestOpenCommitMessage, 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, 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, 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, HostMessage, HostReadyContext, HostReadyMessage, HostResultMessage, HostSessionLifecycleMessage, HostSessionMessage, HostSettingsMessage, 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

@@ -1,8 +1,10 @@
 export { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL, OPENCHAMBER_SDK_MANIFEST_API_VERSIONS } from "./api-version.js";
 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 } from "./workspace.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_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";
+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";
+export { GUEST_FILE_EDITORS_MAX, GUEST_FILE_EDITOR_CONTENT_MAX, GUEST_FILE_EDITOR_PATTERNS_MAX, GUEST_FILE_EDITOR_PATTERN_MAX, GUEST_FILE_EDITOR_TITLE_MAX, GUEST_FILE_EDITOR_VERSION_MAX, createFileSaveTracker, fileEditorPayloadSize, isFileEditorPattern, matchesFileEditorPattern, } from "./file-editor.js";
 export { connectHost, HostRequestError } from "./host.js";
 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.js";
 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.js";

package/dist/manifest.d.ts

@@ -1,4 +1,5 @@
 import type { OpenChamberManifestApiVersion } from './api-version.ts';
+import type { FileEditorContribution } from './file-editor.ts';
 export declare const PANEL_ID: RegExp;
 /**
  * The extension's identity on the rail, the Extensions card, and the approval
@@ -271,16 +272,18 @@ 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`, and
- * `filesystem` follow from `contributes.service`, `contributes.integration`,
- * and `contributes.filesystem`. `model` is one-off text generation with the
+ * 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"];
+export declare const GUEST_CAPABILITIES: readonly ["prompt", "sessions", "files", "model", "conversation", "service", "network", "filesystem", "origins"];
 export type GuestCapability = (typeof GUEST_CAPABILITIES)[number];
 export declare const DECLARED_GUEST_CAPABILITIES: readonly ["prompt", "sessions", "files", "model"];
 /** The capabilities a manifest may ask for directly. */
 export type DeclaredGuestCapability = (typeof DECLARED_GUEST_CAPABILITIES)[number];
+/** How many `contributes.origins` a package may declare. */
+export declare const GUEST_ORIGINS_MAX = 8;
 /** How many `contributes.filesystem` patterns a package may declare. */
 export declare const GUEST_FILESYSTEM_PATTERNS_MAX = 16;
 /** Characters in one `contributes.filesystem` pattern. */
@@ -303,12 +306,19 @@ export type OpenChamberContributes = {
     service?: ServiceContribution;
     /** Paths outside the project the panel may read and write. Grants `filesystem`. */
     filesystem?: string[];
+    /**
+     * https origins the frame may exchange data with directly: fetch, images,
+     * fonts, styles and media, never scripts. Grants `origins`, approved per list.
+     */
+    origins?: string[];
     /** Menu entries on messages and sessions. */
     actions?: GuestActionContribution[];
     /** Composer slash commands that attach a chip. */
     commands?: GuestCommandContribution[];
     /** How the extension's tool calls look in the chat. */
     tools?: GuestToolContribution[];
+    /** Editors the Files view opens matching files in. */
+    fileEditors?: FileEditorContribution[];
 };
 /** Whether any declared action asks for a session's messages, which needs `conversation`. */
 export declare const guestActionsNeedConversation: (actions: readonly GuestActionContribution[] | undefined) => boolean;
@@ -317,7 +327,7 @@ export type PublicGuestCapabilities = {
     requested: GuestCapability[];
     granted: GuestCapability[];
 };
-export declare const requestedGuestCapabilities: (contributes: Pick<OpenChamberContributes, "capabilities" | "integration" | "service" | "filesystem" | "actions">) => GuestCapability[];
+export declare const requestedGuestCapabilities: (contributes: Pick<OpenChamberContributes, "capabilities" | "integration" | "service" | "filesystem" | "actions" | "origins">) => GuestCapability[];
 /**
  * Whether the package ships a visible panel. Background-only extensions can
  * execute code but have no rail surface, attach picker, or full-screen page.
@@ -348,7 +358,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-background' | 'invalid-attach' | 'invalid-page' | 'invalid-status-section' | '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-status-section' | 'invalid-capabilities' | 'invalid-integration' | 'invalid-service' | 'invalid-filesystem' | 'invalid-origins' | 'invalid-actions' | 'invalid-commands' | 'invalid-tools' | 'invalid-file-editors';
 export type ParseManifestFailure = {
     ok: false;
     code: ParseManifestErrorCode;

package/dist/manifest.js

@@ -97,13 +97,15 @@ 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`, and
- * `filesystem` follow from `contributes.service`, `contributes.integration`,
- * and `contributes.filesystem`. `model` is one-off text generation with the
+ * 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'];
+export const GUEST_CAPABILITIES = ['prompt', 'sessions', 'files', 'model', 'conversation', 'service', 'network', 'filesystem', 'origins'];
 export const DECLARED_GUEST_CAPABILITIES = ['prompt', 'sessions', 'files', 'model'];
+/** How many `contributes.origins` a package may declare. */
+export const GUEST_ORIGINS_MAX = 8;
 /** How many `contributes.filesystem` patterns a package may declare. */
 export const GUEST_FILESYSTEM_PATTERNS_MAX = 16;
 /** Characters in one `contributes.filesystem` pattern. */
@@ -138,6 +140,8 @@ export const requestedGuestCapabilities = (contributes) => {
         declared.add('network');
     if (contributes.filesystem && contributes.filesystem.length > 0)
         declared.add('filesystem');
+    if (contributes.origins && contributes.origins.length > 0)
+        declared.add('origins');
     return GUEST_CAPABILITIES.filter((capability) => declared.has(capability));
 };
 /**

package/dist/parse.d.ts

@@ -115,6 +115,7 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             surface: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strip>>;
         filesystem: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        origins: z.ZodOptional<z.ZodArray<z.ZodString>>;
         actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
             label: z.ZodString;
@@ -146,8 +147,8 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
             subtitle: z.ZodOptional<z.ZodString>;
             output: z.ZodOptional<z.ZodEnum<{
-                code: "code";
                 text: "text";
+                code: "code";
                 auto: "auto";
                 json: "json";
                 markdown: "markdown";
@@ -156,6 +157,16 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>;
+        fileEditors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            match: z.ZodArray<z.ZodString>;
+            entry: z.ZodString;
+            content: z.ZodOptional<z.ZodEnum<{
+                text: "text";
+                binary: "binary";
+            }>>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const PACKAGE_VERSION_PATTERN: RegExp;
@@ -276,6 +287,7 @@ export declare const packageManifestSchema: z.ZodObject<{
                 surface: z.ZodOptional<z.ZodLiteral<true>>;
             }, z.core.$strip>>;
             filesystem: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            origins: z.ZodOptional<z.ZodArray<z.ZodString>>;
             actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 id: z.ZodString;
                 label: z.ZodString;
@@ -307,8 +319,8 @@ export declare const packageManifestSchema: z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
                 subtitle: z.ZodOptional<z.ZodString>;
                 output: z.ZodOptional<z.ZodEnum<{
-                    code: "code";
                     text: "text";
+                    code: "code";
                     auto: "auto";
                     json: "json";
                     markdown: "markdown";
@@ -317,6 +329,16 @@ export declare const packageManifestSchema: z.ZodObject<{
                 language: z.ZodOptional<z.ZodString>;
                 columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strip>>>;
+            fileEditors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                title: z.ZodString;
+                match: z.ZodArray<z.ZodString>;
+                entry: z.ZodString;
+                content: z.ZodOptional<z.ZodEnum<{
+                    text: "text";
+                    binary: "binary";
+                }>>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>;
     }, z.core.$strip>;
 }, z.core.$strip>;

package/dist/parse.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { OPENCHAMBER_SDK_MANIFEST_API_VERSIONS } from "./api-version.js";
 import { OPENCHAMBER_ENGINE_PATTERN } from "./host-version.js";
-import { DECLARED_GUEST_CAPABILITIES, GUEST_ACTIONS_MAX, GUEST_ACTION_LABEL_MAX, GUEST_COMMANDS_MAX, GUEST_COMMAND_DESCRIPTION_MAX, GUEST_COMMAND_NAME, GUEST_FILESYSTEM_PATTERNS_MAX, GUEST_FILESYSTEM_PATTERN_MAX, GUEST_SERVICE_PROVIDES, 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, PANEL_ID, hasGuestPage, isGuestFilesystemPattern, isGuestPackageSvgIcon, isSafeAssetPath, resolveIntegrationAuth, GUEST_SURFACE_DOCKS, GUEST_SURFACE_DOCK_SIZE_MAX, GUEST_SURFACE_DOCK_SIZE_MIN, GUEST_STATUS_SECTION_HEIGHT_MAX, GUEST_STATUS_SECTION_HEIGHT_MIN, GUEST_STATUS_SECTION_TITLE_MAX, } from "./manifest.js";
+import { DECLARED_GUEST_CAPABILITIES, GUEST_ACTIONS_MAX, GUEST_ACTION_LABEL_MAX, GUEST_COMMANDS_MAX, GUEST_COMMAND_DESCRIPTION_MAX, GUEST_COMMAND_NAME, GUEST_FILESYSTEM_PATTERNS_MAX, GUEST_FILESYSTEM_PATTERN_MAX, GUEST_ORIGINS_MAX, GUEST_SERVICE_PROVIDES, 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, PANEL_ID, hasGuestPage, isGuestFilesystemPattern, isGuestPackageSvgIcon, isSafeAssetPath, resolveIntegrationAuth, GUEST_SURFACE_DOCKS, GUEST_SURFACE_DOCK_SIZE_MAX, GUEST_SURFACE_DOCK_SIZE_MIN, GUEST_STATUS_SECTION_HEIGHT_MAX, GUEST_STATUS_SECTION_HEIGHT_MIN, GUEST_STATUS_SECTION_TITLE_MAX, } from "./manifest.js";
+import { GUEST_FILE_EDITORS_MAX, GUEST_FILE_EDITOR_PATTERNS_MAX, GUEST_FILE_EDITOR_TITLE_MAX, isFileEditorPattern, } from "./file-editor.js";
 const isPanelIcon = (value) => (PANEL_ID.test(value) || isGuestPackageSvgIcon(value));
 const isHttpsUrl = (value) => {
     try {
@@ -12,6 +13,14 @@ const isHttpsUrl = (value) => {
         return false;
     }
 };
+// An origin the host writes into the frame's CSP as is: a literal hostname,
+// so no `*` or other CSP syntax can widen what the user approved.
+const APPROVABLE_HOSTNAME = /^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/;
+const isApprovableOrigin = (value) => {
+    if (!isHttpsOrigin(value))
+        return false;
+    return APPROVABLE_HOSTNAME.test(new URL(value).hostname);
+};
 const isHttpsOrigin = (value) => {
     try {
         const parsed = new URL(value);
@@ -183,6 +192,15 @@ const toolSchema = z.object({
 }).refine((value) => value.output === 'code' || value.language === undefined, { path: ['language'] })
     .refine((value) => (value.output === 'table') === (value.columns !== undefined), { path: ['columns'] });
 const toolsSchema = z.array(toolSchema).min(1).max(GUEST_TOOLS_MAX);
+const fileEditorSchema = z.object({
+    id: z.string().trim().regex(PANEL_ID),
+    title: z.string().trim().min(1).max(GUEST_FILE_EDITOR_TITLE_MAX),
+    match: z.array(z.string().trim().refine(isFileEditorPattern)).min(1).max(GUEST_FILE_EDITOR_PATTERNS_MAX),
+    entry: z.string().trim().refine((value) => isSafeAssetPath(value) && value.toLowerCase().endsWith('.html')),
+    content: z.enum(['text', 'binary']).optional(),
+});
+const fileEditorsSchema = z.array(fileEditorSchema).min(1).max(GUEST_FILE_EDITORS_MAX)
+    .refine((editors) => uniqueBy(editors, (editor) => editor.id), { message: 'file editor ids must be unique' });
 const contributesSchema = z.object({
     panel: panelSchema,
     background: z.object({
@@ -202,9 +220,13 @@ const contributesSchema = z.object({
     integration: integrationSchema.optional(),
     service: serviceSchema.optional(),
     filesystem: z.array(z.string().max(GUEST_FILESYSTEM_PATTERN_MAX).refine(isGuestFilesystemPattern)).min(1).max(GUEST_FILESYSTEM_PATTERNS_MAX).optional(),
+    origins: z.array(z.string().trim().refine(isApprovableOrigin)).min(1).max(GUEST_ORIGINS_MAX)
+        .refine((origins) => new Set(origins).size === origins.length, { message: 'origins must be unique' })
+        .optional(),
     actions: actionsSchema.optional(),
     commands: commandsSchema.optional(),
     tools: toolsSchema.optional(),
+    fileEditors: fileEditorsSchema.optional(),
 });
 /**
  * Contributions that need either the panel or background execution frame.
@@ -226,6 +248,8 @@ const runtimeContributions = (contributes) => {
         declared.push('service');
     if (contributes.filesystem !== undefined)
         declared.push('filesystem');
+    if (contributes.origins !== undefined)
+        declared.push('origins');
     if (contributes.actions !== undefined)
         declared.push('actions');
     if (contributes.commands !== undefined)
@@ -272,10 +296,10 @@ export const openChamberManifestSchema = z.object({
                 });
             return;
         }
-        if (contributes.statusSection) {
-            // The section frame runs code and may use what the package is granted,
-            // but it only hosts itself: things the host opens or invokes elsewhere
-            // need a panel or background entry.
+        if (contributes.statusSection || contributes.fileEditors) {
+            // A status section or file editor frame runs code and may use what the
+            // package is granted, but it only hosts itself: things the host opens or
+            // invokes elsewhere need a panel or background entry.
             const needsFrame = [];
             if (contributes.page !== undefined)
                 needsFrame.push('page');
@@ -288,7 +312,7 @@ export const openChamberManifestSchema = z.object({
             if (needsFrame.length > 0)
                 ctx.addIssue({
                     code: 'custom', path: ['panel'],
-                    message: `${needsFrame.map((key) => `contributes.${key}`).join(', ')} needs panel.entry or background.entry; a status section only hosts itself.`,
+                    message: `${needsFrame.map((key) => `contributes.${key}`).join(', ')} needs panel.entry or background.entry; a status section or file editor only hosts itself.`,
                 });
             return;
         }
@@ -383,6 +407,9 @@ const failureFromIssue = (issue) => {
     if (path.startsWith('contributes.filesystem')) {
         return fail('invalid-filesystem', 'contributes.filesystem lists 1 to 16 patterns starting with "/" or "~/", without "..", empty segments, or backslashes.');
     }
+    if (path.startsWith('contributes.origins')) {
+        return fail('invalid-origins', `contributes.origins lists 1 to ${GUEST_ORIGINS_MAX} unique https origins like "https://fonts.example.com", without a path.`);
+    }
     if (path.startsWith('contributes.actions')) {
         return fail('invalid-actions', 'contributes.actions lists up to 8 entries with a unique kebab-case id, a label of 1 to 40 characters, where "message" or "session", optional roles (message only), and optional payload ["messages"] (session only).');
     }
@@ -392,6 +419,9 @@ const failureFromIssue = (issue) => {
     if (path.startsWith('contributes.tools')) {
         return fail('invalid-tools', 'contributes.tools lists up to 16 entries with a match of 1 to 128 characters ([A-Za-z0-9_.:-], "*" only at the end), optional name (1 to 40), icon (Remixicon name or package .svg path), title and subtitle templates (1 to 200), output "auto" | "text" | "json" | "markdown" | "code" | "table", language (code only), and columns (table only, 1 to 16).');
     }
+    if (path.startsWith('contributes.fileEditors')) {
+        return fail('invalid-file-editors', `contributes.fileEditors lists 1 to ${GUEST_FILE_EDITORS_MAX} editors with a unique kebab-case id, a title of 1 to ${GUEST_FILE_EDITOR_TITLE_MAX} characters, match: 1 to ${GUEST_FILE_EDITOR_PATTERNS_MAX} file-name patterns (no "/", not only wildcards, like "*.excalidraw"), an entry ending in .html inside the package, and optional content "text" or "binary".`);
+    }
     if (path.startsWith('contributes.integration')) {
         return fail('invalid-integration', 'contributes.integration needs a name, description, and oauth, token, or host.');
     }

package/dist/protocol.d.ts

@@ -145,6 +145,7 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
             page: "page";
             background: "background";
             status: "status";
+            file: "file";
         }>;
         connection: z.ZodObject<{
             connected: z.ZodBoolean;
@@ -787,6 +788,41 @@ 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<"file-open">;
+    payload: z.ZodUnion<readonly [z.ZodObject<{
+        path: z.ZodString;
+        name: z.ZodString;
+        readOnly: z.ZodBoolean;
+        encoding: z.ZodLiteral<"text">;
+        content: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        path: z.ZodString;
+        name: z.ZodString;
+        readOnly: z.ZodBoolean;
+        encoding: z.ZodLiteral<"binary">;
+        bytes: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+    }, z.core.$strip>]>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file-snapshot">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        purpose: z.ZodEnum<{
+            save: "save";
+            handoff: "handoff";
+        }>;
+    }, z.core.$strip>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file-saved">;
+    payload: z.ZodObject<{
+        version: z.ZodString;
+    }, 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">;
@@ -1157,6 +1193,38 @@ 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<"file-snapshot-result">;
+    id: z.ZodString;
+    payload: z.ZodUnion<readonly [z.ZodObject<{
+        snapshot: z.ZodUnion<readonly [z.ZodObject<{
+            content: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            bytes: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+            version: z.ZodString;
+        }, z.core.$strip>]>;
+    }, z.core.$strip>, z.ZodObject<{
+        error: z.ZodString;
+    }, z.core.$strip>]>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file-change">;
+    payload: z.ZodObject<{
+        dirty: z.ZodBoolean;
+        edited: z.ZodBoolean;
+    }, z.core.$strip>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file-save">;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"file-unsupported">;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
 }, z.core.$strip>], "type">;
 type HostWire = z.input<typeof hostMessageSchema>;
 type GuestWire = z.input<typeof guestMessageSchema>;

package/dist/protocol.js

@@ -2,6 +2,11 @@ import { z } from 'zod';
 import { guestSessionWorktreeSchema, guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceQuerySchema, guestWorkspaceSnapshotSchema } from "./workspace-schemas.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";
+// Structured clone recreates a frame's Uint8Array in the receiving realm, so
+// `instanceof` holds for bytes that crossed postMessage.
+const fileBytesSchema = z.instanceof(Uint8Array).refine((bytes) => bytes.byteLength <= GUEST_FILE_EDITOR_CONTENT_MAX);
+const fileTextSchema = z.string().max(GUEST_FILE_EDITOR_CONTENT_MAX);
 const envelope = {
     channel: z.literal(OPENCHAMBER_SDK_CHANNEL),
     v: z.literal(OPENCHAMBER_SDK_API_VERSION),
@@ -146,7 +151,7 @@ const readyPayloadSchema = z.object({
     locale: z.string().min(1),
     directory: z.string().nullable(),
     session: sessionSnapshotSchema,
-    surface: z.enum(['panel', 'dialog', 'page', 'background', 'status']),
+    surface: z.enum(['panel', 'dialog', 'page', 'background', 'status', 'file']),
     connection: guestConnectionSchema,
     settings: guestSettingsSchema,
     item: guestItemSchema,
@@ -259,6 +264,37 @@ export const hostMessageSchema = z.union([
         id: z.string().min(1),
         payload: z.union([messageItemSchema, sessionItemSchema]),
     }),
+    z.object({
+        ...envelope,
+        type: z.literal('file-open'),
+        payload: z.union([
+            z.object({
+                path: z.string().min(1).max(4096),
+                name: z.string().min(1).max(1024),
+                readOnly: z.boolean(),
+                encoding: z.literal('text'),
+                content: fileTextSchema,
+            }),
+            z.object({
+                path: z.string().min(1).max(4096),
+                name: z.string().min(1).max(1024),
+                readOnly: z.boolean(),
+                encoding: z.literal('binary'),
+                bytes: fileBytesSchema,
+            }),
+        ]),
+    }),
+    z.object({
+        ...envelope,
+        type: z.literal('file-snapshot'),
+        id: z.string().min(1),
+        payload: z.object({ purpose: z.enum(['save', 'handoff']) }),
+    }),
+    z.object({
+        ...envelope,
+        type: z.literal('file-saved'),
+        payload: z.object({ version: z.string().max(GUEST_FILE_EDITOR_VERSION_MAX) }),
+    }),
 ]);
 const filePathSchema = z.string().min(1).max(GUEST_FILE_PATH_MAX).refine(isGuestFilePath);
 export const guestMessageSchema = z.discriminatedUnion('type', [
@@ -468,6 +504,27 @@ export const guestMessageSchema = z.discriminatedUnion('type', [
             z.object({ error: z.string().trim().min(1).max(GUEST_RESOLVE_ERROR_MAX) }),
         ]),
     }),
+    z.object({
+        ...envelope,
+        type: z.literal('file-snapshot-result'),
+        id: z.string().min(1),
+        payload: z.union([
+            z.object({
+                snapshot: z.union([
+                    z.object({ content: fileTextSchema, version: z.string().max(GUEST_FILE_EDITOR_VERSION_MAX) }),
+                    z.object({ bytes: fileBytesSchema, version: z.string().max(GUEST_FILE_EDITOR_VERSION_MAX) }),
+                ]),
+            }),
+            z.object({ error: z.string().trim().min(1).max(GUEST_RESOLVE_ERROR_MAX) }),
+        ]),
+    }),
+    z.object({
+        ...envelope,
+        type: z.literal('file-change'),
+        payload: z.object({ dirty: z.boolean(), edited: z.boolean() }),
+    }),
+    z.object({ ...envelope, type: z.literal('file-save') }),
+    z.object({ ...envelope, type: z.literal('file-unsupported') }),
 ]);
 // The hand-written contract types and the schemas must describe the same wire
 // shapes; either drifting from the other fails this file's type-check.

package/package.json

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