@anureo/sdk 0.0.0-stage → 0.3.0

package/src/structured-output/session.d.ts

@@ -0,0 +1,329 @@
+import { type AhpRequestMap, type AhpResultMap, type Capabilities, type SessionOpenParams, type SessionState } from '@anureo/protocol';
+import type { BackendSession, HarnessAdapter, SessionEventSink, SessionMethod } from "../ports.js";
+import type { OutputBridgeManager } from "./bridge.js";
+import type { OutputLimits } from "./limits.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 declare class OutputSession implements BackendSession {
+    /**
+     * 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: {
+        params: SessionOpenParams;
+        sink: SessionEventSink;
+        manager: OutputBridgeManager;
+        limits: OutputLimits;
+        forget: () => void;
+    });
+    /** Session.attach reads the native binding after open. validateEnvelope uses the requested identity until the native backend is available. */
+    get binding(): import("@anureo/protocol").SessionBinding;
+    /** Session.attach adopts this capability projection. The native tool or MCP lease can supply schema support without mutating backend capabilities. */
+    get capabilities(): Capabilities;
+    /** Session.attach restores this optional projected native state. Return a credential-redacted snapshot with the fallback capability revision applied. */
+    get state(): SessionState | 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.
+     */
+    open({ adapter, nativeOutput }: {
+        adapter: HarnessAdapter;
+        nativeOutput: boolean;
+    }): Promise<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.
+     */
+    execute<M extends SessionMethod>(method: M, original: AhpRequestMap[M]): Promise<AhpResultMap[M]>;
+    /**
+     * 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(): Promise<void>;
+    private backend?;
+    private lease?;
+    private disposed;
+    private disposal?;
+    private chain;
+    private queuedBytes;
+    private queuedEvents;
+    private heldBytes;
+    private heldCount;
+    private outputBytes;
+    private readonly pending;
+    private readonly outputs;
+    private readonly byTurn;
+    private readonly unresolved;
+    private readonly active;
+    private readonly terminalVersions;
+    private terminalVersion;
+    private locked?;
+    private readonly privateStrings;
+    private readonly params;
+    private readonly sink;
+    private readonly manager;
+    private readonly limits;
+    private readonly 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.
+     */
+    private dispatch;
+    /**
+     * 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.
+     */
+    private prepareBridge;
+    /**
+     * 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.
+     */
+    private nativeSink;
+    /**
+     * 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.
+     */
+    private rejectDispatch;
+    /**
+     * 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.
+     */
+    private projectCapabilities;
+    /**
+     * 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.
+     */
+    private projectState;
+    /**
+     * 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.
+     */
+    private enqueue;
+    /**
+     * 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.
+     */
+    private emit;
+    /**
+     * 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.
+     */
+    private bind;
+    /**
+     * 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.
+     */
+    private associateOutput;
+    /**
+     * 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.
+     */
+    private redact;
+    /**
+     * 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.
+     */
+    private retain;
+    /**
+     * 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.
+     */
+    private rememberText;
+    /**
+     * 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.
+     */
+    private drop;
+    /**
+     * 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.
+     */
+    private accept;
+    /**
+     * 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.
+     */
+    private validateEnvelope;
+    /**
+     * 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.
+     */
+    private routeEarlyEvent;
+    /**
+     * 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.
+     */
+    private eventTurnId;
+    /**
+     * 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.
+     */
+    private isLateTerminal;
+    /**
+     * 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.
+     */
+    private holdForBinding;
+    /**
+     * 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.
+     */
+    private projectItemEvent;
+    /**
+     * 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.
+     */
+    private projectItemSnapshot;
+    /**
+     * 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.
+     */
+    private projectItemDelta;
+    /**
+     * 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.
+     */
+    private completeTurn;
+    /**
+     * 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.
+     */
+    private recordTerminal;
+    /**
+     * 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.
+     */
+    private publishOutput;
+    /**
+     * 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.
+     */
+    private outputValue;
+    /**
+     * 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.
+     */
+    private publishCommentaryFinals;
+    /**
+     * publishOutput and publishCommentaryFinals await Session.emit directly. Preserve the native
+     * item identity while emitting commentary, and let publication failure halt the terminal path.
+     */
+    private emitCommentaryFinal;
+    /**
+     * 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.
+     */
+    private submitValue;
+    /**
+     * 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.
+     */
+    private submitCandidate;
+    /** submitCandidate reports either byte-budget failure immediately and retains it for later calls and terminal validation. */
+    private rejectCandidateBudget;
+    /**
+     * 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.
+     */
+    private reject;
+    /**
+     * 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.
+     */
+    private prepareSubmission;
+    /**
+     * 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.
+     */
+    private prepareOutput;
+    /**
+     * 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.
+     */
+    private admitOutput;
+    /**
+     * 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.
+     */
+    private release;
+}