@steerable/agent-shell 0.6.15

package/dist/sidecar/supervisor.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Supervises the steerable-sidecar Python subprocess.
+ *
+ * Responsibilities:
+ *  - locate the bundled portable Python runtime (or accept an override),
+ *  - spawn the sidecar with stdin/stdout/stderr pipes,
+ *  - wait for the `__SIDECAR_READY__` marker on stderr before resolving start(),
+ *  - parse JSON-RPC frames and dispatch them to pending requests / handlers,
+ *  - run a periodic `system.ping` health-check and auto-restart on failure,
+ *  - kill the process when the Electron app quits.
+ */
+import { EventEmitter } from 'node:events';
+import type { SidecarApplyEditsResult, SidecarChatStreamHandlers, SidecarChatStreamRequest, SidecarHealthSnapshot, SidecarMethodOptions, SidecarModelCatalog, SidecarReverseHandler, SidecarSandboxPosture, SidecarSessionBranches, SidecarSessionForkOutcome, SidecarSessionMessages, SidecarSessionTree, SidecarSkillModule, SidecarStartOptions, SidecarToolResult } from './types.js';
+/**
+ * Tool names carried by a `tool.list` reply.
+ *
+ * The sidecar answers with OpenAI function-call descriptors —
+ * `{ type: 'function', function: { name, description, parameters } }` — so the
+ * name sits one level in. Reading a top-level `name` yields undefined for every
+ * entry, which reads as "the sidecar registered nothing" rather than as a
+ * decoding error.
+ */
+export declare function toolNamesFromDescriptors(listed: unknown): string[];
+/**
+ * `SidecarSupervisor.start()` 的 boot 失败错误上携带的实例：后台 restart
+ * 循环仍在重试，宿主可监听其 'ready' 事件处理迟到就绪。
+ */
+export interface SidecarBootFailure {
+    supervisor?: SidecarSupervisor;
+}
+export declare class SidecarSupervisor extends EventEmitter {
+    private readonly options;
+    /** Last layer-1 refuse when start() threw (settings page still needs a posture). */
+    static lastSpawnRefusal: SidecarSandboxPosture | null;
+    private child;
+    private readyHealth;
+    private sandboxPosture;
+    private nextRequestId;
+    private pending;
+    private stdoutBuffer;
+    private stderrBuffer;
+    private healthTimer;
+    private failedPings;
+    private shuttingDown;
+    private quitListener;
+    private reverseHandlers;
+    private constructor();
+    /** Spawn the sidecar and wait for the ready marker. */
+    static start(options?: SidecarStartOptions): Promise<SidecarSupervisor>;
+    /** Round-trip a JSON-RPC method call. */
+    call<T = unknown>(method: string, params?: unknown, options?: SidecarMethodOptions): Promise<T>;
+    /** Convenience: list tools registered on the sidecar. */
+    listTools(): Promise<unknown[]>;
+    /**
+     * The gateway's live model catalog (`models.list`): ids the configured
+     * gateway actually accepts, joined with models.dev capabilities. The
+     * host passes the user's configured baseUrl/apiKey explicitly — the
+     * sidecar process env does not carry the app's settings. Fetch failures
+     * come back as `catalogStatus: 'offline'`/`'stale'` in the payload, not
+     * as RPC errors, so the picker can badge instead of breaking.
+     */
+    listModels(params?: {
+        baseUrl?: string;
+        apiKey?: string;
+        refresh?: boolean;
+        provider?: string;
+    }): Promise<SidecarModelCatalog>;
+    /** Names advertised by the sidecar's registry, decoded from `tool.list`. */
+    listToolNames(): Promise<string[]>;
+    /** Convenience: invoke a tool by name. */
+    invokeTool(name: string, args?: Record<string, unknown>, extra?: {
+        consentGranted?: boolean;
+        context?: Record<string, unknown>;
+        timeoutMs?: number;
+    }): Promise<SidecarToolResult>;
+    /** Convenience: ping for a health snapshot. */
+    ping(): Promise<SidecarHealthSnapshot>;
+    /**
+     * W6-1 single source of truth: run the structured-edit algorithm in the
+     * sidecar (Python `file_edit.apply_edits`) on caller-supplied content. The
+     * host keeps all file I/O (read / version check / atomic write); only the
+     * locate-and-replace surgery crosses the wire so the desktop and the
+     * headless / ACP workspace tools share one implementation.
+     */
+    applyEdits(params: {
+        content: string;
+        edits: Array<{
+            oldText: string;
+            newText: string;
+        }>;
+        filePath?: string;
+    }): Promise<SidecarApplyEditsResult>;
+    /**
+     * Skills single source of truth: parse + select SKILL.md modules in the
+     * sidecar (Python `skills.py`) from host-supplied roots. Returns both layers
+     * with bodies; the host applies its own layer filter / budget / name lookup.
+     */
+    listSkills(params: {
+        roots: string[];
+        conditions?: string[];
+        exclude?: string[];
+        ignoreConditions?: boolean;
+    }): Promise<SidecarSkillModule[]>;
+    /**
+     * Run a streaming chat completion through the sidecar's `agent.chat.stream`
+     * method. Subscribes to `stream.chunk` / `stream.done` / `stream.error`
+     * notifications, demuxes them by `streamId`, and surfaces them through the
+     * supplied callbacks.
+     *
+     * Returns the `streamId` so callers can correlate cancel requests.
+     */
+    streamChat(request: SidecarChatStreamRequest, handlers: SidecarChatStreamHandlers): Promise<string>;
+    /** Best-effort cancel a sidecar stream by id. */
+    cancelChat(streamId: string): Promise<void>;
+    /**
+     * W5-2: fork a durable record without running a turn — the non-destructive
+     * regenerate primitive.
+     *
+     * Reports why a fork did not happen instead of collapsing every cause to a
+     * single falsy value. The caller's fallback destroys the reply's UI row and
+     * lets the next turn append into the same record, so a declined address and a
+     * failed request are not interchangeable — see {@link SidecarSessionForkOutcome}.
+     */
+    forkSession(params: {
+        recordId: string;
+        beforeLastUser?: boolean;
+        beforeUserIndex?: number;
+        newRecordId?: string;
+        label?: string;
+    }): Promise<SidecarSessionForkOutcome>;
+    /**
+     * W1.2.1: branch-family view of a record (lineage + direct children).
+     * Soft-fail null when the sidecar has no such record — the caller renders
+     * "no branches" rather than an error.
+     */
+    sessionBranches(recordId: string): Promise<SidecarSessionBranches | null>;
+    /**
+     * Session tree: full branch family containing a record, expanded from
+     * the family root (`agent.session.tree`). Unlike {@link sessionBranches}
+     * (lineage + direct children only), this sees cousins and deeper
+     * descendants — the activation guard and the tree modal both need it.
+     * Soft-fail null when the sidecar has no such record — the caller
+     * renders "no branches" rather than an error.
+     */
+    sessionTree(recordId: string): Promise<SidecarSessionTree | null>;
+    /**
+     * W1.2.1: projected transcript of a record (post-boundary visible span) —
+     * the read path for rendering a branch after a switch. Soft-fail null.
+     */
+    sessionMessages(recordId: string): Promise<SidecarSessionMessages | null>;
+    /**
+     * Inject a user message into a running CoreLoop turn (mid-turn steering).
+     * Soft-fails (`{ ok: false }`) when the turn already ended — the caller
+     * should then send the message as a normal new turn instead.
+     */
+    steerChat(streamId: string, content: string): Promise<boolean>;
+    /**
+     * Register a host-side handler for a reverse (sidecar -> host) request.
+     *
+     * When the sidecar hosts the agent loop but a tool must execute in the
+     * Electron process (shell, filesystem, MCP), the sidecar sends a reverse
+     * `tool.invoke` request; the handler registered for that method runs the
+     * real tool and its return value is sent back as the JSON-RPC result.
+     */
+    onReverseRequest(method: string, handler: SidecarReverseHandler): void;
+    /** Returns the most recent ready snapshot collected at boot. */
+    getBootSnapshot(): SidecarHealthSnapshot | null;
+    /**
+     * W4-3: the layer-1 (sidecar process sandbox) posture recorded at
+     * spawn-plan time. This is the value the renderer reads (via
+     * `GET /api/v2/sidecar/sandbox-posture`) to disclose confined / opt-out
+     * / refused-start. A refused start also lands on `lastSpawnRefusal`.
+     */
+    getSandboxPosture(): SidecarSandboxPosture | null;
+    /** Graceful shutdown. */
+    shutdown(): Promise<void>;
+    private boot;
+    /**
+     * Wrap the sidecar spawn in the platform's process sandbox.
+     *
+     * macOS Seatbelt, Linux bwrap/Landlock, Windows restricted-token
+     * passthrough. Any failure refuses start — confinement requested means
+     * the process does not run unsandboxed. Explicit opt-out
+     * (`sandbox: false` / `STEERABLE_SIDECAR_SANDBOX=0`) is the only
+     * unconfined path. Every exit records `sandboxPosture`.
+     */
+    private resolveSandboxedSpawn;
+    private refuse;
+    private wrapSeatbelt;
+    private wrapLinux;
+    private wrapWindows;
+    private attachListeners;
+    private installAppQuitHook;
+    private waitForReady;
+    private handleStdoutChunk;
+    private handleStderrChunk;
+    private handleStderrLine;
+    private handleStdoutLine;
+    private handleReverseRequest;
+    private writeFrame;
+    private dispatchResponse;
+    private dispatchNotification;
+    private startHealthTimer;
+    private stopHealthTimer;
+    private runHealthCheck;
+    private scheduleRestart;
+    private restart;
+    private requireChild;
+    private failPending;
+    private resolvePythonBinary;
+}
+/**
+ * Resolve the sidecar's Python interpreter: explicit option →
+ * STEERABLE_SIDECAR_PYTHON → bundled python-runtime → sibling framework
+ * venv (dev layout) → system python. Module-level so the egress-proxy
+ * launcher (W1.3.3) spawns the same interpreter the sidecar uses.
+ */
+export declare function resolveSidecarPython(pythonExecutable?: string): string;