@intx/inference 0.1.2

package/src/retry-policy.ts

@@ -0,0 +1,99 @@
+// The default per-call mechanical retry policy. See `RetryPolicy` /
+// `RetrySituation` / `RetryDecision` in `@intx/types/runtime` for the
+// public contract. This module ships the opinionated defaults the
+// harness substitutes when `InferenceOptions.retryPolicy` is omitted.
+//
+// The defaults are deliberately conservative: enough to absorb the
+// transient-flake surface (TCP resets, 5xx, rate-limit jitter, half-
+// streamed connection drops) without masking a genuinely persistent
+// failure under a retry loop a human would never notice.
+
+import type {
+  RetryPolicy,
+  RetrySituation,
+  RetryDecision,
+} from "@intx/types/runtime";
+
+const MAX_ATTEMPTS = 3;
+// Indexed by the failed attempt number (1-indexed): the delay BEFORE
+// the attempt-after-this-one starts. Length must be `MAX_ATTEMPTS - 1`
+// because after the final attempt fails the policy aborts. Drives the
+// `retryable` and `timeout` schedules.
+const RETRYABLE_BACKOFF_BY_FAILED_ATTEMPT_MS: readonly number[] = [500, 1000];
+const QUOTA_DEFAULT_DELAY_MS = 1000;
+
+/**
+ * The default retry policy bundled with `@intx/inference`. Behaviour by
+ * `InferenceError.category`:
+ *
+ * - `credential_failure`, `context_overflow`, `fatal`, `aborted`,
+ *   `protocol_mismatch` — never retry. These categories describe a
+ *   deterministic per-call failure that re-issuing the identical
+ *   request cannot resolve: bad credentials stay bad, a too-large
+ *   context stays too large, a caller-driven abort is intentional,
+ *   and a wire-shape mismatch will repeat on the next response.
+ * - `retryable`, `timeout` — up to 3 attempts total. 500ms before
+ *   attempt 2, then 1000ms before attempt 3. Exponential rather than
+ *   constant so a server taking longer than usual to recover gets a
+ *   slightly larger window each time without compounding into a long
+ *   tail.
+ * - `quota_exhausted` — up to 3 attempts total. The delay is taken
+ *   from `error.retryAfterMs` when the provider returned one (the
+ *   server told us when it would be ready); otherwise a flat
+ *   `1000`ms baseline. The baseline does NOT grow across attempts —
+ *   if 1s isn't long enough for a rate limit to clear, exponential
+ *   backoff on top of the provider's own pacing instructions is more
+ *   likely to mask a config problem than help. Operators who need
+ *   exponential pacing for rate limits should supply a custom policy.
+ *
+ * The 3-attempt cap is the same across every retryable category: a
+ * single transient flake is plausible, two is rare, and a third
+ * failure across the backoff schedule is a real signal that the call
+ * is not going to succeed on its own.
+ */
+export function createDefaultRetryPolicy(): RetryPolicy {
+  return (situation: RetrySituation): RetryDecision => {
+    const { error, attempt } = situation;
+
+    switch (error.category) {
+      case "credential_failure":
+      case "context_overflow":
+      case "fatal":
+      case "aborted":
+      case "protocol_mismatch":
+        return { kind: "abort" };
+
+      case "retryable":
+      case "timeout": {
+        if (attempt >= MAX_ATTEMPTS) return { kind: "abort" };
+        const delayMs = RETRYABLE_BACKOFF_BY_FAILED_ATTEMPT_MS[attempt - 1];
+        if (delayMs === undefined) {
+          // Unreachable in practice given the `attempt >= MAX_ATTEMPTS`
+          // guard above, but the explicit narrowing keeps the schedule
+          // table and the cap from drifting silently if anyone bumps
+          // `MAX_ATTEMPTS` without extending the table.
+          return { kind: "abort" };
+        }
+        return { kind: "retry", delayMs };
+      }
+
+      case "quota_exhausted":
+        if (attempt >= MAX_ATTEMPTS) return { kind: "abort" };
+        return {
+          kind: "retry",
+          delayMs: error.retryAfterMs ?? QUOTA_DEFAULT_DELAY_MS,
+        };
+
+      default: {
+        // Exhaustiveness: if a new InferenceError.category lands
+        // without a clause here, the never-assignment fails at
+        // compile time rather than silently returning undefined
+        // from the policy callback.
+        const exhaustive: never = error.category;
+        throw new Error(
+          `createDefaultRetryPolicy: unhandled error category ${String(exhaustive)}`,
+        );
+      }
+    }
+  };
+}

package/src/scheduler.test.ts

@@ -0,0 +1,41 @@
+// Tests for the `Scheduler` time source. The harness reads
+// `scheduler.now()` to time deltas across multiple operations within a
+// single call; the contract that matters is monotonicity and the same
+// time domain as `setTimeout`. We do not assert specific values — the
+// production default uses `performance.now()` which is sub-ms and
+// floating-point.
+
+import { describe, test, expect } from "bun:test";
+
+import { createDefaultScheduler } from "./harness";
+
+describe("createDefaultScheduler", () => {
+  test("now() returns a finite number", () => {
+    const scheduler = createDefaultScheduler();
+    const value = scheduler.now();
+    expect(Number.isFinite(value)).toBe(true);
+  });
+
+  test("now() is monotonic: a second read is not less than the first", () => {
+    const scheduler = createDefaultScheduler();
+    const a = scheduler.now();
+    const b = scheduler.now();
+    expect(b).toBeGreaterThanOrEqual(a);
+  });
+
+  test("now() advances across a setTimeout that fires", async () => {
+    const scheduler = createDefaultScheduler();
+    const before = scheduler.now();
+    await new Promise<void>((resolve) => {
+      scheduler.setTimeout(() => {
+        resolve();
+      }, 5);
+    });
+    const after = scheduler.now();
+    // Real wall-clock time elapsed across the await must be reflected
+    // in `now()` — the time domain of `setTimeout` and `now()` is the
+    // contract that lets the retry wrapper compute `elapsedMs` from
+    // two `now()` reads sandwiching a `setTimeout`-driven delay.
+    expect(after - before).toBeGreaterThanOrEqual(5);
+  });
+});

package/src/sse.test.ts

@@ -0,0 +1,133 @@
+import { describe, test, expect } from "bun:test";
+import { parseSSE } from "./sse";
+
+function makeStream(chunks: string[]): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    start(controller) {
+      for (const chunk of chunks) {
+        controller.enqueue(encoder.encode(chunk));
+      }
+      controller.close();
+    },
+  });
+}
+
+async function collectSSE(
+  stream: ReadableStream<Uint8Array>,
+): Promise<string[]> {
+  const results: string[] = [];
+  for await (const data of parseSSE(stream)) {
+    results.push(data);
+  }
+  return results;
+}
+
+describe("parseSSE", () => {
+  test("parses a single complete data line", async () => {
+    const stream = makeStream(["data: hello\n\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["hello"]);
+  });
+
+  test("parses multiple data events", async () => {
+    const stream = makeStream(["data: first\n\ndata: second\n\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["first", "second"]);
+  });
+
+  test("strips the optional space after data:", async () => {
+    const stream = makeStream(["data:nospace\n\ndata: withspace\n\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["nospace", "withspace"]);
+  });
+
+  test("skips comment lines", async () => {
+    const stream = makeStream([": this is a comment\ndata: payload\n\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["payload"]);
+  });
+
+  test("skips blank lines between events", async () => {
+    const stream = makeStream(["data: a\n\n\ndata: b\n\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["a", "b"]);
+  });
+
+  test("stops at [DONE] sentinel", async () => {
+    const stream = makeStream(["data: a\n\ndata: [DONE]\n\ndata: b\n\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["a"]);
+  });
+
+  test("handles CRLF line endings", async () => {
+    const stream = makeStream(["data: hello\r\n\r\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["hello"]);
+  });
+
+  test("handles data split across chunks", async () => {
+    // The data line is split mid-word across two chunks.
+    const stream = makeStream(["data: hel", "lo\n\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["hello"]);
+  });
+
+  test("handles newline split across chunks", async () => {
+    const stream = makeStream(["data: hello\n", "\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["hello"]);
+  });
+
+  test("handles many small chunks", async () => {
+    const stream = makeStream([
+      "d",
+      "a",
+      "t",
+      "a",
+      ":",
+      " ",
+      "t",
+      "o",
+      "k",
+      "e",
+      "n",
+      "\n",
+      "\n",
+    ]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["token"]);
+  });
+
+  test("ignores non-data field lines", async () => {
+    const stream = makeStream([
+      "event: content_block_delta\ndata: payload\n\n",
+    ]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["payload"]);
+  });
+
+  test("handles empty stream", async () => {
+    const stream = makeStream([]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual([]);
+  });
+
+  test("handles stream with only comments", async () => {
+    const stream = makeStream([": ping\n: ping\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual([]);
+  });
+
+  test("parses JSON data payloads", async () => {
+    const stream = makeStream(['data: {"type":"text","text":"hello"}\n\n']);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(['{"type":"text","text":"hello"}']);
+  });
+
+  test("handles multiple events in one chunk", async () => {
+    const stream = makeStream(["data: one\n\ndata: two\n\ndata: three\n\n"]);
+    const results = await collectSSE(stream);
+    expect(results).toEqual(["one", "two", "three"]);
+  });
+});

package/src/sse.ts

@@ -0,0 +1,76 @@
+// Server-Sent Events byte stream parser.
+//
+// Converts a ReadableStream<Uint8Array> (the raw HTTP response body) into an
+// AsyncIterable<string> of SSE data payloads. Each yielded string is the
+// value of one `data:` field. Comments (`:`) and blank-line separators are
+// consumed internally. The `[DONE]` sentinel (OpenAI convention) terminates
+// the iteration.
+//
+// The parser buffers incomplete lines across chunk boundaries so split chunks
+// are handled correctly regardless of where chunk boundaries fall.
+
+const decoder = new TextDecoder();
+
+export async function* parseSSE(
+  stream: ReadableStream<Uint8Array>,
+): AsyncIterable<string> {
+  const reader = stream.getReader();
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+
+      if (done) {
+        // Flush any remaining content in the buffer as a final line.
+        if (buffer.length > 0) {
+          const payload = extractDataPayload(buffer);
+          if (payload !== null) {
+            yield payload;
+          }
+        }
+        break;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // Process all complete lines (lines terminated by \n).
+      // A line ending in \r\n counts as terminated at the \n.
+      let newlineIndex: number;
+      while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+        const rawLine = buffer.slice(0, newlineIndex);
+        buffer = buffer.slice(newlineIndex + 1);
+
+        // Strip trailing \r for CRLF line endings.
+        const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+
+        // Blank lines and comment lines are ignored.
+        if (line === "" || line.startsWith(":")) {
+          continue;
+        }
+
+        const payload = extractDataPayload(line);
+        if (payload === null) {
+          continue;
+        }
+
+        if (payload === "[DONE]") {
+          return;
+        }
+
+        yield payload;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function extractDataPayload(line: string): string | null {
+  if (line.startsWith("data:")) {
+    // The spec allows an optional space after the colon.
+    const raw = line.slice(5);
+    return raw.startsWith(" ") ? raw.slice(1) : raw;
+  }
+  return null;
+}

package/src/state.ts

@@ -0,0 +1,135 @@
+// Reactor state management: turn history, async operations, usage tracking.
+//
+// The state object is the authoritative view the director receives on every
+// decision. It is mutable by the reactor only — the director receives a
+// snapshot so it cannot corrupt the reactor's internal state.
+//
+// (INFERENCE.md § Agent Reactor › Director Decision Function)
+
+import type {
+  ConversationTurn,
+  LastCycleSource,
+  PendingOperation,
+  TokenUsage,
+  ReactorState,
+} from "@intx/types/runtime";
+import type { GateSnapshot } from "./gates";
+
+export type ReactorStateManager = ReturnType<typeof createStateManager>;
+
+/**
+ * Creates a mutable state container. All mutations go through explicit methods;
+ * the `snapshot()` method produces an immutable view for the director.
+ */
+export function createStateManager(
+  sessionId: string,
+  initialTurns: ConversationTurn[],
+  initialOps: PendingOperation[],
+  initialUsage: TokenUsage,
+) {
+  let turns: ConversationTurn[] = [...initialTurns];
+  const pendingOperations = new Map<string, PendingOperation>(
+    initialOps.map((op) => [op.correlationId, op]),
+  );
+  const tokenUsage: TokenUsage = { ...initialUsage };
+  let lastCycleUsage: TokenUsage | null = null;
+  let lastCycleSource: LastCycleSource | null = null;
+  let activeGatesSnapshot: GateSnapshot[] = [];
+  const activeForks: { forkId: string; mode: "independent" | "child" }[] = [];
+
+  function appendTurn(msg: ConversationTurn): void {
+    turns.push(msg);
+  }
+
+  function replaceTurns(next: ConversationTurn[]): void {
+    turns = [...next];
+  }
+
+  function addPendingOperation(op: PendingOperation): void {
+    pendingOperations.set(op.correlationId, op);
+  }
+
+  function removePendingOperation(correlationId: string): void {
+    pendingOperations.delete(correlationId);
+  }
+
+  function accumUsage(usage: TokenUsage): void {
+    tokenUsage.input += usage.input;
+    tokenUsage.output += usage.output;
+    tokenUsage.cacheRead += usage.cacheRead;
+    tokenUsage.cacheWrite += usage.cacheWrite;
+    tokenUsage.thinking += usage.thinking;
+  }
+
+  function setLastCycleUsage(usage: TokenUsage): void {
+    lastCycleUsage = { ...usage };
+  }
+
+  function setLastCycleSource(source: LastCycleSource): void {
+    lastCycleSource = { ...source };
+  }
+
+  function setGatesSnapshot(gates: GateSnapshot[]): void {
+    activeGatesSnapshot = gates;
+  }
+
+  function addFork(forkId: string, mode: "independent" | "child"): void {
+    activeForks.push({ forkId, mode });
+  }
+
+  function removeFork(forkId: string): void {
+    const idx = activeForks.findIndex((f) => f.forkId === forkId);
+    if (idx !== -1) activeForks.splice(idx, 1);
+  }
+
+  function getTurns(): ConversationTurn[] {
+    return turns;
+  }
+
+  function getPendingOperations(): PendingOperation[] {
+    return Array.from(pendingOperations.values());
+  }
+
+  function getTokenUsage(): TokenUsage {
+    return { ...tokenUsage };
+  }
+
+  function snapshot(): ReactorState {
+    return {
+      sessionId,
+      turns: turns.map((m) => ({
+        ...m,
+        content: m.content.map((b) => structuredClone(b)),
+      })),
+      pendingOperations: Array.from(pendingOperations.values()).map((op) =>
+        structuredClone(op),
+      ),
+      activeGates: activeGatesSnapshot.map((g) => ({
+        gateId: g.gateId,
+        type: g.type,
+        timeoutAt: g.timeoutAt,
+      })),
+      activeForks: activeForks.map((f) => ({ ...f })),
+      tokenUsage: { ...tokenUsage },
+      lastCycleUsage: lastCycleUsage !== null ? { ...lastCycleUsage } : null,
+      lastCycleSource: lastCycleSource !== null ? { ...lastCycleSource } : null,
+    };
+  }
+
+  return {
+    appendTurn,
+    replaceTurns,
+    addPendingOperation,
+    removePendingOperation,
+    accumUsage,
+    setLastCycleUsage,
+    setLastCycleSource,
+    setGatesSnapshot,
+    addFork,
+    removeFork,
+    getTurns,
+    getPendingOperations,
+    getTokenUsage,
+    snapshot,
+  };
+}

package/src/transform.test.ts

@@ -0,0 +1,207 @@
+import { describe, test, expect } from "bun:test";
+import { transformMessages, createIDNormalizer } from "./transform";
+import type { ConversationTurn } from "@intx/types/runtime";
+
+describe("transformMessages", () => {
+  test("preserves messages when target model matches originating model", () => {
+    const messages: ConversationTurn[] = [
+      {
+        role: "assistant",
+        model: "claude-3-5-sonnet",
+        content: [
+          { type: "thinking", thinking: "Let me think..." },
+          { type: "text", text: "Here is the answer." },
+        ],
+        timestamp: 1000,
+      },
+    ];
+
+    const result = transformMessages(messages, {
+      targetModel: "claude-3-5-sonnet",
+      keepThinkingForSameModel: true,
+    });
+
+    expect(result).toHaveLength(1);
+    const firstMsg = result[0];
+    expect(firstMsg?.content).toHaveLength(2);
+    expect(firstMsg?.content[0]?.type).toBe("thinking");
+  });
+
+  test("strips thinking blocks when replaying to a different model", () => {
+    const messages: ConversationTurn[] = [
+      {
+        role: "assistant",
+        model: "claude-3-5-sonnet",
+        content: [
+          { type: "thinking", thinking: "Some reasoning..." },
+          { type: "text", text: "Answer." },
+        ],
+        timestamp: 1000,
+      },
+    ];
+
+    const result = transformMessages(messages, {
+      targetModel: "gpt-4o",
+    });
+
+    expect(result).toHaveLength(1);
+    const firstMsg = result[0];
+    expect(firstMsg?.content).toHaveLength(1);
+    expect(firstMsg?.content[0]?.type).toBe("text");
+  });
+
+  test("strips thinking blocks when keepThinkingForSameModel is false", () => {
+    const messages: ConversationTurn[] = [
+      {
+        role: "assistant",
+        model: "claude-3-5-sonnet",
+        content: [
+          { type: "thinking", thinking: "Reasoning..." },
+          { type: "text", text: "Answer." },
+        ],
+        timestamp: 1000,
+      },
+    ];
+
+    const result = transformMessages(messages, {
+      targetModel: "claude-3-5-sonnet",
+      keepThinkingForSameModel: false,
+    });
+
+    const firstMsg = result[0];
+    expect(firstMsg?.content).toHaveLength(1);
+    expect(firstMsg?.content[0]?.type).toBe("text");
+  });
+
+  test("injects synthetic tool results for orphaned tool calls", () => {
+    const messages: ConversationTurn[] = [
+      {
+        role: "user",
+        content: [{ type: "text", text: "Do something." }],
+        timestamp: 1000,
+      },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool_call",
+            id: "call_1",
+            name: "read_file",
+            arguments: { path: "/tmp/foo" },
+          },
+        ],
+        timestamp: 1000,
+      },
+      // No tool result follows — the conversation was interrupted.
+    ];
+
+    const result = transformMessages(messages, { targetModel: "gpt-4o" });
+
+    // Should inject a synthetic tool result message.
+    expect(result).toHaveLength(3);
+    const injected = result[2];
+    expect(injected?.role).toBe("user");
+    expect(injected?.content[0]?.type).toBe("tool_result");
+    const toolResult = injected?.content[0];
+    if (toolResult?.type === "tool_result") {
+      expect(toolResult.callId).toBe("call_1");
+      expect(toolResult.isError).toBe(true);
+    }
+  });
+
+  test("does not inject when tool results are present", () => {
+    const messages: ConversationTurn[] = [
+      {
+        role: "user",
+        content: [{ type: "text", text: "Do something." }],
+        timestamp: 1000,
+      },
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool_call",
+            id: "call_1",
+            name: "read_file",
+            arguments: { path: "/tmp/foo" },
+          },
+        ],
+        timestamp: 1000,
+      },
+      {
+        role: "user",
+        content: [
+          {
+            type: "tool_result",
+            callId: "call_1",
+            content: [{ type: "text", text: "file contents" }],
+          },
+        ],
+        timestamp: 1000,
+      },
+    ];
+
+    const result = transformMessages(messages, { targetModel: "gpt-4o" });
+    expect(result).toHaveLength(3);
+  });
+
+  test("preserves user and system messages unchanged", () => {
+    const messages: ConversationTurn[] = [
+      {
+        role: "system",
+        content: [{ type: "text", text: "You are helpful." }],
+        timestamp: 1000,
+      },
+      {
+        role: "user",
+        content: [{ type: "text", text: "Hello." }],
+        timestamp: 1000,
+      },
+    ];
+
+    const result = transformMessages(messages, { targetModel: "gpt-4o" });
+    expect(result).toHaveLength(2);
+    expect(result[0]).toEqual(messages[0]);
+    expect(result[1]).toEqual(messages[1]);
+  });
+});
+
+describe("createIDNormalizer", () => {
+  test("assigns stable portable IDs", () => {
+    const norm = createIDNormalizer();
+    const id1 = norm.normalize(
+      "call_abc_very_long_id_from_openai_responses_api",
+    );
+    const id2 = norm.normalize(
+      "call_abc_very_long_id_from_openai_responses_api",
+    );
+    expect(id1).toBe(id2);
+    expect(id1.startsWith("tc_")).toBe(true);
+  });
+
+  test("assigns different IDs to different provider IDs", () => {
+    const norm = createIDNormalizer();
+    const id1 = norm.normalize("toolu_01A");
+    const id2 = norm.normalize("toolu_02B");
+    expect(id1).not.toBe(id2);
+  });
+
+  test("resolves a portable ID back to the provider ID", () => {
+    const norm = createIDNormalizer();
+    const providerId = "toolu_01AbCdEfGhIjKlMnOpQrStUvWx";
+    const portable = norm.normalize(providerId);
+    expect(norm.resolve(portable)).toBe(providerId);
+  });
+
+  test("resolve returns undefined for unknown portable ID", () => {
+    const norm = createIDNormalizer();
+    expect(norm.resolve("tc_unknown")).toBeUndefined();
+  });
+
+  test("IDs are monotonically increasing", () => {
+    const norm = createIDNormalizer();
+    const ids = ["a", "b", "c"].map((x) => norm.normalize(x));
+    // All different.
+    expect(new Set(ids).size).toBe(3);
+  });
+});