@intx/inference 0.1.2

package/src/authz-extension.ts

@@ -0,0 +1,145 @@
+// Authz-based BeforeToolExtension.
+//
+// Creates an extension that authorizes tool calls against a policy before
+// execution. The caller provides a pre-bound authorize function that
+// encapsulates store, principal, tenant, and condition registry details.
+//
+// Effects:
+//   allow  → tool proceeds
+//   deny   → tool blocked
+//   ask    → tool blocked (gate-based approval deferred to a future commit)
+//   null   → tool blocked (fail-closed: no grants matched)
+//
+// The action is always "invoke" — all tool calls are invocations. If
+// additional action granularity is needed later, the action becomes a
+// parameter.
+//
+// Signal propagation into the authorize function is deferred — the caller
+// can capture the signal in their closure if cancellation is needed.
+//
+// The onDecision callback must not throw. If it does, the exception is
+// logged but swallowed so it cannot interfere with the authorization
+// decision or mask the original error.
+
+import type { BeforeToolExtension } from "@intx/types/runtime";
+import type { Effect } from "@intx/types/authz";
+
+export type AuthzMatchedGrant = {
+  id: string;
+  resource: string;
+  action: string;
+  effect: Effect;
+  origin: "system" | "role" | "creator" | "invoker";
+  specificity: number;
+};
+
+export type AuthzCallResult = {
+  effect: Effect | null;
+  matchingGrants: AuthzMatchedGrant[];
+  resolvedBy: AuthzMatchedGrant | null;
+};
+
+export type AuthzDecision = {
+  callId: string;
+  tool: string;
+  resource: string;
+  action: string;
+  effect: Effect | null;
+  resolvedBy: AuthzMatchedGrant | null;
+  matchingGrants: AuthzMatchedGrant[];
+  blocked: boolean;
+  blockReason: string | undefined;
+  error: string | undefined;
+};
+
+export type AuthzExtensionOptions = {
+  authorize: (resource: string, action: string) => Promise<AuthzCallResult>;
+  onDecision?: (decision: AuthzDecision) => void;
+};
+
+type BlockEffect = "deny" | "ask" | null;
+
+function formatBlockReason(
+  effect: BlockEffect,
+  resource: string,
+  action: string,
+): string {
+  switch (effect) {
+    case "deny":
+      return `Denied by policy: ${resource}/${action}`;
+    case "ask":
+      return `Requires approval: ${resource}/${action}`;
+    case null:
+      return `No matching grants for ${resource}/${action}`;
+  }
+}
+
+function safeOnDecision(
+  callback: ((decision: AuthzDecision) => void) | undefined,
+  decision: AuthzDecision,
+): void {
+  if (callback === undefined) return;
+  try {
+    callback(decision);
+  } catch {
+    // onDecision must not throw. If it does, swallow the exception so
+    // it cannot interfere with the authorization decision or mask the
+    // original error from authorize().
+  }
+}
+
+export function createAuthzExtension(
+  opts: AuthzExtensionOptions,
+): BeforeToolExtension {
+  return {
+    async beforeTool(call) {
+      const resource = `tool:${call.name}`;
+      const action = "invoke";
+
+      let result: AuthzCallResult;
+      try {
+        result = await opts.authorize(resource, action);
+      } catch (cause) {
+        const msg = cause instanceof Error ? cause.message : String(cause);
+        const decision: AuthzDecision = {
+          callId: call.id,
+          tool: call.name,
+          resource,
+          action,
+          effect: null,
+          resolvedBy: null,
+          matchingGrants: [],
+          blocked: true,
+          blockReason: `Authorization failed: ${msg}`,
+          error: msg,
+        };
+        safeOnDecision(opts.onDecision, decision);
+        throw cause;
+      }
+
+      const blocked = result.effect !== "allow";
+      const blockReason =
+        result.effect === "deny" ||
+        result.effect === "ask" ||
+        result.effect === null
+          ? formatBlockReason(result.effect, resource, action)
+          : undefined;
+
+      const decision: AuthzDecision = {
+        callId: call.id,
+        tool: call.name,
+        resource,
+        action,
+        effect: result.effect,
+        resolvedBy: result.resolvedBy,
+        matchingGrants: result.matchingGrants,
+        blocked,
+        blockReason,
+        error: undefined,
+      };
+      safeOnDecision(opts.onDecision, decision);
+
+      return blockReason;
+    },
+  };
+}

package/src/correlation.ts

@@ -0,0 +1,61 @@
+// Correlation registry and validator interface for the agent reactor.
+//
+// Correlation connects outbound async tool calls to inbound responses. The
+// reactor owns the matching; the director does not participate.
+//
+// (INFERENCE.md § Correlation)
+
+import type { InboundMessage, PendingOperation } from "@intx/types/runtime";
+
+/**
+ * Validates whether an inbound message is an authentic response to a
+ * registered pending operation. Consumers provide this at reactor construction
+ * time to enforce sender identity and signature checks.
+ */
+export interface CorrelationValidator {
+  /**
+   * Return true if `message` is a valid resolution for `pending`.
+   * False causes the message to be delivered as a regular uncorrelated event.
+   */
+  validate(
+    pending: PendingOperation,
+    message: InboundMessage,
+  ): Promise<boolean>;
+}
+
+/**
+ * Tracks pending async operations. Each entry maps a correlation ID to the
+ * operation metadata and the gate that is waiting for it.
+ */
+export function createCorrelationRegistry() {
+  const operations = new Map<string, PendingOperation>();
+
+  function register(op: PendingOperation): void {
+    if (operations.has(op.correlationId)) {
+      throw new Error(
+        `Correlation ID "${op.correlationId}" is already registered`,
+      );
+    }
+    operations.set(op.correlationId, op);
+  }
+
+  function lookup(correlationId: string): PendingOperation | undefined {
+    return operations.get(correlationId);
+  }
+
+  function remove(correlationId: string): boolean {
+    return operations.delete(correlationId);
+  }
+
+  function all(): PendingOperation[] {
+    return Array.from(operations.values());
+  }
+
+  function hasAny(): boolean {
+    return operations.size > 0;
+  }
+
+  return { register, lookup, remove, all, hasAny };
+}
+
+export type CorrelationRegistry = ReturnType<typeof createCorrelationRegistry>;

package/src/default-director.test.ts

@@ -0,0 +1,314 @@
+import { describe, test, expect } from "bun:test";
+
+import { createInboundMessage } from "@intx/mime";
+import type {
+  AssistantTurn,
+  InferenceError,
+  LastCycleSource,
+  PartialMessage,
+  ReactorAction,
+  ReactorInboundEvent,
+  ReactorState,
+  ToolResult,
+  TokenUsage,
+} from "@intx/types/runtime";
+
+import { createDefaultDirector } from "./default-director";
+import type {
+  AfterInferenceDecision,
+  AfterInferenceHook,
+  DefaultDirectorPolicy,
+} from "./default-director";
+import { createCapabilities } from "./director";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const TEST_SOURCE: LastCycleSource = {
+  sourceId: "anthropic:claude-test",
+  provider: "anthropic",
+  model: "claude-test",
+};
+
+const TEST_USAGE: TokenUsage = {
+  input: 100,
+  output: 50,
+  cacheRead: 0,
+  cacheWrite: 0,
+  thinking: 0,
+};
+
+function makeState(overrides: Partial<ReactorState> = {}): ReactorState {
+  return {
+    sessionId: "test-session",
+    turns: [],
+    activeForks: [],
+    pendingOperations: [],
+    activeGates: [],
+    tokenUsage: { ...TEST_USAGE },
+    lastCycleUsage: { ...TEST_USAGE },
+    lastCycleSource: { ...TEST_SOURCE },
+    ...overrides,
+  };
+}
+
+function makeAssistantTurn(text: string): AssistantTurn {
+  return {
+    role: "assistant",
+    content: [{ type: "text", text }],
+    model: "claude-test",
+    timestamp: 1000,
+  };
+}
+
+function makeAssistantTurnWithToolCall(
+  callId: string,
+  name: string,
+): AssistantTurn {
+  return {
+    role: "assistant",
+    content: [
+      { type: "tool_call", id: callId, name, arguments: { q: "test" } },
+    ],
+    model: "claude-test",
+    timestamp: 1000,
+  };
+}
+
+function makeInferenceDoneEvent(turn: AssistantTurn): ReactorInboundEvent {
+  return {
+    type: "inference.done",
+    turn,
+    usage: TEST_USAGE,
+    source: TEST_SOURCE,
+  };
+}
+
+function makeInferenceErrorEvent(): ReactorInboundEvent {
+  const error: InferenceError = {
+    category: "fatal",
+    message: "test error",
+  };
+  const partial: PartialMessage = { text: "" };
+  return { type: "inference.error", error, partial };
+}
+
+async function decide(
+  policy: DefaultDirectorPolicy,
+  event: ReactorInboundEvent,
+  state: ReactorState = makeState(),
+): Promise<ReactorAction[]> {
+  const director = createDefaultDirector("You are a test agent.", [], policy);
+  const result = await director.decide(event, state, createCapabilities());
+  return Array.isArray(result) ? result : [result];
+}
+
+// ---------------------------------------------------------------------------
+// Hook decisions
+// ---------------------------------------------------------------------------
+
+describe("DefaultDirector — afterInferenceDone hook", () => {
+  test("continue: existing post-inference logic runs unchanged", async () => {
+    let receivedState: ReactorState | undefined;
+    let receivedTurn: AssistantTurn | undefined;
+    const hook: AfterInferenceHook = (state, turn) => {
+      receivedState = state;
+      receivedTurn = turn;
+      return { type: "continue" };
+    };
+    const turn = makeAssistantTurn("Hello from the model");
+    const actions = await decide(
+      { afterInferenceDone: hook },
+      makeInferenceDoneEvent(turn),
+    );
+
+    // The hook saw the post-cycle state and the turn — verifies the
+    // director plumbed both arguments through, not just called the hook.
+    expect(receivedTurn).toEqual(turn);
+    expect(receivedState?.lastCycleSource).toEqual(TEST_SOURCE);
+    expect(receivedState?.lastCycleUsage).toEqual(TEST_USAGE);
+
+    // Continue falls through to the existing reply path.
+    expect(actions).toEqual([
+      { type: "checkpoint", message: "checkpoint: inference-done" },
+      { type: "reply", content: "Hello from the model" },
+    ]);
+  });
+
+  test("abort: returns [checkpoint, reply, done] with the policy reason", async () => {
+    const hook: AfterInferenceHook = () => ({
+      type: "abort",
+      reason: "budget exhausted",
+    });
+    const actions = await decide(
+      { afterInferenceDone: hook },
+      makeInferenceDoneEvent(makeAssistantTurn("ignored")),
+    );
+    expect(actions).toEqual([
+      { type: "checkpoint", message: "checkpoint: after-inference-abort" },
+      { type: "reply", content: "budget exhausted" },
+      { type: "done" },
+    ]);
+  });
+
+  test("halt: returns [checkpoint, reply, wait] with the policy reason", async () => {
+    const hook: AfterInferenceHook = () => ({
+      type: "halt",
+      reason: "paused for top-up",
+    });
+    const actions = await decide(
+      { afterInferenceDone: hook },
+      makeInferenceDoneEvent(makeAssistantTurn("ignored")),
+    );
+    expect(actions).toEqual([
+      { type: "checkpoint", message: "checkpoint: after-inference-halt" },
+      { type: "reply", content: "paused for top-up" },
+      { type: "wait" },
+    ]);
+  });
+
+  test("hook not set: existing behavior preserved", async () => {
+    const actions = await decide(
+      {},
+      makeInferenceDoneEvent(makeAssistantTurn("Hello")),
+    );
+    expect(actions).toEqual([
+      { type: "checkpoint", message: "checkpoint: inference-done" },
+      { type: "reply", content: "Hello" },
+    ]);
+  });
+
+  test("hook throws: caught, routed to abort with synthesized reason", async () => {
+    const hook: AfterInferenceHook = () => {
+      throw new Error("policy died");
+    };
+    const actions = await decide(
+      { afterInferenceDone: hook },
+      makeInferenceDoneEvent(makeAssistantTurn("ignored")),
+    );
+    expect(actions).toEqual([
+      { type: "checkpoint", message: "checkpoint: after-inference-abort" },
+      {
+        type: "reply",
+        content: "afterInferenceDone policy threw: policy died",
+      },
+      { type: "done" },
+    ]);
+  });
+
+  test("hook returning a Promise is awaited", async () => {
+    const hook: AfterInferenceHook = async () => {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      const decision: AfterInferenceDecision = {
+        type: "abort",
+        reason: "async abort",
+      };
+      return decision;
+    };
+    const actions = await decide(
+      { afterInferenceDone: hook },
+      makeInferenceDoneEvent(makeAssistantTurn("ignored")),
+    );
+    expect(actions).toEqual([
+      { type: "checkpoint", message: "checkpoint: after-inference-abort" },
+      { type: "reply", content: "async abort" },
+      { type: "done" },
+    ]);
+  });
+
+  test("hook does NOT fire on inference.error", async () => {
+    let hookFired = false;
+    const hook: AfterInferenceHook = () => {
+      hookFired = true;
+      return { type: "abort", reason: "should not run" };
+    };
+    const actions = await decide(
+      { afterInferenceDone: hook },
+      makeInferenceErrorEvent(),
+    );
+    expect(hookFired).toBe(false);
+    // The inference.error branch produces its own checkpoint + reply
+    // shape; the hook is not in that path.
+    expect(actions[0]).toEqual({
+      type: "checkpoint",
+      message: "checkpoint: inference-error",
+    });
+  });
+
+  test("abort fires before tool calls execute (tool calls dropped)", async () => {
+    const hook: AfterInferenceHook = () => ({
+      type: "abort",
+      reason: "stop now",
+    });
+    const turn = makeAssistantTurnWithToolCall("call_1", "search");
+    const actions = await decide(
+      { afterInferenceDone: hook },
+      makeInferenceDoneEvent(turn),
+    );
+    // The model's tool call is on the turn, but the hook's abort
+    // routes to done before execute_tools is reached. The TSDoc warns
+    // policy authors about this; the test pins the behavior.
+    expect(actions).toEqual([
+      { type: "checkpoint", message: "checkpoint: after-inference-abort" },
+      { type: "reply", content: "stop now" },
+      { type: "done" },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Firing boundary: hook fires only on inference.done
+//
+// The "does NOT fire on inference.error" test above pins one negative
+// case; this block exhausts the rest of the ReactorInboundEvent union
+// so a future switch refactor (e.g. extracting a shared post-event
+// helper) can't quietly start invoking the hook on the wrong branch.
+// ---------------------------------------------------------------------------
+
+async function fireHook(event: ReactorInboundEvent): Promise<boolean> {
+  let fired = false;
+  const hook: AfterInferenceHook = () => {
+    fired = true;
+    return { type: "continue" };
+  };
+  await decide({ afterInferenceDone: hook }, event);
+  return fired;
+}
+
+describe("DefaultDirector — afterInferenceDone firing boundary", () => {
+  test("not fired on message.received", async () => {
+    const event: ReactorInboundEvent = {
+      type: "message.received",
+      message: createInboundMessage({
+        from: "test@example.com",
+        to: "agent@example.com",
+        content: "hi",
+      }),
+    };
+    expect(await fireHook(event)).toBe(false);
+  });
+
+  test("not fired on tool.done", async () => {
+    const result: ToolResult = { callId: "c1", content: "ok" };
+    const event: ReactorInboundEvent = { type: "tool.done", result };
+    expect(await fireHook(event)).toBe(false);
+  });
+
+  test("not fired on reactor.gate.cleared", async () => {
+    const event: ReactorInboundEvent = {
+      type: "reactor.gate.cleared",
+      gateId: "g1",
+      reason: "resolved",
+    };
+    expect(await fireHook(event)).toBe(false);
+  });
+
+  test("not fired on abort", async () => {
+    const event: ReactorInboundEvent = {
+      type: "abort",
+      reason: "user_disconnect",
+    };
+    expect(await fireHook(event)).toBe(false);
+  });
+});