@steerable/agent-runtime 0.0.0-stage → 0.9.1

package/dist/runtime.js

@@ -0,0 +1,446 @@
+/**
+ * `AgentRuntime` — the CoreLoop-level API of the framework for TypeScript
+ * products. Every method maps 1:1 onto the sidecar JSON-RPC surface
+ * (`docs/spec/sidecar.md`); the runtime drives the same Rust CoreLoop the
+ * server uses (via the Python sidecar facade), so there is no second
+ * implementation to drift.
+ *
+ * Streaming is exposed as an async-iterable of `SSEEvent`-shaped frames so
+ * callers can `for await` a turn, and as a `done` promise carrying the
+ * terminal status. `cancel` / `steer` target the in-flight stream by id.
+ */
+import { SidecarProcess } from './sidecar.js';
+/**
+ * Sink for one in-flight stream. Events are single-consumer: they buffer
+ * until the first `events` iterable attaches, then flow live. `whenDone`
+ * settles on the terminal status regardless of whether anyone consumed the
+ * events, and a consumer that attaches after termination drains the buffer
+ * and completes immediately.
+ */
+class StreamSink {
+    whenDone;
+    buffer = [];
+    listener = null;
+    settle;
+    terminal = null;
+    failure = null;
+    /**
+     * Set by `chatStream` once it has captured this sink from the map. The
+     * map entry may be deleted on termination only after the claim — a done
+     * frame that coalesces with the response into one read must not orphan
+     * the events before the caller gets them.
+     */
+    claimed = false;
+    get isTerminal() {
+        return this.terminal !== null;
+    }
+    constructor() {
+        this.whenDone = new Promise((resolve, reject) => {
+            this.settle = { resolve, reject };
+        });
+        // A stream nobody awaits must not crash the host on transport failure.
+        this.whenDone.catch(() => undefined);
+    }
+    push(event) {
+        if (this.terminal)
+            return;
+        if (this.listener)
+            this.listener.push(event);
+        else
+            this.buffer.push(event);
+    }
+    finish(status, cancelled) {
+        if (this.terminal)
+            return;
+        this.terminal = { status, cancelled };
+        this.listener?.finish();
+        this.settle.resolve(this.terminal);
+    }
+    fail(err) {
+        if (this.terminal)
+            return;
+        this.terminal = { status: 'error', cancelled: false };
+        this.failure = err;
+        this.listener?.fail(err);
+        this.settle.reject(err);
+    }
+    /** Single-consumer attach: replay the buffer, then flow live. */
+    attach(listener) {
+        if (this.listener) {
+            throw new Error('stream events are single-consumer and already attached');
+        }
+        const buffered = this.buffer;
+        this.buffer = [];
+        if (this.failure) {
+            listener.fail(this.failure);
+            return;
+        }
+        this.listener = listener;
+        for (const event of buffered)
+            listener.push(event);
+        if (this.terminal)
+            listener.finish();
+    }
+    detach(listener) {
+        if (this.listener === listener)
+            this.listener = null;
+    }
+}
+export class AgentRuntime {
+    process;
+    toolHandlers = new Map();
+    spawnHandler = null;
+    streams = new Map();
+    constructor(options = {}) {
+        this.process = new SidecarProcess({
+            ...options,
+            onRequest: (method, params) => this.handleReverse(method, params),
+            onNotification: (method, params) => {
+                this.routeStreamNotification(method, params);
+                options.onNotification?.(method, params);
+            },
+        });
+        for (const [name, handler] of Object.entries(options.tools ?? {})) {
+            this.toolHandlers.set(name, handler);
+        }
+    }
+    /** Spawn the sidecar and wait for readiness. */
+    start() {
+        return this.process.start();
+    }
+    /** Graceful drain and exit; in-flight streams finish or fail first. */
+    async close() {
+        await this.process.close();
+        for (const [, s] of this.streams) {
+            s.fail(new Error('runtime closed mid-stream'));
+        }
+        this.streams.clear();
+    }
+    /** Register a host tool the CoreLoop may call back during turns. */
+    registerTool(name, handler) {
+        this.toolHandlers.set(name, handler);
+    }
+    /**
+     * Register the host confined-spawn capability. Without a handler,
+     * `host.process.spawn` reverse calls are rejected and the sidecar fails
+     * closed (the command never runs unsandboxed on no-backend platforms).
+     */
+    onProcessSpawn(handler) {
+        this.spawnHandler = handler;
+    }
+    // ---- system ----------------------------------------------------------
+    ping() {
+        return this.process.request('system.ping');
+    }
+    // ---- sessions --------------------------------------------------------
+    createSession(input) {
+        return this.process.request('agent.session.create', input);
+    }
+    resumeSession(sessionId) {
+        return this.process.request('agent.session.resume', { sessionId });
+    }
+    listSessions(filter = {}) {
+        return this.process.request('agent.session.list', filter);
+    }
+    /** Fork a record into a new branch without running a turn. */
+    forkSession(params) {
+        return this.process.request('agent.session.fork', params);
+    }
+    /** Branch-family view for a lineage. */
+    sessionBranches(lineage) {
+        return this.process.request('agent.session.branches', { lineage });
+    }
+    /**
+     * Projected post-boundary message span of a history record — what the
+     * model would see on resume. Fails loud on unknown records.
+     */
+    sessionMessages(recordId) {
+        return this.process.request('agent.session.messages', { recordId });
+    }
+    // ---- chat ------------------------------------------------------------
+    /**
+     * Start one CoreLoop turn. Resolves with a handle as soon as the sidecar
+     * assigns a stream id; consume `handle.events` for the turn and await
+     * `handle.done` for the terminal status.
+     */
+    async chatStream(params) {
+        // The sidecar's CoreLoop path is opt-in per request; this runtime's
+        // whole API (cooperative cancel, steer, orchestration, bounded
+        // fragments) only exists there, so default it on. A caller embedding
+        // against the legacy direct-stream path can still pass
+        // `useCoreLoop: false` explicitly.
+        const { streamId } = await this.process.request('agent.chat.stream', { useCoreLoop: true, ...params });
+        // Chunks can already have arrived (the sidecar starts streaming before
+        // the response reaches us) — routeStreamNotification registers the sink
+        // eagerly in that case; otherwise create it now. Claiming keeps the map
+        // entry alive past termination until this lookup has happened.
+        let sink = this.streams.get(streamId);
+        if (!sink) {
+            sink = new StreamSink();
+            this.streams.set(streamId, sink);
+        }
+        sink.claimed = true;
+        if (sink.isTerminal)
+            this.streams.delete(streamId);
+        return { streamId, events: streamIterable(sink), done: sink.whenDone };
+    }
+    /** Cooperative cancel: the loop winds down at the next safe point. */
+    async cancelChat(streamId) {
+        await this.process.request('agent.chat.cancel', { streamId });
+    }
+    /** Mid-turn steer; resolves true when the running turn accepted it. */
+    async steerChat(streamId, content) {
+        const res = await this.process.request('agent.chat.steer', { streamId, content });
+        return res?.accepted === true;
+    }
+    /** Fork the record of a running turn. */
+    forkChat(streamId, label) {
+        return this.process.request('agent.chat.fork', { streamId, label });
+    }
+    // ---- tools / skills / workspace --------------------------------------
+    listTools() {
+        return this.process.request('tool.list');
+    }
+    invokeTool(call) {
+        return this.process.request('tool.invoke', call);
+    }
+    listSkills(roots) {
+        return this.process.request('skills.list', { roots });
+    }
+    applyEdits(params) {
+        return this.process.request('workspace.apply_edits', params);
+    }
+    // ---- trace / config ----------------------------------------------------
+    fetchTrace(traceId) {
+        return this.process.request('trace.fetch', { traceId });
+    }
+    exportTrace(traceId) {
+        return this.process.request('trace.export', { traceId });
+    }
+    /** POST turn-outcome counters to a collector's `/v1/metrics`. */
+    exportMetrics(params) {
+        return this.process.request('metrics.export', params);
+    }
+    getConfig() {
+        return this.process.request('config.get');
+    }
+    async setConfig(patch) {
+        await this.process.request('config.set', patch);
+    }
+    /**
+     * The framework-owned OpenAI-compat flag vocabulary (`describe_compat_flags`
+     * on the Python side). Host settings UIs render their compat section from
+     * these descriptors instead of hardcoding flag names, so a new flag needs
+     * no host-side constant to stay in sync.
+     */
+    describeCompatFlags() {
+        return this.process.request('compat.describe');
+    }
+    /**
+     * Per-exec enforcement this host can actually reach (`sandbox.describe`),
+     * given the egress arguments a turn will send. Hosts that set
+     * `execSandbox.requireFull` from a platform guess refuse every shell call
+     * on backends that cannot pin per-host (bwrap, Landlock, Windows). Probe
+     * once and require full only when the reply is `full`.
+     */
+    describeSandbox(params) {
+        return this.process.request('sandbox.describe', params);
+    }
+    /**
+     * The framework-owned harness vocabulary (`harness.describe`, W1.2.2):
+     * every dimension's available implementations with their assumption
+     * contracts, plus the active default selection. Host harness pickers
+     * render from this payload; a new strategy needs no host-side constant.
+     */
+    describeHarness() {
+        return this.process.request('harness.describe');
+    }
+    /**
+     * The gateway's live model catalog (`models.list`): the ids the
+     * configured `STEERABLE_BASE_URL` actually accepts, joined with
+     * models.dev capabilities — reasoning levels included — by the same
+     * resolution the request path's clamp uses, so a picker and the wire
+     * never disagree about a model's knob. Host model pickers render from
+     * this payload and badge the `stale`/`offline` states.
+     */
+    listModels(params) {
+        return this.process.request('models.list', params);
+    }
+    // ---- plugins / presets / session tree --------------------------------
+    /** Every plugin the sidecar registry knows, with lifecycle state. */
+    listPlugins() {
+        return this.process.request('plugin.list');
+    }
+    /** Enable a registered plugin; rejects invalid_params on unknown names. */
+    enablePlugin(name) {
+        return this.process.request('plugin.enable', { name });
+    }
+    /** Disable a plugin without unloading its code. */
+    disablePlugin(name) {
+        return this.process.request('plugin.disable', { name });
+    }
+    /** Hot-reload a reloadable plugin from its source. */
+    reloadPlugin(name) {
+        return this.process.request('plugin.reload', { name });
+    }
+    /**
+     * Descriptors for every tool an enabled plugin provides. Hosts that own
+     * the model-visible tool list advertise these and call them with
+     * `tool.invoke`; disabled plugins contribute none.
+     */
+    describePluginTools() {
+        return this.process.request('plugin.tools.describe');
+    }
+    /** The framework-owned provider-preset table for host settings UIs. */
+    describePresets() {
+        return this.process.request('presets.describe');
+    }
+    /**
+     * The bundled serving-provider catalog (`catalog.describe`): default
+     * URLs, sidecar wire kinds, and chat-capable model ids. Host vendor
+     * pickers render from this payload so a catalog refresh needs no
+     * host-side constant.
+     */
+    describeCatalog() {
+        return this.process.request('catalog.describe');
+    }
+    /** Which preset a (baseUrl, model) pair would auto-match; null when none. */
+    resolvePreset(input) {
+        return this.process.request('presets.resolve', input);
+    }
+    /** The full branch family containing a record (pi-style tree view). */
+    sessionTree(recordId) {
+        return this.process.request('agent.session.tree', { recordId });
+    }
+    /**
+     * Ask a running turn to compact its transcript at the next pre_step
+     * boundary (CC `/compact` parity). Soft-fails false when the stream
+     * already completed, mirroring steerChat.
+     */
+    async compactChat(streamId) {
+        const res = await this.process.request('agent.chat.compact', { streamId });
+        return res?.ok === true;
+    }
+    // ---- internals ---------------------------------------------------------
+    handleReverse(method, params) {
+        if (method === 'tool.invoke') {
+            const call = params;
+            const handler = call && this.toolHandlers.get(call.name);
+            if (!call || !handler) {
+                return Promise.reject(new Error(`tool.invoke: no host handler for ${call?.name ?? '<missing>'}`));
+            }
+            return handler((call.arguments ?? {}));
+        }
+        if (method === 'host.process.spawn') {
+            if (!this.spawnHandler) {
+                return Promise.reject(new Error('host.process.spawn: capability not implemented by this host'));
+            }
+            return this.spawnHandler(params);
+        }
+        return Promise.reject(new Error(`unsupported reverse method ${method}`));
+    }
+    routeStreamNotification(method, params) {
+        const p = (params ?? {});
+        if (!p.streamId)
+            return;
+        if (method === 'stream.chunk' && !this.streams.has(p.streamId)) {
+            // Chunks can arrive before chatStream's response resolves (the sidecar
+            // starts streaming immediately) — register the sink eagerly.
+            this.streams.set(p.streamId, new StreamSink());
+        }
+        const state = this.streams.get(p.streamId);
+        if (!state)
+            return;
+        switch (method) {
+            case 'stream.chunk': {
+                const c = params;
+                if (c.delta) {
+                    state.push({ type: 'content', content: c.delta });
+                }
+                if (c.toolCall) {
+                    state.push({ type: 'tool_call', payload: c.toolCall });
+                }
+                if (c.toolResult) {
+                    state.push({ type: 'tool_result', payload: c.toolResult });
+                }
+                if (c.usage) {
+                    state.push({ type: 'usage', payload: c.usage });
+                }
+                return;
+            }
+            case 'stream.done': {
+                const d = params;
+                state.push({ type: 'done' });
+                const status = (d.status ??
+                    (d.cancelled ? 'cancelled' : d.ok ? 'completed' : 'error'));
+                state.finish(status, d.cancelled === true || status === 'cancelled');
+                if (state.claimed)
+                    this.streams.delete(p.streamId);
+                return;
+            }
+            case 'stream.error': {
+                const e = params;
+                state.push({ type: 'error', message: e.message });
+                state.finish('error', false);
+                if (state.claimed)
+                    this.streams.delete(p.streamId);
+                return;
+            }
+            case 'agent.child': {
+                state.push({
+                    type: 'orchestration',
+                    payload: params,
+                });
+                return;
+            }
+            default:
+                return;
+        }
+    }
+}
+function streamIterable(sink) {
+    return {
+        [Symbol.asyncIterator]() {
+            const queue = [];
+            let done = false;
+            let error = null;
+            let wake = null;
+            const listener = {
+                push(event) {
+                    queue.push(event);
+                    wake?.();
+                },
+                finish() {
+                    done = true;
+                    wake?.();
+                },
+                fail(err) {
+                    error = err;
+                    wake?.();
+                },
+            };
+            sink.attach(listener);
+            return {
+                async next() {
+                    for (;;) {
+                        const event = queue.shift();
+                        if (event !== undefined)
+                            return { value: event, done: false };
+                        if (error)
+                            throw error;
+                        if (done)
+                            return { value: undefined, done: true };
+                        await new Promise((resolve) => {
+                            wake = resolve;
+                        });
+                        wake = null;
+                    }
+                },
+                async return() {
+                    sink.detach(listener);
+                    return { value: undefined, done: true };
+                },
+            };
+        },
+    };
+}

package/dist/sidecar.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `SidecarProcess` — owns the embedded Python sidecar lifecycle so callers
+ * never write subprocess management:
+ *
+ *   spawn → wait `lifecycle.ready` → `system.ping` → serve requests
+ *   unexpected exit → bounded auto-restart with backoff
+ *   close() → `system.shutdown` → wait → SIGTERM → SIGKILL (escalating)
+ *
+ * Requests made while the process is down reject fast with
+ * `SidecarNotReadyError`; the caller decides whether to retry after the
+ * next `ready` event. This mirrors the fail-loud posture of the rest of
+ * the framework — a wedged sidecar surfaces as an error, not a hang.
+ */
+import { EventEmitter } from 'node:events';
+import { JsonRpcTransportClosedError } from './jsonrpc.js';
+/**
+ * Interpreter for the sidecar process.
+ *
+ * Resolution order: explicit `STEERABLE_SIDECAR_PYTHON`, the platform package
+ * npm installed for this host, the framework checkout's `.venv` (so an example
+ * or test inside the repo finds the editable install), then
+ * `STEERABLE_PYTHON`, then `python3`.
+ *
+ * A global install has no framework checkout; a checkout has no platform
+ * package. Both paths end at a working sidecar without extra setup.
+ *
+ * @returns Path to the interpreter, or `python3` when nothing else resolves.
+ */
+export declare function resolveRuntimePython(): string;
+export declare class SidecarNotReadyError extends Error {
+    constructor(message?: string);
+}
+export declare class SidecarStartError extends Error {
+    constructor(message: string);
+}
+export interface SidecarRestartPolicy {
+    /** Max consecutive restarts before the process is left dead. Default 3. */
+    maxRestarts?: number;
+    /** Base backoff in ms; attempt n waits `base * 2^(n-1)`. Default 250. */
+    backoffMs?: number;
+}
+export interface SidecarProcessOptions {
+    /**
+     * Python interpreter used to launch the sidecar. Default: env
+     * `STEERABLE_SIDECAR_PYTHON`, then the `@steerable/runtime-<target>` package
+     * npm installed for this host, then env `STEERABLE_PYTHON`, then `python3`.
+     * The interpreter must be able to import `steerable_sidecar`.
+     */
+    python?: string;
+    /**
+     * Entry module; defaults to `steerable_sidecar`. Pass `null` to invoke the
+     * interpreter directly on `args` (no `-m <module>` prefix) — used by tests
+     * that drive a fake sidecar under `node`.
+     */
+    entryModule?: string | null;
+    /** Extra CLI flags appended after `-m <entryModule>`. */
+    args?: string[];
+    /** Working directory for the sidecar process. */
+    cwd?: string;
+    /** Extra environment merged over `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Restart policy for unexpected exits. Pass `false` to disable. */
+    restart?: SidecarRestartPolicy | false;
+    /** Ms to wait for `lifecycle.ready` before failing the start. Default 15s. */
+    readyTimeoutMs?: number;
+    /** Ms to wait for graceful exit before SIGTERM. Default 5s. */
+    shutdownGraceMs?: number;
+    /** Reverse-channel handler (sidecar → host, e.g. `tool.invoke`). */
+    onRequest?: (method: string, params: unknown) => Promise<unknown>;
+    /** Sidecar-originated notifications (stream.chunk, agent.child, …). */
+    onNotification?: (method: string, params: unknown) => void;
+    /** stderr lines from the sidecar land here (default: swallowed). */
+    onStderr?: (line: string) => void;
+}
+export interface SidecarReadyInfo {
+    version?: string;
+    protocolVersion?: string;
+    pid?: number;
+    listenInfo?: unknown;
+}
+export declare class SidecarProcess extends EventEmitter {
+    private readonly options;
+    private child;
+    private peer;
+    private readyInfo;
+    /** True between close() and actual exit — an expected exit, no restart. */
+    private closing;
+    /** True once a boot fully succeeded; only booted processes earn restarts. */
+    private booted;
+    private restarts;
+    private startPromise;
+    /** Internal deferred resolved when the current boot sees lifecycle.ready. */
+    private readyDeferred;
+    constructor(options?: SidecarProcessOptions);
+    /** True once `lifecycle.ready` + `system.ping` have completed. */
+    get isReady(): boolean;
+    /** Params of the `lifecycle.ready` notification, once received. */
+    get ready(): SidecarReadyInfo | null;
+    /** PID of the live child, if any. */
+    get pid(): number | undefined;
+    /**
+     * Spawn the sidecar and wait for readiness. A manual start resets the
+     * consecutive-restart budget; the auto-restart path deliberately does not
+     * (a crash-looping sidecar must exhaust `maxRestarts`, not loop forever).
+     */
+    start(): Promise<void>;
+    private boot;
+    /**
+     * Graceful stop: `system.shutdown`, wait for exit, escalate to SIGTERM
+     * then SIGKILL. Resolves when the process is gone (or was never up).
+     */
+    close(): Promise<void>;
+    /** JSON-RPC request against the live sidecar; rejects fast when down. */
+    request<TResult = unknown>(method: string, params?: unknown, options?: {
+        timeoutMs?: number | null;
+    }): Promise<TResult>;
+    private spawnOnce;
+    private handleNotification;
+    private handleExit;
+    private teardownPeer;
+}
+export { JsonRpcTransportClosedError };