@intx/inference 0.1.2 → 0.2.2

package/dist/transforms/size-cap.js

@@ -0,0 +1,80 @@
+// Tool-result size-cap transform.
+//
+// When a tool result's content exceeds `maxChars`, the full bytes are spilled
+// via `contextStore.writeBlob` and the inline result is replaced with the
+// first `maxChars` characters plus a marker pointing at the spill via a
+// `tool-output:///{callId}` URI. The agent's `read_file` tool resolves the
+// URI through its `BlobReader` capability.
+//
+// Within-cap results pass through unchanged (no blob is written) but still
+// produce a `TransformRecord` so the manifest captures every invocation.
+const SIZE_CAP_VERSION = "1";
+const SIZE_CAP_NAME = "size-cap";
+/**
+ * Create a `ToolResultTransform` that caps inline tool result content at
+ * `maxChars` characters. Oversized results are spilled to the context store
+ * via `writeBlob` and the inline content becomes a truncated marker
+ * referencing the spill by `tool-output:///{callId}` URI.
+ */
+export function createSizeCapTransform(options) {
+    const { maxChars, contextStore } = options;
+    if (!Number.isFinite(maxChars) || maxChars <= 0) {
+        throw new Error(`createSizeCapTransform: maxChars must be a positive finite number, got ${String(maxChars)}`);
+    }
+    return {
+        name: SIZE_CAP_NAME,
+        version: SIZE_CAP_VERSION,
+        async apply(input, _ctx) {
+            const { call, result } = input;
+            const text = typeof result.content === "string"
+                ? result.content
+                : JSON.stringify(result.content);
+            if (text.length <= maxChars) {
+                return {
+                    output: result,
+                    record: {
+                        strategy: SIZE_CAP_NAME,
+                        version: SIZE_CAP_VERSION,
+                        parameters: { maxChars },
+                        reason: "within-cap",
+                        decisions: { callId: call.id, length: text.length },
+                    },
+                };
+            }
+            const omitted = text.length - maxChars;
+            const kept = text.slice(0, maxChars);
+            const spillURI = `tool-output:///${call.id}`;
+            const marker = `${kept}\n[Tool output truncated: omitted ${String(omitted)} chars. ` +
+                `Full output available at ${spillURI} -- use read_file with that URI to see the rest.]`;
+            const bytes = new TextEncoder().encode(text);
+            await contextStore.writeBlob(call.id, bytes, "text/plain");
+            const output = {
+                ...result,
+                content: marker,
+            };
+            return {
+                output,
+                record: {
+                    strategy: SIZE_CAP_NAME,
+                    version: SIZE_CAP_VERSION,
+                    parameters: { maxChars },
+                    reason: "exceeded-cap",
+                    decisions: {
+                        callId: call.id,
+                        originalLength: text.length,
+                        kept: maxChars,
+                        spillKey: call.id,
+                        spillURI,
+                    },
+                },
+                blobs: [
+                    {
+                        key: call.id,
+                        bytes,
+                        contentType: "text/plain",
+                    },
+                ],
+            };
+        },
+    };
+}

package/dist/turns.d.ts

@@ -0,0 +1,21 @@
+import type { ConversationTurn, ContentBlock, AssistantTurn, InboundMessage, ToolCall, ToolResult } from "@intx/types/runtime";
+export type { ConversationTurn, ContentBlock, AssistantTurn };
+export type { ToolCall, ToolResult };
+export declare function createInboundTurn(message: InboundMessage): ConversationTurn | null;
+/**
+ * Assert that a prompt's tool_call / tool_result blocks are structurally
+ * well-formed before it is sent to a provider.
+ *
+ * Throws if a tool_call id is emitted twice, if a tool_result references a
+ * callId with no preceding tool_call, or if two tool_result blocks answer the
+ * same callId. None of these are valid in a coherent tool conversation — a
+ * tool call has exactly one result. Catching it here surfaces the corruption
+ * as an internal error at the assembly boundary, with the offending id and
+ * turn index, instead of an opaque downstream provider rejection.
+ *
+ * This deliberately does NOT require every tool_call to have a result: an
+ * unanswered tool_call is left legitimately by an after-inference halt/abort
+ * and is repaired downstream for cross-provider replay.
+ */
+export declare function assertWellFormedToolSequence(turns: ConversationTurn[]): void;
+export declare function createToolResultTurn(results: ToolResult[]): ConversationTurn;

package/dist/turns.js

@@ -0,0 +1,135 @@
+import { attachmentCategory, base64Encode } from "@intx/types";
+import { getLogger } from "@intx/log";
+const logger = getLogger(["interchange", "inference", "turns"]);
+/**
+ * Map a received attachment to a model ContentBlock.
+ *
+ * The dispatch uses two policies that look unified but are not, and must
+ * stay distinct:
+ *   - major-type dispatch for image/*, video/*, audio/* → the matching block;
+ *   - allowlist-category dispatch for the document category
+ *     (application/pdf, application/json, text/plain, text/csv,
+ *     text/markdown) → DocumentBlock.
+ * Do NOT collapse this into "always dispatch by major type": that would
+ * route text/plain to a text block instead of DocumentBlock.
+ *
+ * This function is total — it never throws. The hub route allowlist only
+ * guards the local user-upload path; inbound attachments arrive from remote
+ * senders via fetchFull and are not subtype-filtered here (provider adapters
+ * are the contract layer that rejects unsupported media at marshal time, per
+ * INTERCHANGE message design). Any major-type media is therefore passed
+ * through to the adapter. A type that maps to no block at all (e.g. an
+ * archive) degrades to a visible text marker rather than throwing: throwing
+ * here would propagate into the reactor's ungoverned delivery path and let a
+ * single malformed remote attachment tear down the session.
+ */
+function attachmentToContentBlock(att) {
+    const majorType = att.contentType.split("/")[0];
+    if (majorType === "image" ||
+        majorType === "video" ||
+        majorType === "audio" ||
+        attachmentCategory(att.contentType) === "document") {
+        const source = {
+            kind: "base64",
+            mimeType: att.contentType,
+            data: base64Encode(att.data),
+        };
+        if (majorType === "image")
+            return { type: "image", source };
+        if (majorType === "video")
+            return { type: "video", source };
+        if (majorType === "audio")
+            return { type: "audio", source };
+        return { type: "document", source };
+    }
+    logger.warn `Unsupported attachment content type ${att.contentType}; surfacing as a text marker`;
+    return {
+        type: "text",
+        text: `[Unsupported attachment: ${att.name} (${att.contentType})]`,
+    };
+}
+export function createInboundTurn(message) {
+    const content = message.content ?? "";
+    const attachments = message.attachments ?? [];
+    if (content.length === 0 && attachments.length === 0)
+        return null;
+    const blocks = [];
+    if (content.length > 0) {
+        const { from, subject } = message.headers;
+        const envelope = [];
+        if (from.length > 0)
+            envelope.push(`[From: ${from}]`);
+        if (subject !== undefined && subject.length > 0) {
+            envelope.push(`[Subject: ${subject}]`);
+        }
+        const text = envelope.length > 0 ? `${envelope.join("\n")}\n\n${content}` : content;
+        blocks.push({ type: "text", text });
+    }
+    for (const att of attachments) {
+        blocks.push(attachmentToContentBlock(att));
+    }
+    return {
+        role: "user",
+        content: blocks,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Assert that a prompt's tool_call / tool_result blocks are structurally
+ * well-formed before it is sent to a provider.
+ *
+ * Throws if a tool_call id is emitted twice, if a tool_result references a
+ * callId with no preceding tool_call, or if two tool_result blocks answer the
+ * same callId. None of these are valid in a coherent tool conversation — a
+ * tool call has exactly one result. Catching it here surfaces the corruption
+ * as an internal error at the assembly boundary, with the offending id and
+ * turn index, instead of an opaque downstream provider rejection.
+ *
+ * This deliberately does NOT require every tool_call to have a result: an
+ * unanswered tool_call is left legitimately by an after-inference halt/abort
+ * and is repaired downstream for cross-provider replay.
+ */
+export function assertWellFormedToolSequence(turns) {
+    const calledIds = new Set();
+    const answeredIds = new Set();
+    for (let turnIndex = 0; turnIndex < turns.length; turnIndex++) {
+        const turn = turns[turnIndex];
+        if (turn === undefined)
+            continue;
+        for (const block of turn.content) {
+            if (block.type === "tool_call") {
+                if (calledIds.has(block.id)) {
+                    throw new Error(`Malformed tool sequence: duplicate tool_call id ${JSON.stringify(block.id)} at turn ${String(turnIndex)}`);
+                }
+                calledIds.add(block.id);
+            }
+            else if (block.type === "tool_result") {
+                if (!calledIds.has(block.callId)) {
+                    throw new Error(`Malformed tool sequence: tool_result for ${JSON.stringify(block.callId)} at turn ${String(turnIndex)} has no preceding tool_call`);
+                }
+                if (answeredIds.has(block.callId)) {
+                    throw new Error(`Malformed tool sequence: duplicate tool_result for ${JSON.stringify(block.callId)} at turn ${String(turnIndex)}`);
+                }
+                answeredIds.add(block.callId);
+            }
+        }
+    }
+}
+export function createToolResultTurn(results) {
+    const blocks = results.map((r) => {
+        const raw = typeof r.content === "string" ? r.content : JSON.stringify(r.content);
+        const block = {
+            type: "tool_result",
+            callId: r.callId,
+            content: [{ type: "text", text: raw }],
+        };
+        if (r.detail !== undefined) {
+            block.detail = r.detail;
+        }
+        if (r.isError !== undefined) {
+            block.isError = r.isError;
+        }
+        return block;
+    });
+    return { role: "user", content: blocks, timestamp: Date.now() };
+}

package/package.json

@@ -1,20 +1,35 @@
 {
   "name": "@intx/inference",
-  "version": "0.1.2",
+  "version": "0.2.2",
   "license": "LGPL-2.1-only",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "intx-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./providers": {
+      "intx-src": "./src/providers/index.ts",
+      "types": "./dist/providers/index.d.ts",
+      "default": "./dist/providers/index.js"
     }
   },
   "dependencies": {
-    "@intx/log": "0.0.0",
-    "@intx/types": "0.0.0",
+    "@intx/log": "0.2.2",
+    "@intx/types": "0.2.2",
     "arktype": "^2.1.29"
   },
   "devDependencies": {
-    "@intx/mime": "0.0.0"
+    "@intx/mime": "0.2.2"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/actions.ts

@@ -1,245 +0,0 @@
-// 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

@@ -1,57 +0,0 @@
-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;
-};