@steerable/agent-runtime 0.0.0-stage → 0.9.0

package/dist/runtime.d.ts

@@ -0,0 +1,460 @@
+/**
+ * `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 type { AgentSession, HarnessTrace, SidecarHealth, SSEEvent, ToolCall, ToolResult, TraceEvent, TraceSpan } from '@steerable/agent-protocol';
+import { SidecarProcess, type SidecarProcessOptions } from './sidecar.js';
+export interface BranchPoint {
+    recordId: string;
+    lineage: string;
+    seq: number;
+    label?: string | null;
+}
+export interface BranchFamily {
+    lineage: string;
+    children: unknown[];
+}
+export interface SessionMessages {
+    recordId: string;
+    messages: {
+        seq: number;
+        role: string;
+        content: string;
+    }[];
+}
+export interface ToolDescriptor {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+export interface SkillInfo {
+    name: string;
+    path: string;
+    description?: string;
+    [key: string]: unknown;
+}
+export interface ApplyEditsResult {
+    content: string;
+    diff: string;
+    applied: number;
+    matches: unknown[];
+}
+export interface TraceFetchResult {
+    trace: HarnessTrace;
+    spans: TraceSpan[];
+    events: TraceEvent[];
+}
+export interface TraceExportResult {
+    status: string;
+    traceId: string;
+    privacyMode: string;
+}
+/** One finished turn, as `metrics.export` accepts it. Counts and labels only. */
+export interface MetricsExportSample {
+    outcome: 'completed' | 'failed' | 'cancelled';
+    failureKind?: string | null;
+    attempts?: number | null;
+    retried?: boolean;
+    usedDirect?: boolean;
+}
+export interface MetricsExportResult {
+    status: string;
+    metrics: number;
+}
+/**
+ * Wire-level descriptor of one OpenAI-compat flag, as served by
+ * `compat.describe`. `kind` is `"bool"`, `"string-list"`, or
+ * `"enum:<opt1>,<opt2>"`-style; `default` mirrors the framework's
+ * `OpenAICompatFlags` defaults.
+ */
+export interface CompatFlagDescriptor {
+    key: string;
+    field: string;
+    kind: string;
+    default: unknown;
+    description: string;
+}
+/**
+ * One harness implementation choice as served by `harness.describe`
+ * (W1.2.2): the impl name plus its assumption contract.
+ */
+export interface HarnessImplDescriptor {
+    impl: string;
+    assumes: string;
+    params?: Record<string, unknown>;
+}
+/** The `harness.describe` payload: the registry vocabulary plus the
+ * active default selection, keyed by dimension. */
+export interface HarnessDescription {
+    available: Record<string, HarnessImplDescriptor[]>;
+    default: Record<string, HarnessImplDescriptor[] | HarnessImplDescriptor>;
+}
+/** One model id the configured gateway accepts (`models.list`), joined
+ * with the bundled models.dev capability catalog by the same resolution
+ * the request path's reasoning-effort clamp uses. `joinedFrom` keeps the
+ * leaf-join provenance; `capabilities: 'unknown'` means no catalog tier
+ * matched, so reasoning levels are unavailable rather than empty. */
+export interface GatewayModelEntry {
+    id: string;
+    name: string | null;
+    window: number | null;
+    modalities: string[];
+    reasoningLevels: string[];
+    pricing: {
+        promptPerMtok: number | null;
+        completionPerMtok: number | null;
+    } | null;
+    joinedFrom: string | null;
+    capabilities: 'known' | 'unknown';
+}
+/** The `models.list` payload. `catalogStatus` is `live` when the listing
+ * was just fetched from the gateway, `stale` when served from cache after
+ * a refresh failure, and `offline` when the gateway is unreachable with no
+ * cache (then `models` is empty and `error` carries the cause). Discovery
+ * only — the catalog is not a routing whitelist. */
+export interface GatewayModelCatalog {
+    models: GatewayModelEntry[];
+    catalogStatus: 'live' | 'stale' | 'offline';
+    error?: string;
+    fetchedAt?: number;
+    /** Absent on the offline path (no gateway/env context to report). */
+    current?: {
+        model: string | null;
+        reasoningEffort: string | null;
+    };
+}
+/**
+ * One built-in provider preset as served by `presets.describe`: the match
+ * rule (`host` + `modelPrefix`) plus the parameter patch it applies. Host
+ * settings UIs render their preset picker from this list.
+ */
+export interface ProviderPresetDescriptor {
+    host: string;
+    modelPrefix: string;
+    temperature: number | null;
+    topP: number | null;
+    maxTokens: number | null;
+    reasoningEffort: string | null;
+    extraBody: Record<string, unknown> | null;
+}
+/** The resolved parameter patch from `presets.resolve` (`None` fields omitted). */
+export interface ProviderPreset {
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    reasoningEffort?: string;
+    extraBody?: Record<string, unknown>;
+}
+/** One plugin record as served by the `plugin.*` lifecycle RPCs. */
+export interface PluginRecord {
+    name: string;
+    origin: string;
+    tools: string[];
+    enabled: boolean;
+    reloadable: boolean;
+}
+/** One enabled plugin's tool as served by `plugin.tools.describe`. */
+export interface PluginToolDescriptor {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+    mode: string;
+    exposure: 'direct' | 'deferred' | 'hidden';
+    requireConsent: boolean;
+    concurrencySafe: boolean;
+    plugin: string | null;
+}
+/** Recursive node of the `agent.session.tree` branch-family view. */
+export interface SessionTreeNode {
+    recordId: string;
+    sourceRecordId: string | null;
+    sourceUntilSeq: number | null;
+    label: string | null;
+    depth: number;
+    children: SessionTreeNode[];
+}
+/** The `agent.session.tree` payload; `truncated` marks a family cut by the
+ * depth/node bounds documented on the Python handler. */
+export interface SessionTreeResult {
+    recordId: string;
+    tree: SessionTreeNode;
+    nodeCount: number;
+    truncated: boolean;
+}
+export type ChatStreamStatus = 'completed' | 'cancelled' | 'budget_exhausted' | 'error';
+export interface ChatStreamHandle {
+    /** Server-assigned stream id (also the cancel/steer target). */
+    readonly streamId: string;
+    /** Turn events: content deltas, tool calls/results, child lifecycle. */
+    readonly events: AsyncIterable<SSEEvent>;
+    /**
+     * Resolves with the terminal status once `stream.done`/`stream.error`
+     * arrives. Never rejects for a *completed* turn; rejects only when the
+     * transport dies mid-turn.
+     */
+    readonly done: Promise<{
+        status: ChatStreamStatus;
+        cancelled: boolean;
+    }>;
+}
+export interface ChatStreamParams {
+    /** LLM provider kind: "openai_compat" | "anthropic" | <custom>. */
+    provider: string;
+    /** Model id understood by the provider. */
+    model: string;
+    /**
+     * Full message list for the turn (OpenAI chat shape). This doubles as the
+     * WS3 history seed: the sidecar reconciles it against the session record.
+     */
+    messages: Array<{
+        role: string;
+        content: unknown;
+        [key: string]: unknown;
+    }>;
+    baseUrl?: string;
+    apiKey?: string;
+    /** History seed window the host already rendered (see WS3 contract). */
+    historySeed?: unknown[];
+    /** Orchestration opt-in: {maxDepth?, maxParallel?, childMaxRounds?,
+     * childMaxToolErrors?}; child limits default to the parent loop's. */
+    orchestration?: {
+        maxDepth?: number;
+        maxParallel?: number;
+        childMaxRounds?: number;
+        childMaxToolErrors?: number;
+    };
+    /** Per-request tool domain narrowing (fail-closed on the loop side). */
+    toolFilter?: string[];
+    /** Approval policy for this turn. */
+    approval?: Record<string, unknown>;
+    /** Anything else the sidecar accepts is passed through untouched. */
+    [key: string]: unknown;
+}
+export interface AgentRuntimeOptions extends SidecarProcessOptions {
+    /**
+     * Host tool handlers for the reverse channel: the CoreLoop calls these
+     * via `tool.invoke` while a turn runs. Register at construction or with
+     * `registerTool`.
+     */
+    tools?: Record<string, (args: Record<string, unknown>) => Promise<Partial<ToolResult> | string>>;
+}
+/**
+ * Host confined-spawn capability (W2.2.1): the sidecar sends
+ * `host.process.spawn` when the platform has no command-rewriting sandbox
+ * backend (Windows) and the request opted into host spawn. The host spawns
+ * the command confined (restricted token + JobObject on Windows) and reports
+ * the enforcement it actually applied. Contract: docs/spec/safety.md
+ * "Host capability surface".
+ */
+export interface HostSpawnRequest {
+    command: string;
+    cwd?: string;
+    policy: {
+        writableRoots: string[];
+        network: boolean;
+        allowedHosts: string[];
+    };
+    context?: {
+        chatId?: string;
+    };
+}
+export interface HostSpawnResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    truncated?: boolean;
+    /** Enforcement the host actually applied; omitting it reports `none`. */
+    sandbox?: {
+        backend: string;
+        enforcement: 'full' | 'partial' | 'none';
+    };
+}
+export declare class AgentRuntime {
+    readonly process: SidecarProcess;
+    private readonly toolHandlers;
+    private spawnHandler;
+    private readonly streams;
+    constructor(options?: AgentRuntimeOptions);
+    /** Spawn the sidecar and wait for readiness. */
+    start(): Promise<void>;
+    /** Graceful drain and exit; in-flight streams finish or fail first. */
+    close(): Promise<void>;
+    /** Register a host tool the CoreLoop may call back during turns. */
+    registerTool(name: string, handler: (args: Record<string, unknown>) => Promise<Partial<ToolResult> | string>): void;
+    /**
+     * 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: (request: HostSpawnRequest) => Promise<HostSpawnResult>): void;
+    ping(): Promise<SidecarHealth>;
+    createSession(input: {
+        chatId: string;
+        userId: string;
+        projectId?: string | null;
+        scenario?: string;
+        stageData?: Record<string, unknown> | null;
+    }): Promise<AgentSession>;
+    resumeSession(sessionId: string): Promise<AgentSession>;
+    listSessions(filter?: {
+        userId?: string;
+        chatId?: string;
+        activeOnly?: boolean;
+    }): Promise<AgentSession[]>;
+    /** Fork a record into a new branch without running a turn. */
+    forkSession(params: {
+        sessionId: string;
+        recordId: string;
+        label?: string;
+    }): Promise<BranchPoint>;
+    /** Branch-family view for a lineage. */
+    sessionBranches(lineage: string): Promise<BranchFamily>;
+    /**
+     * Projected post-boundary message span of a history record — what the
+     * model would see on resume. Fails loud on unknown records.
+     */
+    sessionMessages(recordId: string): Promise<SessionMessages>;
+    /**
+     * 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.
+     */
+    chatStream(params: ChatStreamParams): Promise<ChatStreamHandle>;
+    /** Cooperative cancel: the loop winds down at the next safe point. */
+    cancelChat(streamId: string): Promise<void>;
+    /** Mid-turn steer; resolves true when the running turn accepted it. */
+    steerChat(streamId: string, content: string): Promise<boolean>;
+    /** Fork the record of a running turn. */
+    forkChat(streamId: string, label?: string): Promise<BranchPoint>;
+    listTools(): Promise<ToolDescriptor[]>;
+    invokeTool(call: ToolCall): Promise<ToolResult>;
+    listSkills(roots: string[]): Promise<{
+        skills: SkillInfo[];
+    }>;
+    applyEdits(params: {
+        content: string;
+        edits: unknown[];
+    }): Promise<ApplyEditsResult>;
+    fetchTrace(traceId: string): Promise<TraceFetchResult>;
+    exportTrace(traceId: string): Promise<TraceExportResult>;
+    /** POST turn-outcome counters to a collector's `/v1/metrics`. */
+    exportMetrics(params: {
+        endpoint: string;
+        samples: MetricsExportSample[];
+        serviceName?: string;
+    }): Promise<MetricsExportResult>;
+    getConfig(): Promise<Record<string, unknown>>;
+    setConfig(patch: Record<string, unknown>): Promise<void>;
+    /**
+     * 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(): Promise<{
+        flags: CompatFlagDescriptor[];
+    }>;
+    /**
+     * 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?: {
+        network?: boolean;
+        allowedHosts?: string[];
+        shell?: string;
+    }): Promise<{
+        backend: string;
+        enforcement: 'full' | 'partial' | 'none';
+    }>;
+    /**
+     * 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(): Promise<HarnessDescription>;
+    /**
+     * 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?: {
+        baseUrl?: string;
+        apiKey?: string;
+        refresh?: boolean;
+        provider?: string;
+    }): Promise<GatewayModelCatalog>;
+    /** Every plugin the sidecar registry knows, with lifecycle state. */
+    listPlugins(): Promise<{
+        plugins: PluginRecord[];
+    }>;
+    /** Enable a registered plugin; rejects invalid_params on unknown names. */
+    enablePlugin(name: string): Promise<{
+        plugin: PluginRecord;
+    }>;
+    /** Disable a plugin without unloading its code. */
+    disablePlugin(name: string): Promise<{
+        plugin: PluginRecord;
+    }>;
+    /** Hot-reload a reloadable plugin from its source. */
+    reloadPlugin(name: string): Promise<{
+        plugin: PluginRecord;
+    }>;
+    /**
+     * 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(): Promise<{
+        tools: PluginToolDescriptor[];
+    }>;
+    /** The framework-owned provider-preset table for host settings UIs. */
+    describePresets(): Promise<{
+        presets: ProviderPresetDescriptor[];
+    }>;
+    /**
+     * 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(): Promise<{
+        providers: Array<{
+            id: string;
+            apiBaseUrl: string | null;
+            envVars: string[];
+            wireKind: string;
+            models: string[];
+        }>;
+    }>;
+    /** Which preset a (baseUrl, model) pair would auto-match; null when none. */
+    resolvePreset(input: {
+        baseUrl?: string;
+        model?: string;
+    }): Promise<{
+        preset: ProviderPreset | null;
+    }>;
+    /** The full branch family containing a record (pi-style tree view). */
+    sessionTree(recordId: string): Promise<SessionTreeResult>;
+    /**
+     * 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.
+     */
+    compactChat(streamId: string): Promise<boolean>;
+    private handleReverse;
+    private routeStreamNotification;
+}