tool-call-closure 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes will be documented here. This project follows Semantic Versioning.
+
+## Unreleased
+
+### Fixed
+
+- Replacement 1.0.0 candidate: recheck generation, closure, and settlement state after caller getters, JSON serialization, and string conversion. Preserve the first terminal result during reentrant operations.
+- Reject reentrant generation replacement and sparse call arrays before an outer registration can supersede a newer or valid existing batch.
+- Keep fixed built-in error codes usable with small `maxCodeBytes` limits; the limit applies to explicitly supplied codes.
+- Reject untrusted snapshot objects before reading their properties.
+
+## 1.0.0 - 2026-10-05
+
+- Add bounded tool-call generations, exactly-once settlement, synthetic closure provenance, stale-result fencing, and explicit OpenAI Chat Completions, OpenAI Responses, and Anthropic adapters.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Huzaifa Asif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,5 @@
+# Notices
+
+`tool-call-closure` is original work distributed under the MIT License.
+
+The published runtime contains no third-party dependencies or copied third-party source. Documentation names interoperable products and links to their public documentation for comparison; those names remain the property of their respective owners.

package/README.md

@@ -0,0 +1,218 @@
+# tool-call-closure
+
+`tool-call-closure` is a small, zero-dependency state machine for one awkward part of an AI agent loop: every announced tool call needs one terminal outcome, even when the run is aborted, times out, hits a limit, or is superseded.
+
+It records calls in source order, accepts each real result once, creates explicit **error/cancelled** outcomes for calls still pending at closure, and rejects late results from old generations. It can format a completed batch for OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages.
+
+## Why this exists
+
+Provider protocols associate each tool result with a prior tool call. Incomplete lifecycles can make a later request invalid. This is especially easy to get wrong when an `AbortSignal`, deadline, concurrency race, or request replacement intersects a batch of tools.
+
+This package is deliberately smaller than an agent runtime. It does not choose tools, execute them, own a transcript, retry providers, or cancel side effects. It only makes terminal accounting explicit and portable.
+
+Existing alternatives are often the better choice:
+
+- Vercel AI SDK already models tool states and can synthesize execution-denied results during UI-message conversion. Use it when your application already uses its message/runtime abstractions.
+- `omk-agent-core` is a full agent runtime with timeouts, abort handling, synthetic terminal results, late-settlement audit events, ordering, scheduling, and transcript integrity checks. Use it when you want that complete runtime.
+- `conversationalist` validates tool-call/result relationships and preserves pairs while trimming transcripts. Use it for transcript validation or token-budget work.
+- `ai-sdk-heal` repairs AI SDK histories with missing placeholders and deduplication. Use it when repairing stored AI SDK message history; this package rejects invalid runtime transitions rather than rewriting a history.
+- Generic promise settlers such as `p-settle` settle promises, but do not track provider call IDs or emit provider payloads.
+
+The narrow gap here is a standalone, runtime-independent primitive with no runtime dependencies. The underlying mechanism is established practice, not a novelty claim.
+
+## Install
+
+```sh
+npm install tool-call-closure
+```
+
+Node.js 18 or newer is required. Both ESM and CommonJS are exported.
+
+## Quick start
+
+```js
+import { createToolCallClosure } from 'tool-call-closure';
+
+const closure = createToolCallClosure();
+const { handle } = closure.begin([
+  { id: 'call_weather', name: 'get_weather' },
+  { id: 'call_calendar', name: 'get_calendar' },
+]);
+
+closure.succeed(handle, 'call_weather', { temperatureC: 24 });
+
+const snapshot = closure.close(handle, {
+  status: 'cancelled',
+  code: 'request_aborted',
+  message: 'The caller disconnected before this tool completed.',
+  sideEffectState: 'unknown',
+});
+
+const input = closure.toOpenAIResponses(snapshot);
+```
+
+The calendar result is synthetic, visibly cancelled, and tagged with `provenance: "synthetic"` in the snapshot. A later real result is rejected; it never replaces the committed terminal outcome.
+
+## API
+
+### `createToolCallClosure(options?)`
+
+Returns a `ToolCallClosure`. The class constructor accepts the same options.
+
+| Option | Default | Purpose |
+| --- | ---: | --- |
+| `maxCalls` | `1000` | Maximum calls in one generation |
+| `maxDiagnostics` | `100` | Maximum rejected-operation diagnostics retained |
+| `maxResultBytes` | `1048576` | Maximum UTF-8 bytes in a reported success result |
+| `maxMessageBytes` | `4096` | Maximum UTF-8 bytes in error/cancellation messages |
+| `maxIdBytes` | `512` | Maximum UTF-8 bytes in a tool-call ID |
+| `maxNameBytes` | `512` | Maximum UTF-8 bytes in a tool name |
+| `maxCodeBytes` | `128` | Maximum UTF-8 bytes in a caller-supplied error/cancellation code |
+
+All limits must be positive safe integers.
+
+Built-in default codes (`error`, `cancelled`, `tool_error`, and `superseded`) stay intact even when `maxCodeBytes` is smaller; they are fixed strings of at most 10 bytes. Explicitly supplied codes, including these same strings, must fit the configured limit.
+
+### `begin(calls)`
+
+Validates `{ id, name }` entries, rejects duplicate IDs, and starts a generation. Starting another generation closes pending calls in the old one as `superseded` and returns that prior snapshot as `superseded`.
+
+```js
+const { generation, handle, superseded } = closure.begin(calls);
+```
+
+Invalid new input is validated before the current generation is superseded.
+Sparse call arrays are invalid. If a call getter starts a newer generation during validation, the outer `begin` throws without replacing that newer generation.
+
+`handle` is an immutable, identity-checked batch handle. Keep it with the promises launched for that batch. A copied `{ generation }` object is not accepted.
+
+Only register complete, committed, ordinary client-side function calls. Do not register streaming call fragments, approval pauses, or provider-hosted tools.
+
+### `settle(handle, callId, outcome)`
+
+Accepts exactly one terminal outcome:
+
+```js
+closure.settle(handle, 'call_1', { status: 'success', content: { ok: true } });
+closure.settle(handle, 'call_2', { status: 'error', code: 'upstream', message: 'Unavailable' });
+closure.settle(handle, 'call_3', { status: 'cancelled', code: 'abort', message: 'Stopped' });
+```
+
+`succeed`, `fail`, and `cancel` are convenience methods. Results return `{ accepted: true, ... }` or `{ accepted: false, reason, ... }`; expected races do not throw. Rejection reasons are `stale_generation`, `run_closed`, `unknown_call`, and `duplicate_settlement`.
+
+Success objects are JSON-stringified at settlement. Circular, undefined, or oversized values throw without changing call state. `fail(Error)` retains the message only, never the stack.
+
+Getters, `toJSON`, and string conversion can execute caller code. State is rechecked after normalization: a nested settlement or closure wins, and a result for a superseded generation is rejected. If caller code itself changes state and then throws, that nested change is preserved. Closed snapshots remain detached and unchanged.
+
+### `close(handle, reason?)`
+
+Commits an `error` or `cancelled` synthetic result for every still-pending call and freezes the run. Already reported outcomes are preserved.
+
+```js
+const snapshot = closure.close(handle, {
+  status: 'error',
+  code: 'tool_limit',
+  message: 'This run reached its tool-call limit.',
+  sideEffectState: 'not_started',
+});
+```
+
+`sideEffectState` is required by the semantics even though it defaults conservatively to `unknown`. Use `not_started` only when the host knows execution never began. A synthetic result never proves that an operation stopped, rolled back, or is safe to retry.
+
+Closing is idempotent. It does **not** abort tool processes, network requests, or side effects. Wire your own `AbortSignal` into executors. If a real promise later settles or rejects, call `settle`; the typed `run_closed`/`stale_generation` result records its observed status and is the audit signal. This package does not silently promote that late value into the transcript.
+
+### `seal(handle)`
+
+Marks an all-reported batch complete without creating synthetic outcomes. It returns `pending_calls` if any call remains pending. Provider adapters refuse an open snapshot, so partial output is never labelled provider-ready.
+
+### `snapshot()`
+
+Returns an immutable detached view. Calls remain in announcement order. Each settlement carries `provenance: "reported" | "synthetic"`.
+
+### Provider adapters
+
+```js
+closure.toOpenAIChatCompletions(snapshot); // role: "tool", tool_call_id, content
+closure.toOpenAIResponses(snapshot);       // type: "function_call_output", call_id, output
+closure.toAnthropicToolResults(snapshot);  // type: "tool_result", tool_use_id, content, is_error
+```
+
+Adapters require a sealed/closed snapshot and preserve announcement order. Repeated export is a pure read; it does not mean the caller should append the same results twice. Adapters do not validate a whole transcript.
+
+For Anthropic, the caller must place the returned blocks in the user message immediately after the assistant message containing the corresponding `tool_use` blocks, with tool results before other user content. A payload-only utility cannot guarantee adjacency.
+
+For OpenAI, choose the adapter matching the API you call; Chat Completions and Responses use different shapes.
+
+## Common patterns
+
+### Timeout
+
+```js
+const timer = setTimeout(() => {
+  controller.abort();
+  closure.close(handle, {
+    status: 'cancelled', code: 'timeout', message: 'Tool deadline elapsed.',
+  });
+}, 10_000);
+```
+
+### Replacement request
+
+Call `begin` with the new batch. The old generation is closed as `superseded`. Keep its immutable handle next to each promise and pass it to `settle`; old promises are then rejected deterministically. The returned supersession snapshot belongs to the old branch only.
+
+### Tool-call limit
+
+Do not invent a success. Close pending calls with an explicit error code, pass those results to the model if your application will continue, and let the model explain the limitation.
+
+## Limits and non-goals
+
+- No tool execution, cancellation, retry, scheduling, persistence, or side-effect rollback.
+- No complete transcript validation or repair.
+- No crash durability or distributed exactly-once guarantee; state exists only in one process.
+- No guarantee that a provider accepts a request; callers own surrounding message order and API-version requirements.
+- Results are retained in memory until a new generation replaces them; use the byte/count limits for untrusted tools.
+- JSON serialization is ordinary `JSON.stringify`, not canonical JSON.
+- Only text provider payloads are emitted; multimodal tool outputs need an SDK-specific adapter.
+- Synthetic outcomes describe orchestration state, not what happened inside a late or non-cooperative tool.
+- The host owns assistant messages, reasoning metadata, approval state, and provider-hosted tool state.
+
+## Research basis
+
+- [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling) distinguishes call IDs and function-call outputs.
+- [Anthropic parallel tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use) documents result ordering and placement.
+- [AI SDK missing tool results](https://ai-sdk.dev/docs/troubleshooting/missing-tool-results-error) documents the complete-result requirement.
+- [LangChainJS #8570](https://github.com/langchain-ai/langchainjs/issues/8570) is a reported abort/missing-result failure mode; it was closed after maintainers could not reproduce it, so it is not presented as a verified outstanding defect.
+
+LangChainJS #10090 was reviewed and intentionally excluded as supporting evidence: it already has a matching error result and concerns router continuation, which this package does not address.
+
+## Troubleshooting
+
+**`stale_generation`** — A newer `begin` replaced the run. Record the late result externally if needed; it was intentionally not committed.
+
+**`run_closed`** — The generation already has terminal results. Do not send a second result for that ID.
+
+**`unknown_call`** — The result ID was never announced in this generation. Check whether you used a provider item ID instead of its call ID.
+
+**Provider reports a missing result** — Confirm every provider call was included in `begin`, close the batch, use the adapter for the correct OpenAI API, and place the payload in the required message position.
+
+**A result exceeds `maxResultBytes`** — Store large output elsewhere and settle with a bounded summary or reference.
+
+## Security
+
+Treat tool output as untrusted data. This package serializes it but does not sanitize prompt injection, HTML, commands, or secrets. Synthetic error content contains only the code/message you provide. Avoid putting credentials or raw internal errors in those fields.
+
+See [SECURITY.md](SECURITY.md) for reporting instructions.
+
+## Development
+
+```sh
+npm test
+npm run lint
+npm run check
+```
+
+The test suite covers boundaries, fuzzed settlement order, generation races, immutability, exact provider shapes, limits, and content handling.
+
+## License
+
+MIT © Huzaifa Asif

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "tool-call-closure",
+  "version": "1.0.0",
+  "description": "Close pending AI tool calls deterministically and fence stale results after aborts, timeouts, limits, or supersession.",
+  "keywords": ["ai", "agents", "tool-calling", "openai", "anthropic", "cancellation", "llm"],
+  "license": "MIT",
+  "author": "Huzaifa Asif",
+  "repository": { "type": "git", "url": "git+https://github.com/Huzaifa-Asif/tool-call-closure.git" },
+  "bugs": { "url": "https://github.com/Huzaifa-Asif/tool-call-closure/issues" },
+  "homepage": "https://github.com/Huzaifa-Asif/tool-call-closure#readme",
+  "type": "module",
+  "main": "./src/index.cjs",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": { ".": { "types": "./src/index.d.ts", "import": "./src/index.js", "require": "./src/index.cjs" } },
+  "files": ["src", "README.md", "LICENSE", "NOTICE.md", "CHANGELOG.md"],
+  "engines": { "node": ">=18" },
+  "sideEffects": false,
+  "scripts": {
+    "lint": "node scripts/lint.mjs",
+    "test": "node --test",
+    "test:coverage": "node --experimental-test-coverage --test",
+    "check": "npm run lint && npm run test:coverage && npm pack --dry-run"
+  },
+  "publishConfig": { "access": "public" }
+}

package/src/index.cjs

@@ -0,0 +1,332 @@
+'use strict';
+
+const DEFAULTS = Object.freeze({
+  maxCalls: 1_000,
+  maxDiagnostics: 100,
+  maxResultBytes: 1_048_576,
+  maxMessageBytes: 4_096,
+  maxIdBytes: 512,
+  maxNameBytes: 512,
+  maxCodeBytes: 128,
+});
+
+const VALID_STATUSES = new Set(['success', 'error', 'cancelled']);
+const CLOSE_STATUSES = new Set(['error', 'cancelled']);
+
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new TypeError(`${name} must be a positive safe integer`);
+  }
+  return value;
+}
+
+function nonEmptyString(value, name) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return value;
+}
+
+function boundedString(value, name, maxBytes) {
+  const text = nonEmptyString(value, name);
+  if (Buffer.byteLength(text) > maxBytes) throw new RangeError(`${name} exceeds its byte limit (${maxBytes})`);
+  return text;
+}
+
+function truncateUtf8(value, maxBytes) {
+  const text = String(value);
+  const bytes = Buffer.from(text);
+  if (bytes.length <= maxBytes) return text;
+  const suffix = maxBytes >= 3 ? '...' : '';
+  let end = maxBytes - Buffer.byteLength(suffix);
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end -= 1;
+  return `${bytes.subarray(0, end).toString('utf8')}${suffix}`;
+}
+
+function serializeContent(value, maxBytes) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value);
+  if (text === undefined) throw new TypeError('result content must be JSON-serializable or a string');
+  if (Buffer.byteLength(text) > maxBytes) {
+    throw new RangeError(`result content exceeds maxResultBytes (${maxBytes})`);
+  }
+  return text;
+}
+
+function freezeCopy(value) {
+  if (Array.isArray(value)) return Object.freeze(value.map(freezeCopy));
+  if (value && typeof value === 'object') {
+    const copy = {};
+    for (const [key, child] of Object.entries(value)) copy[key] = freezeCopy(child);
+    return Object.freeze(copy);
+  }
+  return value;
+}
+
+class ToolCallClosure {
+  #options;
+  #generation = 0;
+  #run = null;
+  #diagnostics = [];
+  #snapshots = new WeakSet();
+
+  constructor(options = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new TypeError('options must be an object');
+    }
+    this.#options = Object.freeze({
+      maxCalls: positiveInteger(options.maxCalls ?? DEFAULTS.maxCalls, 'maxCalls'),
+      maxDiagnostics: positiveInteger(options.maxDiagnostics ?? DEFAULTS.maxDiagnostics, 'maxDiagnostics'),
+      maxResultBytes: positiveInteger(options.maxResultBytes ?? DEFAULTS.maxResultBytes, 'maxResultBytes'),
+      maxMessageBytes: positiveInteger(options.maxMessageBytes ?? DEFAULTS.maxMessageBytes, 'maxMessageBytes'),
+      maxIdBytes: positiveInteger(options.maxIdBytes ?? DEFAULTS.maxIdBytes, 'maxIdBytes'),
+      maxNameBytes: positiveInteger(options.maxNameBytes ?? DEFAULTS.maxNameBytes, 'maxNameBytes'),
+      maxCodeBytes: positiveInteger(options.maxCodeBytes ?? DEFAULTS.maxCodeBytes, 'maxCodeBytes'),
+    });
+  }
+
+  get activeGeneration() {
+    return this.#run?.generation ?? null;
+  }
+
+  begin(calls) {
+    const startingGeneration = this.#generation;
+    if (!Array.isArray(calls)) throw new TypeError('calls must be an array');
+    const count = calls.length;
+    if (!Number.isSafeInteger(count) || count < 0) throw new TypeError('calls.length must be a non-negative safe integer');
+    if (count > this.#options.maxCalls) {
+      throw new RangeError(`calls exceed maxCalls (${this.#options.maxCalls})`);
+    }
+
+    const seen = new Set();
+    const normalized = [];
+    for (let index = 0; index < count; index += 1) {
+      const call = calls[index];
+      if (!call || typeof call !== 'object' || Array.isArray(call)) {
+        throw new TypeError(`calls[${index}] must be an object`);
+      }
+      const id = boundedString(call.id, `calls[${index}].id`, this.#options.maxIdBytes);
+      if (seen.has(id)) throw new TypeError(`duplicate tool call id: ${id}`);
+      seen.add(id);
+      normalized.push({
+        id,
+        name: boundedString(call.name, `calls[${index}].name`, this.#options.maxNameBytes),
+        state: 'pending',
+        settlement: null,
+      });
+    }
+    if (this.#generation !== startingGeneration) {
+      throw new TypeError('active generation changed while validating calls');
+    }
+
+    let superseded = null;
+    if (this.#run && !this.#run.closed) {
+      superseded = this.#commitClose(this.#run, {
+        status: 'cancelled',
+        code: 'superseded',
+        message: truncateUtf8('Tool call was superseded by a newer generation.', this.#options.maxMessageBytes),
+        sideEffectState: 'unknown',
+      });
+    }
+
+    this.#generation += 1;
+    const handle = Object.freeze({ generation: this.#generation });
+    this.#diagnostics = [];
+    this.#run = {
+      generation: this.#generation,
+      handle,
+      closed: false,
+      closeReason: null,
+      calls: normalized,
+      byId: new Map(normalized.map((call) => [call.id, call])),
+    };
+    return Object.freeze({ generation: this.#generation, handle, superseded });
+  }
+
+  settle(handle, callId, outcome) {
+    return this.#settle(handle, callId, outcome);
+  }
+
+  #settle(handle, callId, outcome, defaultCode) {
+    boundedString(callId, 'callId', this.#options.maxIdBytes);
+    const candidateGeneration = handle?.generation;
+    const generation = Number.isSafeInteger(candidateGeneration) && candidateGeneration > 0 ? candidateGeneration : null;
+    const candidateStatus = outcome?.status;
+    const observedStatus = VALID_STATUSES.has(candidateStatus) ? candidateStatus : (candidateStatus == null ? null : 'invalid');
+
+    if (!this.#run || handle !== this.#run.handle) {
+      return this.#reject('stale_generation', callId, generation, observedStatus);
+    }
+    if (this.#run.closed) return this.#reject('run_closed', callId, generation, observedStatus);
+
+    const call = this.#run.byId.get(callId);
+    if (!call) return this.#reject('unknown_call', callId, generation);
+    if (call.state !== 'pending') return this.#reject('duplicate_settlement', callId, generation);
+
+    const settlement = this.#normalizeOutcome(outcome, defaultCode);
+    // JSON serialization, getters, and string conversion can run caller code.
+    // A nested terminal write or newer generation wins over this operation.
+    if (handle !== this.#run.handle) return this.#reject('stale_generation', callId, generation, settlement.status);
+    if (this.#run.closed) return this.#reject('run_closed', callId, generation, settlement.status);
+    if (call.state !== 'pending') return this.#reject('duplicate_settlement', callId, generation, settlement.status);
+    call.state = settlement.status;
+    call.settlement = settlement;
+    return freezeCopy({ accepted: true, generation, callId, settlement });
+  }
+
+  succeed(handle, callId, content) {
+    return this.settle(handle, callId, { status: 'success', content });
+  }
+
+  fail(handle, callId, error, code) {
+    const message = error instanceof Error ? error.message : String(error);
+    return this.#settle(handle, callId, { status: 'error', code, message }, 'tool_error');
+  }
+
+  cancel(handle, callId, message = 'Tool call was cancelled.', code) {
+    return this.#settle(handle, callId, { status: 'cancelled', code, message }, 'cancelled');
+  }
+
+  close(handle, reason = {}) {
+    const candidateGeneration = handle?.generation;
+    const generation = Number.isSafeInteger(candidateGeneration) && candidateGeneration > 0 ? candidateGeneration : null;
+    if (!this.#run || handle !== this.#run.handle) {
+      return this.#reject('stale_generation', null, generation, null);
+    }
+    if (this.#run.closed) return this.snapshot();
+    const run = this.#run;
+
+    const status = reason.status ?? 'cancelled';
+    if (!CLOSE_STATUSES.has(status)) {
+      throw new TypeError('close status must be error or cancelled');
+    }
+    const suppliedCode = reason.code;
+    const code = suppliedCode == null ? status : boundedString(suppliedCode, 'reason.code', this.#options.maxCodeBytes);
+    const sideEffectState = reason.sideEffectState ?? 'unknown';
+    if (sideEffectState !== 'unknown' && sideEffectState !== 'not_started') {
+      throw new TypeError('reason.sideEffectState must be unknown or not_started');
+    }
+    const message = truncateUtf8(
+      reason.message ?? (status === 'error' ? 'Tool call did not complete.' : 'Tool call was cancelled.'),
+      this.#options.maxMessageBytes,
+    );
+    if (this.#run !== run) return this.#reject('stale_generation', null, generation, null);
+    if (run.closed) return this.snapshot();
+    return this.#commitClose(run, { status, code, message, sideEffectState });
+  }
+
+  #commitClose(run, { status, code, message, sideEffectState }) {
+    for (const call of run.calls) {
+      if (call.state === 'pending') {
+        call.state = status;
+        call.settlement = Object.freeze({ status, code, message, provenance: 'synthetic', sideEffectState });
+      }
+    }
+    run.closed = true;
+    run.closeReason = { status, code, message, sideEffectState };
+    return this.snapshot();
+  }
+
+  seal(handle) {
+    const candidateGeneration = handle?.generation;
+    const generation = Number.isSafeInteger(candidateGeneration) && candidateGeneration > 0 ? candidateGeneration : null;
+    if (!this.#run || handle !== this.#run.handle) {
+      return this.#reject('stale_generation', null, generation, null);
+    }
+    if (this.#run.closed) return this.snapshot();
+    if (this.#run.calls.some((call) => call.state === 'pending')) {
+      return this.#reject('pending_calls', null, generation, null);
+    }
+    this.#run.closed = true;
+    this.#run.closeReason = { status: 'complete' };
+    return this.snapshot();
+  }
+
+  snapshot() {
+    if (!this.#run) return null;
+    const snapshot = freezeCopy({
+      generation: this.#run.generation,
+      closed: this.#run.closed,
+      closeReason: this.#run.closeReason,
+      calls: this.#run.calls.map(({ id, name, state, settlement }) => ({ id, name, state, settlement })),
+      diagnostics: this.#diagnostics,
+    });
+    this.#snapshots.add(snapshot);
+    return snapshot;
+  }
+
+  toOpenAIChatCompletions(snapshot = this.snapshot()) {
+    this.#assertSnapshot(snapshot);
+    return snapshot.calls.filter((call) => call.state !== 'pending').map((call) => ({
+      role: 'tool',
+      tool_call_id: call.id,
+      content: this.#adapterContent(call.settlement),
+    }));
+  }
+
+  toOpenAIResponses(snapshot = this.snapshot()) {
+    this.#assertSnapshot(snapshot);
+    return snapshot.calls.filter((call) => call.state !== 'pending').map((call) => ({
+      type: 'function_call_output',
+      call_id: call.id,
+      output: this.#adapterContent(call.settlement),
+    }));
+  }
+
+  toAnthropicToolResults(snapshot = this.snapshot()) {
+    this.#assertSnapshot(snapshot);
+    return snapshot.calls.filter((call) => call.state !== 'pending').map((call) => ({
+      type: 'tool_result',
+      tool_use_id: call.id,
+      content: this.#adapterContent(call.settlement),
+      ...(call.state === 'success' ? {} : { is_error: true }),
+    }));
+  }
+
+  #normalizeOutcome(outcome, defaultCode) {
+    if (!outcome || typeof outcome !== 'object' || Array.isArray(outcome)) {
+      throw new TypeError('outcome must be an object');
+    }
+    const status = outcome.status;
+    if (!VALID_STATUSES.has(status)) {
+      throw new TypeError('outcome.status must be success, error, or cancelled');
+    }
+    if (status === 'success') {
+      return Object.freeze({ status, content: serializeContent(outcome.content, this.#options.maxResultBytes), provenance: 'reported' });
+    }
+    const suppliedCode = outcome.code;
+    return Object.freeze({
+      status,
+      code: suppliedCode == null ? (defaultCode ?? status) : boundedString(suppliedCode, 'outcome.code', this.#options.maxCodeBytes),
+      message: truncateUtf8(outcome.message ?? (status === 'error' ? 'Tool call failed.' : 'Tool call was cancelled.'), this.#options.maxMessageBytes),
+      provenance: 'reported',
+    });
+  }
+
+  #adapterContent(settlement) {
+    if (settlement.status === 'success') return settlement.content;
+    return JSON.stringify({ error: {
+      code: settlement.code,
+      message: settlement.message,
+      ...(settlement.provenance === 'synthetic' ? { side_effect_state: settlement.sideEffectState } : {}),
+    } });
+  }
+
+  #assertSnapshot(snapshot) {
+    if (!snapshot || typeof snapshot !== 'object' || !this.#snapshots.has(snapshot) || !Array.isArray(snapshot.calls)) {
+      throw new TypeError('snapshot must be a ToolCallClosure snapshot');
+    }
+    if (!snapshot.closed) throw new TypeError('snapshot must be sealed before provider export');
+  }
+
+  #reject(reason, callId, generation, observedStatus = null) {
+    const diagnostic = freezeCopy({ reason, callId, generation, observedStatus });
+    if (this.#diagnostics.length < this.#options.maxDiagnostics) this.#diagnostics.push(diagnostic);
+    return freezeCopy({ accepted: false, reason, callId, generation, observedStatus });
+  }
+}
+
+function createToolCallClosure(options) {
+  return new ToolCallClosure(options);
+}
+
+module.exports = { ToolCallClosure, createToolCallClosure };

package/src/index.d.ts

@@ -0,0 +1,56 @@
+export type ToolCall = Readonly<{ id: string; name: string }>;
+export type Settlement =
+  | Readonly<{ status: 'success'; content: string; provenance: 'reported' }>
+  | Readonly<{ status: 'error' | 'cancelled'; code: string; message: string; provenance: 'reported' }>
+  | Readonly<{ status: 'error' | 'cancelled'; code: string; message: string; provenance: 'synthetic'; sideEffectState: 'unknown' | 'not_started' }>;
+export type BatchHandle = Readonly<{ generation: number }>;
+export type CallSnapshot = Readonly<{
+  id: string;
+  name: string;
+  state: 'pending' | 'success' | 'error' | 'cancelled';
+  settlement: Settlement | null;
+}>;
+export type DiagnosticReason = 'stale_generation' | 'run_closed' | 'unknown_call' | 'duplicate_settlement' | 'pending_calls';
+export type Snapshot = Readonly<{
+  generation: number;
+  closed: boolean;
+  closeReason: null | Readonly<{ status: 'complete' }> | Readonly<{ status: 'error' | 'cancelled'; code: string; message: string; sideEffectState: 'unknown' | 'not_started' }>;
+  calls: readonly CallSnapshot[];
+  diagnostics: readonly Readonly<{ reason: DiagnosticReason; callId: string | null; generation: number | null; observedStatus: string | null }>[];
+}>;
+export type SettlementResult =
+  | Readonly<{ accepted: true; generation: number; callId: string; settlement: Settlement }>
+  | Readonly<{ accepted: false; reason: DiagnosticReason; callId: string | null; generation: number | null; observedStatus: string | null }>;
+export interface ToolCallClosureOptions {
+  maxCalls?: number;
+  maxDiagnostics?: number;
+  maxResultBytes?: number;
+  maxMessageBytes?: number;
+  maxIdBytes?: number;
+  maxNameBytes?: number;
+  maxCodeBytes?: number;
+}
+export interface Outcome {
+  status: 'success' | 'error' | 'cancelled';
+  content?: unknown;
+  code?: string;
+  message?: string;
+}
+export declare class ToolCallClosure {
+  constructor(options?: ToolCallClosureOptions);
+  get activeGeneration(): number | null;
+  begin(calls: readonly ToolCall[]): Readonly<{ generation: number; handle: BatchHandle; superseded: Snapshot | null }>;
+  settle(handle: BatchHandle, callId: string, outcome: Outcome): SettlementResult;
+  succeed(handle: BatchHandle, callId: string, content: unknown): SettlementResult;
+  fail(handle: BatchHandle, callId: string, error: unknown, code?: string): SettlementResult;
+  cancel(handle: BatchHandle, callId: string, message?: string, code?: string): SettlementResult;
+  close(handle: BatchHandle, reason?: { status?: 'error' | 'cancelled'; code?: string; message?: string; sideEffectState?: 'unknown' | 'not_started' }): Snapshot | SettlementResult;
+  seal(handle: BatchHandle): Snapshot | SettlementResult;
+  snapshot(): Snapshot | null;
+  toOpenAIChatCompletions(snapshot?: Snapshot): readonly Readonly<{ role: 'tool'; tool_call_id: string; content: string }>[];
+  toOpenAIResponses(snapshot?: Snapshot): readonly Readonly<{ type: 'function_call_output'; call_id: string; output: string }>[];
+  toAnthropicToolResults(snapshot?: Snapshot): readonly Readonly<{ type: 'tool_result'; tool_use_id: string; content: string; is_error?: true }>[];
+}
+export declare function createToolCallClosure(options?: ToolCallClosureOptions): ToolCallClosure;
+declare const api: Readonly<{ ToolCallClosure: typeof ToolCallClosure; createToolCallClosure: typeof createToolCallClosure }>;
+export default api;

package/src/index.js

@@ -0,0 +1,4 @@
+import api from './index.cjs';
+
+export const { ToolCallClosure, createToolCallClosure } = api;
+export default api;