@openchamber/sdk 2.1.0 → 2.2.0

package/dist/popover.d.ts

@@ -0,0 +1,37 @@
+import type { JsonValue } from './contract.ts';
+export declare const GUEST_POPOVER_ID: RegExp;
+export declare const GUEST_POPOVER_COORDINATE_MAX = 100000;
+export declare const GUEST_POPOVER_WIDTH_MIN = 160;
+export declare const GUEST_POPOVER_WIDTH_MAX = 640;
+export declare const GUEST_POPOVER_HEIGHT_MIN = 48;
+export declare const GUEST_POPOVER_HEIGHT_MAX = 480;
+export declare const GUEST_POPOVER_DATA_MAX = 16000;
+export declare const GUEST_POPOVER_DATA_DEPTH_MAX = 32;
+export declare const GUEST_POPOVER_SIDES: readonly ["left", "right", "top", "bottom"];
+export type GuestPopoverSide = (typeof GUEST_POPOVER_SIDES)[number];
+export type GuestPopoverAnchor = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type GuestPopoverRequest = {
+    id: string;
+    anchor: GuestPopoverAnchor;
+    width: number;
+    height: number;
+    side?: GuestPopoverSide;
+    focus?: boolean;
+    data: JsonValue;
+};
+export type GuestPopoverContext = {
+    id: string;
+    data: JsonValue;
+};
+export declare const GUEST_POPOVER_CLOSE_REASONS: readonly ["escape", "outside", "anchor", "owner", "closed", "replaced"];
+export type GuestPopoverClosedEvent = {
+    id: string;
+    reason: (typeof GUEST_POPOVER_CLOSE_REASONS)[number];
+};
+/** Guest-side fast-fail guard. The host schema remains authoritative for untyped callers. */
+export declare const isGuestPopoverRequest: (request: GuestPopoverRequest) => boolean;

package/dist/popover.js

@@ -0,0 +1,57 @@
+export const GUEST_POPOVER_ID = /^[A-Za-z0-9_-]{1,80}$/;
+export const GUEST_POPOVER_COORDINATE_MAX = 100_000;
+export const GUEST_POPOVER_WIDTH_MIN = 160;
+export const GUEST_POPOVER_WIDTH_MAX = 640;
+export const GUEST_POPOVER_HEIGHT_MIN = 48;
+export const GUEST_POPOVER_HEIGHT_MAX = 480;
+export const GUEST_POPOVER_DATA_MAX = 16_000;
+export const GUEST_POPOVER_DATA_DEPTH_MAX = 32;
+export const GUEST_POPOVER_SIDES = ['left', 'right', 'top', 'bottom'];
+export const GUEST_POPOVER_CLOSE_REASONS = ['escape', 'outside', 'anchor', 'owner', 'closed', 'replaced'];
+const hasBoundedJsonTree = (value, depth = 0, budget = { remaining: GUEST_POPOVER_DATA_MAX }) => {
+    if (--budget.remaining < 0 || depth >= GUEST_POPOVER_DATA_DEPTH_MAX)
+        return false;
+    if (value === null)
+        return true;
+    const children = Array.isArray(value) ? value : Object(value) === value ? Object.values(value) : [];
+    for (const item of children) {
+        if (!hasBoundedJsonTree(item, depth + 1, budget))
+            return false;
+    }
+    return true;
+};
+// Used only after the depth bound above, including for JavaScript consumers
+// whose values need not satisfy the public JsonValue type.
+const isFiniteJson = (value) => {
+    if (value === null || value === true || value === false)
+        return true;
+    if (Array.isArray(value))
+        return Object.keys(value).every((key) => /^(0|[1-9]\d*)$/.test(key) && Number(key) < value.length)
+            && value.every(isFiniteJson);
+    if (Object(value) === value) {
+        const prototype = Object.getPrototypeOf(value);
+        return (prototype === null || prototype === Object.prototype) && Object.values(value).every(isFiniteJson);
+    }
+    return String(value) === value || Number.isFinite(value);
+};
+/** Guest-side fast-fail guard. The host schema remains authoritative for untyped callers. */
+export const isGuestPopoverRequest = (request) => {
+    try {
+        if (String(request.id) !== request.id || !GUEST_POPOVER_ID.test(request.id)
+            || !Number.isFinite(request.anchor.x) || Math.abs(request.anchor.x) > GUEST_POPOVER_COORDINATE_MAX
+            || !Number.isFinite(request.anchor.y) || Math.abs(request.anchor.y) > GUEST_POPOVER_COORDINATE_MAX
+            || !Number.isFinite(request.anchor.width) || !Number.isFinite(request.anchor.height)
+            || request.anchor.width <= 0 || request.anchor.height <= 0
+            || request.anchor.width > GUEST_POPOVER_COORDINATE_MAX || request.anchor.height > GUEST_POPOVER_COORDINATE_MAX
+            || !Number.isInteger(request.width) || request.width < GUEST_POPOVER_WIDTH_MIN || request.width > GUEST_POPOVER_WIDTH_MAX
+            || !Number.isInteger(request.height) || request.height < GUEST_POPOVER_HEIGHT_MIN || request.height > GUEST_POPOVER_HEIGHT_MAX
+            || (request.side !== undefined && !GUEST_POPOVER_SIDES.includes(request.side))
+            || (request.focus !== undefined && request.focus !== true && request.focus !== false)
+            || !hasBoundedJsonTree(request.data) || !isFiniteJson(request.data))
+            return false;
+        return JSON.stringify(request.data).length <= GUEST_POPOVER_DATA_MAX;
+    }
+    catch {
+        return false;
+    }
+};

package/dist/protocol.d.ts

@@ -92,6 +92,48 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strip>;
     channel: z.ZodLiteral<"openchamber.sdk">;
     v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shells">;
+    payload: z.ZodObject<{
+        subscriptionId: z.ZodString;
+        snapshot: z.ZodObject<{
+            kind: z.ZodLiteral<"shells">;
+            scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"session">;
+                sessionId: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"project">;
+                projectId: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"global">;
+            }, z.core.$strict>], "kind">;
+            shells: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                sessionID: z.ZodString;
+                command: z.ZodString;
+                startedAt: z.ZodNumber;
+                background: z.ZodBoolean;
+            }, z.core.$strict>>;
+            ended: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                sessionID: z.ZodString;
+                command: z.ZodString;
+                startedAt: z.ZodNumber;
+                background: z.ZodBoolean;
+                status: z.ZodEnum<{
+                    exited: "exited";
+                    timeout: "timeout";
+                    killed: "killed";
+                    stopped: "stopped";
+                    unknown: "unknown";
+                }>;
+                exit: z.ZodOptional<z.ZodNumber>;
+                endedAt: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strip>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"ready">;
     payload: z.ZodObject<{
@@ -128,6 +170,14 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
                 font: z.ZodString;
                 mono: z.ZodString;
                 radius: z.ZodString;
+                syntaxKeyword: z.ZodOptional<z.ZodString>;
+                syntaxString: z.ZodOptional<z.ZodString>;
+                syntaxNumber: z.ZodOptional<z.ZodString>;
+                syntaxFunction: z.ZodOptional<z.ZodString>;
+                syntaxType: z.ZodOptional<z.ZodString>;
+                syntaxComment: z.ZodOptional<z.ZodString>;
+                syntaxVariable: z.ZodOptional<z.ZodString>;
+                syntaxOperator: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
         }, z.core.$strip>;
         locale: z.ZodString;
@@ -146,6 +196,7 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
             background: "background";
             status: "status";
             file: "file";
+            popover: "popover";
         }>;
         connection: z.ZodObject<{
             connected: z.ZodBoolean;
@@ -197,6 +248,15 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
             }, z.core.$strip>>;
             data: z.ZodOptional<z.ZodJSONSchema>;
         }, z.core.$strip>]>>;
+        popover: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            data: z.ZodCustom<import("./contract.ts").JsonValue, import("./contract.ts").JsonValue>;
+        }, z.core.$strict>>;
+        features: z.ZodOptional<z.ZodObject<{
+            deviceStorage: z.ZodOptional<z.ZodLiteral<true>>;
+            statusControls: z.ZodOptional<z.ZodLiteral<true>>;
+            popovers: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     channel: z.ZodLiteral<"openchamber.sdk">;
     v: z.ZodLiteral<1>;
@@ -300,6 +360,29 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strip>;
     channel: z.ZodLiteral<"openchamber.sdk">;
     v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"status-control-event">;
+    payload: z.ZodObject<{
+        id: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"popover-closed">;
+    payload: z.ZodObject<{
+        id: z.ZodString;
+        reason: z.ZodEnum<{
+            escape: "escape";
+            outside: "outside";
+            anchor: "anchor";
+            owner: "owner";
+            closed: "closed";
+            replaced: "replaced";
+        }>;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"resolve">;
     id: z.ZodString;
@@ -418,7 +501,13 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
                 data: z.ZodOptional<z.ZodJSONSchema>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
-    }, z.core.$strip>], "kind">, z.ZodUnion<readonly [z.ZodObject<{
+    }, z.core.$strip>], "kind">, z.ZodObject<{
+        output: z.ZodString;
+        cursor: z.ZodNumber;
+        skipped: z.ZodBoolean;
+    }, z.core.$strip>, z.ZodObject<{
+        stopped: z.ZodLiteral<true>;
+    }, z.core.$strip>, z.ZodUnion<readonly [z.ZodObject<{
         sessionId: z.ZodString;
         sent: z.ZodEnum<{
             failed: "failed";
@@ -470,9 +559,9 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
         }>;
     }, z.core.$strip>, z.ZodObject<{
         status: z.ZodEnum<{
+            stopped: "stopped";
             ready: "ready";
             failed: "failed";
-            stopped: "stopped";
             starting: "starting";
         }>;
     }, z.core.$strip>, z.ZodObject<{
@@ -600,7 +689,7 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
     } | {
         sent: "failed" | "sent" | "no-model" | "skipped";
     } | {
-        status: "ready" | "failed" | "stopped" | "starting";
+        status: "stopped" | "ready" | "failed" | "starting";
     } | {
         content: string;
     } | {
@@ -616,6 +705,12 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
         mtime: number;
     } | {
         text: string;
+    } | {
+        output: string;
+        cursor: number;
+        skipped: boolean;
+    } | {
+        stopped: true;
     };
     error?: undefined;
     code?: undefined;
@@ -737,7 +832,7 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
     } | {
         sent: "failed" | "sent" | "no-model" | "skipped";
     } | {
-        status: "ready" | "failed" | "stopped" | "starting";
+        status: "stopped" | "ready" | "failed" | "starting";
     } | {
         content: string;
     } | {
@@ -753,6 +848,12 @@ export declare const hostMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
         mtime: number;
     } | {
         text: string;
+    } | {
+        output: string;
+        cursor: number;
+        skipped: boolean;
+    } | {
+        stopped: true;
     } | undefined;
 }>>, z.ZodObject<{
     type: z.ZodLiteral<"action">;
@@ -874,24 +975,151 @@ export declare const guestMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>;
     channel: z.ZodLiteral<"openchamber.sdk">;
     v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shells-subscribe">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        subscriptionId: z.ZodString;
+        scope: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"session">;
+            sessionId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"project">;
+            projectId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"global">;
+        }, z.core.$strict>], "kind">;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shells-unsubscribe">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        subscriptionId: z.ZodString;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shell-output">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        shellId: z.ZodString;
+        cursor: z.ZodOptional<z.ZodNumber>;
+        tailBytes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"shell-stop">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        shellId: z.ZodString;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"storage">;
     id: z.ZodString;
     payload: z.ZodDiscriminatedUnion<[z.ZodObject<{
         op: z.ZodLiteral<"get">;
         key: z.ZodString;
+        scope: z.ZodOptional<z.ZodEnum<{
+            instance: "instance";
+            device: "device";
+        }>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"delete">;
         key: z.ZodString;
+        scope: z.ZodOptional<z.ZodEnum<{
+            instance: "instance";
+            device: "device";
+        }>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"set">;
         key: z.ZodString;
         value: z.ZodJSONSchema;
+        scope: z.ZodOptional<z.ZodEnum<{
+            instance: "instance";
+            device: "device";
+        }>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"keys">;
+        scope: z.ZodOptional<z.ZodEnum<{
+            instance: "instance";
+            device: "device";
+        }>>;
     }, z.core.$strict>], "op">;
     channel: z.ZodLiteral<"openchamber.sdk">;
     v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"status-controls">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        controls: 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>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"popover-open">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        id: z.ZodString;
+        anchor: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        side: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+            top: "top";
+            bottom: "bottom";
+        }>>;
+        focus: z.ZodOptional<z.ZodBoolean>;
+        data: z.ZodCustom<import("./contract.ts").JsonValue, import("./contract.ts").JsonValue>;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"popover-close">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        id: z.ZodString;
+        reason: z.ZodOptional<z.ZodEnum<{
+            escape: "escape";
+            closed: "closed";
+        }>>;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"popover-anchor">;
+    id: z.ZodString;
+    payload: z.ZodObject<{
+        id: z.ZodString;
+        active: z.ZodBoolean;
+    }, z.core.$strict>;
+    channel: z.ZodLiteral<"openchamber.sdk">;
+    v: z.ZodLiteral<1>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"open-session">;
     id: z.ZodString;

package/dist/protocol.js

@@ -1,5 +1,8 @@
 import { z } from 'zod';
 import { guestSessionWorktreeSchema, guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceQuerySchema, guestWorkspaceSnapshotSchema } from "./workspace-schemas.js";
+import { guestStatusControlEventSchema, guestStatusControlsSchema } from "./status-control-schemas.js";
+import { guestPopoverClosedEventSchema, guestPopoverDataSchema, guestPopoverRequestSchema } from "./popover-schemas.js";
+import { GUEST_SHELL_END_STATUSES, GUEST_SHELL_ID_MAX, GUEST_SHELLS_MAX, GUEST_SHELL_OUTPUT_TAIL_MAX } from "./shells.js";
 import { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL } from "./api-version.js";
 import { SERVICE_STATUS_VALUES, ATTACH_PROVIDER_ID, GUEST_ACCOUNT_MAX, GUEST_ATTACH_AUTHOR_MAX, GUEST_BADGE_MAX, GUEST_FRAME_HEIGHT_MAX, GUEST_COMMIT_SHA, GUEST_ITEM_MESSAGE_TEXT_MAX, GUEST_ITEM_SESSION_MAX, GUEST_RESOLVE_ERROR_MAX, GUEST_ATTACH_BRANCH_MAX, GUEST_ATTACH_DATA_MAX, GUEST_ATTACH_ID_MAX, GUEST_ATTACH_TEXT_MAX, GUEST_ATTACH_TITLE_MAX, GUEST_ATTACH_URL_MAX, GUEST_CLIPBOARD_TEXT_MAX, GUEST_COMPOSE_TEXT_MAX, GUEST_FILE_CONTENT_MAX, GUEST_FILE_ENTRY_KINDS, GUEST_FILE_LIST_MAX, GUEST_GENERATE_OUTPUT_TOKENS_MAX, GUEST_GENERATE_PROMPT_MAX, GUEST_GENERATE_SYSTEM_MAX, GUEST_GENERATE_TEXT_MAX, GUEST_FILE_PATH_MAX, GUEST_FILE_STAT_KINDS, GUEST_REQUEST_BODY_MAX, GUEST_REQUEST_PATH_MAX, GUEST_REQUEST_RESPONSE_MAX, GUEST_SESSION_AGENT_MAX, GUEST_SESSION_MODEL_MAX, GUEST_SETTING_VALUE_MAX, GUEST_TOAST_MAX, SESSION_LIFECYCLE_PHASES, SETTING_KEY, START_SESSION_SENT, isGuestFilePath, isGuestRequestPath, resolveHostRequestErrorCode, } from "./contract.js";
 import { GUEST_FILE_EDITOR_CONTENT_MAX, GUEST_FILE_EDITOR_VERSION_MAX } from "./file-editor.js";
@@ -39,6 +42,14 @@ const themeTokensSchema = z.object({
     font: z.string().min(1),
     mono: z.string().min(1),
     radius: z.string().min(1),
+    syntaxKeyword: z.string().min(1).optional(),
+    syntaxString: z.string().min(1).optional(),
+    syntaxNumber: z.string().min(1).optional(),
+    syntaxFunction: z.string().min(1).optional(),
+    syntaxType: z.string().min(1).optional(),
+    syntaxComment: z.string().min(1).optional(),
+    syntaxVariable: z.string().min(1).optional(),
+    syntaxOperator: z.string().min(1).optional(),
 });
 const sessionSnapshotSchema = z.object({
     id: z.string().min(1),
@@ -88,9 +99,19 @@ const fileStatResultPayloadSchema = z.object({
 const generateResultPayloadSchema = z.object({
     text: z.string().max(GUEST_GENERATE_TEXT_MAX),
 });
+const shellOutputResultPayloadSchema = z.object({
+    output: z.string(),
+    cursor: z.number(),
+    skipped: z.boolean(),
+});
+const shellStopResultPayloadSchema = z.object({
+    stopped: z.literal(true),
+});
 const hostResultPayloadSchema = z.union([
     guestStorageResultSchema,
     guestWorkspaceSnapshotSchema,
+    shellOutputResultPayloadSchema,
+    shellStopResultPayloadSchema,
     startSessionResultPayloadSchema,
     requestResultPayloadSchema,
     promptResultPayloadSchema,
@@ -151,10 +172,16 @@ const readyPayloadSchema = z.object({
     locale: z.string().min(1),
     directory: z.string().nullable(),
     session: sessionSnapshotSchema,
-    surface: z.enum(['panel', 'dialog', 'page', 'background', 'status', 'file']),
+    surface: z.enum(['panel', 'dialog', 'page', 'background', 'status', 'file', 'popover']),
     connection: guestConnectionSchema,
     settings: guestSettingsSchema,
     item: guestItemSchema,
+    popover: z.object({ id: z.string().min(1).max(80), data: guestPopoverDataSchema }).strict().optional(),
+    features: z.object({
+        deviceStorage: z.literal(true).optional(),
+        statusControls: z.literal(true).optional(),
+        popovers: z.literal(true).optional(),
+    }).optional(),
 });
 const hostResultSchema = z.object({
     ...envelope,
@@ -198,8 +225,36 @@ const hostResultSchema = z.object({
         code: resolveHostRequestErrorCode(message.code),
     };
 });
+const guestRunningShellSchema = z.object({
+    id: z.string().min(1).max(GUEST_SHELL_ID_MAX),
+    sessionID: z.string().min(1).max(1024),
+    command: z.string(),
+    startedAt: z.number().nonnegative(),
+    background: z.boolean(),
+}).strict();
+const guestEndedShellSchema = guestRunningShellSchema.extend({
+    status: z.enum(GUEST_SHELL_END_STATUSES),
+    exit: z.number().int().optional(),
+    endedAt: z.number().nonnegative(),
+}).strict();
+const guestShellsScopeSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('session'), sessionId: z.string().min(1).max(1024) }).strict(),
+    z.object({ kind: z.literal('project'), projectId: z.string().min(1).max(1024) }).strict(),
+    z.object({ kind: z.literal('global') }).strict(),
+]);
+const guestRunningShellsSnapshotSchema = z.object({
+    kind: z.literal('shells'),
+    scope: guestShellsScopeSchema,
+    shells: z.array(guestRunningShellSchema).max(GUEST_SHELLS_MAX),
+    ended: z.array(guestEndedShellSchema).max(GUEST_SHELLS_MAX),
+}).strict();
 export const hostMessageSchema = z.union([
     z.object({ ...envelope, type: z.literal('workspace'), payload: z.object({ subscriptionId: z.string().min(1).max(128), snapshot: guestWorkspaceSnapshotSchema }) }),
+    z.object({
+        ...envelope,
+        type: z.literal('shells'),
+        payload: z.object({ subscriptionId: z.string().min(1).max(128), snapshot: guestRunningShellsSnapshotSchema }),
+    }),
     z.object({
         ...envelope,
         type: z.literal('ready'),
@@ -248,6 +303,12 @@ export const hostMessageSchema = z.union([
             item: guestItemSchema,
         }),
     }),
+    z.object({
+        ...envelope,
+        type: z.literal('status-control-event'),
+        payload: guestStatusControlEventSchema,
+    }),
+    z.object({ ...envelope, type: z.literal('popover-closed'), payload: guestPopoverClosedEventSchema }),
     z.object({
         ...envelope,
         type: z.literal('resolve'),
@@ -310,7 +371,20 @@ export const guestMessageSchema = z.discriminatedUnion('type', [
     z.object({ ...envelope, type: z.literal('workspace-read'), id: z.string().min(1), payload: guestWorkspaceQuerySchema }),
     z.object({ ...envelope, type: z.literal('workspace-subscribe'), id: z.string().min(1), payload: z.object({ subscriptionId: z.string().min(1).max(128), query: guestWorkspaceQuerySchema }) }),
     z.object({ ...envelope, type: z.literal('workspace-unsubscribe'), id: z.string().min(1), payload: z.object({ subscriptionId: z.string().min(1).max(128) }) }),
+    z.object({ ...envelope, type: z.literal('shells-subscribe'), id: z.string().min(1), payload: z.object({ subscriptionId: z.string().min(1).max(128), scope: guestShellsScopeSchema }).strict() }),
+    z.object({ ...envelope, type: z.literal('shells-unsubscribe'), id: z.string().min(1), payload: z.object({ subscriptionId: z.string().min(1).max(128) }).strict() }),
+    z.object({ ...envelope, type: z.literal('shell-output'), id: z.string().min(1), payload: z.object({ shellId: z.string().min(1).max(GUEST_SHELL_ID_MAX), cursor: z.number().int().nonnegative().optional(), tailBytes: z.number().int().positive().max(GUEST_SHELL_OUTPUT_TAIL_MAX).optional() }).strict() }),
+    z.object({ ...envelope, type: z.literal('shell-stop'), id: z.string().min(1), payload: z.object({ shellId: z.string().min(1).max(GUEST_SHELL_ID_MAX) }).strict() }),
     z.object({ ...envelope, type: z.literal('storage'), id: z.string().min(1), payload: guestStorageRequestSchema }),
+    z.object({
+        ...envelope,
+        type: z.literal('status-controls'),
+        id: z.string().min(1),
+        payload: z.object({ controls: guestStatusControlsSchema }).strict(),
+    }),
+    z.object({ ...envelope, type: z.literal('popover-open'), id: z.string().min(1), payload: guestPopoverRequestSchema }),
+    z.object({ ...envelope, type: z.literal('popover-close'), id: z.string().min(1), payload: z.object({ id: z.string().min(1).max(80), reason: z.enum(['closed', 'escape']).optional() }).strict() }),
+    z.object({ ...envelope, type: z.literal('popover-anchor'), id: z.string().min(1), payload: z.object({ id: z.string().min(1).max(80), active: z.boolean() }).strict() }),
     z.object({ ...envelope, type: z.literal('open-session'), id: z.string().min(1), payload: z.object({ sessionId: z.string().min(1).max(1024) }) }),
     z.object({
         ...envelope,

package/dist/schemas.d.ts

@@ -1,6 +1,8 @@
 export { openChamberManifestSchema, PACKAGE_VERSION_PATTERN, packageManifestSchema, parseManifest, parseManifestJson, } from './parse.ts';
 export type { ManifestDocument } from './parse.ts';
 export { guestStorageRequestSchema, guestStorageResultSchema, guestWorkspaceSnapshotSchema } from './workspace-schemas.ts';
+export { guestStatusControlsSchema, guestStatusControlEventSchema } from './status-control-schemas.ts';
+export { guestPopoverClosedEventSchema, guestPopoverRequestSchema } from './popover-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';

package/dist/schemas.js

@@ -3,6 +3,8 @@
 // `@openchamber/sdk`, which carries no schema library.
 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 { guestPopoverClosedEventSchema, guestPopoverRequestSchema } from "./popover-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/shells.d.ts

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

package/dist/shells.js

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