ai-stream-auditor 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project uses [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-10-03
+
+### Added
+
+- Bounded incremental audit state machine for OpenAI Responses and Anthropic Messages events.
+- Separate protocol-completion, semantic-success, and outcome reporting.
+- Lifecycle checks for terminals, content units, deltas, provider status, sequence numbers, and stop reasons.
+- Forward-compatible unknown-event warnings without raw event retention.

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/README.md

@@ -0,0 +1,236 @@
+# ai-stream-auditor
+
+Audit decoded OpenAI Responses and Anthropic Messages event lifecycles for truncated, contradictory, or silently failed streams.
+
+`ai-stream-auditor` is a zero-dependency diagnostic state machine. Feed it the event objects your provider SDK already decoded. It reports whether the provider protocol reached a terminal event, whether that terminal represents a successful result, and exactly where lifecycle invariants broke.
+
+It does **not** open network connections, parse SSE bytes, retry requests, accumulate generated text, or replace a provider SDK.
+
+## Why this exists
+
+An async iterator ending is not proof that a model response completed. A transport can close, a consumer can cancel, an SDK can mishandle a mid-stream error, or a proxy can synthesize an end marker. Provider protocols also distinguish a clean terminal event from outcomes such as token exhaustion, refusal, and failure.
+
+The package's checks are based on the providers' documented event flows and motivated by concrete integration failures:
+
+- [OpenAI streaming Responses guide](https://developers.openai.com/api/docs/guides/streaming-responses)
+- [OpenAI Node issue #2046: mid-stream errors silently swallowed during iteration](https://github.com/openai/openai-node/issues/2046)
+- [Anthropic streaming Messages documentation](https://platform.claude.com/docs/en/build-with-claude/streaming)
+- [AxonHub issue #2092: synthetic end marker hides incomplete Responses stream](https://github.com/looplj/axonhub/issues/2092)
+
+This project is independent and is not an official OpenAI or Anthropic package.
+
+## Install
+
+```sh
+npm install ai-stream-auditor
+```
+
+Requires Node.js 18 or newer. ESM, CommonJS, and TypeScript declarations are included.
+
+## Quick start
+
+```js
+import { createStreamAuditor } from 'ai-stream-auditor';
+
+const auditor = createStreamAuditor('openai-responses');
+
+try {
+  for await (const event of stream) {
+    auditor.push(event);
+    // Process the event normally; the auditor does not retain its payload.
+  }
+  const report = auditor.finish({ cause: 'iterator_end' });
+  if (!report.successful) console.error(report);
+} catch (error) {
+  const report = auditor.finish({ cause: 'transport_error' });
+  console.error(report, error);
+}
+```
+
+For Anthropic:
+
+```js
+const auditor = createStreamAuditor('anthropic-messages');
+for await (const event of stream) auditor.push(event);
+const report = auditor.finish();
+```
+
+## The three questions in every report
+
+```ts
+{
+  protocolComplete: boolean; // Was a provider terminal event observed?
+  successful: boolean;       // Was it structurally valid and semantically successful?
+  outcome: 'completed' | 'tool_use' | 'paused' | 'incomplete' |
+    'refusal' | 'error' | 'cancelled' | 'timeout' |
+    'transport_closed' | 'invalid';
+}
+```
+
+Examples:
+
+| Situation | `protocolComplete` | `successful` | `outcome` |
+| --- | --- | --- | --- |
+| OpenAI `response.completed`, valid lifecycle | `true` | `true` | `completed` |
+| Anthropic `message_stop`, `stop_reason: max_tokens` | `true` | `false` | `incomplete` |
+| Anthropic `message_stop`, `stop_reason: tool_use` | `true` | `true` | `tool_use` |
+| Provider `error` event | `true` | `false` | `error` |
+| Iterator ends without terminal | `false` | `false` | `transport_closed` |
+| Caller cancellation without terminal | `false` | `false` | `cancelled` |
+| Completion event with an open content unit | `true` | `false` | `invalid` |
+
+Protocol completion and application success are intentionally separate. A cleanly encoded incomplete or refused response is complete at the transport protocol level but is not reported as successful.
+
+## API
+
+### `createStreamAuditor(dialect, options?)`
+
+Creates a bounded state machine. Supported dialects:
+
+- `openai-responses`
+- `anthropic-messages`
+
+Options:
+
+| Option | Default | Purpose |
+| --- | ---: | --- |
+| `maxEvents` | 100,000 | Bounds event processing |
+| `maxOpenUnits` | 10,000 | Bounds simultaneously open output items/content parts/blocks |
+| `maxDiagnostics` | 1,000 | Bounds retained diagnostic records |
+
+### `auditor.push(event)`
+
+Push one already-decoded provider event. Events are inspected synchronously and are not retained. Only type counts, bounded lifecycle keys, terminal metadata, and bounded diagnostics remain.
+
+Calling `push` after `finish` throws `StreamAuditError`.
+
+### `auditor.finish({ cause? })`
+
+Finalizes and returns a frozen report. `cause` defaults to `iterator_end` and can be:
+
+- `iterator_end`
+- `cancelled`
+- `timeout`
+- `transport_error`
+
+Use the actual consumer/transport cause; the auditor cannot infer why an iterator stopped.
+
+The report also includes `stopReason`, `terminalEvent`, `eventCount`, event-type counts, diagnostics, the number of dropped diagnostics, and the finish cause.
+
+### `auditStream(events, dialect, options?)`
+
+Audits a synchronous iterable, useful for fixtures, stored diagnostic logs, and mutation tests:
+
+```js
+const report = auditStream(recordedEvents, 'anthropic-messages');
+```
+
+This function deliberately accepts only synchronous iterables. Use `createStreamAuditor` for live async streams so your application controls transport errors and cancellation.
+
+## Checks performed
+
+### Both dialects
+
+- Missing, duplicate, and post-terminal events
+- Provider events before the documented start event
+- Open content units at terminal
+- Duplicate starts/stops and deltas without an open unit
+- Hard event, open-unit, and diagnostic bounds
+- Unknown event types, reported as warnings for forward compatibility
+
+### OpenAI Responses
+
+- `response.created` lifecycle start
+- Output-item and content-part added/done pairing
+- Delta events targeting an open item or content part
+- Non-increasing `sequence_number` values when present
+- `response.completed`, `response.failed`, `response.incomplete`, `response.cancelled`, and `error` terminals
+- Terminal event name versus `response.status` contradictions
+
+### Anthropic Messages
+
+- `message_start` / `message_stop`
+- `content_block_start` / `content_block_delta` / `content_block_stop` by block index
+- Stop reason captured from `message_delta`
+- `max_tokens` and `model_context_window_exceeded` as incomplete
+- `tool_use`, `pause_turn`, and `refusal` as distinct outcomes
+- `error` as a terminal failure
+- `ping` events accepted anywhere before terminal
+
+## Diagnostics
+
+Each diagnostic includes:
+
+```ts
+{
+  severity: 'error' | 'warning';
+  code: string;
+  index: number;       // zero-based event position
+  eventType?: string;
+  // code-specific details such as unit, expected, or actual
+}
+```
+
+Warnings do not make an otherwise valid stream unsuccessful. Today, unknown future event types are warnings. Structural errors make a nominal completion `invalid`.
+
+## Testing truncation and middleware
+
+A useful regression test is cut-at-k: take a valid fixture and audit every prefix before its terminal event. No prefix should be successful.
+
+```js
+for (let cut = 0; cut < validEvents.length; cut += 1) {
+  const report = auditStream(validEvents.slice(0, cut), 'openai-responses');
+  assert.equal(report.successful, false);
+}
+```
+
+Also mutate fixtures by removing a terminal, moving a block stop before its delta, duplicating completion, inserting a provider error, and finishing with cancellation. These cases are included in this package's test suite.
+
+## Limits and non-goals
+
+- The auditor starts at the first event you feed it. Partial logs that intentionally omit earlier lifecycle events will be diagnosed as incomplete.
+- It does not validate SSE framing, `[DONE]` markers, HTTP status, headers, or byte-level decoder behavior.
+- It does not retain or compare generated text, tool arguments, token usage, model IDs, or request IDs.
+- Recognized event names follow the public provider documentation at release time. New names are warnings rather than hard failures; update the package to gain lifecycle-specific checks for them.
+- A valid event sequence does not prove output correctness, safety, authorization, or schema conformance.
+- `transport_error` records the consumer's finish cause; pass the original error separately to your logger if needed.
+
+## Troubleshooting
+
+### `missing_terminal` / `transport_closed`
+
+The iterator ended without a provider terminal. Inspect transport and SDK error channels, proxy buffering, and cancellation paths. Do not treat accumulated text as a completed model result.
+
+### `open_unit_at_terminal`
+
+An output item, content part, or Anthropic block never received its documented done/stop event. Preserve the raw event log in a secure diagnostic environment to identify where the lifecycle was truncated.
+
+### `terminal_status_mismatch`
+
+The OpenAI terminal event name disagrees with `response.status`. This may indicate a transformed or malformed fixture/proxy response. The auditor reports `invalid` rather than guessing which field is authoritative.
+
+### `unknown_event`
+
+Provider protocols can add event types. The report remains successful if no structural error exists. Check current provider documentation and update this package before depending on the new event's lifecycle semantics.
+
+### Too many diagnostics
+
+`droppedDiagnostics` counts records beyond `maxDiagnostics`. The first bounded set is retained. Increase the limit only when your logging and memory budgets permit.
+
+## Security and privacy
+
+The auditor does not retain raw event payloads or generated text by default because there is no retention option. Diagnostics contain event type, event index, lifecycle keys, and status/sequence values; those may still be sensitive in some systems. Apply your logging policy before exporting reports.
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting.
+
+## Development
+
+```sh
+npm ci
+npm run check
+node examples/audit-openai.mjs
+```
+
+## License
+
+MIT © 2026 Huzaifa Asif

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "ai-stream-auditor",
+  "version": "1.0.0",
+  "description": "Audit decoded OpenAI Responses and Anthropic Messages event lifecycles for silent or malformed stream endings.",
+  "keywords": ["ai", "streaming", "openai", "anthropic", "llm", "diagnostics", "testing"],
+  "license": "MIT",
+  "author": "Huzaifa Asif",
+  "repository": { "type": "git", "url": "git+https://github.com/Huzaifa-Asif/ai-stream-auditor.git" },
+  "bugs": { "url": "https://github.com/Huzaifa-Asif/ai-stream-auditor/issues" },
+  "homepage": "https://github.com/Huzaifa-Asif/ai-stream-auditor#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", "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,288 @@
+'use strict';
+
+const DIALECTS = Object.freeze(['openai-responses', 'anthropic-messages']);
+const DEFAULT_LIMITS = Object.freeze({ maxEvents: 100_000, maxOpenUnits: 10_000, maxDiagnostics: 1_000 });
+const OPENAI_EVENTS = new Set([
+  'error', 'response.queued', 'response.created', 'response.in_progress', 'response.completed', 'response.failed',
+  'response.incomplete', 'response.cancelled', 'response.output_item.added', 'response.output_item.done',
+  'response.content_part.added', 'response.content_part.done', 'response.output_text.delta', 'response.output_text.done',
+  'response.output_text.annotation.added', 'response.refusal.delta', 'response.refusal.done',
+  'response.function_call_arguments.delta', 'response.function_call_arguments.done',
+  'response.reasoning_summary_part.added', 'response.reasoning_summary_part.done',
+  'response.reasoning_summary_text.delta', 'response.reasoning_summary_text.done',
+  'response.reasoning_text.delta', 'response.reasoning_text.done',
+  'response.file_search_call.in_progress', 'response.file_search_call.searching', 'response.file_search_call.completed',
+  'response.web_search_call.in_progress', 'response.web_search_call.searching', 'response.web_search_call.completed',
+  'response.code_interpreter_call.in_progress', 'response.code_interpreter_call.interpreting',
+  'response.code_interpreter_call.completed', 'response.code_interpreter_call_code.delta',
+  'response.code_interpreter_call_code.done', 'response.image_generation_call.in_progress',
+  'response.image_generation_call.generating', 'response.image_generation_call.partial_image',
+  'response.image_generation_call.completed', 'response.mcp_call.in_progress', 'response.mcp_call.arguments.delta',
+  'response.mcp_call.arguments.done', 'response.mcp_call.completed', 'response.mcp_call.failed',
+  'response.mcp_list_tools.in_progress', 'response.mcp_list_tools.completed', 'response.mcp_list_tools.failed',
+  'response.audio.delta', 'response.audio.done', 'response.audio.transcript.delta', 'response.audio.transcript.done',
+]);
+const ANTHROPIC_EVENTS = new Set([
+  'message_start', 'content_block_start', 'content_block_delta', 'content_block_stop',
+  'message_delta', 'message_stop', 'ping', 'error',
+]);
+
+class StreamAuditError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'StreamAuditError';
+    this.code = code;
+  }
+}
+
+function limit(value, fallback, name) {
+  const result = value === undefined ? fallback : value;
+  if (!Number.isSafeInteger(result) || result < 1) throw new StreamAuditError(`${name} must be a positive safe integer`, 'invalid_options');
+  return result;
+}
+
+function eventType(event) {
+  return event && typeof event === 'object' && typeof event.type === 'string' ? event.type : undefined;
+}
+
+class StreamAuditor {
+  constructor(dialect, options = {}) {
+    if (!DIALECTS.includes(dialect)) throw new StreamAuditError(`unsupported dialect: ${dialect}`, 'invalid_options');
+    this.dialect = dialect;
+    this.limits = {
+      maxEvents: limit(options.maxEvents, DEFAULT_LIMITS.maxEvents, 'maxEvents'),
+      maxOpenUnits: limit(options.maxOpenUnits, DEFAULT_LIMITS.maxOpenUnits, 'maxOpenUnits'),
+      maxDiagnostics: limit(options.maxDiagnostics, DEFAULT_LIMITS.maxDiagnostics, 'maxDiagnostics'),
+    };
+    this.eventCount = 0;
+    this.counts = new Map();
+    this.diagnostics = [];
+    this.droppedDiagnostics = 0;
+    this.terminal = undefined;
+    this.started = false;
+    this.openUnits = new Map();
+    this.doneUnits = new Set();
+    this.stopReason = undefined;
+    this.lastSequence = undefined;
+    this.boundExceeded = false;
+    this.finished = false;
+  }
+
+  _diagnostic(severity, code, index, type, details) {
+    if (this.diagnostics.length >= this.limits.maxDiagnostics) {
+      this.droppedDiagnostics += 1;
+      return;
+    }
+    this.diagnostics.push(Object.freeze({ severity, code, index, ...(type ? { eventType: type } : {}), ...(details || {}) }));
+  }
+
+  _open(key, index, type) {
+    if (this.openUnits.has(key) || this.doneUnits.has(key)) {
+      this._diagnostic('error', 'duplicate_start', index, type, { unit: key });
+      return;
+    }
+    if (this.openUnits.size >= this.limits.maxOpenUnits) {
+      this.boundExceeded = true;
+      this._diagnostic('error', 'max_open_units', index, type);
+      return;
+    }
+    this.openUnits.set(key, index);
+  }
+
+  _delta(key, index, type) {
+    if (!this.openUnits.has(key)) {
+      this._diagnostic('error', this.doneUnits.has(key) ? 'delta_after_done' : 'delta_without_start', index, type, { unit: key });
+    }
+  }
+
+  _done(key, index, type) {
+    if (!this.openUnits.has(key)) {
+      this._diagnostic('error', this.doneUnits.has(key) ? 'duplicate_done' : 'done_without_start', index, type, { unit: key });
+      return;
+    }
+    this.openUnits.delete(key);
+    this.doneUnits.add(key);
+  }
+
+  _setTerminal(kind, index, type) {
+    if (this.terminal) {
+      this._diagnostic('error', 'duplicate_terminal', index, type, { previousTerminal: this.terminal.type });
+      return;
+    }
+    this.terminal = { kind, index, type };
+    for (const unit of this.openUnits.keys()) {
+      this._diagnostic('error', 'open_unit_at_terminal', index, type, { unit });
+    }
+  }
+
+  push(event) {
+    if (this.finished) throw new StreamAuditError('cannot push after finish()', 'already_finished');
+    const index = this.eventCount;
+    this.eventCount += 1;
+    if (this.eventCount > this.limits.maxEvents) {
+      if (!this.boundExceeded) this._diagnostic('error', 'max_events', index);
+      this.boundExceeded = true;
+      return this;
+    }
+    const type = eventType(event);
+    if (!type) {
+      this._diagnostic('error', 'invalid_event', index);
+      return this;
+    }
+    this.counts.set(type, (this.counts.get(type) || 0) + 1);
+    if (this.terminal) this._diagnostic('error', 'event_after_terminal', index, type, { terminal: this.terminal.type });
+    if (this.dialect === 'openai-responses') this._pushOpenAI(event, index, type);
+    else this._pushAnthropic(event, index, type);
+    return this;
+  }
+
+  _sequence(event, index, type) {
+    if (!Number.isSafeInteger(event.sequence_number)) return;
+    if (this.lastSequence !== undefined && event.sequence_number <= this.lastSequence) {
+      this._diagnostic('error', 'non_increasing_sequence', index, type, { previous: this.lastSequence, current: event.sequence_number });
+    }
+    this.lastSequence = event.sequence_number;
+  }
+
+  _pushOpenAI(event, index, type) {
+    this._sequence(event, index, type);
+    if (!OPENAI_EVENTS.has(type)) {
+      this._diagnostic('warning', 'unknown_event', index, type);
+      return;
+    }
+    if (type === 'response.created') {
+      if (this.started) this._diagnostic('error', 'duplicate_start', index, type, { unit: 'response' });
+      this.started = true;
+      return;
+    }
+    if (!this.started && type !== 'response.queued') {
+      this._diagnostic('error', 'event_before_start', index, type);
+    }
+    if (type === 'response.output_item.added') {
+      this._open(`item:${event.output_index}`, index, type);
+      return;
+    }
+    if (type === 'response.output_item.done') {
+      this._done(`item:${event.output_index}`, index, type);
+      return;
+    }
+    if (type === 'response.content_part.added') {
+      this._open(`content:${event.output_index}:${event.content_index}`, index, type);
+      return;
+    }
+    if (type === 'response.content_part.done') {
+      this._done(`content:${event.output_index}:${event.content_index}`, index, type);
+      return;
+    }
+    if (/\.delta$/.test(type)) {
+      const key = Number.isSafeInteger(event.content_index)
+        ? `content:${event.output_index}:${event.content_index}`
+        : `item:${event.output_index}`;
+      this._delta(key, index, type);
+      return;
+    }
+    if (type === 'response.completed' || type === 'response.failed' || type === 'response.incomplete' || type === 'response.cancelled' || type === 'error') {
+      const kind = type === 'response.completed' ? 'completed'
+        : type === 'response.incomplete' ? 'incomplete'
+          : type === 'response.cancelled' ? 'cancelled' : 'error';
+      if (type.startsWith('response.') && event.response && typeof event.response.status === 'string') {
+        const expected = type.slice('response.'.length);
+        if (event.response.status !== expected) {
+          this._diagnostic('error', 'terminal_status_mismatch', index, type, { expected, actual: event.response.status });
+        }
+      }
+      this._setTerminal(kind, index, type);
+    }
+  }
+
+  _pushAnthropic(event, index, type) {
+    if (!ANTHROPIC_EVENTS.has(type)) {
+      this._diagnostic('warning', 'unknown_event', index, type);
+      return;
+    }
+    if (type === 'ping') return;
+    if (type === 'message_start') {
+      if (this.started) this._diagnostic('error', 'duplicate_start', index, type, { unit: 'message' });
+      this.started = true;
+      return;
+    }
+    if (!this.started && type !== 'ping') this._diagnostic('error', 'event_before_start', index, type);
+    if (type === 'content_block_start') {
+      this._open(`block:${event.index}`, index, type);
+      return;
+    }
+    if (type === 'content_block_delta') {
+      this._delta(`block:${event.index}`, index, type);
+      return;
+    }
+    if (type === 'content_block_stop') {
+      this._done(`block:${event.index}`, index, type);
+      return;
+    }
+    if (type === 'message_delta') {
+      if (!this.started) this._diagnostic('error', 'message_delta_without_start', index, type);
+      if (event.delta && typeof event.delta.stop_reason === 'string') this.stopReason = event.delta.stop_reason;
+      return;
+    }
+    if (type === 'message_stop') {
+      if (!this.stopReason) this._diagnostic('error', 'missing_stop_reason', index, type);
+      const incomplete = this.stopReason === 'max_tokens' || this.stopReason === 'model_context_window_exceeded';
+      const refused = this.stopReason === 'refusal';
+      const kind = incomplete ? 'incomplete' : refused ? 'refusal' : 'completed';
+      this._setTerminal(kind, index, type);
+      return;
+    }
+    if (type === 'error') this._setTerminal('error', index, type);
+  }
+
+  finish(options = {}) {
+    if (this.finished) throw new StreamAuditError('finish() may only be called once', 'already_finished');
+    this.finished = true;
+    const cause = options.cause || 'iterator_end';
+    if (!['iterator_end', 'cancelled', 'timeout', 'transport_error'].includes(cause)) {
+      throw new StreamAuditError(`unsupported finish cause: ${cause}`, 'invalid_options');
+    }
+    if (!this.started && !this.terminal && this.eventCount > 0) this._diagnostic('error', 'missing_start', this.eventCount);
+    if (!this.terminal && !this.boundExceeded) this._diagnostic('error', 'missing_terminal', this.eventCount);
+
+    const hasErrors = this.diagnostics.some(({ severity }) => severity === 'error');
+    let outcome;
+    if (this.boundExceeded || hasErrors && this.terminal && this.terminal.kind === 'completed') outcome = 'invalid';
+    else if (this.terminal) outcome = this.terminal.kind === 'completed' && this.dialect === 'anthropic-messages' && this.stopReason === 'tool_use'
+      ? 'tool_use'
+      : this.terminal.kind === 'completed' && this.dialect === 'anthropic-messages' && this.stopReason === 'pause_turn'
+        ? 'paused'
+        : this.terminal.kind;
+    else if (cause === 'cancelled') outcome = 'cancelled';
+    else if (cause === 'timeout') outcome = 'timeout';
+    else if (cause === 'transport_error') outcome = 'error';
+    else outcome = 'transport_closed';
+
+    return Object.freeze({
+      dialect: this.dialect,
+      protocolComplete: Boolean(this.terminal),
+      successful: ['completed', 'tool_use', 'paused'].includes(outcome),
+      outcome,
+      stopReason: this.stopReason,
+      terminalEvent: this.terminal && this.terminal.type,
+      eventCount: this.eventCount,
+      eventTypes: Object.freeze(Object.fromEntries(this.counts)),
+      diagnostics: Object.freeze([...this.diagnostics]),
+      droppedDiagnostics: this.droppedDiagnostics,
+      finishCause: cause,
+    });
+  }
+}
+
+function createStreamAuditor(dialect, options) {
+  return new StreamAuditor(dialect, options);
+}
+
+function auditStream(events, dialect, options = {}) {
+  if (!events || typeof events[Symbol.iterator] !== 'function') throw new StreamAuditError('events must be iterable', 'invalid_options');
+  const auditor = createStreamAuditor(dialect, options);
+  for (const event of events) auditor.push(event);
+  return auditor.finish({ cause: options.cause });
+}
+
+module.exports = { DEFAULT_LIMITS, DIALECTS, StreamAuditError, StreamAuditor, auditStream, createStreamAuditor };

package/src/index.d.ts

@@ -0,0 +1,54 @@
+export type Dialect = 'openai-responses' | 'anthropic-messages';
+export type FinishCause = 'iterator_end' | 'cancelled' | 'timeout' | 'transport_error';
+export type AuditOutcome = 'completed' | 'tool_use' | 'paused' | 'incomplete' | 'refusal' | 'error' | 'cancelled' | 'timeout' | 'transport_closed' | 'invalid';
+
+export interface AuditOptions {
+  maxEvents?: number;
+  maxOpenUnits?: number;
+  maxDiagnostics?: number;
+  cause?: FinishCause;
+}
+
+export interface Diagnostic {
+  readonly severity: 'error' | 'warning';
+  readonly code: string;
+  readonly index: number;
+  readonly eventType?: string;
+  readonly [detail: string]: unknown;
+}
+
+export interface AuditReport {
+  readonly dialect: Dialect;
+  readonly protocolComplete: boolean;
+  readonly successful: boolean;
+  readonly outcome: AuditOutcome;
+  readonly stopReason?: string;
+  readonly terminalEvent?: string;
+  readonly eventCount: number;
+  readonly eventTypes: Readonly<Record<string, number>>;
+  readonly diagnostics: readonly Diagnostic[];
+  readonly droppedDiagnostics: number;
+  readonly finishCause: FinishCause;
+}
+
+export declare const DEFAULT_LIMITS: Readonly<{ maxEvents: number; maxOpenUnits: number; maxDiagnostics: number }>;
+export declare const DIALECTS: readonly Dialect[];
+
+export declare class StreamAuditError extends Error { readonly code: string }
+export declare class StreamAuditor {
+  constructor(dialect: Dialect, options?: AuditOptions);
+  push(event: unknown): this;
+  finish(options?: { cause?: FinishCause }): AuditReport;
+}
+export declare function createStreamAuditor(dialect: Dialect, options?: AuditOptions): StreamAuditor;
+export declare function auditStream(events: Iterable<unknown>, dialect: Dialect, options?: AuditOptions): AuditReport;
+
+declare const api: {
+  DEFAULT_LIMITS: typeof DEFAULT_LIMITS;
+  DIALECTS: typeof DIALECTS;
+  StreamAuditError: typeof StreamAuditError;
+  StreamAuditor: typeof StreamAuditor;
+  auditStream: typeof auditStream;
+  createStreamAuditor: typeof createStreamAuditor;
+};
+export default api;

package/src/index.js

@@ -0,0 +1,4 @@
+import api from './index.cjs';
+
+export const { DEFAULT_LIMITS, DIALECTS, StreamAuditError, StreamAuditor, auditStream, createStreamAuditor } = api;
+export default api;