@openchamber/sdk 1.24.2 → 2.0.1

package/dist/manifest.d.ts

@@ -10,7 +10,24 @@ export type PanelContribution = {
     name: string;
     icon: string;
     entry?: string;
+    /**
+     * Beside a shared surface (`service.surface`), the panel page is docked to
+     * one edge of the host-drawn picture: a toolbar above it, an inspector
+     * below, a tool column beside it. `dock` is the edge (default
+     * `GUEST_SURFACE_DOCK_DEFAULT`) and `size` the page's thickness in CSS
+     * pixels across that edge (default `GUEST_SURFACE_DOCK_SIZE_DEFAULT`).
+     * Both only make sense with `entry` and `service.surface` together.
+     */
+    dock?: GuestSurfaceDock;
+    size?: number;
 };
+export declare const GUEST_SURFACE_DOCKS: readonly ["top", "bottom", "left", "right"];
+export type GuestSurfaceDock = (typeof GUEST_SURFACE_DOCKS)[number];
+export declare const GUEST_SURFACE_DOCK_DEFAULT: GuestSurfaceDock;
+/** Thickness in CSS px of a docked `panel.entry` when the manifest names none. */
+export declare const GUEST_SURFACE_DOCK_SIZE_DEFAULT = 40;
+export declare const GUEST_SURFACE_DOCK_SIZE_MIN = 24;
+export declare const GUEST_SURFACE_DOCK_SIZE_MAX = 480;
 /** Sandboxed HTML loaded on demand for background actions and slash commands. */
 export type BackgroundContribution = {
     entry: string;
@@ -31,6 +48,26 @@ export type PageContribution = true | {
     entry: string;
     title?: string;
 };
+/**
+ * A section inside the chat's Work Status panel. `true` reuses `panel.entry`;
+ * the object form names its own package HTML, so an extension can ship only
+ * 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`.
+ */
+export type StatusSectionContribution = true | {
+    entry: string;
+    title?: string;
+    height?: number;
+};
+/** Characters in a status section title. */
+export declare const GUEST_STATUS_SECTION_TITLE_MAX = 60;
+/** Smallest frame height the host gives a status section, in CSS px. */
+export declare const GUEST_STATUS_SECTION_HEIGHT_MIN = 24;
+/** Tallest frame height the host gives a status section; taller content scrolls inside the frame. */
+export declare const GUEST_STATUS_SECTION_HEIGHT_MAX = 320;
+/** Frame height before the manifest or the guest says otherwise. */
+export declare const GUEST_STATUS_SECTION_HEIGHT_DEFAULT = 120;
 export type GuestActionWhere = 'message' | 'session';
 export type GuestActionRole = 'user' | 'assistant';
 /** What a session action wants alongside the session id and title. */
@@ -199,18 +236,37 @@ export type PublicSocketBinding = {
     resolved: string | null;
     override: string | null;
 };
+/**
+ * Host roles a service can stand in for. `browser` answers the agent's
+ * `browser.*` actions in place of the in-app browser view; the contract is in
+ * `service-providers.ts`. A service that provides a role needs no panel or
+ * background entry: the host starts it on the first action.
+ */
+export declare const GUEST_SERVICE_PROVIDES: readonly ["browser"];
+export type GuestServiceProvides = (typeof GUEST_SERVICE_PROVIDES)[number];
 export type ServiceContribution = {
     entry: string;
     runtime: 'host';
     permissions?: ServicePermissions;
+    provides?: GuestServiceProvides[];
+    /**
+     * The service shows a live surface (frames out, input in) that the host
+     * draws in this extension's rail panel; see `service-surface.ts`. With
+     * `panel.entry` too, that page is docked to one edge of the picture (see
+     * `PanelContribution.dock`); without it, the panel is the surface alone.
+     */
+    surface?: true;
 };
 /** Catalog card for a local service. Drops nothing secret; grant is host state. */
 export type PublicService = {
     runtime: 'host';
     permissions?: PublicServicePermissions;
     socketBindings?: PublicSocketBinding[];
+    provides?: GuestServiceProvides[];
+    surface?: true;
     granted: boolean;
 };
+export declare const serviceProvides: (service: Pick<ServiceContribution, "provides"> | undefined, role: GuestServiceProvides) => boolean;
 /**
  * What a guest may do beyond drawing its own panel. The user approves the
  * full list once, when the package is installed; a later package that asks
@@ -240,6 +296,8 @@ export type OpenChamberContributes = {
     background?: BackgroundContribution;
     attach?: AttachContribution;
     page?: PageContribution;
+    /** A section in the chat's Work Status panel. */
+    statusSection?: StatusSectionContribution;
     capabilities?: DeclaredGuestCapability[];
     integration?: IntegrationContribution;
     service?: ServiceContribution;
@@ -274,6 +332,14 @@ export declare const resolveAttachMode: (attach: AttachContribution | undefined)
  */
 export declare const resolveAttachEntry: (contributes: Pick<OpenChamberContributes, "attach">) => string | null;
 export declare const resolvePageEntry: (contributes: Pick<OpenChamberContributes, "panel" | "page">) => string | null;
+/**
+ * The HTML the Work Status section loads: `panel.entry` for `true`, the
+ * object's own `entry` otherwise, `null` when nothing is declared or `true`
+ * has no panel page to reuse.
+ */
+export declare const resolveStatusSectionEntry: (contributes: Pick<OpenChamberContributes, "panel" | "statusSection">) => string | null;
+/** Clamp a requested status section height to what the host allows. */
+export declare const clampStatusSectionHeight: (height: number) => number;
 export type OpenChamberEngines = {
     openchamber: string;
 };
@@ -282,7 +348,7 @@ export type OpenChamberManifest = {
     engines?: OpenChamberEngines;
     contributes: OpenChamberContributes;
 };
-export type ParseManifestErrorCode = 'not-object' | 'missing-openchamber' | 'unsupported-api-version' | 'invalid-engines' | 'invalid-version' | 'missing-panel' | 'invalid-panel' | 'invalid-panel-id' | 'invalid-panel-name' | 'invalid-panel-icon' | 'invalid-panel-entry' | 'invalid-background' | 'invalid-attach' | 'invalid-page' | 'invalid-capabilities' | 'invalid-integration' | 'invalid-service' | 'invalid-filesystem' | 'invalid-actions' | 'invalid-commands' | 'invalid-tools';
+export type ParseManifestErrorCode = 'not-object' | 'missing-openchamber' | 'unsupported-api-version' | 'invalid-engines' | 'invalid-version' | 'missing-panel' | 'invalid-panel' | 'invalid-panel-id' | 'invalid-panel-name' | 'invalid-panel-icon' | 'invalid-panel-entry' | 'invalid-background' | 'invalid-attach' | 'invalid-page' | 'invalid-status-section' | 'invalid-capabilities' | 'invalid-integration' | 'invalid-service' | 'invalid-filesystem' | 'invalid-actions' | 'invalid-commands' | 'invalid-tools';
 export type ParseManifestFailure = {
     ok: false;
     code: ParseManifestErrorCode;

package/dist/manifest.js

@@ -1,4 +1,18 @@
 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';
+/** Thickness in CSS px of a docked `panel.entry` when the manifest names none. */
+export const GUEST_SURFACE_DOCK_SIZE_DEFAULT = 40;
+export const GUEST_SURFACE_DOCK_SIZE_MIN = 24;
+export const GUEST_SURFACE_DOCK_SIZE_MAX = 480;
+/** Characters in a status section title. */
+export const GUEST_STATUS_SECTION_TITLE_MAX = 60;
+/** Smallest frame height the host gives a status section, in CSS px. */
+export const GUEST_STATUS_SECTION_HEIGHT_MIN = 24;
+/** Tallest frame height the host gives a status section; taller content scrolls inside the frame. */
+export const GUEST_STATUS_SECTION_HEIGHT_MAX = 320;
+/** Frame height before the manifest or the guest says otherwise. */
+export const GUEST_STATUS_SECTION_HEIGHT_DEFAULT = 120;
 /** How many `contributes.actions` entries a package may declare. */
 export const GUEST_ACTIONS_MAX = 8;
 /** Characters in an action label. */
@@ -71,6 +85,14 @@ export const resolveIntegrationApi = (integration) => {
     }
     return null;
 };
+/**
+ * Host roles a service can stand in for. `browser` answers the agent's
+ * `browser.*` actions in place of the in-app browser view; the contract is in
+ * `service-providers.ts`. A service that provides a role needs no panel or
+ * background entry: the host starts it on the first action.
+ */
+export const GUEST_SERVICE_PROVIDES = ['browser'];
+export const serviceProvides = (service, role) => Boolean(service?.provides?.includes(role));
 /**
  * What a guest may do beyond drawing its own panel. The user approves the
  * full list once, when the package is installed; a later package that asks
@@ -152,6 +174,23 @@ export const resolvePageEntry = (contributes) => {
         return null;
     return contributes.page === true ? contributes.panel.entry : contributes.page.entry;
 };
+/**
+ * The HTML the Work Status section loads: `panel.entry` for `true`, the
+ * object's own `entry` otherwise, `null` when nothing is declared or `true`
+ * has no panel page to reuse.
+ */
+export const resolveStatusSectionEntry = (contributes) => {
+    const section = contributes.statusSection;
+    if (!section)
+        return null;
+    return section === true ? contributes.panel.entry ?? null : section.entry;
+};
+/** Clamp a requested status section height to what the host allows. */
+export const clampStatusSectionHeight = (height) => {
+    if (!Number.isFinite(height))
+        return GUEST_STATUS_SECTION_HEIGHT_DEFAULT;
+    return Math.min(GUEST_STATUS_SECTION_HEIGHT_MAX, Math.max(GUEST_STATUS_SECTION_HEIGHT_MIN, Math.round(height)));
+};
 export const isSafeAssetPath = (value) => {
     if (value.includes('\0') || value.includes('\\') || value.startsWith('/') || value.includes('://')) {
         return false;
@@ -217,6 +256,12 @@ export const toPublicService = (service, granted, socketBindings) => {
             override: binding.override,
         }));
     }
+    if (service.provides && service.provides.length > 0) {
+        next.provides = [...service.provides];
+    }
+    if (service.surface) {
+        next.surface = true;
+    }
     return next;
 };
 /** Guest package version: `1.2.3`, optional prerelease / build. */

package/dist/parse.d.ts

@@ -11,6 +11,13 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             name: z.ZodString;
             icon: z.ZodString;
             entry: z.ZodOptional<z.ZodString>;
+            dock: z.ZodOptional<z.ZodEnum<{
+                top: "top";
+                bottom: "bottom";
+                left: "left";
+                right: "right";
+            }>>;
+            size: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>;
         background: z.ZodOptional<z.ZodObject<{
             entry: z.ZodString;
@@ -29,6 +36,11 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             entry: z.ZodString;
             title: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>]>>;
+        statusSection: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
+            entry: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            height: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>]>>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
             sessions: "sessions";
             prompt: "prompt";
@@ -97,6 +109,10 @@ export declare const openChamberManifestSchema: z.ZodObject<{
                 sockets?: SocketBinding[] | undefined;
                 exec?: string[] | undefined;
             }>>>;
+            provides: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                browser: "browser";
+            }>>>;
+            surface: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strip>>;
         filesystem: z.ZodOptional<z.ZodArray<z.ZodString>>;
         actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -156,6 +172,13 @@ export declare const packageManifestSchema: z.ZodObject<{
                 name: z.ZodString;
                 icon: z.ZodString;
                 entry: z.ZodOptional<z.ZodString>;
+                dock: z.ZodOptional<z.ZodEnum<{
+                    top: "top";
+                    bottom: "bottom";
+                    left: "left";
+                    right: "right";
+                }>>;
+                size: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>;
             background: z.ZodOptional<z.ZodObject<{
                 entry: z.ZodString;
@@ -174,6 +197,11 @@ export declare const packageManifestSchema: z.ZodObject<{
                 entry: z.ZodString;
                 title: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>]>>;
+            statusSection: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<true>, z.ZodObject<{
+                entry: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+                height: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>]>>;
             capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                 sessions: "sessions";
                 prompt: "prompt";
@@ -242,6 +270,10 @@ export declare const packageManifestSchema: z.ZodObject<{
                     sockets?: SocketBinding[] | undefined;
                     exec?: string[] | undefined;
                 }>>>;
+                provides: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                    browser: "browser";
+                }>>>;
+                surface: z.ZodOptional<z.ZodLiteral<true>>;
             }, z.core.$strip>>;
             filesystem: z.ZodOptional<z.ZodArray<z.ZodString>>;
             actions: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/parse.js

@@ -1,7 +1,7 @@
 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_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, } from "./manifest.js";
+import { DECLARED_GUEST_CAPABILITIES, GUEST_ACTIONS_MAX, GUEST_ACTION_LABEL_MAX, GUEST_COMMANDS_MAX, GUEST_COMMAND_DESCRIPTION_MAX, GUEST_COMMAND_NAME, GUEST_FILESYSTEM_PATTERNS_MAX, GUEST_FILESYSTEM_PATTERN_MAX, GUEST_SERVICE_PROVIDES, GUEST_TOOLS_MAX, GUEST_TOOL_COLUMNS_MAX, GUEST_TOOL_COLUMN_MAX, GUEST_TOOL_LANGUAGE_MAX, GUEST_TOOL_MATCH, GUEST_TOOL_MATCH_MAX, GUEST_TOOL_NAME_MAX, GUEST_TOOL_OUTPUTS, GUEST_TOOL_TEMPLATE_MAX, PANEL_ID, hasGuestPage, isGuestFilesystemPattern, isGuestPackageSvgIcon, isSafeAssetPath, resolveIntegrationAuth, GUEST_SURFACE_DOCKS, GUEST_SURFACE_DOCK_SIZE_MAX, GUEST_SURFACE_DOCK_SIZE_MIN, GUEST_STATUS_SECTION_HEIGHT_MAX, GUEST_STATUS_SECTION_HEIGHT_MIN, GUEST_STATUS_SECTION_TITLE_MAX, } from "./manifest.js";
 const isPanelIcon = (value) => (PANEL_ID.test(value) || isGuestPackageSvgIcon(value));
 const isHttpsUrl = (value) => {
     try {
@@ -48,6 +48,8 @@ const panelSchema = z.object({
     name: z.string().trim().min(1),
     icon: z.string().trim().refine(isPanelIcon),
     entry: z.string().trim().refine(isSafeAssetPath).optional(),
+    dock: z.enum(GUEST_SURFACE_DOCKS).optional(),
+    size: z.number().int().min(GUEST_SURFACE_DOCK_SIZE_MIN).max(GUEST_SURFACE_DOCK_SIZE_MAX).optional(),
 });
 const integrationSettingSchema = z.object({
     id: z.string().trim().regex(PANEL_ID),
@@ -140,6 +142,10 @@ const serviceSchema = z.object({
     entry: z.string().trim().refine(isSafeAssetPath),
     runtime: z.literal('host'),
     permissions: servicePermissionsSchema.optional(),
+    provides: z.array(z.enum(GUEST_SERVICE_PROVIDES)).min(1).max(GUEST_SERVICE_PROVIDES.length)
+        .refine((roles) => new Set(roles).size === roles.length, { message: 'provides entries must be unique' })
+        .optional(),
+    surface: z.literal(true).optional(),
 });
 const uniqueBy = (items, key) => (new Set(items.map(key)).size === items.length);
 // `roles` only means something on a message action and `payload` only on a
@@ -187,6 +193,11 @@ const contributesSchema = z.object({
             entry: z.string().trim().refine(isSafeAssetPath),
             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')),
+            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(),
+        })]).optional(),
     capabilities: z.array(z.enum(DECLARED_GUEST_CAPABILITIES)).max(8).optional(),
     integration: integrationSchema.optional(),
     service: serviceSchema.optional(),
@@ -208,7 +219,10 @@ const runtimeContributions = (contributes) => {
         declared.push('capabilities');
     if (contributes.integration !== undefined)
         declared.push('integration');
-    if (contributes.service !== undefined)
+    // 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)
         declared.push('service');
     if (contributes.filesystem !== undefined)
         declared.push('filesystem');
@@ -224,6 +238,23 @@ export const openChamberManifestSchema = z.object({
         openchamber: z.string().trim().regex(OPENCHAMBER_ENGINE_PATTERN),
     }).strict().optional(),
     contributes: contributesSchema.superRefine((contributes, ctx) => {
+        // Docking only means something for a page beside a shared surface.
+        const docked = contributes.panel.dock !== undefined || contributes.panel.size !== undefined;
+        if (docked && !(contributes.service?.surface && hasGuestPage(contributes))) {
+            ctx.addIssue({
+                code: 'custom', path: ['panel', 'dock'],
+                message: 'panel.dock and panel.size place panel.entry beside service.surface; they need both.',
+            });
+            return;
+        }
+        // `true` reuses the panel page; without one the section has nothing to load.
+        if (contributes.statusSection === true && !hasGuestPage(contributes)) {
+            ctx.addIssue({
+                code: 'custom', path: ['statusSection'],
+                message: 'contributes.statusSection: true reuses panel.entry; without a panel page, name its own { "entry": "<package .html>" }.',
+            });
+            return;
+        }
         if (hasGuestPage(contributes))
             return;
         if (contributes.background) {
@@ -241,6 +272,26 @@ export const openChamberManifestSchema = z.object({
                 });
             return;
         }
+        if (contributes.statusSection) {
+            // The section frame runs code and may use what the package is granted,
+            // but it only hosts itself: things the host opens or invokes elsewhere
+            // need a panel or background entry.
+            const needsFrame = [];
+            if (contributes.page !== undefined)
+                needsFrame.push('page');
+            if (contributes.attach !== undefined && contributes.attach !== false)
+                needsFrame.push('attach');
+            if (contributes.actions !== undefined)
+                needsFrame.push('actions');
+            if (contributes.commands !== undefined)
+                needsFrame.push('commands');
+            if (needsFrame.length > 0)
+                ctx.addIssue({
+                    code: 'custom', path: ['panel'],
+                    message: `${needsFrame.map((key) => `contributes.${key}`).join(', ')} needs panel.entry or background.entry; a status section only hosts itself.`,
+                });
+            return;
+        }
         const needsRuntime = runtimeContributions(contributes);
         if (needsRuntime.length === 0)
             return;
@@ -301,6 +352,12 @@ const failureFromIssue = (issue) => {
             return fail('invalid-panel-icon', 'panel.icon must be a Remixicon name or a package .svg path.');
         case 'contributes.panel.entry':
             return fail('invalid-panel-entry', 'panel.entry must be a relative path inside the package.');
+        case 'contributes.panel.dock':
+            return fail('invalid-panel', issue.code === 'custom'
+                ? issue.message
+                : `panel.dock is one of ${GUEST_SURFACE_DOCKS.join(', ')}.`);
+        case 'contributes.panel.size':
+            return fail('invalid-panel', `panel.size is a whole number of CSS pixels from ${GUEST_SURFACE_DOCK_SIZE_MIN} to ${GUEST_SURFACE_DOCK_SIZE_MAX}.`);
         case 'contributes.capabilities':
             return fail('invalid-capabilities', 'contributes.capabilities may list "prompt", "sessions", and "files".');
         default:
@@ -309,6 +366,11 @@ 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.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} }.`);
+    }
     if (path === 'contributes.background' || path.startsWith('contributes.background.')) {
         return fail('invalid-background', 'contributes.background needs an entry ending in .html inside the package.');
     }
@@ -334,7 +396,7 @@ const failureFromIssue = (issue) => {
         return fail('invalid-integration', 'contributes.integration needs a name, description, and oauth, token, or host.');
     }
     if (path.startsWith('contributes.service')) {
-        return fail('invalid-service', 'contributes.service needs entry, runtime "host", and optional permissions.');
+        return fail('invalid-service', 'contributes.service needs entry, runtime "host", optional permissions, optional provides ("browser"), and optional surface (true).');
     }
     return fail('missing-panel', 'contributes.panel is required.');
 };

package/dist/protocol.d.ts

@@ -144,6 +144,7 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
             dialog: "dialog";
             page: "page";
             background: "background";
+            status: "status";
         }>;
         connection: z.ZodObject<{
             connected: z.ZodBoolean;
@@ -633,7 +634,7 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
     id: string;
     ok: false;
     error: string;
-    code: "HOST_UNAVAILABLE" | "HOST_TIMEOUT" | "HOST_REJECTED" | "DISCONNECTED" | "DISABLED" | "BAD_PATH" | "NO_INTEGRATION" | "NO_SERVICE" | "SERVICE_FAILED" | "NO_SESSION" | "SESSION_BUSY" | "NOT_GRANTED" | "NO_DIRECTORY" | "NOT_FOUND" | "FILE_TOO_LARGE" | "DENIED" | "NO_MODEL" | "MODEL_FAILED";
+    code: "HOST_UNAVAILABLE" | "HOST_TIMEOUT" | "HOST_REJECTED" | "DISCONNECTED" | "DISABLED" | "BAD_PATH" | "NO_INTEGRATION" | "NO_SERVICE" | "SERVICE_FAILED" | "NO_SESSION" | "SESSION_BUSY" | "NOT_GRANTED" | "NO_DIRECTORY" | "NOT_FOUND" | "FILE_TOO_LARGE" | "DENIED" | "NO_MODEL" | "MODEL_FAILED" | "UNSUPPORTED";
     payload?: undefined;
 }, {
     type: "result";
@@ -1114,6 +1115,22 @@ export declare const guestMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>;
     channel: z.ZodLiteral<"openchamber.sdk">;
     v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"open-commit">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        sha: z.ZodString;
+    }, z.core.$strip>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"resize">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"resolve-result">;
     id: z.ZodString;

package/dist/protocol.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { guestSessionWorktreeSchema, guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceQuerySchema, guestWorkspaceSnapshotSchema } from "./workspace-schemas.js";
 import { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL } from "./api-version.js";
-import { SERVICE_STATUS_VALUES, ATTACH_PROVIDER_ID, GUEST_ACCOUNT_MAX, GUEST_ATTACH_AUTHOR_MAX, GUEST_BADGE_MAX, GUEST_ITEM_MESSAGE_TEXT_MAX, GUEST_ITEM_SESSION_MAX, GUEST_RESOLVE_ERROR_MAX, GUEST_ATTACH_BRANCH_MAX, GUEST_ATTACH_DATA_MAX, GUEST_ATTACH_ID_MAX, GUEST_ATTACH_TEXT_MAX, GUEST_ATTACH_TITLE_MAX, GUEST_ATTACH_URL_MAX, GUEST_CLIPBOARD_TEXT_MAX, GUEST_COMPOSE_TEXT_MAX, GUEST_FILE_CONTENT_MAX, GUEST_FILE_ENTRY_KINDS, GUEST_FILE_LIST_MAX, GUEST_GENERATE_OUTPUT_TOKENS_MAX, GUEST_GENERATE_PROMPT_MAX, GUEST_GENERATE_SYSTEM_MAX, GUEST_GENERATE_TEXT_MAX, GUEST_FILE_PATH_MAX, GUEST_FILE_STAT_KINDS, GUEST_REQUEST_BODY_MAX, GUEST_REQUEST_PATH_MAX, GUEST_REQUEST_RESPONSE_MAX, GUEST_SESSION_AGENT_MAX, GUEST_SESSION_MODEL_MAX, GUEST_SETTING_VALUE_MAX, GUEST_TOAST_MAX, SESSION_LIFECYCLE_PHASES, SETTING_KEY, START_SESSION_SENT, isGuestFilePath, isGuestRequestPath, resolveHostRequestErrorCode, } from "./contract.js";
+import { SERVICE_STATUS_VALUES, ATTACH_PROVIDER_ID, GUEST_ACCOUNT_MAX, GUEST_ATTACH_AUTHOR_MAX, GUEST_BADGE_MAX, GUEST_FRAME_HEIGHT_MAX, GUEST_COMMIT_SHA, GUEST_ITEM_MESSAGE_TEXT_MAX, GUEST_ITEM_SESSION_MAX, GUEST_RESOLVE_ERROR_MAX, GUEST_ATTACH_BRANCH_MAX, GUEST_ATTACH_DATA_MAX, GUEST_ATTACH_ID_MAX, GUEST_ATTACH_TEXT_MAX, GUEST_ATTACH_TITLE_MAX, GUEST_ATTACH_URL_MAX, GUEST_CLIPBOARD_TEXT_MAX, GUEST_COMPOSE_TEXT_MAX, GUEST_FILE_CONTENT_MAX, GUEST_FILE_ENTRY_KINDS, GUEST_FILE_LIST_MAX, GUEST_GENERATE_OUTPUT_TOKENS_MAX, GUEST_GENERATE_PROMPT_MAX, GUEST_GENERATE_SYSTEM_MAX, GUEST_GENERATE_TEXT_MAX, GUEST_FILE_PATH_MAX, GUEST_FILE_STAT_KINDS, GUEST_REQUEST_BODY_MAX, GUEST_REQUEST_PATH_MAX, GUEST_REQUEST_RESPONSE_MAX, GUEST_SESSION_AGENT_MAX, GUEST_SESSION_MODEL_MAX, GUEST_SETTING_VALUE_MAX, GUEST_TOAST_MAX, SESSION_LIFECYCLE_PHASES, SETTING_KEY, START_SESSION_SENT, isGuestFilePath, isGuestRequestPath, resolveHostRequestErrorCode, } from "./contract.js";
 const envelope = {
     channel: z.literal(OPENCHAMBER_SDK_CHANNEL),
     v: z.literal(OPENCHAMBER_SDK_API_VERSION),
@@ -146,7 +146,7 @@ const readyPayloadSchema = z.object({
     locale: z.string().min(1),
     directory: z.string().nullable(),
     session: sessionSnapshotSchema,
-    surface: z.enum(['panel', 'dialog', 'page', 'background']),
+    surface: z.enum(['panel', 'dialog', 'page', 'background', 'status']),
     connection: guestConnectionSchema,
     settings: guestSettingsSchema,
     item: guestItemSchema,
@@ -443,6 +443,22 @@ export const guestMessageSchema = z.discriminatedUnion('type', [
             count: z.number().int().min(0).max(GUEST_BADGE_MAX).nullable(),
         }),
     }),
+    z.object({
+        ...envelope,
+        type: z.literal('open-commit'),
+        id: z.string().min(1),
+        payload: z.object({
+            sha: z.string().regex(GUEST_COMMIT_SHA),
+        }),
+    }),
+    z.object({
+        ...envelope,
+        type: z.literal('resize'),
+        id: z.string().min(1),
+        payload: z.object({
+            height: z.number().int().min(0).max(GUEST_FRAME_HEIGHT_MAX),
+        }),
+    }),
     z.object({
         ...envelope,
         type: z.literal('resolve-result'),

package/dist/schemas.d.ts

@@ -2,3 +2,6 @@ export { openChamberManifestSchema, PACKAGE_VERSION_PATTERN, packageManifestSche
 export type { ManifestDocument } from './parse.ts';
 export { guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceSnapshotSchema } from './workspace-schemas.ts';
 export { guestMessageSchema, hostMessageSchema, parseGuestMessage, parseHostMessage, } from './protocol.ts';
+export { browserControlActionSchema, browserProviderResultSchema } from './service-provider-schemas.ts';
+export { surfaceClipboardAnswerSchema, surfaceControllerSchema, surfaceHostMessageSchema, surfaceInputEventSchema, surfaceResizeAnswerSchema, surfaceViewerMessageSchema, } from './service-surface-schemas.ts';
+export type { SurfaceHostMessage, SurfaceViewerMessage } from './service-surface-schemas.ts';

package/dist/schemas.js

@@ -4,3 +4,5 @@
 export { openChamberManifestSchema, PACKAGE_VERSION_PATTERN, packageManifestSchema, parseManifest, parseManifestJson, } from "./parse.js";
 export { guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceSnapshotSchema } from "./workspace-schemas.js";
 export { guestMessageSchema, hostMessageSchema, parseGuestMessage, parseHostMessage, } from "./protocol.js";
+export { browserControlActionSchema, browserProviderResultSchema } from "./service-provider-schemas.js";
+export { surfaceClipboardAnswerSchema, surfaceControllerSchema, surfaceHostMessageSchema, surfaceInputEventSchema, surfaceResizeAnswerSchema, surfaceViewerMessageSchema, } from "./service-surface-schemas.js";

package/dist/scrollbar-style.d.ts

@@ -1,2 +1,10 @@
-/** 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";
+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: transparent transparent;\n}\n:hover, [data-oc-scrolling] {\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  *, :hover, [data-oc-scrolling] { scrollbar-width: auto; scrollbar-color: auto; }\n  ::-webkit-scrollbar { width: 6px; height: 6px; background: transparent; }\n  ::-webkit-scrollbar-track { background: transparent; }\n  ::-webkit-scrollbar-thumb {\n    background: transparent;\n    border-radius: 999px;\n    min-width: 24px;\n    min-height: 24px;\n  }\n  :hover::-webkit-scrollbar-thumb, [data-oc-scrolling]::-webkit-scrollbar-thumb { background: var(--oc-scrollbar-thumb); }\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  *, :hover, [data-oc-scrolling] { scrollbar-color: auto; }\n  ::-webkit-scrollbar-thumb, ::-webkit-scrollbar-thumb:hover { background: CanvasText; }\n}\n";
+/**
+ * Marks whichever element scrolls (the root for document scrolling) with
+ * `GUEST_SCROLLING_ATTRIBUTE` and clears it once scrolling has been quiet for
+ * the hide delay. One capturing, passive listener per document; installing
+ * twice is a no-op. Self-contained on purpose: the server inlines its source.
+ */
+export declare function installGuestScrollbarActivity(doc: Document): void;
+/** Inline script form of `installGuestScrollbarActivity`, appended by the host to served guest HTML. */
+export declare const GUEST_SCROLLBAR_SCRIPT: string;

package/dist/scrollbar-style.js

@@ -1,4 +1,17 @@
-/** Shared by served extension documents and the UI kit, including older guest bundles. */
+/**
+ * Scrollbars in extension documents behave like the app's own overlay
+ * scrollbars: invisible at rest, shown while the pointer is over the
+ * scrolling element or while it scrolls, then hidden again after
+ * one second (the app's `OverlayScrollbar` default).
+ *
+ * Hover works from CSS alone. "While it scrolls" needs the attribute set by
+ * `installGuestScrollbarActivity`; without it (an authored CSP that blocks the
+ * inline script), scrollbars still appear on hover.
+ *
+ * Shared by served extension documents and the UI kit, including older guest bundles.
+ */
+/** Attribute present on an element for a moment after it scrolled. */
+const GUEST_SCROLLING_ATTRIBUTE = 'data-oc-scrolling';
 export const GUEST_SCROLLBAR_CSS = `
 :root {
   --oc-scrollbar-thumb: color-mix(in srgb, var(--oc-muted, currentColor) 40%, transparent);
@@ -7,26 +20,58 @@ export const GUEST_SCROLLBAR_CSS = `
 }
 * {
   scrollbar-width: thin;
+  scrollbar-color: transparent transparent;
+}
+:hover, [${GUEST_SCROLLING_ATTRIBUTE}] {
   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; }
+  *, :hover, [${GUEST_SCROLLING_ATTRIBUTE}] { 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);
+    background: transparent;
     border-radius: 999px;
     min-width: 24px;
     min-height: 24px;
   }
+  :hover::-webkit-scrollbar-thumb, [${GUEST_SCROLLING_ATTRIBUTE}]::-webkit-scrollbar-thumb { background: var(--oc-scrollbar-thumb); }
   ::-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; }
+  *, :hover, [${GUEST_SCROLLING_ATTRIBUTE}] { scrollbar-color: auto; }
   ::-webkit-scrollbar-thumb, ::-webkit-scrollbar-thumb:hover { background: CanvasText; }
 }
 `;
+/**
+ * Marks whichever element scrolls (the root for document scrolling) with
+ * `GUEST_SCROLLING_ATTRIBUTE` and clears it once scrolling has been quiet for
+ * the hide delay. One capturing, passive listener per document; installing
+ * twice is a no-op. Self-contained on purpose: the server inlines its source.
+ */
+export function installGuestScrollbarActivity(doc) {
+    const root = doc.documentElement;
+    if (root.hasAttribute('data-oc-scrollbar-activity'))
+        return;
+    root.setAttribute('data-oc-scrollbar-activity', '');
+    const timers = new WeakMap();
+    doc.addEventListener('scroll', (event) => {
+        const target = event.target === doc ? root : event.target;
+        if (!(target instanceof Element))
+            return;
+        if (!target.hasAttribute('data-oc-scrolling'))
+            target.setAttribute('data-oc-scrolling', '');
+        const pending = timers.get(target);
+        if (pending !== undefined)
+            clearTimeout(pending);
+        timers.set(target, setTimeout(() => {
+            timers.delete(target);
+            target.removeAttribute('data-oc-scrolling');
+        }, 1000));
+    }, { capture: true, passive: true });
+}
+/** Inline script form of `installGuestScrollbarActivity`, appended by the host to served guest HTML. */
+export const GUEST_SCROLLBAR_SCRIPT = `(${installGuestScrollbarActivity.toString()})(document);`;

package/dist/service-provider-schemas.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+/**
+ * Host-side parse of what a browser provider answers. `data` stays whatever
+ * the service produced: the host hands it to the agent as is, and only
+ * `browser.capture` is read further (the image the host writes to disk).
+ */
+export declare const browserProviderResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    data: z.ZodObject<{}, z.core.$loose>;
+}, z.core.$strip>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodString;
+}, z.core.$strip>]>;
+export declare const browserControlActionSchema: z.ZodEnum<{
+    "browser.open": "browser.open";
+    "browser.snapshot": "browser.snapshot";
+    "browser.click": "browser.click";
+    "browser.type": "browser.type";
+    "browser.scroll": "browser.scroll";
+    "browser.back": "browser.back";
+    "browser.forward": "browser.forward";
+    "browser.inspect": "browser.inspect";
+    "browser.capture": "browser.capture";
+    "browser.resize": "browser.resize";
+}>;

package/dist/service-provider-schemas.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import { BROWSER_CONTROL_ACTIONS } from "./service-providers.js";
+/**
+ * Host-side parse of what a browser provider answers. `data` stays whatever
+ * the service produced: the host hands it to the agent as is, and only
+ * `browser.capture` is read further (the image the host writes to disk).
+ */
+export const browserProviderResultSchema = z.union([
+    z.object({ ok: z.literal(true), data: z.object({}).passthrough() }),
+    z.object({ ok: z.literal(false), error: z.string().min(1).max(2_000) }),
+]);
+export const browserControlActionSchema = z.enum(BROWSER_CONTROL_ACTIONS);