@intx/inference 0.1.2 → 0.2.2

package/dist/default-director.js

@@ -0,0 +1,199 @@
+// Default conversational director — reference ReactorDirector implementation.
+//
+// Inbound-event → action map (see INFERENCE.md § Director Decision Function
+// for the director contract and action-validation rules):
+//
+//   message.received          → infer
+//   inference.done (tools)    → checkpoint + execute_tools
+//   tool.done                 → checkpoint + infer (re-infer with tool results)
+//   inference.done (no tools) → checkpoint + reply (connector sends the message)
+//   inference.error           → checkpoint + reply (error message to user)
+//   abort                     → done
+//   reactor.gate.cleared      → checkpoint + infer (resume after gate)
+//
+// The inference.done branch additionally runs the optional afterInferenceDone
+// policy hook, whose continue/abort/halt decisions route independently of the
+// event map above. See AfterInferenceDecision for that contract.
+//
+// The director never throws. Inference errors are surfaced to the user as a
+// reply so the problem is visible, and the agent remains alive for retries.
+import { getLogger } from "@intx/log";
+const logger = getLogger(["interchange", "inference", "default-director"]);
+function extractToolCalls(turn) {
+    const calls = [];
+    for (const block of turn.content) {
+        if (block.type === "tool_call") {
+            calls.push({
+                id: block.id,
+                name: block.name,
+                arguments: block.arguments,
+            });
+        }
+    }
+    return calls;
+}
+function extractTextContent(turn) {
+    // Both regular text and refusal blocks carry human-readable model
+    // output that the connector needs to surface — a refusal-only turn
+    // (OpenAI strict-mode policy decline) would otherwise route through
+    // the empty-response branch below and never reach the reply path,
+    // leaving the human waiting for an answer the model already
+    // declined to give. The structural "this was a refusal" signal is
+    // preserved at the persistence layer (event-collector emits a
+    // refusal turn-part); the reply path only needs the words.
+    const parts = [];
+    for (const block of turn.content) {
+        if (block.type === "text") {
+            parts.push(block.text);
+        }
+        else if (block.type === "refusal") {
+            parts.push(block.reason);
+        }
+    }
+    return parts.join("\n").trim();
+}
+const ERROR_PREAMBLE = {
+    credential_failure: "This agent could not complete your request due to a credential error",
+    quota_exhausted: "This agent could not complete your request because the API quota has been exhausted",
+    context_overflow: "This agent could not complete your request because the conversation exceeded the model's context limit",
+    retryable: "This agent encountered a temporary error communicating with the inference provider",
+    fatal: "This agent could not complete your request due to an unrecoverable inference error",
+    aborted: "This agent's inference request was aborted",
+};
+function formatInferenceError(error) {
+    const preamble = ERROR_PREAMBLE[error.category] ?? ERROR_PREAMBLE["fatal"];
+    const status = error.statusCode !== undefined ? ` [HTTP ${error.statusCode}]` : "";
+    return `${preamble}${status}: ${error.message}`;
+}
+export class DefaultDirector {
+    systemPrompt;
+    toolDefinitions;
+    policy;
+    // Track outstanding tool results so we only re-infer once per batch.
+    pendingToolResults = 0;
+    constructor(systemPrompt, toolDefinitions = [], policy = {}) {
+        this.systemPrompt = systemPrompt;
+        this.toolDefinitions = toolDefinitions;
+        this.policy = policy;
+    }
+    async decide(event, state, capabilities) {
+        switch (event.type) {
+            case "message.received": {
+                return capabilities.infer({
+                    systemPrompt: this.systemPrompt,
+                    tools: this.toolDefinitions,
+                });
+            }
+            case "inference.done": {
+                // The hook gates the entire inference.done branch (including
+                // tool extraction and the reactive-mode wait shortcut). An
+                // abort/halt from the policy drops any tool calls the model
+                // emitted in this turn; see AfterInferenceHook TSDoc for the
+                // implications.
+                if (this.policy.afterInferenceDone !== undefined) {
+                    let decision;
+                    try {
+                        decision = await this.policy.afterInferenceDone(state, event.turn);
+                    }
+                    catch (cause) {
+                        const message = cause instanceof Error ? cause.message : String(cause);
+                        logger.error `afterInferenceDone policy threw: ${message}`;
+                        decision = {
+                            type: "abort",
+                            reason: `afterInferenceDone policy threw: ${message}`,
+                        };
+                    }
+                    if (decision.type === "abort") {
+                        // A reply invites the next inbound message, but abort is
+                        // terminal — the reactor rejects reply paired with done. The
+                        // reason is therefore not surfaced on this path.
+                        return [
+                            capabilities.checkpoint("after-inference-abort"),
+                            capabilities.done(),
+                        ];
+                    }
+                    if (decision.type === "halt") {
+                        // A reply already returns the reactor to waiting for the next
+                        // inbound message, so no separate wait is needed (and the
+                        // reactor rejects reply paired with wait).
+                        return [
+                            capabilities.checkpoint("after-inference-halt"),
+                            capabilities.reply(decision.reason),
+                        ];
+                    }
+                    // decision.type === "continue" — fall through.
+                }
+                const toolCalls = extractToolCalls(event.turn);
+                if (toolCalls.length > 0) {
+                    this.pendingToolResults = toolCalls.length;
+                    return [
+                        capabilities.checkpoint("tool-execution"),
+                        capabilities.executeTools(toolCalls, true),
+                    ];
+                }
+                // No tool calls — the model is done reasoning for this turn.
+                if (this.policy.mode === "reactive") {
+                    return [
+                        capabilities.checkpoint("inference-done"),
+                        capabilities.wait(),
+                    ];
+                }
+                // Conversational agent: send reply via the connector.
+                const replyContent = extractTextContent(event.turn);
+                if (replyContent.length > 0) {
+                    return [
+                        capabilities.checkpoint("inference-done"),
+                        capabilities.reply(replyContent),
+                    ];
+                }
+                // Empty response (no text, no tool calls) — checkpoint and wait for
+                // the next inbound message. The reactor only shuts down on explicit
+                // stop (abort), never because the model produced an empty turn.
+                return [capabilities.checkpoint("inference-done"), capabilities.wait()];
+            }
+            case "tool.done": {
+                this.pendingToolResults--;
+                if (this.pendingToolResults > 0) {
+                    return [];
+                }
+                if (this.policy.mode === "reactive") {
+                    return [capabilities.checkpoint("tool-done"), capabilities.wait()];
+                }
+                // All tool results received — re-infer with complete context.
+                return [
+                    capabilities.checkpoint("tool-done"),
+                    capabilities.infer({
+                        systemPrompt: this.systemPrompt,
+                        tools: this.toolDefinitions,
+                    }),
+                ];
+            }
+            case "inference.error": {
+                const statusDetail = event.error.statusCode !== undefined
+                    ? ` [HTTP ${event.error.statusCode}]`
+                    : "";
+                logger.error `Inference error in default director: ${event.error.message}${statusDetail} (category: ${event.error.category})`;
+                const userMessage = formatInferenceError(event.error);
+                return [
+                    capabilities.checkpoint("inference-error"),
+                    capabilities.reply(userMessage),
+                ];
+            }
+            case "reactor.gate.cleared": {
+                return [
+                    capabilities.checkpoint("gate-cleared"),
+                    capabilities.infer({
+                        systemPrompt: this.systemPrompt,
+                        tools: this.toolDefinitions,
+                    }),
+                ];
+            }
+            case "abort": {
+                return capabilities.done();
+            }
+        }
+    }
+}
+export function createDefaultDirector(systemPrompt, toolDefinitions = [], policy = {}) {
+    return new DefaultDirector(systemPrompt, toolDefinitions, policy);
+}

package/dist/director.d.ts

@@ -0,0 +1,6 @@
+import type { ReactorCapabilities } from "@intx/types/runtime";
+/**
+ * Builds a frozen capabilities object. The same instance is reused across
+ * calls since all methods are pure constructors.
+ */
+export declare function createCapabilities(): ReactorCapabilities;

package/dist/director.js

@@ -0,0 +1,56 @@
+// Director interface types and capabilities factory.
+//
+// The capabilities object is passed to the director on every decision call.
+// It provides a type-safe API for constructing reactor actions without
+// requiring the director to import or construct action literals directly.
+//
+// (INFERENCE.md § Reactor Director › Core Director)
+/**
+ * Builds a frozen capabilities object. The same instance is reused across
+ * calls since all methods are pure constructors.
+ */
+export function createCapabilities() {
+    return {
+        infer(options) {
+            return {
+                type: "infer",
+                ...(options !== undefined ? { options } : {}),
+            };
+        },
+        executeTools(calls, parallel, addToHistory) {
+            return {
+                type: "execute_tools",
+                calls,
+                ...(parallel !== undefined ? { parallel } : {}),
+                ...(addToHistory !== undefined ? { addToHistory } : {}),
+            };
+        },
+        suspend(gate) {
+            return { type: "suspend", gate };
+        },
+        fork(mode, forkId) {
+            return { type: "fork", mode, forkId };
+        },
+        emit(eventType, data) {
+            return { type: "emit", eventType, data };
+        },
+        reply(content) {
+            return { type: "reply", content };
+        },
+        checkpoint(reason) {
+            return {
+                type: "checkpoint",
+                message: reason !== undefined ? `checkpoint: ${reason}` : "checkpoint",
+            };
+        },
+        compact(compactor, reason) {
+            return { type: "compact", compactor, reason };
+        },
+        wait() {
+            return { type: "wait" };
+        },
+        done() {
+            return { type: "done" };
+        },
+    };
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+import type { InferenceError } from "@intx/types/runtime";
+export type { InferenceError };
+export declare function classifyHTTPError(statusCode: number, message: string, raw?: unknown, retryAfterMs?: number): InferenceError;
+export declare function classifyNetworkError(cause: unknown): InferenceError;
+export declare function classifyAbortError(): InferenceError;
+export declare function classifyTimeoutError(kind: "inactivity" | "total", thresholdMs: number): InferenceError;
+/**
+ * The one throw type a response parser is permitted to raise. See the
+ * `ResponseParser` contract on `adapter.ts` for full semantics. `raw`
+ * carries the offending bytes or parsed object so operators can
+ * inspect what came over the wire.
+ */
+export declare class ProtocolMismatchError extends Error {
+    readonly raw: unknown;
+    constructor(detail: string, raw?: unknown);
+}
+export declare function classifyProtocolMismatch(detail: string, raw?: unknown): InferenceError;
+export declare function classifyStreamError(cause: unknown): InferenceError;

package/dist/errors.js

@@ -0,0 +1,83 @@
+export function classifyHTTPError(statusCode, message, raw, retryAfterMs) {
+    if (statusCode === 401 || statusCode === 403) {
+        return { category: "credential_failure", message, statusCode, raw };
+    }
+    if (statusCode === 429) {
+        return {
+            category: "quota_exhausted",
+            message,
+            statusCode,
+            ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+            raw,
+        };
+    }
+    if (statusCode === 400) {
+        // Context-overflow manifests as a 400 with a provider-specific message.
+        // Check for known patterns before falling through to fatal.
+        if (isContextOverflowMessage(message)) {
+            return { category: "context_overflow", message, statusCode, raw };
+        }
+        return { category: "fatal", message, statusCode, raw };
+    }
+    if (statusCode >= 500 && statusCode < 600) {
+        return { category: "retryable", message, statusCode, raw };
+    }
+    return { category: "fatal", message, statusCode, raw };
+}
+export function classifyNetworkError(cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return { category: "retryable", message, raw: cause };
+}
+export function classifyAbortError() {
+    return { category: "aborted", message: "inference aborted" };
+}
+export function classifyTimeoutError(kind, thresholdMs) {
+    const message = kind === "inactivity"
+        ? `inference call exceeded inactivity timeout (${String(thresholdMs)} ms with no events from the provider)`
+        : `inference call exceeded total timeout (${String(thresholdMs)} ms wall-clock)`;
+    return { category: "timeout", message };
+}
+/**
+ * The one throw type a response parser is permitted to raise. See the
+ * `ResponseParser` contract on `adapter.ts` for full semantics. `raw`
+ * carries the offending bytes or parsed object so operators can
+ * inspect what came over the wire.
+ */
+export class ProtocolMismatchError extends Error {
+    raw;
+    constructor(detail, raw) {
+        super(detail);
+        this.name = "ProtocolMismatchError";
+        this.raw = raw;
+    }
+}
+export function classifyProtocolMismatch(detail, raw) {
+    return {
+        category: "protocol_mismatch",
+        message: detail,
+        ...(raw !== undefined ? { raw } : {}),
+    };
+}
+export function classifyStreamError(cause) {
+    if (isAbortError(cause)) {
+        return classifyAbortError();
+    }
+    if (cause instanceof ProtocolMismatchError) {
+        return classifyProtocolMismatch(cause.message, cause.raw);
+    }
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return { category: "retryable", message, raw: cause };
+}
+function isContextOverflowMessage(message) {
+    const lower = message.toLowerCase();
+    return (lower.includes("context_length_exceeded") ||
+        lower.includes("context length") ||
+        lower.includes("too many tokens") ||
+        lower.includes("maximum context") ||
+        lower.includes("input is too long"));
+}
+function isAbortError(value) {
+    return (value instanceof Error &&
+        (value.name === "AbortError" ||
+            value.message === "The user aborted a request."));
+}

package/dist/gates.d.ts

@@ -0,0 +1,27 @@
+import type { GateType } from "@intx/types/runtime";
+export type GateRecord = {
+    gateId: string;
+    type: GateType;
+    timeoutAt: number;
+    correlationId: string | undefined;
+    resolve: (reason: "resolved" | "timeout" | "shutdown") => void;
+    onCleared: (gateId: string, reason: "resolved" | "timeout" | "shutdown") => void;
+    timer: ReturnType<typeof setTimeout>;
+};
+export type GateSnapshot = {
+    gateId: string;
+    type: GateType;
+    timeoutAt: number;
+};
+/**
+ * Manages active gates. All gates must have a positive timeout.
+ */
+export declare function createGateManager(): {
+    register: (gateId: string, type: GateType, timeoutMs: number, correlationId: string | undefined, onCleared: (gateId: string, reason: "resolved" | "timeout" | "shutdown") => void) => Promise<"resolved" | "timeout" | "shutdown">;
+    clear: (gateId: string) => boolean;
+    shutdown: () => void;
+    findByCorrelationId: (correlationId: string) => GateRecord | undefined;
+    snapshot: () => GateSnapshot[];
+    has: (gateId: string) => boolean;
+};
+export type GateManager = ReturnType<typeof createGateManager>;

package/dist/gates.js

@@ -0,0 +1,80 @@
+// Gate management for the agent reactor.
+//
+// Gates block the reactor until an external condition resolves. Each gate has
+// a type, an ID, and a mandatory timeout. The gate manager owns all active
+// gates and exposes methods to register, clear, and time out gates.
+//
+// (INFERENCE.md § Gates, Gate Timeouts, Gate Behavior During Suspension)
+/**
+ * Manages active gates. All gates must have a positive timeout.
+ */
+export function createGateManager() {
+    const gates = new Map();
+    function register(gateId, type, timeoutMs, correlationId, onCleared) {
+        if (timeoutMs <= 0) {
+            throw new Error(`Gate "${gateId}" must have a positive timeout (got ${timeoutMs})`);
+        }
+        if (gates.has(gateId)) {
+            throw new Error(`Gate "${gateId}" is already registered`);
+        }
+        const timeoutAt = Date.now() + timeoutMs;
+        let resolveGate;
+        const promise = new Promise((resolve) => {
+            resolveGate = resolve;
+        });
+        const timer = setTimeout(() => {
+            if (gates.has(gateId)) {
+                gates.delete(gateId);
+                resolveGate("timeout");
+                onCleared(gateId, "timeout");
+            }
+        }, timeoutMs);
+        gates.set(gateId, {
+            gateId,
+            type,
+            timeoutAt,
+            correlationId,
+            resolve: resolveGate,
+            onCleared,
+            timer,
+        });
+        return promise;
+    }
+    function clear(gateId) {
+        const gate = gates.get(gateId);
+        if (gate === undefined)
+            return false;
+        clearTimeout(gate.timer);
+        gates.delete(gateId);
+        gate.resolve("resolved");
+        gate.onCleared(gateId, "resolved");
+        return true;
+    }
+    function shutdown() {
+        const entries = Array.from(gates.values());
+        gates.clear();
+        for (const gate of entries) {
+            clearTimeout(gate.timer);
+            gate.resolve("shutdown");
+            gate.onCleared(gate.gateId, "shutdown");
+        }
+    }
+    function findByCorrelationId(correlationId) {
+        for (const gate of gates.values()) {
+            if (gate.correlationId === correlationId)
+                return gate;
+        }
+        return undefined;
+    }
+    function snapshot() {
+        return Array.from(gates.values()).map((g) => ({
+            gateId: g.gateId,
+            type: g.type,
+            timeoutAt: g.timeoutAt,
+        }));
+    }
+    function has(gateId) {
+        return gates.has(gateId);
+    }
+    return { register, clear, shutdown, findByCorrelationId, snapshot, has };
+}

package/dist/harness.d.ts

@@ -0,0 +1,147 @@
+import type { ConversationTurn, InferenceEvent, InferenceOptions, InferenceSource } from "@intx/types/runtime";
+import type { AdapterRegistry } from "./adapter.js";
+/**
+ * Default per-call inactivity timeout (ms). Two minutes is conservative
+ * for reasoning-heavy models that emit `inference.thinking.delta` tokens
+ * regularly when actually working — sustained silence past this means
+ * the provider stream has genuinely stalled, not that the model is
+ * thinking. Operators can tune via `InferenceOptions.inactivityTimeoutMs`.
+ */
+export declare const DEFAULT_INACTIVITY_TIMEOUT_MS = 120000;
+/**
+ * Default per-call total wall-clock cap (ms). Matches Anthropic's
+ * documented per-call recommendation and fits within typical CI
+ * timeouts. Operators can tune via `InferenceOptions.totalTimeoutMs`.
+ */
+export declare const DEFAULT_TOTAL_TIMEOUT_MS = 600000;
+export declare const HarnessId: unique symbol;
+/**
+ * Runtime dependencies injected into `runInference`. Code-only — not part of
+ * any persisted schema. Test harnesses substitute `fetch` (and stamp the
+ * `[HarnessId]` tag for per-harness identity) so production `runInference`
+ * never reaches `globalThis.fetch`.
+ *
+ * `fetch` is intentionally typed as a plain function rather than
+ * `typeof globalThis.fetch` — the latter is augmented per-runtime (Bun adds
+ * `preconnect`; Node and the DOM lib do not) and `runInference` only ever
+ * invokes the call signature.
+ *
+ * The `[HarnessId]` tag is enumerable via `Object.getOwnPropertySymbols`
+ * (and `Reflect.ownKeys`, which is the superset). Do not pass `Dependencies`
+ * instances through reflective serializers or expose them across trust
+ * boundaries. (`JSON.stringify` is safe — it walks string keys only.)
+ */
+export type Dependencies = {
+    readonly fetch: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    /**
+     * Time-based scheduler used by the harness's per-call timeouts (see
+     * `InferenceOptions.inactivityTimeoutMs` / `totalTimeoutMs`). Production
+     * passes the default wrapper around `setTimeout` / `clearTimeout`; the
+     * deterministic test harness injects a scheduler that wraps its virtual
+     * clock so timeout tests fire at virtual-time-N without sleeping real
+     * wall-clock. Required — every caller must make an explicit choice
+     * between the production scheduler and a virtual one. Use
+     * `createDefaultScheduler()` for the production default.
+     */
+    readonly scheduler: Scheduler;
+    /**
+     * Registry resolving an inference source to its provider adapter.
+     * `runSingleAttempt` consults this on every call via `adapters.resolve`,
+     * so it is required — the caller makes an explicit choice of provider set.
+     * Construct it via `createDependencies(adapters)` (core) or, for the
+     * built-in set, `@intx/inference/providers`' `createDefaultDependencies()`.
+     */
+    readonly adapters: AdapterRegistry;
+    readonly [HarnessId]?: symbol;
+};
+/**
+ * Minimal scheduling abstraction. `setTimeout` returns a canceller; the
+ * canceller is idempotent (multiple calls are safe). The harness uses
+ * this for both the inactivity timer (which is re-armed on every event)
+ * and the total wall-clock cap. `now()` is a monotonic time source in
+ * the same `delayMs` units `setTimeout` accepts — deltas across two
+ * `now()` reads describe elapsed time the same way `setTimeout(...,
+ * delta)` would have measured it.
+ */
+export type Scheduler = {
+    setTimeout(callback: () => void, delayMs: number): () => void;
+    now(): number;
+};
+export declare function createDefaultScheduler(): Scheduler;
+/**
+ * Construct runtime dependencies for `runInference` from an explicit adapter
+ * registry, binding `fetch` to `globalThis.fetch` and `scheduler` to the
+ * production wrapper. The registry is required so the caller makes an explicit
+ * choice of provider set; `@intx/inference/providers`' zero-arg
+ * `createDefaultDependencies()` is the honest default that supplies the
+ * built-in registry.
+ *
+ * @param adapters - Registry resolving inference sources to provider adapters
+ * @returns Fully-populated dependencies
+ */
+export declare function createDependencies(adapters: AdapterRegistry): Dependencies;
+export type InferenceHarnessOptions = {
+    turns: ConversationTurn[];
+    source: InferenceSource;
+    inferenceOptions?: InferenceOptions;
+    signal?: AbortSignal;
+    nextSeq: () => number;
+    deps: Dependencies;
+};
+/**
+ * Run a single inference call with mechanical retry. Wraps
+ * `runSingleAttempt` and consults the configured `RetryPolicy` (or the
+ * default from `createDefaultRetryPolicy`) on every `inference.error`.
+ *
+ * Events from each attempt are buffered until the attempt terminates;
+ * the wrapper only flushes them to the caller once it knows whether
+ * the attempt resolved (`inference.done` or a policy-approved abort)
+ * or whether the attempt's events should be discarded in favour of a
+ * retry. The buffer-and-flush model is what guarantees the caller
+ * sees a single clean event stream — exactly one `inference.start`,
+ * no orphaned partial deltas, no leaked `inference.error`s from
+ * attempts the policy chose to retry. The cost is that no events
+ * reach the caller until the wrapper knows the attempt's terminal
+ * shape, even on a successful first attempt. That trade-off is the
+ * deliberate consequence of making "one clean stream" a hard contract
+ * rather than a best-effort one. Consumers that need token-by-token
+ * partials must pin a custom non-buffering wrapper — no streaming-
+ * partials emission API exists today.
+ *
+ * The buffer is per-call and bounded by the size of one attempt's
+ * event stream — no cross-call accumulation.
+ *
+ * Caller-visible seqs stay contiguous across retries. Each attempt
+ * runs against a private seq allocator; on flush the wrapper
+ * re-stamps the buffered events with seqs from the caller's
+ * `nextSeq`, so a retry that discards an attempt does not leave a
+ * gap in the consumer's seq stream.
+ *
+ * Between attempts the wrapper emits one `inference.retry` event with
+ * the failed attempt's number, the policy-chosen `delayMs`, and the
+ * classified error that triggered the retry. The `setTimeout` await
+ * is driven by `deps.scheduler`, so virtual-clock test harnesses
+ * advance retry delays without sleeping real wall-clock. The
+ * caller-supplied `signal` short-circuits the retry delay: aborting
+ * the signal mid-delay wakes the await immediately and the next
+ * `runSingleAttempt` invocation surfaces `inference.error` of
+ * category `aborted` from its entry-time signal check, which the
+ * default policy aborts on.
+ *
+ * Policy-failure handling: if the policy throws synchronously or its
+ * returned Promise rejects, the wrapper treats the failure as
+ * `{ kind: "abort" }` and surfaces the *original* `inference.error`
+ * to the caller. The policy's own exception is logged at `warn` so
+ * operators can see when a custom policy is failing under load, and
+ * dropped — the inference error is what the caller needs to act on,
+ * not the bug in the policy callback.
+ *
+ * Synchronous throws from `runSingleAttempt` (`ProtocolMismatchError`
+ * raised by the streaming parse or the finalization walk, etc.)
+ * propagate out of `runInference`. The current attempt's buffered
+ * events are discarded along with the throw — those represent
+ * protocol bugs the policy mechanism is not equipped to absorb, and
+ * the caller's `for await` rejects so the failure surfaces rather
+ * than being silently buffered.
+ */
+export declare function runInference(opts: InferenceHarnessOptions): AsyncIterable<InferenceEvent>;