@intx/inference 0.2.2 → 0.3.0

package/dist/adapter.d.ts

@@ -6,18 +6,20 @@ export type BuiltRequest = {
 };
 export type RequestBuilder = (messages: ConversationTurn[], model: string, options: InferenceOptions) => BuiltRequest;
 export type ResponseParser = (sseData: string) => InferenceEvent[];
+export type JSONResponseParser = (body: string) => InferenceEvent[];
 export type RetryAfterExtractor = (headers: Headers) => number | undefined;
 export type PacingExtractor = (headers: Headers) => number | undefined;
 export type ProviderAdapter = {
     buildRequest: RequestBuilder;
     parseResponse: ResponseParser;
+    parseJSONResponse: JSONResponseParser;
     extractRetryAfterMs?: RetryAfterExtractor;
     extractPacingDelayMs?: PacingExtractor;
 };
-export type AdapterFactory = (source: LastCycleSource) => ProviderAdapter;
+export type AdapterFactory = (source: LastCycleSource, quirks?: unknown) => ProviderAdapter;
 export type AdapterRegistry = {
     has(provider: string): boolean;
-    resolve(source: LastCycleSource): ProviderAdapter;
+    resolve(source: LastCycleSource, quirks?: unknown): ProviderAdapter;
 };
 /**
  * Builds an adapter registry from a map of provider identifier to adapter

package/dist/adapter.js

@@ -20,12 +20,12 @@ export function createAdapterRegistry(factories) {
         has(provider) {
             return byProvider.has(provider);
         },
-        resolve(source) {
+        resolve(source, quirks) {
             const factory = byProvider.get(source.provider);
             if (factory === undefined) {
                 throw new Error(`Unknown inference provider: ${source.provider}`);
             }
-            return factory(source);
+            return factory(source, quirks);
         },
     };
 }

package/dist/assembly.d.ts

@@ -1,4 +1,4 @@
-import { 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 { type BlobReader, type AuditStore, type BeforeToolExtension, type Compactor, type ContextStore, type ContextTransform, type InferenceSource, type ReactorDirector, type ToolDefinition, type ToolResultTransform, type ToolRunner } from "@intx/types/runtime";
 import { type AuditCollector } from "./audit-collector.js";
 import { type AuthzExtensionOptions } from "./authz-extension.js";
 import type { CorrelationValidator } from "./correlation.js";
@@ -31,6 +31,13 @@ export type ReactorAssemblyConfig = {
     contextStore: ContextStore;
     onEvent: (event: ReactorEmittedEvent) => void;
     authorize?: AuthzExtensionOptions["authorize"];
+    /**
+     * Tool definitions forwarded to the authz extension so it can build the
+     * approver-facing snapshot at an `ask` suspension. Only consumed when
+     * `authorize` is also supplied. Omitting it puts the authz extension in its
+     * no-snapshot mode; the production edge always supplies the resolved set.
+     */
+    toolDefinitions?: readonly ToolDefinition[];
     auditStore?: AuditStore;
     beforeToolExtensions?: BeforeToolExtension[];
     toolResultTransforms?: ToolResultTransform[];

package/dist/assembly.js

@@ -24,7 +24,7 @@ const DEFAULT_SIZE_CAP_MAX_CHARS = 10_000;
  * 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;
+    const { sessionId, director, source, failOverToNextSource, resetToPreferredSource, toolRunner, contextStore, onEvent, authorize, toolDefinitions, 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.
@@ -51,6 +51,7 @@ export function createReactorAssembly(config) {
             ...(auditCollector !== undefined
                 ? { onDecision: (d) => auditCollector.onDecision(d) }
                 : {}),
+            ...(toolDefinitions !== undefined ? { toolDefinitions } : {}),
         })
         : undefined;
     const composedBeforeToolExtensions = authzExtension !== undefined

package/dist/authz-extension.d.ts

@@ -1,4 +1,4 @@
-import type { BeforeToolExtension } from "@intx/types/runtime";
+import type { BeforeToolExtension, ToolDefinition } from "@intx/types/runtime";
 import type { Effect } from "@intx/types/authz";
 export type AuthzMatchedGrant = {
     id: string;
@@ -28,5 +28,19 @@ export type AuthzDecision = {
 export type AuthzExtensionOptions<Ctx = unknown> = {
     authorize: (resource: string, action: string, context: Ctx) => Promise<AuthzCallResult>;
     onDecision?: (decision: AuthzDecision) => void;
+    /**
+     * Deadline applied to an approval suspension, in milliseconds from the
+     * moment the `ask` effect is hit. Defaults to `DEFAULT_APPROVAL_TIMEOUT_MS`.
+     */
+    approvalTimeoutMs?: number;
+    /**
+     * Tool definitions the extension can be asked to authorize, used to build the
+     * approver-facing snapshot at the `ask` branch. Presence is a contract: when
+     * supplied, every tool this extension authorizes must appear here, and an
+     * `ask` for a tool that does not is a wiring defect that throws. Omitted
+     * entirely, the extension produces no snapshot — a mode for callers that
+     * never register a suspension with the hub.
+     */
+    toolDefinitions?: readonly ToolDefinition[];
 };
 export declare function createAuthzExtension<Ctx = unknown>(opts: AuthzExtensionOptions<Ctx>): BeforeToolExtension;

package/dist/authz-extension.js

@@ -7,7 +7,7 @@
 // Effects:
 //   allow  → tool proceeds
 //   deny   → tool blocked
-//   ask    → tool blocked (gate-based approval deferred to a future commit)
+//   ask    → tool suspended (parked awaiting an external approval decision)
 //   null   → tool blocked (fail-closed: no grants matched)
 //
 // The action is always "invoke" — all tool calls are invocations. If
@@ -20,12 +20,15 @@
 // 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.
+// Default deadline for an approval suspension when the caller does not supply
+// one. Matches the reactor's DEFAULT_GATE_TIMEOUT_MS (one hour); the value is
+// duplicated rather than imported to avoid a dependency from the pure-policy
+// extension onto the reactor module.
+const DEFAULT_APPROVAL_TIMEOUT_MS = 3_600_000;
 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}`;
     }
@@ -50,7 +53,25 @@ export function createAuthzExtension(opts) {
     // 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({});
+    // One-shot bypass tokens, keyed on ToolCall.id. A token authorizes a single
+    // re-dispatch of an already-approved call to skip the `ask` gate it would
+    // otherwise re-hit. Held in memory only, within the resumed reactor cycle
+    // that grants and consumes it: a durable allow would outlive the cycle and
+    // defeat the one-shot intent, and a crash between grant and consume simply
+    // re-drives from the durable log and re-grants.
+    const approvedOnce = new Set();
+    // Name → definition lookup for building the approval snapshot at the `ask`
+    // branch. `undefined` (not merely empty) means the caller wired no tool
+    // definitions and wants no snapshot; a defined map means every authorizable
+    // tool must be present, so a lookup miss is a wiring defect that throws. The
+    // sentinel keeps those two contracts distinguishable at the lookup site.
+    const toolDefinitionsByName = opts.toolDefinitions !== undefined
+        ? new Map(opts.toolDefinitions.map((def) => [def.name, def]))
+        : undefined;
     return {
+        grantOneShot(id) {
+            approvedOnce.add(id);
+        },
         async beforeTool(call) {
             const resource = `tool:${call.name}`;
             const action = "invoke";
@@ -75,10 +96,11 @@ export function createAuthzExtension(opts) {
                 safeOnDecision(opts.onDecision, decision);
                 throw cause;
             }
-            const blocked = result.effect !== "allow";
-            const blockReason = result.effect === "deny" ||
-                result.effect === "ask" ||
-                result.effect === null
+            // An `ask` effect suspends the call rather than blocking it, so it is
+            // neither cleanly blocked nor allowed: the decision records
+            // `blocked: false` with no block reason. Only `deny`/null (fail-closed)
+            // are blocks.
+            const blockReason = result.effect === "deny" || result.effect === null
                 ? formatBlockReason(result.effect, resource, action)
                 : undefined;
             const decision = {
@@ -89,12 +111,74 @@ export function createAuthzExtension(opts) {
                 effect: result.effect,
                 resolvedBy: result.resolvedBy,
                 matchingGrants: result.matchingGrants,
-                blocked,
+                blocked: blockReason !== undefined,
                 blockReason,
                 error: undefined,
             };
             safeOnDecision(opts.onDecision, decision);
-            return blockReason;
+            // A one-shot token only authorizes bypassing an `ask` gate. If the
+            // resolved effect is anything else, the grant changed underneath the
+            // token: drop it and let the normal path decide, rather than silently
+            // allowing a call the policy no longer parks.
+            if (approvedOnce.has(call.id) && result.effect !== "ask") {
+                approvedOnce.delete(call.id);
+            }
+            if (blockReason !== undefined) {
+                return { type: "block", reason: blockReason };
+            }
+            if (result.effect === "ask") {
+                // A prior approval authorized this exact call to run once. Consume the
+                // token (delete-on-read) and allow it through instead of suspending,
+                // so a re-dispatched approved call does not re-park on its own gate.
+                if (approvedOnce.has(call.id)) {
+                    approvedOnce.delete(call.id);
+                    return { type: "allow" };
+                }
+                // Mint the correlationId once here so it is the single source of
+                // identity for both the gate and the persisted operation. The
+                // reactor persists the operation, so this id survives a restart.
+                const correlationId = crypto.randomUUID();
+                const timeoutAt = Date.now() + (opts.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS);
+                const gateId = `pending-${correlationId}`;
+                // Build the approver-facing snapshot when tool definitions are wired.
+                // A wired extension must have a definition for every tool it can
+                // authorize, so a miss is a wiring defect rather than a fallback. An
+                // unwired extension produces no snapshot: such callers never register
+                // the suspension with the hub, so the downstream required-snapshot
+                // validator never sees them.
+                let approvalSnapshot;
+                if (toolDefinitionsByName !== undefined) {
+                    const def = toolDefinitionsByName.get(call.name);
+                    if (def === undefined) {
+                        throw new Error(`Tool "${call.name}" was authorized with effect "ask" but has ` +
+                            `no definition in the resolved tool set; the approval ` +
+                            `snapshot cannot be built. This is a wiring defect: every ` +
+                            `tool the authz extension can authorize must be present in ` +
+                            `toolDefinitions.`);
+                    }
+                    approvalSnapshot = {
+                        name: call.name,
+                        description: def.description,
+                        inputSchema: def.inputSchema,
+                        arguments: call.arguments,
+                    };
+                }
+                const pendingOp = {
+                    correlationId,
+                    kind: "approval",
+                    registeredAt: Date.now(),
+                    gateId,
+                    timeoutAt,
+                    suspendedCall: call,
+                    ...(approvalSnapshot !== undefined ? { approvalSnapshot } : {}),
+                };
+                return {
+                    type: "suspend",
+                    gate: { type: "approval", gateId, correlationId, timeoutAt },
+                    pendingOp,
+                };
+            }
+            return { type: "allow" };
         },
     };
 }

package/dist/correlation.d.ts

@@ -18,6 +18,7 @@ export interface CorrelationValidator {
 export declare function createCorrelationRegistry(): {
     register: (op: PendingOperation) => void;
     lookup: (correlationId: string) => PendingOperation | undefined;
+    findByGateId: (gateId: string) => PendingOperation | undefined;
     remove: (correlationId: string) => boolean;
     all: () => PendingOperation[];
     hasAny: () => boolean;

package/dist/correlation.js

@@ -19,6 +19,13 @@ export function createCorrelationRegistry() {
     function lookup(correlationId) {
         return operations.get(correlationId);
     }
+    function findByGateId(gateId) {
+        for (const op of operations.values()) {
+            if (op.gateId === gateId)
+                return op;
+        }
+        return undefined;
+    }
     function remove(correlationId) {
         return operations.delete(correlationId);
     }
@@ -28,5 +35,5 @@ export function createCorrelationRegistry() {
     function hasAny() {
         return operations.size > 0;
     }
-    return { register, lookup, remove, all, hasAny };
+    return { register, lookup, findByGateId, remove, all, hasAny };
 }

package/dist/default-director.d.ts

@@ -1,4 +1,4 @@
-import type { ReactorDirector, ReactorInboundEvent, ReactorState, ReactorCapabilities, ReactorAction, AssistantTurn, ToolDefinition } from "@intx/types/runtime";
+import { type ReactorDirector, type ReactorInboundEvent, type ReactorState, type ReactorCapabilities, type ReactorAction, type AssistantTurn, type ToolDefinition } from "@intx/types/runtime";
 /**
  * Decision returned by an `afterInferenceDone` policy hook.
  *

package/dist/default-director.js

@@ -10,6 +10,8 @@
 //   inference.error           → checkpoint + reply (error message to user)
 //   abort                     → done
 //   reactor.gate.cleared      → checkpoint + infer (resume after gate)
+//   resume.execute_tools      → execute_tools (re-run a parked approved call)
+//   resume.tool_result        → checkpoint + infer (parked call denied/timed out)
 //
 // The inference.done branch additionally runs the optional afterInferenceDone
 // policy hook, whose continue/abort/halt decisions route independently of the
@@ -18,6 +20,7 @@
 // The director never throws. Inference errors are surfaced to the user as a
 // reply so the problem is visible, and the agent remains alive for retries.
 import { getLogger } from "@intx/log";
+import { formatSafetyRatingText, } from "@intx/types/runtime";
 const logger = getLogger(["interchange", "inference", "default-director"]);
 function extractToolCalls(turn) {
     const calls = [];
@@ -33,14 +36,13 @@ function extractToolCalls(turn) {
     return calls;
 }
 function extractTextContent(turn) {
-    // Both regular text and refusal blocks carry human-readable model
-    // output that the connector needs to surface — a refusal-only turn
-    // (OpenAI strict-mode policy decline) would otherwise route through
-    // the empty-response branch below and never reach the reply path,
-    // leaving the human waiting for an answer the model already
-    // declined to give. The structural "this was a refusal" signal is
-    // preserved at the persistence layer (event-collector emits a
-    // refusal turn-part); the reply path only needs the words.
+    // Text, refusal, and safety_rating blocks all carry human-readable
+    // output the connector needs to surface. A refusal-only or
+    // safety-only turn would otherwise route through the empty-response
+    // branch below and never reach the reply path, leaving the human
+    // waiting for an answer the model already declined or blocked.
+    // Structural part kinds are preserved at the persistence layer;
+    // the reply path only needs the words.
     const parts = [];
     for (const block of turn.content) {
         if (block.type === "text") {
@@ -49,6 +51,9 @@ function extractTextContent(turn) {
         else if (block.type === "refusal") {
             parts.push(block.reason);
         }
+        else if (block.type === "safety_rating") {
+            parts.push(formatSafetyRatingText(block));
+        }
     }
     return parts.join("\n").trim();
 }
@@ -151,6 +156,30 @@ export class DefaultDirector {
                 // stop (abort), never because the model produced an empty turn.
                 return [capabilities.checkpoint("inference-done"), capabilities.wait()];
             }
+            case "resume.execute_tools": {
+                // A resumed approval re-runs its parked tool call. The reactor drives
+                // the execution; this director owns the outstanding-result count, so
+                // seed it to the number of calls about to run — exactly as the
+                // inference.done branch seeds it for a fresh tool batch. Without this
+                // seed the count stays zero and the re-dispatched call's tool.done
+                // would decrement to -1 and re-infer off a negative count by accident.
+                this.pendingToolResults = event.calls.length;
+                return capabilities.executeTools(event.calls, false, true);
+            }
+            case "resume.tool_result": {
+                // A parked approval ended without running its tool (rejected or timed
+                // out). The reactor appends the synthetic error result that answers the
+                // parked call, then this re-infers once so the model sees the failure
+                // and continues. No tool ran, so pendingToolResults is untouched — the
+                // counter only gates batches of real executions.
+                return [
+                    capabilities.checkpoint("resume-tool-result"),
+                    capabilities.infer({
+                        systemPrompt: this.systemPrompt,
+                        tools: this.toolDefinitions,
+                    }),
+                ];
+            }
             case "tool.done": {
                 this.pendingToolResults--;
                 if (this.pendingToolResults > 0) {

package/dist/gates.d.ts

@@ -19,6 +19,7 @@ export type GateSnapshot = {
 export declare function createGateManager(): {
     register: (gateId: string, type: GateType, timeoutMs: number, correlationId: string | undefined, onCleared: (gateId: string, reason: "resolved" | "timeout" | "shutdown") => void) => Promise<"resolved" | "timeout" | "shutdown">;
     clear: (gateId: string) => boolean;
+    clearSilently: (gateId: string) => boolean;
     shutdown: () => void;
     findByCorrelationId: (correlationId: string) => GateRecord | undefined;
     snapshot: () => GateSnapshot[];

package/dist/gates.js

@@ -50,6 +50,21 @@ export function createGateManager() {
         gate.onCleared(gateId, "resolved");
         return true;
     }
+    // Clear a gate without invoking its onCleared callback. The caller has
+    // already decided how the reactor resumes and does not want the standard
+    // cleared-event enqueue that onCleared drives. Used by the approval
+    // re-dispatch path, which resumes by re-running the parked tool call rather
+    // than by re-inferring off a gate-cleared event: firing onCleared there
+    // would enqueue a second, spurious continuation.
+    function clearSilently(gateId) {
+        const gate = gates.get(gateId);
+        if (gate === undefined)
+            return false;
+        clearTimeout(gate.timer);
+        gates.delete(gateId);
+        gate.resolve("resolved");
+        return true;
+    }
     function shutdown() {
         const entries = Array.from(gates.values());
         gates.clear();
@@ -76,5 +91,13 @@ export function createGateManager() {
     function has(gateId) {
         return gates.has(gateId);
     }
-    return { register, clear, shutdown, findByCorrelationId, snapshot, has };
+    return {
+        register,
+        clear,
+        clearSilently,
+        shutdown,
+        findByCorrelationId,
+        snapshot,
+        has,
+    };
 }