@anureo/sdk 0.0.0-stage → 0.3.0

package/src/structured-output/session.js

@@ -0,0 +1,846 @@
+// Owns per-session output admission, execution association, publication and revocation.
+import { randomBytes } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { assertEvent } from '@anureo/protocol';
+import { HarnessSdkError, sdkError } from "../errors.js";
+import { guardRequest } from "../requests/guard.js";
+import { OUTPUT_SERVER_NAME, toolError } from "./tool.js";
+import { compileOutputSchema } from "./schema.js";
+import { checkRelease, failure } from "./errors.js";
+/**
+ * Internal BackendSession implementation constructed and tracked by withStructuredOutput's
+ * openSession port. Client.attachSession gives this wrapper to Session, which reads attachment state,
+ * dispatches through execute and releases it through disposeBackend. Owns one native session's output
+ * associations, fallback lane and serialized commitment. Hosts observe receipts independently of
+ * final events, and caller wait cancellation leaves native work and lane ownership alive.
+ */
+export class OutputSession {
+    /**
+     * withStructuredOutput's openSession port constructs this wrapper before tracking and opening it.
+     * Capture dependencies without I/O. The wrapper must await open before attachment and dispose on
+     * setup failure. dispose invokes forget after release attempts so adapter ownership can be removed.
+     */
+    constructor(input) {
+        this.params = input.params;
+        this.sink = input.sink;
+        this.manager = input.manager;
+        this.limits = input.limits;
+        this.forget = input.forget;
+    }
+    /** Session.attach reads the native binding after open. validateEnvelope uses the requested identity until the native backend is available. */
+    get binding() { return this.backend?.binding ?? this.params.binding; }
+    /** Session.attach adopts this capability projection. The native tool or MCP lease can supply schema support without mutating backend capabilities. */
+    get capabilities() { return this.projectCapabilities(this.backend?.capabilities ?? {}); }
+    /** Session.attach restores this optional projected native state. Return a credential-redacted snapshot with the fallback capability revision applied. */
+    get state() { return this.backend?.state ? this.redact(this.projectState(this.backend.state)) : undefined; }
+    /**
+     * withStructuredOutput's openSession port awaits this before Client.attachSession receives the
+     * wrapper. Prepare an optional bridge before native open, then adopt the backend and its active
+     * turns. A reserved bridge name, lease cleanup failure or warning publication failure rejects
+     * setup. Other bridge preparation failures warn and continue. If disposal wins the open race,
+     * await native release and reject with its failure or SESSION_CLOSED.
+     * nativeOutput is the initialization negotiation result, used only to decide bridge preparation;
+     * per-session capabilities decide submission mode. Native-open and release failures reject to the
+     * adapter wrapper, which owns setup cleanup.
+     */
+    async open({ adapter, nativeOutput }) {
+        // The optional port is an execution-location attestation, not a provider-name heuristic.
+        const transport = nativeOutput ? undefined : adapter.outputBridgeTransport?.(this.params);
+        // Avoid a promise turn before native dispatch when no bridge needs preparation.
+        const params = transport ? await this.prepareBridge(transport) : this.params;
+        const backend = await adapter.openSession(structuredClone(params), this.nativeSink());
+        this.backend = backend;
+        if (this.disposed) {
+            await backend.dispose();
+            throw new HarnessSdkError('SESSION_CLOSED');
+        }
+        backend.state?.activeTurnIds.forEach(id => this.active.add(id));
+        return this;
+    }
+    /**
+     * Session.invokeRequest invokes this BackendSession port; Session.executeRequest validates and
+     * projects its result. Prepare output policy, check the transformed request against native
+     * capabilities, and dispatch once. Bind any receipt turn before returning. A native close
+     * receipt revokes output admission before the wrapper returns to Session. Failures
+     * reclaim only definitely rejected, unbound submissions and preserve safe cleanup diagnostics.
+     * Session owns request replay, caller wait cancellation and native-result validation. These waits
+     * never release a live output lane.
+     */
+    async execute(method, original) {
+        if (this.disposed || !this.backend)
+            throw new HarnessSdkError('SESSION_CLOSED');
+        const params = structuredClone(original);
+        if (this.locked && ['input/submit', 'review/start', 'compact/start', 'session/config/set', 'session/revert'].includes(method))
+            throw new HarnessSdkError('STRUCTURED_OUTPUT_BUSY');
+        let submissionId;
+        try {
+            submissionId = requestSubmissionId(method, params);
+            const prepared = await this.prepareSubmission(method, params, submissionId);
+            const result = await this.dispatch(method, prepared, this.backend);
+            if (submissionId && result && typeof result === 'object' && 'turnId' in result && typeof result.turnId === 'string') {
+                const boundSubmissionId = submissionId;
+                await this.enqueue(() => this.bind(boundSubmissionId, result.turnId));
+            }
+            if (method === 'session/config/set')
+                return this.redact(this.projectState(result));
+            if (method === 'history/read')
+                return this.redact(result);
+            if (method === 'session/close')
+                await this.release();
+            return result;
+        }
+        catch (cause) {
+            return this.rejectDispatch(cause, submissionId);
+        }
+    }
+    /**
+     * withStructuredOutput's setup-failure/dispose paths and Session.disposeBackend await this shared
+     * cleanup promise. Close admission immediately, release output resources, then attempt backend
+     * disposal even after release rejection. Remove adapter ownership after both stages and propagate
+     * classified cleanup failures. open separately releases a backend that arrives after this teardown.
+     */
+    dispose() {
+        return this.disposal ??= (async () => {
+            this.disposed = true;
+            const results = await Promise.allSettled([this.release()]);
+            results.push(...await Promise.allSettled([this.backend?.dispose()]));
+            this.forget();
+            checkRelease(results);
+        })();
+    }
+    backend;
+    lease;
+    disposed = false;
+    disposal;
+    chain = Promise.resolve();
+    queuedBytes = 0;
+    queuedEvents = 0;
+    heldBytes = 0;
+    heldCount = 0;
+    outputBytes = 0;
+    pending = new Map();
+    outputs = new Map();
+    byTurn = new Map();
+    unresolved = new Set();
+    active = new Set();
+    terminalVersions = new Map();
+    terminalVersion = 0;
+    locked;
+    privateStrings = new Set();
+    params;
+    sink;
+    manager;
+    limits;
+    forget;
+    /**
+     * execute calls this after preparing the request. Validate its frame size, protocol shape and
+     * native binding and capabilities before dispatch. Return the native promise directly so the close
+     * continuation can revoke output admission as soon as its receipt arrives.
+     */
+    dispatch(method, params, backend) {
+        if (Buffer.byteLength(JSON.stringify(params)) > (this.limits.queue?.maxFrameBytes ?? 8 * 1024 * 1024))
+            throw new HarnessSdkError('FRAME_TOO_LARGE');
+        guardRequest(method, params, this.binding.sessionId, backend.capabilities);
+        return backend.execute(method, params);
+    }
+    /**
+     * open awaits this only for an attested MCP transport. Retain a lease and its private credentials
+     * before returning augmented native-open params. A reserved name rejects before allocation; other
+     * setup failures release any lease and publish a warning before returning the original params.
+     * Cleanup or warning-publication failures reject open, whose adapter caller owns session disposal.
+     */
+    async prepareBridge(transport) {
+        if (this.params.mcpServers?.some(server => server.name === OUTPUT_SERVER_NAME))
+            throw new HarnessSdkError('INVALID_PARAMS', 'Reserved MCP server name');
+        try {
+            this.lease = await this.manager.create(transport, args => this.enqueue(async () => this.submitValue(args)));
+            const config = this.lease.config;
+            if (config.type === 'http') {
+                this.privateStrings.add(config.url);
+                Object.values(config.headers ?? {}).forEach(value => this.privateStrings.add(value));
+            }
+            else
+                Object.values(config.env ?? {}).forEach(value => this.privateStrings.add(value));
+            return { ...this.params, mcpServers: [...(this.params.mcpServers ?? []), config] };
+        }
+        catch {
+            await this.lease?.dispose();
+            this.lease = undefined;
+            await this.sink.emit({ type: 'notice', payload: { severity: 'warning', code: 'STRUCTURED_OUTPUT_BRIDGE_UNAVAILABLE', message: 'Structured output bridge could not be prepared' } });
+            return this.params;
+        }
+    }
+    /**
+     * open supplies these callbacks to the native adapter, which may invoke them before attachment.
+     * Route events and bindings through serialized output policy. Session handles interactions and
+     * direct failure reports. tryEmit returns false when admission throws and forwards both immediate
+     * and asynchronous failures to Session.fail.
+     */
+    nativeSink() {
+        return {
+            bindSubmission: (submissionId, turnId) => this.emit({ type: 'submission/bound', payload: { submissionId, turnId } }),
+            emit: (event, scope = {}) => this.emit(event, scope),
+            tryEmit: (event, scope = {}) => {
+                try {
+                    const operation = this.emit(event, scope);
+                    void operation.catch(cause => this.sink.fail(cause));
+                    return true;
+                }
+                catch (cause) {
+                    void this.sink.fail(cause);
+                    return false;
+                }
+            },
+            requestInteraction: (request, responder) => this.sink.requestInteraction(request, responder),
+            resolveInteraction: result => this.sink.resolveInteraction(result),
+            fail: cause => this.sink.fail(cause),
+        };
+    }
+    /**
+     * execute returns this rejection after preparation, dispatch or result projection fails. Reclaim
+     * only definite submission failures; reject leaves already-bound work alive until its terminal.
+     * Preserve the original cause unless cleanup fails, then attach safe cleanup diagnostics without
+     * replacing the dispatch error code or outcome. Unknown acceptance retains its output lane.
+     */
+    async rejectDispatch(cause, submissionId) {
+        if (submissionId && !sdkError(cause).outcomeUnknown) {
+            try {
+                await this.reject(submissionId);
+            }
+            catch (cleanup) {
+                const error = sdkError(cause), release = sdkError(cleanup, 'RESOURCE_RELEASE_FAILED', true);
+                throw new HarnessSdkError(error.code, error.message, error.retryable, error.outcomeUnknown, { ...error.details, cleanupErrors: [{ code: release.code, outcomeUnknown: release.outcomeUnknown }] });
+            }
+        }
+        throw cause;
+    }
+    /**
+     * The capabilities getter and projectState return this projection to Session attachment
+     * and state observers. Prefer the native tool extension over the MCP extension when both exist,
+     * retaining native schema support and suppressing fallback advertisement after disposal.
+     */
+    projectCapabilities(raw) {
+        const extension = this.backend?.structuredOutputTool ? { name: 'x-anureo/structured-output-tool', version: '1' } : this.lease ? EXTENSION : undefined;
+        if (raw.turn?.outputSchema || !extension || this.disposed)
+            return structuredClone(raw);
+        return { ...structuredClone(raw), turn: { ...raw.turn, outputSchema: true }, extensions: [...(raw.extensions ?? []).filter(value => value.name !== extension.name), extension] };
+    }
+    /**
+     * The state getter, routeEarlyEvent and execute call this before exposing native state to
+     * Session. Return a new state with projected capabilities and the fallback revision offset so
+     * observers can distinguish synthetic support. Other state fields remain shared until redaction.
+     */
+    projectState(state) {
+        return { ...state, capabilities: this.projectCapabilities(state.capabilities), capabilityRevision: state.capabilityRevision + (this.lease || this.backend?.structuredOutputTool ? 1 : 0) };
+    }
+    /**
+     * emit queues acceptance here, prepareBridge and prepareOutput register callbacks that queue
+     * candidates here, and execute queues receipt binding. Run work after earlier queued work,
+     * returning its result/rejection while preserving the chain for later operations. Callers still own
+     * failure publication and cleanup.
+     */
+    enqueue(work) {
+        const operation = this.chain.then(work);
+        this.chain = operation.then(() => { }, () => { });
+        return operation;
+    }
+    /**
+     * nativeSink's emit, tryEmit and bindSubmission callbacks invoke this for native events.
+     * Reserve queue capacity and clone the envelope before serialized accept. Serialization, cloning
+     * and capacity failures throw synchronously. Processing failures await Session.fail before rejecting,
+     * and settlement releases queue counters. Adapters await the returned promise for publication order.
+     */
+    emit(event, scope = {}) {
+        const bytes = Buffer.byteLength(JSON.stringify(event));
+        if (bytes > (this.limits.queue?.maxFrameBytes ?? 8 * 1024 * 1024)
+            || this.queuedBytes + this.heldBytes + bytes > (this.limits.queue?.maxBytes ?? 16 * 1024 * 1024)
+            || this.queuedEvents + this.heldCount >= (this.limits.queue?.maxEvents ?? 2048))
+            throw new HarnessSdkError('BACKPRESSURE_EXCEEDED');
+        const copy = structuredClone({ event, scope });
+        this.queuedBytes += bytes;
+        this.queuedEvents++;
+        const operation = this.enqueue(() => this.accept(copy));
+        return operation.catch(async (cause) => {
+            await this.sink.fail(cause);
+            throw cause;
+        }).finally(() => {
+            this.queuedBytes -= bytes;
+            this.queuedEvents--;
+        });
+    }
+    /**
+     * routeEarlyEvent awaits this after publishing submission/bound, while execute queues it
+     * for a receipt containing turnId. Associate the output and replay held events in order before the
+     * caller advances. Conflicting/earlier-execution bindings throw PROTOCOL_ERROR. Replay failures
+     * reject to emit or execute, whose failure paths still own observation teardown and cleanup.
+     */
+    async bind(submissionId, turnId) {
+        this.unresolved.delete(submissionId);
+        const output = this.outputs.get(submissionId);
+        if (output && this.associateOutput(output, turnId) === 'already-ended')
+            return;
+        // Receipt-only backends can bind after emitting all their execution events.
+        const held = this.pending.get(turnId);
+        if (!held)
+            return;
+        this.pending.delete(turnId);
+        for (const envelope of held) {
+            this.heldCount--;
+            this.heldBytes -= Buffer.byteLength(JSON.stringify(envelope.event));
+            await this.accept(envelope);
+        }
+    }
+    /**
+     * bind uses this decision before replaying held events. A late binding from an input admitted
+     * before the terminal can share that ended execution and is reclaimed immediately. Binding a
+     * newer input to an ended execution or changing an existing binding throws PROTOCOL_ERROR.
+     * Record competing schemas on the first output so a native success reports the conflict.
+     */
+    associateOutput(output, turnId) {
+        if (output.turnId && output.turnId !== turnId)
+            throw new HarnessSdkError('PROTOCOL_ERROR', 'Conflicting structured output binding');
+        const endedAt = this.terminalVersions.get(turnId);
+        if (endedAt !== undefined) {
+            if (output.admittedVersion >= endedAt)
+                throw new HarnessSdkError('PROTOCOL_ERROR', 'Structured submission bound to an earlier execution');
+            this.drop(output.submissionId);
+            return 'already-ended';
+        }
+        output.turnId = turnId;
+        const previous = this.byTurn.get(turnId);
+        if (previous && !isDeepStrictEqual(previous.schema.schema, output.schema.schema))
+            previous.error = failure('STRUCTURED_OUTPUT_BINDING_CONFLICT');
+        else
+            this.byTurn.set(turnId, previous ?? output);
+        return 'associated';
+    }
+    /**
+     * The state getter, accept, routeEarlyEvent, publishOutput and execute project values
+     * here before exposing them to Session. Recursively replace output IDs and retained bridge secrets
+     * in string values, preserving object keys and leaving retained source data untouched. Session
+     * still owns projection of marked user secrets and any host history policy.
+     */
+    redact(value) {
+        /** Rebuild JSON-shaped values so bridge redaction leaves retained source data untouched. */
+        const visit = (node) => {
+            if (typeof node === 'string') {
+                let text = node.replace(/anureo_output_[a-f0-9]{48}/g, '[redacted]');
+                for (const secret of this.privateStrings)
+                    text = text.replaceAll(secret, '[redacted]');
+                return text;
+            }
+            if (Array.isArray(node))
+                return node.map(visit);
+            if (node && typeof node === 'object')
+                return Object.fromEntries(Object.entries(node).map(([key, child]) => [key, visit(child)]));
+            return node;
+        };
+        return visit(value);
+    }
+    /**
+     * rememberText, projectItemSnapshot, submitCandidate and admitOutput reserve or replace retained
+     * data here. Apply a signed byte delta to session/output accounting or throw RESULT_BUDGET_EXCEEDED
+     * before mutation. Callers commit the corresponding value only after this succeeds and drop/release
+     * later reclaim its accounting.
+     */
+    retain(output, bytes) {
+        if (this.outputBytes + bytes > (this.limits.maxResultBytes ?? 16 * 1024 * 1024))
+            throw new HarnessSdkError('RESULT_BUDGET_EXCEEDED');
+        this.outputBytes += bytes;
+        output.retainedBytes += bytes;
+    }
+    /**
+     * projectItemSnapshot and projectItemDelta store text here for outputValue's terminal assembly.
+     * Replace one item's text with signed byte accounting. Distinct-item or byte overflow throws
+     * RESULT_BUDGET_EXCEEDED before replacing text, propagating through accept to observation failure.
+     */
+    rememberText(output, id, text) {
+        if (!output.text.has(id) && output.text.size >= (this.limits.maxItems ?? 2048))
+            throw new HarnessSdkError('RESULT_BUDGET_EXCEEDED');
+        this.retain(output, Buffer.byteLength(text) - Buffer.byteLength(output.text.get(id) ?? ''));
+        output.text.set(id, text);
+    }
+    /**
+     * bind reclaims late terminal associations here, and completeTurn/reject reclaim finished or
+     * rejected submissions. Remove the submission and subtract its retained bytes. These callers still
+     * own turn associations, unresolved IDs and exclusive-lane release.
+     */
+    drop(submissionId) {
+        const output = this.outputs.get(submissionId);
+        if (output)
+            this.outputBytes -= output.retainedBytes;
+        this.outputs.delete(submissionId);
+    }
+    /**
+     * emit queues this work and bind replays held envelopes through it. Validate and route an envelope,
+     * then project its items and commit a terminal before publishing it to Session. A held or suppressed
+     * event resolves without publication. Protocol, budget, cleanup and sink failures reject the caller,
+     * while candidate-validation failures become failed terminals through publishOutput.
+     */
+    async accept({ event, scope }) {
+        if (this.disposed)
+            throw new HarnessSdkError('STREAM_CLOSED');
+        this.validateEnvelope(event, scope);
+        if (await this.routeEarlyEvent(event, scope))
+            return;
+        const turnId = this.eventTurnId(event, scope);
+        if (this.isLateTerminal(event, turnId)) {
+            await this.sink.emit(this.redact(event), scope);
+            return;
+        }
+        if (event.type === 'turn/started')
+            this.active.add(event.payload.turnId);
+        const output = turnId ? this.byTurn.get(turnId) : undefined;
+        if (this.holdForBinding(event, scope, turnId, output))
+            return;
+        const projected = output ? this.projectItemEvent(event, output) : event;
+        if (!projected)
+            return;
+        event = projected;
+        if (event.type === 'turn/completed')
+            event = await this.completeTurn(event, output, turnId);
+        await this.sink.emit(this.redact(event), scope);
+    }
+    /**
+     * accept calls this before routing or retaining an envelope. Assert its protocol shape using the
+     * current binding and validation-only stream metadata. Assertion failures reject acceptance before
+     * association state changes, including for envelopes that would otherwise be held.
+     */
+    validateEnvelope(event, scope) {
+        assertEvent({ ...scope, sessionId: this.binding.sessionId, streamId: 'output-validation', seq: 1, timestamp: new Date().toISOString(), ...event });
+    }
+    /**
+     * accept awaits this before execution projection. Publish binding before replaying held events,
+     * reclaim definite rejections, and publish projected session state. Return true only when publication
+     * is complete here. Binding, cleanup or sink failures reject accept. Rejected-status events continue
+     * through accept for their normal publication after reclamation.
+     */
+    async routeEarlyEvent(event, scope) {
+        if (event.type === 'submission/bound') {
+            await this.sink.emit(event, scope);
+            await this.bind(event.payload.submissionId, event.payload.turnId);
+            return true;
+        }
+        if (event.type === 'submission/status' && event.payload.status === 'rejected')
+            await this.reject(event.payload.submissionId);
+        if (event.type === 'session/state') {
+            await this.sink.emit(this.redact({ ...event, payload: this.projectState(event.payload) }), scope);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * accept uses this pure lookup for output association, buffering and terminal projection. Prefer
+     * scope.turnId, then lifecycle payload identity, returning undefined for unscoped non-lifecycle events.
+     */
+    eventTurnId(event, scope) {
+        return scope.turnId ?? (event.type === 'turn/started' || event.type === 'turn/completed' ? event.payload.turnId : undefined);
+    }
+    /**
+     * accept uses this predicate to forward lifecycle events for already-terminal turns directly to
+     * Session. Return whether the event bypasses output bookkeeping so duplicate starts/completions
+     * cannot reopen completed output state. Session still validates its own lifecycle observations.
+     */
+    isLateTerminal(event, turnId) {
+        return Boolean(turnId && this.terminalVersions.has(turnId) && (event.type === 'turn/started' || event.type === 'turn/completed'));
+    }
+    /**
+     * accept returns early when this retains an item/terminal envelope for a possible late binding.
+     * Reserve held counters and preserve per-turn order while any output is unbound. bind later replays
+     * these envelopes and releases counters. emit already checked combined queued/held capacity.
+     */
+    holdForBinding(event, scope, turnId, output) {
+        const needsBinding = !output && [...this.outputs.values()].some(value => !value.turnId);
+        if (turnId && needsBinding && (event.type.startsWith('item/') || event.type === 'turn/completed')) {
+            const held = this.pending.get(turnId) ?? [];
+            held.push({ event, scope });
+            this.pending.set(turnId, held);
+            this.heldCount++;
+            this.heldBytes += Buffer.byteLength(JSON.stringify(event));
+            return true;
+        }
+        return false;
+    }
+    /**
+     * accept routes output-associated events through this projection before publication. Retain
+     * snapshots/deltas under the output budget and return other events unchanged. undefined means
+     * a native final was withheld until terminal validation. Retention failures reject accept.
+     */
+    projectItemEvent(event, output) {
+        if (event.type === 'item/started' || event.type === 'item/completed')
+            return this.projectItemSnapshot(event, output);
+        if (event.type === 'item/delta')
+            return this.projectItemDelta(event, output);
+        return event;
+    }
+    /**
+     * projectItemEvent retains message snapshots and downgrades visible messages to commentary.
+     * Withhold completed native finals until terminal validation so accepted output can preserve the
+     * identity used by authoritative history. Budget failures throw before publication to accept.
+     */
+    projectItemSnapshot(event, output) {
+        const item = event.payload.item;
+        if (item.type !== 'agentMessage')
+            return event;
+        this.rememberText(output, item.id, item.text);
+        if (item.phase === 'final')
+            output.finalIds.add(item.id);
+        if (output.mode === 'native' && event.type === 'item/completed' && item.phase === 'final') {
+            const previous = output.finalItems.get(item.id);
+            this.retain(output, Buffer.byteLength(JSON.stringify(item)) - (previous ? Buffer.byteLength(JSON.stringify(previous)) : 0));
+            output.finalItems.set(item.id, item);
+            return undefined;
+        }
+        return { ...event, payload: { item: { ...item, phase: 'commentary' } } };
+    }
+    /**
+     * projectItemEvent assembles streamed text and agent-message patches here for terminal parsing.
+     * Preserve final identities but expose patches as commentary until commitment. Budget failures
+     * throw through accept; unrelated deltas pass through unchanged.
+     */
+    projectItemDelta(event, output) {
+        if (event.payload.kind === 'text' && event.payload.text !== undefined) {
+            const text = (output.text.get(event.payload.itemId) ?? '') + event.payload.text;
+            if (Buffer.byteLength(text) > (this.limits.maxResultBytes ?? 16 * 1024 * 1024))
+                throw new HarnessSdkError('RESULT_BUDGET_EXCEEDED');
+            this.rememberText(output, event.payload.itemId, text);
+        }
+        const value = event.payload.value;
+        if (event.payload.kind === 'patch' && value && typeof value === 'object' && !Array.isArray(value) && value.type === 'agentMessage') {
+            this.rememberText(output, event.payload.itemId, String(value.text ?? ''));
+            if (value.phase === 'final')
+                output.finalIds.add(event.payload.itemId);
+            return { ...event, payload: { ...event.payload, value: { ...value, phase: 'commentary' } } };
+        }
+        return event;
+    }
+    /**
+     * accept awaits this for a real turn/completed event and then publishes the returned terminal.
+     * Close candidate admission, disable the direct tool, publish accepted output or withheld commentary,
+     * then reclaim associations and release the fallback lane. Validation can replace success with a
+     * failed terminal. Tool/sink failures reject before remaining cleanup, leaving disposal to reclaim
+     * resources. Host result timeouts never enter this terminal path.
+     */
+    async completeTurn(event, output, turnId) {
+        if (output) {
+            output.finished = true;
+            if (output.mode === 'tool')
+                await this.backend.structuredOutputTool.configure();
+        }
+        if (output && event.payload.status === 'completed')
+            event = await this.publishOutput(event, output, turnId);
+        if (output && event.payload.status !== 'completed')
+            await this.publishCommentaryFinals(output, turnId);
+        this.recordTerminal({ terminalTurnId: event.payload.turnId, associatedTurnId: turnId, output });
+        return event;
+    }
+    /**
+     * completeTurn records the native terminal after tool cleanup and item publication succeed.
+     * Bound the terminal markers used by late binding and reclaim the associated submissions and lane.
+     * Use the payload ID for active, terminal and turn-index records. Match retained candidates and
+     * the lane using the envelope's resolved association ID.
+     */
+    recordTerminal({ terminalTurnId, associatedTurnId, output }) {
+        this.active.delete(terminalTurnId);
+        this.terminalVersions.set(terminalTurnId, ++this.terminalVersion);
+        if (this.terminalVersions.size > (this.limits.maxSubmissions ?? 1024)) {
+            const oldest = this.terminalVersions.keys().next();
+            if (!oldest.done)
+                this.terminalVersions.delete(oldest.value);
+        }
+        if (!output)
+            return;
+        for (const [id, value] of this.outputs)
+            if (value.turnId === associatedTurnId)
+                this.drop(id);
+        this.byTurn.delete(terminalTurnId);
+        if (this.locked?.turnId === associatedTurnId)
+            this.locked = undefined;
+    }
+    /**
+     * completeTurn awaits this only for native success with output state. Convert validation failures
+     * into a failed terminal, or publish commentary followed by one accepted final before returning
+     * success. Reuse the sole completed native final's identity when available. Sink publication failures
+     * reject completeTurn directly, preserving their infrastructure-failure semantics.
+     */
+    async publishOutput(event, output, turnId) {
+        let text;
+        try {
+            if (output.error)
+                throw new HarnessSdkError(output.error.code);
+            const value = this.outputValue(output);
+            output.schema.check(value);
+            const json = JSON.stringify(value);
+            text = this.sink.projectOutput?.(this.redact(json)) ?? this.redact(json);
+            try {
+                output.schema.parse(text);
+            }
+            catch {
+                throw new HarnessSdkError('STRUCTURED_OUTPUT_REDACTED');
+            }
+        }
+        catch (cause) {
+            const error = sdkError(cause, 'STRUCTURED_OUTPUT_INVALID');
+            return { ...event, payload: { ...event.payload, status: 'failed', error: failure(error.code, error.details) } };
+        }
+        if (text !== undefined) {
+            const original = output.mode === 'native' && output.finalItems.size === 1 ? [...output.finalItems.values()][0] : undefined;
+            // Skip an await when there is no commentary to publish before the final.
+            for (const item of output.finalItems.values()) {
+                if (item.id !== original?.id)
+                    await this.emitCommentaryFinal(item, turnId);
+            }
+            const item = { ...(original ?? { id: `anureo-result:${randomBytes(24).toString('hex')}`, type: 'agentMessage' }), phase: 'final', text, status: 'completed' };
+            await this.sink.emit({ type: 'item/completed', payload: { item } }, { turnId });
+        }
+        return event;
+    }
+    /**
+     * publishOutput obtains its candidate here before final schema/privacy checks. Parse the
+     * joined native final texts, or return the first retained tool/MCP value. Missing values throw
+     * STRUCTURED_OUTPUT_MISSING or STRUCTURED_OUTPUT_INVALID according to prior schema attempts.
+     */
+    outputValue(output) {
+        if (output.mode === 'native')
+            return output.schema.parse([...output.finalIds].map(id => output.text.get(id) ?? '').join('\n'));
+        if (output.hasValue)
+            return output.value;
+        throw new HarnessSdkError(output.attempts ? 'STRUCTURED_OUTPUT_INVALID' : 'STRUCTURED_OUTPUT_MISSING');
+    }
+    /**
+     * completeTurn awaits this for non-success terminals, including failures from final validation.
+     * Emit retained native items as commentary in insertion order. Publication failures reject before
+     * completeTurn records the terminal and reclaims its associations.
+     */
+    async publishCommentaryFinals(output, turnId) {
+        for (const item of output.finalItems.values())
+            await this.emitCommentaryFinal(item, turnId);
+    }
+    /**
+     * publishOutput and publishCommentaryFinals await Session.emit directly. Preserve the native
+     * item identity while emitting commentary, and let publication failure halt the terminal path.
+     */
+    emitCommentaryFinal(item, turnId) {
+        return this.sink.emit({ type: 'item/completed', payload: { item: { ...item, phase: 'commentary' } } }, { turnId });
+    }
+    /**
+     * prepareBridge registers a queued handler with OutputBridgeManager.create. The manager's MCP
+     * CallTool handler awaits this result. Check the active MCP output, envelope and exact outputId
+     * before submitCandidate, returning an MCP acceptance or safe retry guidance. Envelope/ID failures
+     * consume no schema attempts. Infrastructure failures reject the registered MCP handler.
+     */
+    submitValue(args) {
+        const output = this.locked;
+        if (this.disposed || !output || output.mode !== 'mcp' || output.finished)
+            return toolError('STRUCTURED_OUTPUT_EXPIRED');
+        const invalidArguments = () => toolError('STRUCTURED_OUTPUT_INVALID_ARGUMENTS', undefined, 'Pass exactly two top-level arguments: outputId (a nonempty string copied exactly from the current task output contract) and value (the final JSON result). Do not nest the argument envelope inside value. Correct the arguments and call this tool again within this execution.');
+        if (!args || typeof args !== 'object' || Array.isArray(args))
+            return invalidArguments();
+        const value = args;
+        if (typeof value.outputId !== 'string' || !value.outputId || !Object.hasOwn(value, 'value') || Object.keys(value).some(key => key !== 'outputId' && key !== 'value'))
+            return invalidArguments();
+        if (output.outputId !== value.outputId)
+            return toolError('STRUCTURED_OUTPUT_ID_MISMATCH', undefined, 'The supplied outputId does not match the current task. This does not mean the task has expired. Copy outputId exactly from the current task output contract, preserving every character, and call this tool again within this execution. Do not reuse an ID from another task.');
+        const result = this.submitCandidate(output, value.value);
+        return result.accepted ? { content: [{ type: 'text', text: '{"accepted":true}' }] } : toolError(result.error.code, result.error.details?.issues);
+    }
+    /**
+     * submitValue formats this decision for MCP. prepareOutput supplies the native tool port with a
+     * queued callback capturing the exact Output. Pi's createOutputTool awaits it and translates
+     * acceptance into a termination request or returns an error for correction. A structurally equal
+     * retry is accepted without storing a second value. The third schema mismatch before acceptance
+     * exhausts retries. Return policy failures as decisions, while clone failure rejects the callback.
+     * Acceptance remains provisional until publishOutput revalidates the projected result.
+     */
+    submitCandidate(output, value) {
+        const rejected = (code, details) => ({ accepted: false, error: failure(code, details) });
+        if (this.disposed || output.finished || this.locked !== output)
+            return rejected('STRUCTURED_OUTPUT_EXPIRED');
+        if (output.error)
+            return { accepted: false, error: output.error };
+        if (output.hasValue)
+            return isDeepStrictEqual(output.value, value) ? { accepted: true } : rejected('STRUCTURED_OUTPUT_ALREADY_SUBMITTED');
+        let bytes;
+        try {
+            bytes = Buffer.byteLength(JSON.stringify(value));
+        }
+        catch {
+            return rejected('STRUCTURED_OUTPUT_INVALID');
+        }
+        if (bytes > (this.limits.maxResultBytes ?? 16 * 1024 * 1024))
+            return this.rejectCandidateBudget(output);
+        try {
+            output.schema.check(value);
+        }
+        catch (cause) {
+            if (++output.attempts >= 3)
+                output.error = failure('STRUCTURED_OUTPUT_RETRIES_EXCEEDED');
+            return rejected(output.error?.code ?? 'STRUCTURED_OUTPUT_INVALID', sdkError(cause).details);
+        }
+        try {
+            this.retain(output, bytes);
+        }
+        catch {
+            return this.rejectCandidateBudget(output);
+        }
+        output.value = structuredClone(value);
+        output.hasValue = true;
+        return { accepted: true };
+    }
+    /** submitCandidate reports either byte-budget failure immediately and retains it for later calls and terminal validation. */
+    rejectCandidateBudget(output) {
+        output.error = failure('RESULT_BUDGET_EXCEEDED');
+        return { accepted: false, error: output.error };
+    }
+    /**
+     * routeEarlyEvent calls this for rejected status, and rejectDispatch calls after a definite request
+     * failure. Remove unresolved admission, then finish/reclaim an unbound output and release its lane.
+     * Bound execution remains owned until its terminal. Tool-disable failures reject before reclamation,
+     * allowing the caller to report cleanup failure and later disposal to attempt release.
+     */
+    async reject(submissionId) {
+        this.unresolved.delete(submissionId);
+        const output = this.outputs.get(submissionId);
+        if (output?.turnId)
+            return; // A rejection cannot undo an execution already observed.
+        if (output)
+            output.finished = true;
+        if (output?.mode === 'tool')
+            await this.backend.structuredOutputTool.configure();
+        this.drop(submissionId);
+        if (this.locked === output)
+            this.locked = undefined;
+    }
+    /**
+     * execute awaits this after checking backend attachment and before native frame/capability checks.
+     * Transform schema-bearing input and record the captured input/review ID as unresolved only
+     * after preparation succeeds. Return params for native validation and dispatch. Setup
+     * failures reject execute, which still knows the original submission ID for definite-failure cleanup.
+     */
+    async prepareSubmission(method, params, submissionId) {
+        if (method === 'input/submit') {
+            const input = params;
+            if (input.outputSchema !== undefined)
+                params = await this.prepareOutput(input, input.outputSchema);
+        }
+        if (submissionId !== undefined)
+            this.unresolved.add(submissionId);
+        return params;
+    }
+    /**
+     * prepareSubmission awaits this for schema-bearing input using the attached backend. Compile the
+     * schema, enforce mode-specific admission and reserve retention, then return native params or
+     * configure the locked fallback before returning transformed input. The native tool callback is registered here
+     * and captures this exact Output. Capacity, schema, exclusivity and registration failures reject to
+     * execute's recovery path, which reclaims definite failures. Dispatch and result observation remain
+     * with execute and Session.
+     */
+    async prepareOutput(input, schemaSource) {
+        if (this.outputs.size >= (this.limits.maxSubmissions ?? 1024))
+            throw new HarnessSdkError('BACKPRESSURE_EXCEEDED');
+        const schema = compileOutputSchema(schemaSource);
+        const output = this.admitOutput(input.submissionId, schema);
+        if (output.mode === 'native')
+            return input;
+        this.locked = output;
+        const prepared = fallbackInput(input, output);
+        if (output.mode === 'tool')
+            await this.backend.structuredOutputTool.configure({
+                name: 'anureo_submit_result',
+                description: 'Submit the final result for the current task. Correct validation errors and retry. Acceptance ends this execution.',
+                schema: structuredClone(schema.schema),
+                execute: value => this.enqueue(async () => this.submitCandidate(output, value)),
+            });
+        return prepared;
+    }
+    /**
+     * prepareOutput calls this after capacity checking and schema compilation, before fallback setup.
+     * Prefer native schemas, then a direct tool, then MCP; reject unavailable or conflicting lanes
+     * before reserving schema bytes and storing the submission. execute has established backend
+     * attachment. Its definite-failure path owns reclaiming state if later setup or dispatch rejects.
+     */
+    admitOutput(submissionId, schema) {
+        const backend = this.backend;
+        const mode = backend.capabilities.turn?.outputSchema ? 'native' : backend.structuredOutputTool ? 'tool' : 'mcp';
+        if (mode === 'mcp' && !this.lease)
+            throw new HarnessSdkError('CAPABILITY_UNSUPPORTED');
+        if (mode !== 'native' && (this.active.size || this.unresolved.size))
+            throw new HarnessSdkError('STRUCTURED_OUTPUT_BUSY');
+        if (mode === 'native' && [...this.outputs.values()].some(output => !isDeepStrictEqual(output.schema.schema, schema.schema)))
+            throw new HarnessSdkError('SESSION_BUSY');
+        const output = {
+            submissionId,
+            outputId: `anureo_output_${randomBytes(24).toString('hex')}`,
+            mode,
+            schema,
+            attempts: 0,
+            hasValue: false,
+            text: new Map(),
+            finalIds: new Set(),
+            finalItems: new Map(),
+            retainedBytes: 0,
+            admittedVersion: this.terminalVersion,
+        };
+        this.retain(output, Buffer.byteLength(JSON.stringify(schema.schema)));
+        this.outputs.set(submissionId, output);
+        return output;
+    }
+    /**
+     * execute awaits this after a native close receipt and dispose awaits it before backend
+     * disposal. Clear retention, associations and held-event accounting, detach the lease, then attempt
+     * lease disposal and native tool disabling together. Clear the lane before invoking either so
+     * queued candidates expire at receipt time. Classify promise rejections after both settle.
+     * Session still owns observation closure, and OutputSession.dispose owns backend release.
+     */
+    async release() {
+        this.outputs.clear();
+        this.byTurn.clear();
+        this.pending.clear();
+        this.unresolved.clear();
+        this.active.clear();
+        this.locked = undefined;
+        this.terminalVersions.clear();
+        this.outputBytes = 0;
+        this.heldBytes = 0;
+        this.heldCount = 0;
+        const lease = this.lease;
+        this.lease = undefined;
+        checkRelease(await Promise.allSettled([lease?.dispose(), this.backend?.structuredOutputTool?.configure()]));
+    }
+}
+/**
+ * projectCapabilities adds this extension for Session attachment and projected state when an MCP
+ * lease supplies fallback support. The native schema capability takes precedence over this marker.
+ */
+const EXTENSION = { name: 'x-anureo/structured-output-mcp', version: '1' };
+/**
+ * execute captures input/review identity once for unresolved admission, receipt binding and
+ * definite-failure cleanup. Other methods have no submission tracked by the output wrapper.
+ */
+function requestSubmissionId(method, params) {
+    if (method === 'input/submit' || method === 'review/start')
+        return params.submissionId;
+    return undefined;
+}
+/**
+ * prepareOutput strips the unsupported native schema field and appends the selected fallback
+ * contract before dispatch. Preserve the original blocks and opaque output identity; the caller
+ * owns tool registration, locking and cleanup. Only fallback modes are passed here.
+ */
+function fallbackInput(input, output) {
+    const { outputSchema: _, ...native } = input;
+    const contract = output.mode === 'tool' ? [
+        'After completing the task, you MUST call anureo_submit_result with your final result matching its parameter schema.',
+        'Correct any validation errors and call it again within this execution. A text answer does not complete the task.',
+    ].join('\n') : [
+        'Required Anureo final-output protocol:',
+        `After completing the task, you MUST invoke the ${OUTPUT_SERVER_NAME} MCP submit_result tool. Its exposed name may have an editor/server prefix and ends with submit_result.`,
+        'Pass the outputId below and your final JSON value as the value argument. A plain text or JSON answer does not complete this task.',
+        'Copy outputId exactly, preserving every character. Pass outputId and value as separate top-level arguments; do not put outputId inside value.',
+        'If the tool reports validation errors, correct the value and call it again within this execution. Once it acknowledges accepted:true, end the task.',
+        'Do not substitute files or shell commands for submitting through this tool.',
+        `outputId: ${output.outputId}`,
+        `JSON Schema: ${JSON.stringify(output.schema.schema)}`,
+    ].join('\n');
+    return { ...native, input: [...input.input, { type: 'text', text: contract }] };
+}