@intx/inference 0.1.2

package/README.md

@@ -0,0 +1,46 @@
+# @intx/inference
+
+Provider-agnostic inference runtime. Adapters for Anthropic,
+OpenAI-compatible relays (including OpenCode Zen), and Google
+GenAI; SSE parsing; retry and error classification; message
+transforms; and the reactor harness that drives a turn from
+prompt to settled tool calls.
+
+Consumed by `@intx/harness`, which composes the reactor with tool
+runners, directors, and runtime capabilities.
+
+```ts
+import { createReactorAssembly, createDefaultDirector } from "@intx/inference";
+
+const director = createDefaultDirector(
+  systemPrompt,
+  toolDefinitions, // ToolDefinition[] — the tool surface advertised to the model
+  policy,
+);
+
+const assembly = createReactorAssembly({
+  sessionId,
+  director,
+  source, // InferenceSource: id, provider, model, apiKey, baseURL
+  toolRunner, // ToolRunner — dispatches the tool calls the director emits
+  contextStore,
+  onEvent: (event) => {
+    // event: ReactorEmittedEvent — persist or forward
+  },
+});
+
+assembly.reactor.start();
+```
+
+Provider selection is driven by `source.provider`; the assembly
+resolves the matching adapter internally. `ReactorAssemblyConfig`
+in `src/assembly.ts` documents the optional fields (`authorize`,
+`auditStore`, transforms, compactors, correlation, gate
+timeouts).
+
+The package is the lower half of the agent stack: it knows how to
+talk to model providers, how to drive a multi-turn exchange to
+completion, and how to compose extensions (gates, audit,
+correlation, authz) into the reactor pipeline. The higher-level
+agent surface — config validation, tool runners, deploy trees,
+runtime capabilities — lives in `@intx/harness`.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@intx/inference",
+  "version": "0.1.2",
+  "license": "LGPL-2.1-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@intx/log": "0.0.0",
+    "@intx/types": "0.0.0",
+    "arktype": "^2.1.29"
+  },
+  "devDependencies": {
+    "@intx/mime": "0.0.0"
+  }
+}

package/src/actions.ts

@@ -0,0 +1,245 @@
+// Action types and validation for the agent reactor.
+//
+// The reactor validates the set of actions returned by the director before
+// executing any of them. Invalid combinations produce a reactor.error rather
+// than partial execution — the reactor does not guess intent.
+//
+// Validation rules (INFERENCE.md § Action Validation):
+// - At most one `infer` action.
+// - At most one `done` action.
+// - At most one `reply` action.
+// - `infer` + `done` together is invalid.
+// - `reply` + `infer` together is invalid.
+// - `reply` + `execute_tools` together is invalid.
+// - `reply` + `done` together is invalid.
+// - `reply` + `suspend` together is invalid.
+// - `wait` + `infer` together is invalid.
+// - `wait` + `execute_tools` together is invalid.
+// - `wait` + `suspend` together is invalid.
+// - `wait` + `reply` together is invalid.
+// - `wait` + `done` together is invalid.
+// - `suspend` cannot appear alongside `infer` or `execute_tools`.
+// - `fork` is composable — may appear alongside any other action.
+// - At most one `checkpoint` action; composable with any other action.
+// - At most one `wait` action.
+// - Multiple `execute_tools` are merged into a single parallel batch.
+// - `emit` is always valid and composable.
+// - At most one `compact` action; composable with `checkpoint`, `emit`, and
+//   `fork`. Not composable with `infer`, `execute_tools`, `reply`, `suspend`,
+//   `wait`, or `done`. Context-overflow recovery runs compaction in its own
+//   cycle and re-infers on the next director invocation.
+
+import type { ReactorAction, ToolCall } from "@intx/types/runtime";
+
+export type ValidationResult =
+  | { ok: true; normalized: ReactorAction[] }
+  | { ok: false; error: string };
+
+/**
+ * Validate and normalize a set of actions returned by the director.
+ *
+ * On success, returns the normalized action list with multiple `execute_tools`
+ * collapsed into a single batched action. On failure, returns a diagnostic
+ * error string.
+ */
+export function validateActions(
+  actions: ReactorAction | ReactorAction[],
+): ValidationResult {
+  const list = Array.isArray(actions) ? actions : [actions];
+
+  // An empty action list means "no-op, keep waiting for the next event."
+  // This is valid — the reactor loop continues to waitForEvent().
+  if (list.length === 0) {
+    return { ok: true, normalized: [] };
+  }
+
+  const inferActions = list.filter((a) => a.type === "infer");
+  const doneActions = list.filter((a) => a.type === "done");
+  const replyActions = list.filter((a) => a.type === "reply");
+  const suspendActions = list.filter((a) => a.type === "suspend");
+  const executeActions = list.filter(
+    (a): a is Extract<ReactorAction, { type: "execute_tools" }> =>
+      a.type === "execute_tools",
+  );
+  const waitActions = list.filter((a) => a.type === "wait");
+  const forkActions = list.filter((a) => a.type === "fork");
+  const emitActions = list.filter((a) => a.type === "emit");
+  const checkpointActions = list.filter((a) => a.type === "checkpoint");
+  const compactActions = list.filter((a) => a.type === "compact");
+
+  if (checkpointActions.length > 1) {
+    return {
+      ok: false,
+      error: "Multiple checkpoint actions are not allowed",
+    };
+  }
+
+  if (inferActions.length > 1) {
+    return { ok: false, error: "Multiple infer actions are not allowed" };
+  }
+
+  if (doneActions.length > 1) {
+    return { ok: false, error: "Multiple done actions are not allowed" };
+  }
+
+  if (inferActions.length > 0 && doneActions.length > 0) {
+    return { ok: false, error: "infer and done cannot appear together" };
+  }
+
+  if (replyActions.length > 1) {
+    return { ok: false, error: "Multiple reply actions are not allowed" };
+  }
+
+  if (replyActions.length > 0 && inferActions.length > 0) {
+    return { ok: false, error: "reply and infer cannot appear together" };
+  }
+
+  if (replyActions.length > 0 && executeActions.length > 0) {
+    return {
+      ok: false,
+      error: "reply and execute_tools cannot appear together",
+    };
+  }
+
+  if (replyActions.length > 0 && doneActions.length > 0) {
+    return { ok: false, error: "reply and done cannot appear together" };
+  }
+
+  if (replyActions.length > 0 && suspendActions.length > 0) {
+    return { ok: false, error: "reply and suspend cannot appear together" };
+  }
+
+  if (suspendActions.length > 0) {
+    if (inferActions.length > 0) {
+      return {
+        ok: false,
+        error: "suspend cannot appear alongside infer",
+      };
+    }
+    if (executeActions.length > 0) {
+      return {
+        ok: false,
+        error: "suspend cannot appear alongside execute_tools",
+      };
+    }
+    if (suspendActions.length > 1) {
+      return { ok: false, error: "Multiple suspend actions are not allowed" };
+    }
+  }
+
+  if (waitActions.length > 1) {
+    return { ok: false, error: "Multiple wait actions are not allowed" };
+  }
+
+  if (waitActions.length > 0) {
+    if (inferActions.length > 0) {
+      return { ok: false, error: "wait and infer cannot appear together" };
+    }
+    if (executeActions.length > 0) {
+      return {
+        ok: false,
+        error: "wait and execute_tools cannot appear together",
+      };
+    }
+    if (suspendActions.length > 0) {
+      return { ok: false, error: "wait and suspend cannot appear together" };
+    }
+    if (replyActions.length > 0) {
+      return { ok: false, error: "wait and reply cannot appear together" };
+    }
+    if (doneActions.length > 0) {
+      return { ok: false, error: "wait and done cannot appear together" };
+    }
+  }
+
+  if (compactActions.length > 1) {
+    return { ok: false, error: "Multiple compact actions are not allowed" };
+  }
+
+  if (compactActions.length > 0) {
+    if (inferActions.length > 0) {
+      return { ok: false, error: "compact and infer cannot appear together" };
+    }
+    if (executeActions.length > 0) {
+      return {
+        ok: false,
+        error: "compact and execute_tools cannot appear together",
+      };
+    }
+    if (replyActions.length > 0) {
+      return { ok: false, error: "compact and reply cannot appear together" };
+    }
+    if (suspendActions.length > 0) {
+      return { ok: false, error: "compact and suspend cannot appear together" };
+    }
+    if (waitActions.length > 0) {
+      return { ok: false, error: "compact and wait cannot appear together" };
+    }
+    if (doneActions.length > 0) {
+      return { ok: false, error: "compact and done cannot appear together" };
+    }
+  }
+
+  // Verify fork actions have unique IDs.
+  const forkIds = forkActions.map(
+    (a) => (a as Extract<ReactorAction, { type: "fork" }>).forkId,
+  );
+  const uniqueForkIds = new Set(forkIds);
+  if (forkIds.length !== uniqueForkIds.size) {
+    return { ok: false, error: "Duplicate fork IDs in action list" };
+  }
+
+  // Build normalized list: collapse execute_tools into one parallel batch.
+  const normalized: ReactorAction[] = [];
+
+  for (const a of checkpointActions) {
+    normalized.push(a);
+  }
+
+  for (const a of emitActions) {
+    normalized.push(a);
+  }
+
+  for (const a of forkActions) {
+    normalized.push(a);
+  }
+
+  for (const a of compactActions) {
+    normalized.push(a);
+  }
+
+  if (executeActions.length > 0) {
+    const merged: ToolCall[] = executeActions.flatMap((a) => a.calls);
+    const allAddToHistory = executeActions.every(
+      (a) => a.addToHistory !== false,
+    );
+    normalized.push({
+      type: "execute_tools",
+      calls: merged,
+      parallel: true,
+      ...(!allAddToHistory ? { addToHistory: false } : {}),
+    });
+  }
+
+  for (const a of replyActions) {
+    normalized.push(a);
+  }
+
+  for (const a of inferActions) {
+    normalized.push(a);
+  }
+
+  for (const a of suspendActions) {
+    normalized.push(a);
+  }
+
+  for (const a of waitActions) {
+    normalized.push(a);
+  }
+
+  for (const a of doneActions) {
+    normalized.push(a);
+  }
+
+  return { ok: true, normalized };
+}

package/src/adapter.ts

@@ -0,0 +1,57 @@
+import type {
+  ConversationTurn,
+  InferenceEvent,
+  InferenceOptions,
+} from "@intx/types/runtime";
+
+// The request shape the harness passes to fetch.
+export type BuiltRequest = {
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+};
+
+// A request builder takes the internal message format and produces a
+// provider-specific HTTP request. Pure function — no state, no side effects.
+export type RequestBuilder = (
+  messages: ConversationTurn[],
+  model: string,
+  options: InferenceOptions,
+) => BuiltRequest;
+
+// A response parser converts one SSE data payload string into zero or more
+// internal inference events. May close over per-request state (e.g., for
+// correlating content block indices with tool call IDs). Each adapter
+// instance is created per inference call, so state does not leak across
+// requests.
+//
+// The parser may return an empty array for events it doesn't care about
+// (e.g., Anthropic's ping events). It MAY throw `ProtocolMismatchError`
+// when the upstream chunk violates the provider's protocol (malformed
+// JSON, schema validation failure, out-of-order events); the harness's
+// stream-error catch converts that into an `inference.error` with
+// category `"protocol_mismatch"` via `classifyStreamError`. No other
+// throw type is permitted, and adapter-returned `inference.error` or
+// `inference.done` events are silently dropped — the harness owns
+// emission of those terminal types and the only path through which
+// adapter-detected failures can surface is `ProtocolMismatchError`.
+export type ResponseParser = (sseData: string) => InferenceEvent[];
+
+// An adapter pairs a request builder with a response parser. Registration
+// is a map keyed by provider identifier — no class hierarchy required.
+
+// Extracts a retry delay from provider-specific response headers on a 429.
+// Returns milliseconds to wait, or undefined if no retry info is available.
+export type RetryAfterExtractor = (headers: Headers) => number | undefined;
+
+// Extracts a pacing delay from response headers on ANY response (including
+// success). Checks remaining rate limit capacity and returns how long to
+// wait before the next request, or undefined if no pacing is needed.
+export type PacingExtractor = (headers: Headers) => number | undefined;
+
+export type ProviderAdapter = {
+  buildRequest: RequestBuilder;
+  parseResponse: ResponseParser;
+  extractRetryAfterMs?: RetryAfterExtractor;
+  extractPacingDelayMs?: PacingExtractor;
+};