@steerable/agent-runtime 0.0.0-stage → 0.9.1

package/dist/sidecar.js

@@ -0,0 +1,306 @@
+/**
+ * `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 { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolvePlatformRuntime } from './platform-runtime.js';
+import { JsonRpcPeer, 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 function resolveRuntimePython() {
+    const explicit = process.env.STEERABLE_SIDECAR_PYTHON?.trim();
+    if (explicit)
+        return explicit;
+    const platform = resolvePlatformRuntime();
+    if (platform.kind === 'ok')
+        return platform.runtime.sidecarPython;
+    const venv = frameworkVenvPython();
+    if (venv)
+        return venv;
+    return process.env.STEERABLE_PYTHON?.trim() || 'python3';
+}
+/**
+ * Walks up from this module to a framework checkout and returns its `.venv`
+ * interpreter when present.
+ *
+ * The package runs from two planes — source (`ts/src/`) and build
+ * (`ts/dist/`) — so both depths are probed and the first hit wins. Absent in a
+ * packed install, where the platform package above already supplied one.
+ */
+function frameworkVenvPython() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const up of [join('..', '..', '..'), join('..', '..', '..', '..')]) {
+        const venv = join(here, up, '.venv');
+        for (const candidate of [join(venv, 'bin', 'python3'), join(venv, 'Scripts', 'python.exe')]) {
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+export class SidecarNotReadyError extends Error {
+    constructor(message = 'sidecar is not running') {
+        super(message);
+        this.name = 'SidecarNotReadyError';
+    }
+}
+export class SidecarStartError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SidecarStartError';
+    }
+}
+const SIGKILL_GRACE_MS = 1_000;
+export class SidecarProcess extends EventEmitter {
+    options;
+    child = null;
+    peer = null;
+    readyInfo = null;
+    /** True between close() and actual exit — an expected exit, no restart. */
+    closing = false;
+    /** True once a boot fully succeeded; only booted processes earn restarts. */
+    booted = false;
+    restarts = 0;
+    startPromise = null;
+    /** Internal deferred resolved when the current boot sees lifecycle.ready. */
+    readyDeferred = null;
+    constructor(options = {}) {
+        super();
+        this.options = options;
+    }
+    /** True once `lifecycle.ready` + `system.ping` have completed. */
+    get isReady() {
+        return this.peer !== null;
+    }
+    /** Params of the `lifecycle.ready` notification, once received. */
+    get ready() {
+        return this.readyInfo;
+    }
+    /** PID of the live child, if any. */
+    get pid() {
+        return this.child?.pid;
+    }
+    /**
+     * 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() {
+        this.restarts = 0;
+        return this.boot();
+    }
+    boot() {
+        if (this.startPromise)
+            return this.startPromise;
+        this.startPromise = this.spawnOnce().finally(() => {
+            this.startPromise = null;
+        });
+        return this.startPromise;
+    }
+    /**
+     * Graceful stop: `system.shutdown`, wait for exit, escalate to SIGTERM
+     * then SIGKILL. Resolves when the process is gone (or was never up).
+     */
+    async close() {
+        this.closing = true;
+        // A restart boot may be in flight — wait for it so we don't leave a
+        // live child behind after close() returns.
+        if (this.startPromise) {
+            await this.startPromise.catch(() => undefined);
+        }
+        const child = this.child;
+        if (!child)
+            return;
+        const exited = new Promise((resolve) => {
+            child.once('exit', () => resolve());
+        });
+        try {
+            if (this.peer) {
+                await this.peer
+                    .request('system.shutdown', undefined, { timeoutMs: 5_000 })
+                    .catch(() => undefined);
+            }
+        }
+        finally {
+            const graceMs = this.options.shutdownGraceMs ?? 5_000;
+            const grace = await raceTimeout(exited, graceMs);
+            if (!grace) {
+                child.kill('SIGTERM');
+                const terminated = await raceTimeout(exited, SIGKILL_GRACE_MS);
+                if (!terminated)
+                    child.kill('SIGKILL');
+            }
+            await exited.catch(() => undefined);
+            this.teardownPeer('sidecar closed');
+            this.child = null;
+        }
+    }
+    /** JSON-RPC request against the live sidecar; rejects fast when down. */
+    request(method, params, options) {
+        const peer = this.peer;
+        if (!peer)
+            return Promise.reject(new SidecarNotReadyError());
+        return peer.request(method, params, options);
+    }
+    async spawnOnce() {
+        const python = this.options.python ?? resolveRuntimePython();
+        const entry = this.options.entryModule === null
+            ? null
+            : (this.options.entryModule ?? 'steerable_sidecar');
+        const args = [
+            ...(entry === null ? [] : ['-m', entry]),
+            ...(this.options.args ?? []),
+        ];
+        const child = spawn(python, args, {
+            cwd: this.options.cwd,
+            env: { ...process.env, ...this.options.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.child = child;
+        child.stderr?.setEncoding('utf8');
+        let stderrBuf = '';
+        child.stderr?.on('data', (chunk) => {
+            stderrBuf += chunk;
+            let nl;
+            while ((nl = stderrBuf.indexOf('\n')) !== -1) {
+                const line = stderrBuf.slice(0, nl);
+                stderrBuf = stderrBuf.slice(nl + 1);
+                if (line.trim().length > 0)
+                    this.options.onStderr?.(line);
+            }
+        });
+        const peer = new JsonRpcPeer({
+            write: (line) => {
+                child.stdin?.write(line);
+            },
+            onNotification: (method, params) => this.handleNotification(method, params),
+            onRequest: this.options.onRequest,
+        });
+        child.stdout?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => peer.feed(chunk));
+        child.on('exit', (code, signal) => this.handleExit(code, signal));
+        child.on('error', (err) => {
+            this.teardownPeer(`sidecar spawn error: ${err.message}`);
+        });
+        const readyTimeoutMs = this.options.readyTimeoutMs ?? 15_000;
+        const readySignal = new Promise((resolve, reject) => {
+            this.readyDeferred = { resolve, reject };
+        });
+        const timer = setTimeout(() => {
+            this.readyDeferred?.reject(new SidecarStartError(`sidecar did not emit lifecycle.ready within ${readyTimeoutMs}ms`));
+        }, readyTimeoutMs);
+        child.once('exit', (code) => {
+            this.readyDeferred?.reject(new SidecarStartError(`sidecar exited during boot (code ${String(code)})`));
+        });
+        // The peer only becomes the serving peer after ready + ping, so a
+        // half-booted process never answers requests. A failed boot kills the
+        // child — callers must not leak a process they never got a handle to.
+        try {
+            await readySignal;
+        }
+        catch (err) {
+            child.kill('SIGKILL');
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+            this.readyDeferred = null;
+        }
+        try {
+            await peer.request('system.ping', undefined, { timeoutMs: 5_000 });
+        }
+        catch (err) {
+            child.kill('SIGKILL');
+            throw new SidecarStartError(`sidecar failed post-ready ping: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        this.peer = peer;
+        this.booted = true;
+        // 'ready' means fully serving: listeners may issue requests immediately.
+        this.emit('ready', this.readyInfo);
+    }
+    handleNotification(method, params) {
+        if (method === 'lifecycle.ready') {
+            this.readyInfo = (params ?? {});
+            this.readyDeferred?.resolve();
+            return;
+        }
+        if (method === 'lifecycle.shutdown') {
+            this.emit('shutdown', params);
+            return;
+        }
+        this.options.onNotification?.(method, params);
+    }
+    handleExit(code, signal) {
+        const wasClosing = this.closing;
+        const wasBooted = this.booted;
+        this.booted = false;
+        this.teardownPeer(`sidecar exited (code ${String(code)}, signal ${String(signal)})`);
+        this.child = null;
+        this.readyInfo = null;
+        this.emit('exit', code, signal);
+        // Only a process that fully booted earns a restart — a boot failure is
+        // almost always deterministic (bad interpreter, missing package), and
+        // retrying it just delays the caller's error.
+        if (wasClosing || !wasBooted)
+            return;
+        const policy = this.options.restart;
+        if (policy === false)
+            return;
+        const maxRestarts = policy?.maxRestarts ?? 3;
+        const backoffMs = policy?.backoffMs ?? 250;
+        if (this.restarts >= maxRestarts) {
+            this.emit('dead', code, signal);
+            return;
+        }
+        this.restarts += 1;
+        const delay = backoffMs * 2 ** (this.restarts - 1);
+        this.emit('restart', this.restarts, delay);
+        setTimeout(() => {
+            if (this.closing)
+                return;
+            this.boot().catch((err) => {
+                this.emit('restart-failed', err instanceof Error ? err : new Error(String(err)));
+            });
+        }, delay);
+    }
+    teardownPeer(reason) {
+        if (!this.peer)
+            return;
+        this.peer.close(reason);
+        this.peer = null;
+    }
+}
+function raceTimeout(p, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), ms);
+        p.then(() => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+}
+export { JsonRpcTransportClosedError };

package/dist/transports.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Adapters that let `@steerable/agent-ui` hooks consume an `AgentRuntime`
+ * directly — `useChatStream` gets a `ChatStreamTransport`, `useAgentSession`
+ * gets an `AgentSessionTransport`.
+ *
+ * The interfaces below are declared locally and kept structurally identical
+ * to the ones in `@steerable/agent-ui/hooks`; the runtime package must not
+ * depend on the UI package (layering: UI sits above runtime). The
+ * compile-time gate `test/ui-transport.types.ts` asserts assignability both
+ * ways so the two declarations cannot drift apart.
+ */
+import type { AgentSession, SSEEvent } from '@steerable/agent-protocol';
+import type { AgentRuntime, ChatStreamParams } from './runtime.js';
+/** Mirrors `@steerable/agent-ui` `ChatStreamSendInput`. */
+export interface ChatStreamSendInput {
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/** Mirrors `@steerable/agent-ui` `ChatStreamTransport`. */
+export interface ChatStreamTransport {
+    stream: (input: ChatStreamSendInput, onEvent: (event: SSEEvent) => void) => Promise<void | (() => void)>;
+    steer?: (content: string) => Promise<boolean>;
+}
+/** Mirrors `@steerable/agent-ui` `AgentSessionTransport`. */
+export interface AgentSessionTransport {
+    create: (input: {
+        chatId: string;
+        userId: string;
+        projectId?: string | null;
+        scenario?: string;
+        stageData?: Record<string, unknown> | null;
+    }) => Promise<AgentSession>;
+    resume: (sessionId: string) => Promise<AgentSession>;
+    list: (filter: {
+        userId?: string;
+        chatId?: string;
+        activeOnly?: boolean;
+    }) => Promise<AgentSession[]>;
+}
+export interface ChatStreamTransportOptions {
+    /**
+     * Static portion of every `agent.chat.stream` request — must pin at least
+     * the provider and model; any other sidecar field is passed through.
+     * (Written as Pick+Record instead of Omit: Omit collapses the index
+     * signature on ChatStreamParams and would drop the required fields.)
+     */
+    params: Pick<ChatStreamParams, 'provider' | 'model'> & Record<string, unknown>;
+    /**
+     * Resolve the session a turn belongs to. Called once per `stream` call;
+     * typically `() => currentSessionId` from your session hook. The value is
+     * forwarded as the request's `sessionId` passthrough field — session
+     * binding itself is the host's job (`agent.session.create`/`resume`).
+     */
+    sessionId: () => string;
+}
+/**
+ * Build the `ChatStreamTransport` for `useChatStream`. Per the hook's
+ * contract, `stream` resolves when the turn terminates; mid-turn stop is
+ * `runtime.cancelChat(streamId)` (cooperative — the loop winds down at the
+ * next safe point and the terminal `done` still arrives), and `steer`
+ * targets the currently active stream.
+ */
+export declare function createChatStreamTransport(runtime: AgentRuntime, options: ChatStreamTransportOptions): ChatStreamTransport;
+/**
+ * Build the `AgentSessionTransport` for `useAgentSession` — session
+ * lifecycle straight onto the sidecar's storage adapter.
+ */
+export declare function createSessionTransport(runtime: AgentRuntime): AgentSessionTransport;

package/dist/transports.js

@@ -0,0 +1,57 @@
+/**
+ * Adapters that let `@steerable/agent-ui` hooks consume an `AgentRuntime`
+ * directly — `useChatStream` gets a `ChatStreamTransport`, `useAgentSession`
+ * gets an `AgentSessionTransport`.
+ *
+ * The interfaces below are declared locally and kept structurally identical
+ * to the ones in `@steerable/agent-ui/hooks`; the runtime package must not
+ * depend on the UI package (layering: UI sits above runtime). The
+ * compile-time gate `test/ui-transport.types.ts` asserts assignability both
+ * ways so the two declarations cannot drift apart.
+ */
+/**
+ * Build the `ChatStreamTransport` for `useChatStream`. Per the hook's
+ * contract, `stream` resolves when the turn terminates; mid-turn stop is
+ * `runtime.cancelChat(streamId)` (cooperative — the loop winds down at the
+ * next safe point and the terminal `done` still arrives), and `steer`
+ * targets the currently active stream.
+ */
+export function createChatStreamTransport(runtime, options) {
+    let activeStreamId = null;
+    return {
+        stream: async (input, onEvent) => {
+            const handle = await runtime.chatStream({
+                ...options.params,
+                messages: [{ role: 'user', content: input.content }],
+                sessionId: options.sessionId(),
+                metadata: input.metadata,
+            });
+            activeStreamId = handle.streamId;
+            try {
+                for await (const event of handle.events) {
+                    onEvent(event);
+                }
+            }
+            finally {
+                if (activeStreamId === handle.streamId)
+                    activeStreamId = null;
+            }
+        },
+        steer: async (content) => {
+            if (!activeStreamId)
+                return false;
+            return runtime.steerChat(activeStreamId, content);
+        },
+    };
+}
+/**
+ * Build the `AgentSessionTransport` for `useAgentSession` — session
+ * lifecycle straight onto the sidecar's storage adapter.
+ */
+export function createSessionTransport(runtime) {
+    return {
+        create: (input) => runtime.createSession(input),
+        resume: (sessionId) => runtime.resumeSession(sessionId),
+        list: (filter) => runtime.listSessions(filter),
+    };
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@steerable/agent-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.1",
+  "description": "Steerable framework — official TypeScript production runtime. Owns the embedded Python sidecar lifecycle (spawn / ready handshake / health / bounded auto-restart / graceful drain) and exposes the CoreLoop-level API over the sidecar JSON-RPC surface. There is no TS CoreLoop; this package drives the same Rust CoreLoop the server uses (via the Python sidecar facade), so cross-language conformance holds by construction.",
+  "license": "Apache-2.0",
+  "homepage": "https://steerableframework.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pathlyapp/steerable.git",
+    "directory": "packages/agent-runtime/ts"
+  },
+  "bugs": {
+    "url": "https://github.com/pathlyapp/steerable/issues"
+  },
+  "keywords": [
+    "steerable",
+    "agent",
+    "runtime",
+    "coreloop",
+    "sidecar",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@steerable/agent-protocol": "0.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "@steerable/agent-ui": "0.9.1"
+  },
+  "optionalDependencies": {
+    "@steerable/runtime-darwin-arm64": "0.9.1",
+    "@steerable/runtime-darwin-x64": "0.9.1",
+    "@steerable/runtime-linux-arm64": "0.9.1",
+    "@steerable/runtime-linux-x64": "0.9.1",
+    "@steerable/runtime-win32-x64": "0.9.1"
+  },
+  "scripts": {
+    "gen": "echo agent-runtime-ts",
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "check:drift": "echo ok"
+  }
 }