ai-runtime-engine 1.1.0

package/dist/providers/wire/anthropicWire.js

@@ -0,0 +1,83 @@
+/**
+ * Anthropic-native wire (`POST {baseUrl}/v1/messages`). A distinct shape from OpenAI-compat:
+ * `x-api-key` + `anthropic-version` headers, top-level `system`, `content[]`/`stop_reason` response.
+ */
+const ANTHROPIC_VERSION = '2023-06-01';
+function mapStop(reason) {
+    switch (reason) {
+        case 'end_turn':
+        case 'stop_sequence':
+            return 'stop';
+        case 'max_tokens':
+            return 'length';
+        case 'tool_use':
+            return 'tool_calls';
+        default:
+            return 'stop';
+    }
+}
+function userContent(req) {
+    const parts = req.input.parts;
+    if (!parts || parts.length === 0)
+        return req.input.text ?? '';
+    const blocks = [];
+    if (req.input.text)
+        blocks.push({ type: 'text', text: req.input.text });
+    for (const part of parts) {
+        if (part.kind === 'text')
+            blocks.push({ type: 'text', text: part.text });
+        else if (part.kind === 'image') {
+            blocks.push({ type: 'image', source: { type: 'base64', media_type: part.mime, data: part.data.replace(/^data:[^,]+,/, '') } });
+        }
+    }
+    return blocks;
+}
+export const anthropicWire = {
+    shape: 'anthropic',
+    buildRequest(req, ctx) {
+        const base = String(ctx.baseUrl).replace(/\/+$/, '');
+        const body = {
+            model: ctx.model,
+            max_tokens: ctx.maxTokens,
+            temperature: req.params?.temperature ?? 0,
+            messages: [{ role: 'user', content: userContent(req) }],
+        };
+        if (req.system)
+            body.system = req.system;
+        if (req.params?.topP !== undefined)
+            body.top_p = req.params.topP;
+        if (req.params?.stop !== undefined)
+            body.stop_sequences = req.params.stop;
+        if (req.tools && req.tools.length > 0) {
+            body.tools = req.tools.map((t) => ({ name: t.name, ...(t.description ? { description: t.description } : {}), input_schema: t.parameters ?? { type: 'object' } }));
+        }
+        const headers = {
+            'content-type': 'application/json',
+            'anthropic-version': ANTHROPIC_VERSION,
+            ...(ctx.headers ?? {}),
+        };
+        if (ctx.apiKey)
+            headers['x-api-key'] = ctx.apiKey;
+        return { url: `${base}/v1/messages`, headers, body };
+    },
+    readResponse(json) {
+        const j = json;
+        const blocks = j.content ?? [];
+        const text = blocks
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text ?? '')
+            .join('');
+        const parsed = {
+            finishReason: mapStop(j.stop_reason),
+            usage: { inputTokens: j.usage?.input_tokens, outputTokens: j.usage?.output_tokens },
+        };
+        if (text)
+            parsed.text = text;
+        const toolBlocks = blocks.filter((b) => b.type === 'tool_use');
+        if (toolBlocks.length > 0) {
+            const toolCalls = toolBlocks.map((b) => ({ ...(b.id ? { id: b.id } : {}), name: b.name ?? '', arguments: b.input }));
+            parsed.toolCalls = toolCalls;
+        }
+        return parsed;
+    },
+};

package/dist/providers/wire/openaiWire.d.ts

@@ -0,0 +1,7 @@
+/**
+ * OpenAI-compatible wire (`POST {baseUrl}/chat/completions`). This one shape covers Groq, Cerebras,
+ * OpenRouter, Mistral, Ollama's OpenAI endpoint, Gemini's OpenAI-compat endpoint, and any generic
+ * gateway, with a `tools` branch for function-calling.
+ */
+import type { WireModule } from './types.js';
+export declare const openaiWire: WireModule;

package/dist/providers/wire/openaiWire.js

@@ -0,0 +1,81 @@
+/**
+ * OpenAI-compatible wire (`POST {baseUrl}/chat/completions`). This one shape covers Groq, Cerebras,
+ * OpenRouter, Mistral, Ollama's OpenAI endpoint, Gemini's OpenAI-compat endpoint, and any generic
+ * gateway, with a `tools` branch for function-calling.
+ */
+import { toMultimodalContent } from './types.js';
+function mapFinish(reason) {
+    switch (reason) {
+        case 'stop':
+            return 'stop';
+        case 'length':
+            return 'length';
+        case 'tool_calls':
+            return 'tool_calls';
+        case 'content_filter':
+            return 'content_filter';
+        default:
+            return 'stop';
+    }
+}
+export const openaiWire = {
+    shape: 'openai',
+    buildRequest(req, ctx, jsonMode) {
+        const base = String(ctx.baseUrl).replace(/\/+$/, '');
+        const messages = [];
+        if (req.system)
+            messages.push({ role: 'system', content: req.system });
+        messages.push({ role: 'user', content: toMultimodalContent(req.input.text, req.input.parts) });
+        const wantsJson = jsonMode && (req.output?.format === 'json' || req.output?.format === 'structured_output');
+        const body = {
+            model: ctx.model,
+            temperature: req.params?.temperature ?? 0,
+            max_tokens: ctx.maxTokens,
+            messages,
+        };
+        if (req.params?.topP !== undefined)
+            body.top_p = req.params.topP;
+        if (req.params?.stop !== undefined)
+            body.stop = req.params.stop;
+        if (wantsJson)
+            body.response_format = { type: 'json_object' };
+        if (req.tools && req.tools.length > 0) {
+            body.tools = req.tools.map((t) => ({
+                type: 'function',
+                function: { name: t.name, ...(t.description ? { description: t.description } : {}), ...(t.parameters ? { parameters: t.parameters } : {}) },
+            }));
+        }
+        const headers = { 'content-type': 'application/json', ...(ctx.headers ?? {}) };
+        if (ctx.apiKey)
+            headers.authorization = `Bearer ${ctx.apiKey}`;
+        return { url: `${base}/chat/completions`, headers, body };
+    },
+    readResponse(json) {
+        const j = json;
+        const choice = j.choices?.[0];
+        const parsed = {
+            finishReason: mapFinish(choice?.finish_reason),
+            usage: { inputTokens: j.usage?.prompt_tokens, outputTokens: j.usage?.completion_tokens },
+        };
+        const content = choice?.message?.content;
+        if (content)
+            parsed.text = content;
+        const rawCalls = choice?.message?.tool_calls;
+        if (rawCalls && rawCalls.length > 0) {
+            const toolCalls = rawCalls.map((c) => {
+                let args = c.function?.arguments;
+                if (typeof args === 'string') {
+                    try {
+                        args = JSON.parse(args);
+                    }
+                    catch {
+                        /* leave raw string if not JSON */
+                    }
+                }
+                return { ...(c.id ? { id: c.id } : {}), name: c.function?.name ?? '', arguments: args };
+            });
+            parsed.toolCalls = toolCalls;
+        }
+        return parsed;
+    },
+};

package/dist/providers/wire/registry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * wireShape -> wire-module factory. Open for extension: register a new shape without editing the
+ * existing wires. Lives in the providers layer, never in core, so adding a novel protocol never
+ * touches routing/scoring.
+ */
+import type { WireModule, WireShape } from './types.js';
+export declare function getWire(shape: WireShape): WireModule;
+export declare function registerWire(wire: WireModule): void;

package/dist/providers/wire/registry.js

@@ -0,0 +1,20 @@
+/**
+ * wireShape -> wire-module factory. Open for extension: register a new shape without editing the
+ * existing wires. Lives in the providers layer, never in core, so adding a novel protocol never
+ * touches routing/scoring.
+ */
+import { openaiWire } from './openaiWire.js';
+import { anthropicWire } from './anthropicWire.js';
+const WIRES = new Map([
+    ['openai', openaiWire],
+    ['anthropic', anthropicWire],
+]);
+export function getWire(shape) {
+    const wire = WIRES.get(shape);
+    if (!wire)
+        throw new Error(`unknown wire shape '${shape}'`);
+    return wire;
+}
+export function registerWire(wire) {
+    WIRES.set(wire.shape, wire);
+}

package/dist/providers/wire/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The wire-module interface. A wire is the PURE mapping between the normalized AIRequest/AIResponse
+ * and one provider WIRE SHAPE (OpenAI-compatible `/chat/completions`, Anthropic `/v1/messages`, ...).
+ * Purity means the request is assertable without a socket, with no network dependency. Wires live in
+ * the providers layer; `core/` never sees them.
+ */
+import type { AIRequest, FinishReason, ToolCall } from '../../types.js';
+export type WireShape = 'openai' | 'anthropic';
+export interface WireContext {
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    maxTokens: number;
+}
+export interface WireRequest {
+    url: string;
+    headers: Record<string, string>;
+    body: unknown;
+}
+export interface WireParsed {
+    text?: string;
+    json?: unknown;
+    toolCalls?: ToolCall[];
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    finishReason: FinishReason;
+}
+export interface WireModule {
+    readonly shape: WireShape;
+    /** Pure request builder. `jsonMode` requests a JSON response format where the shape supports it. */
+    buildRequest(req: AIRequest, ctx: WireContext, jsonMode: boolean): WireRequest;
+    /** Parse a successful response body into normalized pieces. */
+    readResponse(json: unknown): WireParsed;
+}
+/** Turn input parts into an OpenAI-style content value (string when text-only, array when multimodal). */
+export declare function toMultimodalContent(text: string | undefined, parts: AIRequest['input']['parts']): unknown;

package/dist/providers/wire/types.js

@@ -0,0 +1,24 @@
+/**
+ * The wire-module interface. A wire is the PURE mapping between the normalized AIRequest/AIResponse
+ * and one provider WIRE SHAPE (OpenAI-compatible `/chat/completions`, Anthropic `/v1/messages`, ...).
+ * Purity means the request is assertable without a socket, with no network dependency. Wires live in
+ * the providers layer; `core/` never sees them.
+ */
+/** Turn input parts into an OpenAI-style content value (string when text-only, array when multimodal). */
+export function toMultimodalContent(text, parts) {
+    if (!parts || parts.length === 0)
+        return text ?? '';
+    const content = [];
+    if (text)
+        content.push({ type: 'text', text });
+    for (const part of parts) {
+        if (part.kind === 'text')
+            content.push({ type: 'text', text: part.text });
+        else if (part.kind === 'image') {
+            const url = part.data.startsWith('http') || part.data.startsWith('data:') ? part.data : `data:${part.mime};base64,${part.data}`;
+            content.push({ type: 'image_url', image_url: { url } });
+        }
+        // audio/video/file/pdf are provider-specific and left to native adapters; ignored here.
+    }
+    return content;
+}

package/dist/runtime/config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Runtime configuration loader. Canonical file: `.ai-runtime/config.yaml` (runtime settings + the
+ * router config). WRAPS, never forks, the existing strict `parseConfig`: a small strict zod fragment
+ * validates/plucks the runtime-level keys (runtime:, and learning/verification/budget/policy — which
+ * the root schema rejects), then delegates the remainder to parseConfig so its strictness and
+ * inline-secret rejection are preserved. Root `ai-runtime.yaml` remains a supported fallback.
+ *
+ * NOTE: `src/config/load.ts` and `AI.load()` are intentionally untouched — the CLI's existing behavior
+ * is frozen until Phase 2 migrates it.
+ */
+import type { RuntimeConfig } from './types.js';
+/**
+ * Parse a runtime config object (from `.ai-runtime/config.yaml` or a legacy root file). Runtime-level
+ * keys are validated and split off; everything else is validated by the existing strict router schema.
+ */
+export declare function parseRuntimeConfig(raw: unknown): RuntimeConfig;
+export interface LoadedRuntimeConfig {
+    config: RuntimeConfig;
+    configFile?: string;
+    source: 'runtime-dir' | 'root' | 'explicit' | 'none';
+}
+/** Locate `<root>/.ai-runtime/config.{yaml,yml,json}`. */
+export declare function findRuntimeConfigFile(workspaceRoot: string): string | undefined;
+/**
+ * Load the runtime config for a workspace. dotenv from the workspace root first; then explicit path >
+ * `.ai-runtime/config.*` > legacy root `ai-runtime.*` > empty.
+ */
+export declare function loadRuntimeConfig(opts: {
+    workspaceRoot: string;
+    explicitPath?: string;
+}): LoadedRuntimeConfig;

package/dist/runtime/config.js

@@ -0,0 +1,121 @@
+/**
+ * Runtime configuration loader. Canonical file: `.ai-runtime/config.yaml` (runtime settings + the
+ * router config). WRAPS, never forks, the existing strict `parseConfig`: a small strict zod fragment
+ * validates/plucks the runtime-level keys (runtime:, and learning/verification/budget/policy — which
+ * the root schema rejects), then delegates the remainder to parseConfig so its strictness and
+ * inline-secret rejection are preserved. Root `ai-runtime.yaml` remains a supported fallback.
+ *
+ * NOTE: `src/config/load.ts` and `AI.load()` are intentionally untouched — the CLI's existing behavior
+ * is frozen until Phase 2 migrates it.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { config as loadDotenv } from 'dotenv';
+import { z } from 'zod';
+import { parseConfig, STRATEGIES } from '../config/schema.js';
+import { findConfigFile } from '../config/load.js';
+import { AIError } from '../core/fallback/errors.js';
+import { RUNTIME_MODES } from './types.js';
+/** Runtime-level keys that live in `.ai-runtime/config.yaml` but are NOT part of the strict root schema. */
+const RUNTIME_ONLY_KEYS = ['runtime', 'learning', 'verification', 'budget', 'policy', 'permissions', 'routing'];
+const runtimeSettings = z.object({ defaultMode: z.enum(RUNTIME_MODES).optional(), defaultStrategy: z.enum(STRATEGIES).optional(), context: z.object({ maxTokens: z.number().optional() }).strict().optional(), skills: z.object({ paths: z.array(z.string()).optional(), packages: z.array(z.string()).optional(), autoload: z.boolean().optional() }).strict().optional() }).strict();
+const learning = z.object({ enabled: z.boolean().optional() }).strict();
+const verification = z.object({ enabled: z.boolean().optional() }).strict();
+const budget = z.object({ maxCostUsd: z.number().optional(), maxCalls: z.number().optional() }).strict();
+const policy = z
+    .object({ allowProviders: z.array(z.string()).optional(), denyProviders: z.array(z.string()).optional(), requireLocal: z.boolean().optional(), maxCostUsd: z.number().optional(), strategy: z.enum(STRATEGIES).optional() })
+    .strict();
+const permissions = z
+    .object({ fsRead: z.boolean().optional(), fsWrite: z.boolean().optional(), shell: z.boolean().optional(), shellAllowedCommands: z.array(z.string()).optional(), gitWrite: z.boolean().optional(), gitCommit: z.boolean().optional(), gitPush: z.boolean().optional(), network: z.boolean().optional() })
+    .strict();
+const routing = z
+    .object({ excludeProviders: z.array(z.string()).optional(), excludeModels: z.array(z.string()).optional(), preferProviders: z.array(z.string()).optional(), preferModels: z.array(z.string()).optional() })
+    .strict();
+const runtimeFragment = z
+    .object({ runtime: runtimeSettings.optional(), learning: learning.optional(), verification: verification.optional(), budget: budget.optional(), policy: policy.optional(), permissions: permissions.optional(), routing: routing.optional() })
+    .partial();
+/**
+ * Parse a runtime config object (from `.ai-runtime/config.yaml` or a legacy root file). Runtime-level
+ * keys are validated and split off; everything else is validated by the existing strict router schema.
+ */
+export function parseRuntimeConfig(raw) {
+    if (raw === null || typeof raw !== 'object')
+        throw new AIError('invalid ai-runtime config: expected a mapping', { category: 'CONFIG' });
+    const obj = raw;
+    // Validate the runtime-level fragment.
+    const fragResult = runtimeFragment.safeParse(pick(obj, RUNTIME_ONLY_KEYS));
+    if (!fragResult.success) {
+        const issues = fragResult.error.issues.map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`).join('\n');
+        throw new AIError(`invalid ai-runtime config:\n${issues}`, { category: 'CONFIG' });
+    }
+    const frag = fragResult.data;
+    // Delegate the remainder (providers, strategy, weights, defaults, privacy, telemetry, tasks) to the strict router schema.
+    const rest = omit(obj, RUNTIME_ONLY_KEYS);
+    if (!('providers' in rest))
+        rest.providers = [];
+    const router = parseConfig(rest);
+    // Fold the runtime-only router keys back onto the RouterConfig (they exist on the type; resolveConfig reads them).
+    if (frag.learning)
+        router.learning = frag.learning;
+    if (frag.verification)
+        router.verification = frag.verification;
+    if (frag.budget)
+        router.budget = frag.budget;
+    if (frag.policy)
+        router.policy = frag.policy;
+    // Top-level `routing:` is folded into the runtime settings (a runtime concern, resolved with env + per-run).
+    const runtimeOut = { ...(frag.runtime ?? {}), ...(frag.routing ? { routing: frag.routing } : {}) };
+    return { ...(Object.keys(runtimeOut).length ? { runtime: runtimeOut } : {}), ...(frag.permissions ? { permissions: frag.permissions } : {}), router };
+}
+const RUNTIME_DIR_FILES = ['config.yaml', 'config.yml', 'config.json'];
+/** Locate `<root>/.ai-runtime/config.{yaml,yml,json}`. */
+export function findRuntimeConfigFile(workspaceRoot) {
+    for (const name of RUNTIME_DIR_FILES) {
+        const full = join(workspaceRoot, '.ai-runtime', name);
+        if (existsSync(full))
+            return full;
+    }
+    return undefined;
+}
+/**
+ * Load the runtime config for a workspace. dotenv from the workspace root first; then explicit path >
+ * `.ai-runtime/config.*` > legacy root `ai-runtime.*` > empty.
+ */
+export function loadRuntimeConfig(opts) {
+    loadDotenv({ path: resolve(opts.workspaceRoot, '.env'), quiet: true });
+    if (opts.explicitPath) {
+        const file = resolve(opts.workspaceRoot, opts.explicitPath);
+        // A missing explicit path yields an empty config (matches the legacy loader; a typo'd -c never throws).
+        if (!existsSync(file))
+            return { config: { router: { providers: [] } }, source: 'none' };
+        return { config: parseRuntimeConfig(readParsed(file)), configFile: file, source: 'explicit' };
+    }
+    const runtimeFile = findRuntimeConfigFile(opts.workspaceRoot);
+    if (runtimeFile)
+        return { config: parseRuntimeConfig(readParsed(runtimeFile)), configFile: runtimeFile, source: 'runtime-dir' };
+    const rootFile = findConfigFile(opts.workspaceRoot);
+    if (rootFile)
+        return { config: parseRuntimeConfig(readParsed(rootFile)), configFile: rootFile, source: 'root' };
+    return { config: { router: { providers: [] } }, source: 'none' };
+}
+// ── helpers ──
+function readParsed(file) {
+    const text = readFileSync(file, 'utf8');
+    return file.endsWith('.json') ? JSON.parse(text) : parseYaml(text);
+}
+function pick(obj, keys) {
+    const out = {};
+    for (const k of keys)
+        if (k in obj)
+            out[k] = obj[k];
+    return out;
+}
+function omit(obj, keys) {
+    const drop = new Set(keys);
+    const out = {};
+    for (const [k, v] of Object.entries(obj))
+        if (!drop.has(k))
+            out[k] = v;
+    return out;
+}

package/dist/runtime/context.d.ts

@@ -0,0 +1,34 @@
+/**
+ * RuntimeContext — the ONE runtime-state container, assembled once per run and passed by reference to
+ * every Runtime layer (mode resolution, context compiler, planner, orchestrator, executor, memory,
+ * skills, tools). No other overlapping runtime-state abstraction exists. NOTE: this is runtime STATE;
+ * the ContextCompiler's output (compiled model input) is a different, transient thing.
+ *
+ * Slots are optional and fill in as phases land (P1: runId/request/workspace/policy/budget/provider
+ * state; P3: conversation/memory; P6: plan; P7: execution). Later-phase slots are typed `unknown` for
+ * now so they widen without a breaking change.
+ */
+import type { ExecutionPolicy } from './policy.js';
+import type { RuntimeRunInput } from './types.js';
+import type { WorkspaceInfo } from './workspace/workspace.js';
+export interface RuntimeContext {
+    /** Identity of this runtime.run() invocation. */
+    runId: string;
+    /** Caller idempotency identity, if supplied. */
+    requestId?: string;
+    request: RuntimeRunInput;
+    workspace?: WorkspaceInfo;
+    /** The single policy authority for this run. */
+    policy: ExecutionPolicy;
+    budget?: {
+        maxCostUsd?: number;
+        maxCalls?: number;
+    };
+    /** Read-only provider/model state views (discovery/health), attached by later phases. */
+    providerState?: unknown;
+    conversation?: unknown;
+    memory?: unknown;
+    plan?: unknown;
+    execution?: unknown;
+    metadata?: Record<string, unknown>;
+}

package/dist/runtime/context.js

@@ -0,0 +1,11 @@
+/**
+ * RuntimeContext — the ONE runtime-state container, assembled once per run and passed by reference to
+ * every Runtime layer (mode resolution, context compiler, planner, orchestrator, executor, memory,
+ * skills, tools). No other overlapping runtime-state abstraction exists. NOTE: this is runtime STATE;
+ * the ContextCompiler's output (compiled model input) is a different, transient thing.
+ *
+ * Slots are optional and fill in as phases land (P1: runId/request/workspace/policy/budget/provider
+ * state; P3: conversation/memory; P6: plan; P7: execution). Later-phase slots are typed `unknown` for
+ * now so they widen without a breaking change.
+ */
+export {};

package/dist/runtime/events.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Runtime lifecycle events — a SEPARATE union from the router's TelemetryEvent (which is frozen). The
+ * emitter fans out redacted, metadata-only events to sinks, and never lets a throwing observer break a
+ * run. Every event carries the correlation `runId` so a host can join a live stream to a RunResult.
+ *
+ * Token-streaming extension point: `response.delta` is reserved here (content-bearing, redacted like
+ * everything else). Provider token streaming is NOT implemented in 1.0 — no delta is ever emitted yet —
+ * but declaring the arm keeps the host/emitter architecture ready for it without a breaking change.
+ */
+import type { Clock } from '../util/clock.js';
+import type { ErrorCategory } from '../types.js';
+import type { ExecutableMode, ModeSource, RuntimeMode, RuntimeStatus } from './types.js';
+export type RuntimeEvent = {
+    type: 'runtime.started';
+    ts: number;
+    runId: string;
+    requested: RuntimeMode;
+} | {
+    type: 'mode.selected';
+    ts: number;
+    runId: string;
+    requested: RuntimeMode;
+    selected: ExecutableMode;
+    executed: ExecutableMode;
+    source: ModeSource;
+    confidence: number;
+} | {
+    type: 'clarification.requested';
+    ts: number;
+    runId: string;
+    question: string;
+} | {
+    type: 'provider.selected';
+    ts: number;
+    runId: string;
+    providerId: string;
+    model: string;
+} | {
+    type: 'provider.failed';
+    ts: number;
+    runId: string;
+    providerId: string;
+    model: string;
+    category?: ErrorCategory;
+} | {
+    type: 'run.completed';
+    ts: number;
+    runId: string;
+    ok: boolean;
+    status: RuntimeStatus;
+    confidence: number;
+} | {
+    type: 'response.delta';
+    ts: number;
+    runId: string;
+    text: string;
+};
+/** Distributive Omit so an event can be emitted without pre-stamping `ts`. */
+type WithoutTs<T> = T extends unknown ? Omit<T, 'ts'> : never;
+export type RuntimeEventInput = WithoutTs<RuntimeEvent>;
+/** A sink for runtime events. Mirrors the telemetry sink shape (emit + optional events query). */
+export interface RuntimeEventSink {
+    emit(event: RuntimeEvent): void;
+    events?(): RuntimeEvent[];
+}
+/** In-memory ring buffer of recent events. */
+export declare class MemoryEventSink implements RuntimeEventSink {
+    private readonly limit;
+    private readonly buffer;
+    constructor(limit?: number);
+    emit(event: RuntimeEvent): void;
+    events(): RuntimeEvent[];
+}
+/** Forwards each event to a user callback; a throwing callback can never break a run. */
+export declare class CallbackEventSink implements RuntimeEventSink {
+    private readonly forward;
+    constructor(forward: (event: RuntimeEvent) => void);
+    emit(event: RuntimeEvent): void;
+}
+/**
+ * Fans out redacted events to a built-in memory buffer plus any attached sinks. Redaction happens once
+ * here, at entry, so downstream sinks receive already-scrubbed metadata.
+ */
+export declare class RuntimeEmitter {
+    private readonly clock;
+    private readonly memory;
+    private readonly sinks;
+    constructor(options?: {
+        clock?: Clock;
+        sinks?: RuntimeEventSink[];
+    });
+    /** Stamp `ts`, redact once, and fan out. A throwing sink can never break a run. */
+    emit(input: RuntimeEventInput): void;
+    /** Subscribe to future events; returns an unsubscribe function. */
+    on(listener: (event: RuntimeEvent) => void): () => void;
+    /** Recent events from the built-in buffer. */
+    recent(): RuntimeEvent[];
+}
+export {};

package/dist/runtime/events.js

@@ -0,0 +1,82 @@
+/**
+ * Runtime lifecycle events — a SEPARATE union from the router's TelemetryEvent (which is frozen). The
+ * emitter fans out redacted, metadata-only events to sinks, and never lets a throwing observer break a
+ * run. Every event carries the correlation `runId` so a host can join a live stream to a RunResult.
+ *
+ * Token-streaming extension point: `response.delta` is reserved here (content-bearing, redacted like
+ * everything else). Provider token streaming is NOT implemented in 1.0 — no delta is ever emitted yet —
+ * but declaring the arm keeps the host/emitter architecture ready for it without a breaking change.
+ */
+import { systemClock } from '../util/clock.js';
+import { redact } from '../security/redact.js';
+/** In-memory ring buffer of recent events. */
+export class MemoryEventSink {
+    limit;
+    buffer = [];
+    constructor(limit = 500) {
+        this.limit = limit;
+    }
+    emit(event) {
+        this.buffer.push(event);
+        if (this.buffer.length > this.limit)
+            this.buffer.shift();
+    }
+    events() {
+        return [...this.buffer];
+    }
+}
+/** Forwards each event to a user callback; a throwing callback can never break a run. */
+export class CallbackEventSink {
+    forward;
+    constructor(forward) {
+        this.forward = forward;
+    }
+    emit(event) {
+        try {
+            this.forward(event);
+        }
+        catch {
+            /* observability must never break a run */
+        }
+    }
+}
+/**
+ * Fans out redacted events to a built-in memory buffer plus any attached sinks. Redaction happens once
+ * here, at entry, so downstream sinks receive already-scrubbed metadata.
+ */
+export class RuntimeEmitter {
+    clock;
+    memory = new MemoryEventSink();
+    sinks;
+    constructor(options = {}) {
+        this.clock = options.clock ?? systemClock;
+        this.sinks = options.sinks ?? [];
+    }
+    /** Stamp `ts`, redact once, and fan out. A throwing sink can never break a run. */
+    emit(input) {
+        const event = redact({ ...input, ts: this.clock.now() });
+        this.memory.emit(event);
+        for (const sink of this.sinks) {
+            try {
+                sink.emit(event);
+            }
+            catch {
+                /* observability must never break a run */
+            }
+        }
+    }
+    /** Subscribe to future events; returns an unsubscribe function. */
+    on(listener) {
+        const sink = new CallbackEventSink(listener);
+        this.sinks.push(sink);
+        return () => {
+            const i = this.sinks.indexOf(sink);
+            if (i >= 0)
+                this.sinks.splice(i, 1);
+        };
+    }
+    /** Recent events from the built-in buffer. */
+    recent() {
+        return this.memory.events();
+    }
+}