@intx/inference 0.1.2 → 0.2.2

package/src/default-director.ts

@@ -1,344 +0,0 @@
-// Default conversational director — reference ReactorDirector implementation.
-//
-// Implements the decision table from INFERENCE.md § Director Decision Function:
-//
-//   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 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";
-import type {
-  ReactorDirector,
-  ReactorInboundEvent,
-  ReactorState,
-  ReactorCapabilities,
-  ReactorAction,
-  AssistantTurn,
-  ToolCall,
-  ToolDefinition,
-} from "@intx/types/runtime";
-
-const logger = getLogger(["interchange", "inference", "default-director"]);
-
-/**
- * Decision returned by an `afterInferenceDone` policy hook.
- *
- *   continue — proceed with the director's normal post-inference logic
- *              (tool extraction, reply, or wait per the existing flow).
- *   abort    — terminate the agent. Routes to `[checkpoint, reply, done]`
- *              and the reactor shuts down. Stronger than the
- *              `inference.error` branch, which only replies and stays
- *              alive — `abort` is for "session is over, do not accept
- *              further inputs."
- *   halt     — pause the current cycle without terminating. Routes to
- *              `[checkpoint, reply, wait]`. Reactor stays alive waiting
- *              for the next inbound event. There is no auto-resume; an
- *              external event (mail, gate clearance, etc.) must reach
- *              the reactor for the agent to make progress again.
- *
- * `reason` becomes the connector reply text verbatim — policy authors
- * choose what is safe to surface to the user. There is no separate
- * private-reason / user-message split today; add one if a real need
- * appears.
- */
-export type AfterInferenceDecision =
-  | { type: "continue" }
-  | { type: "abort"; reason: string }
-  | { type: "halt"; reason: string };
-
-/**
- * Function shape for an after-inference-done policy hook.
- *
- * The hook fires only on `inference.done` (a successful cycle). Errored
- * cycles do not invoke it. `mode: "reactive"` does not change firing —
- * the hook gates the entire `inference.done` branch, including the
- * reactive-wait shortcut, so a budget check applies to reactive agents
- * the same way it does to conversational ones.
- *
- * The hook receives the post-cycle `ReactorState` (with `lastCycleSource`
- * and `lastCycleUsage` populated for the just-completed call) and the
- * assistant turn. Returns a decision (sync or async) that controls
- * whether the director continues, terminates the agent, or pauses the
- * cycle.
- *
- * Canonical use case: cost-aware gating. Read `state.lastCycleSource`
- * + `state.lastCycleUsage`, price the call against user-supplied rate
- * data, decide whether the budget is exhausted. Token caps, time caps,
- * wallet checks, and governance triggers fit the same shape; the
- * type stays policy-agnostic.
- *
- * "Downgrade to cheaper model" policies do NOT use this hook to return
- * a new source. Compose them via an external observer of
- * `lastCycleSource` / `lastCycleUsage` that calls `setSource` from
- * outside the director.
- *
- * The hook blocks the reactor's inference.done branch: keep its
- * latency low. The return type admits a Promise, but every await
- * inside the hook is wall-clock time the agent isn't making progress.
- * Small lookups (in-memory caches, fast DB reads) are fine; arbitrary
- * waits are not.
- *
- * Tool calls and `halt`: if the model emitted tool calls and the hook
- * returns `halt` (or `abort`), those tool calls are dropped — the
- * director never executes them. On resume, the model's next inference
- * sees an assistant turn with unanswered tool calls; depending on the
- * provider this is either a validation error or a confused model.
- * Policy authors that combine `halt` with tool-heavy agents need to
- * understand this.
- */
-export type AfterInferenceHook = (
-  state: ReactorState,
-  turn: AssistantTurn,
-) => AfterInferenceDecision | Promise<AfterInferenceDecision>;
-
-export type DefaultDirectorPolicy = {
-  /**
-   * Controls the agent's behavior after inference completes.
-   *
-   *   "conversational" (default) — The standard agentic loop. After tools
-   *     complete, re-infer so the model can reason about results, issue more
-   *     tool calls, or compose a reply. When inference produces text without
-   *     tool calls, send it as a connector reply.
-   *
-   *   "reactive" — The agent acts on each message by executing tools, then
-   *     returns to the event loop to wait for the next inbound event. It does
-   *     not re-infer after tools complete and does not send connector replies.
-   *     Use this for agents that perform a single action per message.
-   */
-  mode?: "conversational" | "reactive";
-
-  /**
-   * Optional policy hook fired after every successful `inference.done`.
-   * See `AfterInferenceHook` for the contract: firing boundary, return
-   * shape, composition patterns, and policy-author caveats.
-   *
-   * If the hook throws or rejects, the director catches the error,
-   * routes to `{ type: "abort", reason: "afterInferenceDone policy
-   * threw: <message>" }`, and logs at error level. The director's
-   * never-throws contract is preserved.
-   */
-  afterInferenceDone?: AfterInferenceHook;
-};
-
-function extractToolCalls(turn: AssistantTurn): ToolCall[] {
-  const calls: ToolCall[] = [];
-  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: AssistantTurn): string {
-  // 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: string[] = [];
-  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: Record<string, string> = {
-  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: {
-  category: string;
-  message: string;
-  statusCode?: number;
-}): string {
-  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 implements ReactorDirector {
-  private readonly systemPrompt: string;
-  private readonly toolDefinitions: ToolDefinition[];
-  private readonly policy: DefaultDirectorPolicy;
-
-  // Track outstanding tool results so we only re-infer once per batch.
-  private pendingToolResults = 0;
-
-  constructor(
-    systemPrompt: string,
-    toolDefinitions: ToolDefinition[] = [],
-    policy: DefaultDirectorPolicy = {},
-  ) {
-    this.systemPrompt = systemPrompt;
-    this.toolDefinitions = toolDefinitions;
-    this.policy = policy;
-  }
-
-  async decide(
-    event: ReactorInboundEvent,
-    state: ReactorState,
-    capabilities: ReactorCapabilities,
-  ): Promise<ReactorAction | ReactorAction[]> {
-    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: AfterInferenceDecision;
-          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") {
-            return [
-              capabilities.checkpoint("after-inference-abort"),
-              capabilities.reply(decision.reason),
-              capabilities.done(),
-            ];
-          }
-          if (decision.type === "halt") {
-            return [
-              capabilities.checkpoint("after-inference-halt"),
-              capabilities.reply(decision.reason),
-              capabilities.wait(),
-            ];
-          }
-          // 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: string,
-  toolDefinitions: ToolDefinition[] = [],
-  policy: DefaultDirectorPolicy = {},
-): ReactorDirector {
-  return new DefaultDirector(systemPrompt, toolDefinitions, policy);
-}

package/src/director.ts

@@ -1,87 +0,0 @@
-// 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)
-
-import type {
-  ReactorAction,
-  ReactorCapabilities,
-  GateType,
-  ForkMode,
-  InferenceOptions,
-  ToolCall,
-} from "@intx/types/runtime";
-
-/**
- * Builds a frozen capabilities object. The same instance is reused across
- * calls since all methods are pure constructors.
- */
-export function createCapabilities(): ReactorCapabilities {
-  return {
-    infer(options?: InferenceOptions): ReactorAction {
-      return {
-        type: "infer",
-        ...(options !== undefined ? { options } : {}),
-      };
-    },
-
-    executeTools(
-      calls: ToolCall[],
-      parallel?: boolean,
-      addToHistory?: boolean,
-    ): ReactorAction {
-      return {
-        type: "execute_tools",
-        calls,
-        ...(parallel !== undefined ? { parallel } : {}),
-        ...(addToHistory !== undefined ? { addToHistory } : {}),
-      };
-    },
-
-    suspend(gate: {
-      type: GateType;
-      gateId: string;
-      timeoutMs: number;
-      correlationId?: string;
-    }): ReactorAction {
-      return { type: "suspend", gate };
-    },
-
-    fork(mode: ForkMode, forkId: string): ReactorAction {
-      return { type: "fork", mode, forkId };
-    },
-
-    emit(
-      eventType: `custom.${string}`,
-      data: Record<string, unknown>,
-    ): ReactorAction {
-      return { type: "emit", eventType, data };
-    },
-
-    reply(content: string): ReactorAction {
-      return { type: "reply", content };
-    },
-
-    checkpoint(reason?: string): ReactorAction {
-      return {
-        type: "checkpoint",
-        message: reason !== undefined ? `checkpoint: ${reason}` : "checkpoint",
-      };
-    },
-
-    compact(compactor: string, reason: string): ReactorAction {
-      return { type: "compact", compactor, reason };
-    },
-
-    wait(): ReactorAction {
-      return { type: "wait" };
-    },
-
-    done(): ReactorAction {
-      return { type: "done" };
-    },
-  };
-}

package/src/errors.test.ts

@@ -1,133 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import {
-  classifyHTTPError,
-  classifyNetworkError,
-  classifyAbortError,
-  classifyStreamError,
-  classifyProtocolMismatch,
-  ProtocolMismatchError,
-} from "./errors";
-
-describe("classifyHTTPError", () => {
-  test("401 → credential_failure", () => {
-    const err = classifyHTTPError(401, "Unauthorized");
-    expect(err.category).toBe("credential_failure");
-    expect(err.statusCode).toBe(401);
-  });
-
-  test("403 → credential_failure", () => {
-    const err = classifyHTTPError(403, "Forbidden");
-    expect(err.category).toBe("credential_failure");
-    expect(err.statusCode).toBe(403);
-  });
-
-  test("429 → quota_exhausted", () => {
-    const err = classifyHTTPError(429, "Too Many Requests");
-    expect(err.category).toBe("quota_exhausted");
-    expect(err.statusCode).toBe(429);
-  });
-
-  test("500 → retryable", () => {
-    const err = classifyHTTPError(500, "Internal Server Error");
-    expect(err.category).toBe("retryable");
-    expect(err.statusCode).toBe(500);
-  });
-
-  test("503 → retryable", () => {
-    const err = classifyHTTPError(503, "Service Unavailable");
-    expect(err.category).toBe("retryable");
-  });
-
-  test("400 with context_length_exceeded → context_overflow", () => {
-    const err = classifyHTTPError(
-      400,
-      "context_length_exceeded: too many tokens",
-    );
-    expect(err.category).toBe("context_overflow");
-  });
-
-  test("400 with 'input is too long' → context_overflow", () => {
-    const err = classifyHTTPError(400, "input is too long for this model");
-    expect(err.category).toBe("context_overflow");
-  });
-
-  test("400 with generic message → fatal", () => {
-    const err = classifyHTTPError(400, "Bad request");
-    expect(err.category).toBe("fatal");
-  });
-
-  test("404 → fatal", () => {
-    const err = classifyHTTPError(404, "Not Found");
-    expect(err.category).toBe("fatal");
-  });
-
-  test("carries raw body", () => {
-    const raw = { error: { message: "oops" } };
-    const err = classifyHTTPError(500, "Server Error", raw);
-    expect(err.raw).toBe(raw);
-  });
-});
-
-describe("classifyNetworkError", () => {
-  test("Error instance → retryable with message", () => {
-    const err = classifyNetworkError(new Error("ECONNRESET"));
-    expect(err.category).toBe("retryable");
-    expect(err.message).toBe("ECONNRESET");
-  });
-
-  test("string → retryable", () => {
-    const err = classifyNetworkError("network timeout");
-    expect(err.category).toBe("retryable");
-    expect(err.message).toBe("network timeout");
-  });
-});
-
-describe("classifyAbortError", () => {
-  test("always returns aborted category", () => {
-    const err = classifyAbortError();
-    expect(err.category).toBe("aborted");
-  });
-});
-
-describe("classifyStreamError", () => {
-  test("AbortError → aborted", () => {
-    const abort = new DOMException("Aborted", "AbortError");
-    const err = classifyStreamError(abort);
-    expect(err.category).toBe("aborted");
-  });
-
-  test("generic Error → retryable", () => {
-    const err = classifyStreamError(new Error("stream corrupted"));
-    expect(err.category).toBe("retryable");
-    expect(err.message).toBe("stream corrupted");
-  });
-
-  test("ProtocolMismatchError → protocol_mismatch with raw passed through", () => {
-    const raw = { choices: [{ delta: { role: 42 } }] };
-    const cause = new ProtocolMismatchError(
-      "delta.role must be a string (was number)",
-      raw,
-    );
-    const err = classifyStreamError(cause);
-    expect(err.category).toBe("protocol_mismatch");
-    expect(err.message).toBe("delta.role must be a string (was number)");
-    expect(err.raw).toBe(raw);
-  });
-});
-
-describe("classifyProtocolMismatch", () => {
-  test("constructs a protocol_mismatch error with the given detail and raw", () => {
-    const raw = { malformed: true };
-    const err = classifyProtocolMismatch("bad chunk", raw);
-    expect(err.category).toBe("protocol_mismatch");
-    expect(err.message).toBe("bad chunk");
-    expect(err.raw).toBe(raw);
-  });
-
-  test("omits raw when none is supplied", () => {
-    const err = classifyProtocolMismatch("bad chunk");
-    expect(err.category).toBe("protocol_mismatch");
-    expect(err.message).toBe("bad chunk");
-    expect("raw" in err).toBe(false);
-  });
-});

package/src/errors.ts

@@ -1,115 +0,0 @@
-import type { InferenceError } from "@intx/types/runtime";
-
-export type { InferenceError };
-
-export function classifyHTTPError(
-  statusCode: number,
-  message: string,
-  raw?: unknown,
-  retryAfterMs?: number,
-): InferenceError {
-  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: unknown): InferenceError {
-  const message = cause instanceof Error ? cause.message : String(cause);
-  return { category: "retryable", message, raw: cause };
-}
-
-export function classifyAbortError(): InferenceError {
-  return { category: "aborted", message: "inference aborted" };
-}
-
-export function classifyTimeoutError(
-  kind: "inactivity" | "total",
-  thresholdMs: number,
-): InferenceError {
-  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 {
-  readonly raw: unknown;
-  constructor(detail: string, raw?: unknown) {
-    super(detail);
-    this.name = "ProtocolMismatchError";
-    this.raw = raw;
-  }
-}
-
-export function classifyProtocolMismatch(
-  detail: string,
-  raw?: unknown,
-): InferenceError {
-  return {
-    category: "protocol_mismatch",
-    message: detail,
-    ...(raw !== undefined ? { raw } : {}),
-  };
-}
-
-export function classifyStreamError(cause: unknown): InferenceError {
-  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: string): boolean {
-  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: unknown): boolean {
-  return (
-    value instanceof Error &&
-    (value.name === "AbortError" ||
-      value.message === "The user aborted a request.")
-  );
-}