@anureo/sdk 0.2.0 → 0.3.0

package/src/session.d.ts

@@ -0,0 +1,459 @@
+import { type AhpEvent, type AhpEventPayload, type AhpRequestMap, type AhpResultMap, type Capabilities, type InteractionRequested, type InteractionResponse, type SessionBinding, type SessionOpenParams, type SessionState } from '@anureo/protocol';
+import type { ClientOptions, SubmitOptions } from "./client-options.js";
+import type { BackendSession, EventScope, NativeInteractionResponder, SessionEventSink, SessionMethod } from "./ports.js";
+import { Turn } from "./turn.js";
+import type { EventSubscriptionOptions, RequestOptions } from "./types.js";
+/**
+ * Submit input, dispatch requests and observe events for a session opened through Client.
+ * Await close to request native close and release resources, or dispose to release observation
+ * and backend resources with native stop unconfirmed. Client.dispose also releases its sessions.
+ */
+export declare class Session implements SessionEventSink {
+    private readonly params;
+    private readonly options;
+    private readonly createId;
+    /**
+     * Client.open constructs this sink before starting native open so callbacks and teardown can race
+     * attachment safely. Clone initial state, allocate stream identity and install privacy/interaction
+     * hooks without acquiring a backend. ID generation or cloning can throw; Client owns later disposal.
+     */
+    constructor(params: SessionOpenParams, options: ClientOptions, capabilities: Capabilities, createId: () => string);
+    /**
+     * Read the stable session ID used in request and event envelopes.
+     */
+    get id(): string;
+    /**
+     * Read a detached, frozen copy of the current binding. Its native reference may change after
+     * a revert or a native state update. Cloning failures throw synchronously.
+     */
+    get binding(): Readonly<SessionBinding>;
+    /**
+     * Capture the current binding and the original working directory for Client.sessions.resume or
+     * Client.sessions.fork. Cloning failures throw synchronously.
+     */
+    get reference(): Readonly<{
+        binding: SessionBinding;
+        cwd: string;
+    }>;
+    /**
+     * Read a detached, frozen copy of the session's current capabilities before choosing an operation.
+     * Cloning failures throw synchronously.
+     */
+    get capabilities(): Readonly<Capabilities>;
+    /**
+     * Read a frozen, privacy-filtered copy of the currently admitted state without waiting for
+     * the event queue. Projection or cloning failures throw synchronously.
+     */
+    get snapshot(): Readonly<SessionState>;
+    /**
+     * OutputSession.publishOutput invokes this optional sink hook before revalidating final JSON.
+     * Return marked-secret projection without mutating the candidate; OutputSession owns schema failure
+     * handling and final publication.
+     */
+    projectOutput(text: string): string;
+    /**
+     * Attach the backend, restore active observations and publish initial state. Client.attachSession
+     * awaits this before returning a session to the host. Dispose a mismatched or already-closed
+     * attachment before rejecting. Adoption or publication failure rejects to Client.open, which
+     * owns session cleanup.
+     */
+    attach(backend: BackendSession): Promise<void>;
+    /**
+     * Subscribe to future session events without replay; subscribe before submitting to observe its
+     * lifecycle from admission. Each subscription is isolated and bounded; invalid limits throw and later
+     * failures reject reads. Consumers must exhaust, return or abort the iterator to release it. Detaching
+     * or overflowing this observer does not stop native execution or affect sibling subscriptions.
+     */
+    events(options?: EventSubscriptionOptions): AsyncIterable<AhpEvent>;
+    /**
+     * Client.attachSession supplies this sink to OutputSession, whose event forwarding calls it;
+     * Session.bindSubmission, outcome bookkeeping and interaction hooks also await the same ordered path.
+     * Clone and enqueue a payload. Resolve once the ordered queue processes it, even when a duplicate
+     * is suppressed or observation has since closed. Reject closed admission, serialization, cloning,
+     * capacity or processing failures. Overflow and processing failures also end observation.
+     */
+    emit(payload: AhpEventPayload, scope?: EventScope): Promise<void>;
+    /**
+     * A direct adapter sink consumer unable to await publication can use this admission probe. Return
+     * false on closure, serialization or capacity failure and invoke fail; true means the immediate
+     * checks passed, with emit rejection observed asynchronously. It does not promise successful
+     * publication. OutputSession.open supplies its own native-adapter tryEmit forwarding callback.
+     */
+    tryEmit(payload: AhpEventPayload, scope?: EventScope): boolean;
+    /**
+     * Native sink consumers may report association here; onRequestSucceeded awaits it when a receipt
+     * contains turnId. Queue submission/bound through emit so event admission orders association against
+     * native completion. Publication failures reject; successful association can release submit's Turn
+     * before a separate native receipt settles. Wrapped adapters reach the same event path via OutputSession.
+     */
+    bindSubmission(submissionId: string, turnId: string): Promise<void>;
+    /**
+     * Submit text or protocol blocks. Delivery defaults to native, so the adapter may queue the input
+     * or join an existing execution. Resolve a Turn as soon as the input is bound to an execution,
+     * independently of receipt or terminal timing. Normalization, admission, dispatch and wait failures
+     * can reject before association. Use Turn.result for the terminal outcome and dispose the handle
+     * when finished observing. Abort or timeout leaves admitted work running.
+     */
+    submit(options: SubmitOptions, wait?: RequestOptions): Promise<Turn>;
+    /**
+     * Hosts start a native review through submitExecution's association lifecycle. Resolve a Turn on
+     * binding or reject admission/dispatch/wait failure; caller cancellation leaves admitted work alive.
+     * ID generation or option cloning can throw synchronously. The returned observer follows the same
+     * disposal and native-control rules as submit.
+     */
+    review(options: {
+        target: AhpRequestMap['review/start']['target'];
+    }, wait?: RequestOptions): Promise<Turn>;
+    /**
+     * Request interruption for the whole session. Set cancelQueued only if advertised by the session.
+     * Resolve the native receipt or reject on capability, dispatch or wait failure. Caller cancellation
+     * affects waiting only. Use Turn.result for a terminal execution outcome.
+     * Request ID generation can throw synchronously before request is called.
+     */
+    interrupt(options?: {
+        cancelQueued?: boolean;
+    }, wait?: RequestOptions): Promise<AhpResultMap['session/interrupt']>;
+    /**
+     * Dispatch a typed session request and await its receipt. Matching method/request IDs replay the
+     * cached outcome while retained; changed params or a submission reserved by another request reject
+     * with a conflict. session/close instead shares its existing close work regardless of request ID.
+     * Hosts and context's Turn control callbacks use this entry. Ordinary calls validate
+     * wait options before dispatch and return a caller-scoped receipt wait; session/close validates the
+     * request first and uses closeRequest's shared teardown. Validation, dispatch and wait failures reject;
+     * admitted native work, bookkeeping and cleanup survive cancellation without automatic retries.
+     */
+    request<M extends SessionMethod>(method: M, params: AhpRequestMap[M], wait?: RequestOptions): Promise<AhpResultMap[M]>;
+    /**
+     * Settle a native interaction through a configured handler or manual interaction/respond request.
+     * OutputSession.open forwards the adapter's request/responder here. An own key in
+     * ClientOptions.interactions enables the kind; undefined selects manual handling and omission rejects
+     * it. Notify native rejection for closed/unsupported/handler-capacity cases, otherwise register
+     * settlement and publish interaction/requested before scheduling a configured host handler. Return
+     * the registry's response after native settlement/publication, or reject its failure. The host handler
+     * owns its work; Session aborts its signal on settlement/teardown without cancelling that work.
+     */
+    requestInteraction(request: InteractionRequested, responder: NativeInteractionResponder): Promise<InteractionResponse>;
+    /**
+     * OutputSession.open forwards native settlement reports here; direct adapters can use the sink too.
+     * Return InteractionRegistry.resolveExternally's publication promise without invoking the responder.
+     * The original interaction wait rejects even for responded because native supplied no response value;
+     * unknown/already-resolved IDs are ignored by the registry.
+     */
+    resolveInteraction(result: AhpResultMap['interaction/respond']): Promise<void>;
+    /**
+     * OutputSession forwards adapter observation loss here; emit, tryEmit, rejectNativeResult and cached
+     * bookkeeping also invoke it. Idempotently end observation with a safe unknown-outcome SDK error,
+     * await interaction cancellation, then attempt backend release while suppressing release-promise
+     * rejection. A synchronous disposal throw rejects this call. Native execution stop stays unconfirmed;
+     * the first caller can await cleanup without initiating a native interrupt; later calls return early.
+     */
+    fail(cause: unknown): Promise<void>;
+    /**
+     * Request native close and await interaction and backend cleanup. Concurrent close calls share the
+     * work. A session whose observation already ended awaits backend release and returns its stored
+     * receipt or an unconfirmed-stop receipt. Cleanup failure can reject after native close succeeds.
+     * Abort or timeout rejects only this caller's wait.
+     * Request ID generation can throw synchronously before closeRequest is called.
+     */
+    close(wait?: RequestOptions): Promise<AhpResultMap['session/close']>;
+    /**
+     * Client.open awaits this on setup/wait failure and Client.dispose awaits it before adapter release;
+     * host session consumers may also call it directly. Share teardown and its rejection: end observation,
+     * abort handler signals, await interaction cancellation, then release the backend. Native close is
+     * caller-owned and execution stop remains unconfirmed; repeated disposal never repeats owned work.
+     */
+    dispose(): Promise<void>;
+    private backend?;
+    private observationFailure?;
+    private closed;
+    private recovering;
+    private closing?;
+    private closeReceipt?;
+    private disposal?;
+    private backendDisposal?;
+    private readonly ended;
+    private seq;
+    private readonly streamId;
+    private source;
+    private backlog;
+    private pendingBytes;
+    private totalBytes;
+    private readonly hub;
+    private readonly executions;
+    private readonly submissions;
+    private readonly requests;
+    private readonly interactions;
+    private readonly handlers;
+    private handlerCount;
+    private readonly secrets;
+    private state;
+    /**
+     * attach and admitEvent call before recomputing status. Replace native state with a detached clone,
+     * preserving earlier metadata patches omitted by the snapshot. Clone failure propagates to attachment
+     * or ordered publication; callers still own binding validation and active-execution bookkeeping.
+     */
+    private adoptState;
+    /**
+     * Recompute the status and active IDs exposed by snapshot and state events after lifecycle changes.
+     * Closure, closing and recovery take precedence over execution activity.
+     */
+    private updateStatus;
+    /**
+     * attach restores active observations here; admitEvent and bindRecord reuse the same execution
+     * registry for live events and late associations. Return an existing context or allocate bounded
+     * completion/events/results and explicit Turn controls. Reclaim only an eligible terminal snapshot;
+     * throw BACKPRESSURE_EXCEEDED if capacity stays pinned. Invalid budgets throw before insertion.
+     * Turn owns each observer's cancellation.
+     */
+    private context;
+    /**
+     * context calls under execution-count pressure. Remove at most the oldest eligible terminal
+     * execution, subtract its retained bytes and remove its acknowledged submissions. Older unbound
+     * inputs pin possible late results; returning without eviction makes context reject capacity instead
+     * of silently losing a future association. Existing Turn handles keep their shared context.
+     */
+    private reclaimExecution;
+    /** emit and tryEmit share the configured count budget, which defaults to 2048 queued events. */
+    private maxQueuedEvents;
+    /**
+     * emit and tryEmit use this shared rule before reserving bytes. Report a frame/pending-byte budget
+     * overflow without changing accounting; callers decide whether to reject or return false and fail
+     * observation.
+     */
+    private eventExceedsByteCapacity;
+    /**
+     * emit schedules this synchronous phase on source and observes throws through fail. Validate before
+     * admitting state changes, then project private content, retain execution results and publish the
+     * public event. Ignore duplicate lifecycle events; settle terminal results before ending their stream.
+     * Queued work arriving after observation closes is ignored.
+     */
+    private publish;
+    /**
+     * publish calls before any lifecycle mutation. Validate envelope/payload identity and extension
+     * support, returning the optional execution ID used for admission and retention. Shape, identity or
+     * capability errors throw into emit's failure chain without reserving execution/submission state.
+     */
+    private validateEvent;
+    /**
+     * publish calls after validateEvent and consumes the returned payload/context for privacy projection
+     * and retention. Route submission and session changes separately from execution admission; ignored
+     * duplicates return undefined. Unknown/conflicting identity or invalid lifecycle transitions throw
+     * into emit's observation-failure chain. This phase neither publishes nor settles terminal results.
+     */
+    private admitEvent;
+    /**
+     * admitEvent routes submission/status here before publish can expose it. Reject an unresolved
+     * association for rejected/unknown status, retaining unknown outcomes for late binding, then return
+     * projected diagnostics. Unknown IDs or projection failures throw into emit's observation-failure
+     * chain; acknowledgement remains owned by dispatch bookkeeping.
+     */
+    private admitSubmissionStatus;
+    /**
+     * admitSubmissionStatus calls after any association rejection. Return status/identity unchanged
+     * while projecting receipt and error content so private native diagnostics cannot reach observers.
+     * Projection errors propagate through admission to emit; public event publication remains with publish.
+     */
+    private projectSubmissionStatus;
+    /**
+     * admitEvent calls with the context for a validated execution event. Enforce native turn/item order,
+     * mutating execution-local markers only for admitted transitions. Return false to suppress duplicate
+     * turn starts/completions or item completions; throw for invalid transitions. retainEvent owns terminal
+     * settlement after privacy projection, so this phase does not finish the execution.
+     */
+    private admitExecutionEvent;
+    /**
+     * admitExecutionEvent delegates item transitions here after payload validation. Require an active
+     * execution and reject repeated starts or deltas without a live item. Completion snapshots may
+     * introduce an item without a start; suppress repeated completions without changing its markers.
+     */
+    private admitItemEvent;
+    /**
+     * publish passes an admitted public event here before session-wide fanout. Accumulate bounded result
+     * content and update shared byte accounting; accumulator/budget errors throw into emit's failure chain.
+     * For native completion, record terminal sequence and resolve Turn.result before publishing and ending
+     * the execution hub. Session-wide publication and activity recomputation remain with publish.
+     */
+    private retainEvent;
+    /**
+     * The context control callbacks, submitExecution, interrupt and close allocate fresh host request
+     * identity here. Return sessionId/requestId from the configured ID source; generator failures throw.
+     * Deduplicated dispatch reuses supplied identity rather than generating another request.
+     */
+    private requestIdentity;
+    /**
+     * admitEvent calls for an ordered submission/bound event. Reject conflicting or definitively rejected
+     * bindings with PROTOCOL_ERROR; otherwise reuse/allocate the execution and resolve association.
+     * submitExecution consumes that promise to construct a Turn independently of native acknowledgement;
+     * the caller still owns event publication and dispatch bookkeeping.
+     */
+    private bindRecord;
+    /**
+     * submitExecution uses this on dispatch rejection; onRequestFailed calls after failure-status
+     * publication. Reject unresolved association with the original cause and track definitive rejection
+     * and acknowledgement. Unknown outcomes stay eligible for late binding; a pending dispatch remains
+     * pinned until bookkeeping acknowledges it. A resolved association is never undone.
+     */
+    private rejectSubmission;
+    /**
+     * submitExecution allocates before waiting for association; reserveSubmission also uses it for dispatch
+     * admission, including raw requests. Return existing bookkeeping or allocate a binding gate, reclaiming
+     * at most one acknowledged rejected/terminal entry under pressure. Throw BACKPRESSURE_EXCEEDED rather
+     * than evict unresolved work; callers own reservation, acknowledgement and settlement.
+     */
+    private getOrCreateSubmission;
+    /**
+     * getOrCreateSubmission calls under submission-count pressure. Evict the oldest acknowledged
+     * rejection or terminal association, if any. Unknown unbound submissions remain eligible for
+     * late binding; getOrCreateSubmission rejects admission if nothing can be reclaimed.
+     */
+    private reclaimSubmission;
+    /**
+     * submit and review return this association wait. Validate before allocating bookkeeping, dispatch
+     * independently, then construct a Turn when binding resolves. Observe dispatch rejection separately
+     * so the original error reaches an unresolved association while admitted records stay pinned through
+     * status publication. Caller abort/deadline ends only waiting; late binding and native work continue.
+     * ID generation/cloning failures throw before dispatch; submit converts those throws to rejection.
+     */
+    private submitExecution;
+    /**
+     * submitExecution checks before creating an association gate; dispatchOperation checks every
+     * dispatch, including replays. Lifecycle failures take precedence over protocol/capability errors.
+     * Callers return these throws as rejected promises before reserving native work.
+     */
+    private validateRequestAdmission;
+    /**
+     * validateRequestAdmission checks lifecycle before protocol and capability admission.
+     * Throw for closed/closing/recovery-blocked business calls, retaining explicit interruption and
+     * interaction controls during close/recovery plus history and close during recovery. Callers expose
+     * these failures without native dispatch; this check changes no state.
+     */
+    private assertCallable;
+    /**
+     * request, submitExecution and closeRequest call before applying their own wait ownership. Validate
+     * and detach params, replay matching cached outcomes, admit capacity and reserve submission identity,
+     * then cache new work. Admission errors reject before native dispatch; request identity conflicts do
+     * not replace cached work. Serialization/cloning can throw to the surrounding caller; host deadlines
+     * never cancel the cached outcome or its bookkeeping.
+     */
+    private dispatchOperation;
+    /**
+     * dispatchOperation calls after replay checks and before reserving submission identity. Reclaim at
+     * most the oldest settled request, then report whether a new dispatch fits. Unsettled outcomes stay
+     * cached even when their host observers have cancelled; a false result becomes BACKPRESSURE_EXCEEDED.
+     */
+    private admitRequestCapacity;
+    /**
+     * dispatchOperation calls only for submission-bearing methods once request-cache capacity is
+     * available. Reserve one request ID per submission or throw a conflict/capacity error before native
+     * execution. Association alone does not acknowledge dispatch; outcome bookkeeping owns that step.
+     */
+    private reserveSubmission;
+    /**
+     * dispatchOperation returns this shared outcome after admission. Cache before native work starts
+     * in a microtask, race that work against observation closure, and observe bookkeeping separately.
+     * Replays receive the same receipt/rejection without awaiting binding/status events; bookkeeping
+     * failures end observation through fail rather than replace the cached outcome.
+     */
+    private cacheRequestOutcome;
+    /**
+     * cacheRequestOutcome schedules this once per admitted request. Route interaction controls through
+     * the registry or await the backend, validate native identity before projecting content, then update
+     * request-owned state and return a frozen validated result. Failures reject the cached outcome unless
+     * observation closure wins its race; execution and state effects can still finish after that race.
+     * The caller owns outcome bookkeeping and never retries native work automatically.
+     */
+    private executeRequest;
+    /**
+     * executeRequest awaits one invocation after request admission. Keep manual interaction responses
+     * and cancellations in the registry so they share settlement with automatic handlers; dispatch other
+     * methods to the attached backend. Throws/rejections become cached request failures without retries.
+     */
+    private invokeRequest;
+    /**
+     * executeRequest projects only after native-result validation. Redact history before the optional
+     * host hook, preserve submission/close receipts, and project other method results. Projection failures
+     * reject the cached outcome; executeRequest still owns hook invocation and final result validation.
+     */
+    private projectRequestResult;
+    /**
+     * executeRequest commits projected config, revert-reference and goal results before freezing the
+     * returned receipt. Cloning failures reject that request; caller cancellation does not roll back
+     * these updates. Other methods leave request-owned state unchanged; events own execution activity.
+     */
+    private applyRequestResult;
+    /**
+     * executeRequest calls before privacy projection or request-owned state changes. Validate protocol
+     * shape and submission/steer identities; malformed results call rejectNativeResult, which throws an
+     * unknown-outcome protocol error and starts observation teardown. On success the assertion narrows
+     * the native value for projection.
+     */
+    private validateNativeResult;
+    /**
+     * validateNativeResult calls for malformed shape or conflicting identity. Start fail without waiting
+     * for cleanup, then throw the same unknown-outcome protocol error into executeRequest's rejection.
+     * Native effects cannot be inferred safely, so caller-visible failure must not claim definite rejection.
+     */
+    private rejectNativeResult;
+    /**
+     * cacheRequestOutcome registers this success continuation separately from its returned receipt.
+     * Acknowledge a retained submission, await receipt-based binding before status, and publish accepted/
+     * queued/dispatched disposition while observation remains open. A publication failure goes to the
+     * cache's fail observer without replacing the receipt; non-submission outcomes need no bookkeeping.
+     */
+    private onRequestSucceeded;
+    /**
+     * cacheRequestOutcome registers this rejection continuation separately from its returned failure.
+     * Mark eligible unknown outcomes as requiring recovery, then publish submission failure before
+     * acknowledging it with rejectSubmission. Publication failure goes to the cache's fail observer;
+     * unknown outcomes remain available for late binding. Definite submission rejection alone leaves
+     * unrelated executions usable.
+     */
+    private onRequestFailed;
+    /**
+     * requestInteraction calls only after requested-event publication. Invoke the supplied host handler
+     * with a cloned native request and abort signal, then send its answer through InteractionRegistry.
+     * Skip aborted invocation/delivery; release capacity only when host work settles, even after native
+     * settlement. Handler/delivery failure cancels an actionable interaction; secondary cancellation
+     * errors are observed and suppressed. This scheduling does not return a handler wait to the adapter.
+     */
+    private startInteractionHandler;
+    /**
+     * fail, finishClose and dispose call at their respective teardown stages. Mark closed, reject the
+     * closure race and unresolved associations/results, abort handler signals and end unfinished streams.
+     * Completed execution snapshots/streams remain intact. Callers own interaction cancellation, backend
+     * release and any native close; rejecting observation does not assert execution stopped.
+     */
+    private endObservation;
+    /**
+     * close and request(session/close) return this caller wait around shared close work or, once
+     * observation is closed, backend release. Invalid or already-aborted waits reject before either
+     * operation starts. Later abort/deadline affects only the caller's wait.
+     */
+    private closeRequest;
+    /**
+     * closeRequest asks for a receipt on an already-closed session. Await backend release and
+     * propagate its failure before returning the stored native receipt or an unconfirmed stop.
+     */
+    private closedReceipt;
+    /**
+     * closeRequest starts this once per close attempt. Dispatch before marking the session closing
+     * so close itself passes the lifecycle guard. A successful receipt proceeds through finishClose.
+     * Dispatch rejection clears the close gate, marks recovery when the outcome is unknown and
+     * rejects shared close work with the original cause.
+     */
+    private startClose;
+    /**
+     * startClose registers this on native success and shares its result or cleanup rejection with host
+     * waiters. Store the receipt, attempt interaction cancellation then backend release in order, and end
+     * observation even if cleanup failed. Throw a safe combined error only after both attempts; native stop
+     * confirmation changes unfinished-observation diagnostics without inventing terminal Turn results.
+     */
+    private finishClose;
+    /**
+     * fail, closedReceipt, finishClose and dispose share the backend's returned release promise and its
+     * rejection; never infer native stop. A synchronous disposal throw escapes before promise caching.
+     * Before attachment the no-op promise does not own a backend arriving later: attach rejects/releases
+     * that backend when observation has already closed.
+     */
+    private disposeBackend;
+}