@immediately-run/sandbox-protocol 0.1.0

package/dist/sdk.d.ts

@@ -0,0 +1,378 @@
+/** Every wire name this side speaks, as a union. */
+export type WireName = 'api-catalog' | 'auth-state' | 'compile' | 'debug-enabled' | 'debug-log' | 'debug-query' | 'debug-query-result' | 'diagnostics' | 'dnd-cancel' | 'dropped-item' | 'editor-context' | 'form-factor' | 'fs-change' | 'invitations' | 'launch-dismiss' | 'launch-ended' | 'llm-provider' | 'metadata-update' | 'mount-add' | 'mount-remove' | 'protocol-contribute' | 'protocol-dnd' | 'protocol-editor' | 'protocol-fetch' | 'protocol-ipc' | 'protocol-launch' | 'protocol-llm' | 'protocol-secrets' | 'protocol-settings' | 'protocol-spaces' | 'protocol-task' | 'protocol-theme' | 'protocol-vcs' | 'region-message' | 'request-api-catalog' | 'request-auth-state' | 'request-debug-enabled' | 'request-diagnostics' | 'request-editor-context' | 'request-form-factor' | 'request-handshake' | 'request-invitations' | 'request-llm-provider' | 'request-mounts' | 'request-secrets-metadata' | 'request-session-mounts' | 'request-theme' | 'request-vcs-state' | 'sdk-handshake' | 'secrets-metadata' | 'session-mounts' | 'task-cancel' | 'task-complete' | 'task-input' | 'theme' | 'urlchange' | 'vcs-state';
+/** `api-catalog` — push · host->app. polled with `request-api-catalog`. */
+export declare const API_CATALOG = "api-catalog";
+/** Read off this message today: `methods`. */
+/** `auth-state` — push · host->app. polled with `request-auth-state`. */
+export declare const AUTH_STATE = "auth-state";
+/** Read off this message today: `state`. */
+/** `compile` — message · host->app. */
+export declare const COMPILE = "compile";
+/** `debug-enabled` — push · host->app. polled with `request-debug-enabled`. */
+export declare const DEBUG_ENABLED = "debug-enabled";
+/** Read off this message today: `enabled`. */
+/** `debug-log` — message · app->host. */
+export declare const DEBUG_LOG = "debug-log";
+export interface DebugLogPayload {
+    data: unknown;
+    level: "debug" | "error" | "info" | "warn";
+    message: string;
+}
+/** `debug-query` — message · host->app. */
+export declare const DEBUG_QUERY = "debug-query";
+export interface DebugQueryPayload {
+    id?: unknown;
+    method?: unknown;
+    params?: unknown;
+}
+/** `debug-query-result` — message · app->host. */
+export declare const DEBUG_QUERY_RESULT = "debug-query-result";
+export interface DebugQueryResultPayload {
+    error: string | undefined;
+    id: unknown;
+    ok: boolean;
+    result: unknown;
+}
+/** `diagnostics` — push · host->app. polled with `request-diagnostics`. */
+export declare const DIAGNOSTICS = "diagnostics";
+/** Read off this message today: `buildErrors`, `consoleEntries`, `provenance`. */
+/** `dnd-cancel` — message · app->host. */
+export declare const DND_CANCEL = "dnd-cancel";
+/** `dropped-item` — message · host->app. */
+export declare const DROPPED_ITEM = "dropped-item";
+export interface DroppedItemPayload {
+    from: string;
+    item: {
+        bytes?: unknown | undefined;
+        kind: "dir" | "file";
+        mountId: string;
+        name: string;
+        relPath: string;
+    };
+    position: {
+        x: number;
+        y: number;
+    };
+}
+/** `editor-context` — push · host->app. polled with `request-editor-context`. DIVERGENT (R3-274e): declared-incomplete — the host (site-main channelBridge.ts) sends {dirtyPaths, openFiles, activeFile, viewedFile}; this side declares only {dirtyPaths, activeFile?} while the SDK reads all four. `viewedFile` (R3-268) and `openFiles` never entered this declaration. R3-274e picks one shape for both sides.. */
+export declare const EDITOR_CONTEXT = "editor-context";
+/** Read off this message today: `activeFile`, `dirtyPaths`, `openFiles`, `viewedFile`. */
+/** `form-factor` — push · host->app. polled with `request-form-factor`. */
+export declare const FORM_FACTOR = "form-factor";
+/** Read off this message today: `formFactor`. */
+/** `fs-change` — push · host->app. DIVERGENT (R3-274e): subset-reads with no declared owner on either side — the host sends {paths, epoch}; this side reads only `paths`, the SDK reads both. Nothing forces the two to agree, which is the divergence PLATFORM_LAYERING_SPEC §2 names as the exemplar. The `kind` also differs (message here, push channel in the SDK). R3-274e decides: keep `epoch` or drop it.. */
+export declare const FS_CHANGE = "fs-change";
+/** Read off this message today: `epoch`, `paths`. */
+/** `invitations` — push · host->app. polled with `request-invitations`. */
+export declare const INVITATIONS = "invitations";
+/** Read off this message today: `invites`. */
+/** `launch-dismiss` — message · app->host. */
+export declare const LAUNCH_DISMISS = "launch-dismiss";
+export interface LaunchDismissPayload {
+    launchId: string;
+}
+/** `launch-ended` — message · host->app. */
+export declare const LAUNCH_ENDED = "launch-ended";
+export interface LaunchEndedPayload {
+    launchId: string;
+    status: "dismissed" | "failed" | "revoked";
+}
+/** `llm-provider` — push · host->app. polled with `request-llm-provider`. */
+export declare const LLM_PROVIDER = "llm-provider";
+/** Read off this message today: `provider`. */
+/** `metadata-update` — message · host->app. */
+export declare const METADATA_UPDATE = "metadata-update";
+/** `mount-add` — message · host->app. */
+export declare const MOUNT_ADD = "mount-add";
+/** Read off this message today: `mount`. */
+/** `mount-remove` — message · host->app. */
+export declare const MOUNT_REMOVE = "mount-remove";
+/** Read off this message today: `id`, `path`, `reason`. */
+/** `protocol-contribute` — stream · app->host. */
+export declare const PROTOCOL_CONTRIBUTE = "protocol-contribute";
+/** Params of `protocol-contribute` method `run`. */
+export interface ProtocolContributeRunParams {
+    branchName?: string | undefined;
+    commitMessage: string;
+    mode?: "direct" | "pr" | undefined;
+}
+/** `protocol-dnd` — request · app->host. */
+export declare const PROTOCOL_DND = "protocol-dnd";
+/** Params of `protocol-dnd` method `startDrag`. */
+export interface ProtocolDndStartDragParams {
+    bytes?: {
+        buffer: unknown;
+        byteLength: number;
+        byteOffset: number;
+        BYTES_PER_ELEMENT: number;
+        copyWithin: unknown;
+        entries: unknown;
+        every: unknown;
+        fill: unknown;
+        filter: unknown;
+        find: unknown;
+        findIndex: unknown;
+        forEach: unknown;
+        includes: unknown;
+        indexOf: unknown;
+        join: unknown;
+        keys: unknown;
+        lastIndexOf: unknown;
+        length: number;
+        map: unknown;
+        reduce: unknown;
+        reduceRight: unknown;
+        reverse: unknown;
+        set: unknown;
+        slice: unknown;
+        some: unknown;
+        sort: unknown;
+        subarray: unknown;
+        toLocaleString: unknown;
+        toString: () => string;
+        valueOf: unknown;
+        values: unknown;
+    } | undefined;
+    kind: "dir" | "file";
+    mountId: string;
+    name: string;
+    relPath: string;
+}
+/** `protocol-editor` — request · app->host. */
+export declare const PROTOCOL_EDITOR = "protocol-editor";
+/** `protocol-fetch` — request+stream · app->host. */
+export declare const PROTOCOL_FETCH = "protocol-fetch";
+/** Params of `protocol-fetch` method `fetch`. */
+export interface ProtocolFetchFetchParams {
+    body: string | undefined;
+    headers: Record<string, string> | undefined;
+    method: string | undefined;
+    url: string;
+}
+/** Params of `protocol-fetch` method `fetchStream`. */
+export interface ProtocolFetchFetchStreamParams {
+    body: string | undefined;
+    headers: Record<string, string> | undefined;
+    method: string | undefined;
+    url: string;
+}
+/** `protocol-ipc` — request · app->host. */
+export declare const PROTOCOL_IPC = "protocol-ipc";
+/** Params of `protocol-ipc` method `post`. */
+export interface ProtocolIpcPostParams {
+    msg: unknown;
+    to: string;
+}
+/** Params of `protocol-ipc` method `reveal`. */
+export interface ProtocolIpcRevealParams {
+    to: string;
+}
+/** `protocol-launch` — request · app->host. */
+export declare const PROTOCOL_LAUNCH = "protocol-launch";
+/** Params of `protocol-launch` method `create`. */
+export interface ProtocolLaunchCreateParams {
+    opts: {
+        input?: Record<string, unknown> | undefined;
+        region: "overlay" | "stage";
+    };
+    target: {
+        entryPoint?: string | undefined;
+        task?: string | undefined;
+        version?: string | undefined;
+    };
+}
+/** `protocol-llm` — stream · app->host. */
+export declare const PROTOCOL_LLM = "protocol-llm";
+/** Params of `protocol-llm` method `chat`. */
+export interface ProtocolLlmChatParams {
+    maxTokens?: number | undefined;
+    messages: Array<{
+        content: unknown;
+        role: unknown;
+    }>;
+    modelHint?: "fast" | "smart" | undefined;
+    responseFormat?: "json" | "text" | undefined;
+    tools?: Array<unknown> | undefined;
+}
+/** `protocol-secrets` — request · app->host. */
+export declare const PROTOCOL_SECRETS = "protocol-secrets";
+/** `protocol-settings` — request · app->host. */
+export declare const PROTOCOL_SETTINGS = "protocol-settings";
+/** `protocol-spaces` — request · app->host. */
+export declare const PROTOCOL_SPACES = "protocol-spaces";
+/** Params of `protocol-spaces` method `invite`. */
+export interface ProtocolSpacesInviteParams {
+    login: string;
+    role: "owner" | "reader" | "writer";
+    spaceId: string;
+}
+/** Params of `protocol-spaces` method `list`. */
+export interface ProtocolSpacesListParams {
+    app?: false | true | undefined;
+}
+/** Params of `protocol-spaces` method `lookupUser`. */
+export interface ProtocolSpacesLookupUserParams {
+    login: string;
+}
+/** Params of `protocol-spaces` method `members`. */
+export interface ProtocolSpacesMembersParams {
+    spaceId: string;
+}
+/** Params of `protocol-spaces` method `revokeGrant`. */
+export interface ProtocolSpacesRevokeGrantParams {
+    appKey: string;
+    spaceId: string;
+}
+/** Params of `protocol-spaces` method `setRole`. */
+export interface ProtocolSpacesSetRoleParams {
+    role: "owner" | "reader" | "writer";
+    spaceId: string;
+    uid: string;
+}
+/** Params of `protocol-spaces` method `unshare`. */
+export interface ProtocolSpacesUnshareParams {
+    spaceId: string;
+    uid: string;
+}
+/** `protocol-task` — request · app->host. */
+export declare const PROTOCOL_TASK = "protocol-task";
+/** Params of `protocol-task` method `invoke`. */
+export interface ProtocolTaskInvokeParams {
+    params: Record<string, unknown>;
+    task: string;
+}
+/** `protocol-theme` — request · app->host. */
+export declare const PROTOCOL_THEME = "protocol-theme";
+/** Params of `protocol-theme` method `set`. */
+export interface ProtocolThemeSetParams {
+    theme: "dark" | "light";
+}
+/** `protocol-vcs` — request · app->host. */
+export declare const PROTOCOL_VCS = "protocol-vcs";
+/** `region-message` — message · host->app. */
+export declare const REGION_MESSAGE = "region-message";
+export interface RegionMessagePayload {
+    data: unknown;
+    from: string;
+}
+/** `request-api-catalog` — poll · app->host. */
+export declare const REQUEST_API_CATALOG = "request-api-catalog";
+/** `request-auth-state` — poll · app->host. */
+export declare const REQUEST_AUTH_STATE = "request-auth-state";
+/** `request-debug-enabled` — poll · app->host. */
+export declare const REQUEST_DEBUG_ENABLED = "request-debug-enabled";
+/** `request-diagnostics` — poll · app->host. */
+export declare const REQUEST_DIAGNOSTICS = "request-diagnostics";
+/** `request-editor-context` — poll · app->host. */
+export declare const REQUEST_EDITOR_CONTEXT = "request-editor-context";
+/** `request-form-factor` — poll · app->host. */
+export declare const REQUEST_FORM_FACTOR = "request-form-factor";
+/** `request-handshake` — message · host->app. */
+export declare const REQUEST_HANDSHAKE = "request-handshake";
+/** `request-invitations` — poll · app->host. */
+export declare const REQUEST_INVITATIONS = "request-invitations";
+/** `request-llm-provider` — poll · app->host. */
+export declare const REQUEST_LLM_PROVIDER = "request-llm-provider";
+/** `request-mounts` — message · app->host. */
+export declare const REQUEST_MOUNTS = "request-mounts";
+/** `request-secrets-metadata` — poll · app->host. */
+export declare const REQUEST_SECRETS_METADATA = "request-secrets-metadata";
+/** `request-session-mounts` — poll · app->host. */
+export declare const REQUEST_SESSION_MOUNTS = "request-session-mounts";
+/** `request-theme` — poll · app->host. */
+export declare const REQUEST_THEME = "request-theme";
+/** `request-vcs-state` — poll · app->host. */
+export declare const REQUEST_VCS_STATE = "request-vcs-state";
+/** `sdk-handshake` — message · app->host. DIVERGENT (R3-274e): divergent-declared — TWO producers of one name with different payloads: this frame announces {protocolVersion, sandboxProtocolVersion}, the SDK announces {protocolVersion, sdkVersion}. R3-274d gave the frame its own SANDBOX_PROTOCOL_VERSION (announced additively; the host logs it, fail-open) and retired the sibling-checkout read that used to source `protocolVersion`. R3-274e picks one shape.. */
+export declare const SDK_HANDSHAKE = "sdk-handshake";
+export interface SdkHandshakePayload {
+    protocolVersion: string;
+    sdkVersion: string;
+}
+/** `secrets-metadata` — push · host->app. polled with `request-secrets-metadata`. */
+export declare const SECRETS_METADATA = "secrets-metadata";
+/** Read off this message today: `secrets`. */
+/** `session-mounts` — push · host->app. polled with `request-session-mounts`. */
+export declare const SESSION_MOUNTS = "session-mounts";
+/** Read off this message today: `mounts`. */
+/** `task-cancel` — message · app->host. */
+export declare const TASK_CANCEL = "task-cancel";
+/** `task-complete` — message · app->host. */
+export declare const TASK_COMPLETE = "task-complete";
+export interface TaskCompletePayload {
+    result: unknown;
+}
+/** `task-input` — message · host->app. */
+export declare const TASK_INPUT = "task-input";
+export interface TaskInputPayload {
+    params?: Record<string, unknown> | undefined;
+    task: string;
+}
+/** `theme` — push · host->app. polled with `request-theme`. */
+export declare const THEME = "theme";
+/** Read off this message today: `theme`. */
+/** `urlchange` — message · both. */
+export declare const URLCHANGE = "urlchange";
+/** `vcs-state` — push · host->app. polled with `request-vcs-state`. */
+export declare const VCS_STATE = "vcs-state";
+/** Read off this message today: `branch`, `changes`, `diffLoading`, `prs`. */
+/** Every wire name this side speaks, keyed by its constant. */
+export declare const WIRE_NAMES: {
+    readonly API_CATALOG: "api-catalog";
+    readonly AUTH_STATE: "auth-state";
+    readonly COMPILE: "compile";
+    readonly DEBUG_ENABLED: "debug-enabled";
+    readonly DEBUG_LOG: "debug-log";
+    readonly DEBUG_QUERY: "debug-query";
+    readonly DEBUG_QUERY_RESULT: "debug-query-result";
+    readonly DIAGNOSTICS: "diagnostics";
+    readonly DND_CANCEL: "dnd-cancel";
+    readonly DROPPED_ITEM: "dropped-item";
+    readonly EDITOR_CONTEXT: "editor-context";
+    readonly FORM_FACTOR: "form-factor";
+    readonly FS_CHANGE: "fs-change";
+    readonly INVITATIONS: "invitations";
+    readonly LAUNCH_DISMISS: "launch-dismiss";
+    readonly LAUNCH_ENDED: "launch-ended";
+    readonly LLM_PROVIDER: "llm-provider";
+    readonly METADATA_UPDATE: "metadata-update";
+    readonly MOUNT_ADD: "mount-add";
+    readonly MOUNT_REMOVE: "mount-remove";
+    readonly PROTOCOL_CONTRIBUTE: "protocol-contribute";
+    readonly PROTOCOL_DND: "protocol-dnd";
+    readonly PROTOCOL_EDITOR: "protocol-editor";
+    readonly PROTOCOL_FETCH: "protocol-fetch";
+    readonly PROTOCOL_IPC: "protocol-ipc";
+    readonly PROTOCOL_LAUNCH: "protocol-launch";
+    readonly PROTOCOL_LLM: "protocol-llm";
+    readonly PROTOCOL_SECRETS: "protocol-secrets";
+    readonly PROTOCOL_SETTINGS: "protocol-settings";
+    readonly PROTOCOL_SPACES: "protocol-spaces";
+    readonly PROTOCOL_TASK: "protocol-task";
+    readonly PROTOCOL_THEME: "protocol-theme";
+    readonly PROTOCOL_VCS: "protocol-vcs";
+    readonly REGION_MESSAGE: "region-message";
+    readonly REQUEST_API_CATALOG: "request-api-catalog";
+    readonly REQUEST_AUTH_STATE: "request-auth-state";
+    readonly REQUEST_DEBUG_ENABLED: "request-debug-enabled";
+    readonly REQUEST_DIAGNOSTICS: "request-diagnostics";
+    readonly REQUEST_EDITOR_CONTEXT: "request-editor-context";
+    readonly REQUEST_FORM_FACTOR: "request-form-factor";
+    readonly REQUEST_HANDSHAKE: "request-handshake";
+    readonly REQUEST_INVITATIONS: "request-invitations";
+    readonly REQUEST_LLM_PROVIDER: "request-llm-provider";
+    readonly REQUEST_MOUNTS: "request-mounts";
+    readonly REQUEST_SECRETS_METADATA: "request-secrets-metadata";
+    readonly REQUEST_SESSION_MOUNTS: "request-session-mounts";
+    readonly REQUEST_THEME: "request-theme";
+    readonly REQUEST_VCS_STATE: "request-vcs-state";
+    readonly SDK_HANDSHAKE: "sdk-handshake";
+    readonly SECRETS_METADATA: "secrets-metadata";
+    readonly SESSION_MOUNTS: "session-mounts";
+    readonly TASK_CANCEL: "task-cancel";
+    readonly TASK_COMPLETE: "task-complete";
+    readonly TASK_INPUT: "task-input";
+    readonly THEME: "theme";
+    readonly URLCHANGE: "urlchange";
+    readonly VCS_STATE: "vcs-state";
+};

package/dist/sdk.js

@@ -0,0 +1,202 @@
+"use strict";
+// GENERATED by scripts/generate.mjs — DO NOT EDIT.
+// Source of truth: src/descriptors.protocol.mjs (@immediately-run/sandbox-protocol)
+// descriptorsHash: fbd9b76f9e8edc71
+//
+// The sandbox↔SDK wire vocabulary (PLATFORM_LAYERING_SPEC §2 / S1). Import the
+// constants instead of writing the string: a rename then has ONE edit site and
+// the protocol snapshot gate sees it. Payload types are emitted for every name
+// that has a declared shape; a name handled as `any` today gets its read field
+// list in the doc comment instead (R3-274e is where those grow real types).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECRETS_METADATA = exports.SDK_HANDSHAKE = exports.REQUEST_VCS_STATE = exports.REQUEST_THEME = exports.REQUEST_SESSION_MOUNTS = exports.REQUEST_SECRETS_METADATA = exports.REQUEST_MOUNTS = exports.REQUEST_LLM_PROVIDER = exports.REQUEST_INVITATIONS = exports.REQUEST_HANDSHAKE = exports.REQUEST_FORM_FACTOR = exports.REQUEST_EDITOR_CONTEXT = exports.REQUEST_DIAGNOSTICS = exports.REQUEST_DEBUG_ENABLED = exports.REQUEST_AUTH_STATE = exports.REQUEST_API_CATALOG = exports.REGION_MESSAGE = exports.PROTOCOL_VCS = exports.PROTOCOL_THEME = exports.PROTOCOL_TASK = exports.PROTOCOL_SPACES = exports.PROTOCOL_SETTINGS = exports.PROTOCOL_SECRETS = exports.PROTOCOL_LLM = exports.PROTOCOL_LAUNCH = exports.PROTOCOL_IPC = exports.PROTOCOL_FETCH = exports.PROTOCOL_EDITOR = exports.PROTOCOL_DND = exports.PROTOCOL_CONTRIBUTE = exports.MOUNT_REMOVE = exports.MOUNT_ADD = exports.METADATA_UPDATE = exports.LLM_PROVIDER = exports.LAUNCH_ENDED = exports.LAUNCH_DISMISS = exports.INVITATIONS = exports.FS_CHANGE = exports.FORM_FACTOR = exports.EDITOR_CONTEXT = exports.DROPPED_ITEM = exports.DND_CANCEL = exports.DIAGNOSTICS = exports.DEBUG_QUERY_RESULT = exports.DEBUG_QUERY = exports.DEBUG_LOG = exports.DEBUG_ENABLED = exports.COMPILE = exports.AUTH_STATE = exports.API_CATALOG = void 0;
+exports.WIRE_NAMES = exports.VCS_STATE = exports.URLCHANGE = exports.THEME = exports.TASK_INPUT = exports.TASK_COMPLETE = exports.TASK_CANCEL = exports.SESSION_MOUNTS = void 0;
+/** `api-catalog` — push · host->app. polled with `request-api-catalog`. */
+exports.API_CATALOG = 'api-catalog';
+/** Read off this message today: `methods`. */
+/** `auth-state` — push · host->app. polled with `request-auth-state`. */
+exports.AUTH_STATE = 'auth-state';
+/** Read off this message today: `state`. */
+/** `compile` — message · host->app. */
+exports.COMPILE = 'compile';
+/** `debug-enabled` — push · host->app. polled with `request-debug-enabled`. */
+exports.DEBUG_ENABLED = 'debug-enabled';
+/** Read off this message today: `enabled`. */
+/** `debug-log` — message · app->host. */
+exports.DEBUG_LOG = 'debug-log';
+/** `debug-query` — message · host->app. */
+exports.DEBUG_QUERY = 'debug-query';
+/** `debug-query-result` — message · app->host. */
+exports.DEBUG_QUERY_RESULT = 'debug-query-result';
+/** `diagnostics` — push · host->app. polled with `request-diagnostics`. */
+exports.DIAGNOSTICS = 'diagnostics';
+/** Read off this message today: `buildErrors`, `consoleEntries`, `provenance`. */
+/** `dnd-cancel` — message · app->host. */
+exports.DND_CANCEL = 'dnd-cancel';
+/** `dropped-item` — message · host->app. */
+exports.DROPPED_ITEM = 'dropped-item';
+/** `editor-context` — push · host->app. polled with `request-editor-context`. DIVERGENT (R3-274e): declared-incomplete — the host (site-main channelBridge.ts) sends {dirtyPaths, openFiles, activeFile, viewedFile}; this side declares only {dirtyPaths, activeFile?} while the SDK reads all four. `viewedFile` (R3-268) and `openFiles` never entered this declaration. R3-274e picks one shape for both sides.. */
+exports.EDITOR_CONTEXT = 'editor-context';
+/** Read off this message today: `activeFile`, `dirtyPaths`, `openFiles`, `viewedFile`. */
+/** `form-factor` — push · host->app. polled with `request-form-factor`. */
+exports.FORM_FACTOR = 'form-factor';
+/** Read off this message today: `formFactor`. */
+/** `fs-change` — push · host->app. DIVERGENT (R3-274e): subset-reads with no declared owner on either side — the host sends {paths, epoch}; this side reads only `paths`, the SDK reads both. Nothing forces the two to agree, which is the divergence PLATFORM_LAYERING_SPEC §2 names as the exemplar. The `kind` also differs (message here, push channel in the SDK). R3-274e decides: keep `epoch` or drop it.. */
+exports.FS_CHANGE = 'fs-change';
+/** Read off this message today: `epoch`, `paths`. */
+/** `invitations` — push · host->app. polled with `request-invitations`. */
+exports.INVITATIONS = 'invitations';
+/** Read off this message today: `invites`. */
+/** `launch-dismiss` — message · app->host. */
+exports.LAUNCH_DISMISS = 'launch-dismiss';
+/** `launch-ended` — message · host->app. */
+exports.LAUNCH_ENDED = 'launch-ended';
+/** `llm-provider` — push · host->app. polled with `request-llm-provider`. */
+exports.LLM_PROVIDER = 'llm-provider';
+/** Read off this message today: `provider`. */
+/** `metadata-update` — message · host->app. */
+exports.METADATA_UPDATE = 'metadata-update';
+/** `mount-add` — message · host->app. */
+exports.MOUNT_ADD = 'mount-add';
+/** Read off this message today: `mount`. */
+/** `mount-remove` — message · host->app. */
+exports.MOUNT_REMOVE = 'mount-remove';
+/** Read off this message today: `id`, `path`, `reason`. */
+/** `protocol-contribute` — stream · app->host. */
+exports.PROTOCOL_CONTRIBUTE = 'protocol-contribute';
+/** `protocol-dnd` — request · app->host. */
+exports.PROTOCOL_DND = 'protocol-dnd';
+/** `protocol-editor` — request · app->host. */
+exports.PROTOCOL_EDITOR = 'protocol-editor';
+/** `protocol-fetch` — request+stream · app->host. */
+exports.PROTOCOL_FETCH = 'protocol-fetch';
+/** `protocol-ipc` — request · app->host. */
+exports.PROTOCOL_IPC = 'protocol-ipc';
+/** `protocol-launch` — request · app->host. */
+exports.PROTOCOL_LAUNCH = 'protocol-launch';
+/** `protocol-llm` — stream · app->host. */
+exports.PROTOCOL_LLM = 'protocol-llm';
+/** `protocol-secrets` — request · app->host. */
+exports.PROTOCOL_SECRETS = 'protocol-secrets';
+/** `protocol-settings` — request · app->host. */
+exports.PROTOCOL_SETTINGS = 'protocol-settings';
+/** `protocol-spaces` — request · app->host. */
+exports.PROTOCOL_SPACES = 'protocol-spaces';
+/** `protocol-task` — request · app->host. */
+exports.PROTOCOL_TASK = 'protocol-task';
+/** `protocol-theme` — request · app->host. */
+exports.PROTOCOL_THEME = 'protocol-theme';
+/** `protocol-vcs` — request · app->host. */
+exports.PROTOCOL_VCS = 'protocol-vcs';
+/** `region-message` — message · host->app. */
+exports.REGION_MESSAGE = 'region-message';
+/** `request-api-catalog` — poll · app->host. */
+exports.REQUEST_API_CATALOG = 'request-api-catalog';
+/** `request-auth-state` — poll · app->host. */
+exports.REQUEST_AUTH_STATE = 'request-auth-state';
+/** `request-debug-enabled` — poll · app->host. */
+exports.REQUEST_DEBUG_ENABLED = 'request-debug-enabled';
+/** `request-diagnostics` — poll · app->host. */
+exports.REQUEST_DIAGNOSTICS = 'request-diagnostics';
+/** `request-editor-context` — poll · app->host. */
+exports.REQUEST_EDITOR_CONTEXT = 'request-editor-context';
+/** `request-form-factor` — poll · app->host. */
+exports.REQUEST_FORM_FACTOR = 'request-form-factor';
+/** `request-handshake` — message · host->app. */
+exports.REQUEST_HANDSHAKE = 'request-handshake';
+/** `request-invitations` — poll · app->host. */
+exports.REQUEST_INVITATIONS = 'request-invitations';
+/** `request-llm-provider` — poll · app->host. */
+exports.REQUEST_LLM_PROVIDER = 'request-llm-provider';
+/** `request-mounts` — message · app->host. */
+exports.REQUEST_MOUNTS = 'request-mounts';
+/** `request-secrets-metadata` — poll · app->host. */
+exports.REQUEST_SECRETS_METADATA = 'request-secrets-metadata';
+/** `request-session-mounts` — poll · app->host. */
+exports.REQUEST_SESSION_MOUNTS = 'request-session-mounts';
+/** `request-theme` — poll · app->host. */
+exports.REQUEST_THEME = 'request-theme';
+/** `request-vcs-state` — poll · app->host. */
+exports.REQUEST_VCS_STATE = 'request-vcs-state';
+/** `sdk-handshake` — message · app->host. DIVERGENT (R3-274e): divergent-declared — TWO producers of one name with different payloads: this frame announces {protocolVersion, sandboxProtocolVersion}, the SDK announces {protocolVersion, sdkVersion}. R3-274d gave the frame its own SANDBOX_PROTOCOL_VERSION (announced additively; the host logs it, fail-open) and retired the sibling-checkout read that used to source `protocolVersion`. R3-274e picks one shape.. */
+exports.SDK_HANDSHAKE = 'sdk-handshake';
+/** `secrets-metadata` — push · host->app. polled with `request-secrets-metadata`. */
+exports.SECRETS_METADATA = 'secrets-metadata';
+/** Read off this message today: `secrets`. */
+/** `session-mounts` — push · host->app. polled with `request-session-mounts`. */
+exports.SESSION_MOUNTS = 'session-mounts';
+/** Read off this message today: `mounts`. */
+/** `task-cancel` — message · app->host. */
+exports.TASK_CANCEL = 'task-cancel';
+/** `task-complete` — message · app->host. */
+exports.TASK_COMPLETE = 'task-complete';
+/** `task-input` — message · host->app. */
+exports.TASK_INPUT = 'task-input';
+/** `theme` — push · host->app. polled with `request-theme`. */
+exports.THEME = 'theme';
+/** Read off this message today: `theme`. */
+/** `urlchange` — message · both. */
+exports.URLCHANGE = 'urlchange';
+/** `vcs-state` — push · host->app. polled with `request-vcs-state`. */
+exports.VCS_STATE = 'vcs-state';
+/** Read off this message today: `branch`, `changes`, `diffLoading`, `prs`. */
+/** Every wire name this side speaks, keyed by its constant. */
+exports.WIRE_NAMES = {
+    API_CATALOG: exports.API_CATALOG,
+    AUTH_STATE: exports.AUTH_STATE,
+    COMPILE: exports.COMPILE,
+    DEBUG_ENABLED: exports.DEBUG_ENABLED,
+    DEBUG_LOG: exports.DEBUG_LOG,
+    DEBUG_QUERY: exports.DEBUG_QUERY,
+    DEBUG_QUERY_RESULT: exports.DEBUG_QUERY_RESULT,
+    DIAGNOSTICS: exports.DIAGNOSTICS,
+    DND_CANCEL: exports.DND_CANCEL,
+    DROPPED_ITEM: exports.DROPPED_ITEM,
+    EDITOR_CONTEXT: exports.EDITOR_CONTEXT,
+    FORM_FACTOR: exports.FORM_FACTOR,
+    FS_CHANGE: exports.FS_CHANGE,
+    INVITATIONS: exports.INVITATIONS,
+    LAUNCH_DISMISS: exports.LAUNCH_DISMISS,
+    LAUNCH_ENDED: exports.LAUNCH_ENDED,
+    LLM_PROVIDER: exports.LLM_PROVIDER,
+    METADATA_UPDATE: exports.METADATA_UPDATE,
+    MOUNT_ADD: exports.MOUNT_ADD,
+    MOUNT_REMOVE: exports.MOUNT_REMOVE,
+    PROTOCOL_CONTRIBUTE: exports.PROTOCOL_CONTRIBUTE,
+    PROTOCOL_DND: exports.PROTOCOL_DND,
+    PROTOCOL_EDITOR: exports.PROTOCOL_EDITOR,
+    PROTOCOL_FETCH: exports.PROTOCOL_FETCH,
+    PROTOCOL_IPC: exports.PROTOCOL_IPC,
+    PROTOCOL_LAUNCH: exports.PROTOCOL_LAUNCH,
+    PROTOCOL_LLM: exports.PROTOCOL_LLM,
+    PROTOCOL_SECRETS: exports.PROTOCOL_SECRETS,
+    PROTOCOL_SETTINGS: exports.PROTOCOL_SETTINGS,
+    PROTOCOL_SPACES: exports.PROTOCOL_SPACES,
+    PROTOCOL_TASK: exports.PROTOCOL_TASK,
+    PROTOCOL_THEME: exports.PROTOCOL_THEME,
+    PROTOCOL_VCS: exports.PROTOCOL_VCS,
+    REGION_MESSAGE: exports.REGION_MESSAGE,
+    REQUEST_API_CATALOG: exports.REQUEST_API_CATALOG,
+    REQUEST_AUTH_STATE: exports.REQUEST_AUTH_STATE,
+    REQUEST_DEBUG_ENABLED: exports.REQUEST_DEBUG_ENABLED,
+    REQUEST_DIAGNOSTICS: exports.REQUEST_DIAGNOSTICS,
+    REQUEST_EDITOR_CONTEXT: exports.REQUEST_EDITOR_CONTEXT,
+    REQUEST_FORM_FACTOR: exports.REQUEST_FORM_FACTOR,
+    REQUEST_HANDSHAKE: exports.REQUEST_HANDSHAKE,
+    REQUEST_INVITATIONS: exports.REQUEST_INVITATIONS,
+    REQUEST_LLM_PROVIDER: exports.REQUEST_LLM_PROVIDER,
+    REQUEST_MOUNTS: exports.REQUEST_MOUNTS,
+    REQUEST_SECRETS_METADATA: exports.REQUEST_SECRETS_METADATA,
+    REQUEST_SESSION_MOUNTS: exports.REQUEST_SESSION_MOUNTS,
+    REQUEST_THEME: exports.REQUEST_THEME,
+    REQUEST_VCS_STATE: exports.REQUEST_VCS_STATE,
+    SDK_HANDSHAKE: exports.SDK_HANDSHAKE,
+    SECRETS_METADATA: exports.SECRETS_METADATA,
+    SESSION_MOUNTS: exports.SESSION_MOUNTS,
+    TASK_CANCEL: exports.TASK_CANCEL,
+    TASK_COMPLETE: exports.TASK_COMPLETE,
+    TASK_INPUT: exports.TASK_INPUT,
+    THEME: exports.THEME,
+    URLCHANGE: exports.URLCHANGE,
+    VCS_STATE: exports.VCS_STATE,
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@immediately-run/sandbox-protocol",
+  "version": "0.1.0",
+  "description": "The sandbox<->SDK wire protocol: ONE descriptor set, projected into the wire-name constants, the payload types, and the per-side snapshots both repos gate against (PLATFORM_LAYERING_SPEC S1). Consumed by sandbox and immediately-run-sdk so a wire change is a version bump, not a hand-copied file.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/immediately-run/immediately-run-sandbox-protocol.git"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./sandbox": {
+      "types": "./dist/sandbox.d.ts",
+      "default": "./dist/sandbox.js"
+    },
+    "./sdk": {
+      "types": "./dist/sdk.d.ts",
+      "default": "./dist/sdk.js"
+    },
+    "./snapshots/sandbox": "./snapshots/sandbox.json",
+    "./snapshots/sdk": "./snapshots/sdk.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "snapshots"
+  ],
+  "scripts": {
+    "generate": "node scripts/generate.mjs",
+    "build": "npm run generate && tsc -p tsconfig.build.json",
+    "test": "jest",
+    "lint": "eslint src test",
+    "check:drift": "node scripts/verify-drift.mjs --self-test && node scripts/verify-drift.mjs",
+    "check:dependency-free": "node scripts/check-dependency-free.mjs --self-test && node scripts/check-dependency-free.mjs",
+    "verify": "npm run build && npm test && npm run lint && npm run check:drift && npm run check:dependency-free",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.17.0",
+    "eslint": "^9.18.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.20.0"
+  }
+}