@threahq/remote-session 0.1.0

package/session.d.ts

@@ -0,0 +1,729 @@
+import { BotRuntimeTransport, type BotRuntimeHello, type DecisionOption, type DecisionRequest, type DelegationAvailableNudge, type StepFrame } from "@threahq/bot-runtime-client";
+import { type RemoteSessionConfig } from "./identity.js";
+import { ThreaClient, type ClaimedInvocation, type RuntimeSessionLink } from "./client.js";
+export declare const SUPPORTED_CAPABILITIES: readonly ["active-scratchpad", "mentionable"];
+export declare const SESSION_CONTROL_CAPABILITY = "session-control";
+/** Milliseconds to wait after an interrupt before delivering the steer turn, so the runtime has returned to idle. */
+export declare const STEER_SETTLE_MS = 250;
+export declare const RECONNECT_HANDOFF_FALLBACK_MS = 30000;
+export declare const COMPLETED_TURN_MEMORY = 64;
+export interface ModelSuggestionInfo {
+    value: string;
+    label?: string;
+    description?: string;
+}
+/** A runtime this session can hand a `/spawn` off to; `description` is the resolved binary path. */
+export interface SpawnRuntimeInfo {
+    value: string;
+    label: string;
+    /** What `--thinking` accepts for THIS runtime, so a Claude desk can offer Pi's levels and back. */
+    thinkingLevels: readonly string[];
+    /** What `--model` accepts for THIS runtime, read from its own config on this machine. */
+    models: readonly ModelSuggestionInfo[];
+    description?: string;
+}
+/** A turn handed to the connector for execution by its runtime. */
+export interface DeliveredTurn {
+    invocationId: string;
+    streamId: string;
+    /** The stream tree the turn belongs to: the session's scratchpad, or a channel or DM root when the bot was mentioned there. */
+    rootStreamId: string;
+    sourceMessageId: string;
+    content: string;
+    /**
+     * The turn arrived sealed (E2EE): everything the connector records for it is
+     * ciphertext to the server, so a transcript tracer may run in full-detail
+     * mode — the point of sealed steps is more for the owner, nothing for the server.
+     */
+    sealed: boolean;
+}
+/**
+ * How a connector drives its runtime for session control. `stop` and `steer`
+ * are actuated by the SDK itself (they manipulate SDK-owned turn state) using
+ * `interrupt()`/`steer()`; every other advertised command is routed to
+ * `runCommand`, which returns the user-facing ack markdown.
+ */
+export interface SessionControlInvocationContext {
+    rootStreamId: string;
+    /** The message the user typed the command into — what a command anchors its thread on. */
+    sourceMessageId: string;
+}
+export interface SessionControlActuator {
+    /** Command names to advertise (must be Threa catalog names, e.g. "model", "thinking", "compact", "run", "reload", "steer", "stop"). */
+    commands: readonly string[];
+    /** Model options for the composer's arg picker. */
+    modelSuggestions?: readonly ModelSuggestionInfo[];
+    /** Levels for the canonical /thinking command's arg picker. */
+    thinkingLevels?: readonly string[];
+    /** Runtimes for the canonical /spawn command's arg picker. */
+    spawnRuntimes?: readonly SpawnRuntimeInfo[];
+    /** Which of them a `/spawn` naming no runtime lands on, so the picker offers its models first. */
+    spawnDefaultRuntime?: string;
+    /**
+     * Interrupt the runtime's current turn. False = control lost (e.g. pane gone).
+     * The SDK always passes the stream the turn answers into; a serial runtime may
+     * ignore it, but a runtime declaring `maxConcurrentTurns > 1` must interrupt
+     * only that stream's turn.
+     */
+    interrupt(streamId?: string): boolean;
+    /**
+     * Fold text into the RUNNING turn without interrupting it — the runtime's
+     * native mid-turn steering (typing into Claude Code while it works). When
+     * present and a turn is in flight, /steer steers in place: the running
+     * invocation keeps its trace and its reply. Absent, /steer falls back to
+     * interrupt + redeliver. False = control lost. The SDK always passes the
+     * target stream; a serial runtime may ignore it, but a runtime declaring
+     * `maxConcurrentTurns > 1` must steer only that stream's turn.
+     */
+    steer?(text: string, streamId?: string): Promise<boolean> | boolean;
+    runCommand(name: string, args: string, context: SessionControlInvocationContext): Promise<{
+        /** False rejects the command: it closes as failed with `message` as the reason and nothing is posted. */
+        ok: boolean;
+        /** What the command did ("Set the model to opus"). It lands on the command's own entry, not in the stream. */
+        summary?: string;
+        /** Reply markdown, for a command whose result is content the user asked for (`/status`'s report) rather than an account of it. */
+        message?: string;
+        afterAck?: () => unknown | Promise<unknown>;
+        /**
+         * Hand the still-open command to another process, which drives its steps
+         * and closes it with this claim. Nothing is posted and the SDK stops
+         * observing the command once the handoff returns; a throw fails it here.
+         */
+        handoff?: (claim: HandedOffCommandClaim) => unknown | Promise<unknown>;
+        /**
+         * Set by a handoff this session outlives (`/spawn` launches a second agent).
+         * The default assumes the handoff is winding this session down, so presence
+         * parks busy and claiming pauses until the process is gone; a session that
+         * keeps running must answer the next message instead of sitting out the
+         * fallback window. `onHandoffReset` belongs to the parked path only.
+         */
+        handoffKeepsSessionRunning?: boolean;
+        onHandoffReset?: () => unknown | Promise<unknown>;
+    }>;
+}
+/** What another process needs to report on, renew and close a claimed command. */
+export interface HandedOffCommandClaim {
+    workspaceId: string;
+    invocationId: string;
+    instanceId: string;
+    claimToken: string;
+}
+/**
+ * What a connector implements. The SDK owns the whole session lifecycle —
+ * linking, claiming, steer/stop semantics, presence, idle timeouts, claim
+ * renewal, attachments — and calls the delegate at the two points a runtime
+ * differs: delivering a turn into it, and (optionally) driving it.
+ */
+export interface RemoteSessionDelegate {
+    /** Push a turn into the runtime. Resolve when handed off (not when answered). */
+    deliverTurn(turn: DeliveredTurn): Promise<void>;
+    /**
+     * The scratchpad link was created or resumed (also after an unarchive
+     * reattach). Runs before the link is committed locally and before presence
+     * is synced, so a connector can record what this process now owns. A throw
+     * leaves the session unlinked for this tick (the next poll links again); it
+     * does not stop the session from connecting or claiming meanwhile.
+     */
+    onLinked?(link: RuntimeSessionLink): Promise<void> | void;
+    /** Present iff the connector can drive the runtime. Gates advertising session control (fail-safe). */
+    sessionControl?: SessionControlActuator;
+    /**
+     * The linked scratchpad was archived (the server already ended the session
+     * link) and stayed archived through the restore grace window. Called after
+     * the SDK has gone offline and failed its in-flight turns; the connector
+     * finishes the wind-down — the Claude channel pushes its branch and kills
+     * its own tmux window, so this hook may never return. An unarchive within
+     * the grace window reattaches the session instead and this never fires.
+     */
+    onArchived?: (payload: {
+        rootStreamId: string;
+    }) => Promise<void> | void;
+}
+export interface ShutdownOptions {
+    /**
+     * The host runtime died under us — stdin closed and the parent process is
+     * gone: an OOM kill, a crash, a supervisor that took the pane down. A host
+     * that quit and closed us on the way out does not set this.
+     */
+    hostGone?: boolean;
+}
+/** The connector's runtime identity and user-facing wording. */
+export interface RuntimeDescriptor {
+    /** Threa runtime kind, e.g. "claude-code-channel". */
+    kind: string;
+    /** `bot:hello` output manifest. */
+    manifest?: BotRuntimeHello["manifest"];
+    /** Presence status text while a turn is executing, e.g. "Working in Claude Code…". */
+    busyStatusText: string;
+    /** Trace note recorded when a turn is handed to the runtime. */
+    forwardedNote?: string;
+    /** Error recorded on in-flight turns when the session shuts down. */
+    shutdownErrorMessage: string;
+    /**
+     * Streams that may run a turn at the same time. Absent = 1 = serial: one turn
+     * at a time across the whole session. Above 1, at most one turn per response
+     * stream runs, and the actuator must honour the `streamId` passed to
+     * `interrupt`/`steer`. At most 12.
+     */
+    maxConcurrentTurns?: number;
+}
+export interface SendResult {
+    ok: boolean;
+    message: string;
+    /** Set when the failure leaves the request open so the caller may retry. */
+    retryable?: boolean;
+    closedTurn?: true;
+}
+export interface RemoteSessionStatusSnapshot {
+    stopped: boolean;
+    linkGeneration: number;
+    linkState: "unlinked" | "linked" | "detached";
+    rootStreamId?: string;
+    activeStreamId?: string;
+    socketConnected: boolean;
+    inflightCount: number;
+    activeTurnStreamId?: string;
+    /** Distinct response streams with an in-flight turn. */
+    inflightStreamIds: string[];
+    /** Decisions opened on the stream and still awaiting an answer. */
+    pendingDecisionCount: number;
+}
+type SessionControlCommand = {
+    name: string;
+    args: string;
+};
+/**
+ * Extract the session-control command (name + args) from a claimed invocation.
+ * Prefers the structured `metadata.command` the dispatch endpoint stamps; falls
+ * back to parsing the `/name args` prompt for a session-control invocation.
+ */
+export declare function parseSessionControlCommand(invocation: ClaimedInvocation): SessionControlCommand | null;
+export declare function isSessionControlInvocation(invocation: ClaimedInvocation): boolean;
+/**
+ * Turn a claimed invocation into the body the runtime reads. The source message
+ * is the request; any hydrated history follows as compact context.
+ */
+export declare function formatInvocationContent(invocation: ClaimedInvocation): string;
+export declare function withInboundAttachments(content: string, manifest: string): string;
+/** Fold the steer text + any swept queued messages into one prompt (most recent last). */
+export declare function buildSteerContent(parts: string[]): string;
+/** Capabilities advertised in hello + presence. Session control only when the connector can drive the runtime. */
+export declare function supportedCapabilitiesFor(sessionControlEnabled: boolean): string[];
+export declare function effectiveRuntimeManifest(manifest: BotRuntimeHello["manifest"] | undefined, actuator: SessionControlActuator | undefined): NonNullable<BotRuntimeHello["manifest"]>;
+/**
+ * Capabilities to claim with. Idle: everything we support. Busy (a turn in
+ * flight): session-control ONLY, so /stop and /steer jump the queue while a
+ * normal active-scratchpad follow-up waits. Empty when busy without runtime
+ * control (callers must not claim in that state).
+ */
+export declare function claimCapabilitiesFor(busy: boolean, sessionControlEnabled: boolean): string[];
+export declare function runtimeCapabilitiesFor(runtimeSessionId: string, actuator: SessionControlActuator | undefined): Record<string, unknown>;
+/**
+ * The descriptive half of a presence body, handed to {@link RemoteSessionOptions.onPresence}
+ * after it has been published. Status is included so a supervisor can tell a
+ * session that is running from one that shut down; the BIK is not, because it
+ * belongs to the running process alone.
+ */
+export interface RuntimePresenceReport {
+    runtimeKind: string;
+    instanceId: string;
+    runtimeSessionId: string;
+    displayName: string;
+    status: "available" | "busy" | "offline";
+    capabilities: Record<string, unknown>;
+    manifest: Record<string, unknown>;
+}
+export interface RemoteSessionOptions {
+    config: RemoteSessionConfig;
+    client: ThreaClient;
+    delegate: RemoteSessionDelegate;
+    runtime: RuntimeDescriptor;
+    /** Injectable for tests. */
+    transport?: BotRuntimeTransport;
+    /**
+     * Tap for the workspace-wide `delegation:available` socket nudge (roadmap
+     * 5.4) — wire it to a `DelegationRunner.notifyAvailable()`. The nudge payload
+     * carries the delegation id so a runner lacking the stream grant can claim it
+     * by id (and, on 404, request access, F3). Only fires on the SDK-constructed
+     * transport; an injected transport owns its callbacks.
+     */
+    onDelegationAvailable?: (payload?: DelegationAvailableNudge) => void;
+    /**
+     * Called with every presence this session publishes, hello included, once the
+     * write has gone through. A supervising connector records it so presence can
+     * be held while the session's process is not running; a public connector has
+     * no use for it and leaves it unset.
+     */
+    onPresence?: (presence: RuntimePresenceReport) => void;
+    log?: (message: string) => void;
+    /** Override the archive→restore grace window (tests). */
+    archiveGraceMs?: number;
+}
+/**
+ * A linked Threa scratchpad session for one runtime instance. Owns the whole
+ * loop: link creation, claim drain + busy semantics, steer/stop, presence,
+ * idle timeouts, claim renewal, and attachment plumbing. Connectors implement
+ * `RemoteSessionDelegate` and call `sendInterim`/`reply` from their runtime.
+ */
+/** What a connector asks its human when it cannot make the call itself. */
+export interface DecisionRequestInput {
+    title: string;
+    /** Markdown body shown under the title on the card. */
+    body?: string;
+    options: DecisionOption[];
+    allowNote?: boolean;
+    externalRef?: string;
+    expiresInMs?: number;
+    /** Defaults to the active turn's stream, then the root stream. */
+    streamId?: string;
+    /** Defaults to the in-flight invocation on that stream when one is running. */
+    invocationId?: string;
+}
+export type DecisionOutcome = {
+    status: "resolved";
+    optionId: string;
+    note: string | null;
+    decision: DecisionRequest;
+} | {
+    status: "cancelled" | "expired";
+    decision: DecisionRequest;
+};
+/** Thrown into every awaiting `requestDecision` when the session tears down. */
+export declare class DecisionAbandonedError extends Error {
+    readonly decisionId: string;
+    constructor(decisionId: string);
+}
+export declare class RemoteSession {
+    private readonly config;
+    private readonly client;
+    private readonly delegate;
+    private readonly runtime;
+    private readonly transport;
+    private readonly log;
+    private readonly onPresence;
+    private readonly bik;
+    /** The keyring as last advertised to the server, so a grant only writes presence when it added a key. */
+    private advertisedKeyIds;
+    private readonly hello;
+    /** This bot's own id, learned from the `bot:hello` ack — a sealed card's AAD names its requester. */
+    private botId;
+    private link;
+    private linkGeneration;
+    private claiming;
+    /** Claim HTTP mutates server presence outside presenceTail, so teardown waits for its drain. */
+    private claimDrainTask;
+    private claimRetryTimer;
+    private claimFailures;
+    private reconnectHandoff;
+    private onHandoffReset;
+    private reconnectResetTimer;
+    private reconnectFallbackTask;
+    private stopped;
+    private readonly archive;
+    private pollTimer;
+    /** Consecutive empty poll ticks while the socket is down; drives the poll backoff. */
+    private emptyNoSocketPolls;
+    private readonly inflight;
+    private readonly completed;
+    private readonly terminalReplies;
+    private nextRouteOrder;
+    /** Teardown generation fences stale routes from writes, reinsertion, and presence changes. */
+    private lifecycle;
+    private presenceTail;
+    private readonly observedClaims;
+    private readonly cancelledInvocations;
+    private claimDrainRequested;
+    private claimDrainScheduled;
+    private activeTurnStream;
+    /** Decisions this session opened and is still awaiting an answer for, keyed by decision id. */
+    private readonly pendingDecisions;
+    private decisionPollTimer;
+    private readonly maxConcurrentTurns;
+    constructor(options: RemoteSessionOptions);
+    private get sessionControlEnabled();
+    private get parallel();
+    /** Distinct response streams of the in-flight routes. */
+    private inflightStreams;
+    /** With the serial default this is exactly `inflight.size > 0`. */
+    private get atCapacity();
+    private refreshHelloCapabilities;
+    /** The stream of the turn the runtime is executing right now, if any. */
+    get activeTurnStreamId(): string | undefined;
+    /** The scratchpad root stream, once linked. */
+    get rootStreamId(): string | undefined;
+    get statusSnapshot(): RemoteSessionStatusSnapshot;
+    /**
+     * Where this install's E2E keys live and which one it holds. Built lazily so
+     * an operator who never enables encryption is not asked to pick a key store.
+     */
+    private buildKeyring;
+    start(): Promise<void>;
+    /** Create (or recover) the scratchpad link. Best-effort so a transient Threa outage self-heals on the next poll tick. */
+    private ensureLink;
+    /** The reattach hook: a confirmed link is what cancels the grace, so failure must read as "still archived". */
+    private relinkAfterRestore;
+    private createLink;
+    /** Actionable next step for the link failures a retry alone will never fix. */
+    private linkErrorHint;
+    shutdown(options?: ShutdownOptions): Promise<void>;
+    private revokeAllRoutes;
+    private failUnansweredRoutes;
+    private verifyPrincipal;
+    private createSession;
+    /**
+     * Resolve the owner-key half of an E2E create. Throws with an actionable
+     * message when the owner has no encryption key — ensureLink logs it and
+     * retries each poll tick, so the session self-heals the moment the owner
+     * sets up encryption. This install's own key is phase two's to mint: under
+     * the per-stream policy it is keyed to a scratchpad that does not exist yet.
+     */
+    private resolveE2eCreateBlock;
+    /**
+     * Phase two of the encrypted create: mint the generation-0 stream key, wrap
+     * it to the owner's UIK + this install's BIK, and store the wraps. Until this
+     * lands nobody can seal into the scratchpad (INV-E1 keeps plaintext out), so
+     * a failure retries in place; a 409 means an earlier attempt landed.
+     */
+    private provisionE2eStreamKey;
+    /** Returns whether at least one invocation was claimed (feeds the poll backoff reset). */
+    private claimDrain;
+    private runClaimDrain;
+    private waitForClaimDrain;
+    /**
+     * Claim one invocation and, when it arrives sealed, hydrate it in place: open
+     * the SSK wraps with this install's BIK, decrypt the trigger + history, and
+     * stash the {@link SealingState} every reply/step seals with. From here on the
+     * invocation looks like a plaintext one to the rest of the loop — only the
+     * write paths branch on `sealing`. A hydration failure fails the invocation
+     * loudly (scrubbed reason) and reports "nothing claimed" rather than throwing
+     * the drain into a TTL-recycle loop.
+     */
+    private claimAndHydrate;
+    private scheduleClaimRetry;
+    private claimNext;
+    private markClaimProcessing;
+    private installInputUpdate;
+    private abortForInputRestart;
+    private abortRunningTurnForContext;
+    private applyInputUpdate;
+    private terminalizeObservedClaim;
+    private scheduleRequestedClaimDrain;
+    private isClaimCancelled;
+    private isOutputCurrent;
+    private releaseObservation;
+    private fenceObservedClaim;
+    private failFencedInvocation;
+    /**
+     * Start one turn that sees every ordinary message already queued behind this
+     * one, and return any session-control commands the sweep pulled up with them.
+     *
+     * Without this, N messages sent while the session was busy became N
+     * sequential turns, each answering a question the user had already moved
+     * past — the reply to message 1 arriving after they had sent 4 more. `/steer`
+     * has always folded the backlog (`sweepQueuedForSteer`); an ordinary message
+     * got no such treatment, and that asymmetry is the whole of the lag.
+     *
+     * The primary invocation keeps the reply; the folded ones close without a
+     * response of their own, exactly as the steer sweep closes what it folds.
+     * Session control is never folded as text — a queued `/stop` has to stop the
+     * turn, not become a line in its prompt — so it is handed back to the caller.
+     */
+    private startFoldedTurn;
+    /**
+     * The content each folded message contributes, attachments included, for the
+     * ones still live once every download has landed. Every claim here is under
+     * `observeClaim`, which renews it on its own timer, so a slow download cannot
+     * expire the claims the sweep is holding.
+     */
+    private foldedTurnParts;
+    private bindRunningOwner;
+    private unbindRunningOwner;
+    private completeContributors;
+    private failContributors;
+    /** Register an invocation as the in-flight turn and push its content to the runtime. */
+    private deliverTurn;
+    /** The turn-handed-to-runtime trace note — sealed under the stream key on an E2E turn. */
+    private recordForwardedStep;
+    /**
+     * Close a control invocation with session-authored text or no response. Final
+     * replies and idle timeouts use the prepared-close path so ambiguous retries
+     * retain their exact wire body.
+     */
+    private completeTurn;
+    private handleSessionControl;
+    private runStop;
+    private stopTurnsOutsideScratchpad;
+    /**
+     * Route /steer. With a turn in flight and a steer-capable actuator, fold the
+     * text into the RUNNING turn (the running invocation keeps its trace and its
+     * reply). Otherwise fall back to interrupt + redeliver — the only option for
+     * an idle session (there is no turn to fold into) or a runtime without
+     * native mid-turn steering.
+     */
+    private runSteer;
+    /**
+     * Steer in place: sweep any messages queued while busy, record a `steer`
+     * step on the running turn's trace (the visible record of what was folded
+     * in), and inject the combined text via the runtime's native mid-turn
+     * steering. The running invocation stays the primary — its eventual reply
+     * answers the steer — so the /steer command itself closes immediately
+     * (command_completed resolves the card) instead of spinning until the turn
+     * ends.
+     */
+    private steerRunningTurn;
+    /**
+     * Interrupt the running turn, then fold the steer text + any messages queued
+     * while the runtime was busy into ONE combined turn (mirrors Pi: N messages →
+     * 1 response). The interrupt is the only actuation; the combined content
+     * round-trips through the normal delivery path so the runtime replies to it.
+     */
+    private steerByInterrupt;
+    /**
+     * Claim messages queued while the runtime was busy and fold their text in
+     * (steer text last).
+     *
+     * Scoped to the stream the steered turn answers into, for the same reason the
+     * fold's sweep is: a message belonging to another stream would be folded
+     * here, closed unanswered where it was asked, and answered somewhere else.
+     * Unscoped when nothing is in flight — there is no turn whose stream to
+     * inherit, and the steer itself is then the only thing being folded into.
+     */
+    private sweepQueuedForSteer;
+    /** Fold the swept messages' prepared content (steer text last); a claim cancelled since its download contributes nothing. */
+    private steerParts;
+    /**
+     * Seal a session-control command ack under the stream key, when the claim
+     * carried the SSK wraps (an E2E scratchpad). Returns undefined on a plaintext
+     * claim or a key race — the caller then takes the plaintext path, which
+     * closes silently on E2E rather than showing the command as failed.
+     */
+    private sealSessionControlAck;
+    /**
+     * Close a session-control command with an account of what it did. The summary
+     * lands on the command's own entry, so nothing is posted in the stream and
+     * there is nothing to seal — it states what happened and never quotes stream
+     * content, the same way the dispatched entry already carries the command args.
+     */
+    private completeAck;
+    /** Close a session-control command by posting its answer — content the user asked for, not an account of the command. */
+    private completeReply;
+    private completeSilentAck;
+    private completeNoResponse;
+    private failAfterTerminalWrite;
+    private failInvocation;
+    /**
+     * Close every in-flight turn that an interrupt just aborted, so none
+     * idle-hangs for an hour. Nothing is posted: the /stop or /steer that caused
+     * the interrupt closes with its own account of it, on its own entry.
+     */
+    private completeInterruptedTurns;
+    /** The prompt + history the runtime reads, with any downloaded attachments appended as a manifest. */
+    private buildTurnContent;
+    /**
+     * The text a message folded into a running turn contributes: its prompt and
+     * the manifest of its own attachments — no history and no history
+     * attachments, the running turn already has them. A control command
+     * contributes its /steer args, or nothing.
+     */
+    private foldedSteerContent;
+    /**
+     * Download the turn's inbound attachments and return the manifest listing
+     * where they landed ("" when none). `sourceOnly` skips the history messages'
+     * attachments and takes the source message's alone.
+     */
+    private inboundAttachmentManifest;
+    private route;
+    private registerTurn;
+    private revokedResult;
+    private postTurnMessage;
+    private writeRouteMessage;
+    /**
+     * A reply that carries no words and no attachments closes as `noResponse` —
+     * the wire's own word for a turn that said nothing — instead of standing in a
+     * message the session never wrote.
+     */
+    private prepareReply;
+    private prepareTimeout;
+    private postPreparedClose;
+    private settleClosed;
+    private reopenAfterFailedCompletion;
+    private touchCompleted;
+    private isTerminalPostError;
+    private terminalizeRouteWrite;
+    private terminalWriteResult;
+    private terminalResult;
+    /** Drop write credentials but retain a digest for exact final-reply idempotency. */
+    private evictTerminalRoute;
+    private postThroughClosed;
+    sendInterim(invocationId: string, text: string): Promise<SendResult>;
+    private runSend;
+    reply(invocationId: string, text: string): Promise<SendResult>;
+    private runReply;
+    private closeWith;
+    private runCompletion;
+    private closeStaleReply;
+    /**
+     * Close an in-flight turn as failed: the runtime reported the work itself
+     * failed, so nothing is posted and the invocation carries the reason. Mirrors
+     * what the delivery catch path does after `registerTurn` — the route dies,
+     * presence frees up, and the next claim drain runs. Tracked as the route's
+     * closing task so a shutdown mid-fail awaits it instead of failing the turn
+     * a second time. Returns false when this session holds no route for the id or
+     * the turn already closed, so nothing was failed.
+     */
+    failTurn(invocationId: string, errorMessage: string): Promise<boolean>;
+    /**
+     * Record trace steps against an in-flight turn. Fire-and-forget: a failed
+     * frame is logged and dropped, not retried — steps are ephemeral progress,
+     * not state. Returns false when the invocation is no longer taking work
+     * (answered, expired, superseded, or its completion is already on the wire),
+     * which a transcript tailer uses as its stop signal. Frames must arrive
+     * already redacted (or full, on a sealed turn — the tailer decides); this
+     * method ships them verbatim, sealing each one under the stream key when the
+     * turn is sealed so plaintext step content never leaves the machine on an E2E
+     * scratchpad.
+     */
+    recordSteps(invocationId: string, frames: StepFrame[], statusText?: string): Promise<boolean>;
+    postToInvocation(invocationId: string, body: {
+        content: string;
+        clientMessageId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    postToStream(streamId: string, body: {
+        content: string;
+        clientMessageId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    private postRouteOwnedMessage;
+    private routeUnavailableError;
+    /**
+     * The stream a control command acts on: its own in parallel mode, every stream
+     * (undefined) in serial mode, where one turn runs whichever stream it answers.
+     */
+    private controlStream;
+    private controlRoutes;
+    private routeForStream;
+    private openRoute;
+    /** Whether this session still holds the invocation open (not yet replied, timed out, or superseded). */
+    isInflight(invocationId: string): boolean;
+    /** Reset idle timeouts for every in-flight turn in a stream (a pending approval is a sign of life). */
+    keepAlive(streamId: string): void;
+    /**
+     * Put a call the runtime cannot make to the human on the stream and block on
+     * the answer. The card is opened over HTTP; the answer arrives on the bot
+     * plane (`decision:resolved`/`decision:cancelled`) with a `getDecision` poll
+     * on the socket backstop cadence as the missed-push insurance.
+     */
+    requestDecision(input: DecisionRequestInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<DecisionOutcome>;
+    /** Withdraw a decision this session opened (also settles a local awaiter through the push/poll). */
+    cancelDecision(decisionId: string): Promise<void>;
+    /**
+     * The question half of a sealed create body: the title, body and option
+     * labels travel inside the ciphertext, leaving only ids and tones for the
+     * server to validate an answer against. The AAD binds the seal to the stream
+     * the card is posted to, which on a thread is not the root the key hangs off,
+     * and to an id minted here because the seal needs it before the row exists.
+     */
+    private sealedDecisionQuestion;
+    /**
+     * The note the human attached, opened when it is sealed. A note that will not
+     * open settles the decision without one: the answer itself is readable either
+     * way, and losing the note beats stranding the turn on it.
+     */
+    private decisionNote;
+    private outcomeFor;
+    /** A `decision:resolved`/`decision:cancelled` push for a decision this session is awaiting. */
+    private handleDecisionPush;
+    private settleDecision;
+    private failDecision;
+    /** A pending decision is a sign of life for the turn that is blocked on it. */
+    private keepTurnAliveForDecisions;
+    /**
+     * (Re)arm the decision backstop, replacing any pending tick. The socket-up
+     * cadence is bounded by half the turn's idle timeout because this poll is
+     * also what keeps a turn blocked on an open card alive.
+     */
+    private scheduleDecisionPoll;
+    private stopDecisionPollWhenIdle;
+    /** Missed-push backstop: read every pending decision and settle the ones that moved. */
+    private pollPendingDecisions;
+    /** Teardown: nobody is left to answer, so no connector may keep awaiting one. */
+    /** Reject the matching awaiters and withdraw their cards, so no answerable card outlives its asker. */
+    private abandonPendingDecisions;
+    /** Queue timeout closure behind posts so in-flight output cannot be overtaken. */
+    private onReplyTimeout;
+    private runIdleTimeout;
+    private clearInflight;
+    /**
+     * A `bot:session_archived` push. Scoped to this session AND this root: a
+     * runtime that re-registered under a new session id, or a cold start that
+     * replaced an archived scratchpad with a fresh one, must not die to a stale
+     * event for the retired root.
+     */
+    private handleSessionArchived;
+    /** A `bot:session_restored` push: the server revived this session's link. */
+    private handleSessionRestored;
+    /**
+     * `bot:session_archived` is a one-shot push with no replay: a socket that was
+     * down when the archive landed never learns of it, and the runtime then holds
+     * a link to a dead scratchpad forever — taking its tmux window and worktree
+     * with it. Re-derive from the server on every poll tick and socket bootstrap.
+     */
+    private probeArchiveBackstop;
+    /**
+     * Detach effects. No more work can arrive, so fail any in-flight turn (its
+     * reply could no longer land), drop the link, and go offline — but the
+     * worktree survives until the grace expires.
+     */
+    private detachForArchive;
+    /** The grace expired with the scratchpad still archived: hand the connector its terminal wind-down. */
+    private windDownForArchive;
+    private startPoll;
+    private handleTransportDisconnected;
+    /** (Re)arm the poll timer. Replaces any pending tick so a state change can pull the next tick closer. */
+    private reschedulePoll;
+    private pollTick;
+    /**
+     * Socket up → slow backstop (pushes deliver work). Socket down → start at the
+     * configured fast cadence and double per empty tick up to the cap, so an
+     * active HTTP-only conversation stays snappy while an idle socketless session
+     * can't burn the edge-request quota. Claimed work resets the backoff.
+     */
+    private nextPollDelay;
+    private resetReconnectHandoff;
+    /**
+     * Hold a key for each sealed scratchpad this bot was granted, then advertise
+     * the keyring. Under the default policy the one key already covers them and
+     * this changes nothing; under the per-stream policy the key is minted here,
+     * and until presence carries it the owner has nothing to re-wrap to.
+     */
+    private keyGrantedStreams;
+    /**
+     * Give up the key held for a scratchpad this bot was revoked from, then
+     * re-advertise. The server has already deleted the wraps only that key could
+     * open, so holding it buys nothing — under the default policy there is no
+     * such key and the shared one stays, which is the point of one key per host.
+     */
+    private keyRevokedStream;
+    /**
+     * Push presence when the held keyring is no longer what the server was last
+     * told, and update the hello body so a reconnect re-announces the same set.
+     * A key the server has not registered is one no wrap can be addressed to, so
+     * this runs before the wraps that name it.
+     */
+    private advertiseKeyring;
+    private enqueuePresence;
+    /** Derive presence when this generation's queued write runs, not when queued. */
+    private syncPresence;
+    private enqueueOfflinePresence;
+    private publishPresence;
+    /** Never a reason to fail a presence write: the report is bookkeeping for a supervisor. */
+    private reportPresence;
+    private presenceBody;
+    private claimBody;
+    private replyDigest;
+    private summarize;
+}
+export {};