@cursor/bdk 0.2.1

package/dist/internal/session-engine.d.ts

@@ -0,0 +1,912 @@
+/**
+ * The session engine owns durable sessions and turn execution. A session is
+ * one Cursor agent conversation plus a materialized workspace, an event log,
+ * and channel bookkeeping (continuation keys, per-session channel state).
+ * Turns are executed by the Cursor SDK runner and their streaming updates
+ * are mapped onto the channel event vocabulary and dispatched to channel
+ * event handlers and hooks.
+ */
+import type { SDKCustomToolResult } from "@cursor/sdk";
+import type { Meter } from "@opentelemetry/api";
+import { SlackAskDedupeStore, SlackNudgeStore } from "../channels/slack/nudge-store.js";
+import { type AgentProject, type ApprovalDecision, type ArtifactListFilter, type ArtifactPage, type ArtifactRecord, type ArtifactsApi, type AuthContext, type CallToolOptions, type ChannelDefinition, type ChannelSession, type ConnectionTransport, type DiscoveredTool, type HostContext, type HttpChannelDefinition, type PendingApproval, type PendingAuth, type ReceiveInput, type SendMessageOptions, type SessionEvent, type SessionInfo, type SessionListSource, type SessionRecord, type SessionSummary, type ToolCallOutcome, type TurnOutcome } from "../types.js";
+import { type CloudAgentUsage } from "./cloud-turn-cost.js";
+import { type EventLogMemoryStats } from "./event-log.js";
+import { type HostPlatforms } from "./host-platforms.js";
+import { McpOauthOnDemandHub } from "./mcp-oauth-on-demand.js";
+import type { OtelCollector } from "./otel/collector.js";
+import type { AgentRunner } from "./sdk-runner.js";
+import { SessionStore } from "./session-store.js";
+import { StorageCoordinator } from "./storage-coordinator.js";
+import { type EstimateTurnCostFn } from "./turn-cost.js";
+import { TurnLeaseStore } from "./turn-lease-store.js";
+import { TurnOutbox } from "./turn-outbox.js";
+export declare const HTTP_CHANNEL_ID = "http";
+export { mergeChannelStateSkipNull } from "./channel-state.js";
+export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
+export declare class SessionBusyError extends Error {
+    constructor(sessionId: string);
+}
+/**
+ * Hosted enqueue-only admission could not coalesce into an active turn.
+ * Distinct from {@link SessionBusyError}: the caller asked not to start work.
+ */
+export declare class HostedEnqueueNotActiveError extends Error {
+    constructor(sessionId?: string);
+}
+export { SessionAuthError } from "./auth.js";
+export declare class UnknownChannelError extends Error {
+    constructor(channelId: string);
+}
+export declare class UnknownToolError extends Error {
+    readonly availableToolNames: string[];
+    constructor(toolName: string, availableToolNames: string[]);
+}
+export declare class ToolNotDirectlyCallableError extends Error {
+    constructor(toolName: string);
+}
+export declare class InvalidContinuationTokenError extends Error {
+    constructor(detail: string);
+}
+/**
+ * A session-bound direct call whose harness cwd cannot be materialized and
+ * whose effect is not read: a write tool may rely on ctx.workspaceDir being
+ * the real session workspace, so it fails typed instead of silently running
+ * in a scratch directory.
+ */
+export declare class WorkspaceUnavailableError extends Error {
+    constructor(toolName: string, cause: unknown);
+}
+export declare class ToolInputError extends Error {
+    constructor(args: {
+        toolName: string;
+        detail: string;
+    });
+}
+export declare class UnknownSessionError extends Error {
+    constructor(sessionId: string);
+}
+export declare class ApprovalNotFoundError extends Error {
+    constructor(sessionId: string, callId: string);
+}
+export declare class ApprovalInterruptedError extends Error {
+    constructor(sessionId: string, callId: string);
+}
+export declare class AuthNotFoundError extends Error {
+    constructor(sessionId: string, callId: string);
+}
+export declare class AuthInterruptedError extends Error {
+    constructor(sessionId: string, callId: string);
+}
+export interface SessionEngineOptions {
+    project: AgentProject;
+    stateRoot: string;
+    runner: AgentRunner;
+    logger?: (line: string) => void;
+    platforms?: HostPlatforms;
+    /**
+     * Test seam / override for cloud billed usage (`Agent.getUsage`). Used to
+     * backfill `turn.completed` rows that older engines persisted without
+     * usage/cost so the playground Trace tab can still show an estimate.
+     */
+    getCloudUsage?: (sdkAgentId: string) => Promise<CloudAgentUsage | undefined>;
+    /**
+     * Resolve turn cost via `POST /v1/models/estimate-cost`. Tests inject a
+     * stub; production uses billed usage events when an agent id is known.
+     */
+    estimateTurnCost?: EstimateTurnCostFn;
+    /** Process-level OTel collector; observe-only, never fatal. */
+    otel?: OtelCollector;
+    /** Process-level meter for {@link HostContext.otel}. Absent → no-op counters. */
+    otelMeter?: Meter;
+}
+/**
+ * A connection the serve host resolved once it was listening — a **peer**
+ * (`defineConnection({ agent })` mapped to the target agent's MCP endpoint)
+ * or the **Cursor account bridge** (`defineConnection({ cursorAccount })`
+ * mapped to the loopback bridge route). Local turns (and host-side MCP
+ * calls) use {@link localUrl}; cloud turns use {@link cloudUrl} when the
+ * serve host configured a public URL (peers and the account bridge).
+ */
+export interface EngineResolvedConnection {
+    /** MCP server name the model sees (the connection filename). */
+    name: string;
+    /** Loopback MCP URL, e.g. `http://127.0.0.1:3000/<slug>/v1/mcp`. */
+    localUrl: string;
+    /** Publicly reachable MCP URL for cloud turns, when configured. */
+    cloudUrl?: string;
+    /** Auth headers calls must present (host bearer / bridge secret). */
+    headers?: Record<string, string>;
+    /**
+     * When set, cloud turns must reach the account bridge via {@link cloudUrl}
+     * so the filter is enforced — omitting the bridge must not fail open to
+     * the account's broader native connector set.
+     */
+    accountServersFilter?: readonly string[];
+}
+export interface EngineSendOptions extends SendMessageOptions {
+    mode?: "chat" | "task";
+    /**
+     * Hosted v2 control-plane identity. Private host plumbing only: channel
+     * authors cannot choose a session id through the public SendMessageOptions.
+     */
+    hostedSessionId?: string;
+    /**
+     * Hosted active-guest enqueue: admit only by coalescing into an already
+     * running turn. Never creates a session or starts a turn. Private host
+     * plumbing — not part of public SendMessageOptions.
+     */
+    hostedEnqueueOnly?: boolean;
+}
+interface AdmitTurnOptions {
+    admission?: "preempt" | "coalesce";
+    sourceTs?: string;
+    /**
+     * When true, skip `clearCoalesced` on the preempt admit path. Used by
+     * coalesce drain so asks that arrived during drain are not wiped.
+     */
+    retainCoalesced?: boolean;
+    /** See {@link EngineSendOptions.hostedEnqueueOnly}. */
+    hostedEnqueueOnly?: boolean;
+}
+export declare class SessionEngine {
+    readonly project: AgentProject;
+    readonly stateRoot: string;
+    readonly sessions: SessionStore;
+    /** Durable Slack mid-turn nudges under `<stateRoot>/slack-nudges`. */
+    readonly nudgeStore: SlackNudgeStore;
+    /** Durable `channelId:ts` ask claims under `<stateRoot>/slack-asks`. */
+    readonly askDedupe: SlackAskDedupeStore;
+    /** Cross-process turn ownership under `<stateRoot>/turn-leases`. */
+    readonly turnLeases: TurnLeaseStore;
+    /** Messages for turns another server owns, under `<stateRoot>/outbox`. */
+    readonly outbox: TurnOutbox<AdmitTurnOptions>;
+    /**
+     * Runtime for `agent/storage.ts` (`defineStorage`), when
+     * authored. All durable state changes funnel through it (session
+     * records, event chunks); the eval run store attaches via
+     * {@link StorageCoordinator.evalRuns} at serve start.
+     */
+    readonly storage: StorageCoordinator | undefined;
+    /** In-flight lazy restores, deduped per channel + continuation key. */
+    private readonly restoreInFlight;
+    /** In-flight authored files → Agent Store syncs (see syncToCloudStore). */
+    private readonly cloudSyncs;
+    private readonly runner;
+    private readonly logger;
+    private readonly logs;
+    private readonly channelsById;
+    /** Sessions with a turn being admitted (before the run promise exists). */
+    private readonly pendingTurns;
+    private readonly activeTurns;
+    /**
+     * Sessions whose workspace a turn in this process has materialized. A
+     * session is busy from admit — before the governor slot and the turn's
+     * own materialize — so a read running alongside a turn consults this,
+     * not busy, to know whether the workspace is ready to be left alone.
+     */
+    private readonly materializedWorkspaces;
+    /** Context used by the cloud turn's HTTP MCP callbacks. */
+    private readonly activeToolContexts;
+    /**
+     * Tool call ids the host answered instead of running, per session.
+     *
+     * The mapper emits the result event from the harness's view of a finished
+     * call, which cannot tell an answered call from a real one — so the decision
+     * point records the id here and the mapper stamps the event from it.
+     * Registered only while a turn can invoke a tool.
+     */
+    private readonly stubbedCallIds;
+    /**
+     * Delivered-nudge count per session at the last tool boundary. The carrier
+     * drains out-of-process, so a growing count is how the engine learns a
+     * follow-up reached the agent.
+     */
+    private readonly deliveredNudges;
+    /** Aborts the in-flight turn per session so a follow-up can preempt it. */
+    private readonly turnAborts;
+    /** Serializes turn admission per session (latest follow-up wins). */
+    private readonly admissionChains;
+    /** Live turn snapshot so a coalesced Slack wake can repaint on this process. */
+    private readonly liveTurns;
+    /** FIFO turn slots under `concurrency.maxRunningTurns` (unlimited when unset). */
+    private readonly turnGovernor;
+    /**
+     * Per-session coalesce queue for `admission: "coalesce"` (Slack). Drained
+     * into one follow-up turn when the active turn finishes without interrupt.
+     */
+    private readonly coalesceQueues;
+    /**
+     * Sessions whose turn lifecycle is draining coalesced follow-ups. Counts as
+     * busy so inbound coalesce admits enqueue instead of racing `clearCoalesced`.
+     */
+    private readonly coalesceDrains;
+    private readonly lastOutcomes;
+    private readonly updateChains;
+    private readonly dispatchChains;
+    private readonly backgroundWork;
+    private readonly mcpHost;
+    private readonly platforms;
+    private readonly approvals;
+    private readonly auths;
+    private readonly oauthHub;
+    private probeCursorAccount;
+    private readonly otel;
+    private readonly otelHost;
+    private readonly stopMemoryTelemetry;
+    private reminderApi;
+    private evalsApi;
+    private readonly kvApi;
+    private readonly filesApi;
+    /** Engine-owned artifacts service behind every `ctx.artifacts` facade. */
+    private readonly artifactsStore;
+    /** Serve-time resolved connections (see {@link setResolvedConnections}). */
+    private resolvedConnections;
+    /** Direct server-tool HTTP MCP transport exposed only to cloud turns. */
+    private cloudServerToolsConnection;
+    /** Re-resolved after hosted v2 task binding writes the Cursor credential. */
+    private cloudServerToolsHeaders;
+    private readonly getCloudUsage;
+    private readonly estimateTurnCost;
+    /** Sessions whose completed turns are fully priced (no further backfill). */
+    private readonly cloudCostBackfillDone;
+    /** Deduped in-flight cloud cost backfills, keyed by session id. */
+    private readonly cloudCostBackfill;
+    /** Per-session FileSystem handle cache (not a tree snapshot). */
+    private readonly sessionRoots;
+    /** In-flight factory resolves, so the first turn and a racing callTool share one handle. */
+    private readonly sessionRootInflight;
+    /** Per-turn `unionFs({ "/": authored, "/tmp": tempFs() })`. Dropped at end of turn. */
+    private readonly turnRoots;
+    /** In-flight `prewarmSharedWorkspace`; first turn waits so it lands hot. */
+    private sharedWarm;
+    constructor(options: SessionEngineOptions);
+    /**
+     * Attach serve-time resolved connections (peers, Cursor account bridge).
+     * They join the per-turn SDK `mcpServers` map (loopback URL for local
+     * turns, `cloudUrl` for cloud turns) and the host-side registry
+     * (`ctx.host.mcp`, always loopback).
+     */
+    setResolvedConnections(connections: EngineResolvedConnection[]): void;
+    private authoredConnection;
+    setCloudServerToolsConnection(connection: ConnectionTransport, resolveHeaders?: () => Record<string, string> | undefined): void;
+    private currentCloudServerToolsConnection;
+    setMcpOauthCallbackUrl(url: string): void;
+    setCursorAccountAuthProbe(probe: (connection: string) => Promise<string | undefined>): void;
+    get oauthCallbackHub(): McpOauthOnDemandHub;
+    /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / files / otel / Slack nudges). */
+    get host(): HostContext;
+    /**
+     * Host services with `files` and `otel` bound to one session, so a relative
+     * path resolves to that session's scope and can never read another
+     * session's. Unbound (no session) keeps `host.files` usable for
+     * `{ scope: "deployment" }` and fails loudly on session-scoped calls.
+     */
+    private hostForSession;
+    /** Unbound `ctx.artifacts` facade (channel handlers, scratch tool calls). */
+    get artifacts(): ArtifactsApi;
+    /**
+     * Build one `ctx.artifacts` facade over the engine-owned artifacts
+     * service. With a `binding` (tools, hooks) `tag` auto-fills the bound
+     * session (and turn when known) and rejects a conflicting explicit
+     * `sessionId`; without one (channel handlers) callers may pass
+     * `sessionId` / `turnId` explicitly.
+     */
+    artifactsApi(binding?: {
+        sessionId: string;
+        turnId?: string;
+    }): ArtifactsApi;
+    /**
+     * Single tag funnel: upsert the row, then — for session-bound tags —
+     * append `artifact.tagged` through {@link appendEvent} so persistence
+     * flush and hook fan-out are inherited. Session-less tags skip the event.
+     * An unknown `sessionId` rejects before the row is written (appending to
+     * a session that was never materialized here would mint an orphan local
+     * event log, breaking the local-over-sink restore invariant).
+     */
+    private tagArtifact;
+    /**
+     * Install the Slack nudge carrier into a local session's harness cwd, so a
+     * follow-up that arrives mid-turn reaches the running agent at its next tool
+     * boundary instead of waiting for the boundary turn.
+     *
+     * Slack-only and local-only: the carrier is a Cursor hook in the workspace,
+     * and a cloud VM has neither the workspace nor the nudge store.
+     *
+     * The harness only reads these hooks when the workspace is its own git root;
+     * nested in an outer repo it reads that repo's instead and the carrier never
+     * runs, leaving follow-ups to drain at the turn boundary as before.
+     */
+    private materializeNudgeCarrier;
+    /**
+     * Report a mid-turn follow-up reaching the agent, as `nudge.delivered`.
+     *
+     * The workspace carrier drains `pending/` into `delivered/` out of process,
+     * so the engine watches the delivered count grow rather than the turn's own
+     * events. Counting rather than edge-detecting on "still queued" matters:
+     * the carrier runs at the same tool boundary this check does, so a nudge
+     * queued and drained between two readings is never seen as pending.
+     *
+     * Channels need this to move a live progress message below the follow-up —
+     * Slack cannot reorder messages.
+     */
+    private emitDeliveredNudges;
+    /**
+     * Record the thread's delivered count before the turn runs. Earlier turns
+     * leave their own records behind, so only growth from here is this turn's.
+     */
+    private baselineDeliveredNudges;
+    private readDeliveredNudges;
+    private slackNudgeHostApi;
+    /** Attach the serve-host reminder API (called from startServer). */
+    setReminders(api: HostContext["reminders"]): void;
+    /** Attach the serve-host playground evals API (called from startServer). */
+    setEvals(api: HostContext["evals"]): void;
+    /**
+     * Start or resume a session on a channel. When `continuationToken`
+     * addresses an existing session this is a follow-up turn; otherwise a new
+     * session is created (keyed by the provided token, or a fresh one).
+     *
+     * v2 (`/v2` selectors) refuses `continuationToken` and looks
+     * up `(agentId, cKey)` from a mailbox stamp or structured claim.
+     */
+    send(channelId: string, message: string, options?: EngineSendOptions): Promise<ChannelSession>;
+    /**
+     * Atomically validate and rotate an HTTP follow-up credential, then admit
+     * the message to its exact session without changing the owning channel key.
+     */
+    followUpHttp(sessionId: string, token: {
+        channelId: string;
+        key: string;
+    }, message: string): Promise<string | undefined>;
+    /** Whether a continuation token already maps to a session on this channel. */
+    hasContinuationSession(channelId: string, continuationToken: string): Promise<boolean>;
+    /** Look up a session as a channel-scoped handle. */
+    getChannelSession(channelId: string, sessionId: string): Promise<ChannelSession | null>;
+    /** Cross-channel hand-off (schedules and channel route handlers). */
+    receive(channel: ChannelDefinition | HttpChannelDefinition | string, input: ReceiveInput): Promise<ChannelSession>;
+    /** Fire-and-forget task session (schedules' markdown form). */
+    runTask(args: {
+        channelId: string;
+        prompt: string;
+        auth: AuthContext | null;
+        title?: string;
+    }): Promise<{
+        sessionId: string;
+        done: Promise<TurnOutcome>;
+    }>;
+    /**
+     * Repaint on the follow-up wake without retargeting the live turn.
+     * Persist already took the refresh; in-flight writes stay on the carrier ts.
+     */
+    private repaintOnCoalescedRefresh;
+    /**
+     * Admit a turn for `sessionId`.
+     *
+     * Default (`preempt`): a follow-up cancels the running turn and starts
+     * immediately (HTTP / MCP). With `admission: "coalesce"` (Slack), a busy
+     * session enqueues the message and returns without interrupting; the queue
+     * drains into one follow-up when the active turn finishes.
+     *
+     * Resolves to `true` when the message was coalesced (enqueued), `false`
+     * when a turn was started.
+     */
+    private startTurn;
+    /** Admit what other servers handed to this turn's holder. Never awaited by the lifecycle. */
+    private drainOutbox;
+    private enqueueCoalesced;
+    private clearCoalesced;
+    /**
+     * Drop queued follow-ups the nudge carrier already carried into the turn
+     * that just finished — the contract {@link SendMessageOptions.coalesceSourceTs}
+     * describes. Re-asking them would answer the same message twice.
+     *
+     * Items with no `sourceTs` cannot be matched and are kept.
+     */
+    private withoutNudgedFollowups;
+    /** Mark drained follow-ups delivered so the next turn's carrier skips them. */
+    private settleDrainedFollowups;
+    private formatCoalescedFollowups;
+    private drainCoalescedFollowups;
+    private steerIntoRunningTurn;
+    private admitTurn;
+    /**
+     * Cancel the turn in flight for `sessionId` (if any) and wait for it to
+     * settle, so its SDK run is terminal before the next turn's send. Safe to
+     * call when nothing is running.
+     */
+    private interruptActiveTurn;
+    /**
+     * Abort the in-flight turn without starting a follow-up. Returns whether
+     * a turn was active (or pending abort) when called. Also clears any
+     * coalesced follow-ups queued behind the session.
+     */
+    interrupt(sessionId: string): Promise<boolean>;
+    isContinuationBusy(channelId: string, continuationToken: string): Promise<boolean>;
+    /**
+     * Last agent-posted Slack message ts for warm `<slack_thread_delta>`, from
+     * the session's channel state when present.
+     */
+    getContinuationLastBotMessageTs(channelId: string, continuationToken: string): Promise<string | undefined>;
+    interruptContinuation(channelId: string, continuationToken: string): Promise<boolean>;
+    private hasRootOverride;
+    /**
+     * FileSystem for this turn or `callTool`. Authored `root` (static or
+     * factory) is cached per session when `cache` is set; unscoped
+     * `callTool` passes the invocation id and does not cache, so factories
+     * cannot share one tree across callers. A static handle is used as
+     * authored — every session sees that same object. Host-default agents
+     * get `localFileSystem` against the harness cwd — same path verbs as
+     * the Cursor SDK natives, always through the synthesized tools.
+     */
+    private resolveFileSystem;
+    private resolveAuthoredFileSystem;
+    private dropTurnFileSystem;
+    private prepareScratchToolInput;
+    private withTurnScratchTools;
+    private nativeFileSystemOutcome;
+    /**
+     * Local harness cwd for a session: per-send override, else the shared
+     * `agent.local.workspaceDir`, else `<agent.local.cwd>/<sessionId>`, else
+     * the durable session workspace.
+     */
+    harnessCwd(record: SessionRecord): string;
+    /**
+     * True when the harness cwd is a directory the session does not own — a
+     * per-send override (e.g. a PR worktree) or a workspace shared by every
+     * session. Agent scaffold has to stay out of those, so it lands in the
+     * durable session workspace and the instructions travel inline instead.
+     */
+    private hasBorrowedWorkspace;
+    /**
+     * Resolve the shared harness workspace during startup, so the first session
+     * is not the one that waits for it. Only possible with
+     * `local.workspaceDir`: every other layout gives a session its own cwd,
+     * which is unknowable until that session exists.
+     *
+     * Best effort — warming is an optimization, and a turn rebuilds on its own.
+     */
+    prewarmSharedWorkspace(): Promise<void>;
+    private warmSharedWorkspace;
+    /** Directory that receives AGENTS.md / skills / agent tools. */
+    private scaffoldDir;
+    private executeTurn;
+    /**
+     * Sync authored skills onto the Agent Store at `skills/<name>/…` (hosted)
+     * or `agent-serve/<agent>/skills/<name>/…` (personal-key local+cloud)
+     * before the first cloud prompt, so `--agent-store-skills-dir` and the
+     * first-turn S3 scan can discover them. False when the sync fails: the
+     * turn then runs without store skills rather than pointing discovery at
+     * paths that do not exist.
+     */
+    private ensureCloudSkillsSynced;
+    /**
+     * Sync `agent/sandbox/workspace/**` seeds onto the Agent Store at
+     * `workspace/…` (hosted) or `agent-serve/<agent>/workspace/…`
+     * (personal-key local+cloud) before the first cloud prompt, which names
+     * the mounted directory (see buildCloudWorkspaceSection).
+     */
+    private ensureCloudWorkspaceSynced;
+    /**
+     * Replace this session's store prefix with the pending `workspaceFiles`.
+     * Undefined when the write did not land; the prompt must not name the
+     * mount, matching ensureCloudWorkspaceSynced.
+     */
+    private syncCloudSessionWorkspaceFiles;
+    private wipeCloudSessionWorkspace;
+    private clearPendingWorkspaceFiles;
+    /**
+     * With files authored, every first cloud turn re-copies the authored
+     * bytes and the memo only dedupes concurrent first turns. The mount is
+     * writable from cloud sessions, so a once-per-process copy would let one
+     * session's edits masquerade as agent definition for every later session
+     * until the engine restarts; re-syncing keeps the store true to discovery
+     * the same way local materialization always rewrites skills. Without
+     * authored files the sync is best-effort stale cleanup and one attempt
+     * per process is enough, success or not — a deployment without the files
+     * surface must not fail and log on every new session for a feature it
+     * does not use.
+     */
+    private syncToCloudStore;
+    /**
+     * Hosted deployments own the deployment store. Local `serve`/`run` with
+     * a personal API key writes into the USER store under `agent-serve/`.
+     * A persistent deployment's version container has no cloud store at all:
+     * its state directory is the durable copy, and its service-account key
+     * must not be mistaken for a personal one.
+     */
+    private cloudStore;
+    private buildTurnRequest;
+    /**
+     * Connection names a cloud turn can only reach through the host connection
+     * bridge on the tool MCP endpoint: filtered account connections without a
+     * public bridge URL, and host-OAuth connections whose tokens live on this
+     * host.
+     */
+    cloudBridgeableConnectionNames(): string[];
+    /**
+     * True when cloud turns reach `name` through the host connection bridge —
+     * the gate the tool MCP endpoint applies before forwarding a bridge
+     * request to `host.mcp`, so arbitrary names stay unreachable from a VM.
+     */
+    isCloudBridgedConnection(name: string): boolean;
+    /**
+     * Session-bound transport for one host-bridged connection: the tool MCP
+     * endpoint with the connection named, so `tools/list` / `tools/call`
+     * forward to the host-side client (`host.mcp`) where the credential —
+     * account bridge secret or host OAuth token — actually lives.
+     */
+    private cloudBridgeTransport;
+    /**
+     * Authored + resolved MCP servers for a turn. Skips advertised
+     * connections (those surface as named server tools). On cloud turns,
+     * connections whose credential lives on this host — filtered account
+     * connections without a public bridge URL, host-OAuth servers — mount
+     * as host connection bridges over the tool MCP endpoint instead of
+     * being omitted or failing the turn closed.
+     */
+    private buildMcpServers;
+    /**
+     * True when a connection with per-session `auth` attaches to the model
+     * (not advertised). These turns set
+     * {@link RunnerTurnRequest.perSendMcpServers} so the evaluated headers
+     * ride every send instead of being pinned on the cached agent handle.
+     */
+    private hasAttachedAuthedConnections;
+    /**
+     * Evaluate per-session connection auth (`defineConnection({ auth })`)
+     * for connections that attach to the model this turn. Advertised
+     * connections evaluate their own auth inside the tool synthesis path. A
+     * callback that throws fails the turn — a turn never silently runs
+     * without the connection's identity.
+     */
+    private evaluateConnectionAuth;
+    private buildCustomTools;
+    /**
+     * True while `sessionId` has a turn in flight. The host connection bridge
+     * applies this before forwarding to `host.mcp` — the same window
+     * {@link callActiveServerTool} enforces for authored server tools — so an
+     * endpoint credential that outlives a turn (e.g. in a VM's MCP config)
+     * cannot reach host-credentialed connectors between turns.
+     */
+    hasActiveTurn(sessionId: string): boolean;
+    callActiveServerTool(sessionId: string, toolName: string, input: unknown): Promise<SDKCustomToolResult>;
+    private executeServerTool;
+    /**
+     * Bind outbound inject (Factory / Cursor API `traceparent`) to the
+     * turn span for the whole harness run. Host files / VFS RPCs happen
+     * here, not under `runInCall`. No-op when OTel is off.
+     */
+    private runTurnExecute;
+    /**
+     * Bind outbound inject (Factory / Cursor API `traceparent`) to the
+     * tool span. No-op when OTel is off.
+     */
+    private runToolExecute;
+    /**
+     * Park a server-tool call until a human approves or denies. Emits
+     * `action.approval_requested` / `action.approval_resolved` on the
+     * held turn log so the playground and stream see the gate.
+     */
+    private parkForApproval;
+    private clearPendingApprovals;
+    /** Pending tool approvals for a session (live waiters ∪ persisted). */
+    listPendingApprovals(sessionId: string): Promise<PendingApproval[]>;
+    /**
+     * Approve or deny a parked server-tool call. Unblocks the in-flight
+     * SDK custom-tool callback for the same `callId`.
+     *
+     * Pass `asSessionOwner: true` only from an explicit host bridge (e.g. `--dev`
+     * playground resolving a Slack-owned parked tool). Ownership is checked
+     * against the stored session principal; `by` still records the clicker.
+     */
+    resolveApproval(sessionId: string, callId: string, decision: ApprovalDecision, auth: AuthContext | null, options?: {
+        asSessionOwner?: boolean;
+    }): Promise<PendingApproval>;
+    private removePendingApproval;
+    private wrapMcp;
+    private advertiseMcp;
+    private withMcpListAuth;
+    private withMcpAuth;
+    private parkAndRetryMcp;
+    private persistHostedMcpOauth;
+    private mintAuthUrl;
+    private parkForAuth;
+    private clearPendingAuths;
+    listPendingAuths(sessionId: string): Promise<PendingAuth[]>;
+    resolveAuth(sessionId: string, callId: string, decision: ApprovalDecision, auth: AuthContext | null, options?: {
+        asSessionOwner?: boolean;
+    }): Promise<PendingAuth>;
+    private removePendingAuth;
+    runWithMcpPark<T>(sessionId: string, toolName: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Call an authored server tool deterministically: validate `input`
+     * against the tool's schema (zod schemas validate and transform; plain
+     * JSON Schema inputs pass through unvalidated, matching the model path),
+     * run `execute` in-process, and return the normalized result exactly as
+     * the model would receive it.
+     *
+     * With `options.sessionId` the tool runs inside that session (its info
+     * and materialized workspace) and the call is recorded on the session's
+     * event stream as `actions.requested` / `action.result` under a
+     * per-call `turnId` (the call id), so it shows up in trajectories.
+     * While a model turn is running, a read-effect call runs alongside it
+     * (the turn's workspace is read as-is) and a write-effect call is
+     * rejected with {@link SessionBusyError}. Without a session, the tool
+     * runs against an **ephemeral** scratch
+     * workspace under `<stateRoot>/tool-calls/<callId>` (materialized with
+     * seed files, removed after the call returns).
+     *
+     * Throws {@link UnknownToolError}, {@link ToolNotDirectlyCallableError},
+     * {@link ToolInputError}, or {@link UnknownSessionError} before the tool
+     * body runs; a tool body that throws is reported as an `isError` outcome
+     * with the same `{ content, isError }` envelope the model would see, not
+     * an exception.
+     */
+    /**
+     * The session identity a direct call (or catalog listing) runs under:
+     * an explicit sessionId, a continuation token resolved to a live (or
+     * restorable) session with the same owner/busy checks a sessionId call
+     * gets, or — when neither maps to a session — a synthetic identity
+     * carrying the token's channel id and continuation key so binding
+     * resolvers (e.g. VFS mounts) can still serve the call.
+     */
+    private resolveDirectCallIdentity;
+    /**
+     * The live tool catalog for one session identity: authored server tools
+     * plus the advertised passthroughs a turn under the same identity would
+     * see, under their model-facing names. A connection whose listing fails
+     * is skipped and reported in `connectionErrors` — the inspection surface
+     * degrades legibly instead of hiding every other tool behind one broken
+     * connector.
+     */
+    listCatalogTools(options?: Pick<CallToolOptions, "auth" | "sessionId" | "continuationToken">): Promise<{
+        tools: DiscoveredTool[];
+        connectionErrors: Array<{
+            connection: string;
+            message: string;
+        }>;
+    }>;
+    /**
+     * One catalog tool by name. Authored tools are local — their schema does
+     * not depend on session identity or connection listings — so a detail
+     * fetch for `ls` must not wait on every advertised MCP server.
+     */
+    describeCatalogTool(toolName: string, options?: Pick<CallToolOptions, "auth" | "sessionId" | "continuationToken">): Promise<{
+        tool: DiscoveredTool;
+    } | {
+        tool: undefined;
+        availableTools: string[];
+        connectionErrors: Array<{
+            connection: string;
+            message: string;
+        }>;
+    }>;
+    callTool(toolName: string, input?: unknown, options?: CallToolOptions): Promise<ToolCallOutcome>;
+    /**
+     * Whether the host answers a bridged MCP call, for the cloud host bridge —
+     * the one tool path that does not reach {@link executeServerTool}, because
+     * it forwards to `host.mcp` instead of invoking a tool body.
+     *
+     * A frozen session refuses forward-looking time args here even when it is
+     * not a dry run. A bridged tool carries no `defineTool`, so it declares no
+     * effect, and the policy reads an undeclared tool as a write. In a dry run
+     * that answers bridged reads too; resolving effects from a server's own
+     * listing is the next unit's work.
+     */
+    bridgedCallAnswer(args: {
+        sessionId: string;
+        connectionName: string;
+        toolName: string;
+        input?: unknown;
+    }): Promise<{
+        answered: true;
+        result: SDKCustomToolResult;
+    } | {
+        answered: false;
+    }>;
+    /**
+     * The bounded annotations a connection's listing declares for one tool, or
+     * undefined when the tool is unlisted, unannotated, or the listing fails —
+     * all of which the policy reads as unclassified, the refusing state.
+     */
+    private bridgedToolInfo;
+    private appendEvent;
+    private queueDispatch;
+    private dispatchEvent;
+    private channelEventHandlersFor;
+    /**
+     * Wait until everything this session has already emitted is durably
+     * mirrored: its dispatch chain first (the chain's tail runs the turn-end
+     * storage flush, so the record carries the boundary event's handler
+     * mutations), then the storage delivery queue. Hosted v2 awaits this
+     * before the execution reply — the pod can be parked the moment the
+     * reply lands, and an unflushed session record would strand a
+     * conversation whose blobs persisted but whose record (which selects the
+     * conversation to hydrate) never reached the sink. No-op without a
+     * storage mirror.
+     *
+     * Under a debounced event policy the turn-end flush is a timer, not the
+     * chain's tail, so flush explicitly before waiting on the queue; a no-op
+     * when the chain already flushed.
+     */
+    drainSessionDurability(sessionId: string): Promise<void>;
+    waitForCompletion(sessionId: string): Promise<TurnOutcome>;
+    /**
+     * Sessions visible to `caller`, newest first (`GET /v1/sessions`).
+     * Callers only see sessions whose stored principal matches — except when
+     * `includeAll` is set (dev mode), where the listing becomes a full
+     * observability surface across every principal (channel-driven runs,
+     * schedule/task sessions, other callers). The route auth chain still
+     * gates who may call this at all.
+     *
+     * When the project uses `cursorHostedStorage`, prefers durable Bugbot rows
+     * (merged with any newer local records not flushed yet). Falls back to the
+     * local `--state-root` store when the sink is unavailable.
+     */
+    listSessions(caller: AuthContext | null, options?: {
+        includeAll?: boolean;
+    }): Promise<SessionSummary[]>;
+    /**
+     * One artifacts page for `GET /v1/artifacts`, newest-updated first.
+     * Without `includeAll`, the sessions-list ownership rule applies — only
+     * artifacts tagged on a session whose principal matches the caller — as
+     * a predicate inside the page scan, so visibility never forces a wider
+     * read than the page itself. Session-less artifacts are agent-scoped and
+     * visible only with `includeAll`.
+     */
+    pageArtifacts(caller: AuthContext | null, options?: {
+        includeAll?: boolean;
+        filter?: ArtifactListFilter;
+        limit?: number;
+        cursor?: string;
+    }): Promise<ArtifactPage>;
+    /**
+     * One artifact's file/blob payload for `GET /v1/artifacts/:id/content`.
+     * Same visibility rule as {@link listArtifacts}. Undefined when the
+     * artifact is missing, invisible to the caller, or carries no payload.
+     */
+    getArtifactContent(caller: AuthContext | null, id: string, options?: {
+        includeAll?: boolean;
+    }): Promise<{
+        record: ArtifactRecord;
+        body: Uint8Array;
+    } | undefined>;
+    private ownedSessionIds;
+    /**
+     * Same as {@link listSessions}, plus which store answered
+     * (`cursor-hosted` = durable DB via the control-plane proxy; `local` =
+     * `--state-root`).
+     */
+    listSessionsWithSource(caller: AuthContext | null, options?: {
+        includeAll?: boolean;
+    }): Promise<{
+        sessions: SessionSummary[];
+        source: SessionListSource;
+    }>;
+    /**
+     * The single newest session visible to `caller` (`GET /v1/sessions?latest=1`).
+     *
+     * Short-circuits the full listing: the local store already holds every
+     * session this host created plus the startup bulk restore, so the common
+     * case answers from memory without a sink round trip. Only when the local
+     * store has nothing for the caller (fresh host, `restore: "off"`) does it
+     * ask the sink — for a bounded newest-written window when the backend
+     * can order by write time, else the full list. A session written by
+     * another replica moments ago can lose to a local one; callers that need
+     * the exact newest row should use the full listing.
+     */
+    latestSessionWithSource(caller: AuthContext | null, options?: {
+        includeAll?: boolean;
+    }): Promise<{
+        sessions: SessionSummary[];
+        source: SessionListSource;
+    }>;
+    /**
+     * Durable sink rows plus local records (local wins on the same id when
+     * newer — covers debounce windows that have not flushed yet). Newest
+     * `updatedAt` first.
+     */
+    private mergeStoredAndLocalSessions;
+    private summarizeSessionRecords;
+    eventStream(sessionId: string, startIndex?: number): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Append an assistant message to a session transcript without a model turn
+     * and without a user `message.received` bubble. Used by host-driven channel
+     * tasks (e.g. webhook stages) to publish a final summary.
+     */
+    emitAssistantMessage(sessionId: string, text: string): Promise<void>;
+    /**
+     * Billed/catalog cost for a session. Powers playground, traces, and
+     * `agent-sdk cost` via `GET /v1/session/:id/cost`.
+     */
+    sessionCost(sessionId: string): Promise<{
+        sessionId: string;
+        source: "usage" | "catalog" | "unavailable";
+        cost: {
+            rawCostCents: number;
+            chargedCents: number;
+        };
+        costUsd: number;
+        rawCostUsd: number;
+        model?: string;
+    }>;
+    /** Snapshot of recorded events (for download / offline trace). */
+    listEvents(sessionId: string, startIndex?: number, options?: {
+        backfillCloudCost?: boolean;
+    }): Promise<SessionEvent[]>;
+    /**
+     * Historical cloud turns may lack usage/cost on `turn.completed` (pre-0.1.29
+     * engines, or getUsage still zero at turn end). Fill them from billed usage
+     * before the playground replays the stream so Trace can show cost.
+     */
+    private backfillCloudTurnCosts;
+    private runCloudTurnCostBackfill;
+    setContinuationToken(sessionId: string, token: string | null): Promise<void>;
+    isTurnRunning(sessionId: string): boolean;
+    sessionInfo(record: SessionRecord): SessionInfo;
+    private channelSession;
+    private resolveChannelId;
+    private initialChannelState;
+    /** Serialized, immutable record updates (latest-wins per session). */
+    private updateRecord;
+    /**
+     * Restore sessions from the authored storage sink. Called once at
+     * serve start, before channels accept traffic: any persisted session
+     * missing from the local `--state-root` is materialized there — events
+     * as `events.ndjson`, record as `session.json` — after which every
+     * existing read path (continuation lookup, event replay/streams) works
+     * unchanged. Local state always wins over the sink, so restarts on the
+     * same host are no-ops.
+     *
+     * Failures are logged and skipped; a broken store (including rows that
+     * violate the SessionRecord shape) never blocks serve start.
+     */
+    restoreStoredSessions(): Promise<void>;
+    private runBulkRestore;
+    /**
+     * Local session lookup with lazy restore by session id.
+     *
+     * `GET /v1/sessions` (cursor-hosted) can list durable rows that were not
+     * bulk-restored into `--state-root` (restore caps, `restore: "off"`, or
+     * eval Open-trace by id). Events/stream/follow-up must materialize that
+     * one session before answering, or the playground shows an empty timeline
+     * after redeploy.
+     */
+    getOrRestoreSession(sessionId: string): Promise<SessionRecord | undefined>;
+    /**
+     * Lazy restore: a continuation lookup missed locally, so ask the sink
+     * for that one session and materialize it before resuming. Disk grows
+     * with sessions that are actually resumed, not with history.
+     *
+     * Concurrent misses for the same key (webhook redeliveries, retries)
+     * share one in-flight restore — a second materialization racing the
+     * first resumed turn could truncate events the turn already appended.
+     * Sink errors propagate and fail the send (see
+     * {@link StorageCoordinator.getSessionByContinuation}).
+     */
+    private restoreSessionByContinuation;
+    private restoreSessionById;
+    private loadAndMaterializeByContinuation;
+    private loadAndMaterializeById;
+    private materializeRestoredRecord;
+    /**
+     * Write one restored session to the local state root. Events land on
+     * disk before the record: a session becomes visible (and addressable via
+     * its continuation key) only with its full stream in place, and the
+     * lazily opened event log hydrates from this file.
+     */
+    private materializeSession;
+    trackBackground(promise: Promise<unknown>): void;
+    /** In-process event-log residency (OOM-suspect cache vs durable count). */
+    eventLogMemoryStats(): EventLogMemoryStats;
+    /** Drain running turns, dispatches, and pending writes, then dispose. */
+    close(): Promise<void>;
+}
+/**
+ * Restore-time turn-id fence: the durable record's `turnCount` may lag the
+ * event stream, and the next turn's id is `turn_${turnCount + 1}`, so take
+ * the highest `turn_<n>` the stream already recorded when it is ahead.
+ */
+export declare function withTurnCountClampedToEvents(record: SessionRecord, events: readonly SessionEvent[]): SessionRecord;
+//# sourceMappingURL=session-engine.d.ts.map