@openchamber/sdk 2.5.1 → 2.5.2

package/API.md

@@ -215,7 +215,7 @@ Await subscription registration to handle refusal, then retain its returned unsu
 
 Snapshots carry `state: 'loading' | 'ready' | 'error'`; session snapshots also carry per-directory `coverage`. Loading/error may retain data. Only `ready` establishes complete empty success. Reads use existing shared stores and hydration, never a git scan per extension request.
 
-Projects contain `id`, `name`, `directory`. Worktrees contain `directory`, `name`, `branch`, and `status: 'ready' | 'pending' | 'invalid' | 'missing'`. Session records contain `id`, `title`, `projectId`, `directory`, `parentId`, `createdAt`, `updatedAt`, `archivedAt`, `worktree`, `activity`, `outcome`, and `items`. Item references contain only this extension's `id` and optional `data`.
+Projects contain `id`, `name`, `directory`. Worktrees contain `directory`, `name`, `branch`, and `status: 'ready' | 'pending' | 'invalid' | 'missing'`. Session records contain `id`, `title`, `projectId`, `directory`, `parentId`, `createdAt`, `updatedAt`, `archivedAt`, `worktree`, `activity`, `outcome`, `items`, and `links`. Item references contain only this extension's `id` and optional `data`. `links` is every thread linked to the session, whoever linked it (the user, the agent through `session.link`, this extension or another), each with `title`, `url`, `kind: 'issue' | 'change'` (`change` is a pull, merge or change request) and `linkedAt`; read-only, and a change to it sends a new snapshot. Hosts older than this field omit it.
 
 `activity` is `unknown`, `idle`, `running`, `retrying`, `waiting-permission`, or `waiting-question` (the agent put a form to the user and is waiting on the answer). `outcome` is the last observed `completed` or `failed` turn, or `null` when unknown or working. Outcomes are in memory for the latest 2,000 observed sessions, reset on runtime switch, and are not reconstructed from persisted history. A later idle event preserves an observed failure until another run starts. `completed` never means the extension's task is Done. Blocking-request contents and approve/reply actions are not exposed.
 
@@ -253,6 +253,31 @@ Omit `options`, or pass `{ scope: 'instance' }`, for this existing server-owned
 
 `setStatusControls` accepts zero to four declarations. A button is `{ kind: 'button', id, label, disabled? }`; a select is `{ kind: 'select', id, label, value, options, disabled? }`, with one to 16 unique options and a selected value in that list. IDs are kebab-case and at most 40 characters; labels are 1 to 60 characters; option values are 1 to 80 characters. Register `onStatusControl` synchronously after `connectHost`, then feature-gate `setStatusControls` with `features.statusControls`. Buttons receive no `value`; select events carry a declared value. The host rejects stale, unknown, disabled, or invalid controls. It accepts at most 20 changed control publications per second per frame and avoids semantic no-op updates. Controls exist only for the expanded, mounted status frame that registered them. Folding or hiding the section removes controls and listeners. A project change clears header controls; publish them again from `onDirectory`. Workspace subscriptions remain active. Old hosts return `UNSUPPORTED`; keep a body control visible until `setStatusControls` succeeds.
 
+#### Sections the app draws
+
+With `source`, the app draws the section itself and loads no frame: `{ source: { path: '/status', interval?: 2000 }, title?: 'Resources' }`. It needs `contributes.service`; a section with a source and no `entry` needs no `panel.entry` either. While the section is shown and expanded, the app sends `GET /status` to your service, then again `interval` ms (1000 to 60000, default 2000) after each answer. The query carries `locale` (the app's language, such as `uk` or `pt-BR`) and `directory` when the panel shows a project. Answer with JSON:
+
+```json
+{
+  "rows": [
+    { "kind": "line", "id": "cpu", "label": "CPU", "content": { "kind": "bar", "value": 25, "tone": "info" }, "value": "25%" },
+    { "kind": "line", "id": "app", "label": "OpenChamber", "value": "1.6 GB",
+      "content": { "kind": "chart", "values": [1.5e9, 1.6e9], "unit": "bytes", "step": 2, "tone": "accent" } },
+    { "kind": "line", "id": "web", "label": "web", "dot": "success",
+      "content": { "kind": "chips", "chips": [{ "id": "port-5173", "label": ":5173", "url": "http://localhost:5173" }] },
+      "actions": [{ "kind": "button", "id": "stop-web", "label": "Stop", "variant": "destructive", "confirm": "Stop web?" }] },
+    { "kind": "note", "id": "hint", "text": "Docker isn't running.", "tone": "warning" }
+  ],
+  "controls": [{ "kind": "button", "id": "refresh", "label": "Refresh" }]
+}
+```
+
+A `line` has a `label` and optionally an `icon` (a Remixicon name; an unknown one is left out), a status `dot`, one `content`, a `value` with `valueTone`, a `badge` `{ label, tone? }`, a `tooltip`, and up to two `actions`. `content` is a `bar` (`value` 0 to 100), a `chart` (`values` oldest first, at most 120; `max`; `unit` `bytes`, `percent` or `count` for the hover label; `step` seconds between points), `chips` (one to six, each with an optional `http(s)` `url` the chip opens), `text`, or a `segmented` choice of two to four options. Actions are a `button` (`variant` `default`, `outline` or `destructive`; `confirm` asks on the first click and acts on the second), a `switch` (`checked`), or a `select`. A `note` is a line of text, `muted` by default or tinted `info`, `warning` or `error`. `controls` are header controls in the `setStatusControls` shape. Tones are `default`, `muted`, `accent`, `success`, `warning`, `error` and `info`; the app takes their colours from its theme. At most 16 rows. Row ids are unique, and so are control ids across the whole answer. Types: `GuestStatusView` and friends in `@openchamber/sdk`; the app checks answers with `guestStatusViewSchema` from `@openchamber/sdk/schemas` and shows an error instead of an answer that does not parse.
+
+When the user activates a control, the app posts `{ "id": "stop-web" }` to the same path, with `value` for a choice (`on` or `off` for a switch), and reads the section again as soon as you answer. Answer 2xx when it worked; otherwise the app shows an error toast with your `{ "message": "..." }` when the body has one. The choice shows at once and stays until a reading taken after your answer.
+
+Keep `entry` beside `source` to support OpenChamber versions that predate it: they ignore `source` and load the frame. Web and desktop only, like every status section.
+
 ### 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`.

package/DOCUMENTATION.md

@@ -27,7 +27,8 @@ Public author pages live in `packages/docs/content/docs/sdk.mdx`, `sdk/host.mdx`
 
 - Extension activity uses `useConfigStore.isConnected` plus live status records and directory `sessionStatusReady` authority. `useUIStore.eventStreamStatus` is an unmaintained diagnostic field, not a connection gate; its default `idle` must not hide known running or idle sessions as `unknown`.
 
-- `contributes.statusSection` is `true` or `{ entry, title?, height?, defaultExpanded?, requiresProject? }` (`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). `defaultExpanded` defaults to true and only applies when the user has no saved expansion choice. `requiresProject` defaults to false; when true, the actual Work Status directory controls both presence and body rendering. `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. Host-rendered controls exist only after a mounted, expanded status frame calls `setStatusControls`; folding, hiding, or retiring the frame removes them. A project change clears header controls; publish them again from `onDirectory`. Workspace subscriptions remain active.
+- `contributes.statusSection` is `true` or `{ entry?, source?, title?, height?, defaultExpanded?, requiresProject? }` (`StatusSectionContribution`), the object form with `entry`, `source`, or both. `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). `defaultExpanded` defaults to true and only applies when the user has no saved expansion choice. `requiresProject` defaults to false; when true, the actual Work Status directory controls both presence and body rendering. `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. Host-rendered controls exist only after a mounted, expanded status frame calls `setStatusControls`; folding, hiding, or retiring the frame removes them. A project change clears header controls; publish them again from `onDirectory`. Workspace subscriptions remain active.
+- `contributes.statusSection.source` is `{ path, interval? }` (`StatusSectionSource`, `src/status-view.ts`): a section the host draws itself, with no frame. While the section is shown and expanded the host reads `GET path` from the extension's service through `/api/guests/:id/service/request`, the next read `interval` ms after the last one finished (`GUEST_STATUS_SOURCE_INTERVAL_MIN`..`MAX`, default 2000, resolved by `resolveStatusSectionSource`), with `query.locale` and, when the panel has a project, `query.directory`. The answer is a `GuestStatusView`: up to 16 rows, each a `line` (label, optional icon, dot, content, value, badge, tooltip, up to two actions) or a `note`; content is a `bar`, `chart`, `chips`, `text` or `segmented` choice; actions are a `button` (optional two-click `confirm`), `switch` or `select`; `controls` are header controls in the `setStatusControls` shape. Colours are theme tones (`GuestStatusTone`), never CSS. The host parses the answer with `guestStatusViewSchema` (`src/status-view-schemas.ts`, exported from `@openchamber/sdk/schemas`), which asserts at compile time that it equals the type, and refuses the whole answer when it does not parse. Activating a control posts `{ id, value? }` (`GuestStatusActionEvent`; a switch sends `on` or `off`) to the same path; a non-2xx answer may carry `{ message }` for the host's error toast. A source needs `contributes.service` (`invalid-status-section` without one) and makes the host the service's caller, so a source-only package needs no `panel.entry` or `background.entry` for its service; frame-only declarations (`capabilities`, `integration`, `filesystem`) still do. A section that declares both is drawn from `source` by hosts that know it; older hosts strip the unknown key and load `entry`, so an extension keeps `entry` for as long as it supports them.
 - `openSurface(surfaceId)` posts `open-surface { surfaceId }`; an id that is not a context panel surface is `HOST_REJECTED`. The host (`lib/guests/open-surface.ts`) opens it the way its rail icon does, under the frame's directory, or under the directory the rail shows when the frame has none (a Work Status section in a chat draft without a project has none of its own). The result follows what the panel shows afterwards: a surface already on screen stays open where the icon would toggle it closed; one that did not open (`chat`, which needs a session beside it) is `UNSUPPORTED`; no directory yet is `NO_DIRECTORY`. VS Code and mobile answer `UNSUPPORTED` explicitly. A resolved call means the surface is on screen.
 - `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.
@@ -99,7 +100,7 @@ Actions, commands, and the badge are host chrome too. `useGuestActions` (`packag
 
 Add a type when the host grows that hole, not before. Any new `connectHost` method ships with a `PluginPane` / `answerGuestMessage` branch in the same change.
 
-Rebuild every example bundle after an SDK change (`bunx openchamber-guest-bundle` per entry, see `examples/README.md`); the built files are checked in.
+Rebuild every example bundle after an SDK change (`bunx openchamber-guest-bundle` per entry, see `examples/README.md`); the built files are checked in. A Bun upgrade needs the same rebuild: the minifier names identifiers differently between releases, so a panel bundle built by the previous Bun no longer matches and `examples.test.ts` fails for every PR until the bundles are regenerated. Service bundles are not minified and keep matching.
 
 ## Anchored popovers
 

package/dist/index.d.ts

@@ -1,15 +1,17 @@
 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, GuestStorageOptions, GuestStorageScope, GuestSessionWorktree } from './workspace.ts';
+export type { GuestLoadState, GuestProject, GuestWorktree, GuestSessionActivity, GuestSessionRecord, GuestSessionLink, GuestDirectoryCoverage, GuestProjectsSnapshot, GuestWorktreesSnapshot, GuestSessionsSnapshot, GuestWorkspaceSnapshot, GuestWorkspaceQuery, GuestWorkspaceSubscription, GuestWorkspaceUpdate, GuestStorageRequest, GuestStorageResult, GuestStorageOptions, GuestStorageScope, GuestSessionWorktree } from './workspace.ts';
 export { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_VALUE_BYTES, GUEST_STORAGE_TOTAL_BYTES, GUEST_DEVICE_STORAGE_TOTAL_BYTES } from './workspace.ts';
 export type { GuestRunningShell, GuestEndedShell, GuestShellEndStatus, GuestRunningShellsSnapshot, GuestShellsScope, GuestShellsSubscription, GuestShellOutputRequest, GuestShellOutputResult, GuestShellStopResult, } from './shells.ts';
 export { GUEST_SHELL_END_STATUSES, GUEST_SHELL_ID_MAX, GUEST_SHELLS_MAX, GUEST_SHELL_OUTPUT_TAIL_MAX, } from './shells.ts';
 export { GUEST_STATUS_CONTROLS_MAX, GUEST_STATUS_CONTROL_ID, GUEST_STATUS_CONTROL_LABEL_MAX, GUEST_STATUS_CONTROL_OPTIONS_MAX, GUEST_STATUS_CONTROL_VALUE_MAX } from './status-controls.ts';
 export type { GuestStatusControl, GuestStatusControlEvent, GuestStatusControlOption } from './status-controls.ts';
+export { GUEST_STATUS_SOURCE_INTERVAL_DEFAULT, GUEST_STATUS_SOURCE_INTERVAL_MAX, GUEST_STATUS_SOURCE_INTERVAL_MIN, GUEST_STATUS_VIEW_ACTIONS_MAX, GUEST_STATUS_VIEW_CHART_POINTS_MAX, GUEST_STATUS_VIEW_CHIPS_MAX, GUEST_STATUS_VIEW_ICON, GUEST_STATUS_VIEW_NOTE_MAX, GUEST_STATUS_VIEW_ROWS_MAX, GUEST_STATUS_VIEW_SEGMENTS_MAX, GUEST_STATUS_VIEW_SEGMENTS_MIN, GUEST_STATUS_VIEW_TEXT_MAX, } from './status-view.ts';
+export type { GuestStatusAction, GuestStatusActionEvent, GuestStatusChartUnit, GuestStatusChip, GuestStatusContent, GuestStatusRow, GuestStatusTone, GuestStatusView, StatusSectionSource, } from './status-view.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_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, SOURCE_CONTROL_DEFAULT_INSTANCES_MAX, SOURCE_CONTROL_GUEST_ID_MAX, SOURCE_CONTROL_URL_TEMPLATES_MAX, SOURCE_CONTROL_URL_TEMPLATE_MAX, SOURCE_CONTROL_URL_TOKENS, sourceControlProviderIdOf, toPublicService, toPublicSourceControl, 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, resolveStatusSectionSource, resolveAttachMode, resolveIntegrationApi, resolveIntegrationAuth, serviceProvides, SOURCE_CONTROL_DEFAULT_INSTANCES_MAX, SOURCE_CONTROL_GUEST_ID_MAX, SOURCE_CONTROL_URL_TEMPLATES_MAX, SOURCE_CONTROL_URL_TEMPLATE_MAX, SOURCE_CONTROL_URL_TOKENS, sourceControlProviderIdOf, toPublicService, toPublicSourceControl, 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, PublicSourceControl, SourceControlCapabilities, SourceControlContribution, SourceControlMergeMethod, 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';

package/dist/index.js

@@ -4,8 +4,9 @@ export { guestFramePolicy } from './frame-policy.js';
 export { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_VALUE_BYTES, GUEST_STORAGE_TOTAL_BYTES, GUEST_DEVICE_STORAGE_TOTAL_BYTES } from './workspace.js';
 export { GUEST_SHELL_END_STATUSES, GUEST_SHELL_ID_MAX, GUEST_SHELLS_MAX, GUEST_SHELL_OUTPUT_TAIL_MAX, } from './shells.js';
 export { GUEST_STATUS_CONTROLS_MAX, GUEST_STATUS_CONTROL_ID, GUEST_STATUS_CONTROL_LABEL_MAX, GUEST_STATUS_CONTROL_OPTIONS_MAX, GUEST_STATUS_CONTROL_VALUE_MAX } from './status-controls.js';
+export { GUEST_STATUS_SOURCE_INTERVAL_DEFAULT, GUEST_STATUS_SOURCE_INTERVAL_MAX, GUEST_STATUS_SOURCE_INTERVAL_MIN, GUEST_STATUS_VIEW_ACTIONS_MAX, GUEST_STATUS_VIEW_CHART_POINTS_MAX, GUEST_STATUS_VIEW_CHIPS_MAX, GUEST_STATUS_VIEW_ICON, GUEST_STATUS_VIEW_NOTE_MAX, GUEST_STATUS_VIEW_ROWS_MAX, GUEST_STATUS_VIEW_SEGMENTS_MAX, GUEST_STATUS_VIEW_SEGMENTS_MIN, GUEST_STATUS_VIEW_TEXT_MAX, } from './status-view.js';
 export { compareOpenChamberVersions, hostMeetsOpenChamberEngine, openChamberEngineMinimum, OPENCHAMBER_ENGINE_PATTERN, parseOpenChamberVersion, } from './host-version.js';
-export { DECLARED_GUEST_CAPABILITIES, GUEST_ACTIONS_MAX, GUEST_ACTION_LABEL_MAX, GUEST_CAPABILITIES, GUEST_COMMANDS_MAX, GUEST_COMMAND_DESCRIPTION_MAX, GUEST_COMMAND_NAME, GUEST_TOOLS_MAX, GUEST_TOOL_COLUMNS_MAX, GUEST_TOOL_COLUMN_MAX, GUEST_TOOL_LANGUAGE_MAX, GUEST_TOOL_MATCH, GUEST_TOOL_MATCH_MAX, GUEST_TOOL_NAME_MAX, GUEST_TOOL_OUTPUTS, GUEST_TOOL_TEMPLATE_MAX, GUEST_TOOL_TEMPLATE_VALUE_MAX, guestActionsNeedConversation, GUEST_FILESYSTEM_PATTERN_MAX, GUEST_FILESYSTEM_PATTERNS_MAX, GUEST_ORIGINS_MAX, GUEST_SERVICE_PROVIDES, GUEST_SURFACE_DOCKS, GUEST_SURFACE_DOCK_DEFAULT, GUEST_SURFACE_DOCK_SIZE_DEFAULT, GUEST_SURFACE_DOCK_SIZE_MAX, GUEST_SURFACE_DOCK_SIZE_MIN, GUEST_STATUS_SECTION_HEIGHT_DEFAULT, GUEST_STATUS_SECTION_HEIGHT_MAX, GUEST_STATUS_SECTION_HEIGHT_MIN, GUEST_STATUS_SECTION_TITLE_MAX, clampStatusSectionHeight, HOST_LINEAR_API_ORIGIN, isGuestFilesystemPattern, hasGuestCapability, hasGuestPage, isGuestApproved, isGuestPackageSvgIcon, requestedGuestCapabilities, resolveAttachEntry, resolvePageEntry, resolveStatusSectionEntry, resolveAttachMode, resolveIntegrationApi, resolveIntegrationAuth, serviceProvides, SOURCE_CONTROL_DEFAULT_INSTANCES_MAX, SOURCE_CONTROL_GUEST_ID_MAX, SOURCE_CONTROL_URL_TEMPLATES_MAX, SOURCE_CONTROL_URL_TEMPLATE_MAX, SOURCE_CONTROL_URL_TOKENS, sourceControlProviderIdOf, toPublicService, toPublicSourceControl, 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, resolveStatusSectionSource, resolveAttachMode, resolveIntegrationApi, resolveIntegrationAuth, serviceProvides, SOURCE_CONTROL_DEFAULT_INSTANCES_MAX, SOURCE_CONTROL_GUEST_ID_MAX, SOURCE_CONTROL_URL_TEMPLATES_MAX, SOURCE_CONTROL_URL_TEMPLATE_MAX, SOURCE_CONTROL_URL_TOKENS, sourceControlProviderIdOf, toPublicService, toPublicSourceControl, 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 { GUEST_POPOVER_COORDINATE_MAX, GUEST_POPOVER_DATA_DEPTH_MAX, GUEST_POPOVER_DATA_MAX, GUEST_POPOVER_HEIGHT_MAX, GUEST_POPOVER_HEIGHT_MIN, GUEST_POPOVER_ID, GUEST_POPOVER_SIDES, GUEST_POPOVER_WIDTH_MAX, GUEST_POPOVER_WIDTH_MIN, GUEST_POPOVER_CLOSE_REASONS, isGuestPopoverRequest, } from './popover.js';

package/dist/manifest.d.ts

@@ -1,5 +1,6 @@
 import type { OpenChamberManifestApiVersion } from './api-version.ts';
 import type { FileEditorContribution } from './file-editor.ts';
+import { type StatusSectionSource } from './status-view.ts';
 export declare const PANEL_ID: RegExp;
 /**
  * The extension's identity on the rail, the Extensions card, and the approval
@@ -55,9 +56,15 @@ export type PageContribution = true | {
  * this section and no rail panel. `title` replaces `panel.name` on the section
  * header; `height` is the starting frame height in CSS px before the guest
  * reports its own through `setHeight`.
+ *
+ * `source` makes the host draw the section itself from the service's answers
+ * (`status-view.ts`), without a frame. The object form needs `entry`,
+ * `source`, or both: a host that knows `source` uses it, an older one loads
+ * `entry`.
  */
 export type StatusSectionContribution = true | {
-    entry: string;
+    entry?: string;
+    source?: StatusSectionSource;
     title?: string;
     height?: number;
     defaultExpanded?: boolean;
@@ -524,6 +531,8 @@ export declare const resolvePageEntry: (contributes: Pick<OpenChamberContributes
  * has no panel page to reuse.
  */
 export declare const resolveStatusSectionEntry: (contributes: Pick<OpenChamberContributes, 'panel' | 'statusSection'>) => string | null;
+/** Where the host reads a source-backed section, with the interval resolved; `null` for a frame-only section. */
+export declare const resolveStatusSectionSource: (contributes: Pick<OpenChamberContributes, 'statusSection'>) => Required<StatusSectionSource> | null;
 /** Clamp a requested status section height to what the host allows. */
 export declare const clampStatusSectionHeight: (height: number) => number;
 export type OpenChamberEngines = {

package/dist/manifest.js

@@ -1,3 +1,4 @@
+import { GUEST_STATUS_SOURCE_INTERVAL_DEFAULT } from './status-view.js';
 export const PANEL_ID = /^[a-z][a-z0-9-]*$/;
 export const GUEST_SURFACE_DOCKS = ['top', 'bottom', 'left', 'right'];
 export const GUEST_SURFACE_DOCK_DEFAULT = 'top';
@@ -213,7 +214,14 @@ export const resolveStatusSectionEntry = (contributes) => {
     const section = contributes.statusSection;
     if (!section)
         return null;
-    return section === true ? contributes.panel.entry ?? null : section.entry;
+    return section === true ? contributes.panel.entry ?? null : section.entry ?? null;
+};
+/** Where the host reads a source-backed section, with the interval resolved; `null` for a frame-only section. */
+export const resolveStatusSectionSource = (contributes) => {
+    const section = contributes.statusSection;
+    if (!section || section === true || !section.source)
+        return null;
+    return { path: section.source.path, interval: section.source.interval ?? GUEST_STATUS_SOURCE_INTERVAL_DEFAULT };
 };
 /** Clamp a requested status section height to what the host allows. */
 export const clampStatusSectionHeight = (height) => {

package/dist/parse.d.ts

@@ -37,7 +37,11 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>]>>;
         statusSection: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
-            entry: z.ZodString;
+            entry: z.ZodOptional<z.ZodString>;
+            source: z.ZodOptional<z.ZodObject<{
+                path: z.ZodString;
+                interval: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>;
             title: z.ZodOptional<z.ZodString>;
             height: z.ZodOptional<z.ZodNumber>;
             defaultExpanded: z.ZodOptional<z.ZodBoolean>;
@@ -322,7 +326,11 @@ export declare const packageManifestSchema: z.ZodObject<{
                 title: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>]>>;
             statusSection: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
-                entry: z.ZodString;
+                entry: z.ZodOptional<z.ZodString>;
+                source: z.ZodOptional<z.ZodObject<{
+                    path: z.ZodString;
+                    interval: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>>;
                 title: z.ZodOptional<z.ZodString>;
                 height: z.ZodOptional<z.ZodNumber>;
                 defaultExpanded: z.ZodOptional<z.ZodBoolean>;

package/dist/parse.js

@@ -2,6 +2,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_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, SOURCE_CONTROL_DEFAULT_INSTANCES_MAX, SOURCE_CONTROL_GUEST_ID_MAX, SOURCE_CONTROL_URL_TEMPLATES_MAX, SOURCE_CONTROL_URL_TEMPLATE_MAX, SOURCE_CONTROL_URL_TOKENS, } from './manifest.js';
+import { isGuestRequestPath } from './contract.js';
+import { GUEST_STATUS_SOURCE_INTERVAL_MAX, GUEST_STATUS_SOURCE_INTERVAL_MIN } from './status-view.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) => {
@@ -354,12 +356,16 @@ const contributesSchema = z.object({
             title: z.string().trim().min(1).max(200).optional(),
         })]).optional(),
     statusSection: z.union([z.literal(true), z.object({
-            entry: z.string().trim().refine((value) => isSafeAssetPath(value) && value.toLowerCase().endsWith('.html')),
+            entry: z.string().trim().refine((value) => isSafeAssetPath(value) && value.toLowerCase().endsWith('.html')).optional(),
+            source: z.object({
+                path: z.string().trim().refine(isGuestRequestPath),
+                interval: z.number().int().min(GUEST_STATUS_SOURCE_INTERVAL_MIN).max(GUEST_STATUS_SOURCE_INTERVAL_MAX).optional(),
+            }).strict().optional(),
             title: z.string().trim().min(1).max(GUEST_STATUS_SECTION_TITLE_MAX).optional(),
             height: z.number().int().min(GUEST_STATUS_SECTION_HEIGHT_MIN).max(GUEST_STATUS_SECTION_HEIGHT_MAX).optional(),
             defaultExpanded: z.boolean().optional(),
             requiresProject: z.boolean().optional(),
-        })]).optional(),
+        }).refine((section) => section.entry !== undefined || section.source !== undefined)]).optional(),
     capabilities: z.array(z.enum(DECLARED_GUEST_CAPABILITIES)).max(8).optional(),
     integration: integrationSchema.optional(),
     service: serviceSchema.optional(),
@@ -376,6 +382,10 @@ const contributesSchema = z.object({
 /**
  * Contributions that need either the panel or background execution frame.
  */
+/** A section the host draws from the service's answers: the host is the service's caller. */
+const hasStatusSource = (contributes) => (Boolean(contributes.statusSection && contributes.statusSection !== true && contributes.statusSection.source));
+/** A section the host loads as a frame: `true`, or an object with an `entry`. */
+const hasStatusFrame = (contributes) => (contributes.statusSection === true || Boolean(contributes.statusSection?.entry));
 const runtimeContributions = (contributes) => {
     const declared = [];
     if (contributes.page !== undefined)
@@ -389,7 +399,8 @@ const runtimeContributions = (contributes) => {
     // A service the host starts itself (it provides a role or a surface) needs
     // no frame; one that only answers a panel's `serviceRequest` has no caller
     // without one.
-    if (contributes.service !== undefined && !contributes.service.provides?.length && !contributes.service.surface)
+    if (contributes.service !== undefined && !contributes.service.provides?.length && !contributes.service.surface
+        && !hasStatusSource(contributes))
         declared.push('service');
     if (contributes.filesystem !== undefined)
         declared.push('filesystem');
@@ -441,6 +452,14 @@ export const openChamberManifestSchema = z.object({
             });
             return;
         }
+        // The host reads a source from the extension's service; without one it has nothing to ask.
+        if (hasStatusSource(contributes) && !contributes.service) {
+            ctx.addIssue({
+                code: 'custom', path: ['statusSection', 'source'],
+                message: 'contributes.statusSection.source is read from the extension\'s service; declare contributes.service.',
+            });
+            return;
+        }
         if (hasGuestPage(contributes))
             return;
         if (contributes.background) {
@@ -458,7 +477,7 @@ export const openChamberManifestSchema = z.object({
                 });
             return;
         }
-        if (contributes.statusSection || contributes.fileEditors) {
+        if (hasStatusFrame(contributes) || 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.
@@ -558,7 +577,7 @@ const failureFromIssue = (issue) => {
     if (path === 'contributes.statusSection' || path.startsWith('contributes.statusSection.')) {
         return fail('invalid-status-section', issue.code === 'custom'
             ? issue.message
-            : `contributes.statusSection must be true or { entry: "<package .html>", title?: "1 to ${GUEST_STATUS_SECTION_TITLE_MAX} characters", height?: ${GUEST_STATUS_SECTION_HEIGHT_MIN} to ${GUEST_STATUS_SECTION_HEIGHT_MAX} }.`);
+            : `contributes.statusSection must be true or { entry?: "<package .html>", source?: { path: "/status", interval?: ${GUEST_STATUS_SOURCE_INTERVAL_MIN} to ${GUEST_STATUS_SOURCE_INTERVAL_MAX} }, title?: "1 to ${GUEST_STATUS_SECTION_TITLE_MAX} characters", height?: ${GUEST_STATUS_SECTION_HEIGHT_MIN} to ${GUEST_STATUS_SECTION_HEIGHT_MAX} } with entry, source, or both.`);
     }
     if (path === 'contributes.background' || path.startsWith('contributes.background.')) {
         return fail('invalid-background', 'contributes.background needs an entry ending in .html inside the package.');

package/dist/protocol.d.ts

@@ -89,6 +89,15 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
                     id: z.ZodString;
                     data: z.ZodOptional<z.ZodJSONSchema>;
                 }, z.core.$strip>>;
+                links: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    title: z.ZodString;
+                    url: z.ZodString;
+                    kind: z.ZodEnum<{
+                        change: "change";
+                        issue: "issue";
+                    }>;
+                    linkedAt: z.ZodNumber;
+                }, z.core.$strip>>>;
             }, z.core.$strip>>;
         }, z.core.$strip>], "kind">;
     }, z.core.$strip>;
@@ -503,6 +512,15 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
                 id: z.ZodString;
                 data: z.ZodOptional<z.ZodJSONSchema>;
             }, z.core.$strip>>;
+            links: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                url: z.ZodString;
+                kind: z.ZodEnum<{
+                    change: "change";
+                    issue: "issue";
+                }>;
+                linkedAt: z.ZodNumber;
+            }, z.core.$strip>>>;
         }, z.core.$strip>>;
     }, z.core.$strip>], "kind">, z.ZodObject<{
         output: z.ZodString;
@@ -645,6 +663,12 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
                 id: string;
                 data?: z.util.JSONType | undefined;
             }[];
+            links?: {
+                title: string;
+                url: string;
+                kind: "change" | "issue";
+                linkedAt: number;
+            }[] | undefined;
         }[];
     } | {
         status: number;
@@ -788,6 +812,12 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
                 id: string;
                 data?: z.util.JSONType | undefined;
             }[];
+            links?: {
+                title: string;
+                url: string;
+                kind: "change" | "issue";
+                linkedAt: number;
+            }[] | undefined;
         }[];
     } | {
         status: number;

package/dist/schemas.d.ts

@@ -2,6 +2,7 @@ export { openChamberManifestSchema, PACKAGE_VERSION_PATTERN, packageManifestSche
 export type { ManifestDocument } from './parse.ts';
 export { guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceSnapshotSchema } from './workspace-schemas.ts';
 export { guestStatusControlsSchema, guestStatusControlEventSchema } from './status-control-schemas.ts';
+export { guestStatusViewSchema } from './status-view-schemas.ts';
 export { guestPopoverClosedEventSchema, guestPopoverRequestSchema } from './popover-schemas.ts';
 export { guestMessageSchema, hostMessageSchema, parseGuestMessage, parseHostMessage, } from './protocol.ts';
 export { browserControlActionSchema, browserProviderResultSchema, sourceControlProviderMethodSchema, sourceControlProviderSchemasV1, } from './service-provider-schemas.ts';

package/dist/schemas.js

@@ -4,6 +4,7 @@
 export { openChamberManifestSchema, PACKAGE_VERSION_PATTERN, packageManifestSchema, parseManifest, parseManifestJson, } from './parse.js';
 export { guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceSnapshotSchema } from './workspace-schemas.js';
 export { guestStatusControlsSchema, guestStatusControlEventSchema } from './status-control-schemas.js';
+export { guestStatusViewSchema } from './status-view-schemas.js';
 export { guestPopoverClosedEventSchema, guestPopoverRequestSchema } from './popover-schemas.js';
 export { guestMessageSchema, hostMessageSchema, parseGuestMessage, parseHostMessage, } from './protocol.js';
 export { browserControlActionSchema, browserProviderResultSchema, sourceControlProviderMethodSchema, sourceControlProviderSchemasV1, } from './service-provider-schemas.js';

package/dist/status-view-schemas.d.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+/** A service's answer to `GET <source.path>`. Row ids and control ids are each unique. */
+export declare const guestStatusViewSchema: z.ZodObject<{
+    rows: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"line">;
+        id: z.ZodString;
+        label: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        dot: z.ZodOptional<z.ZodEnum<{
+            accent: "accent";
+            default: "default";
+            error: "error";
+            info: "info";
+            muted: "muted";
+            success: "success";
+            warning: "warning";
+        }>>;
+        content: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"bar">;
+            value: z.ZodNumber;
+            tone: z.ZodOptional<z.ZodEnum<{
+                accent: "accent";
+                default: "default";
+                error: "error";
+                info: "info";
+                muted: "muted";
+                success: "success";
+                warning: "warning";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"chart">;
+            values: z.ZodArray<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            tone: z.ZodOptional<z.ZodEnum<{
+                accent: "accent";
+                default: "default";
+                error: "error";
+                info: "info";
+                muted: "muted";
+                success: "success";
+                warning: "warning";
+            }>>;
+            unit: z.ZodOptional<z.ZodEnum<{
+                bytes: "bytes";
+                count: "count";
+                percent: "percent";
+            }>>;
+            step: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"chips">;
+            chips: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                tone: z.ZodOptional<z.ZodEnum<{
+                    accent: "accent";
+                    default: "default";
+                    error: "error";
+                    info: "info";
+                    muted: "muted";
+                    success: "success";
+                    warning: "warning";
+                }>>;
+                url: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"text">;
+            text: z.ZodString;
+            tone: z.ZodOptional<z.ZodEnum<{
+                accent: "accent";
+                default: "default";
+                error: "error";
+                info: "info";
+                muted: "muted";
+                success: "success";
+                warning: "warning";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"segmented">;
+            id: z.ZodString;
+            label: z.ZodString;
+            value: z.ZodString;
+            options: z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strict>>;
+            disabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>]>>;
+        value: z.ZodOptional<z.ZodString>;
+        valueTone: z.ZodOptional<z.ZodEnum<{
+            accent: "accent";
+            default: "default";
+            error: "error";
+            info: "info";
+            muted: "muted";
+            success: "success";
+            warning: "warning";
+        }>>;
+        badge: z.ZodOptional<z.ZodObject<{
+            label: z.ZodString;
+            tone: z.ZodOptional<z.ZodEnum<{
+                accent: "accent";
+                default: "default";
+                error: "error";
+                info: "info";
+                muted: "muted";
+                success: "success";
+                warning: "warning";
+            }>>;
+        }, z.core.$strict>>;
+        tooltip: z.ZodOptional<z.ZodString>;
+        actions: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"button">;
+            id: z.ZodString;
+            label: z.ZodString;
+            variant: z.ZodOptional<z.ZodEnum<{
+                default: "default";
+                destructive: "destructive";
+                outline: "outline";
+            }>>;
+            confirm: z.ZodOptional<z.ZodString>;
+            disabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"switch">;
+            id: z.ZodString;
+            label: z.ZodString;
+            checked: z.ZodBoolean;
+            disabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"select">;
+            id: z.ZodString;
+            label: z.ZodString;
+            value: z.ZodString;
+            options: z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strict>>;
+            disabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>]>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"note">;
+        id: z.ZodString;
+        text: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            info: "info";
+            muted: "muted";
+            warning: "warning";
+        }>>;
+    }, z.core.$strict>]>>;
+    controls: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"button">;
+        id: z.ZodString;
+        label: z.ZodString;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"select">;
+        id: z.ZodString;
+        label: z.ZodString;
+        value: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>], "kind">>>;
+}, z.core.$strict>;

package/dist/status-view-schemas.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import { guestStatusControlsSchema } from './status-control-schemas.js';
+import { GUEST_STATUS_CONTROL_ID, GUEST_STATUS_CONTROL_LABEL_MAX, GUEST_STATUS_CONTROL_OPTIONS_MAX, GUEST_STATUS_CONTROL_VALUE_MAX, } from './status-controls.js';
+import { GUEST_STATUS_VIEW_ACTIONS_MAX, GUEST_STATUS_VIEW_CHART_POINTS_MAX, GUEST_STATUS_VIEW_CHIPS_MAX, GUEST_STATUS_VIEW_ICON, GUEST_STATUS_VIEW_NOTE_MAX, GUEST_STATUS_VIEW_ROWS_MAX, GUEST_STATUS_VIEW_SEGMENTS_MAX, GUEST_STATUS_VIEW_SEGMENTS_MIN, GUEST_STATUS_VIEW_TEXT_MAX, } from './status-view.js';
+const idSchema = z.string().regex(GUEST_STATUS_CONTROL_ID);
+const labelSchema = z.string().min(1).max(GUEST_STATUS_CONTROL_LABEL_MAX);
+const valueSchema = z.string().min(1).max(GUEST_STATUS_CONTROL_VALUE_MAX);
+const textSchema = z.string().min(1).max(GUEST_STATUS_VIEW_TEXT_MAX);
+const toneSchema = z.enum(['default', 'muted', 'accent', 'success', 'warning', 'error', 'info']);
+const finite = z.number().finite();
+const isWebUrl = (value) => {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+};
+const optionSchema = z.object({ value: valueSchema, label: labelSchema }).strict();
+/** One to `max` options with unique values, and `value` among them. */
+const choiceSchema = (kind, min, max) => z.object({
+    kind: z.literal(kind),
+    id: idSchema,
+    label: labelSchema,
+    value: valueSchema,
+    options: z.array(optionSchema).min(min).max(max),
+    disabled: z.boolean().optional(),
+}).strict().refine((choice) => new Set(choice.options.map((option) => option.value)).size === choice.options.length, { message: 'option values must be unique', path: ['options'] }).refine((choice) => choice.options.some((option) => option.value === choice.value), { message: 'value must be one of its options', path: ['value'] });
+const chipSchema = z.object({
+    id: idSchema,
+    label: labelSchema,
+    tone: toneSchema.optional(),
+    url: z.string().max(2_000).refine(isWebUrl, { message: 'chip url must be http(s)' }).optional(),
+}).strict();
+const contentSchema = z.union([
+    z.object({ kind: z.literal('bar'), value: finite.min(0).max(100), tone: toneSchema.optional() }).strict(),
+    z.object({
+        kind: z.literal('chart'),
+        values: z.array(finite.min(0)).max(GUEST_STATUS_VIEW_CHART_POINTS_MAX),
+        max: finite.positive().optional(),
+        tone: toneSchema.optional(),
+        unit: z.enum(['bytes', 'percent', 'count']).optional(),
+        step: finite.positive().max(3_600).optional(),
+    }).strict(),
+    z.object({
+        kind: z.literal('chips'),
+        chips: z.array(chipSchema).min(1).max(GUEST_STATUS_VIEW_CHIPS_MAX),
+    }).strict(),
+    z.object({ kind: z.literal('text'), text: textSchema, tone: toneSchema.optional() }).strict(),
+    choiceSchema('segmented', GUEST_STATUS_VIEW_SEGMENTS_MIN, GUEST_STATUS_VIEW_SEGMENTS_MAX),
+]);
+const actionSchema = z.union([
+    z.object({
+        kind: z.literal('button'),
+        id: idSchema,
+        label: labelSchema,
+        variant: z.enum(['default', 'outline', 'destructive']).optional(),
+        confirm: labelSchema.optional(),
+        disabled: z.boolean().optional(),
+    }).strict(),
+    z.object({
+        kind: z.literal('switch'),
+        id: idSchema,
+        label: labelSchema,
+        checked: z.boolean(),
+        disabled: z.boolean().optional(),
+    }).strict(),
+    choiceSchema('select', 1, GUEST_STATUS_CONTROL_OPTIONS_MAX),
+]);
+const rowSchema = z.union([
+    z.object({
+        kind: z.literal('line'),
+        id: idSchema,
+        label: labelSchema,
+        icon: z.string().regex(GUEST_STATUS_VIEW_ICON).optional(),
+        dot: toneSchema.optional(),
+        content: contentSchema.optional(),
+        value: valueSchema.optional(),
+        valueTone: toneSchema.optional(),
+        badge: z.object({ label: labelSchema, tone: toneSchema.optional() }).strict().optional(),
+        tooltip: textSchema.optional(),
+        actions: z.array(actionSchema).max(GUEST_STATUS_VIEW_ACTIONS_MAX).optional(),
+    }).strict(),
+    z.object({
+        kind: z.literal('note'),
+        id: idSchema,
+        text: z.string().min(1).max(GUEST_STATUS_VIEW_NOTE_MAX),
+        tone: z.enum(['muted', 'info', 'warning', 'error']).optional(),
+    }).strict(),
+]);
+/** Every id a view's controls answer to: header controls, line actions, segmented choices. */
+const controlIds = (view) => [
+    ...(view.controls ?? []).map((control) => control.id),
+    ...view.rows.flatMap((row) => (row.kind === 'line'
+        ? [
+            ...(row.actions ?? []).map((action) => action.id),
+            ...(row.content?.kind === 'segmented' ? [row.content.id] : []),
+        ]
+        : [])),
+];
+/** A service's answer to `GET <source.path>`. Row ids and control ids are each unique. */
+export const guestStatusViewSchema = z.object({
+    rows: z.array(rowSchema).max(GUEST_STATUS_VIEW_ROWS_MAX),
+    controls: guestStatusControlsSchema.optional(),
+}).strict().refine((view) => new Set(view.rows.map((row) => row.id)).size === view.rows.length, { message: 'row ids must be unique', path: ['rows'] }).refine((view) => {
+    const ids = controlIds(view);
+    return new Set(ids).size === ids.length;
+}, { message: 'control ids must be unique across the view' });
+const assertViewParsed = (value) => value;
+const assertViewContract = (value) => value;
+void assertViewParsed;
+void assertViewContract;

package/dist/status-view.d.ts

@@ -0,0 +1,129 @@
+import type { GuestStatusControl, GuestStatusControlOption } from './status-controls.ts';
+/** Fastest the host asks a service for its section, in ms. */
+export declare const GUEST_STATUS_SOURCE_INTERVAL_MIN = 1000;
+/** Slowest polling a source may ask for, in ms. */
+export declare const GUEST_STATUS_SOURCE_INTERVAL_MAX = 60000;
+/** Polling interval when the manifest names none, in ms. */
+export declare const GUEST_STATUS_SOURCE_INTERVAL_DEFAULT = 2000;
+export declare const GUEST_STATUS_VIEW_ROWS_MAX = 16;
+export declare const GUEST_STATUS_VIEW_ACTIONS_MAX = 2;
+export declare const GUEST_STATUS_VIEW_CHIPS_MAX = 6;
+export declare const GUEST_STATUS_VIEW_CHART_POINTS_MAX = 120;
+export declare const GUEST_STATUS_VIEW_SEGMENTS_MIN = 2;
+export declare const GUEST_STATUS_VIEW_SEGMENTS_MAX = 4;
+export declare const GUEST_STATUS_VIEW_TEXT_MAX = 200;
+export declare const GUEST_STATUS_VIEW_NOTE_MAX = 300;
+export declare const GUEST_STATUS_VIEW_ICON: RegExp;
+/** Where the host reads a source-backed section and how often. */
+export type StatusSectionSource = {
+    /** Service path, such as `/status`. */
+    path: string;
+    /** Milliseconds between reads while the section is on screen. */
+    interval?: number;
+};
+/**
+ * Colours come from the theme, never from the extension: `accent` is the
+ * theme's primary, the status tones are its status colours, `muted` is
+ * secondary text.
+ */
+export type GuestStatusTone = 'default' | 'muted' | 'accent' | 'success' | 'warning' | 'error' | 'info';
+/** How a chart's hover label formats a point. */
+export type GuestStatusChartUnit = 'bytes' | 'percent' | 'count';
+export type GuestStatusChip = {
+    id: string;
+    label: string;
+    tone?: GuestStatusTone;
+    /** An `http(s)` URL the chip opens; without one the chip is a label. */
+    url?: string;
+};
+/** What sits between a line's label and its value. */
+export type GuestStatusContent = {
+    kind: 'bar';
+    value: number;
+    tone?: GuestStatusTone;
+} | {
+    kind: 'chart';
+    /** Oldest first; the newest point sits at the right edge. */
+    values: number[];
+    /** Top of the chart; the largest value when omitted. */
+    max?: number;
+    tone?: GuestStatusTone;
+    unit?: GuestStatusChartUnit;
+    /** Seconds between points, for the hover's "12 s ago". */
+    step?: number;
+} | {
+    kind: 'chips';
+    chips: GuestStatusChip[];
+} | {
+    kind: 'text';
+    text: string;
+    tone?: GuestStatusTone;
+} | {
+    kind: 'segmented';
+    id: string;
+    label: string;
+    value: string;
+    options: GuestStatusControlOption[];
+    disabled?: boolean;
+};
+/** A control at the end of a line. Activating it posts `{ id, value? }` to the source path. */
+export type GuestStatusAction = {
+    kind: 'button';
+    id: string;
+    label: string;
+    variant?: 'default' | 'outline' | 'destructive';
+    /** Asked on the first click; the second click acts. */
+    confirm?: string;
+    disabled?: boolean;
+} | {
+    kind: 'switch';
+    id: string;
+    label: string;
+    checked: boolean;
+    disabled?: boolean;
+} | {
+    kind: 'select';
+    id: string;
+    label: string;
+    value: string;
+    options: GuestStatusControlOption[];
+    disabled?: boolean;
+};
+export type GuestStatusRow = {
+    kind: 'line';
+    id: string;
+    label: string;
+    /** A Remixicon name, as in `panel.icon`. */
+    icon?: string;
+    /** A status dot before the label. */
+    dot?: GuestStatusTone;
+    content?: GuestStatusContent;
+    value?: string;
+    valueTone?: GuestStatusTone;
+    badge?: {
+        label: string;
+        tone?: GuestStatusTone;
+    };
+    tooltip?: string;
+    actions?: GuestStatusAction[];
+} | {
+    kind: 'note';
+    id: string;
+    text: string;
+    tone?: 'muted' | 'info' | 'warning' | 'error';
+};
+/** The answer to `GET <source.path>`. */
+export type GuestStatusView = {
+    rows: GuestStatusRow[];
+    /** Header controls, the same declarations `setStatusControls` takes. */
+    controls?: GuestStatusControl[];
+};
+/**
+ * The body of `POST <source.path>` when the user activates a control. A switch
+ * sends `on` or `off`; a select or segmented control sends the chosen value; a
+ * button sends no value.
+ */
+export type GuestStatusActionEvent = {
+    id: string;
+    value?: string;
+};

package/dist/status-view.js

@@ -0,0 +1,15 @@
+/** Fastest the host asks a service for its section, in ms. */
+export const GUEST_STATUS_SOURCE_INTERVAL_MIN = 1_000;
+/** Slowest polling a source may ask for, in ms. */
+export const GUEST_STATUS_SOURCE_INTERVAL_MAX = 60_000;
+/** Polling interval when the manifest names none, in ms. */
+export const GUEST_STATUS_SOURCE_INTERVAL_DEFAULT = 2_000;
+export const GUEST_STATUS_VIEW_ROWS_MAX = 16;
+export const GUEST_STATUS_VIEW_ACTIONS_MAX = 2;
+export const GUEST_STATUS_VIEW_CHIPS_MAX = 6;
+export const GUEST_STATUS_VIEW_CHART_POINTS_MAX = 120;
+export const GUEST_STATUS_VIEW_SEGMENTS_MIN = 2;
+export const GUEST_STATUS_VIEW_SEGMENTS_MAX = 4;
+export const GUEST_STATUS_VIEW_TEXT_MAX = 200;
+export const GUEST_STATUS_VIEW_NOTE_MAX = 300;
+export const GUEST_STATUS_VIEW_ICON = /^[a-z0-9][a-z0-9-]{0,39}$/;

package/dist/workspace-schemas.d.ts

@@ -91,6 +91,15 @@ export declare const guestWorkspaceSnapshotSchema: z.ZodDiscriminatedUnion<[z.Zo
             id: z.ZodString;
             data: z.ZodOptional<z.ZodJSONSchema>;
         }, z.core.$strip>>;
+        links: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            url: z.ZodString;
+            kind: z.ZodEnum<{
+                change: "change";
+                issue: "issue";
+            }>;
+            linkedAt: z.ZodNumber;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>], "kind">;
 export declare const guestSessionWorktreeSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{

package/dist/workspace-schemas.js

@@ -21,6 +21,7 @@ export const guestWorkspaceSnapshotSchema = z.discriminatedUnion('kind', [
             createdAt: z.number(), updatedAt: z.number(), archivedAt: z.number().nullable(), worktree: worktree.nullable(),
             activity: z.enum(['unknown', 'idle', 'running', 'retrying', 'waiting-permission', 'waiting-question']),
             outcome: z.enum(['completed', 'failed']).nullable(), items: z.array(z.object({ id: identity, data: z.json().optional() })),
+            links: z.array(z.object({ title: z.string(), url: z.string(), kind: z.enum(['issue', 'change']), linkedAt: z.number() })).optional(),
         })),
     }),
 ]);

package/dist/workspace.d.ts

@@ -13,6 +13,17 @@ export type GuestWorktree = {
 };
 /** `waiting-question` means the agent is waiting on an answer — a form it put to the user. */
 export type GuestSessionActivity = 'unknown' | 'idle' | 'running' | 'retrying' | 'waiting-permission' | 'waiting-question';
+/**
+ * A thread linked to a session, by whoever linked it: the user, the agent
+ * (`session.link`), this extension or another. `change` is a code change
+ * under review (a pull, merge or change request).
+ */
+export type GuestSessionLink = {
+    title: string;
+    url: string;
+    kind: 'issue' | 'change';
+    linkedAt: number;
+};
 export type GuestSessionRecord = {
     id: string;
     title: string;
@@ -30,6 +41,8 @@ export type GuestSessionRecord = {
         id: string;
         data?: JsonValue;
     }[];
+    /** Every link on the session, read-only. Absent from hosts older than this field. */
+    links?: GuestSessionLink[];
 };
 export type GuestDirectoryCoverage = {
     directory: string;

package/package.json

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