@intx/inference 0.1.2 → 0.2.2

package/dist/assembly.js

@@ -0,0 +1,132 @@
+// 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, } from "@intx/types/runtime";
+import { createAuditCollector } from "./audit-collector.js";
+import { createAuthzExtension, } from "./authz-extension.js";
+import { createReactor, } from "./reactor.js";
+import { createSizeCapTransform } from "./transforms/index.js";
+const logger = getLogger(["interchange", "assembly"]);
+const DEFAULT_SIZE_CAP_MAX_CHARS = 10_000;
+/**
+ * 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) {
+    const { sessionId, director, source, failOverToNextSource, resetToPreferredSource, 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 = 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) => {
+            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 = 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 = [
+        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() {
+        if (auditCollector === undefined || auditStore === undefined)
+            return;
+        const records = auditCollector.flush();
+        if (records.length > 0) {
+            await auditStore.commitAudit(records);
+        }
+    }
+    const composedAfterCheckpoint = auditCollector !== undefined
+        ? async () => {
+            await flushAudit();
+            if (callerAfterCheckpoint !== undefined) {
+                await callerAfterCheckpoint();
+            }
+        }
+        : callerAfterCheckpoint;
+    const composedOnShutdown = 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;
+    // exactOptionalPropertyTypes is on: only set optional keys when defined.
+    const reactorConfig = {
+        sessionId,
+        director,
+        source,
+        ...(failOverToNextSource !== undefined ? { failOverToNextSource } : {}),
+        ...(resetToPreferredSource !== undefined ? { resetToPreferredSource } : {}),
+        toolRunner,
+        contextStore,
+        onEvent: composedOnEvent,
+        deps,
+        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/dist/audit-collector.d.ts

@@ -0,0 +1,10 @@
+import type { AuditRecord } from "@intx/types/audit";
+import type { InferenceEvent } from "@intx/types/runtime";
+import type { AuthzDecision } from "./authz-extension.js";
+export type AuditCollector = {
+    onEvent(event: InferenceEvent): void;
+    onDecision(decision: AuthzDecision): void;
+    flush(): AuditRecord[];
+    pending(): number;
+};
+export declare function createAuditCollector(sessionId: string): AuditCollector;

package/dist/audit-collector.js

@@ -0,0 +1,139 @@
+// Audit collector: accumulates tool invocation records for persistence.
+//
+// The collector correlates three data sources into complete AuditRecord
+// objects:
+//   1. tool.start events — tool name and arguments (allowed calls only)
+//   2. AuthzDecision via onDecision — governance decision
+//   3. tool.done events — result and completion metadata
+//
+// Correlation is by callId. For blocked calls, no tool.start is emitted;
+// the collector creates the record from the buffered decision and the
+// tool.done event alone.
+//
+// Wiring: the caller must connect onDecision to the authz extension's
+// onDecision callback, and onEvent to the reactor's event stream. The
+// types alone do not enforce this — it is a composition-layer concern.
+import { getLogger } from "@intx/log";
+const logger = getLogger(["interchange", "audit-collector"]);
+function coerceContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (typeof content === "object" && content !== null) {
+        // content is a non-null object — compatible with Record<string, unknown>
+        // but TypeScript can't verify the index signature without a cast.
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- non-null object is structurally compatible with Record<string, unknown> but TS won't widen
+        return content;
+    }
+    throw new Error(`Unexpected tool result content type: ${typeof content}`);
+}
+function mapGrant(g) {
+    return {
+        id: g.id,
+        resource: g.resource,
+        action: g.action,
+        effect: g.effect,
+        origin: g.origin,
+        specificity: g.specificity,
+    };
+}
+function decisionToAuthz(d) {
+    return {
+        effect: d.effect,
+        resolvedBy: d.resolvedBy ? mapGrant(d.resolvedBy) : null,
+        matchingGrants: d.matchingGrants.map(mapGrant),
+        blocked: d.blocked,
+        ...(d.blockReason !== undefined ? { blockReason: d.blockReason } : {}),
+    };
+}
+export function createAuditCollector(sessionId) {
+    const decisions = new Map();
+    const pendingRecords = new Map();
+    const completed = [];
+    function onDecision(decision) {
+        decisions.set(decision.callId, decision);
+    }
+    function onEvent(event) {
+        if (event.type === "tool.start") {
+            const call = event.data.call;
+            const decision = decisions.get(call.id);
+            decisions.delete(call.id);
+            pendingRecords.set(call.id, {
+                callId: call.id,
+                tool: call.name,
+                arguments: call.arguments,
+                authz: decision ? decisionToAuthz(decision) : null,
+            });
+            return;
+        }
+        if (event.type === "tool.done") {
+            const result = event.data.result;
+            const pending = pendingRecords.get(result.callId);
+            if (pending) {
+                pendingRecords.delete(result.callId);
+                completed.push({
+                    callId: pending.callId,
+                    tool: pending.tool,
+                    arguments: pending.arguments,
+                    authz: pending.authz,
+                    result: {
+                        content: coerceContent(result.content),
+                        isError: result.isError === true,
+                    },
+                    timestamp: new Date().toISOString(),
+                    sessionId,
+                    seq: event.seq,
+                });
+                return;
+            }
+            // Blocked call: no tool.start was emitted. Build the record from
+            // the buffered decision and the tool.done event.
+            const decision = decisions.get(result.callId);
+            if (decision === undefined) {
+                // Orphaned tool.done: no tool.start or authz decision was recorded.
+                // Emit a degraded record rather than crashing the session — the audit
+                // system is observational infrastructure and must not veto execution.
+                logger.warn `Orphaned tool.done for callId "${result.callId}": no tool.start or authz decision was recorded`;
+                completed.push({
+                    callId: result.callId,
+                    tool: "$orphaned",
+                    arguments: {},
+                    authz: null,
+                    result: {
+                        content: coerceContent(result.content),
+                        isError: result.isError === true,
+                    },
+                    timestamp: new Date().toISOString(),
+                    sessionId,
+                    seq: event.seq,
+                });
+                return;
+            }
+            decisions.delete(result.callId);
+            completed.push({
+                callId: result.callId,
+                tool: decision.tool,
+                arguments: {},
+                authz: decisionToAuthz(decision),
+                result: {
+                    content: coerceContent(result.content),
+                    isError: result.isError === true,
+                },
+                timestamp: new Date().toISOString(),
+                sessionId,
+                seq: event.seq,
+            });
+        }
+    }
+    function flush() {
+        return completed.splice(0);
+    }
+    function pendingCount() {
+        return pendingRecords.size + decisions.size;
+    }
+    return {
+        onEvent,
+        onDecision,
+        flush,
+        pending: pendingCount,
+    };
+}

package/dist/auth.d.ts

@@ -0,0 +1,24 @@
+import type { InferenceSource } from "@intx/types/runtime";
+/**
+ * Sentinel for headers that carry the API key verbatim (no prefix).
+ * Used by providers like Anthropic (`x-api-key`) and Google
+ * (`x-goog-api-key`) that accept the raw credential.
+ */
+export declare const CREDENTIAL_SENTINEL = "<inject:credential>";
+/**
+ * Sentinel for headers that carry a Bearer-prefixed API key. Used by
+ * providers that follow the `Authorization: Bearer <token>` convention
+ * (OpenAI, OpenAI-compatible).
+ */
+export declare const BEARER_CREDENTIAL_SENTINEL = "<inject:bearer-credential>";
+/**
+ * Replace credential sentinels in a header map with material derived
+ * from the inference source. Returns a new object; the input is not
+ * mutated. Non-sentinel header values pass through unchanged.
+ *
+ * A header value that contains a sentinel as a substring but is not
+ * exactly equal to it is left alone -- partial replacement would be
+ * surprising, and no legitimate adapter constructs sentinel-bearing
+ * composite values.
+ */
+export declare function injectCredentials(headers: Record<string, string>, source: InferenceSource): Record<string, string>;

package/{src/auth.ts → dist/auth.js}

@@ -1,5 +1,3 @@
-import type { InferenceSource } from "@intx/types/runtime";
-
 // Sentinel placeholder strings adapters use in their built request
 // headers to declare which credential the harness should fill at send
 // time. The harness scans every header value and replaces exact-match
@@ -18,21 +16,18 @@ import type { InferenceSource } from "@intx/types/runtime";
 // keyword prefix that would never appear in a legitimate header value:
 // matching is exact, but defense-in-depth ensures a literal echo from
 // an upstream system can't accidentally trigger replacement.
-
 /**
  * Sentinel for headers that carry the API key verbatim (no prefix).
  * Used by providers like Anthropic (`x-api-key`) and Google
  * (`x-goog-api-key`) that accept the raw credential.
  */
 export const CREDENTIAL_SENTINEL = "<inject:credential>";
-
 /**
  * Sentinel for headers that carry a Bearer-prefixed API key. Used by
  * providers that follow the `Authorization: Bearer <token>` convention
  * (OpenAI, OpenAI-compatible).
  */
 export const BEARER_CREDENTIAL_SENTINEL = "<inject:bearer-credential>";
-
 /**
  * Replace credential sentinels in a header map with material derived
  * from the inference source. Returns a new object; the input is not
@@ -43,19 +38,18 @@ export const BEARER_CREDENTIAL_SENTINEL = "<inject:bearer-credential>";
  * surprising, and no legitimate adapter constructs sentinel-bearing
  * composite values.
  */
-export function injectCredentials(
-  headers: Record<string, string>,
-  source: InferenceSource,
-): Record<string, string> {
-  const result: Record<string, string> = {};
-  for (const [name, value] of Object.entries(headers)) {
-    if (value === CREDENTIAL_SENTINEL) {
-      result[name] = source.apiKey;
-    } else if (value === BEARER_CREDENTIAL_SENTINEL) {
-      result[name] = `Bearer ${source.apiKey}`;
-    } else {
-      result[name] = value;
+export function injectCredentials(headers, source) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === CREDENTIAL_SENTINEL) {
+            result[name] = source.apiKey;
+        }
+        else if (value === BEARER_CREDENTIAL_SENTINEL) {
+            result[name] = `Bearer ${source.apiKey}`;
+        }
+        else {
+            result[name] = value;
+        }
     }
-  }
-  return result;
+    return result;
 }

package/dist/authz-extension.d.ts

@@ -0,0 +1,32 @@
+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<Ctx = unknown> = {
+    authorize: (resource: string, action: string, context: Ctx) => Promise<AuthzCallResult>;
+    onDecision?: (decision: AuthzDecision) => void;
+};
+export declare function createAuthzExtension<Ctx = unknown>(opts: AuthzExtensionOptions<Ctx>): BeforeToolExtension;

package/dist/authz-extension.js

@@ -0,0 +1,100 @@
+// 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.
+function formatBlockReason(effect, resource, action) {
+    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) {
+    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) {
+    // The reactor does not know workflow concepts; per-call context is the
+    // caller's domain. The third arg is plumbing here -- if the caller
+    // needs to attach context (workflow step, tenant id, request id), they
+    // do so by closure on the authorize function. The empty object is the
+    // safe default at this layer.
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- the inference layer has no domain knowledge to construct a Ctx; callers that need a populated context use closure capture on the authorize function (see @intx/workflow's AuthorizeContext)
+    const emptyContext = Object.freeze({});
+    return {
+        async beforeTool(call) {
+            const resource = `tool:${call.name}`;
+            const action = "invoke";
+            let result;
+            try {
+                result = await opts.authorize(resource, action, emptyContext);
+            }
+            catch (cause) {
+                const msg = cause instanceof Error ? cause.message : String(cause);
+                const decision = {
+                    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 = {
+                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/dist/correlation.d.ts

@@ -0,0 +1,25 @@
+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 declare function createCorrelationRegistry(): {
+    register: (op: PendingOperation) => void;
+    lookup: (correlationId: string) => PendingOperation | undefined;
+    remove: (correlationId: string) => boolean;
+    all: () => PendingOperation[];
+    hasAny: () => boolean;
+};
+export type CorrelationRegistry = ReturnType<typeof createCorrelationRegistry>;

package/dist/correlation.js

@@ -0,0 +1,32 @@
+// 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)
+/**
+ * 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();
+    function register(op) {
+        if (operations.has(op.correlationId)) {
+            throw new Error(`Correlation ID "${op.correlationId}" is already registered`);
+        }
+        operations.set(op.correlationId, op);
+    }
+    function lookup(correlationId) {
+        return operations.get(correlationId);
+    }
+    function remove(correlationId) {
+        return operations.delete(correlationId);
+    }
+    function all() {
+        return Array.from(operations.values());
+    }
+    function hasAny() {
+        return operations.size > 0;
+    }
+    return { register, lookup, remove, all, hasAny };
+}

package/dist/default-director.d.ts

@@ -0,0 +1,111 @@
+import type { ReactorDirector, ReactorInboundEvent, ReactorState, ReactorCapabilities, ReactorAction, AssistantTurn, ToolDefinition } from "@intx/types/runtime";
+/**
+ * Decision returned by an `afterInferenceDone` policy hook.
+ *
+ *   continue — proceed with the director's normal post-inference logic
+ *              (tool extraction, reply, or wait per the existing flow).
+ *   abort    — terminate the agent. Routes to `[checkpoint, done]` and
+ *              the reactor shuts down. Stronger than the
+ *              `inference.error` branch, which only replies and stays
+ *              alive — `abort` is for "session is over, do not accept
+ *              further inputs."
+ *   halt     — pause the current cycle without terminating. Routes to
+ *              `[checkpoint, reply]`; the reply returns the reactor to
+ *              waiting for the next inbound event, so it stays alive.
+ *              There is no auto-resume; an external event (mail, gate
+ *              clearance, etc.) must reach the reactor for the agent to
+ *              make progress again.
+ *
+ * `reason` on a `halt` becomes the connector reply text verbatim, so
+ * policy authors choose what is safe to surface to the user. On an
+ * `abort` the reason is not surfaced: a terminal action cannot carry a
+ * reply, since a reply invites continuation. Delivering an abort reason
+ * to the user needs a dedicated terminal-notice path, which does not
+ * exist today.
+ */
+export type AfterInferenceDecision = {
+    type: "continue";
+} | {
+    type: "abort";
+    reason: string;
+} | {
+    type: "halt";
+    reason: string;
+};
+/**
+ * Function shape for an after-inference-done policy hook.
+ *
+ * The hook fires only on `inference.done` (a successful cycle). Errored
+ * cycles do not invoke it. `mode: "reactive"` does not change firing —
+ * the hook gates the entire `inference.done` branch, including the
+ * reactive-wait shortcut, so a budget check applies to reactive agents
+ * the same way it does to conversational ones.
+ *
+ * The hook receives the post-cycle `ReactorState` (with `lastCycleSource`
+ * and `lastCycleUsage` populated for the just-completed call) and the
+ * assistant turn. Returns a decision (sync or async) that controls
+ * whether the director continues, terminates the agent, or pauses the
+ * cycle.
+ *
+ * Canonical use case: cost-aware gating. Read `state.lastCycleSource`
+ * + `state.lastCycleUsage`, price the call against user-supplied rate
+ * data, decide whether the budget is exhausted. Token caps, time caps,
+ * wallet checks, and governance triggers fit the same shape; the
+ * type stays policy-agnostic.
+ *
+ * "Downgrade to cheaper model" policies do NOT use this hook to return
+ * a new source. Compose them via an external observer of
+ * `lastCycleSource` / `lastCycleUsage` that calls `setSource` from
+ * outside the director.
+ *
+ * The hook blocks the reactor's inference.done branch: keep its
+ * latency low. The return type admits a Promise, but every await
+ * inside the hook is wall-clock time the agent isn't making progress.
+ * Small lookups (in-memory caches, fast DB reads) are fine; arbitrary
+ * waits are not.
+ *
+ * Tool calls and `halt`: if the model emitted tool calls and the hook
+ * returns `halt` (or `abort`), those tool calls are dropped — the
+ * director never executes them. On resume, the model's next inference
+ * sees an assistant turn with unanswered tool calls; depending on the
+ * provider this is either a validation error or a confused model.
+ * Policy authors that combine `halt` with tool-heavy agents need to
+ * understand this.
+ */
+export type AfterInferenceHook = (state: ReactorState, turn: AssistantTurn) => AfterInferenceDecision | Promise<AfterInferenceDecision>;
+export type DefaultDirectorPolicy = {
+    /**
+     * Controls the agent's behavior after inference completes.
+     *
+     *   "conversational" (default) — The standard agentic loop. After tools
+     *     complete, re-infer so the model can reason about results, issue more
+     *     tool calls, or compose a reply. When inference produces text without
+     *     tool calls, send it as a connector reply.
+     *
+     *   "reactive" — The agent acts on each message by executing tools, then
+     *     returns to the event loop to wait for the next inbound event. It does
+     *     not re-infer after tools complete and does not send connector replies.
+     *     Use this for agents that perform a single action per message.
+     */
+    mode?: "conversational" | "reactive";
+    /**
+     * Optional policy hook fired after every successful `inference.done`.
+     * See `AfterInferenceHook` for the contract: firing boundary, return
+     * shape, composition patterns, and policy-author caveats.
+     *
+     * If the hook throws or rejects, the director catches the error,
+     * routes to `{ type: "abort", reason: "afterInferenceDone policy
+     * threw: <message>" }`, and logs at error level. The director's
+     * never-throws contract is preserved.
+     */
+    afterInferenceDone?: AfterInferenceHook;
+};
+export declare class DefaultDirector implements ReactorDirector {
+    private readonly systemPrompt;
+    private readonly toolDefinitions;
+    private readonly policy;
+    private pendingToolResults;
+    constructor(systemPrompt: string, toolDefinitions?: ToolDefinition[], policy?: DefaultDirectorPolicy);
+    decide(event: ReactorInboundEvent, state: ReactorState, capabilities: ReactorCapabilities): Promise<ReactorAction | ReactorAction[]>;
+}
+export declare function createDefaultDirector(systemPrompt: string, toolDefinitions?: ToolDefinition[], policy?: DefaultDirectorPolicy): ReactorDirector;