@intx/inference 0.1.2 → 0.3.0

package/src/assembly.ts

@@ -1,250 +0,0 @@
-// Reactor assembly helper.
-//
-// `createReactorAssembly` is the canonical way to construct a reactor when the
-// caller wants the standard wiring: a default size-cap tool-result transform,
-// authz as a before-tool extension, an audit collector that flushes at
-// checkpoint and shutdown boundaries, and a `BlobReader` over the supplied
-// context store. Future reactor consumers (the harness today; in-process agent
-// runtimes tomorrow) should use this helper rather than calling `createReactor`
-// directly so the wiring stays consistent across composition points.
-
-import { getLogger } from "@intx/log";
-import {
-  createBlobReader,
-  type BlobReader,
-  type AuditStore,
-  type BeforeToolExtension,
-  type Compactor,
-  type ContextStore,
-  type ContextTransform,
-  type InferenceSource,
-  type ReactorDirector,
-  type ToolResultTransform,
-  type ToolRunner,
-} from "@intx/types/runtime";
-
-import { createAuditCollector, type AuditCollector } from "./audit-collector";
-import {
-  createAuthzExtension,
-  type AuthzExtensionOptions,
-} from "./authz-extension";
-import type { CorrelationValidator } from "./correlation";
-import { createDefaultDependencies, type Dependencies } from "./harness";
-import {
-  createReactor,
-  type Reactor,
-  type ReactorConfig,
-  type ReactorEmittedEvent,
-} from "./reactor";
-import { createSizeCapTransform } from "./transforms";
-
-const logger = getLogger(["interchange", "assembly"]);
-
-const DEFAULT_SIZE_CAP_MAX_CHARS = 10_000;
-
-/**
- * Configuration for `createReactorAssembly`. Required fields mirror
- * `ReactorConfig`. Optional fields toggle the composed extensions: the helper
- * builds an authz before-tool extension when `authorize` is supplied, builds
- * and wires an audit collector when `auditStore` is supplied, and always
- * prepends a default size-cap tool-result transform.
- *
- * The helper does NOT wrap the supplied `contextStore`; callers that need
- * additional behavior (the harness wraps for connector-thread state) layer
- * that on themselves before passing the store in.
- */
-export type ReactorAssemblyConfig = {
-  sessionId: string;
-  director: ReactorDirector;
-  source: InferenceSource;
-  toolRunner: ToolRunner;
-  contextStore: ContextStore;
-  onEvent: (event: ReactorEmittedEvent) => void;
-
-  authorize?: AuthzExtensionOptions["authorize"];
-  auditStore?: AuditStore;
-  beforeToolExtensions?: BeforeToolExtension[];
-  toolResultTransforms?: ToolResultTransform[];
-  contextTransforms?: ContextTransform[];
-  compactors?: Record<string, Compactor>;
-  sizeCapMaxChars?: number;
-
-  afterCheckpoint?: () => Promise<void>;
-  onShutdown?: () => Promise<void>;
-
-  deps?: Dependencies;
-  correlationValidator?: CorrelationValidator;
-  inferenceRunner?: ReactorConfig["inferenceRunner"];
-  gateTimeout?: number;
-  shutdownTimeoutMs?: number;
-};
-
-/**
- * Output of `createReactorAssembly`. The `reactor` is started by the caller as
- * usual. `blobReader` is exposed so the caller can pass it to tool factories
- * that resolve `tool-output:///{callId}` URIs against the same context store
- * the reactor commits to. `auditCollector` is `undefined` when no `auditStore`
- * was supplied.
- */
-export type ReactorAssembly = {
-  reactor: Reactor;
-  blobReader: BlobReader;
-  auditCollector: AuditCollector | undefined;
-};
-
-/**
- * Build the standard reactor wiring. This is the canonical reactor-assembly
- * path: any consumer that needs the default size-cap transform, authz, audit
- * collection, and blob reader should call this helper instead of constructing
- * a `ReactorConfig` by hand. Direct `createReactor` use is reserved for
- * reactor-internal tests and any future consumer that genuinely needs a
- * different composition.
- */
-export function createReactorAssembly(
-  config: ReactorAssemblyConfig,
-): ReactorAssembly {
-  const {
-    sessionId,
-    director,
-    source,
-    toolRunner,
-    contextStore,
-    onEvent,
-    authorize,
-    auditStore,
-    beforeToolExtensions: callerBeforeToolExtensions,
-    toolResultTransforms: callerToolResultTransforms,
-    contextTransforms,
-    compactors,
-    sizeCapMaxChars,
-    afterCheckpoint: callerAfterCheckpoint,
-    onShutdown: callerOnShutdown,
-    deps,
-    correlationValidator,
-    inferenceRunner,
-    gateTimeout,
-    shutdownTimeoutMs,
-  } = config;
-
-  // Audit collector is created up-front so the authz extension can route its
-  // decisions through `onDecision`. When no auditStore is supplied, no
-  // collector is created and authz runs without decision recording.
-  const auditCollector: AuditCollector | undefined =
-    auditStore !== undefined ? createAuditCollector(sessionId) : undefined;
-
-  // When an audit collector is present, intercept the reactor's event stream
-  // to feed it tool.start / tool.done events (the collector correlates these
-  // with authz decisions by callId). message.received is reactor-internal and
-  // is forwarded to the caller but not to the collector. Without a collector,
-  // the caller's onEvent is used directly.
-  const composedOnEvent =
-    auditCollector !== undefined
-      ? (event: ReactorEmittedEvent) => {
-          if (event.type !== "message.received") {
-            auditCollector.onEvent(event);
-          }
-          onEvent(event);
-        }
-      : onEvent;
-
-  // Authz is composed in front of any caller-supplied before-tool extensions
-  // so policy enforcement runs first. Without authz, the caller's list (if
-  // any) is passed through unchanged.
-  const authzExtension =
-    authorize !== undefined
-      ? createAuthzExtension({
-          authorize,
-          ...(auditCollector !== undefined
-            ? { onDecision: (d) => auditCollector.onDecision(d) }
-            : {}),
-        })
-      : undefined;
-
-  const composedBeforeToolExtensions: BeforeToolExtension[] | undefined =
-    authzExtension !== undefined
-      ? [authzExtension, ...(callerBeforeToolExtensions ?? [])]
-      : callerBeforeToolExtensions;
-
-  // The size-cap transform is always prepended so oversized payloads spill
-  // before any caller transform sees them. Caller transforms run after and
-  // can rely on the inline content already being bounded.
-  const sizeCapTransform = createSizeCapTransform({
-    maxChars: sizeCapMaxChars ?? DEFAULT_SIZE_CAP_MAX_CHARS,
-    contextStore,
-  });
-  const composedToolResultTransforms: ToolResultTransform[] = [
-    sizeCapTransform,
-    ...(callerToolResultTransforms ?? []),
-  ];
-
-  // Audit flush wraps the caller's lifecycle hooks: the helper's flush runs
-  // first so the records produced by the just-completed cycle are persisted
-  // before the caller's hook observes the checkpoint or shutdown boundary.
-  async function flushAudit(): Promise<void> {
-    if (auditCollector === undefined || auditStore === undefined) return;
-    const records = auditCollector.flush();
-    if (records.length > 0) {
-      await auditStore.commitAudit(records);
-    }
-  }
-
-  const composedAfterCheckpoint: (() => Promise<void>) | undefined =
-    auditCollector !== undefined
-      ? async () => {
-          await flushAudit();
-          if (callerAfterCheckpoint !== undefined) {
-            await callerAfterCheckpoint();
-          }
-        }
-      : callerAfterCheckpoint;
-
-  const composedOnShutdown: (() => Promise<void>) | undefined =
-    auditCollector !== undefined
-      ? async () => {
-          const inflight = auditCollector.pending();
-          if (inflight > 0) {
-            logger.warn`${inflight} audit records in flight at shutdown, these tool calls will not be recorded`;
-          }
-          await flushAudit();
-          if (callerOnShutdown !== undefined) {
-            await callerOnShutdown();
-          }
-        }
-      : callerOnShutdown;
-
-  // ReactorConfig.deps is required; default to createDefaultDependencies()
-  // when the caller did not supply one so we never pass `undefined`.
-  const resolvedDeps: Dependencies = deps ?? createDefaultDependencies();
-
-  // exactOptionalPropertyTypes is on: only set optional keys when defined.
-  const reactorConfig: ReactorConfig = {
-    sessionId,
-    director,
-    source,
-    toolRunner,
-    contextStore,
-    onEvent: composedOnEvent,
-    deps: resolvedDeps,
-    toolResultTransforms: composedToolResultTransforms,
-    ...(composedBeforeToolExtensions !== undefined
-      ? { beforeToolExtensions: composedBeforeToolExtensions }
-      : {}),
-    ...(contextTransforms !== undefined ? { contextTransforms } : {}),
-    ...(compactors !== undefined ? { compactors } : {}),
-    ...(composedAfterCheckpoint !== undefined
-      ? { afterCheckpoint: composedAfterCheckpoint }
-      : {}),
-    ...(composedOnShutdown !== undefined
-      ? { onShutdown: composedOnShutdown }
-      : {}),
-    ...(correlationValidator !== undefined ? { correlationValidator } : {}),
-    ...(inferenceRunner !== undefined ? { inferenceRunner } : {}),
-    ...(gateTimeout !== undefined ? { gateTimeout } : {}),
-    ...(shutdownTimeoutMs !== undefined ? { shutdownTimeoutMs } : {}),
-  };
-
-  const reactor = createReactor(reactorConfig);
-  const blobReader = createBlobReader(contextStore);
-
-  return { reactor, blobReader, auditCollector };
-}

package/src/audit-collector.test.ts

@@ -1,332 +0,0 @@
-import { describe, test, expect } from "bun:test";
-
-import { createAuditCollector } from "./audit-collector";
-import type { AuthzDecision } from "./authz-extension";
-import type { InferenceEvent } from "@intx/types/runtime";
-
-function makeDecision(overrides: Partial<AuthzDecision> = {}): AuthzDecision {
-  return {
-    callId: "call-1",
-    tool: "bash",
-    resource: "tool:bash",
-    action: "invoke",
-    effect: "allow",
-    resolvedBy: null,
-    matchingGrants: [],
-    blocked: false,
-    blockReason: undefined,
-    error: undefined,
-    ...overrides,
-  };
-}
-
-function toolStart(
-  callId: string,
-  name: string,
-  args: Record<string, unknown> = {},
-  seq = 1,
-): InferenceEvent {
-  return {
-    type: "tool.start",
-    seq,
-    data: { call: { id: callId, name, arguments: args } },
-  };
-}
-
-function toolDone(
-  callId: string,
-  content: string | Record<string, unknown>,
-  seq = 2,
-  isError = false,
-): InferenceEvent {
-  return {
-    type: "tool.done",
-    seq,
-    data: { result: { callId, content, isError } },
-  };
-}
-
-describe("createAuditCollector", () => {
-  test("collects a complete allowed tool invocation", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onDecision(makeDecision({ callId: "c1" }));
-    collector.onEvent(toolStart("c1", "bash", { cmd: "ls" }));
-    collector.onEvent(toolDone("c1", "file.txt", 5));
-
-    const records = collector.flush();
-    expect(records.length).toBe(1);
-    const r = records[0];
-    if (r === undefined) throw new Error("expected record");
-
-    expect(r.callId).toBe("c1");
-    expect(r.tool).toBe("bash");
-    expect(r.arguments).toEqual({ cmd: "ls" });
-    expect(r.result.content).toBe("file.txt");
-    expect(r.result.isError).toBe(false);
-    expect(r.sessionId).toBe("session-1");
-    expect(r.seq).toBe(5);
-    expect(r.authz).not.toBeNull();
-    if (r.authz === null) throw new Error("expected authz");
-    expect(r.authz.effect).toBe("allow");
-    expect(r.authz.blocked).toBe(false);
-  });
-
-  test("collects a blocked tool invocation (no tool.start)", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onDecision(
-      makeDecision({
-        callId: "c1",
-        effect: "deny",
-        blocked: true,
-        blockReason: "Denied by policy: tool:bash/invoke",
-      }),
-    );
-    collector.onEvent(
-      toolDone("c1", "Denied by policy: tool:bash/invoke", 3, true),
-    );
-
-    const records = collector.flush();
-    expect(records.length).toBe(1);
-    const r = records[0];
-    if (r === undefined) throw new Error("expected record");
-
-    expect(r.callId).toBe("c1");
-    expect(r.tool).toBe("bash");
-    expect(r.result.isError).toBe(true);
-    expect(r.result.content).toBe("Denied by policy: tool:bash/invoke");
-    expect(r.authz).not.toBeNull();
-    if (r.authz === null) throw new Error("expected authz");
-    expect(r.authz.effect).toBe("deny");
-    expect(r.authz.blocked).toBe(true);
-  });
-
-  test("collects tool invocation without authz extension", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onEvent(toolStart("c1", "curl", { url: "http://x" }));
-    collector.onEvent(toolDone("c1", { status: 200 }, 4));
-
-    const records = collector.flush();
-    expect(records.length).toBe(1);
-    const r = records[0];
-    if (r === undefined) throw new Error("expected record");
-
-    expect(r.authz).toBeNull();
-    expect(r.result.content).toEqual({ status: 200 });
-  });
-
-  test("handles parallel tool calls with same name", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onDecision(makeDecision({ callId: "c1", tool: "bash" }));
-    collector.onDecision(makeDecision({ callId: "c2", tool: "bash" }));
-    collector.onEvent(toolStart("c1", "bash", { cmd: "ls" }, 1));
-    collector.onEvent(toolStart("c2", "bash", { cmd: "pwd" }, 2));
-    collector.onEvent(toolDone("c1", "/home", 3));
-    collector.onEvent(toolDone("c2", "/tmp", 4));
-
-    const records = collector.flush();
-    expect(records.length).toBe(2);
-
-    const r1 = records.find((r) => r.callId === "c1");
-    const r2 = records.find((r) => r.callId === "c2");
-    if (r1 === undefined || r2 === undefined)
-      throw new Error("expected both records");
-
-    expect(r1.arguments).toEqual({ cmd: "ls" });
-    expect(r1.result.content).toBe("/home");
-    expect(r2.arguments).toEqual({ cmd: "pwd" });
-    expect(r2.result.content).toBe("/tmp");
-  });
-
-  test("parallel mixed batch: one allowed, one blocked", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onDecision(
-      makeDecision({ callId: "c1", effect: "allow", blocked: false }),
-    );
-    collector.onDecision(
-      makeDecision({
-        callId: "c2",
-        effect: "deny",
-        blocked: true,
-        blockReason: "denied",
-      }),
-    );
-
-    collector.onEvent(toolStart("c1", "bash", {}, 1));
-    collector.onEvent(toolDone("c2", "denied", 2, true));
-    collector.onEvent(toolDone("c1", "ok", 3));
-
-    const records = collector.flush();
-    expect(records.length).toBe(2);
-
-    const allowed = records.find((r) => r.callId === "c1");
-    const blocked = records.find((r) => r.callId === "c2");
-    if (allowed === undefined || blocked === undefined)
-      throw new Error("expected both");
-
-    expect(allowed.result.isError).toBe(false);
-    expect(blocked.result.isError).toBe(true);
-    if (blocked.authz === null) throw new Error("expected authz");
-    expect(blocked.authz.blocked).toBe(true);
-  });
-
-  test("flush clears completed records", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onEvent(toolStart("c1", "bash", {}, 1));
-    collector.onEvent(toolDone("c1", "ok", 2));
-
-    const first = collector.flush();
-    expect(first.length).toBe(1);
-
-    const second = collector.flush();
-    expect(second.length).toBe(0);
-  });
-
-  test("flush does not return in-flight records", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onDecision(makeDecision({ callId: "c1" }));
-    collector.onEvent(toolStart("c1", "bash", {}, 1));
-    // No tool.done yet
-
-    const records = collector.flush();
-    expect(records.length).toBe(0);
-    expect(collector.pending()).toBe(1);
-  });
-
-  test("pending counts buffered decisions and in-flight records", () => {
-    const collector = createAuditCollector("session-1");
-    expect(collector.pending()).toBe(0);
-
-    collector.onDecision(makeDecision({ callId: "c1" }));
-    expect(collector.pending()).toBe(1);
-
-    collector.onEvent(toolStart("c1", "bash", {}, 1));
-    expect(collector.pending()).toBe(1);
-
-    collector.onEvent(toolDone("c1", "ok", 2));
-    expect(collector.pending()).toBe(0);
-  });
-
-  test("records across multiple flush cycles accumulate correctly", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onEvent(toolStart("c1", "bash", {}, 1));
-    collector.onEvent(toolDone("c1", "a", 2));
-    expect(collector.flush().length).toBe(1);
-
-    collector.onEvent(toolStart("c2", "curl", {}, 3));
-    collector.onEvent(toolDone("c2", "b", 4));
-    collector.onEvent(toolStart("c3", "node", {}, 5));
-    collector.onEvent(toolDone("c3", "c", 6));
-    expect(collector.flush().length).toBe(2);
-  });
-
-  test("authz decision with resolvedBy and matchingGrants", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onDecision(
-      makeDecision({
-        callId: "c1",
-        effect: "allow",
-        resolvedBy: {
-          id: "grant-1",
-          resource: "tool:bash",
-          action: "invoke",
-          effect: "allow",
-          origin: "creator",
-          specificity: 1009,
-        },
-        matchingGrants: [
-          {
-            id: "grant-1",
-            resource: "tool:bash",
-            action: "invoke",
-            effect: "allow",
-            origin: "creator",
-            specificity: 1009,
-          },
-        ],
-      }),
-    );
-    collector.onEvent(toolStart("c1", "bash", {}, 1));
-    collector.onEvent(toolDone("c1", "ok", 2));
-
-    const records = collector.flush();
-    const r = records[0];
-    if (r === undefined) throw new Error("expected record");
-    if (r.authz === null) throw new Error("expected authz");
-    if (r.authz.resolvedBy === undefined || r.authz.resolvedBy === null)
-      throw new Error("expected resolvedBy");
-
-    expect(r.authz.resolvedBy.id).toBe("grant-1");
-    expect(r.authz.resolvedBy.specificity).toBe(1009);
-    expect(r.authz.matchingGrants.length).toBe(1);
-  });
-
-  test("ignores non-tool events", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onEvent({
-      type: "inference.start",
-      seq: 1,
-      data: { model: "test" },
-    });
-    collector.onEvent({
-      type: "reactor.start",
-      seq: 2,
-      data: {},
-    });
-
-    expect(collector.flush().length).toBe(0);
-    expect(collector.pending()).toBe(0);
-  });
-
-  test("emits degraded record on orphaned tool.done with no prior context", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onEvent(toolDone("unknown-call", "result", 1));
-
-    const records = collector.flush();
-    expect(records.length).toBe(1);
-    const r = records[0];
-    if (r === undefined) throw new Error("expected record");
-
-    expect(r.callId).toBe("unknown-call");
-    expect(r.tool).toBe("$orphaned");
-    expect(r.arguments).toEqual({});
-    expect(r.authz).toBeNull();
-    expect(r.result.content).toBe("result");
-    expect(r.sessionId).toBe("session-1");
-    expect(r.seq).toBe(1);
-  });
-
-  test("orphaned tool.done propagates isError into degraded record", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onEvent(toolDone("orphan-err", "denied", 1, true));
-
-    const records = collector.flush();
-    expect(records.length).toBe(1);
-    const r = records[0];
-    if (r === undefined) throw new Error("expected record");
-
-    expect(r.tool).toBe("$orphaned");
-    expect(r.result.isError).toBe(true);
-    expect(r.result.content).toBe("denied");
-  });
-
-  test("orphaned tool.done does not leak into pending count", () => {
-    const collector = createAuditCollector("session-1");
-
-    collector.onEvent(toolDone("orphan-1", "result", 1));
-
-    expect(collector.pending()).toBe(0);
-    expect(collector.flush().length).toBe(1);
-  });
-});