@anureo/sdk 0.2.0 → 0.3.0

package/src/index.js

@@ -0,0 +1,23 @@
+// Root entry point for the application API, adapter contracts and host utilities.
+export { createClient, Client } from "./client.js";
+export { Session } from "./session.js";
+export { Turn } from "./turn.js";
+export * from "./errors.js";
+export { waitForRequest } from "./request.js";
+/** Adapter/observer buffering primitives, also available from the package's queue entry point. */
+export * from "./queue.js";
+/** Session-local native ID mapping implementation. */
+export * from "./adapter/identity.js";
+/** Interaction settlement and replay implementation used by Session. */
+export * from "./lifecycle/interactions.js";
+/** Adapter subprocess handles and launch helpers, also available from the process entry point; callers drain output and await handle disposal. */
+export * from "./process.js";
+/** Marked-secret projection implementation used by Session. */
+export * from "./privacy/secrets.js";
+/**
+ * Forward LogTape's host logging controls without adding SDK ownership. The exported dispose is
+ * LogTape's logging teardown; native resources are released through Client.dispose separately.
+ */
+export { configure, configureSync, dispose, disposeSync, drain, getLogger, reset, resetSync } from '@logtape/logtape';
+/** Explicit unattended approval policy for hosts; never enabled by Client automatically. */
+export { approveWithNarrowestScope } from "./lifecycle/approval.js";

package/src/lifecycle/approval.d.ts

@@ -0,0 +1,16 @@
+import type { InteractionRequested, InteractionResponse } from '@anureo/protocol';
+/**
+ * Select an advertised grant for unattended approval. Prefer allow-once, then session, then
+ * rule grants. When several options have the same scope, return the first advertised option.
+ * Reject with Error when the request offers none of these grants.
+ *
+ * Opt in through ClientOptions.interactions.approval, as createReviewClient and
+ * createRefactorClient do. The returned promise completes when the answer is selected.
+ * Session.startInteractionHandler invokes the registered policy and awaits native delivery
+ * separately. If selection rejects while the signal is active, Session attempts cancellation.
+ */
+export declare function approveWithNarrowestScope(request: Extract<InteractionRequested, {
+    kind: 'approval';
+}>): Promise<Extract<InteractionResponse, {
+    kind: 'approval';
+}>>;

package/src/lifecycle/approval.js

@@ -0,0 +1,18 @@
+/**
+ * Select an advertised grant for unattended approval. Prefer allow-once, then session, then
+ * rule grants. When several options have the same scope, return the first advertised option.
+ * Reject with Error when the request offers none of these grants.
+ *
+ * Opt in through ClientOptions.interactions.approval, as createReviewClient and
+ * createRefactorClient do. The returned promise completes when the answer is selected.
+ * Session.startInteractionHandler invokes the registered policy and awaits native delivery
+ * separately. If selection rejects while the signal is active, Session attempts cancellation.
+ */
+export async function approveWithNarrowestScope(request) {
+    const allow = request.options.find(option => option.semantic === 'allowOnce')
+        ?? request.options.find(option => option.semantic === 'allowSession')
+        ?? request.options.find(option => option.semantic === 'allowWithRule');
+    if (!allow)
+        throw new Error('Approval request has no allow option');
+    return { kind: 'approval', optionId: allow.id };
+}

package/src/lifecycle/deferred.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Create a package-internal promise with caller-owned settlement. Session uses it for observation
+ * closure, retained execution results and submission binding. A preinstalled rejection observer
+ * allows callers to attach later and still receive the original rejection.
+ */
+export declare function deferred<T>(): {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (cause: unknown) => void;
+};

package/src/lifecycle/deferred.js

@@ -0,0 +1,12 @@
+/**
+ * Create a package-internal promise with caller-owned settlement. Session uses it for observation
+ * closure, retained execution results and submission binding. A preinstalled rejection observer
+ * allows callers to attach later and still receive the original rejection.
+ */
+export function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+    void promise.catch(() => { });
+    return { promise, resolve, reject };
+}

package/src/lifecycle/errors.d.ts

@@ -0,0 +1,18 @@
+import { HarnessSdkError } from "../errors.js";
+/**
+ * Construct the package-internal error used to reject unfinished Turn results and streams.
+ * Session.finishClose passes native stop confirmation; Session.dispose uses the unconfirmed default.
+ * Even confirmed stop supplies no terminal result, so outcomeUnknown stays true. Callers still own
+ * interaction cancellation and backend release; constructing this error performs neither.
+ */
+export declare function observationClosed({ executionStopped }?: {
+    executionStopped?: 'confirmed' | 'unconfirmed';
+}): HarnessSdkError;
+/**
+ * Construct a package-internal aggregate of cleanup failures without releasing resources.
+ * Client.dispose and Session.finishClose throw this after their release attempts. The client's
+ * rethrowAfterCleanup uses it when setup and cleanup both fail. Deduplicate input causes and
+ * flatten nested release diagnostics in order. The returned error contains codes and unknown-outcome
+ * flags so raw failure messages stay out of aggregate diagnostics.
+ */
+export declare function combined(causes: unknown[]): HarnessSdkError;

package/src/lifecycle/errors.js

@@ -0,0 +1,45 @@
+import { HarnessSdkError, sdkError } from "../errors.js";
+/**
+ * Construct the package-internal error used to reject unfinished Turn results and streams.
+ * Session.finishClose passes native stop confirmation; Session.dispose uses the unconfirmed default.
+ * Even confirmed stop supplies no terminal result, so outcomeUnknown stays true. Callers still own
+ * interaction cancellation and backend release; constructing this error performs neither.
+ */
+export function observationClosed({ executionStopped = 'unconfirmed' } = {}) {
+    const message = executionStopped === 'confirmed'
+        ? 'Observation closed before a native terminal result'
+        : 'Observation closed; execution stop is unconfirmed';
+    return new HarnessSdkError('OBSERVATION_CLOSED', message, false, true, { source: 'sdk', executionStopped });
+}
+/**
+ * Construct a package-internal aggregate of cleanup failures without releasing resources.
+ * Client.dispose and Session.finishClose throw this after their release attempts. The client's
+ * rethrowAfterCleanup uses it when setup and cleanup both fail. Deduplicate input causes and
+ * flatten nested release diagnostics in order. The returned error contains codes and unknown-outcome
+ * flags so raw failure messages stay out of aggregate diagnostics.
+ */
+export function combined(causes) {
+    const errors = [...new Set(causes)].flatMap(releaseDiagnostics);
+    return new HarnessSdkError('RESOURCE_RELEASE_FAILED', 'One or more owned resources could not be released', false, true, { source: 'sdk', errors });
+}
+/**
+ * releaseDiagnostics filters nested aggregates with this guard before copying their codes. Accept
+ * only bounded machine-readable codes; do not trust nested messages or arbitrary error details.
+ */
+function isReleaseDiagnostic(value) {
+    return !!value && typeof value === 'object' && 'code' in value
+        && typeof value.code === 'string' && /^[A-Z][A-Z0-9_]{0,80}$/.test(value.code);
+}
+/**
+ * combined flat-maps each distinct cause through this normalization. Flatten an existing release
+ * aggregate or return one safe code/unknown flag, preserving input order and discarding raw causes.
+ * No cleanup is attempted; callers decide when to throw the aggregate.
+ */
+function releaseDiagnostics(cause) {
+    const error = sdkError(cause);
+    if (error.code === 'RESOURCE_RELEASE_FAILED' && Array.isArray(error.details?.errors)) {
+        return error.details.errors.filter(isReleaseDiagnostic)
+            .map(value => ({ code: value.code, outcomeUnknown: value.outcomeUnknown === true }));
+    }
+    return [{ code: error.code, outcomeUnknown: error.outcomeUnknown }];
+}

package/src/lifecycle/events.d.ts

@@ -0,0 +1,35 @@
+import type { EventSubscriptionOptions } from "../types.js";
+/**
+ * Package-internal fan-out for bounded live subscriptions without replay or producer backpressure.
+ * Session.publish feeds the session hub and Session.retainEvent feeds each execution hub.
+ * Session orders and ends those streams. Consumers release their own subscriptions.
+ */
+export declare class EventHub<T> {
+    /**
+     * Subscribe to future events with an independent queue. Session.events and Turn.events return
+     * this iterator to host consumers, who exhaust or return it, or abort the signal to release it.
+     * Invalid budgets throw synchronously. The optional filter defaults to accepting all events. An
+     * overlapping blocked read rejects with CONCURRENT_EVENT_READ and ends the subscription.
+     * Cancelling a live subscription completes its blocked and future reads and skips any
+     * buffered events. Once detached by termination or failure, abort no longer affects the reader.
+     * Late subscribers observe the stored termination even if their signal is already aborted.
+     */
+    subscribe(options?: EventSubscriptionOptions, accepts?: (value: T) => boolean): AsyncIterableIterator<T>;
+    /**
+     * Session.publish sends session events here; Session.retainEvent sends execution events here before
+     * ending terminal streams. Offer the event synchronously to each subscriber in registration
+     * order. Each subscriber filters and clones it independently. A filter, clone or queue admission
+     * failure closes that subscription and lets delivery continue. Ignore publication after hub end.
+     */
+    publish(value: T): void;
+    /**
+     * Session.retainEvent ends terminal execution streams; Session.endObservation ends remaining
+     * execution and session streams with a failure. Idempotently end all observers with an optional read
+     * failure and remove their abort listeners. Queued events drain before a truthy cause rejects reads
+     * (otherwise reads complete). Later subscribers observe the first termination without replay.
+     * Consumers still own returning or exhausting their readers.
+     */
+    end(cause?: unknown): void;
+    private readonly subscribers;
+    private termination?;
+}

package/src/lifecycle/events.js

@@ -0,0 +1,141 @@
+// Owns isolated live event fan-out and each observer's queue, reader and cancellation lifetime.
+import { BoundedEventQueue } from "../queue.js";
+/**
+ * Package-internal fan-out for bounded live subscriptions without replay or producer backpressure.
+ * Session.publish feeds the session hub and Session.retainEvent feeds each execution hub.
+ * Session orders and ends those streams. Consumers release their own subscriptions.
+ */
+export class EventHub {
+    /**
+     * Subscribe to future events with an independent queue. Session.events and Turn.events return
+     * this iterator to host consumers, who exhaust or return it, or abort the signal to release it.
+     * Invalid budgets throw synchronously. The optional filter defaults to accepting all events. An
+     * overlapping blocked read rejects with CONCURRENT_EVENT_READ and ends the subscription.
+     * Cancelling a live subscription completes its blocked and future reads and skips any
+     * buffered events. Once detached by termination or failure, abort no longer affects the reader.
+     * Late subscribers observe the stored termination even if their signal is already aborted.
+     */
+    subscribe(options = {}, accepts = () => true) {
+        const subscription = createSubscription({ options, accepts, remove: observer => this.subscribers.delete(observer) });
+        if (this.termination) {
+            subscription.queue.end(this.termination.cause);
+        }
+        else if (options.signal?.aborted) {
+            subscription.cancel();
+        }
+        else {
+            this.subscribers.add(subscription);
+            options.signal?.addEventListener('abort', subscription.cancel, { once: true });
+        }
+        return subscription.iterator;
+    }
+    /**
+     * Session.publish sends session events here; Session.retainEvent sends execution events here before
+     * ending terminal streams. Offer the event synchronously to each subscriber in registration
+     * order. Each subscriber filters and clones it independently. A filter, clone or queue admission
+     * failure closes that subscription and lets delivery continue. Ignore publication after hub end.
+     */
+    publish(value) {
+        if (this.termination)
+            return;
+        for (const subscriber of this.subscribers)
+            deliverToSubscriber(subscriber, value);
+    }
+    /**
+     * Session.retainEvent ends terminal execution streams; Session.endObservation ends remaining
+     * execution and session streams with a failure. Idempotently end all observers with an optional read
+     * failure and remove their abort listeners. Queued events drain before a truthy cause rejects reads
+     * (otherwise reads complete). Later subscribers observe the first termination without replay.
+     * Consumers still own returning or exhausting their readers.
+     */
+    end(cause) {
+        if (this.termination)
+            return;
+        this.termination = { cause };
+        for (const subscriber of this.subscribers) {
+            subscriber.end(cause);
+        }
+    }
+    subscribers = new Set();
+    termination;
+}
+/**
+ * EventHub.subscribe allocates an observer here before deciding whether to register it or close it.
+ * Queue construction can throw before registration. Closure calls remove to release hub membership
+ * and leaves the reader available to drain. Cancellation also returns the reader to release ownership.
+ */
+function createSubscription({ options, accepts, remove }) {
+    const queue = createSubscriptionQueue(options);
+    const reader = queue[Symbol.asyncIterator]();
+    let cancelled = false;
+    /** Remove hub membership and the listener registered by subscribe, leaving the reader available to drain. */
+    const detach = () => {
+        remove(subscription);
+        options.signal?.removeEventListener('abort', cancelSubscription);
+    };
+    /** Hub termination and delivery/read failures detach before closing admission, preserving buffered drain. */
+    const endSubscription = (cause) => {
+        detach();
+        queue.end(cause);
+    };
+    /** subscribe registers this abort listener; early iterator exit also skips retained data and releases ownership. */
+    const cancelSubscription = () => {
+        cancelled = true;
+        endSubscription();
+        void reader.return?.();
+    };
+    const iterator = {
+        /** Reuse the claimed reader for for-await, without acquiring a second queue reader. */
+        [Symbol.asyncIterator]() { return this; },
+        /** Await queue delivery/termination and propagate read failures after detaching; cancellation skips retained data. */
+        async next() {
+            if (cancelled)
+                return { done: true, value: undefined };
+            try {
+                const result = await reader.next();
+                if (result.done)
+                    detach();
+                return result;
+            }
+            catch (cause) {
+                endSubscription(cause);
+                throw cause;
+            }
+        },
+        /** Early exit completes this observer's blocked reads without stopping the shared producer. */
+        async return() {
+            cancelSubscription();
+            return { done: true, value: undefined };
+        },
+        /** Release this observer before rejecting with the consumer's supplied cause. */
+        async throw(cause) {
+            cancelSubscription();
+            throw cause;
+        },
+    };
+    const subscription = { queue, accepts, end: endSubscription, cancel: cancelSubscription, iterator };
+    return subscription;
+}
+/** Allocate an observer's queue, capping individual events at 8 MiB or the smaller total byte budget. Invalid limits throw before registration. */
+function createSubscriptionQueue(options) {
+    const maxBytes = options.queue?.maxBytes ?? 16 * 1024 * 1024;
+    return new BoundedEventQueue({
+        ...options.queue,
+        maxBytes,
+        maxFrameBytes: Math.min(maxBytes, 8 * 1024 * 1024),
+    });
+}
+/**
+ * EventHub.publish offers each event here. Filter before cloning so each accepting subscriber gets
+ * its own copy. On failure, close only this subscriber and preserve its buffered events before a
+ * truthy cause rejects reads or a falsy cause completes them.
+ */
+function deliverToSubscriber(subscriber, value) {
+    try {
+        if (subscriber.accepts(value))
+            subscriber.queue.push(structuredClone(value));
+    }
+    catch (cause) {
+        subscriber.end(cause);
+    }
+}

package/src/lifecycle/execution-observation.d.ts

@@ -0,0 +1,33 @@
+import type { AhpEvent } from '@anureo/protocol';
+import type { EventHub } from "./events.js";
+import type { Input, RequestOptions, TurnResult } from "../types.js";
+/**
+ * Internal port allocated by Session.context and passed to Turn by Session.submitExecution when
+ * association resolves. Turn uses it for live subscriptions, terminal results and explicit controls.
+ * Session owns event ordering, shared settlement and native resources. Each Turn owns its wait
+ * and subscription cancellation.
+ */
+export interface ExecutionObservation {
+    /** Stable execution ID reported by the adapter and shared by submissions bound to the same turn. */
+    readonly id: string;
+    /** Session-owned live producer hub; Turn.events creates an isolated subscription without replay. */
+    readonly events: EventHub<AhpEvent>;
+    /** Session.retainEvent resolves the frozen snapshot at native completion. Session.endObservation rejects unfinished results on closure. */
+    readonly result: Promise<TurnResult>;
+    /** Session.retainEvent sets this on turn/completed before publishing the terminal event and ending its stream. */
+    readonly terminal: boolean;
+    /**
+     * Turn.steer explicitly invokes the callback installed by Session.context. It normalizes input and
+     * awaits Session.request('turn/steer') with this execution as the atomic target. It discards the
+     * validated receipt and propagates normalization, admission, dispatch and wait rejections. Native
+     * work continues if the caller ends its wait after admission.
+     */
+    steer(input: Input, wait?: RequestOptions): Promise<void>;
+    /**
+     * Turn.interrupt explicitly invokes the callback installed by Session.context. It awaits
+     * Session.request('turn/interrupt') for this execution, discarding the validated receipt or
+     * propagating admission, dispatch and wait rejections. Session.retainEvent settles result
+     * separately when the terminal event arrives.
+     */
+    interrupt(wait?: RequestOptions): Promise<void>;
+}

package/src/lifecycle/immutable.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Clone acyclic protocol data and freeze enumerable object and array descendants. Cloning or
+ * freezing failures throw and leave the original value untouched.
+ *
+ * Called by:
+ * - Client.initialize to store negotiated capabilities; failure rejects initialization.
+ * - Session's constructor/attach and binding/reference/capabilities/snapshot getters to detach stored
+ *   or exposed state. Session.executeRequest returns frozen receipts; failure rejects its request.
+ * - ResultAccumulator.finish to return a terminal snapshot. Session.retainEvent settles the shared
+ *   Turn result with that snapshot, or lets a failure propagate through ordered publication.
+ */
+export declare function immutable<T>(value: T): T;

package/src/lifecycle/immutable.js

@@ -0,0 +1,28 @@
+/**
+ * Clone acyclic protocol data and freeze enumerable object and array descendants. Cloning or
+ * freezing failures throw and leave the original value untouched.
+ *
+ * Called by:
+ * - Client.initialize to store negotiated capabilities; failure rejects initialization.
+ * - Session's constructor/attach and binding/reference/capabilities/snapshot getters to detach stored
+ *   or exposed state. Session.executeRequest returns frozen receipts; failure rejects its request.
+ * - ResultAccumulator.finish to return a terminal snapshot. Session.retainEvent settles the shared
+ *   Turn result with that snapshot, or lets a failure propagate through ordered publication.
+ */
+export function immutable(value) {
+    const copy = structuredClone(value);
+    /**
+     * immutable invokes this recursive walk on its detached clone. Freeze descendants first so no
+     * enumerable object/array child of a returned protocol snapshot remains writable; failures propagate.
+     */
+    const freeze = (entry) => {
+        if (entry && typeof entry === 'object') {
+            for (const child of Object.values(entry)) {
+                freeze(child);
+            }
+            Object.freeze(entry);
+        }
+    };
+    freeze(copy);
+    return copy;
+}

package/src/lifecycle/input.d.ts

@@ -0,0 +1,9 @@
+import type { InputBlock } from '@anureo/protocol';
+import type { Input } from "../types.js";
+/**
+ * Normalize host input into one text block for a string or a detached copy of a block array.
+ * Throw INVALID_PARAMS for other values or clone failure. Session.submit and the callback installed
+ * by Session.context for Turn.steer pass the resulting blocks to request admission, which validates
+ * their contents and capabilities. Both expose normalization failures as promise rejections.
+ */
+export declare function inputBlocks(input: Input): InputBlock[];

package/src/lifecycle/input.js

@@ -0,0 +1,19 @@
+import { HarnessSdkError } from "../errors.js";
+/**
+ * Normalize host input into one text block for a string or a detached copy of a block array.
+ * Throw INVALID_PARAMS for other values or clone failure. Session.submit and the callback installed
+ * by Session.context for Turn.steer pass the resulting blocks to request admission, which validates
+ * their contents and capabilities. Both expose normalization failures as promise rejections.
+ */
+export function inputBlocks(input) {
+    if (typeof input === 'string')
+        return [{ type: 'text', text: input }];
+    if (!Array.isArray(input))
+        throw new HarnessSdkError('INVALID_PARAMS');
+    try {
+        return structuredClone(input);
+    }
+    catch {
+        throw new HarnessSdkError('INVALID_PARAMS');
+    }
+}

package/src/lifecycle/interactions.d.ts

@@ -0,0 +1,129 @@
+import { type InteractionRequested, type InteractionResponse, type InteractionResult } from "@anureo/protocol";
+import type { NativeInteractionResponder } from "../ports.js";
+/**
+ * Track native requests, settle their answers and retain bounded response replay state.
+ * Session uses this SDK implementation helper and supplies publication and privacy hooks.
+ * Direct consumers own those integrations and should await cancelAll with a teardown reason
+ * when releasing a session. The registry owns request expiry and native response wait timers.
+ */
+export declare class InteractionRegistry {
+    private readonly publish;
+    private readonly limits;
+    private readonly beforeResponse?;
+    /**
+     * Configure settlement publication and synchronous pre-response checks without starting native
+     * work. Session supplies a publisher that aborts the host handler and awaits publication of
+     * interaction/resolved while observation is open. It also supplies SecretRedactor.rememberResponse
+     * to register secrets before delivery. respond runs the check for every validated attempt, including
+     * replays, and propagates a throw before delivery. Settlement awaits publication without a deadline.
+     */
+    constructor(publish: (result: InteractionResult) => Promise<void>, limits: {
+        /** Pending and settling capacity. Admission trims resolved records at maxPending + 1024. */
+        maxPending: number;
+        /** Interaction lifetime in milliseconds, shortened by an earlier request expiresAt. */
+        timeoutMs: number;
+        /** Native response/cancellation wait in milliseconds, defaulting to 30,000. Native work can continue after timeout. */
+        responseTimeoutMs?: number;
+    }, beforeResponse?: ((request: InteractionRequested, response: InteractionResponse) => void) | undefined);
+    /**
+     * Count requests that consume admission capacity in begin, including native delivery and
+     * cancellation in flight. Capacity becomes available when a request is marked resolved.
+     */
+    get pendingCount(): number;
+    /**
+     * List detached copies of actionable requests for manual answering. Cloning failures throw
+     * without changing registry state. These copies retain native fields, so callers own projection
+     * before exposing them to observers.
+     */
+    pending(): InteractionRequested[];
+    /**
+     * Register a unique unexpired request and an unrefed expiry timer. Duplicate IDs, exhausted
+     * capacity and invalid/elapsed lifetimes throw synchronously. A request-cloning failure rejects
+     * the returned promise after the expiry timer is scheduled. On success, the promise resolves
+     * with the answer after native delivery and result publication.
+     * Cancellation and peer settlement reject it after publication is attempted. If native delivery
+     * fails and publishing its unknown outcome also fails, this waiter stays unresolved; respond
+     * rejects the publication failure instead.
+     * Session.requestInteraction adopts this promise after publishing interaction/requested and
+     * scheduling any host handler. Adapters supply the responder through that sink method and own
+     * the native resources it uses.
+     */
+    begin(request: InteractionRequested, responder: NativeInteractionResponder): Promise<InteractionResponse>;
+    /**
+     * Deliver an answer or replay the retained operation for the same request ID and serialized
+     * response. Validation and the synchronous pre-response hook run before any replay or delivery.
+     * Missing IDs reject with INTERACTION_EXPIRED. Conflicting answers to settling or resolved
+     * requests reject with INTERACTION_ALREADY_RESOLVED. The operation clears expiry, retains
+     * capacity during native delivery, and settles after the publication it initiates. If another
+     * settlement wins during delivery, late native success rejects with RESULT_UNKNOWN.
+     * Session.invokeRequest returns the promise for manual requests. Session.startInteractionHandler
+     * awaits it for automatic answers and attempts handler_failed cancellation on rejection while
+     * its signal remains active.
+     */
+    respond(id: string, requestId: string, response: InteractionResponse): Promise<InteractionResult>;
+    /**
+     * Cancel or expire an unresolved request, notifying native once when pending. The reason and
+     * outcome both default to "cancelled". Missing IDs reject with INTERACTION_EXPIRED. Resolved IDs
+     * and in-flight settlement with reason "cancelled" reject with INTERACTION_ALREADY_RESOLVED.
+     * Other reasons mark in-flight settlement unknown without another native call. Native notification
+     * failure or timeout also changes the outcome to unknown.
+     * Await publication, reject begin's waiter with INTERACTION_CANCELLED or RESULT_UNKNOWN, and
+     * return the outcome. If publication fails, the cancellation caller receives that failure and
+     * the original waiter still receives its lifecycle error. Session.invokeRequest returns this
+     * promise for manual cancellation. Session.startInteractionHandler and the expiry timer observe
+     * and suppress its rejection. cancelAll collects its outcome during teardown.
+     */
+    cancel(id: string, reason?: string, outcome?: CancellationOutcome): Promise<InteractionResult>;
+    /**
+     * Attempt concurrent cancellation of unresolved interactions, optionally limited to turnId; await
+     * every attempt and suppress individual failures. Session.fail, Session.finishClose and
+     * Session.dispose await this before releasing the backend. Use a reason other than "cancelled"
+     * to settle in-flight requests. The literal reason "connection_lost" requests an unknown outcome.
+     */
+    cancelAll(reason: string, turnId?: string): Promise<void>;
+    /**
+     * Publish native-side settlement without calling the responder; ignore unknown/resolved IDs
+     * and reject the waiter even for responded because no value is supplied. Clear expiry and release
+     * capacity before publication; publication failure rejects this call but still rejects the waiter.
+     * An unknown outcome rejects the waiter with RESULT_UNKNOWN; other outcomes use INTERACTION_ALREADY_RESOLVED.
+     * Session.resolveInteraction returns this promise to adapters reporting an already-settled native request.
+     */
+    resolveExternally(result: InteractionResult): Promise<void>;
+    private readonly records;
+    /**
+     * begin calls after admission checks, before inserting a new request. At the replay bound, evict
+     * only the oldest resolved record so unresolved native work and its capacity remain accounted for.
+     * Duplicate checks run first: a retained ID cannot be reused by evicting its own replay guard.
+     */
+    private evictOldestResolvedRecord;
+    /**
+     * respond caches this operation after admission. Bound native delivery without retrying it, then
+     * publish before resolving begin's waiter. If delivery succeeds after another settlement resolves
+     * the record, reject with RESULT_UNKNOWN without publishing again. Normalize delivery/publication
+     * failures for both callers. If publishing the unknown outcome itself fails, that failure escapes
+     * before the original waiter is rejected. Cancellation uses publishRejectedSettlement's finally instead.
+     */
+    private deliverResponse;
+    /**
+     * cancel calls only for an actionable record. Hold capacity and clear expiry before notifying native;
+     * timeout or notification failure changes the requested outcome to unknown. Release capacity before
+     * publication, then reject begin's waiter even if publication fails. Once started, this attempt
+     * still publishes after its native wait, even if teardown or peer settlement has already published.
+     */
+    private cancelPending;
+    /**
+     * Wait for publication before rejecting begin's waiter with its lifecycle error. A publication
+     * failure still reaches cancel, cancelPending or resolveExternally. Those callers clear expiry
+     * and release capacity before entering this step.
+     */
+    private publishRejectedSettlement;
+    /**
+     * Bound one invocation of the adapter's registered callback. deliverResponse supplies the answer
+     * and cancelPending supplies null and a reason. Both await and classify native errors or timeout.
+     * A timeout ends the registry's wait and keeps observing late rejection. The adapter still owns
+     * completion and native resource cleanup.
+     */
+    private notifyNative;
+}
+type CancellationOutcome = "cancelled" | "expired" | "unknown";
+export {};