instar 0.28.113 → 0.28.115

package/dist/providers/events.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Canonical event vocabulary for the provider portability substrate.
+ *
+ * Adapters normalize provider-native events to this vocabulary at the
+ * abstraction boundary. Application code (sentinels, monitors, dashboards)
+ * subscribes to these canonical events and never sees provider-specific
+ * shapes.
+ *
+ * Canonical event design rules:
+ *   1. Discriminated by `type` for exhaustiveness checks.
+ *   2. Every event carries a `timestamp` (ISO 8601 UTC).
+ *   3. Every event includes the `providerId` of the emitting adapter, so
+ *      consumers logging events have provenance.
+ *   4. Provider-specific data goes under `providerSpecific` (escape hatch
+ *      for the rare consumer that needs it — most should ignore).
+ *
+ * Adding a new event type:
+ *   1. Add the variant to the `CanonicalEvent` union below.
+ *   2. Update the conformance suite to verify adapters emit it correctly.
+ *   3. Document the mapping for each adapter in `specs/provider-portability/`.
+ *
+ * Provider-native events that have no canonical equivalent fall back to
+ * `ProviderRawEvent` — but use sparingly; raw events leak the abstraction.
+ */
+import type { ProviderId, ProviderSpecific, SessionHandle } from './types.js';
+interface EventBase {
+    /** Discriminator. */
+    readonly type: string;
+    /** ISO 8601 UTC timestamp of when the event was observed. */
+    readonly timestamp: string;
+    /** Adapter that emitted (and presumably normalized) the event. */
+    readonly providerId: ProviderId;
+    /** Session this event pertains to, when applicable. */
+    readonly session?: SessionHandle;
+    /** Escape hatch for adapter-specific extension fields. */
+    readonly providerSpecific?: ProviderSpecific;
+}
+/**
+ * Incremental message content from the model. Emitted during streaming
+ * generation. Concatenate `delta` values to reconstruct the full response.
+ *
+ * For Claude: derived from `message.content[].text` deltas in the JSONL stream.
+ * For Codex: derived from `item.agentMessage.delta` notifications.
+ */
+export interface MessageDeltaEvent extends EventBase {
+    readonly type: 'message-delta';
+    /** Text chunk produced since the previous delta. */
+    readonly delta: string;
+    /** Cumulative content so far in this turn (optional — adapters may omit). */
+    readonly cumulative?: string;
+}
+/**
+ * Model has invoked a tool. Emitted when the model emits a tool call,
+ * BEFORE the tool's result is known.
+ */
+export interface ToolCallEvent extends EventBase {
+    readonly type: 'tool-call';
+    /** Provider-side ID for matching to the corresponding ToolResultEvent. */
+    readonly toolCallId: string;
+    /** Tool name as registered with the provider. */
+    readonly toolName: string;
+    /** Arguments passed to the tool, as a structured value. */
+    readonly arguments: unknown;
+}
+/**
+ * Tool execution finished. Pairs with a previous ToolCallEvent by `toolCallId`.
+ */
+export interface ToolResultEvent extends EventBase {
+    readonly type: 'tool-result';
+    readonly toolCallId: string;
+    /** Tool's return value. */
+    readonly result: unknown;
+    /** Whether the tool reported an error. */
+    readonly isError: boolean;
+}
+/**
+ * A model "turn" (single inference call) has completed. Fires once per turn,
+ * after all deltas and tool calls for that turn have been emitted.
+ */
+export interface TurnEndEvent extends EventBase {
+    readonly type: 'turn-end';
+    /** Reason the turn ended. */
+    readonly stopReason: 'end-of-turn' | 'tool-use' | 'max-tokens' | 'stop-sequence' | 'interrupted' | 'unknown';
+    /** Usage report for this turn, if the adapter has authoritative data. */
+    readonly usage: import('./types.js').UsageReport | null;
+}
+/**
+ * Session lifecycle event — start, end, fork, rollback, compact.
+ */
+export interface SessionLifecycleEvent extends EventBase {
+    readonly type: 'session-lifecycle';
+    readonly lifecycleKind: 'started' | 'ended' | 'forked' | 'rolled-back' | 'compact-pending' | 'compacted' | 'paused' | 'resumed';
+    /** For forked / rolled-back, the source session and turn index. */
+    readonly source?: {
+        session: SessionHandle;
+        turnIndex?: number;
+    };
+}
+/**
+ * Subagent (child session spawned by the parent agent) lifecycle event.
+ * Adapters that lack native subagent hooks (e.g., Codex) synthesize these
+ * from app-server thread notifications.
+ */
+export interface SubagentLifecycleEvent extends EventBase {
+    readonly type: 'subagent-lifecycle';
+    readonly lifecycleKind: 'started' | 'completed' | 'failed';
+    readonly parentSession: SessionHandle;
+    readonly childSession: SessionHandle;
+    readonly purpose?: string;
+}
+/**
+ * An interactive prompt was emitted by the provider (permission request,
+ * confirmation, selection). Carries the structured data when the adapter
+ * has it (Codex app-server emits structured approval events); falls back
+ * to raw terminal capture for adapters that only have TTY (Claude).
+ */
+export interface InteractivePromptEvent extends EventBase {
+    readonly type: 'interactive-prompt';
+    readonly promptKind: 'permission' | 'confirmation' | 'selection' | 'plan' | 'unknown';
+    /** Human-readable summary of what the prompt is asking. */
+    readonly summary: string;
+    /** Choices for selection-kind prompts. */
+    readonly choices?: ReadonlyArray<{
+        label: string;
+        value: string;
+    }>;
+    /** Whether this is structured (parsed event) or scraped (from terminal output). */
+    readonly source: 'structured' | 'scraped';
+}
+/**
+ * Provider raised an error mid-stream. Distinguished from thrown errors
+ * because the stream may continue (recoverable error) or be ending
+ * (terminal error). Check `recoverable`.
+ */
+export interface ErrorEvent extends EventBase {
+    readonly type: 'error';
+    readonly message: string;
+    readonly recoverable: boolean;
+    readonly errorKind: 'auth' | 'quota' | 'rate-limit' | 'timeout' | 'network' | 'malformed-response' | 'unsupported' | 'unknown';
+}
+/**
+ * Escape hatch for provider-native events that don't normalize to anything
+ * above. Use sparingly — every ProviderRawEvent is a leak in the abstraction.
+ * When you find yourself emitting these repeatedly for the same kind of
+ * thing, that's a signal to add a new canonical event type instead.
+ */
+export interface ProviderRawEvent extends EventBase {
+    readonly type: 'provider-raw';
+    /** Provider's own event name (e.g., 'item.commandExecution.outputDelta'). */
+    readonly nativeName: string;
+    /** Raw payload, shape-defined-by-provider. */
+    readonly payload: unknown;
+}
+export type CanonicalEvent = MessageDeltaEvent | ToolCallEvent | ToolResultEvent | TurnEndEvent | SessionLifecycleEvent | SubagentLifecycleEvent | InteractivePromptEvent | ErrorEvent | ProviderRawEvent;
+/** Type alias for the discriminator field values. */
+export type CanonicalEventType = CanonicalEvent['type'];
+/**
+ * Exhaustiveness helper for `switch` statements over CanonicalEventType.
+ * Use as the `default:` case to get compile-time errors when new variants
+ * are added but not handled.
+ */
+export declare function assertExhaustiveEvent(event: never): never;
+/** Type guard: is this event from the given adapter? */
+export declare function isFromProvider(event: CanonicalEvent, providerId: ProviderId): boolean;
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/providers/events.d.ts.map

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

package/dist/providers/events.js

@@ -0,0 +1,38 @@
+/**
+ * Canonical event vocabulary for the provider portability substrate.
+ *
+ * Adapters normalize provider-native events to this vocabulary at the
+ * abstraction boundary. Application code (sentinels, monitors, dashboards)
+ * subscribes to these canonical events and never sees provider-specific
+ * shapes.
+ *
+ * Canonical event design rules:
+ *   1. Discriminated by `type` for exhaustiveness checks.
+ *   2. Every event carries a `timestamp` (ISO 8601 UTC).
+ *   3. Every event includes the `providerId` of the emitting adapter, so
+ *      consumers logging events have provenance.
+ *   4. Provider-specific data goes under `providerSpecific` (escape hatch
+ *      for the rare consumer that needs it — most should ignore).
+ *
+ * Adding a new event type:
+ *   1. Add the variant to the `CanonicalEvent` union below.
+ *   2. Update the conformance suite to verify adapters emit it correctly.
+ *   3. Document the mapping for each adapter in `specs/provider-portability/`.
+ *
+ * Provider-native events that have no canonical equivalent fall back to
+ * `ProviderRawEvent` — but use sparingly; raw events leak the abstraction.
+ */
+// ── Utility helpers ───────────────────────────────────────────────────
+/**
+ * Exhaustiveness helper for `switch` statements over CanonicalEventType.
+ * Use as the `default:` case to get compile-time errors when new variants
+ * are added but not handled.
+ */
+export function assertExhaustiveEvent(event) {
+    throw new Error(`Unhandled canonical event variant: ${JSON.stringify(event)}`);
+}
+/** Type guard: is this event from the given adapter? */
+export function isFromProvider(event, providerId) {
+    return event.providerId === providerId;
+}
+//# sourceMappingURL=events.js.map

package/dist/providers/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/providers/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA4KH,yEAAyE;AAEzE;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAY;IAChD,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AACjF,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,cAAc,CAAC,KAAqB,EAAE,UAAsB;IAC1E,OAAO,KAAK,CAAC,UAAU,KAAK,UAAU,CAAC;AACzC,CAAC"}

package/dist/providers/markers.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Substrate-level markers used by adapter implementations to declare
+ * properties of a primitive that the registry, routing layer, or test
+ * harness needs to read without invoking the primitive.
+ *
+ * Symbols are used (rather than string property names) so adapters can't
+ * accidentally collide with primitive interface fields. The presence of
+ * a marker is observable; reading it does not trigger a throwing stub's
+ * "not implemented" branch.
+ */
+/**
+ * Marker attached to throwing-stub primitives by an adapter's
+ * `createStubPrimitive` factory. When present and truthy, the primitive
+ * claims a capability flag on the registry but every method call throws
+ * UnsupportedCapabilityError.
+ *
+ * The Phase 3c parity harness uses this to distinguish real
+ * implementations from placeholder stubs — without it, a paired-adapter
+ * scenario could pass for the wrong reason (both sides returned non-null
+ * stubs that happen to satisfy `!= null`).
+ *
+ * Real primitives MUST NOT set this marker. Stub factories MUST set it
+ * to `true`.
+ */
+export declare const STUB_MARKER: unique symbol;
+/**
+ * Test whether a primitive impl is a throwing stub.
+ *
+ * Returns true for stubs created by an adapter's `createStubPrimitive`
+ * factory, false for real implementations. Reading the marker via Symbol
+ * key does NOT trigger a stub's throwing-method branch (Proxy traps only
+ * fire on get for string properties that the stub doesn't whitelist).
+ */
+export declare function isStubPrimitive(impl: unknown): boolean;
+//# sourceMappingURL=markers.d.ts.map

package/dist/providers/markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.d.ts","sourceRoot":"","sources":["../../src/providers/markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,EAAE,OAAO,MAA6C,CAAC;AAE/E;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKtD"}

package/dist/providers/markers.js

@@ -0,0 +1,40 @@
+/**
+ * Substrate-level markers used by adapter implementations to declare
+ * properties of a primitive that the registry, routing layer, or test
+ * harness needs to read without invoking the primitive.
+ *
+ * Symbols are used (rather than string property names) so adapters can't
+ * accidentally collide with primitive interface fields. The presence of
+ * a marker is observable; reading it does not trigger a throwing stub's
+ * "not implemented" branch.
+ */
+/**
+ * Marker attached to throwing-stub primitives by an adapter's
+ * `createStubPrimitive` factory. When present and truthy, the primitive
+ * claims a capability flag on the registry but every method call throws
+ * UnsupportedCapabilityError.
+ *
+ * The Phase 3c parity harness uses this to distinguish real
+ * implementations from placeholder stubs — without it, a paired-adapter
+ * scenario could pass for the wrong reason (both sides returned non-null
+ * stubs that happen to satisfy `!= null`).
+ *
+ * Real primitives MUST NOT set this marker. Stub factories MUST set it
+ * to `true`.
+ */
+export const STUB_MARKER = Symbol.for('@instar/providers/stub');
+/**
+ * Test whether a primitive impl is a throwing stub.
+ *
+ * Returns true for stubs created by an adapter's `createStubPrimitive`
+ * factory, false for real implementations. Reading the marker via Symbol
+ * key does NOT trigger a stub's throwing-method branch (Proxy traps only
+ * fire on get for string properties that the stub doesn't whitelist).
+ */
+export function isStubPrimitive(impl) {
+    if (impl == null || (typeof impl !== 'object' && typeof impl !== 'function')) {
+        return false;
+    }
+    return impl[STUB_MARKER] === true;
+}
+//# sourceMappingURL=markers.js.map

package/dist/providers/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../../src/providers/markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,WAAW,GAAkB,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;AAE/E;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,UAAU,CAAC,EAAE,CAAC;QAC7E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAQ,IAAgC,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;AACjE,CAAC"}

package/dist/providers/parity/_codex_paritytest.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Codex-vs-Anthropic parity test — Phase 4 step 4.
+ *
+ * Runs the same scenario set against `anthropic-headless` (left) and
+ * `openai-codex` (right). The Phase 4 acceptance test: can the substrate
+ * abstract over BOTH providers correctly, not just two Anthropic flavors?
+ *
+ * Real-API scenarios are gated by INSTAR_REAL_API=1 AND require valid
+ * credentials for both providers. Structural-only scenarios always run.
+ *
+ * Run with:
+ *   npx tsx src/providers/parity/_codex_paritytest.ts
+ *   INSTAR_REAL_API=1 npx tsx src/providers/parity/_codex_paritytest.ts
+ */
+export {};
+//# sourceMappingURL=_codex_paritytest.d.ts.map

package/dist/providers/parity/_codex_paritytest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_codex_paritytest.d.ts","sourceRoot":"","sources":["../../../src/providers/parity/_codex_paritytest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/providers/parity/_codex_paritytest.js

@@ -0,0 +1,37 @@
+/**
+ * Codex-vs-Anthropic parity test — Phase 4 step 4.
+ *
+ * Runs the same scenario set against `anthropic-headless` (left) and
+ * `openai-codex` (right). The Phase 4 acceptance test: can the substrate
+ * abstract over BOTH providers correctly, not just two Anthropic flavors?
+ *
+ * Real-API scenarios are gated by INSTAR_REAL_API=1 AND require valid
+ * credentials for both providers. Structural-only scenarios always run.
+ *
+ * Run with:
+ *   npx tsx src/providers/parity/_codex_paritytest.ts
+ *   INSTAR_REAL_API=1 npx tsx src/providers/parity/_codex_paritytest.ts
+ */
+import { createAnthropicHeadlessAdapter } from '../adapters/anthropic-headless/index.js';
+import { createOpenAiCodexAdapter } from '../adapters/openai-codex/index.js';
+import { allParityScenarios, runParitySuite, reportParityResults, } from './index.js';
+async function main() {
+    const realApi = process.env['INSTAR_REAL_API'] === '1';
+    // eslint-disable-next-line no-console
+    console.log(`Codex×Anthropic parity suite — realApi=${realApi}`);
+    const left = createAnthropicHeadlessAdapter();
+    const right = createOpenAiCodexAdapter();
+    const results = await runParitySuite({
+        left: left,
+        right: right,
+        ctx: { realApi, timeoutMs: 120_000 },
+    }, allParityScenarios);
+    const exitCode = reportParityResults(results);
+    process.exit(exitCode);
+}
+void main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error('codex parity suite crashed:', err);
+    process.exit(2);
+});
+//# sourceMappingURL=_codex_paritytest.js.map

package/dist/providers/parity/_codex_paritytest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_codex_paritytest.js","sourceRoot":"","sources":["../../../src/providers/parity/_codex_paritytest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AACzF,OAAO,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,KAAK,GAAG,CAAC;IACvD,sCAAsC;IACtC,OAAO,CAAC,GAAG,CAAC,0CAA0C,OAAO,EAAE,CAAC,CAAC;IAEjE,MAAM,IAAI,GAAG,8BAA8B,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAG,wBAAwB,EAAE,CAAC;IAEzC,MAAM,OAAO,GAAG,MAAM,cAAc,CAClC;QACE,IAAI,EAAE,IAA+D;QACrE,KAAK,EAAE,KAAiE;QACxE,GAAG,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE;KACrC,EACD,kBAAkB,CACnB,CAAC;IAEF,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACxB,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/providers/parity/_paritytest.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Runnable parity test — exercises the two Anthropic adapters against
+ * each other via every scenario in {@link allParityScenarios}.
+ *
+ * Real-API scenarios are gated by INSTAR_REAL_API=1. Without it, only
+ * structural scenarios run (capability declarations, primitive shape).
+ * Both modes are useful: structural-only catches regressions cheap;
+ * real-API mode catches behavioral drift before it ships.
+ *
+ * Run with:
+ *   npx tsx src/providers/parity/_paritytest.ts
+ *   INSTAR_REAL_API=1 npx tsx src/providers/parity/_paritytest.ts
+ */
+export {};
+//# sourceMappingURL=_paritytest.d.ts.map

package/dist/providers/parity/_paritytest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_paritytest.d.ts","sourceRoot":"","sources":["../../../src/providers/parity/_paritytest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/providers/parity/_paritytest.js

@@ -0,0 +1,36 @@
+/**
+ * Runnable parity test — exercises the two Anthropic adapters against
+ * each other via every scenario in {@link allParityScenarios}.
+ *
+ * Real-API scenarios are gated by INSTAR_REAL_API=1. Without it, only
+ * structural scenarios run (capability declarations, primitive shape).
+ * Both modes are useful: structural-only catches regressions cheap;
+ * real-API mode catches behavioral drift before it ships.
+ *
+ * Run with:
+ *   npx tsx src/providers/parity/_paritytest.ts
+ *   INSTAR_REAL_API=1 npx tsx src/providers/parity/_paritytest.ts
+ */
+import { createAnthropicHeadlessAdapter } from '../adapters/anthropic-headless/index.js';
+import { createAnthropicInteractivePoolAdapter } from '../adapters/anthropic-interactive-pool/index.js';
+import { allParityScenarios, runParitySuite, reportParityResults, } from './index.js';
+async function main() {
+    const realApi = process.env['INSTAR_REAL_API'] === '1';
+    // eslint-disable-next-line no-console
+    console.log(`Parity suite — realApi=${realApi}`);
+    const left = createAnthropicHeadlessAdapter();
+    const right = createAnthropicInteractivePoolAdapter({ poolSize: 1 });
+    const results = await runParitySuite({
+        left: left,
+        right: right,
+        ctx: { realApi, timeoutMs: 120_000 },
+    }, allParityScenarios);
+    const exitCode = reportParityResults(results);
+    process.exit(exitCode);
+}
+void main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error('parity suite crashed:', err);
+    process.exit(2);
+});
+//# sourceMappingURL=_paritytest.js.map

package/dist/providers/parity/_paritytest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_paritytest.js","sourceRoot":"","sources":["../../../src/providers/parity/_paritytest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,8BAA8B,EAAE,MAAM,yCAAyC,CAAC;AACzF,OAAO,EAAE,qCAAqC,EAAE,MAAM,iDAAiD,CAAC;AACxG,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,KAAK,GAAG,CAAC;IACvD,sCAAsC;IACtC,OAAO,CAAC,GAAG,CAAC,0BAA0B,OAAO,EAAE,CAAC,CAAC;IAEjD,MAAM,IAAI,GAAG,8BAA8B,EAAE,CAAC;IAC9C,MAAM,KAAK,GAAG,qCAAqC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;IAErE,MAAM,OAAO,GAAG,MAAM,cAAc,CAClC;QACE,IAAI,EAAE,IAA+D;QACrE,KAAK,EAAE,KAAiE;QACxE,GAAG,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE;KACrC,EACD,kBAAkB,CACnB,CAAC;IAEF,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACxB,sCAAsC;IACtC,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAC;IAC5C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/providers/parity/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Phase 3c — behavior-parity scenarios across paired adapters.
+ *
+ * Public entry point. Import {@link runParitySuite} and any scenario
+ * sets, construct two adapters, and run.
+ */
+export { runParitySuite, reportParityResults } from './runner.js';
+export type { ParityContext, ParityHarness, ParityResult, ParityScenario, } from './runner.js';
+export { oneShotCompletionScenarios } from './scenarios/oneShotCompletion.js';
+export { capabilityOverlapScenarios } from './scenarios/capabilityOverlap.js';
+export { sessionIdScenarios } from './scenarios/sessionId.js';
+/**
+ * The full Phase 3c scenario set. Adapters wiring this in for the first
+ * time should start here, then layer in optional / asymmetric primitive
+ * scenarios as they're written.
+ */
+export declare const allParityScenarios: readonly [{
+    readonly name: "capability/distinctIds";
+    readonly run: import("./runner.js").ParityScenario;
+}, {
+    readonly name: "capability/sharedCapabilitiesInstantiate";
+    readonly run: import("./runner.js").ParityScenario;
+}, {
+    readonly name: "oneShot/primitiveShape";
+    readonly run: import("./runner.js").ParityScenario;
+}, {
+    readonly name: "oneShot/arithmeticParity";
+    readonly run: import("./runner.js").ParityScenario;
+}, {
+    readonly name: "oneShot/abortSignalParity";
+    readonly run: import("./runner.js").ParityScenario;
+}, {
+    readonly name: "sessionId/shape";
+    readonly run: import("./runner.js").ParityScenario;
+}, {
+    readonly name: "sessionId/unknownHandle";
+    readonly run: import("./runner.js").ParityScenario;
+}];
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/parity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/parity/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAM9D;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAIrB,CAAC"}

package/dist/providers/parity/index.js

@@ -0,0 +1,24 @@
+/**
+ * Phase 3c — behavior-parity scenarios across paired adapters.
+ *
+ * Public entry point. Import {@link runParitySuite} and any scenario
+ * sets, construct two adapters, and run.
+ */
+export { runParitySuite, reportParityResults } from './runner.js';
+export { oneShotCompletionScenarios } from './scenarios/oneShotCompletion.js';
+export { capabilityOverlapScenarios } from './scenarios/capabilityOverlap.js';
+export { sessionIdScenarios } from './scenarios/sessionId.js';
+import { oneShotCompletionScenarios } from './scenarios/oneShotCompletion.js';
+import { capabilityOverlapScenarios } from './scenarios/capabilityOverlap.js';
+import { sessionIdScenarios } from './scenarios/sessionId.js';
+/**
+ * The full Phase 3c scenario set. Adapters wiring this in for the first
+ * time should start here, then layer in optional / asymmetric primitive
+ * scenarios as they're written.
+ */
+export const allParityScenarios = [
+    ...capabilityOverlapScenarios,
+    ...oneShotCompletionScenarios,
+    ...sessionIdScenarios,
+];
+//# sourceMappingURL=index.js.map

package/dist/providers/parity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/parity/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAQlE,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,GAAG,0BAA0B;IAC7B,GAAG,0BAA0B;IAC7B,GAAG,kBAAkB;CACb,CAAC"}

package/dist/providers/parity/runner.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Behavior-parity test runner.
+ *
+ * Phase 2 conformance suites verify a single adapter's contract shape.
+ * Phase 3c parity scenarios go one level deeper: given TWO adapters that
+ * claim the same capability, send identical inputs to both and assert
+ * observable equivalence.
+ *
+ * This catches drift between sibling adapters (e.g. anthropic-headless vs
+ * anthropic-interactive-pool) where each correctly implements the
+ * primitive contract in isolation but their externally-observable behavior
+ * disagrees on edge cases — empty prompts, control characters, very long
+ * outputs, error shapes, cancellation semantics.
+ *
+ * Design notes:
+ *   - Scenarios are async functions that receive a ParityHarness and
+ *     return a ParityResult describing what they observed.
+ *   - The runner orchestrates lifecycle (start / dispose) for both
+ *     adapters and aggregates results.
+ *   - "Equivalent" is scenario-defined — scenarios assert structural
+ *     equivalence (same error class, same response length bucket) rather
+ *     than literal string equality, because LLM outputs aren't
+ *     deterministic.
+ *   - Real-API scenarios are gated by ctx.realApi; structural-only
+ *     scenarios (capability-flag presence, primitive instantiation)
+ *     always run.
+ */
+import type { ProviderAdapter } from '../registry.js';
+export interface ParityContext {
+    /** Whether to run scenarios that hit a real provider API. */
+    realApi: boolean;
+    /** Per-scenario timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Optional skip patterns — scenarios whose name matches are skipped. */
+    skipPatterns?: ReadonlyArray<RegExp>;
+}
+export interface ParityHarness {
+    readonly left: ProviderAdapter & {
+        start?(): Promise<void>;
+        dispose?(): Promise<void>;
+    };
+    readonly right: ProviderAdapter & {
+        start?(): Promise<void>;
+        dispose?(): Promise<void>;
+    };
+    readonly ctx: ParityContext;
+}
+export interface ParityResult {
+    scenario: string;
+    status: 'pass' | 'fail' | 'skip';
+    reason?: string;
+    /**
+     * Free-form scenario-specific observations attached to the result for
+     * post-hoc inspection. Scenarios typically include both adapters'
+     * observable outputs (under `left`/`right`) plus any context (counts,
+     * timings) the failure mode needs to be diagnosable.
+     */
+    observations?: Record<string, unknown>;
+}
+export type ParityScenario = (h: ParityHarness) => Promise<ParityResult>;
+/**
+ * Run every scenario against the pair of adapters and aggregate results.
+ *
+ * Adapter lifecycle: start() called once before scenarios (if defined),
+ * dispose() called once after (if defined). Scenarios run sequentially —
+ * concurrent execution against pool-backed adapters can cause queueing
+ * effects that confound parity comparisons.
+ */
+export declare function runParitySuite(harness: ParityHarness, scenarios: ReadonlyArray<{
+    name: string;
+    run: ParityScenario;
+}>): Promise<ReadonlyArray<ParityResult>>;
+/**
+ * Pretty-print a parity result set to stdout. Returns process exit code
+ * (0 if all pass-or-skip, 1 if any fail).
+ */
+export declare function reportParityResults(results: ReadonlyArray<ParityResult>): number;
+//# sourceMappingURL=runner.d.ts.map

package/dist/providers/parity/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/providers/parity/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG;QAAE,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IACxF,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG;QAAE,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IACzF,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAEzE;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,cAAc,CAAA;CAAE,CAAC,GAC9D,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAyCtC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAYhF"}