prefix-safe-json 0.0.1-alpha.2 → 0.0.1-alpha.3

package/README.md

@@ -2,13 +2,77 @@
 
 > ⚠️ **Alpha** — This project is under active development. APIs may change without notice. Do not use in production.
 
-Incremental LLM tool-call JSON parser and deterministic repair engine.
+**Don't execute incomplete AI tool calls.**
+
+`prefix-safe-json` is a fail-closed integrity layer for streamed LLM tool
+calls. It distinguishes complete, unfabricated arguments from truncated
+ones — including ones a syntax-level JSON repairer can make *look* complete
+— before they reach a tool with real side effects (writing a file, running a
+command, sending a request).
+
+```
+model output truncated
+        ↓
+    json repair
+        ↓
+    looks valid
+        ↓
+❌ dangerous execution
+```
+
+```
+   prefix-safe-json
+        ↓
+      truncated
+        ↓
+  executable: false
+        ↓
+        retry
+```
 
 ![Demo: a tool call truncated mid-argument is correctly reported non-executable, while the same call delivered in full is reported executable](examples/demo.gif)
 
 *(Real terminal output from [`examples/anthropic-truncation-safety.mjs`](examples/anthropic-truncation-safety.mjs) — not staged. Same script CI runs on every push.)*
 
-## Problem
+## Quick start: the execution safety gate
+
+The highest-level API answers one question per tool call — is it safe to
+execute right now — without requiring you to know anything about parser
+state, coordinator events, or JSON Pointers:
+
+```typescript
+import { createToolCallExecutionGate, AnthropicStreamAdapter } from "prefix-safe-json";
+
+const gate = createToolCallExecutionGate(undefined, undefined, {
+  write_file: {
+    type: "object",
+    properties: { path: { type: "string" }, content: { type: "string" } },
+    required: ["path", "content"],
+  },
+});
+const adapter = new AnthropicStreamAdapter();
+
+for (const rawEvent of anthropicSseEvents) {
+  for (const normalized of adapter.push(rawEvent)) gate.push(normalized);
+}
+
+for (const decision of gate.finish().decisions) {
+  if (decision.action === "execute") {
+    await tools[decision.name](decision.value);
+  } else {
+    console.warn(`${decision.name}: ${decision.action} (${decision.reason})`); // "retry" or "reject"
+  }
+}
+```
+
+Provider adapters exist for OpenAI, Anthropic, Gemini, OpenRouter,
+OpenAI-compatible endpoints, and the [Vercel AI SDK](https://ai-sdk.dev)
+(`ai` package — not a dependency of this library; see
+[`examples/ai-sdk-execution-gate.mjs`](examples/ai-sdk-execution-gate.mjs)).
+Full semantics, the decision table, and provider finish-reason mapping:
+[`docs/EXECUTION_GATE.md`](docs/EXECUTION_GATE.md).
+
+## The lower-level problem this is built on
 
 LLM providers (OpenAI, Anthropic, Gemini, OpenRouter) stream tool-call arguments as small JSON chunks. During streaming, the JSON is frequently incomplete: strings split mid-word, UTF-8 characters split mid-byte, containers left unclosed, numbers terminated at chunk boundaries.
 
@@ -98,6 +162,25 @@ draws exactly that distinction (`outcome: "truncated"`) and could gate
 execution on it without touching the syntax-repair behavior for the other
 case.
 
+## Scope: what this does and doesn't protect against
+
+This library is honestly scoped as **execution integrity** — complete,
+unfabricated, schema-valid arguments — not a general "AI security platform."
+It does **not**:
+
+- defend against prompt injection (it says nothing about whether the
+  arguments a model *chose* to send are the arguments it *should* have
+  sent — only whether they're complete and unfabricated)
+- resolve authorization (it doesn't know which caller may invoke which tool)
+- sandbox execution (`action: "execute"` means "this is genuinely the
+  complete value the model produced," not "safe to run without your own
+  validation and permissions")
+- detect a malicious or wrong tool choice (a model calling the wrong tool
+  with complete, schema-valid arguments is still reported `execute`)
+
+See [`docs/EXECUTION_GATE.md`](docs/EXECUTION_GATE.md#limitations---what-this-does-not-protect-against)
+for the full list, including known internal limitations.
+
 ## Current Status (Alpha)
 
 ### Implemented
@@ -111,8 +194,9 @@ case.
 - Configurable resource limits (depth, input size, string length, queued events)
 - Machine-readable test corpus with 25+ canonical fixtures
 - Chunk invariance verification
-- Provider stream adapters for OpenAI (legacy `function_call` and Responses API), Anthropic, Gemini, OpenRouter, and generic OpenAI-compatible endpoints, plus a coordinator for tracking multiple concurrent tool-call streams
+- Provider stream adapters for OpenAI (legacy `function_call` and Responses API), Anthropic, Gemini, OpenRouter, generic OpenAI-compatible endpoints, and the Vercel AI SDK, plus a coordinator for tracking multiple concurrent tool-call streams
 - Optional per-tool JSON Schema validation on the coordinator (see below) — a value can be structurally complete and still not match what a tool declared it needs
+- `createToolCallExecutionGate()` — a fail-closed `execute` / `retry` / `reject` decision per tool call, built on top of the coordinator (see [`docs/EXECUTION_GATE.md`](docs/EXECUTION_GATE.md))
 
 ### Not Yet Implemented
 
@@ -155,7 +239,11 @@ A schema mismatch also surfaces as a coordinator diagnostic (`E_SCHEMA_VALIDATIO
 npm install prefix-safe-json
 ```
 
-## Quick Start
+## Low-level API: Quick Start
+
+The execution gate (above) is what most consumers want. The low-level
+`createParser()` API it's built on is also fully public, for anyone who
+needs direct access to parser state:
 
 ```typescript
 import { createParser } from "prefix-safe-json";
@@ -192,6 +280,12 @@ and asserts the truncated call is never reported executable while a
 genuinely complete one is. This example runs in CI on every push, so it
 can't silently rot into a stale claim.
 
+For the same demonstration through the high-level execution gate and the
+[Vercel AI SDK](https://ai-sdk.dev)'s `fullStream` shape instead, see
+[`examples/ai-sdk-execution-gate.mjs`](examples/ai-sdk-execution-gate.mjs)
+(`node examples/ai-sdk-execution-gate.mjs` after `pnpm run build`) — also
+run in CI on every push.
+
 ## License
 
 Licensed under either of:

package/dist/coordinator/diagnostic-codes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Emitted (as a stream-wide `provider_diagnostic`, no `callRef`) by a
+ * provider adapter when the underlying provider reports that generation was
+ * stopped by a content-safety/policy filter, as opposed to a generic
+ * cancellation. The execution gate matches on this to return a distinct
+ * `reason: "content_filtered"` rather than lumping it in with ordinary
+ * incomplete-stream retries - a policy termination should not be retried
+ * blindly.
+ */
+export declare const CONTENT_FILTERED_DIAGNOSTIC_CODE = "E_CONTENT_FILTERED";
+//# sourceMappingURL=diagnostic-codes.d.ts.map

package/dist/coordinator/diagnostic-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-codes.d.ts","sourceRoot":"","sources":["../../src/coordinator/diagnostic-codes.ts"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,uBAAuB,CAAC"}

package/dist/coordinator/diagnostic-codes.js

@@ -0,0 +1,22 @@
+// ---------------------------------------------------------------------------
+// Cross-module coordinator-level diagnostic codes.
+//
+// Most coordinator diagnostics (see coordinator.ts) are inline string
+// literals local to wherever they're raised - there's no central registry,
+// unlike the parser-level `DiagnosticCode` in diagnostics/codes.ts. This
+// file exists only for the handful of codes that a provider adapter raises
+// and something *outside* that adapter (e.g. the execution gate) needs to
+// recognize by exact code, where a shared constant is safer than either
+// module guessing the other's string literal.
+// ---------------------------------------------------------------------------
+/**
+ * Emitted (as a stream-wide `provider_diagnostic`, no `callRef`) by a
+ * provider adapter when the underlying provider reports that generation was
+ * stopped by a content-safety/policy filter, as opposed to a generic
+ * cancellation. The execution gate matches on this to return a distinct
+ * `reason: "content_filtered"` rather than lumping it in with ordinary
+ * incomplete-stream retries - a policy termination should not be retried
+ * blindly.
+ */
+export const CONTENT_FILTERED_DIAGNOSTIC_CODE = "E_CONTENT_FILTERED";
+//# sourceMappingURL=diagnostic-codes.js.map

package/dist/coordinator/diagnostic-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-codes.js","sourceRoot":"","sources":["../../src/coordinator/diagnostic-codes.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mDAAmD;AACnD,EAAE;AACF,sEAAsE;AACtE,2EAA2E;AAC3E,yEAAyE;AACzE,2EAA2E;AAC3E,0EAA0E;AAC1E,wEAAwE;AACxE,8CAA8C;AAC9C,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,oBAAoB,CAAC"}

package/dist/coordinator/protocol.d.ts

@@ -1,4 +1,4 @@
-export type ProviderName = "openai" | "anthropic" | "gemini" | "openrouter" | "openai-compatible" | "unknown";
+export type ProviderName = "openai" | "anthropic" | "gemini" | "openrouter" | "openai-compatible" | "ai-sdk" | "unknown";
 export interface NormalizedEventBase {
     /**
      * Deterministic sequence number assigned by the stream coordinator.

package/dist/coordinator/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/coordinator/protocol.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,mBAAmB,GACnB,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,MAAM,yBAAyB,GACjC,kBAAkB,GAClB,qBAAqB,GACrB,sBAAsB,GACtB,2BAA2B,GAC3B,gBAAgB,GAChB,uBAAuB,GACvB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,2BAA4B,SAAQ,mBAAmB;IACtE,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;CACrC;AAED,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,QAAQ,GACR,WAAW,GACX,gBAAgB,GAChB,eAAe,GACf,SAAS,CAAC;AAEd,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC3D,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;CACpC;AAED,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/coordinator/protocol.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,WAAW,GACX,QAAQ,GACR,YAAY,GACZ,mBAAmB,GACnB,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,MAAM,yBAAyB,GACjC,kBAAkB,GAClB,qBAAqB,GACrB,sBAAsB,GACtB,2BAA2B,GAC3B,gBAAgB,GAChB,uBAAuB,GACvB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAElC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,2BAA4B,SAAQ,mBAAmB;IACtE,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;CACrC;AAED,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,QAAQ,GACR,WAAW,GACX,gBAAgB,GAChB,eAAe,GACf,SAAS,CAAC;AAEd,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC3D,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;CACpC;AAED,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/gate/decide.d.ts

@@ -0,0 +1,20 @@
+import { CoordinatorDiagnostic, ToolCallState } from "../coordinator/types.js";
+import { StreamEndReason } from "../coordinator/protocol.js";
+import { ExecuteDecision, NonExecutableDecision } from "./types.js";
+export interface DecisionContext {
+    /**
+     * The stream-level end reason - what actually happened to the underlying
+     * provider stream, not any single call's own (possibly still-"collecting")
+     * status. Stream-wide fail-closed conditions (provider_error) key off this
+     * rather than per-call state.
+     */
+    readonly streamEndReason: StreamEndReason;
+    /**
+     * The coordinator's full, unfiltered diagnostics list (`snapshot().diagnostics`).
+     * `decideExecution` splits this into per-call (`internalId` matches) and
+     * global (`internalId` undefined) subsets itself.
+     */
+    readonly diagnostics: readonly CoordinatorDiagnostic[];
+}
+export declare function decideExecution(call: ToolCallState, ctx: DecisionContext): ExecuteDecision | NonExecutableDecision;
+//# sourceMappingURL=decide.d.ts.map

package/dist/gate/decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../../src/gate/decide.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,EAAE,eAAe,EAAmB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAErF,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAE1C;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACxD;AAeD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,aAAa,EACnB,GAAG,EAAE,eAAe,GACnB,eAAe,GAAG,qBAAqB,CAmHzC"}

package/dist/gate/decide.js

@@ -0,0 +1,127 @@
+// ---------------------------------------------------------------------------
+// Pure execution-decision mapping.
+//
+// Deliberately a standalone function (no coordinator/adapter dependency) so
+// the entire decision table can be unit-tested directly against hand-built
+// ToolCallState fixtures, without spinning up a full push()/finish()
+// pipeline for every row of the table.
+//
+// Priority order matters and is intentional: every fail-closed disqualifier
+// (resource limits, provider errors, content-policy terminations, schema
+// mismatches, malformed content, positively-observed truncation) is checked
+// before the single positive "execute" branch. "execute" is reached only
+// once nothing above has disqualified the call - it is the last positive
+// case, never the first check made, so a future status value that happens
+// to superficially resemble "complete" still can't skip the checks ahead of
+// it.
+// ---------------------------------------------------------------------------
+import { DiagnosticCode } from "../diagnostics/codes.js";
+import { CONTENT_FILTERED_DIAGNOSTIC_CODE } from "../coordinator/diagnostic-codes.js";
+const PARSER_RESOURCE_LIMIT_CODES = new Set([
+    DiagnosticCode.E_LIMIT_DEPTH,
+    DiagnosticCode.E_LIMIT_INPUT_BYTES,
+    DiagnosticCode.E_LIMIT_STRING_BYTES,
+    DiagnosticCode.E_LIMIT_EVENT_QUEUE,
+]);
+const COORDINATOR_RESOURCE_LIMIT_CODES = new Set([
+    "E_COORDINATOR_LIMIT_CALLS",
+    "E_COORDINATOR_LIMIT_EVENTS",
+    "E_TOOL_NAME_LIMIT",
+]);
+export function decideExecution(call, ctx) {
+    const parserDiagnostics = call.parser.diagnostics;
+    const callCoordinatorDiagnostics = ctx.diagnostics.filter((d) => d.internalId === call.internalId);
+    const globalCoordinatorDiagnostics = ctx.diagnostics.filter((d) => d.internalId === undefined);
+    const coordinatorDiagnostics = [
+        ...globalCoordinatorDiagnostics,
+        ...callCoordinatorDiagnostics,
+    ];
+    const common = {
+        internalId: call.internalId,
+        toolCallId: call.toolCallId,
+        toolIndex: call.toolIndex,
+        name: call.name,
+        stableValue: call.parser.stableValue,
+        parserDiagnostics,
+        coordinatorDiagnostics,
+    };
+    function reject(reason) {
+        return { ...common, action: "reject", executable: false, reason };
+    }
+    function retry(reason) {
+        return { ...common, action: "retry", executable: false, reason };
+    }
+    // --- Universal fail-closed checks ---------------------------------------
+    // Evaluated first and unconditionally, regardless of call.status, so a
+    // resource limit, a provider-side failure, or a content-policy
+    // termination always wins over whatever the structural status looks like.
+    const hasResourceLimit = parserDiagnostics.some((d) => PARSER_RESOURCE_LIMIT_CODES.has(d.code)) ||
+        callCoordinatorDiagnostics.some((d) => COORDINATOR_RESOURCE_LIMIT_CODES.has(d.code)) ||
+        globalCoordinatorDiagnostics.some((d) => d.code === "E_COORDINATOR_LIMIT_EVENTS");
+    if (hasResourceLimit) {
+        return reject("resource_limit");
+    }
+    if (ctx.streamEndReason === "provider_error") {
+        return reject("provider_error");
+    }
+    const isContentFiltered = globalCoordinatorDiagnostics.some((d) => d.code === CONTENT_FILTERED_DIAGNOSTIC_CODE);
+    if (isContentFiltered) {
+        return reject("content_filtered");
+    }
+    // --- Status-specific handling --------------------------------------------
+    // Exhaustive over ToolCallState["status"] with no `default`: if a future
+    // coordinator version adds a new status literal without a matching case
+    // here, `noImplicitReturns` fails the build - not a silent runtime gap.
+    switch (call.status) {
+        case "complete": {
+            if (call.schemaValid === false) {
+                return reject("schema_invalid");
+            }
+            // The ONLY positive branch in this entire function, reached only
+            // after every disqualifying check above has already passed. The
+            // `call.name !== undefined` check is defensive/redundant with the
+            // coordinator's own invariant (a call only reaches status "complete"
+            // when its name is known) - narrowing on it here is what lets
+            // `ExecuteDecision.name` be typed as a required `string` instead of
+            // `string | undefined`, so it never needs re-checking at every call
+            // site. If the invariant were ever violated, this still fails closed
+            // to "stream_incomplete" rather than fabricating a name.
+            if (call.parser.executable === true &&
+                call.parser.stableValue !== undefined &&
+                call.name !== undefined) {
+                const decision = {
+                    ...common,
+                    name: call.name,
+                    action: "execute",
+                    executable: true,
+                    reason: "complete",
+                    value: call.parser.stableValue,
+                };
+                return decision;
+            }
+            // Root closed, syntactically valid, but not trusted: the parser's
+            // own executable contract failed it (stream-end-reason mismatch or
+            // trailing data), even though nothing here required a repair.
+            return retry("stream_incomplete");
+        }
+        case "truncated":
+            // The parser positively observed an open string/number/literal or an
+            // unclosed container - a real, raw mid-value cut, not a matter of
+            // interpretation.
+            return retry("truncated");
+        case "invalid":
+            // Duplicate key, unexpected token, or a missing/conflicting tool
+            // identity - a genuine content defect, independent of how the stream
+            // ended.
+            return reject("malformed");
+        case "salvaged":
+            // Root only closed via a safe-container-closing repair; the JSON
+            // *looks* complete, but provider metadata never confirmed genuine
+            // completion. This is the container-level truncation case.
+            return retry("stream_incomplete");
+        case "cancelled":
+        case "collecting":
+            return retry("stream_incomplete");
+    }
+}
+//# sourceMappingURL=decide.js.map

package/dist/gate/decide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.js","sourceRoot":"","sources":["../../src/gate/decide.ts"],"names":[],"mappings":"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"}

package/dist/gate/gate.d.ts

@@ -0,0 +1,25 @@
+import { CoordinatorLimits, JsonSchemaLike } from "../coordinator/types.js";
+import { ParserOptions } from "../types.js";
+import { ToolCallExecutionGate } from "./types.js";
+/**
+ * Creates a fail-closed execution-decision gate for streamed LLM tool calls.
+ * Wraps a `ToolCallStreamCoordinator` (same constructor arguments) and adds
+ * exactly one operation: turn each call's settled state into an
+ * `ExecutionDecision` (`execute` / `retry` / `reject`) via a deterministic,
+ * fully-typed decision table. See `docs/EXECUTION_GATE.md`.
+ *
+ * ```ts
+ * const gate = createToolCallExecutionGate(undefined, undefined, {
+ *   write_file: { type: "object", required: ["path", "content"], properties: {
+ *     path: { type: "string" }, content: { type: "string" } } },
+ * });
+ * for (const raw of providerEvents) {
+ *   for (const normalized of adapter.push(raw)) gate.push(normalized);
+ * }
+ * for (const decision of gate.finish().decisions) {
+ *   if (decision.action === "execute") await tools[decision.name](decision.value);
+ * }
+ * ```
+ */
+export declare function createToolCallExecutionGate(limits?: Partial<CoordinatorLimits>, parserOptions?: ParserOptions, toolSchemas?: Record<string, JsonSchemaLike>): ToolCallExecutionGate;
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/gate/gate.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,iBAAiB,EAEjB,cAAc,EAGf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAEL,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AA+DpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,EACnC,aAAa,CAAC,EAAE,aAAa,EAC7B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAC3C,qBAAqB,CAEvB"}

package/dist/gate/gate.js

@@ -0,0 +1,80 @@
+// ---------------------------------------------------------------------------
+// ToolCallExecutionGate — high-level execution safety layer.
+//
+// Built by composition over ToolCallStreamCoordinator, not by extending or
+// reimplementing it: the gate holds a coordinator instance and adds exactly
+// one thing coordinator state doesn't already capture - which stream-end
+// reason actually got applied - then maps every ToolCallState through the
+// pure decideExecution() table. No re-parsing, no duplicate event pipeline.
+// ---------------------------------------------------------------------------
+import { createToolCallStreamCoordinator } from "../coordinator/coordinator.js";
+import { decideExecution } from "./decide.js";
+class DefaultToolCallExecutionGate {
+    coordinator;
+    // Mirrors the coordinator's own "first provider_stream_end (from push(),
+    // or from finish()'s meta if none arrived) wins" rule - see push()/finish()
+    // below and DefaultToolCallStreamCoordinator.finish()'s matching
+    // `if (!this.isFinished)` guard.
+    streamEndReason;
+    streamEndCaptured = false;
+    constructor(limits, parserOptions, toolSchemas) {
+        this.coordinator = createToolCallStreamCoordinator(limits, parserOptions, toolSchemas);
+    }
+    push(event) {
+        if (event.type === "provider_stream_end" && !this.streamEndCaptured) {
+            this.streamEndCaptured = true;
+            this.streamEndReason = event.reason;
+        }
+        return this.coordinator.push(event);
+    }
+    snapshot() {
+        const snap = this.coordinator.snapshot();
+        const ctx = {
+            // Pre-finish, no stream-end reason has been observed yet ("unknown"
+            // is a neutral placeholder here, not a claim anything went wrong) -
+            // every in-flight call is still "collecting" regardless, so this
+            // never influences whether something looks executable.
+            streamEndReason: this.streamEndReason ?? "unknown",
+            diagnostics: snap.diagnostics,
+        };
+        return snap.calls.map((call) => decideExecution(call, ctx));
+    }
+    drainEvents() {
+        return this.coordinator.drainEvents();
+    }
+    finish(meta) {
+        if (!this.streamEndCaptured) {
+            this.streamEndCaptured = true;
+            this.streamEndReason = meta?.reason ?? "unknown";
+        }
+        const result = this.coordinator.finish(meta);
+        const diagnostics = this.coordinator.snapshot().diagnostics;
+        const ctx = { streamEndReason: this.streamEndReason ?? "unknown", diagnostics };
+        const decisions = result.calls.map((call) => decideExecution(call, ctx));
+        return { decisions, diagnostics };
+    }
+}
+/**
+ * Creates a fail-closed execution-decision gate for streamed LLM tool calls.
+ * Wraps a `ToolCallStreamCoordinator` (same constructor arguments) and adds
+ * exactly one operation: turn each call's settled state into an
+ * `ExecutionDecision` (`execute` / `retry` / `reject`) via a deterministic,
+ * fully-typed decision table. See `docs/EXECUTION_GATE.md`.
+ *
+ * ```ts
+ * const gate = createToolCallExecutionGate(undefined, undefined, {
+ *   write_file: { type: "object", required: ["path", "content"], properties: {
+ *     path: { type: "string" }, content: { type: "string" } } },
+ * });
+ * for (const raw of providerEvents) {
+ *   for (const normalized of adapter.push(raw)) gate.push(normalized);
+ * }
+ * for (const decision of gate.finish().decisions) {
+ *   if (decision.action === "execute") await tools[decision.name](decision.value);
+ * }
+ * ```
+ */
+export function createToolCallExecutionGate(limits, parserOptions, toolSchemas) {
+    return new DefaultToolCallExecutionGate(limits, parserOptions, toolSchemas);
+}
+//# sourceMappingURL=gate.js.map

package/dist/gate/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/gate/gate.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,6DAA6D;AAC7D,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,yEAAyE;AACzE,0EAA0E;AAC1E,4EAA4E;AAC5E,8EAA8E;AAE9E,OAAO,EAAE,+BAA+B,EAAE,MAAM,+BAA+B,CAAC;AAUhF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAO9C,MAAM,4BAA4B;IACf,WAAW,CAA4B;IAExD,yEAAyE;IACzE,4EAA4E;IAC5E,iEAAiE;IACjE,iCAAiC;IACzB,eAAe,CAA8B;IAC7C,iBAAiB,GAAG,KAAK,CAAC;IAElC,YACE,MAAmC,EACnC,aAA6B,EAC7B,WAA4C;QAE5C,IAAI,CAAC,WAAW,GAAG,+BAA+B,CAAC,MAAM,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC;IACzF,CAAC;IAED,IAAI,CAAC,KAAgC;QACnC,IAAI,KAAK,CAAC,IAAI,KAAK,qBAAqB,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACpE,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;YAC9B,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,MAAM,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,QAAQ;QACN,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG;YACV,oEAAoE;YACpE,oEAAoE;YACpE,iEAAiE;YACjE,uDAAuD;YACvD,eAAe,EAAE,IAAI,CAAC,eAAe,IAAI,SAAS;YAClD,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC;IACxC,CAAC;IAED,MAAM,CAAC,IAGN;QACC,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAC5B,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;YAC9B,IAAI,CAAC,eAAe,GAAG,IAAI,EAAE,MAAM,IAAI,SAAS,CAAC;QACnD,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,WAAW,CAAC;QAC5D,MAAM,GAAG,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe,IAAI,SAAS,EAAE,WAAW,EAAE,CAAC;QAChF,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;QAEzE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;IACpC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAAmC,EACnC,aAA6B,EAC7B,WAA4C;IAE5C,OAAO,IAAI,4BAA4B,CAAC,MAAM,EAAE,aAAa,EAAE,WAAW,CAAC,CAAC;AAC9E,CAAC"}

package/dist/gate/types.d.ts

@@ -0,0 +1,122 @@
+import { JsonValue, Diagnostic } from "../types.js";
+import { CoordinatorDiagnostic, CoordinatorPushResult, ToolCallCoordinatorEvent } from "../coordinator/types.js";
+import { NormalizedToolStreamEvent, StreamEndReason } from "../coordinator/protocol.js";
+/**
+ * What to do with a tool call right now.
+ *
+ * - `"execute"`: the arguments are complete, unfabricated, and (if a schema
+ *   was registered for this tool) schema-valid. Safe to run.
+ * - `"retry"`: the provider's output was incomplete or truncated. There is
+ *   nothing wrong with the data received so far - there just isn't a
+ *   trustworthy complete value yet. Re-request/continue generation.
+ * - `"reject"`: the data itself is the problem (malformed JSON, a schema
+ *   mismatch, a resource limit, a provider-side error, or a content-policy
+ *   termination). Re-sending the exact same partial input will not fix it.
+ */
+export type ExecutionAction = "execute" | "retry" | "reject";
+/**
+ * Machine-readable classification of *why* an `ExecutionAction` was chosen.
+ * See `docs/EXECUTION_GATE.md` for the full decision table.
+ */
+export type ExecutionReason = "complete" | "truncated" | "stream_incomplete" | "schema_invalid" | "malformed" | "resource_limit" | "provider_error" | "content_filtered" | "unknown";
+interface ExecutionDecisionCommon {
+    /** The coordinator's internal call identifier (see `ToolCallState.internalId`). */
+    readonly internalId: string;
+    readonly toolCallId?: string;
+    readonly toolIndex?: number;
+    readonly name?: string;
+    /**
+     * Whatever was safely committed for this call, complete or not - present
+     * for both executable and non-executable decisions so a caller can see
+     * *what part* of a rejected/retried call was genuinely received (e.g. a
+     * `path` field that arrived before a `content` field got cut off).
+     * Never the source of truth for whether it's safe to act on - that's
+     * `action`/`executable`. Absent only when nothing was ever committed.
+     */
+    readonly stableValue?: JsonValue;
+    /** This call's own parser diagnostics, verbatim (`ToolCallState.parser.diagnostics`). */
+    readonly parserDiagnostics: readonly Diagnostic[];
+    /** Coordinator-level diagnostics attributable to this call, verbatim. */
+    readonly coordinatorDiagnostics: readonly CoordinatorDiagnostic[];
+}
+/**
+ * The one and only shape a decision can have when `action === "execute"`.
+ * `value` is a real, present `JsonValue` here - never `undefined`, never
+ * optional - because this is the single positive case: everything else in
+ * the gate exists to rule this out unless it's genuinely earned.
+ */
+export interface ExecuteDecision extends ExecutionDecisionCommon {
+    readonly action: "execute";
+    readonly executable: true;
+    readonly reason: "complete";
+    readonly value: JsonValue;
+    /**
+     * Narrowed to required here (unlike the inherited `name?: string`):
+     * the coordinator only ever transitions a call to `status: "complete"`
+     * when `name` is defined (see `DefaultToolCallStreamCoordinator.finishCall`
+     * - a call with no name is forced to `"invalid"` instead), so every
+     * `ExecuteDecision` genuinely has one. Encoding that here means
+     * `tools[decision.name](decision.value)` type-checks directly after
+     * narrowing on `action === "execute"`, with no non-null assertion needed.
+     */
+    readonly name: string;
+}
+/**
+ * Every other outcome. `value` does not exist on this type at all (not
+ * `undefined` - absent) - TypeScript itself refuses code that reads a
+ * "final executable value" off a call the gate did not clear for execution.
+ */
+export interface NonExecutableDecision extends ExecutionDecisionCommon {
+    readonly action: "retry" | "reject";
+    readonly executable: false;
+    readonly reason: Exclude<ExecutionReason, "complete">;
+}
+/**
+ * `ExecuteDecision | NonExecutableDecision` - a discriminated union on
+ * `action` (and redundantly on `executable`, for callers who prefer that
+ * check). Narrowing on either field gives you the right shape:
+ *
+ * ```ts
+ * if (decision.action === "execute") {
+ *   await tools[decision.name](decision.value); // JsonValue, not JsonValue|undefined
+ * }
+ * ```
+ */
+export type ExecutionDecision = ExecuteDecision | NonExecutableDecision;
+export interface ToolCallExecutionGateFinalResult {
+    /** One decision per tool call the coordinator ever created. */
+    readonly decisions: readonly ExecutionDecision[];
+    /**
+     * The full, unfiltered coordinator diagnostics list (same as
+     * `coordinator.snapshot().diagnostics`) - includes diagnostics with no
+     * associated call, e.g. `E_COORDINATOR_LIMIT_CALLS` fires for a call that
+     * hit the concurrent-call limit before a `ToolCallState` could even be
+     * created for it, so it can never appear in `decisions`.
+     */
+    readonly diagnostics: readonly CoordinatorDiagnostic[];
+}
+/**
+ * High-level fail-closed execution decision layer built on top of
+ * `ToolCallStreamCoordinator`. Answers one question per tool call: is it
+ * safe to execute right now? Callers never need to touch parser lexical
+ * state, coordinator event mechanics, or JSON Pointer paths - push provider
+ * events in, read `ExecutionDecision`s out.
+ */
+export interface ToolCallExecutionGate {
+    push(event: NormalizedToolStreamEvent): CoordinatorPushResult;
+    /**
+     * In-flight view. Every decision here is `"retry"` or `"reject"` -
+     * `"execute"` is only ever returned once the stream has genuinely
+     * finished (see `finish()`), since schema validity and prefix-safety are
+     * both only meaningful once a call has settled.
+     */
+    snapshot(): readonly ExecutionDecision[];
+    /** Drains the underlying coordinator's raw event queue, for advanced/UI consumers. */
+    drainEvents(): readonly ToolCallCoordinatorEvent[];
+    finish(meta?: {
+        reason?: StreamEndReason;
+        providerReason?: string;
+    }): ToolCallExecutionGateFinalResult;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/gate/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/gate/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAExF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE7D;;;GAGG;AACH,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,WAAW,GACX,mBAAmB,GACnB,gBAAgB,GAChB,WAAW,GACX,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,SAAS,CAAC;AAEd,UAAU,uBAAuB;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC;IAEjC,yFAAyF;IACzF,QAAQ,CAAC,iBAAiB,EAAE,SAAS,UAAU,EAAE,CAAC;IAElD,yEAAyE;IACzE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACnE;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAgB,SAAQ,uBAAuB;IAC9D,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAE1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;CACvD;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,eAAe,GAAG,qBAAqB,CAAC;AAExE,MAAM,WAAW,gCAAgC;IAC/C,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAEjD;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACxD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,KAAK,EAAE,yBAAyB,GAAG,qBAAqB,CAAC;IAE9D;;;;;OAKG;IACH,QAAQ,IAAI,SAAS,iBAAiB,EAAE,CAAC;IAEzC,sFAAsF;IACtF,WAAW,IAAI,SAAS,wBAAwB,EAAE,CAAC;IAEnD,MAAM,CAAC,IAAI,CAAC,EAAE;QACZ,MAAM,CAAC,EAAE,eAAe,CAAC;QACzB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GAAG,gCAAgC,CAAC;CACtC"}

package/dist/gate/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/gate/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/gate/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -11,8 +11,17 @@ export { DiagnosticCode } from "./diagnostics/codes.js";
  * Creates a stream coordinator for mapping overlapping multi-tool streams.
  */
 export { createToolCallStreamCoordinator } from "./coordinator/coordinator.js";
-export type { ToolCallStreamCoordinator, ToolCallState, JsonSchemaLike, } from "./coordinator/types.js";
-export type { NormalizedToolStreamEvent } from "./coordinator/protocol.js";
+export type { ToolCallStreamCoordinator, ToolCallState, JsonSchemaLike, CoordinatorLimits, CoordinatorDiagnostic, } from "./coordinator/types.js";
+export type { NormalizedToolStreamEvent, ProviderName } from "./coordinator/protocol.js";
+export { CONTENT_FILTERED_DIAGNOSTIC_CODE } from "./coordinator/diagnostic-codes.js";
+/**
+ * @public (Stable)
+ * Fail-closed execution-decision layer built on top of the coordinator.
+ * Answers one question per tool call: is it safe to execute right now?
+ * See docs/EXECUTION_GATE.md.
+ */
+export { createToolCallExecutionGate } from "./gate/gate.js";
+export type { ToolCallExecutionGate, ToolCallExecutionGateFinalResult, ExecutionDecision, ExecuteDecision, NonExecutableDecision, ExecutionAction, ExecutionReason, } from "./gate/types.js";
 export type { ProviderStreamAdapter } from "./providers/adapter.js";
 /**
  * @public (Experimental)
@@ -24,4 +33,5 @@ export { OpenAICompatibleStreamAdapter } from "./providers/openai-compatible.js"
 export { AnthropicStreamAdapter } from "./providers/anthropic.js";
 export { GeminiStreamAdapter } from "./providers/gemini.js";
 export { OpenRouterStreamAdapter } from "./providers/openrouter.js";
+export { AiSdkStreamAdapter } from "./providers/ai-sdk.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,YAAY,EAEV,qBAAqB,EACrB,aAAa,EAGb,UAAU,EACV,cAAc,EACd,WAAW,EAGX,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EAGnB,SAAS,EACT,UAAU,EACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD;;;GAGG;AACH,OAAO,EAAE,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAC/E,YAAY,EACV,yBAAyB,EACzB,aAAa,EACb,cAAc,GACf,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAG3E,YAAY,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,YAAY,EAEV,qBAAqB,EACrB,aAAa,EAGb,UAAU,EACV,cAAc,EACd,WAAW,EAGX,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EAGnB,SAAS,EACT,UAAU,EACV,SAAS,EACT,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,YAAY,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAGxD;;;GAGG;AACH,OAAO,EAAE,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAC/E,YAAY,EACV,yBAAyB,EACzB,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,yBAAyB,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzF,OAAO,EAAE,gCAAgC,EAAE,MAAM,mCAAmC,CAAC;AAGrF;;;;;GAKG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAC7D,YAAY,EACV,qBAAqB,EACrB,gCAAgC,EAChC,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -14,6 +14,15 @@ export { DiagnosticCode } from "./diagnostics/codes.js";
  * Creates a stream coordinator for mapping overlapping multi-tool streams.
  */
 export { createToolCallStreamCoordinator } from "./coordinator/coordinator.js";
+export { CONTENT_FILTERED_DIAGNOSTIC_CODE } from "./coordinator/diagnostic-codes.js";
+// Execution Safety Gate API
+/**
+ * @public (Stable)
+ * Fail-closed execution-decision layer built on top of the coordinator.
+ * Answers one question per tool call: is it safe to execute right now?
+ * See docs/EXECUTION_GATE.md.
+ */
+export { createToolCallExecutionGate } from "./gate/gate.js";
 /**
  * @public (Experimental)
  * Provider adapters for various LLM network shapes.
@@ -24,4 +33,5 @@ export { OpenAICompatibleStreamAdapter } from "./providers/openai-compatible.js"
 export { AnthropicStreamAdapter } from "./providers/anthropic.js";
 export { GeminiStreamAdapter } from "./providers/gemini.js";
 export { OpenRouterStreamAdapter } from "./providers/openrouter.js";
+export { AiSdkStreamAdapter } from "./providers/ai-sdk.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAiC3C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,kBAAkB;AAClB;;;GAGG;AACH,OAAO,EAAE,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAW/E;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAE9E;;;GAGG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAiC3C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,kBAAkB;AAClB;;;GAGG;AACH,OAAO,EAAE,+BAA+B,EAAE,MAAM,8BAA8B,CAAC;AAS/E,OAAO,EAAE,gCAAgC,EAAE,MAAM,mCAAmC,CAAC;AAErF,4BAA4B;AAC5B;;;;;GAKG;AACH,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAc7D;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,kCAAkC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/providers/ai-sdk.d.ts

@@ -0,0 +1,54 @@
+import { ProviderName, NormalizedToolStreamEvent, StreamEndReason } from "../coordinator/protocol.js";
+import { ProviderStreamAdapter } from "./adapter.js";
+interface AiSdkToolInputStartPart {
+    type: "tool-input-start";
+    id?: string;
+    toolCallId?: string;
+    toolName?: string;
+}
+interface AiSdkToolInputDeltaPart {
+    type: "tool-input-delta";
+    id?: string;
+    toolCallId?: string;
+    delta?: string;
+}
+interface AiSdkToolInputEndPart {
+    type: "tool-input-end";
+    id?: string;
+    toolCallId?: string;
+}
+interface AiSdkToolCallPart {
+    type: "tool-call";
+    toolCallId?: string;
+    toolName?: string;
+}
+interface AiSdkToolErrorPart {
+    type: "tool-error";
+    toolCallId?: string;
+    toolName?: string;
+    error?: unknown;
+}
+interface AiSdkFinishPart {
+    type: "finish";
+    finishReason?: string;
+}
+interface AiSdkErrorPart {
+    type: "error";
+    error?: unknown;
+}
+export type AiSdkStreamPart = AiSdkToolInputStartPart | AiSdkToolInputDeltaPart | AiSdkToolInputEndPart | AiSdkToolCallPart | AiSdkToolErrorPart | AiSdkFinishPart | AiSdkErrorPart | {
+    type: string;
+    [key: string]: unknown;
+};
+export declare class AiSdkStreamAdapter implements ProviderStreamAdapter<unknown> {
+    readonly provider: ProviderName;
+    private sequence;
+    private finished;
+    push(rawEvent: unknown): readonly NormalizedToolStreamEvent[];
+    finish(meta?: {
+        reason?: StreamEndReason;
+        providerReason?: string;
+    }): readonly NormalizedToolStreamEvent[];
+}
+export {};
+//# sourceMappingURL=ai-sdk.d.ts.map

package/dist/providers/ai-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.d.ts","sourceRoot":"","sources":["../../src/providers/ai-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,yBAAyB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACtG,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAiBrD,UAAU,uBAAuB;IAC/B,IAAI,EAAE,kBAAkB,CAAC;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,uBAAuB;IAC/B,IAAI,EAAE,kBAAkB,CAAC;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,qBAAqB;IAC7B,IAAI,EAAE,gBAAgB,CAAC;IACvB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,iBAAiB;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAGnB;AAED,UAAU,kBAAkB;IAC1B,IAAI,EAAE,YAAY,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,eAAe;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,eAAe,GACvB,uBAAuB,GACvB,uBAAuB,GACvB,qBAAqB,GACrB,iBAAiB,GACjB,kBAAkB,GAClB,eAAe,GACf,cAAc,GACd;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AA4B7C,qBAAa,kBAAmB,YAAW,qBAAqB,CAAC,OAAO,CAAC;IACvE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAY;IAC3C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAS;IAEzB,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,yBAAyB,EAAE;IA2J7D,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,eAAe,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,yBAAyB,EAAE;CAW3G"}

package/dist/providers/ai-sdk.js

@@ -0,0 +1,191 @@
+import { CONTENT_FILTERED_DIAGNOSTIC_CODE } from "../coordinator/diagnostic-codes.js";
+function toolPartId(part) {
+    // "tool-input-start"/"tool-input-delta" carry `id`; "tool-input-end" is
+    // documented with `toolCallId`. Reading both defensively means this
+    // adapter keeps working correlated-by-ID either way, rather than silently
+    // dropping events if one part type uses the other field name.
+    return part.id ?? part.toolCallId;
+}
+function stringifyError(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    if (error &&
+        typeof error === "object" &&
+        "message" in error &&
+        typeof error.message === "string") {
+        return error.message;
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+export class AiSdkStreamAdapter {
+    provider = "ai-sdk";
+    sequence = 0;
+    finished = false;
+    push(rawEvent) {
+        if (this.finished)
+            return [];
+        const events = [];
+        if (!rawEvent || typeof rawEvent !== "object") {
+            events.push({
+                type: "provider_diagnostic",
+                sequence: ++this.sequence,
+                provider: this.provider,
+                code: "E_PROVIDER_EVENT_MALFORMED",
+                severity: "error",
+                message: "Raw event is not an object",
+            });
+            return events;
+        }
+        // A single permissive cast (rather than narrowing the `AiSdkStreamPart`
+        // union directly) matches the other adapters in this directory - their
+        // catch-all `{ type: string; [key: string]: unknown }` union member
+        // means the compiler can never fully exclude it inside a `switch (type)`
+        // case, so property access still needs a shape where every field used
+        // below is already optional.
+        const part = rawEvent;
+        switch (part.type) {
+            case "tool-input-start": {
+                const id = toolPartId(part);
+                if (id === undefined)
+                    break;
+                events.push({
+                    type: "tool_call_start",
+                    sequence: ++this.sequence,
+                    provider: this.provider,
+                    callRef: { sourceKey: `tool-input:${id}` },
+                    toolCallId: id,
+                    name: part.toolName,
+                });
+                break;
+            }
+            case "tool-input-delta": {
+                const id = toolPartId(part);
+                if (id === undefined || typeof part.delta !== "string")
+                    break;
+                events.push({
+                    type: "tool_call_arguments_delta",
+                    sequence: ++this.sequence,
+                    provider: this.provider,
+                    callRef: { sourceKey: `tool-input:${id}` },
+                    delta: part.delta,
+                });
+                break;
+            }
+            case "tool-input-end": {
+                const id = toolPartId(part);
+                if (id === undefined)
+                    break;
+                events.push({
+                    type: "tool_call_end",
+                    sequence: ++this.sequence,
+                    provider: this.provider,
+                    callRef: { sourceKey: `tool-input:${id}` },
+                    reason: "complete", // corrected by the stream-level "finish" part below
+                });
+                break;
+            }
+            case "tool-call": {
+                // Intentionally a no-op. This part carries the SDK's own resolved
+                // `input` for the call, which - per this library's whole reason for
+                // existing (see README's Cline / `fixJson` analysis) - may already
+                // be silently repaired from a truncated stream. Trusting it here
+                // would reintroduce exactly the problem this adapter exists to
+                // avoid. The call's real argument text was already captured
+                // verbatim from "tool-input-delta" parts above, byte for byte.
+                break;
+            }
+            case "tool-error": {
+                const id = toolPartId(part);
+                events.push({
+                    type: "provider_diagnostic",
+                    sequence: ++this.sequence,
+                    provider: this.provider,
+                    code: "E_PROVIDER_TOOL_ERROR",
+                    severity: "error",
+                    message: `Tool "${part.toolName ?? "unknown"}" reported an error: ${stringifyError(part.error)}`,
+                    ...(id !== undefined ? { callRef: { sourceKey: `tool-input:${id}` } } : {}),
+                });
+                break;
+            }
+            case "finish": {
+                const finishReason = part.finishReason;
+                let reason = "unknown";
+                if (finishReason === "stop" || finishReason === "tool-calls") {
+                    reason = "complete";
+                }
+                else if (finishReason === "length") {
+                    reason = "length";
+                }
+                else if (finishReason === "content-filter") {
+                    // Not a generic cancellation: a policy/safety termination should
+                    // never be blindly retried. Recorded as its own machine-readable
+                    // diagnostic so the execution gate can reject with reason
+                    // "content_filtered" instead of the generic "stream_incomplete"
+                    // it would otherwise fall back to for a "cancelled" end reason.
+                    reason = "cancelled";
+                    events.push({
+                        type: "provider_diagnostic",
+                        sequence: ++this.sequence,
+                        provider: this.provider,
+                        code: CONTENT_FILTERED_DIAGNOSTIC_CODE,
+                        severity: "error",
+                        message: "Generation stopped by the model provider's content filter",
+                    });
+                }
+                else if (finishReason === "error") {
+                    reason = "provider_error";
+                }
+                // "other" (and any future/unrecognized literal) intentionally falls
+                // through to "unknown" - fail closed on an unclassified reason
+                // rather than guessing it means "complete".
+                events.push({
+                    type: "provider_stream_end",
+                    sequence: ++this.sequence,
+                    provider: this.provider,
+                    reason,
+                    providerReason: finishReason,
+                });
+                this.finished = true;
+                break;
+            }
+            case "error": {
+                events.push({
+                    type: "provider_stream_end",
+                    sequence: ++this.sequence,
+                    provider: this.provider,
+                    reason: "provider_error",
+                    providerReason: stringifyError(part.error),
+                });
+                this.finished = true;
+                break;
+            }
+            // Unrelated part types (text-delta, reasoning-delta, tool-result,
+            // start, start-step, finish-step, etc.) carry no tool-argument or
+            // stream-termination information for our purposes and must not crash
+            // the adapter.
+            default:
+                break;
+        }
+        return events;
+    }
+    finish(meta) {
+        if (this.finished)
+            return [];
+        this.finished = true;
+        return [{
+                type: "provider_stream_end",
+                sequence: ++this.sequence,
+                provider: this.provider,
+                reason: meta?.reason ?? "unknown",
+                providerReason: meta?.providerReason,
+            }];
+    }
+}
+//# sourceMappingURL=ai-sdk.js.map

package/dist/providers/ai-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../../src/providers/ai-sdk.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prefix-safe-json",
-  "version": "0.0.1-alpha.2",
+  "version": "0.0.1-alpha.3",
   "description": "Incremental LLM tool-call JSON parser and deterministic repair engine — never reports a value until it's unambiguously complete",
   "keywords": [
     "json",
@@ -58,7 +58,8 @@
     "validate-corpus": "tsx scripts/validate-corpus.ts",
     "clean": "rimraf dist coverage .vitest",
     "pack:check": "pnpm pack --dry-run",
-    "example:anthropic": "node examples/anthropic-truncation-safety.mjs"
+    "example:anthropic": "node examples/anthropic-truncation-safety.mjs",
+    "example:ai-sdk": "node examples/ai-sdk-execution-gate.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^9.8.0",