@openchamber/sdk 1.23.2-preview.1 → 1.24.1

package/dist/host.js

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,4 +1,5 @@
 export { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL, OPENCHAMBER_SDK_MANIFEST_API_VERSIONS } from "./api-version.js";
+export { GUEST_SCROLLBAR_CSS } from "./scrollbar-style.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, HOST_LINEAR_API_ORIGIN, isGuestFilesystemPattern, hasGuestCapability, hasGuestPage, isGuestApproved, isGuestPackageSvgIcon, requestedGuestCapabilities, resolveAttachEntry, resolvePageEntry, resolveAttachMode, resolveIntegrationApi, resolveIntegrationAuth, toPublicService, toPublicIntegration, } from "./manifest.js";

package/dist/manifest.d.ts

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

package/dist/manifest.js

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

package/dist/parse.d.ts

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

package/dist/parse.js

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

package/dist/protocol.d.ts

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

package/dist/protocol.js

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

package/dist/scrollbar-style.d.ts

@@ -0,0 +1,2 @@
+/** Shared by served extension documents and the UI kit, including older guest bundles. */
+export declare const GUEST_SCROLLBAR_CSS = "\n:root {\n  --oc-scrollbar-thumb: color-mix(in srgb, var(--oc-muted, currentColor) 40%, transparent);\n  --oc-scrollbar-thumb-hover: color-mix(in srgb, var(--oc-muted, currentColor) 65%, transparent);\n  scrollbar-gutter: stable;\n}\n* {\n  scrollbar-width: thin;\n  scrollbar-color: var(--oc-scrollbar-thumb) transparent;\n}\n/* Chromium's standard scrollbar properties otherwise override its pseudo-elements. */\n@supports selector(::-webkit-scrollbar) {\n  * { scrollbar-width: auto; scrollbar-color: auto; }\n  ::-webkit-scrollbar { width: 6px; height: 6px; background: transparent; }\n  :root::-webkit-scrollbar, body::-webkit-scrollbar { background: var(--oc-bg, inherit); }\n  ::-webkit-scrollbar-track { background: transparent; }\n  ::-webkit-scrollbar-thumb {\n    background: var(--oc-scrollbar-thumb);\n    border-radius: 999px;\n    min-width: 24px;\n    min-height: 24px;\n  }\n  ::-webkit-scrollbar-thumb:hover { background: var(--oc-scrollbar-thumb-hover); }\n  ::-webkit-scrollbar-corner { background: transparent; }\n  ::-webkit-scrollbar-button { display: none; width: 0; height: 0; }\n}\n@media (forced-colors: active) {\n  * { scrollbar-color: auto; }\n  ::-webkit-scrollbar-thumb, ::-webkit-scrollbar-thumb:hover { background: CanvasText; }\n}\n";

package/dist/scrollbar-style.js

@@ -0,0 +1,32 @@
+/** Shared by served extension documents and the UI kit, including older guest bundles. */
+export const GUEST_SCROLLBAR_CSS = `
+:root {
+  --oc-scrollbar-thumb: color-mix(in srgb, var(--oc-muted, currentColor) 40%, transparent);
+  --oc-scrollbar-thumb-hover: color-mix(in srgb, var(--oc-muted, currentColor) 65%, transparent);
+  scrollbar-gutter: stable;
+}
+* {
+  scrollbar-width: thin;
+  scrollbar-color: var(--oc-scrollbar-thumb) transparent;
+}
+/* Chromium's standard scrollbar properties otherwise override its pseudo-elements. */
+@supports selector(::-webkit-scrollbar) {
+  * { scrollbar-width: auto; scrollbar-color: auto; }
+  ::-webkit-scrollbar { width: 6px; height: 6px; background: transparent; }
+  :root::-webkit-scrollbar, body::-webkit-scrollbar { background: var(--oc-bg, inherit); }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb {
+    background: var(--oc-scrollbar-thumb);
+    border-radius: 999px;
+    min-width: 24px;
+    min-height: 24px;
+  }
+  ::-webkit-scrollbar-thumb:hover { background: var(--oc-scrollbar-thumb-hover); }
+  ::-webkit-scrollbar-corner { background: transparent; }
+  ::-webkit-scrollbar-button { display: none; width: 0; height: 0; }
+}
+@media (forced-colors: active) {
+  * { scrollbar-color: auto; }
+  ::-webkit-scrollbar-thumb, ::-webkit-scrollbar-thumb:hover { background: CanvasText; }
+}
+`;

package/dist/ui/menu.js

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

package/dist/ui/select.js

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