@openchamber/sdk 1.23.2-preview.1

package/dist/contract.js

@@ -0,0 +1,256 @@
+import { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL } from "./api-version.js";
+export const START_SESSION_SENT = ['sent', 'no-model', 'skipped', 'failed'];
+export const SESSION_LIFECYCLE_PHASES = ['started', 'completed', 'failure'];
+export const GUEST_FILE_ENTRY_KINDS = ['file', 'directory', 'other'];
+export const GUEST_FILE_STAT_KINDS = ['file', 'directory', 'other', 'missing'];
+export const isStartSessionResult = (value) => Boolean(value && 'sessionId' in value);
+export const isPromptResult = (value) => Boolean(value && 'sent' in value && !('sessionId' in value));
+export const EMPTY_GUEST_CONNECTION = {
+    connected: false,
+    account: '',
+};
+export const isGuestMessageItem = (item) => (item !== null && item.kind === 'message');
+export const isGuestSessionItem = (item) => (item !== null && item.kind === 'session');
+/** The composer chip: what the guest handed to `attach`, with `text` filled from the chip. */
+export const isGuestAttachItem = (item) => (item !== null && item.kind !== 'message' && item.kind !== 'session');
+export const GUEST_TOAST_MAX = 500;
+export const GUEST_CLIPBOARD_TEXT_MAX = 32_000;
+export const GUEST_COMPOSE_TEXT_MAX = 16_000;
+export const GUEST_ATTACH_ID_MAX = 128;
+export const GUEST_ATTACH_TITLE_MAX = 200;
+export const GUEST_ATTACH_URL_MAX = 2_000;
+export const GUEST_ATTACH_TEXT_MAX = 16_000;
+export const GUEST_ATTACH_AUTHOR_MAX = 80;
+export const GUEST_ATTACH_BRANCH_MAX = 200;
+/** `JSON.stringify(data).length` ceiling for `AttachIssueRequest.data`. */
+export const GUEST_ATTACH_DATA_MAX = 16_000;
+export const GUEST_ACCOUNT_MAX = 200;
+export const GUEST_SESSION_MODEL_MAX = 200;
+export const GUEST_SESSION_AGENT_MAX = 80;
+export const GUEST_SETTING_VALUE_MAX = 2_000;
+export const GUEST_REQUEST_PATH_MAX = 2_000;
+export const GUEST_REQUEST_BODY_MAX = 64_000;
+export const GUEST_REQUEST_RESPONSE_MAX = 256_000;
+export const GUEST_REQUEST_TIMEOUT_MS = 20_000;
+/** Guest file path, in characters. */
+export const GUEST_FILE_PATH_MAX = 1_024;
+/** File content in characters, read and write alike. */
+export const GUEST_FILE_CONTENT_MAX = 2_000_000;
+/** Entries a `listDir` answer carries; longer directories are truncated. */
+export const GUEST_FILE_LIST_MAX = 2_000;
+/** Characters in a `generate` prompt. */
+export const GUEST_GENERATE_PROMPT_MAX = 64_000;
+/** Characters in a `generate` system prompt. */
+export const GUEST_GENERATE_SYSTEM_MAX = 8_000;
+/** Largest `maxOutputTokens` a guest may ask for. */
+export const GUEST_GENERATE_OUTPUT_TOKENS_MAX = 4_000;
+/** Characters in a `generate` answer. */
+export const GUEST_GENERATE_TEXT_MAX = 256_000;
+/** How long `generate` waits for the model before `HOST_TIMEOUT`. */
+export const GUEST_GENERATE_TIMEOUT_MS = 90_000;
+/** Characters of one message's text on a `GuestMessageItem` or a `GuestSessionItem` message. */
+export const GUEST_ITEM_MESSAGE_TEXT_MAX = 200_000;
+/** `JSON.stringify` length ceiling for a `GuestSessionItem`; the host drops the oldest messages to stay under it. */
+export const GUEST_ITEM_SESSION_MAX = 2_000_000;
+/** Largest count a rail badge shows. */
+export const GUEST_BADGE_MAX = 999;
+/** Characters in a `resolve-result` error string. */
+export const GUEST_RESOLVE_ERROR_MAX = 500;
+export const HOST_REQUEST_ERROR_CODES = [
+    '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',
+];
+export const SERVICE_STATUS_VALUES = ['stopped', 'starting', 'ready', 'failed'];
+const hostRequestErrorCodeSet = new Set(HOST_REQUEST_ERROR_CODES);
+export const isHostRequestErrorCode = (value) => (hostRequestErrorCodeSet.has(value));
+/** Unknown or omitted wire codes become HOST_REJECTED. */
+export const resolveHostRequestErrorCode = (value) => (value && isHostRequestErrorCode(value) ? value : 'HOST_REJECTED');
+export const isJsonValue = (value) => {
+    if (value === undefined)
+        return false;
+    if (value === null || value === true || value === false)
+        return true;
+    if (String(value) === value)
+        return true;
+    if (Number(value) === value)
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (Object(value) === value)
+        return Object.values(value).every(isJsonValue);
+    return false;
+};
+/** Whether `data` is plain JSON that serializes within `GUEST_ATTACH_DATA_MAX`. */
+export const isAttachData = (value) => (isJsonValue(value) && JSON.stringify(value).length <= GUEST_ATTACH_DATA_MAX);
+const clampBranch = (value) => (value?.trim().slice(0, GUEST_ATTACH_BRANCH_MAX) ?? '');
+/** Guest attach is dropped by the host schema if these limits overflow. */
+export const clampAttachRequest = (request) => {
+    const id = request.id.trim().slice(0, GUEST_ATTACH_ID_MAX);
+    const title = request.title.trim().slice(0, GUEST_ATTACH_TITLE_MAX);
+    const url = request.url.trim().slice(0, GUEST_ATTACH_URL_MAX);
+    const text = request.text?.trim().slice(0, GUEST_ATTACH_TEXT_MAX);
+    const author = request.author?.trim().slice(0, GUEST_ATTACH_AUTHOR_MAX);
+    const kind = request.kind === 'pull' ? 'pull' : 'issue';
+    const next = {
+        providerId: request.providerId.trim(),
+        id,
+        title: title || id,
+        url,
+        kind,
+    };
+    if (text) {
+        next.text = text;
+    }
+    if (author) {
+        next.author = author;
+    }
+    if (kind === 'pull') {
+        const head = clampBranch(request.branches?.head);
+        const base = clampBranch(request.branches?.base);
+        if (head && base) {
+            next.branches = { head, base };
+        }
+    }
+    if (isAttachData(request.data)) {
+        next.data = request.data;
+    }
+    return next;
+};
+/** Same attach clamp. `worktree` stays only when the guest asked for one. */
+export const clampStartSessionRequest = (request) => {
+    const next = clampAttachRequest(request);
+    if (request.projectId)
+        next.projectId = request.projectId;
+    if (request.navigation)
+        next.navigation = request.navigation;
+    if (request.worktree) {
+        next.worktree = request.worktree;
+    }
+    return next;
+};
+/** Prompt text uses the compose limit. `send` stays only when the guest asked. */
+export const clampPromptRequest = (request) => {
+    const next = {
+        text: request.text.trim().slice(0, GUEST_COMPOSE_TEXT_MAX),
+    };
+    if (request.send) {
+        next.send = true;
+    }
+    return next;
+};
+/** Badge counts are whole numbers from 0 to `GUEST_BADGE_MAX`; anything else clears. */
+export const clampBadgeCount = (count) => {
+    if (count === null || !Number.isFinite(count))
+        return null;
+    return Math.min(GUEST_BADGE_MAX, Math.max(0, Math.round(count)));
+};
+/**
+ * Which grant a file path needs. `/…` and `~/…` are outside the project and
+ * go through the declared `filesystem` patterns; anything else is joined to
+ * the open project directory.
+ */
+export const guestFileScope = (path) => (path.startsWith('/') || path === '~' || path.startsWith('~/') ? 'filesystem' : 'project');
+/**
+ * What the host schema accepts as a file path. Semantics (`..`, symlinks,
+ * declared patterns) are the server's call and come back as `BAD_PATH`; this
+ * only keeps a message from being dropped unanswered.
+ */
+export const isGuestFilePath = (value) => (value.length > 0
+    && value.length <= GUEST_FILE_PATH_MAX
+    && !value.includes('\0')
+    && !value.includes('\\'));
+export const ATTACH_PROVIDER_ID = /^[a-z][a-z0-9-]*$/;
+export const SETTING_KEY = /^[a-z][a-z0-9-]*$/;
+export const isGuestRequestPath = (value) => {
+    if (!value.startsWith('/') || value.includes('\0') || value.includes('\\') || value.includes('://')) {
+        return false;
+    }
+    if (value.length > GUEST_REQUEST_PATH_MAX) {
+        return false;
+    }
+    const segments = value.split('/');
+    return !segments.some((segment) => segment === '.' || segment === '..');
+};
+const serviceStatusSet = new Set(SERVICE_STATUS_VALUES);
+export const isServiceStatusResult = (value) => Boolean(value && 'status' in value && serviceStatusSet.has(String(value.status)) && !('body' in value));
+export const isGuestRequestResult = (value) => Boolean(value && 'status' in value && 'body' in value && Number.isInteger(value.status));
+export const isFileReadResult = (value) => Boolean(value && 'content' in value && String(value.content) === value.content);
+export const isFileWriteResult = (value) => Boolean(value && 'written' in value && value.written === true);
+export const isFileListResult = (value) => Boolean(value && 'entries' in value && Array.isArray(value.entries));
+const fileStatKindSet = new Set(GUEST_FILE_STAT_KINDS);
+export const isFileStatResult = (value) => Boolean(value && 'kind' in value && 'size' in value && fileStatKindSet.has(String(value.kind)) && Number.isFinite(value.size));
+export const isGenerateResult = (value) => Boolean(value && 'text' in value && String(value.text) === value.text && !('status' in value));
+const HOST_PUSH_TYPES = new Set([
+    'workspace',
+    'ready', 'directory', 'session', 'connection', 'settings', 'session-lifecycle', 'item', 'resolve',
+]);
+const asWireRecord = (data) => (Object(data) === data ? data : null);
+const isNonEmptyString = (value) => (String(value) === value && value.length > 0);
+const readResultMessage = (wire) => {
+    if (!isNonEmptyString(wire.id))
+        return null;
+    if (wire.ok === true) {
+        const message = {
+            channel: OPENCHAMBER_SDK_CHANNEL,
+            v: OPENCHAMBER_SDK_API_VERSION,
+            type: 'result',
+            id: wire.id,
+            ok: true,
+        };
+        if (Object(wire.payload) === wire.payload) {
+            // SAFETY: a trusted host answered an id this client issued; the per-call
+            // guards in host.ts (isStartSessionResult and friends) narrow the payload
+            // before it reaches a caller.
+            message.payload = wire.payload;
+        }
+        return message;
+    }
+    if (wire.ok === false && isNonEmptyString(wire.error)) {
+        return {
+            channel: OPENCHAMBER_SDK_CHANNEL,
+            v: OPENCHAMBER_SDK_API_VERSION,
+            type: 'result',
+            id: wire.id,
+            ok: false,
+            error: wire.error,
+            code: resolveHostRequestErrorCode(isNonEmptyString(wire.code) ? wire.code : undefined),
+        };
+    }
+    return null;
+};
+/**
+ * The guest's read of a host message. The host is the trusted parent frame
+ * (the client only listens to `event.source === parent`), so this checks the
+ * envelope and the discriminant rather than every field, and the guest bundle
+ * carries no schema library for it. The host side parses guest input with
+ * `guestMessageSchema` in `@openchamber/sdk/schemas`.
+ */
+export const readHostMessage = (data) => {
+    const wire = asWireRecord(data);
+    if (!wire || wire.channel !== OPENCHAMBER_SDK_CHANNEL || wire.v !== OPENCHAMBER_SDK_API_VERSION)
+        return null;
+    if (wire.type === 'result')
+        return readResultMessage(wire);
+    if (!HOST_PUSH_TYPES.has(String(wire.type)) || Object(wire.payload) !== wire.payload)
+        return null;
+    // SAFETY: envelope and discriminant verified above and the sender is the
+    // trusted parent frame; protocol.ts asserts these push shapes against the
+    // host's own schema at compile time.
+    return wire;
+};

package/dist/host-version.d.ts

@@ -0,0 +1,16 @@
+/** `1.22.0` or `>=1.22.0`. Ranges beyond a floor are not accepted. */
+export declare const OPENCHAMBER_ENGINE_PATTERN: RegExp;
+export type OpenChamberVersionParts = {
+    major: number;
+    minor: number;
+    patch: number;
+};
+export declare const parseOpenChamberVersion: (value: string) => OpenChamberVersionParts | null;
+export declare const compareOpenChamberVersions: (left: string, right: string) => number;
+/** Normalize `>=1.22.0` / `1.22.0` to the floor version string. */
+export declare const openChamberEngineMinimum: (engine: string) => string | null;
+/**
+ * True when this OpenChamber build is new enough for the guest's `engines.openchamber`.
+ * Unknown host versions fail closed when an engine is declared.
+ */
+export declare const hostMeetsOpenChamberEngine: (hostVersion: string, engine: string) => boolean;

package/dist/host-version.js

@@ -0,0 +1,50 @@
+const CORE_VERSION = /^(\d+)\.(\d+)\.(\d+)$/;
+/** `1.22.0` or `>=1.22.0`. Ranges beyond a floor are not accepted. */
+export const OPENCHAMBER_ENGINE_PATTERN = /^(>=)?\d+\.\d+\.\d+$/;
+export const parseOpenChamberVersion = (value) => {
+    const core = String(value || '').trim().replace(/^v/i, '').split(/[-+]/)[0] ?? '';
+    const match = CORE_VERSION.exec(core);
+    if (!match) {
+        return null;
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+};
+export const compareOpenChamberVersions = (left, right) => {
+    const a = parseOpenChamberVersion(left);
+    const b = parseOpenChamberVersion(right);
+    if (!a || !b) {
+        return 0;
+    }
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    return a.patch - b.patch;
+};
+/** Normalize `>=1.22.0` / `1.22.0` to the floor version string. */
+export const openChamberEngineMinimum = (engine) => {
+    const trimmed = engine.trim();
+    if (!OPENCHAMBER_ENGINE_PATTERN.test(trimmed)) {
+        return null;
+    }
+    const floor = trimmed.startsWith('>=') ? trimmed.slice(2) : trimmed;
+    return parseOpenChamberVersion(floor) ? floor : null;
+};
+/**
+ * True when this OpenChamber build is new enough for the guest's `engines.openchamber`.
+ * Unknown host versions fail closed when an engine is declared.
+ */
+export const hostMeetsOpenChamberEngine = (hostVersion, engine) => {
+    const minimum = openChamberEngineMinimum(engine);
+    if (!minimum) {
+        return false;
+    }
+    if (!parseOpenChamberVersion(hostVersion)) {
+        return false;
+    }
+    return compareOpenChamberVersions(hostVersion, minimum) >= 0;
+};

package/dist/host.d.ts

@@ -0,0 +1,101 @@
+import { type GuestProjectsSnapshot, type GuestWorktreesSnapshot, type GuestSessionsSnapshot } from './workspace.ts';
+import type { JsonValue } from './contract.ts';
+import { type AttachIssueRequest, type ComposeRequest, type PromptRequest, type PromptResult, type SessionLifecycleEvent, type StartSessionRequest, type GuestConnection, type GuestItem, type GuestMessage, type GuestRequest, type GuestRequestResult, type GuestSettings, type HostReadyContext, type HostRequestErrorCode, type ResolveRequest, type SessionSnapshot, type StartSessionResult, type ToastRequest, type ServiceStatusResult, type FileListResult, type FileReadResult, type FileStatResult, type FileWriteResult, type GenerateRequest, type GenerateResult } from './contract.ts';
+export type HostFrame = {
+    addEventListener: Window['addEventListener'];
+    removeEventListener: Window['removeEventListener'];
+    parent: {
+        postMessage: (message: GuestMessage, targetOrigin: string) => void;
+    };
+};
+export type HostClientOptions = {
+    /** Test seam. Defaults to `window`. */
+    target?: HostFrame;
+    /** Test seam. Defaults to `source === parent`. */
+    acceptSource?: (source: MessageEvent['source']) => boolean;
+    /** Test seam. Defaults to `GUEST_REQUEST_TIMEOUT_MS`. */
+    requestTimeoutMs?: number;
+};
+export type HostClient = {
+    listProjects: () => Promise<GuestProjectsSnapshot>;
+    listWorktrees: (projectId: string) => Promise<GuestWorktreesSnapshot>;
+    listSessions: (projectId: string) => Promise<GuestSessionsSnapshot>;
+    onProjects: (listener: (snapshot: GuestProjectsSnapshot) => void) => Promise<() => void>;
+    onWorktrees: (projectId: string, listener: (snapshot: GuestWorktreesSnapshot) => void) => Promise<() => void>;
+    onSessions: (projectId: string, listener: (snapshot: GuestSessionsSnapshot) => void) => Promise<() => void>;
+    openSession: (sessionId: string) => Promise<void>;
+    storage: {
+        get: (key: string) => Promise<JsonValue | undefined>;
+        set: (key: string, value: JsonValue) => Promise<void>;
+        delete: (key: string) => Promise<void>;
+        keys: () => Promise<string[]>;
+    };
+    onReady: (listener: (context: HostReadyContext) => void) => () => void;
+    onDirectory: (listener: (directory: string | null) => void) => () => void;
+    onSession: (listener: (session: SessionSnapshot | null) => void) => () => void;
+    onSessionLifecycle: (listener: (event: SessionLifecycleEvent) => void) => () => void;
+    onConnection: (listener: (connection: GuestConnection) => void) => () => void;
+    onSettings: (listener: (settings: GuestSettings) => void) => () => void;
+    /**
+     * The item this surface was opened for: a chip (`AttachIssueRequest`), a
+     * message (`GuestMessageItem`), or a session (`GuestSessionItem`). Replays
+     * the last value; `null` when there is none.
+     */
+    onItem: (listener: (item: GuestItem | null) => void) => () => void;
+    /**
+     * Answer the host when the user submits one of this package's
+     * `contributes.commands`. Return the chip to attach, or `null` for nothing
+     * (the host shows a short notice). A thrown error reaches the user as a
+     * toast. One handler at a time; the returned function removes it.
+     */
+    onResolve: (handler: (request: ResolveRequest) => Promise<AttachIssueRequest | null> | AttachIssueRequest | null) => () => void;
+    toast: (request: ToastRequest) => Promise<void>;
+    openUrl: (url: string) => Promise<void>;
+    openSurface: (surfaceId: string) => Promise<void>;
+    writeClipboard: (text: string) => Promise<void>;
+    compose: (request: ComposeRequest) => Promise<void>;
+    attach: (request: AttachIssueRequest) => Promise<void>;
+    startSession: (request: StartSessionRequest) => Promise<StartSessionResult>;
+    prompt: (request: PromptRequest) => Promise<PromptResult>;
+    sessionLink: (request: AttachIssueRequest) => Promise<void>;
+    close: () => Promise<void>;
+    oauthStart: () => Promise<void>;
+    oauthDisconnect: () => Promise<void>;
+    request: (request: GuestRequest) => Promise<GuestRequestResult>;
+    serviceRequest: (request: GuestRequest) => Promise<GuestRequestResult>;
+    serviceStatus: () => Promise<ServiceStatusResult>;
+    /**
+     * Read a UTF-8 text file. A relative path is inside the open project
+     * (capability `files`); `/…` or `~/…` must match a declared
+     * `contributes.filesystem` pattern (capability `filesystem`). Over
+     * `GUEST_FILE_CONTENT_MAX` characters is `FILE_TOO_LARGE`; a missing file
+     * is `NOT_FOUND`.
+     */
+    readFile: (path: string) => Promise<FileReadResult>;
+    /**
+     * Write a UTF-8 text file atomically, creating parent directories. Same
+     * path rules as `readFile`. Content over `GUEST_FILE_CONTENT_MAX` is
+     * refused before sending.
+     */
+    writeFile: (path: string, content: string) => Promise<FileWriteResult>;
+    /** Entries of a directory, sorted by name, capped at `GUEST_FILE_LIST_MAX`. Same path rules as `readFile`. */
+    listDir: (path: string) => Promise<FileListResult>;
+    /** Kind, size, and mtime of a path. A missing path is `kind: 'missing'`, not an error. Same path rules as `readFile`. */
+    stat: (path: string) => Promise<FileStatResult>;
+    /**
+     * One-off text generation with the user's Small Model (capability
+     * `model`). Nothing enters a session and no history is kept. `prompt` is
+     * 1 to `GUEST_GENERATE_PROMPT_MAX` characters, `system` up to
+     * `GUEST_GENERATE_SYSTEM_MAX`. No usable model is `NO_MODEL`; a model that
+     * failed is `MODEL_FAILED`. Waits up to `GUEST_GENERATE_TIMEOUT_MS`.
+     */
+    generate: (request: GenerateRequest) => Promise<GenerateResult>;
+    /** Number on this guest's rail icon (0 to `GUEST_BADGE_MAX`); `null` clears it. Opening the panel clears it too. */
+    setBadge: (count: number | null) => Promise<void>;
+    dispose: () => void;
+};
+export declare class HostRequestError extends Error {
+    readonly code: HostRequestErrorCode;
+    constructor(code: HostRequestErrorCode, message: string);
+}
+export declare const connectHost: (options?: HostClientOptions) => HostClient;