@cursor/bdk 0.2.1

package/dist/internal/session-engine.js

@@ -0,0 +1,4493 @@
+/**
+ * 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.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { AsyncLocalStorage } from "node:async_hooks";
+import { access, mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { SLACK_CHANNEL_ID } from "../channels/slack/constants.js";
+import { materializeSlackNudgeCarrier } from "../channels/slack/nudge-carrier.js";
+import { SlackAskDedupeStore, SlackNudgeStore } from "../channels/slack/nudge-store.js";
+import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
+import { AGENT_SERVE_USER_STORE_FILES_SOURCE_ID, agentStoreKeys, DEPLOYMENT_STORE_MOUNT_PATH, USER_STORE_MOUNT_PATH, } from "../files.js";
+import { cursorHostedFiles, isCursorHostedFilesAvailable, isCursorUserStoreFilesAvailable, } from "../files-backends/cursor-hosted.js";
+import { isFileSystemToolAlias, isMutatingFileSystemTool, localFileSystem, resolveFileSystemTools, resolveHostHarnessToolOptions, tempFs, unionFs, writeWorkspaceFilesToRoot, } from "../filesystem.js";
+import { storageKeysForArchitecture } from "../storage.js";
+import { DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, isCursorAccountTransport, isHostOauthConnectionTransport, isSymbolicConnectionTransport, } from "../types.js";
+import { resolveAdvertisedTools } from "./advertise-tools.js";
+import { ApprovalGate } from "./approval-gate.js";
+import { ArtifactsStore } from "./artifacts-store.js";
+import { assertTimeArgs, normalizeAsOf, schemaTimeWindowKeys, sessionClock } from "./as-of.js";
+import { SessionAuthError, samePrincipal } from "./auth.js";
+import { mergeChannelStateMutation, mergeChannelStateSkipNull } from "./channel-state.js";
+import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
+import { applyCloudUsageToEvents, cloudSdkAgentIdFromEvents, isUnpricedCompletedTurn, mapSdkTokenUsage, } from "./cloud-turn-cost.js";
+import { applyAgentContinuationDefaults, channelContinuationIdentity, httpContinuationIdentity, } from "./continuation-channel.js";
+import { continuationSource, resolveV2Key, V2EngineError } from "./continuation-identity.js";
+import { describeError, describeErrorCode } from "./describe-error.js";
+import { isDevMode } from "./dev-mode.js";
+import { EventLogStore } from "./event-log.js";
+import { TurnEventMapper } from "./event-mapper.js";
+import { applyWebScratchUpdate, ingestHostAgentToolsScratch, remapScratchPaths, } from "./filesystem/scratch.js";
+import { fileSystemTool, hostFileToolsFromAuthored, rootFileToolsFromAuthored, synthesizeFileSystemTools, } from "./filesystem/tools.js";
+import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
+import { createHostFilesApi } from "./host-files.js";
+import { createHostKvApi } from "./host-kv.js";
+import { createHostOtelApi } from "./host-otel.js";
+import { createHostPlatforms, createHostSlackClient, } from "./host-platforms.js";
+import { HostedAdmissionLocalSendError, isDuringHostedAdmission, } from "./hosted-admission-context.js";
+import { hostedSessionResumeKey } from "./hosted-catch-protocol.js";
+import { formatContinuationToken, newContinuationKey, newSessionId, newToolCallId, parseContinuationToken, } from "./ids.js";
+import { validateToolInput } from "./json-schema.js";
+import { isMcpNeedsAuthError, McpHost } from "./mcp-host.js";
+import { McpOauthOnDemandHub } from "./mcp-oauth-on-demand.js";
+import { shouldStartProcessMemoryTelemetry, startProcessMemoryTelemetry, } from "./process-memory-telemetry.js";
+import { buildSessionContextBlock, SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
+import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
+import { sessionExternalLinks } from "./session-links.js";
+import { SessionStore } from "./session-store.js";
+import { syncSkillsToStore } from "./skills-sync.js";
+import { steeringEnabled } from "./steering.js";
+import { StorageCoordinator, isTurnBoundaryEvent } from "./storage-coordinator.js";
+import { decideToolCall, directCallEffect } from "./tool-policy.js";
+import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
+import { estimateTurnCostFromApi, roundCostUsd } from "./turn-cost.js";
+import { TurnGovernor } from "./turn-governor.js";
+import { TurnLeaseStore } from "./turn-lease-store.js";
+import { TurnOutbox } from "./turn-outbox.js";
+import { resolveAgentV2Hosting } from "./v2-hosting.js";
+import { buildAgentsMdContent, buildCloudMemorySection, buildCloudSessionWorkspaceSection, buildCloudWorkspaceSection, ensureOwnGitRoot, isNestedInGitRepo, materializeWorkspace, SERVER_TOOLS_MCP_SERVER_NAME, } from "./workspace.js";
+import { syncSessionWorkspaceFiles, syncWorkspaceToStore, WorkspaceFileRefusal, wipeSessionWorkspace, } from "./workspace-sync.js";
+export const HTTP_CHANNEL_ID = "http";
+export { mergeChannelStateSkipNull } from "./channel-state.js";
+export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
+export class SessionBusyError extends Error {
+    constructor(sessionId) {
+        super(`Session ${sessionId} already has a running turn; wait for session.waiting before sending a follow-up`);
+        this.name = "SessionBusyError";
+    }
+}
+/**
+ * Hosted enqueue-only admission could not coalesce into an active turn.
+ * Distinct from {@link SessionBusyError}: the caller asked not to start work.
+ */
+export class HostedEnqueueNotActiveError extends Error {
+    constructor(sessionId) {
+        super(sessionId === undefined
+            ? "Hosted enqueue requires an active accepting session"
+            : `Hosted enqueue requires an active turn on session ${sessionId}`);
+        this.name = "HostedEnqueueNotActiveError";
+    }
+}
+// Defined in auth.js (HTTP/session-store callers import it without this
+// module); re-exported here because this is its historical public home.
+export { SessionAuthError } from "./auth.js";
+export class UnknownChannelError extends Error {
+    constructor(channelId) {
+        super(`Unknown channel "${channelId}"`);
+        this.name = "UnknownChannelError";
+    }
+}
+export class UnknownToolError extends Error {
+    constructor(toolName, availableToolNames) {
+        super(`Unknown tool "${toolName}"`);
+        this.availableToolNames = availableToolNames;
+        this.name = "UnknownToolError";
+    }
+}
+export class ToolNotDirectlyCallableError extends Error {
+    constructor(toolName) {
+        super(`Tool "${toolName}" runs in the agent environment (execution: "agent") and cannot be called directly on the host`);
+        this.name = "ToolNotDirectlyCallableError";
+    }
+}
+export class InvalidContinuationTokenError extends Error {
+    constructor(detail) {
+        super(`Invalid continuation token: ${detail}`);
+        this.name = "InvalidContinuationTokenError";
+    }
+}
+/**
+ * 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 class WorkspaceUnavailableError extends Error {
+    constructor(toolName, cause) {
+        super(`Session workspace unavailable for tool "${toolName}": ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "WorkspaceUnavailableError";
+    }
+}
+export class ToolInputError extends Error {
+    constructor(args) {
+        super(`Invalid input for tool "${args.toolName}": ${args.detail}`);
+        this.name = "ToolInputError";
+    }
+}
+export class UnknownSessionError extends Error {
+    constructor(sessionId) {
+        super(`Unknown session ${sessionId}`);
+        this.name = "UnknownSessionError";
+    }
+}
+export class ApprovalNotFoundError extends Error {
+    constructor(sessionId, callId) {
+        super(`No pending approval for session ${sessionId} call ${callId}`);
+        this.name = "ApprovalNotFoundError";
+    }
+}
+export class ApprovalInterruptedError extends Error {
+    constructor(sessionId, callId) {
+        super(`Approval for session ${sessionId} call ${callId} is no longer live (host may have restarted while the tool was parked)`);
+        this.name = "ApprovalInterruptedError";
+    }
+}
+export class AuthNotFoundError extends Error {
+    constructor(sessionId, callId) {
+        super(`No pending MCP auth for session ${sessionId} call ${callId}`);
+        this.name = "AuthNotFoundError";
+    }
+}
+export class AuthInterruptedError extends Error {
+    constructor(sessionId, callId) {
+        super(`MCP auth for session ${sessionId} call ${callId} is no longer live (host may have restarted while the tool was parked)`);
+        this.name = "AuthInterruptedError";
+    }
+}
+const mcpAuthAls = new AsyncLocalStorage();
+/** Marker that we `git init`'d this shared harness so scaffold is ours to write. */
+const OWNED_HARNESS = join(".agent-serve", "owned-harness");
+function pathExists(path) {
+    return access(path).then(() => true, () => false);
+}
+/**
+ * Nested dirs get their own git root so the harness does not ripwalk the
+ * enclosing checkout. A real `workspaceDir` checkout (already a git root)
+ * is left alone.
+ */
+function ownSharedHarness(dir) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (yield pathExists(join(dir, OWNED_HARNESS))) {
+            return true;
+        }
+        if (!(yield isNestedInGitRepo(dir))) {
+            return false;
+        }
+        yield ensureOwnGitRoot(dir);
+        if (yield isNestedInGitRepo(dir)) {
+            return false;
+        }
+        yield mkdir(join(dir, ".agent-serve"), { recursive: true });
+        yield writeFile(join(dir, OWNED_HARNESS), "");
+        return true;
+    });
+}
+export class SessionEngine {
+    constructor(options) {
+        var _a, _b, _c, _d, _e;
+        /** In-flight lazy restores, deduped per channel + continuation key. */
+        this.restoreInFlight = new Map();
+        /** In-flight authored files → Agent Store syncs (see syncToCloudStore). */
+        this.cloudSyncs = new Map();
+        this.channelsById = new Map();
+        /** Sessions with a turn being admitted (before the run promise exists). */
+        this.pendingTurns = new Set();
+        this.activeTurns = new Map();
+        /**
+         * 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.
+         */
+        this.materializedWorkspaces = new Set();
+        /** Context used by the cloud turn's HTTP MCP callbacks. */
+        this.activeToolContexts = new Map();
+        /**
+         * 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.
+         */
+        this.stubbedCallIds = new Map();
+        /**
+         * 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.
+         */
+        this.deliveredNudges = new Map();
+        /** Aborts the in-flight turn per session so a follow-up can preempt it. */
+        this.turnAborts = new Map();
+        /** Serializes turn admission per session (latest follow-up wins). */
+        this.admissionChains = new Map();
+        /** Live turn snapshot so a coalesced Slack wake can repaint on this process. */
+        this.liveTurns = new Map();
+        /**
+         * Per-session coalesce queue for `admission: "coalesce"` (Slack). Drained
+         * into one follow-up turn when the active turn finishes without interrupt.
+         */
+        this.coalesceQueues = new Map();
+        /**
+         * Sessions whose turn lifecycle is draining coalesced follow-ups. Counts as
+         * busy so inbound coalesce admits enqueue instead of racing `clearCoalesced`.
+         */
+        this.coalesceDrains = new Map();
+        this.lastOutcomes = new Map();
+        this.updateChains = new Map();
+        this.dispatchChains = new Map();
+        this.backgroundWork = new Set();
+        this.approvals = new ApprovalGate();
+        this.auths = new ApprovalGate();
+        this.oauthHub = new McpOauthOnDemandHub();
+        /** Serve-time resolved connections (see {@link setResolvedConnections}). */
+        this.resolvedConnections = [];
+        /** Sessions whose completed turns are fully priced (no further backfill). */
+        this.cloudCostBackfillDone = new Set();
+        /** Deduped in-flight cloud cost backfills, keyed by session id. */
+        this.cloudCostBackfill = new Map();
+        /** Per-session FileSystem handle cache (not a tree snapshot). */
+        this.sessionRoots = new Map();
+        /** In-flight factory resolves, so the first turn and a racing callTool share one handle. */
+        this.sessionRootInflight = new Map();
+        /** Per-turn `unionFs({ "/": authored, "/tmp": tempFs() })`. Dropped at end of turn. */
+        this.turnRoots = new Map();
+        this.project = options.project;
+        applyAgentContinuationDefaults(this.project);
+        this.stateRoot = options.stateRoot;
+        this.runner = options.runner;
+        this.logger = (_a = options.logger) !== null && _a !== void 0 ? _a : (() => { });
+        this.getCloudUsage = (_b = options.getCloudUsage) !== null && _b !== void 0 ? _b : defaultGetCloudUsage;
+        this.estimateTurnCost = (_c = options.estimateTurnCost) !== null && _c !== void 0 ? _c : estimateTurnCostFromApi;
+        this.otel = options.otel;
+        this.otelHost = createHostOtelApi({
+            agentName: options.project.name,
+            meter: options.otelMeter,
+            collector: options.otel,
+        });
+        this.turnGovernor = new TurnGovernor(options.project.agent.concurrency);
+        this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
+        this.nudgeStore = new SlackNudgeStore(join(options.stateRoot, "slack-nudges"));
+        this.askDedupe = new SlackAskDedupeStore(join(options.stateRoot, "slack-asks"));
+        this.turnLeases = new TurnLeaseStore(join(options.stateRoot, "turn-leases"));
+        this.outbox = new TurnOutbox(join(options.stateRoot, "outbox"));
+        this.logs = new EventLogStore(sessionId => this.sessions.eventFilePath(sessionId), (sessionId, error) => this.logger(`[agent-sdk] failed to persist events for ${sessionId}: ${describeError(error)}`));
+        // Framework session state (records, event chunks, continuations) is
+        // mirrored to whatever this selects; see framework-storage-selection.ts
+        // for why the choice does not belong to the agent author.
+        const frameworkStorage = selectFrameworkStorageDefinition({
+            authored: options.project.storage,
+            architecture: options.project.agent.architecture,
+        });
+        this.storage =
+            frameworkStorage === undefined
+                ? undefined
+                : new StorageCoordinator({
+                    definition: frameworkStorage,
+                    agentName: options.project.name,
+                    projectRoot: options.project.rootDir,
+                    logger: this.logger,
+                    keys: storageKeysForArchitecture(options.project.agent.architecture),
+                });
+        this.kvApi = createHostKvApi(Object.assign({ agentName: options.project.name, stateRoot: options.stateRoot }, (this.storage === undefined ? {} : { storage: this.storage })));
+        const v2Hosting = resolveAgentV2Hosting({
+            architecture: options.project.agent.architecture,
+        });
+        const managedV2Files = v2Hosting.kind === "cursor-managed"
+            ? () => cursorHostedFiles({
+                resolveStoreSourceId: () => v2Hosting.resolveStoreIds().deploymentStoreSourceId,
+            })
+            : undefined;
+        this.filesApi = createHostFilesApi({
+            agentName: options.project.name,
+            stateRoot: options.stateRoot,
+            sink: managedV2Files === null || managedV2Files === void 0 ? void 0 : managedV2Files(),
+        });
+        this.artifactsStore = new ArtifactsStore({
+            stateRoot: options.stateRoot,
+            agentName: options.project.name,
+            config: options.project.artifacts,
+            sink: managedV2Files === null || managedV2Files === void 0 ? void 0 : managedV2Files(),
+        });
+        // Peer and Cursor-account transports are symbolic until the serve host
+        // resolves them; the host-side MCP registry starts with the concrete
+        // connections and gains the rest via setResolvedConnections.
+        this.mcpHost = new McpHost([
+            ...options.project.agent.connections,
+            ...((_d = options.project.agent.hostConnections) !== null && _d !== void 0 ? _d : []),
+        ].filter(connection => !isSymbolicConnectionTransport(connection.transport)));
+        const basePlatforms = (_e = options.platforms) !== null && _e !== void 0 ? _e : createHostPlatforms();
+        const slackBinding = resolveDedicatedSlackHostBinding(options.project.channels);
+        this.platforms =
+            slackBinding === undefined
+                ? basePlatforms
+                : {
+                    github: basePlatforms.github,
+                    slack: createHostSlackClient({
+                        credentials: slackBinding.credentials,
+                        envPrefix: slackBinding.envPrefix,
+                    }),
+                };
+        for (const channel of options.project.channels) {
+            this.channelsById.set(channel.id, channel.definition);
+        }
+        this.stopMemoryTelemetry = shouldStartProcessMemoryTelemetry()
+            ? startProcessMemoryTelemetry({
+                agentName: options.project.name,
+                getEventLogStats: () => this.logs.memoryStats(),
+                logger: this.logger,
+                meter: options.otelMeter,
+            })
+            : undefined;
+    }
+    /**
+     * 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) {
+        this.resolvedConnections = connections;
+        for (const connection of connections) {
+            const authored = this.authoredConnection(connection.name);
+            this.mcpHost.addConnection(Object.assign(Object.assign({}, (authored !== null && authored !== void 0 ? authored : { name: connection.name })), { name: connection.name, transport: {
+                    url: connection.localUrl,
+                    headers: connection.headers,
+                } }));
+        }
+    }
+    authoredConnection(name) {
+        var _a;
+        var _b;
+        return ((_b = this.project.agent.connections.find(item => item.name === name)) !== null && _b !== void 0 ? _b : (_a = this.project.agent.hostConnections) === null || _a === void 0 ? void 0 : _a.find(item => item.name === name));
+    }
+    setCloudServerToolsConnection(connection, resolveHeaders) {
+        this.cloudServerToolsConnection = connection;
+        this.cloudServerToolsHeaders = resolveHeaders;
+    }
+    currentCloudServerToolsConnection() {
+        const connection = this.cloudServerToolsConnection;
+        const resolveHeaders = this.cloudServerToolsHeaders;
+        if (connection === undefined || !("url" in connection) || resolveHeaders === undefined) {
+            return connection;
+        }
+        const { headers: _headers } = connection, withoutHeaders = __rest(connection, ["headers"]);
+        const headers = resolveHeaders();
+        return Object.assign(Object.assign({}, withoutHeaders), (headers === undefined ? {} : { headers }));
+    }
+    setMcpOauthCallbackUrl(url) {
+        this.oauthHub.callbackUrl = url;
+        this.mcpHost.setOAuthRedirectUrl(url);
+    }
+    setCursorAccountAuthProbe(probe) {
+        this.probeCursorAccount = probe;
+    }
+    get oauthCallbackHub() {
+        return this.oauthHub;
+    }
+    /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / files / otel / Slack nudges). */
+    get host() {
+        return {
+            mcp: this.wrapMcp(this.mcpHost),
+            github: this.platforms.github,
+            slack: this.platforms.slack,
+            reminders: this.reminderApi,
+            evals: this.evalsApi,
+            kv: this.kvApi,
+            files: this.filesApi,
+            otel: this.otelHost,
+            slackNudges: this.slackNudgeHostApi(),
+        };
+    }
+    /**
+     * 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.
+     */
+    hostForSession(sessionId) {
+        const host = this.host;
+        return sessionId === undefined
+            ? host
+            : Object.assign(Object.assign({}, host), { files: this.filesApi.forSession(sessionId), otel: this.otelHost.forSession(sessionId) });
+    }
+    /** Unbound `ctx.artifacts` facade (channel handlers, scratch tool calls). */
+    get artifacts() {
+        return this.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) {
+        return {
+            tag: (input) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                if (binding === undefined) {
+                    return this.tagArtifact(input);
+                }
+                if (input.sessionId !== undefined && input.sessionId !== binding.sessionId) {
+                    throw new Error(`artifacts.tag: this context is bound to session ${binding.sessionId}; cannot tag for ${input.sessionId}`);
+                }
+                return this.tagArtifact(Object.assign(Object.assign({}, input), { sessionId: binding.sessionId, turnId: (_a = input.turnId) !== null && _a !== void 0 ? _a : binding.turnId }));
+            }),
+            list: filter => this.artifactsStore.list(filter),
+            page: options => this.artifactsStore.page(options),
+        };
+    }
+    /**
+     * 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).
+     */
+    tagArtifact(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            if (input.sessionId !== undefined &&
+                (yield this.getOrRestoreSession(input.sessionId)) === undefined) {
+                throw new UnknownSessionError(input.sessionId);
+            }
+            const record = yield this.artifactsStore.tag(input);
+            if (record.sessionId !== undefined) {
+                yield this.appendEvent(record.sessionId, {
+                    type: "artifact.tagged",
+                    turnId: record.turnId,
+                    data: {
+                        id: record.id,
+                        kind: record.kind,
+                        key: record.key,
+                        title: record.title,
+                        data: record.data,
+                        source: record.source,
+                    },
+                });
+            }
+            this.logger(`[session] artifact tagged kind=${record.kind} id=${record.id} source=${record.source} session=${(_a = record.sessionId) !== null && _a !== void 0 ? _a : "-"} key=${(_b = record.key) !== null && _b !== void 0 ? _b : "-"}`);
+            return record;
+        });
+    }
+    /**
+     * 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.
+     */
+    materializeNudgeCarrier(record, harnessCwd) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (record.channelId !== SLACK_CHANNEL_ID ||
+                record.continuationKey === null ||
+                record.continuationKey === "" ||
+                // Borrowed: a PR worktree, or a checkout shared by every session. Hooks
+                // written there dirty a tree this session did not create, and a shared
+                // cwd holds one continuation pointer for all of them — the carrier would
+                // inject one thread's follow-ups into another thread's turn. Nothing is
+                // lost: a borrowed checkout is its own git root, so the harness reads its
+                // hooks rather than these, and follow-ups drain at the turn boundary.
+                this.hasBorrowedWorkspace(record)) {
+                return;
+            }
+            if (steeringEnabled()) {
+                return;
+            }
+            try {
+                yield materializeSlackNudgeCarrier({
+                    harnessCwd,
+                    nudgeRootDir: join(this.stateRoot, "slack-nudges"),
+                    continuationKey: record.continuationKey,
+                });
+            }
+            catch (error) {
+                // Best-effort: without the carrier, follow-ups still drain at the turn
+                // boundary — one turn later, never lost.
+                this.logger(`[session] slack nudge carrier not installed: ${describeError(error)}`);
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    emitDeliveredNudges(record, emit) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const delivered = yield this.readDeliveredNudges(record);
+            if (delivered === undefined) {
+                return;
+            }
+            const previous = this.deliveredNudges.get(record.sessionId);
+            this.deliveredNudges.set(record.sessionId, delivered);
+            if (previous !== undefined && delivered > previous) {
+                emit({ type: "nudge.delivered", data: {} });
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    baselineDeliveredNudges(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const delivered = yield this.readDeliveredNudges(record);
+            if (delivered !== undefined) {
+                this.deliveredNudges.set(record.sessionId, delivered);
+            }
+        });
+    }
+    readDeliveredNudges(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const continuationKey = record.continuationKey;
+            // Same gate as the carrier: only Slack queues follow-ups mid-turn, and
+            // this runs on every tool boundary of every turn.
+            if (record.channelId !== SLACK_CHANNEL_ID ||
+                continuationKey === null ||
+                continuationKey === "") {
+                return undefined;
+            }
+            try {
+                return yield this.nudgeStore.deliveredCount(continuationKey);
+            }
+            catch (_a) {
+                // A store read must never break the turn it is observing.
+                return undefined;
+            }
+        });
+    }
+    slackNudgeHostApi() {
+        return {
+            append: input => this.nudgeStore.append(input),
+            drainFormatted: continuationKey => this.nudgeStore.drainFormatted(continuationKey),
+            clear: continuationKey => this.nudgeStore.clear(continuationKey),
+            hasUndelivered: continuationKey => this.nudgeStore.hasUndelivered(continuationKey),
+            isDelivered: (continuationKey, sourceTs) => this.nudgeStore.isDelivered(continuationKey, sourceTs),
+            tryClaimAsk: (channelId, messageTs) => this.askDedupe.tryClaim(channelId, messageTs),
+            releaseAsk: (channelId, messageTs) => this.askDedupe.release(channelId, messageTs),
+        };
+    }
+    /** Attach the serve-host reminder API (called from startServer). */
+    setReminders(api) {
+        this.reminderApi = api;
+    }
+    /** Attach the serve-host playground evals API (called from startServer). */
+    setEvals(api) {
+        this.evalsApi = api;
+    }
+    // ==========================================================================
+    // Sending messages
+    // ==========================================================================
+    /**
+     * 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_1, message_1) {
+        return __awaiter(this, arguments, void 0, function* (channelId, message, options = {}) {
+            var _a, _b;
+            var _c, _d, _e, _f, _g, _h;
+            if (isDuringHostedAdmission()) {
+                // Only sends that bypassed the admission capture stub (typically a
+                // startup-captured `onStart` send) reach the engine inside the
+                // admission window; running one would leak an invisible local session
+                // on a sessionless pod.
+                throw new HostedAdmissionLocalSendError();
+            }
+            if (options.clearCloudOverride === true && options.cloud !== undefined) {
+                throw new Error("send options cloud and clearCloudOverride cannot be combined");
+            }
+            const identity = channelId === HTTP_CHANNEL_ID
+                ? httpContinuationIdentity(this.project.httpChannel)
+                : channelContinuationIdentity(this.channelsById.get(channelId));
+            let sendOptions = options;
+            let skipContinuationLookup = false;
+            if (continuationSource(identity) === "control-plane") {
+                if (options.continuationToken !== undefined) {
+                    throw new V2EngineError("v2: do not pass continuationToken; use mailboxContinuation or claim");
+                }
+                const cKey = resolveV2Key(identity, options);
+                sendOptions = Object.assign(Object.assign({}, options), { continuationToken: cKey });
+                skipContinuationLookup = cKey.startsWith("evt:");
+            }
+            const auth = (_c = sendOptions.auth) !== null && _c !== void 0 ? _c : null;
+            let existing = skipContinuationLookup || sendOptions.continuationToken === undefined
+                ? undefined
+                : yield this.sessions.findByContinuation(channelId, sendOptions.continuationToken);
+            if (existing === undefined &&
+                !skipContinuationLookup &&
+                sendOptions.continuationToken !== undefined) {
+                // Local miss: the session may live only in the storage sink (it
+                // fell outside the startup restore window, or restore is lazy-only).
+                existing = yield this.restoreSessionByContinuation(channelId, sendOptions.continuationToken);
+            }
+            if (existing === undefined && sendOptions.hostedSessionId !== undefined) {
+                const byId = yield this.getOrRestoreSession(sendOptions.hostedSessionId);
+                if (byId !== undefined) {
+                    // evt: skips the mailbox index; same hostedSessionId is a Temporal
+                    // retry. cont:session:<id> is the explicit CP resume (keep the
+                    // original key so a PR lane stays addressable by its webhooks).
+                    if (byId.continuationKey !== sendOptions.continuationToken &&
+                        ((_a = sendOptions.mailboxContinuation) === null || _a === void 0 ? void 0 : _a.key) !==
+                            hostedSessionResumeKey(sendOptions.hostedSessionId)) {
+                        throw new V2EngineError(`v2: hosted session id ${sendOptions.hostedSessionId} already belongs to another mailbox`);
+                    }
+                    existing = byId;
+                }
+            }
+            if (existing !== undefined) {
+                if (sendOptions.hostedSessionId !== undefined &&
+                    existing.sessionId !== sendOptions.hostedSessionId) {
+                    throw new V2EngineError(`v2: continuation belongs to session ${existing.sessionId}, not ${sendOptions.hostedSessionId}`);
+                }
+                if (!samePrincipal(existing.auth, auth)) {
+                    throw new SessionAuthError(existing.sessionId);
+                }
+                // Refresh harness cwd when the caller supplies a newer worktree (e.g. PR
+                // synchronize). Leave the durable continuation key unchanged.
+                let record = existing;
+                const enqueueOnly = sendOptions.hostedEnqueueOnly === true;
+                if (!enqueueOnly) {
+                    const refreshWorkspace = sendOptions.workspaceDir !== undefined &&
+                        sendOptions.workspaceDir !== existing.workspaceOverride;
+                    if (refreshWorkspace ||
+                        sendOptions.workspaceFiles !== undefined ||
+                        sendOptions.images !== undefined) {
+                        record = yield this.updateRecord(existing.sessionId, current => (Object.assign(Object.assign({}, current), { workspaceOverride: refreshWorkspace
+                                ? sendOptions.workspaceDir
+                                : current.workspaceOverride, pendingWorkspaceFiles: mergePendingWorkspaceFiles(current.pendingWorkspaceFiles, sendOptions.workspaceFiles), pendingImages: mergePendingImages(current.pendingImages, sendOptions.images) })));
+                    }
+                    // A caller can explicitly return a continuation to the agent's
+                    // configured runtime. Omission remains sticky for compatibility:
+                    // follow-ups that do not know the original attach keep it.
+                    if (sendOptions.clearCloudOverride === true && record.cloudOverride !== undefined) {
+                        record = yield this.updateRecord(record.sessionId, current => (Object.assign(Object.assign({}, current), { cloudOverride: undefined })));
+                    }
+                    else if (sendOptions.cloud !== undefined &&
+                        JSON.stringify(sendOptions.cloud) !== JSON.stringify(record.cloudOverride)) {
+                        record = yield this.updateRecord(record.sessionId, current => (Object.assign(Object.assign({}, current), { cloudOverride: sendOptions.cloud })));
+                    }
+                    // Refresh wake-derived channel state (GitHub headSha / refs) without
+                    // wiping sticky fields. Null patch values are skipped.
+                    if (sendOptions.refreshState !== undefined) {
+                        record = yield this.updateRecord(record.sessionId, current => (Object.assign(Object.assign({}, current), { channelState: mergeChannelStateSkipNull(current.channelState, sendOptions.refreshState) })));
+                    }
+                }
+                const since = (yield this.logs.get(record.sessionId)).count;
+                const coalesced = yield this.startTurn(record.sessionId, message, Object.assign(Object.assign({ admission: enqueueOnly ? "coalesce" : ((_d = sendOptions.admission) !== null && _d !== void 0 ? _d : "preempt") }, (sendOptions.coalesceSourceTs === undefined
+                    ? {}
+                    : { sourceTs: sendOptions.coalesceSourceTs })), (enqueueOnly ? { hostedEnqueueOnly: true } : {})));
+                if (enqueueOnly && !coalesced) {
+                    throw new HostedEnqueueNotActiveError(record.sessionId);
+                }
+                if (!enqueueOnly && coalesced && sendOptions.refreshState !== undefined) {
+                    yield this.repaintOnCoalescedRefresh(record.sessionId, sendOptions.refreshState);
+                }
+                return this.channelSession(record.sessionId, record, false, coalesced, since);
+            }
+            if (sendOptions.hostedEnqueueOnly === true) {
+                throw new HostedEnqueueNotActiveError(sendOptions.hostedSessionId);
+            }
+            const now = new Date().toISOString();
+            const channelState = this.initialChannelState(channelId, sendOptions.state);
+            const purpose = sendOptions.purpose === "eval" ? "eval" : "live";
+            const frozenAsOf = normalizeAsOf(sendOptions.asOf);
+            assertTimeArgs(this.project.agent.tools, frozenAsOf);
+            const record = {
+                sessionId: (_e = sendOptions.hostedSessionId) !== null && _e !== void 0 ? _e : newSessionId(),
+                channelId,
+                mode: (_f = sendOptions.mode) !== null && _f !== void 0 ? _f : "chat",
+                purpose,
+                dryRun: sendOptions.dryRun === true ? true : undefined,
+                asOf: frozenAsOf,
+                continuationKey: (_g = sendOptions.continuationToken) !== null && _g !== void 0 ? _g : newContinuationKey(),
+                auth,
+                title: sendOptions.title,
+                channelState,
+                workspaceOverride: sendOptions.workspaceDir,
+                pendingWorkspaceFiles: sendOptions.workspaceFiles,
+                pendingImages: sendOptions.images,
+                cloudOverride: sendOptions.cloud,
+                sdkAgentId: sendOptions.sdkAgentId,
+                turnCount: 0,
+                createdAt: now,
+                updatedAt: now,
+            };
+            yield this.sessions.save(record);
+            (_b = this.storage) === null || _b === void 0 ? void 0 : _b.sessionRecord(record);
+            yield this.appendEvent(record.sessionId, {
+                type: "session.started",
+                data: {
+                    channelId,
+                    dryRun: record.dryRun === true ? true : undefined,
+                },
+            });
+            const since = (yield this.logs.get(record.sessionId)).count;
+            yield this.startTurn(record.sessionId, message, Object.assign({ admission: (_h = sendOptions.admission) !== null && _h !== void 0 ? _h : "preempt" }, (sendOptions.coalesceSourceTs === undefined
+                ? {}
+                : { sourceTs: sendOptions.coalesceSourceTs })));
+            return this.channelSession(record.sessionId, record, true, false, since);
+        });
+    }
+    /**
+     * 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, token, message) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const next = newContinuationKey();
+            const stale = new Error("stale HTTP continuation");
+            let previous;
+            try {
+                yield this.updateRecord(sessionId, record => {
+                    var _a;
+                    const expectedChannel = record.httpContinuationKey === undefined ? record.channelId : HTTP_CHANNEL_ID;
+                    const expectedKey = (_a = record.httpContinuationKey) !== null && _a !== void 0 ? _a : record.continuationKey;
+                    if (token.channelId !== expectedChannel || token.key !== expectedKey) {
+                        throw stale;
+                    }
+                    previous = record.httpContinuationKey;
+                    return Object.assign(Object.assign({}, record), { httpContinuationKey: next });
+                });
+            }
+            catch (error) {
+                if (error === stale) {
+                    return undefined;
+                }
+                throw error;
+            }
+            try {
+                yield this.startTurn(sessionId, message);
+                return next;
+            }
+            catch (error) {
+                yield this.updateRecord(sessionId, record => record.httpContinuationKey === next ? Object.assign(Object.assign({}, record), { httpContinuationKey: previous }) : record);
+                throw error;
+            }
+        });
+    }
+    /** Whether a continuation token already maps to a session on this channel. */
+    hasContinuationSession(channelId, continuationToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let existing = yield this.sessions.findByContinuation(channelId, continuationToken);
+            if (existing === undefined) {
+                existing = yield this.restoreSessionByContinuation(channelId, continuationToken);
+            }
+            return existing !== undefined;
+        });
+    }
+    /** Look up a session as a channel-scoped handle. */
+    getChannelSession(channelId, sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined || record.channelId !== channelId) {
+                return null;
+            }
+            return this.channelSession(sessionId, record, false);
+        });
+    }
+    /** Cross-channel hand-off (schedules and channel route handlers). */
+    receive(channel, input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const channelId = this.resolveChannelId(channel);
+            const definition = this.channelsById.get(channelId);
+            if ((definition === null || definition === void 0 ? void 0 : definition.receive) !== undefined) {
+                let lastCreated;
+                const send = (message_1, ...args_1) => __awaiter(this, [message_1, ...args_1], void 0, function* (message, options = {}) {
+                    const session = yield this.send(channelId, message, options);
+                    lastCreated = session;
+                    return session;
+                });
+                const returned = yield definition.receive(input, {
+                    send,
+                    artifacts: this.artifactsApi(),
+                });
+                const session = returned !== null && returned !== void 0 ? returned : lastCreated;
+                if (session === undefined) {
+                    throw new Error(`Channel "${channelId}" receive hook did not start a session`);
+                }
+                return session;
+            }
+            return this.send(channelId, input.message, {
+                auth: input.auth,
+            });
+        });
+    }
+    /** Fire-and-forget task session (schedules' markdown form). */
+    runTask(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const session = yield this.send(args.channelId, args.prompt, Object.assign({ auth: args.auth, mode: "task" }, (args.title === undefined ? {} : { title: args.title })));
+            return { sessionId: session.id, done: this.waitForCompletion(session.id) };
+        });
+    }
+    // ==========================================================================
+    // Turn execution
+    // ==========================================================================
+    /**
+     * Repaint on the follow-up wake without retargeting the live turn.
+     * Persist already took the refresh; in-flight writes stay on the carrier ts.
+     */
+    repaintOnCoalescedRefresh(sessionId, patch) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b;
+            const live = this.liveTurns.get(sessionId);
+            if (live === undefined || patch === undefined) {
+                return;
+            }
+            const repaintState = (_b = mergeChannelStateSkipNull(live.channelState, patch)) !== null && _b !== void 0 ? _b : live.channelState;
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined) {
+                return;
+            }
+            const handler = (_a = this.channelEventHandlersFor(record.channelId)) === null || _a === void 0 ? void 0 : _a["message.received"];
+            if (handler === undefined) {
+                return;
+            }
+            yield handler({
+                type: "message.received",
+                data: { text: "" },
+                index: 0,
+                sessionId,
+                at: new Date().toISOString(),
+            }, {
+                channelId: record.channelId,
+                state: repaintState,
+                continuationToken: record.continuationKey,
+                setContinuationToken: (token) => this.setContinuationToken(sessionId, token),
+            }, {
+                session: live.session,
+                host: this.hostForSession(sessionId),
+                artifacts: this.artifactsApi({ sessionId }),
+            });
+        });
+    }
+    /**
+     * 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.
+     */
+    startTurn(sessionId, message, options = {}) {
+        var _a;
+        const prior = (_a = this.admissionChains.get(sessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
+        const admitted = prior
+            .catch(() => { })
+            .then(() => __awaiter(this, void 0, void 0, function* () {
+            // Another server holds the turn: hand the message to it and coalesce.
+            // Enqueue-only must not report coalesced success without a local
+            // enqueue — the outbox drain may never run on this process.
+            if (yield this.turnLeases.runningElsewhere(sessionId)) {
+                if (options.hostedEnqueueOnly === true) {
+                    throw new HostedEnqueueNotActiveError(sessionId);
+                }
+                yield this.outbox.post(sessionId, { message, options });
+                return true;
+            }
+            return this.admitTurn(sessionId, message, options);
+        }));
+        this.admissionChains.set(sessionId, admitted.catch(() => { }));
+        return admitted;
+    }
+    /** Admit what other servers handed to this turn's holder. Never awaited by the lifecycle. */
+    drainOutbox(sessionId) {
+        void this.outbox
+            .takeAll(sessionId)
+            .then(items => {
+            for (const item of items) {
+                void this.startTurn(sessionId, item.message, item.options).catch(() => { });
+            }
+        })
+            .catch(() => { });
+    }
+    enqueueCoalesced(sessionId, item) {
+        var _a;
+        const queue = (_a = this.coalesceQueues.get(sessionId)) !== null && _a !== void 0 ? _a : [];
+        if (item.sourceTs !== undefined && queue.some(entry => entry.sourceTs === item.sourceTs)) {
+            return;
+        }
+        queue.push(item);
+        this.coalesceQueues.set(sessionId, queue);
+    }
+    clearCoalesced(sessionId) {
+        this.coalesceQueues.delete(sessionId);
+    }
+    /**
+     * 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.
+     */
+    withoutNudgedFollowups(sessionId, queued) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const record = yield this.sessions.get(sessionId);
+            const continuationKey = record === null || record === void 0 ? void 0 : record.continuationKey;
+            if (continuationKey === undefined || continuationKey === null) {
+                return [...queued];
+            }
+            const kept = [];
+            for (const item of queued) {
+                if (item.sourceTs === undefined) {
+                    kept.push(item);
+                    continue;
+                }
+                try {
+                    if (!(yield this.nudgeStore.isDelivered(continuationKey, item.sourceTs))) {
+                        kept.push(item);
+                    }
+                }
+                catch (_a) {
+                    // A store read failure must not swallow the ask.
+                    kept.push(item);
+                }
+            }
+            return kept;
+        });
+    }
+    /** Mark drained follow-ups delivered so the next turn's carrier skips them. */
+    settleDrainedFollowups(sessionId, items) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const record = yield this.sessions.get(sessionId);
+            const continuationKey = record === null || record === void 0 ? void 0 : record.continuationKey;
+            if (continuationKey === undefined || continuationKey === null) {
+                return;
+            }
+            for (const item of items) {
+                if (item.sourceTs === undefined) {
+                    continue;
+                }
+                try {
+                    yield this.nudgeStore.markDelivered(continuationKey, item.sourceTs);
+                }
+                catch (error) {
+                    // Worst case the carrier re-injects it; the ask still gets answered.
+                    this.logger(`[session] nudge markDelivered failed for ${sessionId}: ${describeError(error)}`);
+                }
+            }
+        });
+    }
+    formatCoalescedFollowups(items) {
+        if (items.length === 1) {
+            return items[0].message;
+        }
+        const parts = ["<slack_followups>", `${items.length} asks arrived while you were busy.`, ""];
+        for (let i = 0; i < items.length; i++) {
+            parts.push(`### Ask ${i + 1}`);
+            parts.push(items[i].message);
+            parts.push("");
+        }
+        parts.push("</slack_followups>");
+        return parts.join("\n").trimEnd();
+    }
+    drainCoalescedFollowups(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const queued = (_a = this.coalesceQueues.get(sessionId)) !== null && _a !== void 0 ? _a : [];
+            if (queued.length === 0) {
+                return;
+            }
+            this.coalesceQueues.delete(sessionId);
+            const pending = yield this.withoutNudgedFollowups(sessionId, queued);
+            if (pending.length === 0) {
+                this.logger(`[session] coalesce drain skipped; all follow-ups already nudged ${sessionId}`);
+                return;
+            }
+            // These become the next turn's prompt, so settle them in the nudge store
+            // first: a surviving pending record would be injected by that turn's own
+            // carrier, re-asking what the turn is already about.
+            yield this.settleDrainedFollowups(sessionId, pending);
+            const message = this.formatCoalescedFollowups(pending);
+            this.logger(`[session] coalesce drain starting follow-up (${pending.length}) ${sessionId}`);
+            yield this.startTurn(sessionId, message, {
+                admission: "preempt",
+                retainCoalesced: true,
+            });
+        });
+    }
+    steerIntoRunningTurn(sessionId, message) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.runner.steer === undefined) {
+                return "revert_to_followup";
+            }
+            try {
+                return yield this.runner.steer({ sessionId, text: message });
+            }
+            catch (error) {
+                this.logger(`[session] steer failed for ${sessionId}: ${describeError(error)}`);
+                return "revert_to_followup";
+            }
+        });
+    }
+    admitTurn(sessionId_1, message_1) {
+        return __awaiter(this, arguments, void 0, function* (sessionId, message, options = {}) {
+            var _a;
+            const admission = (_a = options.admission) !== null && _a !== void 0 ? _a : "preempt";
+            if (admission === "coalesce" && steeringEnabled() && this.isTurnRunning(sessionId)) {
+                const toolCtx = this.activeToolContexts.get(sessionId);
+                const steerOutcome = yield this.steerIntoRunningTurn(sessionId, message);
+                if (steerOutcome === "complete_delivered") {
+                    this.logger(`[session] steered into running turn ${sessionId}`);
+                    if (toolCtx !== undefined) {
+                        toolCtx.emit({ type: "message.received", data: { text: message } });
+                        toolCtx.emit({ type: "nudge.delivered", data: {} });
+                    }
+                    return true;
+                }
+            }
+            // Re-checked after the steer: a turn that ended during it falls through
+            // and this message starts the next turn itself. Enqueueing here instead
+            // would orphan it — the completion drain already ran.
+            if (admission === "coalesce" && this.isTurnRunning(sessionId)) {
+                this.enqueueCoalesced(sessionId, {
+                    message,
+                    sourceTs: options.sourceTs,
+                });
+                this.logger(`[session] coalesce enqueue ${sessionId}`);
+                return true;
+            }
+            // Another server owns this session, so coalesce even a preempt. No local
+            // enqueue: `drainCoalescedFollowups` reads only this process's queue, so
+            // the shared nudge store is the carrier. Not redundant with `acquire`
+            // below — this returns before preempt's `clearCoalesced` drops the queue.
+            // Enqueue-only cannot claim coalesced here: nothing joined a local turn.
+            if (yield this.turnLeases.runningElsewhere(sessionId)) {
+                if (options.hostedEnqueueOnly === true) {
+                    throw new HostedEnqueueNotActiveError(sessionId);
+                }
+                this.logger(`[session] coalesce; another server owns ${sessionId}`);
+                return true;
+            }
+            // Enqueue-only must never start a turn (or preempt/interrupt). Steer and
+            // coalesce above already returned true when they absorbed the message.
+            if (options.hostedEnqueueOnly === true) {
+                throw new HostedEnqueueNotActiveError(sessionId);
+            }
+            // Interrupt any turn in flight and wait for it to settle so the SDK run is
+            // terminal before this turn's send (the follow-up also force-expires as a
+            // belt-and-suspenders — see buildTurnRequest). Drain-resume skips interrupt:
+            // the parent lifecycle already cleared activeTurns, and awaiting the in-
+            // flight coalesce drain here would deadlock on itself.
+            if (options.retainCoalesced !== true) {
+                yield this.interruptActiveTurn(sessionId);
+            }
+            // Preempt owns the conversation — drop stale coalesced asks. Coalesce
+            // admits and drain-resume keep the queue (retainCoalesced / coalesce path).
+            if (admission === "preempt" && options.retainCoalesced !== true) {
+                this.clearCoalesced(sessionId);
+            }
+            // A neighbour won the race; same outcome as the branch above.
+            const lease = yield this.turnLeases.acquire(sessionId, () => {
+                var _a;
+                // Stalled past the stale window and a successor took over. Stand down
+                // rather than answer the thread alongside it.
+                this.logger(`[session] lease lost mid-turn; aborting ${sessionId}`);
+                (_a = this.turnAborts.get(sessionId)) === null || _a === void 0 ? void 0 : _a.abort();
+            });
+            if (lease === undefined) {
+                this.logger(`[session] lease lost during admit ${sessionId}`);
+                return true;
+            }
+            this.pendingTurns.add(sessionId);
+            let lifecycleInstalled = false;
+            try {
+                const record = yield this.updateRecord(sessionId, current => (Object.assign(Object.assign({}, current), { turnCount: current.turnCount + 1 })));
+                const turnId = `turn_${record.turnCount}`;
+                const isFirstTurn = record.turnCount === 1;
+                yield this.appendEvent(sessionId, {
+                    type: "message.received",
+                    turnId,
+                    data: { text: message },
+                });
+                // `turn.started` is appended by executeTurn once the turn holds a
+                // governor slot; saturated engines emit `turn.queued` first.
+                const abort = new AbortController();
+                this.turnAborts.set(sessionId, abort);
+                // Lifecycle promise includes post-turn coalesce drain so waiters and
+                // interrupt settle after follow-ups are admitted (not only executeTurn).
+                // Assigned before the async body runs so self-identity checks typecheck.
+                let lifecycle;
+                lifecycle = (() => __awaiter(this, void 0, void 0, function* () {
+                    let outcome;
+                    const poll = setInterval(() => this.drainOutbox(sessionId), 1000);
+                    poll.unref();
+                    try {
+                        outcome = yield this.executeTurn(record, turnId, message, isFirstTurn, abort.signal);
+                        if (outcome.status === "cancelled") {
+                            outcome.cancellationReason = abort.signal.aborted ? "signal" : "runner";
+                        }
+                    }
+                    catch (error) {
+                        outcome = {
+                            status: "error",
+                            errorMessage: describeError(error),
+                            errorCode: describeErrorCode(error),
+                        };
+                    }
+                    finally {
+                        clearInterval(poll);
+                        this.liveTurns.delete(sessionId);
+                    }
+                    this.lastOutcomes.set(sessionId, outcome);
+                    const wasCurrent = this.activeTurns.get(sessionId) === lifecycle;
+                    if (wasCurrent) {
+                        this.activeTurns.delete(sessionId);
+                    }
+                    if (this.turnAborts.get(sessionId) === abort) {
+                        this.turnAborts.delete(sessionId);
+                    }
+                    // Failed/cancelled owners must not start a coalesced successor.
+                    // Hosted execute would then 503 and Temporal/FIFO would re-run the
+                    // same follow-ups as full deliveries.
+                    if (wasCurrent && !abort.signal.aborted && outcome.status === "finished") {
+                        const drain = this.drainCoalescedFollowups(sessionId).catch(error => {
+                            this.logger(`[session] coalesce drain failed for ${sessionId}: ${describeError(error)}`);
+                        });
+                        this.coalesceDrains.set(sessionId, drain);
+                        try {
+                            yield drain;
+                        }
+                        finally {
+                            if (this.coalesceDrains.get(sessionId) === drain) {
+                                this.coalesceDrains.delete(sessionId);
+                            }
+                        }
+                    }
+                    // The drain may have nested a successor turn, which took its own
+                    // reference; the lease outlives this release until that one ends too.
+                    yield lease.release();
+                    // Handed off between the last poll and the release: nobody else will.
+                    if (!abort.signal.aborted) {
+                        this.drainOutbox(sessionId);
+                    }
+                    return outcome;
+                }))();
+                this.activeTurns.set(sessionId, lifecycle);
+                lifecycleInstalled = true;
+            }
+            finally {
+                this.pendingTurns.delete(sessionId);
+                if (!lifecycleInstalled) {
+                    // Nothing will run the release above, and the session would sit behind
+                    // this lease until it went stale.
+                    yield lease.release();
+                }
+            }
+            return false;
+        });
+    }
+    /**
+     * 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.
+     */
+    interruptActiveTurn(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            (_a = this.turnAborts.get(sessionId)) === null || _a === void 0 ? void 0 : _a.abort();
+            const active = this.activeTurns.get(sessionId);
+            if (active !== undefined) {
+                yield active.catch(() => { });
+            }
+            const drain = this.coalesceDrains.get(sessionId);
+            if (drain !== undefined) {
+                yield drain.catch(() => { });
+            }
+        });
+    }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b;
+            const hadWork = this.turnAborts.has(sessionId) ||
+                this.activeTurns.has(sessionId) ||
+                this.coalesceDrains.has(sessionId) ||
+                ((_b = (_a = this.coalesceQueues.get(sessionId)) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0;
+            this.clearCoalesced(sessionId);
+            yield this.outbox.clear(sessionId);
+            const record = yield this.sessions.get(sessionId);
+            const continuationKey = record === null || record === void 0 ? void 0 : record.continuationKey;
+            if (continuationKey !== undefined && continuationKey !== null) {
+                yield this.nudgeStore.clear(continuationKey);
+            }
+            yield this.interruptActiveTurn(sessionId);
+            return hadWork;
+        });
+    }
+    isContinuationBusy(channelId, continuationToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let existing = yield this.sessions.findByContinuation(channelId, continuationToken);
+            if (existing === undefined) {
+                existing = yield this.restoreSessionByContinuation(channelId, continuationToken);
+            }
+            if (existing === undefined) {
+                return false;
+            }
+            return this.isTurnRunning(existing.sessionId);
+        });
+    }
+    /**
+     * Last agent-posted Slack message ts for warm `<slack_thread_delta>`, from
+     * the session's channel state when present.
+     */
+    getContinuationLastBotMessageTs(channelId, continuationToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let existing = yield this.sessions.findByContinuation(channelId, continuationToken);
+            if (existing === undefined) {
+                existing = yield this.restoreSessionByContinuation(channelId, continuationToken);
+            }
+            if (existing === undefined) {
+                return undefined;
+            }
+            const live = this.liveTurns.get(existing.sessionId);
+            const diskTs = lastBotMessageTsOf(existing.channelState);
+            if (live === undefined) {
+                return diskTs;
+            }
+            const liveTs = lastBotMessageTsOf(live.channelState);
+            // This turn mutated the watermark (including a rewind to null). Live
+            // wins so a later disk persist cannot resurrect a deleted ts.
+            if (liveTs !== lastBotMessageTsOf(live.channelStateAtTurnStart)) {
+                return liveTs;
+            }
+            // Unchanged clone: a later owner-turn persist may have a newer ts.
+            return laterLastBotMessageTs(liveTs, diskTs);
+        });
+    }
+    interruptContinuation(channelId, continuationToken) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let existing = yield this.sessions.findByContinuation(channelId, continuationToken);
+            if (existing === undefined) {
+                existing = yield this.restoreSessionByContinuation(channelId, continuationToken);
+            }
+            if (existing === undefined) {
+                return false;
+            }
+            return this.interrupt(existing.sessionId);
+        });
+    }
+    hasRootOverride() {
+        return this.project.agent.root !== undefined;
+    }
+    /**
+     * 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.
+     */
+    resolveFileSystem(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const authored = this.project.agent.root;
+            if (authored === undefined) {
+                return localFileSystem({ cwd: options.cwd });
+            }
+            const authoredRoot = yield this.resolveAuthoredFileSystem(options);
+            if (options.cache) {
+                const existing = this.turnRoots.get(options.sessionId);
+                if (existing !== undefined) {
+                    return existing.root;
+                }
+            }
+            const root = unionFs({
+                "/": authoredRoot,
+                "/tmp": tempFs(),
+            });
+            if (options.cache && this.isTurnRunning(options.sessionId)) {
+                this.turnRoots.set(options.sessionId, { root, cwd: options.cwd });
+            }
+            return root;
+        });
+    }
+    resolveAuthoredFileSystem(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const authored = this.project.agent.root;
+            if (authored === undefined) {
+                throw new Error("resolveAuthoredFileSystem requires an authored root");
+            }
+            if (options.cache) {
+                const cached = this.sessionRoots.get(options.sessionId);
+                if (cached !== undefined) {
+                    return cached;
+                }
+                const inflight = this.sessionRootInflight.get(options.sessionId);
+                if (inflight !== undefined) {
+                    return inflight;
+                }
+            }
+            const resolve = () => __awaiter(this, void 0, void 0, function* () {
+                if (typeof authored !== "function") {
+                    return authored;
+                }
+                const host = this.hostForSession(options.cache ? options.sessionId : undefined);
+                const ctx = Object.assign(Object.assign({ sessionId: options.sessionId, agentName: this.project.agent.name }, (options.continuationKey === undefined
+                    ? {}
+                    : { continuationKey: options.continuationKey })), { host: { files: host.files, reminders: host.reminders, kv: host.kv } });
+                return yield authored(ctx);
+            });
+            if (!options.cache) {
+                return resolve();
+            }
+            const pending = resolve();
+            this.sessionRootInflight.set(options.sessionId, pending);
+            try {
+                const resolved = yield pending;
+                this.sessionRoots.set(options.sessionId, resolved);
+                return resolved;
+            }
+            finally {
+                this.sessionRootInflight.delete(options.sessionId);
+            }
+        });
+    }
+    dropTurnFileSystem(sessionId) {
+        this.turnRoots.delete(sessionId);
+    }
+    prepareScratchToolInput(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (options.sessionId === undefined) {
+                return options.input;
+            }
+            const turn = this.turnRoots.get(options.sessionId);
+            if (turn === undefined) {
+                return options.input;
+            }
+            yield ingestHostAgentToolsScratch({
+                cwd: turn.cwd,
+                root: turn.root,
+            });
+            return remapScratchPaths(options.input, turn.cwd);
+        });
+    }
+    withTurnScratchTools(tools, sessionId) {
+        const turn = this.turnRoots.get(sessionId);
+        if (turn === undefined) {
+            return tools;
+        }
+        return tools.map(tool => {
+            const execute = tool.definition.execute;
+            if (typeof execute !== "function") {
+                return tool;
+            }
+            return Object.assign(Object.assign({}, tool), { definition: Object.assign(Object.assign({}, tool.definition), { execute: (input, ctx) => __awaiter(this, void 0, void 0, function* () {
+                        const remapped = yield this.prepareScratchToolInput({
+                            sessionId,
+                            input: input !== null && typeof input === "object" && !Array.isArray(input)
+                                ? input
+                                : {},
+                        });
+                        return execute(remapped, ctx);
+                    }) }) });
+        });
+    }
+    nativeFileSystemOutcome(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { toolName, input, callId } = options;
+            if (!isFileSystemToolAlias(toolName)) {
+                return undefined;
+            }
+            // Same policy the authored callTool path asks: a dry-run write is
+            // answered by the host. Native edit/delete used to return before
+            // decideToolCall and persist through the FileSystem.
+            const decision = decideToolCall({
+                dryRun: options.dryRun === true,
+                effect: isMutatingFileSystemTool(toolName) ? "write" : "read",
+                input,
+            });
+            if (decision.kind === "answer") {
+                return {
+                    callId,
+                    toolName,
+                    isError: false,
+                    result: decision.result,
+                    durationMs: 0,
+                    sessionId: options.sessionId,
+                };
+            }
+            const root = yield this.resolveFileSystem({
+                sessionId: (_a = options.sessionId) !== null && _a !== void 0 ? _a : callId,
+                continuationKey: options.continuationKey,
+                cache: options.sessionId !== undefined,
+                cwd: options.cwd,
+            });
+            const rawArgs = input !== null && typeof input === "object" && !Array.isArray(input)
+                ? input
+                : {};
+            const args = yield this.prepareScratchToolInput({
+                sessionId: options.sessionId,
+                input: rawArgs,
+            });
+            const tool = fileSystemTool(root, toolName, args);
+            const execute = tool === null || tool === void 0 ? void 0 : tool.definition.execute;
+            if (tool === undefined || typeof execute !== "function") {
+                // A resolved root owns this native name. Falling through would let
+                // an authored lookalike run, or surface UnknownToolError after we
+                // already advertised the FileSystem tool.
+                return {
+                    callId,
+                    toolName,
+                    isError: true,
+                    result: {
+                        status: "error",
+                        error: { message: `FileSystem cannot handle ${toolName}` },
+                    },
+                    durationMs: 0,
+                    sessionId: options.sessionId,
+                    errorMessage: `FileSystem cannot handle ${toolName}`,
+                };
+            }
+            const validation = validateToolInput(tool.definition.inputSchema, args);
+            if (!validation.ok) {
+                return {
+                    callId,
+                    toolName,
+                    isError: true,
+                    result: {
+                        status: "error",
+                        error: { message: validation.message },
+                    },
+                    durationMs: 0,
+                    sessionId: options.sessionId,
+                    errorMessage: validation.message,
+                };
+            }
+            try {
+                const value = yield execute(validation.value, {
+                    toolCallId: callId,
+                    workspaceDir: options.cwd,
+                });
+                return {
+                    callId,
+                    toolName,
+                    isError: false,
+                    result: normalizeToolResult(value),
+                    durationMs: 0,
+                    sessionId: options.sessionId,
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    callId,
+                    toolName,
+                    isError: true,
+                    result: { status: "error", error: { message } },
+                    durationMs: 0,
+                    sessionId: options.sessionId,
+                    errorMessage: message,
+                };
+            }
+        });
+    }
+    /**
+     * 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) {
+        var _a, _b;
+        if (record.workspaceOverride !== undefined) {
+            return record.workspaceOverride;
+        }
+        const shared = (_a = this.project.agent.local) === null || _a === void 0 ? void 0 : _a.workspaceDir;
+        if (shared !== undefined) {
+            return shared;
+        }
+        const agentCwd = (_b = this.project.agent.local) === null || _b === void 0 ? void 0 : _b.cwd;
+        if (agentCwd !== undefined) {
+            return join(agentCwd, record.sessionId);
+        }
+        return this.sessions.workspaceDir(record.sessionId);
+    }
+    /**
+     * 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.
+     */
+    hasBorrowedWorkspace(record) {
+        var _a;
+        return (record.workspaceOverride !== undefined || ((_a = this.project.agent.local) === null || _a === void 0 ? void 0 : _a.workspaceDir) !== undefined);
+    }
+    /**
+     * 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() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.sharedWarm === undefined) {
+                this.sharedWarm = this.warmSharedWorkspace();
+            }
+            yield this.sharedWarm;
+        });
+    }
+    warmSharedWorkspace() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const agent = this.project.agent;
+            const workspaceDir = (_a = agent.local) === null || _a === void 0 ? void 0 : _a.workspaceDir;
+            if (workspaceDir === undefined ||
+                agent.runtime !== "local" ||
+                this.hasRootOverride() ||
+                this.runner.prewarm === undefined) {
+                return;
+            }
+            const startedAt = Date.now();
+            try {
+                yield mkdir(workspaceDir, { recursive: true });
+                if (yield ownSharedHarness(workspaceDir)) {
+                    yield materializeWorkspace({
+                        agent,
+                        workspaceDir,
+                        seed: true,
+                        stateRoot: this.stateRoot,
+                    });
+                }
+                const harness = resolveHostHarnessToolOptions(agent.allowedTools);
+                const outcome = yield this.runner.prewarm(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ workspaceDir, runnerStateDir: join(this.stateRoot, "runner"), sandbox: ((_b = agent.local) === null || _b === void 0 ? void 0 : _b.sandbox) === true }, (harness.tools === undefined ? {} : { tools: harness.tools })), (harness.disallowedTools === undefined
+                    ? {}
+                    : { disallowedTools: harness.disallowedTools })), { 
+                    // No session yet, so auth'd connections are omitted rather than
+                    // warmed without an identity; the per-send flag still has to match
+                    // the turns' requests or the warmed executor is one no turn asks for.
+                    mcpServers: this.buildMcpServers("local") }), (this.hasAttachedAuthedConnections() ||
+                    this.project.agent.connections.some(connection => isCursorAccountTransport(connection.transport))
+                    ? { perSendMcpServers: true }
+                    : {})), { subagents: buildRunnerSubagents(agent) }), (agent.model === undefined ? {} : { model: agent.model })));
+                // Report what happened rather than that the call returned: a runner
+                // that cannot warm resolves cleanly, and logging success there would
+                // tell an operator the workspace is hot when nothing touched it.
+                this.logger(outcome.warmed
+                    ? `[agent-sdk] warmed ${workspaceDir} in ${Date.now() - startedAt}ms`
+                    : `[agent-sdk] did not warm ${workspaceDir}: ${outcome.reason}`);
+            }
+            catch (error) {
+                this.logger(`[agent-sdk] could not warm ${workspaceDir}: ${describeError(error)}`);
+            }
+        });
+    }
+    /** Directory that receives AGENTS.md / skills / agent tools. */
+    scaffoldDir(record) {
+        if (this.hasBorrowedWorkspace(record)) {
+            return this.sessions.workspaceDir(record.sessionId);
+        }
+        return this.harnessCwd(record);
+    }
+    executeTurn(record, turnId, message, isFirstTurn, signal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b, _c, _d, _e, _f, _g, _h, _j, _k;
+            const sessionId = record.sessionId;
+            const workspaceDir = this.scaffoldDir(record);
+            const harnessCwd = this.harnessCwd(record);
+            const turnChannelState = structuredClone((_b = record.channelState) !== null && _b !== void 0 ? _b : null);
+            const eventContext = {
+                channelState: structuredClone(turnChannelState),
+                channelStateAtTurnStart: structuredClone(turnChannelState),
+                session: this.sessionInfo(record),
+            };
+            this.liveTurns.set(sessionId, eventContext);
+            // Hold the open log so tool events append synchronously. Fire-and-forget
+            // `appendEvent` races parallel tool completions and delays the live stream
+            // until the next await tick — often after *all* parallel tools finish.
+            const log = yield this.logs.get(sessionId);
+            const emit = (payload) => {
+                try {
+                    const event = log.append(Object.assign(Object.assign({}, payload), { turnId }));
+                    this.queueDispatch(sessionId, event, eventContext);
+                }
+                catch (error) {
+                    this.logger(`[agent-sdk] failed to record event for ${sessionId}: ${describeError(error)}`);
+                }
+            };
+            // Read by closure, so the mapper still sees it while draining after the
+            // registry entry below is gone.
+            const stubbed = new Set();
+            const mapper = new TurnEventMapper(emit, callId => stubbed.has(callId));
+            // Take a turn slot before any work happens. When every slot is busy the
+            // turn waits FIFO — durable `turn.queued` marks the wait — and a
+            // preempting follow-up (or interrupt) resolves the wait as cancelled
+            // without the turn ever running.
+            const permit = yield this.turnGovernor.acquire({
+                sessionId,
+                signal,
+                onQueued: position => {
+                    var _a;
+                    const maxRunningTurns = (_a = this.turnGovernor.maxRunningTurns) !== null && _a !== void 0 ? _a : 0;
+                    emit({ type: "turn.queued", data: { position, maxRunningTurns } });
+                    this.logger(`[session] ${sessionId} ${turnId} queued at position ${position} (${maxRunningTurns} turn slot(s) busy)`);
+                },
+            });
+            let outcome;
+            if (permit === undefined) {
+                // Preempted while waiting for a slot; settle as an interrupted turn.
+                outcome = { status: "cancelled" };
+            }
+            else {
+                emit({ type: "turn.started", data: {} });
+                try {
+                    if (record.workspaceOverride === undefined &&
+                        ((_a = this.project.agent.local) === null || _a === void 0 ? void 0 : _a.workspaceDir) !== undefined) {
+                        yield this.prewarmSharedWorkspace();
+                    }
+                    // Scaffold agent files into the session workspace even when the harness
+                    // cwd is overridden (e.g. a PR worktree).
+                    if (!this.hasRootOverride()) {
+                        yield materializeWorkspace({
+                            agent: this.project.agent,
+                            workspaceDir,
+                            seed: isFirstTurn,
+                            stateRoot: this.stateRoot,
+                        });
+                        this.materializedWorkspaces.add(sessionId);
+                        // Must precede the carrier: the harness resolves rules, skills,
+                        // `mcp.json` and hooks from its git root, so a workspace nested in an
+                        // outer repo would load that repo's hooks instead of the ones written
+                        // just below. Only for directories this session owns — a borrowed
+                        // checkout or worktree keeps its own root.
+                        if (!this.hasBorrowedWorkspace(record)) {
+                            yield ensureOwnGitRoot(harnessCwd);
+                        }
+                        yield this.materializeNudgeCarrier(record, harnessCwd);
+                    }
+                    // Baseline before the agent can run, so a follow-up that arrives and
+                    // drains before the first tool boundary still counts as an increase.
+                    yield this.baselineDeliveredNudges(record);
+                    const pendingFiles = record.pendingWorkspaceFiles;
+                    const pendingImages = record.pendingImages;
+                    const runtime = resolveSessionRuntime({
+                        agentRuntime: this.project.agent.runtime,
+                        cloudOverride: record.cloudOverride,
+                    });
+                    const hasPendingFiles = pendingFiles !== undefined && Object.keys(pendingFiles).length > 0;
+                    if (hasPendingFiles && runtime !== "cloud") {
+                        const root = yield this.resolveFileSystem({
+                            sessionId,
+                            continuationKey: (_c = record.continuationKey) !== null && _c !== void 0 ? _c : undefined,
+                            cache: true,
+                            cwd: harnessCwd,
+                        });
+                        yield writeWorkspaceFilesToRoot(root, pendingFiles);
+                    }
+                    if ((hasPendingFiles && runtime !== "cloud") ||
+                        (pendingImages !== undefined && pendingImages.length > 0)) {
+                        yield this.updateRecord(sessionId, current => (Object.assign(Object.assign({}, current), { pendingWorkspaceFiles: hasPendingFiles &&
+                                runtime !== "cloud" &&
+                                current.pendingWorkspaceFiles === pendingFiles
+                                ? undefined
+                                : current.pendingWorkspaceFiles, pendingImages: current.pendingImages === pendingImages ? undefined : current.pendingImages })));
+                    }
+                    const onUpdate = (update) => __awaiter(this, void 0, void 0, function* () {
+                        const turn = this.turnRoots.get(sessionId);
+                        if (turn !== undefined) {
+                            update = yield applyWebScratchUpdate({
+                                cwd: turn.cwd,
+                                root: turn.root,
+                                update,
+                            });
+                        }
+                        mapper.handleUpdate(update);
+                        // Yield so the HTTP NDJSON writer can flush tool start/result
+                        // events while sibling parallel tools are still executing.
+                        if (update.type === "tool-call-started" ||
+                            update.type === "tool-call-completed" ||
+                            // Nested subagent progress (newer SDKs); string check keeps
+                            // typecheck green against older published `@cursor/sdk` pins.
+                            update.type === "tool-call-delta") {
+                            // Same boundary the carrier hook runs on, so a drain is visible
+                            // by the time this fires.
+                            yield this.emitDeliveredNudges(record, emit);
+                            yield yieldEventLoop();
+                        }
+                    });
+                    const request = yield this.buildTurnRequest(record, turnId, message, isFirstTurn, emit, eventContext, onUpdate, signal, pendingImages);
+                    this.activeToolContexts.set(sessionId, { record, turnId, emit });
+                    this.stubbedCallIds.set(sessionId, stubbed);
+                    try {
+                        outcome = yield this.runTurnExecute(record, turnId, () => this.runner.runTurn(request));
+                    }
+                    finally {
+                        this.activeToolContexts.delete(sessionId);
+                        this.stubbedCallIds.delete(sessionId);
+                    }
+                }
+                catch (error) {
+                    this.approvals.cancelSession(sessionId, "deny");
+                    this.auths.cancelSession(sessionId, "deny");
+                    outcome = {
+                        status: "error",
+                        errorMessage: describeError(error),
+                        errorCode: describeErrorCode(error),
+                    };
+                }
+                finally {
+                    permit.release();
+                    this.dropTurnFileSystem(sessionId);
+                    this.approvals.cancelSession(sessionId, "deny");
+                    this.auths.cancelSession(sessionId, "deny");
+                    yield this.clearPendingApprovals(sessionId);
+                    yield this.clearPendingAuths(sessionId);
+                    // Anything still queued belongs to the next turn's boundary drain, not
+                    // to this turn's edge detection.
+                    this.deliveredNudges.delete(sessionId);
+                }
+            }
+            mapper.finish();
+            if (mapper.title !== undefined) {
+                const title = mapper.title;
+                yield this.updateRecord(sessionId, current => (Object.assign(Object.assign({}, current), { title })));
+                eventContext.session = Object.assign(Object.assign({}, eventContext.session), { title });
+            }
+            const finalResult = (_d = outcome.result) !== null && _d !== void 0 ? _d : mapper.finalText;
+            const finalUsage = (_e = outcome.usage) !== null && _e !== void 0 ? _e : mapper.usage;
+            const finalCost = finalUsage === undefined
+                ? undefined
+                : yield this.estimateTurnCost({
+                    model: (_f = this.project.agent.model) !== null && _f !== void 0 ? _f : DEFAULT_MODEL,
+                    usage: finalUsage,
+                    agentId: record.sdkAgentId,
+                    conversationId: (_g = record.sdkAgentId) !== null && _g !== void 0 ? _g : sessionId,
+                });
+            if (finalCost !== undefined) {
+                outcome = Object.assign(Object.assign({}, outcome), { cost: finalCost });
+            }
+            if (outcome.status === "finished") {
+                yield this.appendEvent(sessionId, {
+                    type: "turn.completed",
+                    turnId,
+                    data: {
+                        result: finalResult,
+                        usage: finalUsage,
+                        cost: finalCost,
+                    },
+                }, eventContext);
+            }
+            else {
+                const interrupted = signal.aborted && outcome.status === "cancelled";
+                yield this.appendEvent(sessionId, {
+                    type: "turn.failed",
+                    turnId,
+                    data: {
+                        status: outcome.status,
+                        message: interrupted
+                            ? "turn interrupted"
+                            : ((_h = outcome.errorMessage) !== null && _h !== void 0 ? _h : (outcome.status === "cancelled" ? "turn cancelled" : "turn failed")),
+                    },
+                }, eventContext);
+            }
+            const current = yield this.sessions.get(sessionId);
+            const mode = (_j = current === null || current === void 0 ? void 0 : current.mode) !== null && _j !== void 0 ? _j : record.mode;
+            if (mode === "task") {
+                yield this.appendEvent(sessionId, outcome.status === "finished"
+                    ? { type: "session.completed", turnId, data: {} }
+                    : {
+                        type: "session.failed",
+                        turnId,
+                        data: { message: (_k = outcome.errorMessage) !== null && _k !== void 0 ? _k : "task failed" },
+                    }, eventContext);
+                yield this.wipeCloudSessionWorkspace(sessionId);
+            }
+            else {
+                yield this.appendEvent(sessionId, {
+                    type: "session.waiting",
+                    turnId,
+                    data: {},
+                }, eventContext);
+            }
+            // Commit live channel state here. appendEvent does not wait for
+            // dispatch, and awaiting that chain deadlocks when an earlier handler
+            // is waiting on the next turn (defineResult refresh). Coalesce drain
+            // snapshots disk as soon as this returns.
+            yield this.updateRecord(sessionId, current => (Object.assign(Object.assign({}, current), { channelState: mergeChannelStateMutation({
+                    current: current.channelState,
+                    before: eventContext.channelStateAtTurnStart,
+                    after: eventContext.channelState,
+                }) })));
+            return Object.assign(Object.assign({}, outcome), { result: finalResult, usage: finalUsage });
+        });
+    }
+    /**
+     * 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.
+     */
+    ensureCloudSkillsSynced(store) {
+        const skills = this.project.agent.skills;
+        return this.syncToCloudStore("skills", store, skills.length > 0, () => syncSkillsToStore({
+            sink: store.sink,
+            agentName: this.project.name,
+            skills,
+            skillsPrefix: store.skillsPrefix,
+        }));
+    }
+    /**
+     * 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).
+     */
+    ensureCloudWorkspaceSynced(store) {
+        const seedFiles = this.project.agent.seedFiles;
+        return this.syncToCloudStore("workspace", store, seedFiles.length > 0, () => syncWorkspaceToStore({
+            sink: store.sink,
+            seedFiles,
+            workspacePrefix: store.workspacePrefix,
+        }));
+    }
+    /**
+     * 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.
+     */
+    syncCloudSessionWorkspaceFiles(store, sessionId, files) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const workspacePrefix = store.sessionWorkspacePrefix(sessionId);
+            try {
+                const relPaths = yield syncSessionWorkspaceFiles({
+                    sink: store.sink,
+                    files,
+                    workspacePrefix,
+                });
+                return {
+                    dir: `${store.mountPath}/${workspacePrefix}`,
+                    relPaths,
+                };
+            }
+            catch (error) {
+                this.logger(`[workspace] ${store.label} session files sync failed: ${error instanceof Error ? error.message : String(error)}`);
+                if (error instanceof WorkspaceFileRefusal) {
+                    yield this.clearPendingWorkspaceFiles(sessionId, files);
+                }
+                return undefined;
+            }
+        });
+    }
+    wipeCloudSessionWorkspace(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const store = this.cloudStore();
+            if (store === undefined) {
+                return;
+            }
+            try {
+                yield wipeSessionWorkspace({
+                    sink: store.sink,
+                    workspacePrefix: store.sessionWorkspacePrefix(sessionId),
+                });
+            }
+            catch (error) {
+                this.logger(`[workspace] ${store.label} session files wipe failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+    }
+    clearPendingWorkspaceFiles(sessionId, pending) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.updateRecord(sessionId, current => (Object.assign(Object.assign({}, current), { pendingWorkspaceFiles: current.pendingWorkspaceFiles === pending ? undefined : current.pendingWorkspaceFiles })));
+        });
+    }
+    /**
+     * 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.
+     */
+    syncToCloudStore(surface, store, authored, run) {
+        const inFlight = this.cloudSyncs.get(surface);
+        if (inFlight !== undefined) {
+            return inFlight;
+        }
+        let sync = run().then(() => true, error => {
+            this.logger(`[${surface}] ${store.label} sync failed: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        });
+        if (authored) {
+            sync = sync.finally(() => {
+                this.cloudSyncs.delete(surface);
+            });
+        }
+        this.cloudSyncs.set(surface, sync);
+        return sync;
+    }
+    /**
+     * 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.
+     */
+    cloudStore() {
+        const v2Hosting = resolveAgentV2Hosting({
+            architecture: this.project.agent.architecture,
+        });
+        if (v2Hosting.kind === "cursor-managed-persistent") {
+            return undefined;
+        }
+        const deployment = {
+            mountPath: DEPLOYMENT_STORE_MOUNT_PATH,
+            skillsPrefix: agentStoreKeys.skillsPrefix(),
+            workspacePrefix: agentStoreKeys.workspacePrefix(),
+            sessionWorkspacePrefix: (sessionId) => agentStoreKeys.sessionWorkspacePrefix(sessionId),
+            label: "deployment store",
+        };
+        if (v2Hosting.kind === "cursor-managed") {
+            return Object.assign({ sink: cursorHostedFiles({
+                    resolveStoreSourceId: () => v2Hosting.resolveStoreIds().deploymentStoreSourceId,
+                }) }, deployment);
+        }
+        if (v2Hosting.kind === "not-v2" && isCursorHostedFilesAvailable()) {
+            return Object.assign({ sink: cursorHostedFiles() }, deployment);
+        }
+        if (isCursorUserStoreFilesAvailable()) {
+            return {
+                sink: cursorHostedFiles({
+                    storeSourceId: AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
+                }),
+                mountPath: USER_STORE_MOUNT_PATH,
+                skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
+                workspacePrefix: agentStoreKeys.userWorkspacePrefix(this.project.name),
+                sessionWorkspacePrefix: (sessionId) => agentStoreKeys.userSessionWorkspacePrefix(this.project.name, sessionId),
+                label: "user store",
+            };
+        }
+        return undefined;
+    }
+    buildTurnRequest(record, turnId, prompt, isFirstTurn, emit, eventContext, onUpdate, signal, images) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            var _d;
+            const agent = this.project.agent;
+            // Per-session cloud attach (channel/tool handoff) forces cloud runtime
+            // even when the agent defaults to local for chat server tools.
+            const runtime = resolveSessionRuntime({
+                agentRuntime: agent.runtime,
+                cloudOverride: record.cloudOverride,
+            });
+            // Fail closed: only the local harness can enforce the built-in tool
+            // allowlist, and a restriction that silently does not apply is worse
+            // than a refused turn. Non-local agents already fail discovery; this
+            // guards hybrid agents' per-send cloud sessions.
+            //
+            // Factory roots omit `allowedTools` at discovery (the live handle is
+            // resolved per session). The allowlist guard below therefore never
+            // fires for `defineAgent({ root: (ctx) => … })` with omitted `tools`,
+            // and a per-send `cloud` attach would skip the virtual-root allowlist
+            // and run unrestricted on a VM. Any authored root refuses non-local turns.
+            if (runtime !== "local" && this.hasRootOverride()) {
+                throw new Error(`Agent "${agent.name}" declares root, which cannot be served on ${runtime} turns. Refusing the session rather than running it against the host VM.`);
+            }
+            if (runtime !== "local" && agent.allowedTools !== undefined) {
+                throw new Error(`Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on ${runtime} turns. Refusing the session rather than running it unrestricted.`);
+            }
+            // Same fail-closed posture for per-session connection features:
+            // advertised tools are server tools (in-process, local turns only) and
+            // per-session auth headers cannot reach a cloud VM's (or the Grok Bot
+            // harness's) MCP config. A turn that silently runs without its
+            // per-session tools or identity is worse than a refused one. Non-local
+            // agents already fail discovery; this guards hybrid agents' per-send
+            // cloud sessions.
+            const perSessionConnection = agent.connections.find(connection => connection.advertiseTools === true || connection.auth !== undefined);
+            if (runtime !== "local" && perSessionConnection !== undefined) {
+                throw new Error(`Agent "${agent.name}" connection "${perSessionConnection.name}" uses advertiseTools/auth, which only run on local turns. Refusing the session rather than running it without the connection's tools or identity.`);
+            }
+            const mergedCloud = runtime === "cloud"
+                ? mergeCloudOptions({
+                    base: agent.cloud,
+                    override: record.cloudOverride,
+                })
+                : undefined;
+            const authoredRoot = this.hasRootOverride();
+            const root = runtime === "local"
+                ? yield this.resolveFileSystem({
+                    sessionId: record.sessionId,
+                    continuationKey: (_d = record.continuationKey) !== null && _d !== void 0 ? _d : undefined,
+                    cache: true,
+                    cwd: this.harnessCwd(record),
+                })
+                : undefined;
+            const harnessTools = runtime === "local" && root !== undefined
+                ? authoredRoot
+                    ? {
+                        tools: resolveFileSystemTools({
+                            root,
+                            tools: agent.allowedTools,
+                        }),
+                    }
+                    : resolveHostHarnessToolOptions(agent.allowedTools)
+                : undefined;
+            const fileTools = root === undefined
+                ? []
+                : synthesizeFileSystemTools(root, authoredRoot
+                    ? rootFileToolsFromAuthored(agent.allowedTools)
+                    : hostFileToolsFromAuthored(agent.allowedTools));
+            // Host-default keeps native SemanticSearch (the host index).
+            // `localFileSystem.search` is empty, so synthesizing would
+            // replace a working index with an empty custom tool.
+            const synthesized = root === undefined
+                ? []
+                : this.withTurnScratchTools(authoredRoot ? fileTools : fileTools.filter(tool => tool.name !== "SemanticSearch"), record.sessionId);
+            let turnPrompt = prompt;
+            if (isFirstTurn) {
+                const contextBlock = buildSessionContextBlock({
+                    sessionId: record.sessionId,
+                    channelId: record.channelId,
+                    channelKind: (_b = (_a = this.channelsById.get(record.channelId)) === null || _a === void 0 ? void 0 : _a.meta) === null || _b === void 0 ? void 0 : _b.kind,
+                    environment: isDevMode() ? "local dev server" : "hosted deployment",
+                    now: record.asOf === undefined ? undefined : sessionClock(record.asOf)(),
+                });
+                turnPrompt = `${contextBlock}\n\n${prompt}`;
+            }
+            if (runtime === "cloud") {
+                // Cloud VMs have no materialized workspace: ship the full context,
+                // including agent tool script bodies. Authored skills and workspace
+                // seeds land on the store mount (skills for native discovery, seeds
+                // for the model's file tools), per-turn workspaceFiles land under
+                // the session prefix, and on hosted deployments the shared memory
+                // journal is on that mount too — say where. When the turn carries
+                // the session-bound server-tool MCP endpoint, the preamble catalogs
+                // server tools under that MCP server name *before* the agent-tool
+                // "write the script if missing" recipe, so a model told to "use
+                // <server tool>" calls MCP instead of inventing a .sh.
+                const hosted = isCursorHostedFilesAvailable();
+                const store = hosted || isCursorUserStoreFilesAvailable() ? this.cloudStore() : undefined;
+                let preamble = "";
+                const sections = [];
+                const pending = record.pendingWorkspaceFiles;
+                if (isFirstTurn) {
+                    preamble = buildAgentsMdContent(agent, {
+                        includeScripts: true,
+                        serverToolsMcpName: this.cloudServerToolsConnection === undefined
+                            ? undefined
+                            : SERVER_TOOLS_MCP_SERVER_NAME,
+                    });
+                }
+                if (store !== undefined) {
+                    if (isFirstTurn) {
+                        // Synced whenever a store is reachable, not just when skills or
+                        // seeds exist: removing the last one has to delete its store copies
+                        // too.
+                        const [, seedsSynced] = yield Promise.all([
+                            this.ensureCloudSkillsSynced(store),
+                            this.ensureCloudWorkspaceSynced(store),
+                        ]);
+                        // Only name the mount when the bytes landed; a failed sync must
+                        // not send the model looking for files that are not there.
+                        if (seedsSynced && agent.seedFiles.length > 0) {
+                            sections.push(buildCloudWorkspaceSection(`${store.mountPath}/${store.workspacePrefix}`));
+                        }
+                    }
+                    if (pending !== undefined && Object.keys(pending).length > 0) {
+                        const synced = yield this.syncCloudSessionWorkspaceFiles(store, record.sessionId, pending);
+                        if (synced !== undefined) {
+                            sections.push(buildCloudSessionWorkspaceSection(synced.dir, synced.relPaths));
+                            yield this.clearPendingWorkspaceFiles(record.sessionId, pending);
+                        }
+                    }
+                }
+                else if (pending !== undefined && Object.keys(pending).length > 0) {
+                    this.logger(`[workspace] no cloud store on this hosting; dropping workspaceFiles for session ${record.sessionId}: ${Object.keys(pending).join(", ")}`);
+                    yield this.clearPendingWorkspaceFiles(record.sessionId, pending);
+                }
+                if (isFirstTurn && hosted) {
+                    sections.push(buildCloudMemorySection(this.project.name));
+                }
+                if (preamble !== "" || sections.length > 0) {
+                    turnPrompt = [preamble, ...sections, turnPrompt].filter(part => part !== "").join("\n\n");
+                }
+            }
+            else if (isFirstTurn && runtime === "local" && authoredRoot) {
+                // The harness reports no path for a root it never mounted.
+                turnPrompt = `<user_info>\nWorkspace Path: /\n</user_info>\n\n${turnPrompt}`;
+            }
+            // A virtual root has no scaffold dir either, so its catalog carries the
+            // synthesized file tools and embedded script bodies.
+            const localInstructions = runtime === "local"
+                ? authoredRoot
+                    ? buildAgentsMdContent(Object.assign(Object.assign({}, agent), { tools: [...agent.tools, ...synthesized] }), { includeScripts: true })
+                    : buildAgentsMdContent(agent, {
+                        includeScripts: this.hasBorrowedWorkspace(record),
+                    })
+                : undefined;
+            return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined ? {} : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), sandbox: authoredRoot ? false : ((_c = agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true }), (runtime === "local" && harnessTools !== undefined
+                ? Object.assign(Object.assign({}, (harnessTools.tools === undefined ? {} : { tools: harnessTools.tools })), (harnessTools.disallowedTools === undefined
+                    ? {}
+                    : { disallowedTools: harnessTools.disallowedTools })) : {})), { runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), (agent.modelFallbacks === undefined ? {} : { modelFallbacks: agent.modelFallbacks })), { runtime, agentName: agent.name }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { 
+                // Local turns send the composed instructions as the harness system
+                // prompt; grokbot turns carry them into the hosted session, which
+                // surfaces them in the Sand system prompt. Cloud turns inline them into
+                // the first prompt above instead. Script bodies are embedded whenever
+                // the harness cannot reach the scaffold dir: always for grokbot (the
+                // box never sees the session workspace) and for a borrowed local cwd
+                // (PR worktree, shared checkout); otherwise the catalog references the
+                // on-disk paths under the harness cwd.
+                instructions: runtime === "grokbot"
+                    ? buildAgentsMdContent(agent, { includeScripts: true })
+                    : localInstructions }), (runtime === "cloud" && !isCursorHostedFilesAvailable()
+                ? { agentServeAgent: this.project.name }
+                : {})), { customTools: runtime === "local" ? yield this.buildCustomTools(record, turnId, emit, synthesized) : {}, mcpServers: this.buildMcpServers(runtime, record.sessionId, yield this.evaluateConnectionAuth(record)) }), (runtime === "local" &&
+                (this.hasAttachedAuthedConnections() ||
+                    this.project.agent.connections.some(connection => isCursorAccountTransport(connection.transport)))
+                ? { perSendMcpServers: true }
+                : {})), { subagents: buildRunnerSubagents(agent), onUpdate,
+                signal, 
+                // Local follow-ups expire any lingering active run so a preempted turn
+                // (or one orphaned by a crashed process) never blocks this send.
+                forceExpireActiveRun: runtime === "local" && !isFirstTurn, onRequestId: requestId => {
+                    emit({ type: "turn.bound", data: { requestId } });
+                }, onSdkAgentId: (sdkAgentId) => __awaiter(this, void 0, void 0, function* () {
+                    if (record.sdkAgentId === sdkAgentId) {
+                        return;
+                    }
+                    yield this.updateRecord(record.sessionId, current => (Object.assign(Object.assign({}, current), { sdkAgentId })));
+                    record.sdkAgentId = sdkAgentId;
+                    eventContext.session = Object.assign(Object.assign({}, eventContext.session), { sdkAgentId });
+                    yield this.appendEvent(record.sessionId, {
+                        type: "agent.bound",
+                        turnId,
+                        data: Object.assign({ sdkAgentId }, (sdkAgentId.startsWith("bc-")
+                            ? { url: `https://cursor.com/agents/${sdkAgentId}` }
+                            : {})),
+                    }, eventContext);
+                }) });
+        });
+    }
+    /**
+     * 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() {
+        const names = [];
+        for (const connection of this.project.agent.connections) {
+            if (isHostOauthConnectionTransport(connection.transport)) {
+                names.push(connection.name);
+            }
+        }
+        for (const resolved of this.resolvedConnections) {
+            if (resolved.accountServersFilter !== undefined && resolved.cloudUrl === undefined) {
+                names.push(resolved.name);
+            }
+        }
+        return names;
+    }
+    /**
+     * 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) {
+        if (this.cloudServerToolsConnection === undefined) {
+            return false;
+        }
+        return this.cloudBridgeableConnectionNames().includes(name);
+    }
+    /**
+     * 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.
+     */
+    cloudBridgeTransport(sessionId, connectionName) {
+        const connection = this.currentCloudServerToolsConnection();
+        if (connection === undefined || !("url" in connection)) {
+            return undefined;
+        }
+        const url = new URL(connection.url);
+        url.searchParams.set("agentkitSessionId", sessionId);
+        url.searchParams.set("connection", connectionName);
+        return Object.assign(Object.assign({}, connection), { url: url.toString() });
+    }
+    /**
+     * 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.
+     */
+    buildMcpServers(runtime, sessionId, sessionAuth) {
+        var _a;
+        // The Grok Bot harness manages its own MCP surface; authored
+        // connections are refused at discovery, so there is nothing to mount.
+        if (runtime === "grokbot") {
+            return {};
+        }
+        // Advertised connections surface as named server tools instead of an
+        // attached MCP server (each tool appears exactly once).
+        const advertisedNames = new Set(this.project.agent.connections
+            .filter(connection => connection.advertiseTools === true)
+            .map(connection => connection.name));
+        const hostConnectionNames = new Set(((_a = this.project.agent.hostConnections) !== null && _a !== void 0 ? _a : []).map(connection => connection.name));
+        const bridgedNames = new Set(runtime === "cloud" &&
+            sessionId !== undefined &&
+            this.cloudServerToolsConnection !== undefined &&
+            "url" in this.cloudServerToolsConnection
+            ? this.cloudBridgeableConnectionNames()
+            : []);
+        assertCloudCanHonorAccountServersFilters({
+            runtime,
+            resolvedConnections: this.resolvedConnections.filter(resolved => !advertisedNames.has(resolved.name) && !hostConnectionNames.has(resolved.name)),
+            bridgedNames,
+        });
+        const bridgeTransport = (name) => sessionId === undefined || !bridgedNames.has(name)
+            ? undefined
+            : this.cloudBridgeTransport(sessionId, name);
+        const servers = {};
+        for (const connection of this.project.agent.connections) {
+            if (advertisedNames.has(connection.name) || hostConnectionNames.has(connection.name)) {
+                continue;
+            }
+            if (isSymbolicConnectionTransport(connection.transport)) {
+                continue;
+            }
+            // A cloud VM cannot use a credential that lives on this host, and the
+            // cloud API rejects the `oauth` key outright ("Unrecognized key(s) in
+            // object: 'oauth'"), which fails the whole turn. Mount the host
+            // connection bridge instead when serve has a cloud tools URL; omit
+            // otherwise (host tools via `ctx.host.mcp` still reach the server).
+            if (runtime === "cloud" && isHostOauthConnectionTransport(connection.transport)) {
+                const bridged = bridgeTransport(connection.name);
+                if (bridged !== undefined) {
+                    servers[connection.name] = bridged;
+                }
+                continue;
+            }
+            // Per-session auth: merge the evaluated headers over the static
+            // ones. With no evaluation in hand (prewarm has no session) the
+            // connection is omitted rather than attached without its identity.
+            if (connection.auth !== undefined) {
+                const evaluated = sessionAuth === null || sessionAuth === void 0 ? void 0 : sessionAuth.get(connection.name);
+                if (evaluated === undefined) {
+                    continue;
+                }
+                const transport = connection.transport;
+                if ("url" in transport) {
+                    servers[connection.name] = Object.assign(Object.assign({}, transport), { headers: Object.assign(Object.assign({}, transport.headers), evaluated) });
+                }
+                continue;
+            }
+            servers[connection.name] = connection.transport;
+        }
+        for (const resolved of this.resolvedConnections) {
+            if (advertisedNames.has(resolved.name) || hostConnectionNames.has(resolved.name)) {
+                continue;
+            }
+            const url = runtime === "cloud" ? resolved.cloudUrl : resolved.localUrl;
+            if (url === undefined) {
+                // Filtered account connections bridge through the host so the
+                // `servers` filter is honored; unfiltered ones keep their documented
+                // fallback to the account's native connectors on the VM.
+                const bridged = bridgeTransport(resolved.name);
+                if (bridged !== undefined) {
+                    servers[resolved.name] = bridged;
+                }
+                continue;
+            }
+            const authored = this.authoredConnection(resolved.name);
+            if (sessionId !== undefined &&
+                authored !== undefined &&
+                isCursorAccountTransport(authored.transport)) {
+                const bound = new URL(url);
+                bound.searchParams.set("agentkitSessionId", sessionId);
+                servers[resolved.name] = {
+                    url: bound.toString(),
+                    headers: resolved.headers,
+                };
+                continue;
+            }
+            servers[resolved.name] = {
+                url,
+                headers: resolved.headers,
+            };
+        }
+        if (runtime === "cloud" &&
+            sessionId !== undefined &&
+            this.cloudServerToolsConnection !== undefined &&
+            this.project.agent.tools.some(tool => tool.execution === "server")) {
+            if (servers[SERVER_TOOLS_MCP_SERVER_NAME] !== undefined) {
+                throw new Error(`MCP connection name "${SERVER_TOOLS_MCP_SERVER_NAME}" is reserved for authored server tools on cloud turns.`);
+            }
+            const connection = this.currentCloudServerToolsConnection();
+            if (connection !== undefined && "url" in connection) {
+                const url = new URL(connection.url);
+                url.searchParams.set("agentkitSessionId", sessionId);
+                servers[SERVER_TOOLS_MCP_SERVER_NAME] = Object.assign(Object.assign({}, connection), { url: url.toString() });
+            }
+        }
+        return servers;
+    }
+    /**
+     * 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.
+     */
+    hasAttachedAuthedConnections() {
+        return this.project.agent.connections.some(connection => connection.auth !== undefined && connection.advertiseTools !== true);
+    }
+    /**
+     * 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.
+     */
+    evaluateConnectionAuth(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const authed = this.project.agent.connections.filter(connection => connection.auth !== undefined && connection.advertiseTools !== true);
+            if (authed.length === 0) {
+                return undefined;
+            }
+            const session = this.sessionInfo(record);
+            const evaluated = new Map();
+            for (const connection of authed) {
+                const auth = connection.auth;
+                if (auth === undefined) {
+                    continue;
+                }
+                try {
+                    evaluated.set(connection.name, (yield auth(session)).headers);
+                }
+                catch (error) {
+                    throw new Error(`Connection "${connection.name}" auth failed: ${describeError(error)}`, {
+                        cause: error,
+                    });
+                }
+            }
+            return evaluated;
+        });
+    }
+    buildCustomTools(record_1, turnId_1, emit_1) {
+        return __awaiter(this, arguments, void 0, function* (record, turnId, emit, extraTools = []) {
+            const agent = this.project.agent;
+            const tools = {};
+            const register = (tool) => {
+                tools[tool.name] = Object.assign(Object.assign(Object.assign({ description: tool.description, inputSchema: tool.inputSchema }, (tool.outputSchema === undefined
+                    ? {}
+                    : {
+                        outputSchema: tool.outputSchema,
+                    })), (tool.annotations === undefined ? {} : { annotations: tool.annotations })), { execute: (args, context) => __awaiter(this, void 0, void 0, function* () {
+                        return this.executeServerTool({
+                            tool,
+                            input: args,
+                            toolCallId: context.toolCallId,
+                            record,
+                            turnId,
+                            emit,
+                        });
+                    }) });
+            };
+            for (const tool of [...agent.tools, ...extraTools]) {
+                if (tool.execution !== "server") {
+                    continue;
+                }
+                if (typeof tool.definition.execute !== "function") {
+                    continue;
+                }
+                register(tool);
+            }
+            // Advertised connections (`defineConnection({ advertiseTools })`):
+            // named passthroughs resolved fresh on every turn — reminder fires and
+            // post-restart follow-ups included — and a listing failure throws,
+            // failing the turn closed.
+            for (const tool of yield mcpAuthAls.run({
+                sessionId: record.sessionId,
+                turnId,
+                callId: newToolCallId("mcp"),
+                toolName: "mcp",
+                emit,
+            }, () => resolveAdvertisedTools({
+                agent,
+                session: this.sessionInfo(record),
+                hostMcp: this.advertiseMcp(),
+            }))) {
+                register(tool);
+            }
+            return tools;
+        });
+    }
+    /**
+     * 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) {
+        return this.activeToolContexts.has(sessionId);
+    }
+    callActiveServerTool(sessionId, toolName, input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const active = this.activeToolContexts.get(sessionId);
+            if (active === undefined) {
+                return toolErrorResult(`Session ${sessionId} has no active turn for tool "${toolName}".`);
+            }
+            const tool = this.project.agent.tools.find(candidate => candidate.name === toolName && candidate.execution === "server");
+            if (tool === undefined) {
+                return toolErrorResult(`Unknown server tool "${toolName}".`);
+            }
+            const toolCallId = newToolCallId(toolName);
+            this.logger(`[session] cloud HTTP MCP tool ${toolName} dispatch (${sessionId}, ${toolCallId})`);
+            const result = yield this.executeServerTool({
+                tool,
+                input,
+                toolCallId,
+                record: active.record,
+                turnId: active.turnId,
+                emit: active.emit,
+            });
+            this.logger(`[session] cloud HTTP MCP tool ${toolName} complete (${sessionId}, ${toolCallId}, isError=${isErrorEnvelope(result)})`);
+            return result;
+        });
+    }
+    executeServerTool(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b;
+            const execute = args.tool.definition.execute;
+            if (args.tool.execution !== "server" || typeof execute !== "function") {
+                return toolErrorResult(`Tool "${args.tool.name}" is not a server tool.`);
+            }
+            const validation = validateToolInput(args.tool.definition.inputSchema, args.input);
+            if (!validation.ok) {
+                return toolErrorResult(`Invalid input for tool "${args.tool.name}": ${validation.message}`);
+            }
+            const toolCallId = (_b = args.toolCallId) !== null && _b !== void 0 ? _b : newToolCallId(args.tool.name);
+            const toolCtx = Object.assign({ toolCallId, session: this.sessionInfo(args.record), workspaceDir: this.harnessCwd(args.record), stateRoot: this.stateRoot, host: this.hostForSession(args.record.sessionId), artifacts: this.artifactsApi({
+                    sessionId: args.record.sessionId,
+                    turnId: args.turnId,
+                }), send: (channelId, message, sendOptions = {}) => { var _a; return this.send(channelId, message, Object.assign(Object.assign({}, sendOptions), { auth: (_a = sendOptions.auth) !== null && _a !== void 0 ? _a : args.record.auth })); }, getSession: (channelId, sessionId) => this.getChannelSession(channelId, sessionId), emit: args.emit, now: sessionClock(args.record.asOf) }, (args.record.asOf === undefined ? {} : { asOf: args.record.asOf }));
+            try {
+                // Before the approval gate: a dry run is unattended, so parking a write
+                // for a human would hang the turn rather than answer it.
+                const decision = decideToolCall(Object.assign(Object.assign(Object.assign({ dryRun: args.record.dryRun === true, effect: args.tool.definition.effect }, (args.tool.advertised === true
+                    ? {
+                        mcpTool: {
+                            name: args.tool.name,
+                            annotations: args.tool.annotations,
+                        },
+                    }
+                    : {})), { dryRunResult: args.tool.definition.dryRunResult, input: validation.value, asOf: args.record.asOf, timeArgs: args.tool.definition.timeArgs }), (args.tool.advertised === true && args.record.asOf !== undefined
+                    ? { timeWindow: schemaTimeWindowKeys(args.tool.inputSchema) }
+                    : {})));
+                if (decision.kind === "answer") {
+                    (_a = this.stubbedCallIds.get(args.record.sessionId)) === null || _a === void 0 ? void 0 : _a.add(toolCallId);
+                    this.logger(`[session] tool ${args.tool.name} answered by host (${toolCallId})`);
+                    return normalizeToolResult(decision.result);
+                }
+                if (decision.kind === "unbounded") {
+                    this.logger(`[session] tool ${args.tool.name} refused, unbounded_time (${toolCallId})`);
+                    return toolErrorResult(decision.message);
+                }
+                if (decision.kind === "refuse") {
+                    this.logger(`[session] tool ${args.tool.name} refused, effect unclassified (${toolCallId})`);
+                    // The coverage signal: a run reports how much of itself was runnable.
+                    args.emit({
+                        type: "action.effect_unclassified",
+                        data: { callId: toolCallId, toolName: args.tool.name },
+                    });
+                    return toolErrorResult(decision.message);
+                }
+                const needsGate = yield evaluateNeedsApproval(args.tool.definition.needsApproval, validation.value);
+                if (needsGate) {
+                    const decision = yield this.parkForApproval({
+                        sessionId: args.record.sessionId,
+                        turnId: args.turnId,
+                        callId: toolCallId,
+                        toolName: args.tool.name,
+                        args: validation.value,
+                        emit: args.emit,
+                    });
+                    if (decision === "deny") {
+                        return toolErrorResult(`Tool "${args.tool.name}" was denied by a human approver.`);
+                    }
+                }
+                const started = Date.now();
+                this.logger(`[session] tool ${args.tool.name} start`);
+                const result = yield this.runToolExecute({
+                    record: args.record,
+                    turnId: args.turnId,
+                    callId: toolCallId,
+                    toolName: args.tool.name,
+                }, () => mcpAuthAls.run({
+                    sessionId: args.record.sessionId,
+                    turnId: args.turnId,
+                    callId: toolCallId,
+                    toolName: args.tool.name,
+                    emit: args.emit,
+                }, () => execute(validation.value, toolCtx)));
+                this.logger(`[session] tool ${args.tool.name} done (${Date.now() - started}ms)`);
+                return normalizeToolResult(result);
+            }
+            catch (error) {
+                this.logger(`[session] tool ${args.tool.name} failed: ${describeError(error)}`);
+                return toolErrorResult(`Tool "${args.tool.name}" failed: ${describeError(error)}`);
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    runTurnExecute(record, turnId, fn) {
+        const otel = this.otel;
+        const run = () => Promise.resolve(fn());
+        if (otel === undefined) {
+            return run();
+        }
+        return otel.runInTurn({
+            sessionId: record.sessionId,
+            session: this.sessionInfo(record),
+            turnId,
+        }, run);
+    }
+    /**
+     * Bind outbound inject (Factory / Cursor API `traceparent`) to the
+     * tool span. No-op when OTel is off.
+     */
+    runToolExecute(args, fn) {
+        const otel = this.otel;
+        const run = () => Promise.resolve(fn());
+        if (otel === undefined) {
+            return run();
+        }
+        return otel.runInCall({
+            sessionId: args.record.sessionId,
+            session: this.sessionInfo(args.record),
+            turnId: args.turnId,
+            callId: args.callId,
+            toolName: args.toolName,
+        }, run);
+    }
+    /**
+     * 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.
+     */
+    parkForApproval(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const requestedAt = new Date().toISOString();
+            const pendingRecord = {
+                callId: args.callId,
+                turnId: args.turnId,
+                toolName: args.toolName,
+                args: args.args,
+                requestedAt,
+            };
+            const resolutionPromise = this.approvals.wait(args.sessionId, pendingRecord);
+            yield this.updateRecord(args.sessionId, current => { var _a; return (Object.assign(Object.assign({}, current), { pendingApprovals: [
+                    ...((_a = current.pendingApprovals) !== null && _a !== void 0 ? _a : []).filter(item => item.callId !== args.callId),
+                    pendingRecord,
+                ] })); });
+            args.emit({
+                type: "action.approval_requested",
+                data: {
+                    callId: args.callId,
+                    toolName: args.toolName,
+                    args: args.args,
+                },
+            });
+            this.logger(`[session] tool ${args.toolName} awaiting approval (${args.callId})`);
+            const { decision, by } = yield resolutionPromise;
+            yield this.updateRecord(args.sessionId, current => { var _a; return (Object.assign(Object.assign({}, current), { pendingApprovals: ((_a = current.pendingApprovals) !== null && _a !== void 0 ? _a : []).filter(item => item.callId !== args.callId) })); });
+            args.emit({
+                type: "action.approval_resolved",
+                data: Object.assign({ callId: args.callId, toolName: args.toolName, decision }, (by === undefined ? {} : { by })),
+            });
+            this.logger(`[session] tool ${args.toolName} approval ${decision} (${args.callId})`);
+            return decision;
+        });
+    }
+    clearPendingApprovals(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const current = yield this.sessions.get(sessionId);
+            if (current === undefined ||
+                current.pendingApprovals === undefined ||
+                current.pendingApprovals.length === 0) {
+                return;
+            }
+            yield this.updateRecord(sessionId, record => (Object.assign(Object.assign({}, record), { pendingApprovals: [] })));
+        });
+    }
+    /** Pending tool approvals for a session (live waiters ∪ persisted). */
+    listPendingApprovals(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined) {
+                return [];
+            }
+            const live = this.approvals.list(sessionId);
+            if (live.length > 0) {
+                return live;
+            }
+            return (_a = record.pendingApprovals) !== null && _a !== void 0 ? _a : [];
+        });
+    }
+    /**
+     * 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, callId, decision, auth, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined) {
+                throw new ApprovalNotFoundError(sessionId, callId);
+            }
+            const ownershipAuth = (options === null || options === void 0 ? void 0 : options.asSessionOwner) === true ? record.auth : auth;
+            if (!samePrincipal(record.auth, ownershipAuth)) {
+                throw new SessionAuthError(sessionId);
+            }
+            const pending = (_b = ((_a = record.pendingApprovals) !== null && _a !== void 0 ? _a : []).find(item => item.callId === callId)) !== null && _b !== void 0 ? _b : this.approvals.list(sessionId).find(item => item.callId === callId);
+            if (pending === undefined) {
+                throw new ApprovalNotFoundError(sessionId, callId);
+            }
+            const resolvedBy = approvalResolverLabel(auth);
+            if (!this.approvals.resolve(sessionId, callId, decision, resolvedBy)) {
+                yield this.removePendingApproval(sessionId, callId);
+                throw new ApprovalInterruptedError(sessionId, callId);
+            }
+            return pending;
+        });
+    }
+    removePendingApproval(sessionId, callId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.updateRecord(sessionId, current => { var _a; return (Object.assign(Object.assign({}, current), { pendingApprovals: ((_a = current.pendingApprovals) !== null && _a !== void 0 ? _a : []).filter(item => item.callId !== callId) })); });
+        });
+    }
+    wrapMcp(inner) {
+        return {
+            names: () => inner.names(),
+            listTools: name => this.withMcpAuth(name, () => inner.listTools(name)),
+            callTool: (name, tool, args) => this.withMcpAuth(name, () => inner.callTool(name, tool, args)),
+        };
+    }
+    advertiseMcp() {
+        return {
+            listTools: name => this.withMcpListAuth(name, () => this.mcpHost.listTools(name)),
+            callTool: (name, tool, args) => this.withMcpAuth(name, () => this.mcpHost.callTool(name, tool, args)),
+            oneOff: connection => {
+                const inner = this.mcpHost.oneOff(connection);
+                return {
+                    listTools: () => this.withMcpListAuth(connection.name, () => inner.listTools()),
+                    callTool: (tool, args) => this.withMcpAuth(connection.name, () => inner.callTool(tool, args)),
+                };
+            },
+        };
+    }
+    withMcpListAuth(connection, run) {
+        const ctx = mcpAuthAls.getStore();
+        if (ctx === undefined) {
+            return this.withMcpAuth(connection, run);
+        }
+        const toolName = `mcp:${connection}`;
+        return mcpAuthAls.run(Object.assign(Object.assign({}, ctx), { callId: newToolCallId(toolName), toolName }), () => this.withMcpAuth(connection, run));
+    }
+    withMcpAuth(connection, run) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield run();
+            }
+            catch (error) {
+                if (!isMcpNeedsAuthError(error)) {
+                    throw error;
+                }
+                return yield this.parkAndRetryMcp(connection, run, error);
+            }
+        });
+    }
+    parkAndRetryMcp(connection, run, error) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const ctx = mcpAuthAls.getStore();
+            if (ctx === undefined) {
+                throw error;
+            }
+            const minted = yield this.mintAuthUrl(connection, ctx.sessionId);
+            if (minted === undefined) {
+                throw error;
+            }
+            if ("authorized" in minted) {
+                yield this.persistHostedMcpOauth(connection);
+                yield this.mcpHost.dropClient(connection);
+                return yield this.withMcpAuth(connection, run);
+            }
+            if (minted.state !== "") {
+                const bind = this.oauthHub.bind(minted.state, ctx.sessionId, ctx.callId);
+                if (bind === "already_done") {
+                    yield this.persistHostedMcpOauth(connection);
+                    yield this.mcpHost.dropClient(connection);
+                    return yield this.withMcpAuth(connection, run);
+                }
+            }
+            const decision = yield this.parkForAuth({
+                sessionId: ctx.sessionId,
+                turnId: ctx.turnId,
+                callId: ctx.callId,
+                toolName: ctx.toolName,
+                connection,
+                authUrl: minted.authUrl,
+                emit: ctx.emit,
+            });
+            if (decision === "deny") {
+                throw new Error(`MCP connection "${connection}" authorization was denied.`);
+            }
+            yield this.persistHostedMcpOauth(connection);
+            yield this.mcpHost.dropClient(connection);
+            return yield this.withMcpAuth(connection, run);
+        });
+    }
+    persistHostedMcpOauth(connection) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const authored = this.authoredConnection(connection);
+            if (authored === undefined || !isHostOauthConnectionTransport(authored.transport)) {
+                return;
+            }
+            yield this.oauthHub.persistFor(connection, authored.transport.url);
+        });
+    }
+    mintAuthUrl(connection, sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const authored = this.authoredConnection(connection);
+            if (authored === undefined) {
+                return undefined;
+            }
+            if (isCursorAccountTransport(authored.transport)) {
+                const probe = this.probeCursorAccount;
+                if (probe === undefined) {
+                    return undefined;
+                }
+                const authUrl = yield probe(connection);
+                if (authUrl === undefined || authUrl === "") {
+                    return undefined;
+                }
+                return { authUrl, state: "" };
+            }
+            if (!isHostOauthConnectionTransport(authored.transport)) {
+                return undefined;
+            }
+            return yield this.oauthHub.mint({
+                connection,
+                url: authored.transport.url,
+                type: authored.transport.type === "sse" ? "sse" : "http",
+                headers: authored.transport.headers,
+                sessionId,
+            });
+        });
+    }
+    parkForAuth(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const requestedAt = new Date().toISOString();
+            const pendingRecord = {
+                callId: args.callId,
+                turnId: args.turnId,
+                toolName: args.toolName,
+                connection: args.connection,
+                authUrl: args.authUrl,
+                requestedAt,
+            };
+            const resolutionPromise = this.auths.wait(args.sessionId, pendingRecord);
+            yield this.updateRecord(args.sessionId, current => { var _a; return (Object.assign(Object.assign({}, current), { pendingAuths: [
+                    ...((_a = current.pendingAuths) !== null && _a !== void 0 ? _a : []).filter(item => item.callId !== args.callId),
+                    pendingRecord,
+                ] })); });
+            args.emit({
+                type: "action.auth_requested",
+                data: {
+                    callId: args.callId,
+                    toolName: args.toolName,
+                    connection: args.connection,
+                    authUrl: args.authUrl,
+                },
+            });
+            this.logger(`[session] tool ${args.toolName} awaiting MCP auth ${args.connection} (${args.callId})`);
+            const { decision, by } = yield resolutionPromise;
+            yield this.updateRecord(args.sessionId, current => { var _a; return (Object.assign(Object.assign({}, current), { pendingAuths: ((_a = current.pendingAuths) !== null && _a !== void 0 ? _a : []).filter(item => item.callId !== args.callId) })); });
+            args.emit({
+                type: "action.auth_resolved",
+                data: {
+                    callId: args.callId,
+                    toolName: args.toolName,
+                    connection: args.connection,
+                    decision,
+                    by,
+                },
+            });
+            this.logger(`[session] tool ${args.toolName} MCP auth ${decision} (${args.callId})`);
+            return decision;
+        });
+    }
+    clearPendingAuths(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.oauthHub.abortSession(sessionId);
+            const current = yield this.sessions.get(sessionId);
+            if (current === undefined ||
+                current.pendingAuths === undefined ||
+                current.pendingAuths.length === 0) {
+                return;
+            }
+            yield this.updateRecord(sessionId, record => (Object.assign(Object.assign({}, record), { pendingAuths: [] })));
+        });
+    }
+    listPendingAuths(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined) {
+                return [];
+            }
+            const live = this.auths.list(sessionId);
+            if (live.length > 0) {
+                return live;
+            }
+            return (_a = record.pendingAuths) !== null && _a !== void 0 ? _a : [];
+        });
+    }
+    resolveAuth(sessionId, callId, decision, auth, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined) {
+                throw new AuthNotFoundError(sessionId, callId);
+            }
+            const ownershipAuth = (options === null || options === void 0 ? void 0 : options.asSessionOwner) === true ? record.auth : auth;
+            if (!samePrincipal(record.auth, ownershipAuth)) {
+                throw new SessionAuthError(sessionId);
+            }
+            const pending = (_b = ((_a = record.pendingAuths) !== null && _a !== void 0 ? _a : []).find(item => item.callId === callId)) !== null && _b !== void 0 ? _b : this.auths.list(sessionId).find(item => item.callId === callId);
+            if (pending === undefined) {
+                throw new AuthNotFoundError(sessionId, callId);
+            }
+            const resolvedBy = approvalResolverLabel(auth);
+            if (decision === "deny") {
+                yield this.oauthHub.abortCall(sessionId, callId);
+            }
+            if (!this.auths.resolve(sessionId, callId, decision, resolvedBy)) {
+                yield this.removePendingAuth(sessionId, callId);
+                throw new AuthInterruptedError(sessionId, callId);
+            }
+            return pending;
+        });
+    }
+    removePendingAuth(sessionId, callId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.updateRecord(sessionId, current => { var _a; return (Object.assign(Object.assign({}, current), { pendingAuths: ((_a = current.pendingAuths) !== null && _a !== void 0 ? _a : []).filter(item => item.callId !== callId) })); });
+        });
+    }
+    runWithMcpPark(sessionId, toolName, fn) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const active = this.activeToolContexts.get(sessionId);
+            if (active === undefined) {
+                return fn();
+            }
+            return mcpAuthAls.run({
+                sessionId,
+                turnId: active.turnId,
+                callId: newToolCallId(toolName),
+                toolName,
+                emit: active.emit,
+            }, fn);
+        });
+    }
+    // ==========================================================================
+    // Direct tool calls (deterministic invocation, no model turn)
+    // ==========================================================================
+    /**
+     * 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.
+     */
+    resolveDirectCallIdentity(callId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            if (options.sessionId !== undefined && options.continuationToken !== undefined) {
+                throw new InvalidContinuationTokenError("mutually exclusive with sessionId — a real session already carries its own continuation key");
+            }
+            const auth = (_a = options.auth) !== null && _a !== void 0 ? _a : null;
+            let record;
+            let continuation = null;
+            if (options.sessionId !== undefined) {
+                record = yield this.sessions.get(options.sessionId);
+                if (record === undefined) {
+                    throw new UnknownSessionError(options.sessionId);
+                }
+            }
+            else if (options.continuationToken !== undefined) {
+                continuation = parseContinuationToken(options.continuationToken);
+                if (continuation === null) {
+                    throw new InvalidContinuationTokenError(`expected "<channelId>:<key>" (as /v1/sessions lists it), got "${options.continuationToken}"`);
+                }
+                // A token that maps to a live (or restorable) session takes the
+                // session path: same owner check, same busy semantics, same event
+                // recording as an explicit sessionId. Skipping those just because
+                // the caller addressed the session by token would fail open.
+                record = (_b = (yield this.sessions.findByContinuation(continuation.channelId, continuation.key))) !== null && _b !== void 0 ? _b : (yield this.restoreSessionByContinuation(continuation.channelId, continuation.key));
+                if (record !== undefined && !samePrincipal(record.auth, auth)) {
+                    throw new SessionAuthError(record.sessionId);
+                }
+            }
+            if (record !== undefined) {
+                return {
+                    record,
+                    session: this.sessionInfo(record),
+                    workspaceDir: this.harnessCwd(record),
+                    scratchDir: undefined,
+                    busy: this.activeTurns.has(record.sessionId) || this.pendingTurns.has(record.sessionId),
+                };
+            }
+            // No session behind the token (or no token at all): a synthetic
+            // session carries the token's channel id and key, so binding resolvers
+            // keyed on the continuation key (e.g. VFS mounts) can serve the call
+            // with no live session. The workspace stays scratch and nothing is
+            // recorded on a session event stream.
+            const scratchDir = join(this.stateRoot, "tool-calls", callId);
+            return {
+                record: undefined,
+                session: {
+                    id: callId,
+                    channelId: (_c = continuation === null || continuation === void 0 ? void 0 : continuation.channelId) !== null && _c !== void 0 ? _c : DIRECT_TOOL_CALL_CHANNEL_ID,
+                    mode: "task",
+                    continuationKey: continuation === null || continuation === void 0 ? void 0 : continuation.key,
+                    auth,
+                },
+                workspaceDir: scratchDir,
+                scratchDir,
+                busy: false,
+            };
+        });
+    }
+    /**
+     * 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() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            const { session } = yield this.resolveDirectCallIdentity(newToolCallId("catalog"), options);
+            const connectionErrors = [];
+            const advertised = yield resolveAdvertisedTools({
+                agent: this.project.agent,
+                session,
+                hostMcp: this.mcpHost,
+                onConnectionError: (connection, error) => {
+                    connectionErrors.push({
+                        connection,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                },
+            });
+            return {
+                tools: [...this.project.agent.tools, ...advertised],
+                connectionErrors,
+            };
+        });
+    }
+    /**
+     * 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_1) {
+        return __awaiter(this, arguments, void 0, function* (toolName, options = {}) {
+            const authored = this.project.agent.tools.find(tool => tool.name === toolName);
+            if (authored !== undefined) {
+                return { tool: authored };
+            }
+            const catalog = yield this.listCatalogTools(options);
+            const tool = catalog.tools.find(entry => entry.name === toolName);
+            if (tool === undefined) {
+                return {
+                    tool: undefined,
+                    availableTools: catalog.tools.map(entry => entry.name),
+                    connectionErrors: catalog.connectionErrors,
+                };
+            }
+            return { tool };
+        });
+    }
+    callTool(toolName_1) {
+        return __awaiter(this, arguments, void 0, function* (toolName, input = {}, options = {}) {
+            var _a;
+            var _b, _c;
+            const callId = newToolCallId(toolName);
+            // Identity resolves before the tool lookup: advertised connection tools
+            // only exist relative to a session (per-session auth), so finding them
+            // needs the same identity the call runs under.
+            const identity = yield this.resolveDirectCallIdentity(callId, options);
+            const record = identity.record;
+            const session = identity.session;
+            let workspaceDir = identity.workspaceDir;
+            let scratchDir = identity.scratchDir;
+            if (isFileSystemToolAlias(toolName) &&
+                identity.busy &&
+                record !== undefined &&
+                isMutatingFileSystemTool(toolName)) {
+                throw new SessionBusyError(record.sessionId);
+            }
+            const native = yield this.nativeFileSystemOutcome({
+                toolName,
+                input,
+                callId,
+                sessionId: record === null || record === void 0 ? void 0 : record.sessionId,
+                continuationKey: (_c = (_b = record === null || record === void 0 ? void 0 : record.continuationKey) !== null && _b !== void 0 ? _b : session.continuationKey) !== null && _c !== void 0 ? _c : undefined,
+                cwd: workspaceDir,
+                dryRun: (record === null || record === void 0 ? void 0 : record.dryRun) === true,
+            });
+            if (native !== undefined) {
+                return native;
+            }
+            let tool = this.project.agent.tools.find(t => t.name === toolName);
+            if (tool === undefined && this.project.agent.connections.some(c => c.advertiseTools === true)) {
+                // Advertised passthroughs are ordinary server tools in the session's
+                // namespace; resolve the live listing so direct calls address them by
+                // the same model-facing name a turn would. A listing failure fails
+                // the call closed, like it fails a turn.
+                const advertised = yield resolveAdvertisedTools({
+                    agent: this.project.agent,
+                    session,
+                    hostMcp: this.advertiseMcp(),
+                });
+                tool = advertised.find(t => t.name === toolName);
+            }
+            if (tool === undefined) {
+                throw new UnknownToolError(toolName, this.project.agent.tools.filter(t => t.execution === "server").map(t => t.name));
+            }
+            const execute = tool.definition.execute;
+            if (tool.execution !== "server" || typeof execute !== "function") {
+                throw new ToolNotDirectlyCallableError(toolName);
+            }
+            const validation = validateToolInput(tool.definition.inputSchema, input);
+            if (!validation.ok) {
+                throw new ToolInputError({ toolName, detail: validation.message });
+            }
+            // A running model turn owns the session workspace: a direct write would
+            // race the harness's own edits, so it waits (409). A read runs alongside
+            // the turn — the operator inspecting a live session is the point — and
+            // its events stay separable by their per-call turnId. The effect can
+            // depend on the input, hence deciding after validation; an MCP tool
+            // nothing classifies is a write here, fail-closed.
+            if (identity.busy &&
+                record !== undefined &&
+                directCallEffect(tool, validation.value) !== "read") {
+                throw new SessionBusyError(record.sessionId);
+            }
+            let workspaceUnavailable = false;
+            try {
+                yield mkdir(workspaceDir, { recursive: true });
+            }
+            catch (error) {
+                if (record === undefined) {
+                    throw error;
+                }
+                // A session's harness cwd can be a path the serving process cannot
+                // create (e.g. an absolute `local.cwd` like /repo on a hosted pod
+                // where the sandboxed harness would have made it). Read-effect calls
+                // fall back to a scratch workspace instead of failing: tools that
+                // resolve their state from the session identity (VFS mounts) never
+                // touch ctx.workspaceDir. Advertised passthroughs are relocatable by
+                // construction: their execute body forwards to the connection and
+                // never reads the workspace. A write (or undeclared, which resolves
+                // to write) authored tool may rely on ctx.workspaceDir being the
+                // real session workspace, so silently relocating it is not safe —
+                // fail typed instead.
+                //
+                // A shared `local.workspaceDir` (change-monitor's phantom /repo) is
+                // that path by design. Relocating it to scratch would flag a false
+                // session-state warning; keep the borrowed cwd and skip the flag.
+                const relocatable = tool.advertised === true || directCallEffect(tool, validation.value) === "read";
+                if (!relocatable) {
+                    throw new WorkspaceUnavailableError(toolName, error);
+                }
+                if (((_a = this.project.agent.local) === null || _a === void 0 ? void 0 : _a.workspaceDir) !== undefined) {
+                    this.logger(`[session] tool ${toolName} harness cwd unavailable (direct ${callId}); keeping borrowed workspace`);
+                }
+                else {
+                    this.logger(`[session] tool ${toolName} workspace unavailable (direct ${callId}); using scratch: ${error instanceof Error ? error.message : String(error)}`);
+                    scratchDir = join(this.stateRoot, "tool-calls", callId);
+                    workspaceDir = scratchDir;
+                    workspaceUnavailable = true;
+                    yield mkdir(workspaceDir, { recursive: true });
+                }
+            }
+            // Match what a model turn would see: session workspaces get the same
+            // scaffold as executeTurn (seeds only before the first turn); scratch
+            // workspaces are materialized fresh. A read running alongside a turn
+            // that has materialized its workspace leaves it alone — re-seeding
+            // would restore files the agent deleted mid-turn. A session is busy
+            // from admit, though, so a read that lands while the first turn is
+            // still queued or scaffolding materializes the workspace itself, seeds
+            // included (turnCount is already 1 for that pending first turn).
+            const turnMaterialized = record !== undefined && identity.busy && this.materializedWorkspaces.has(record.sessionId);
+            if (!this.hasRootOverride() &&
+                (record === undefined || workspaceUnavailable || !turnMaterialized)) {
+                yield materializeWorkspace({
+                    agent: this.project.agent,
+                    workspaceDir: record === undefined || workspaceUnavailable ? workspaceDir : this.scaffoldDir(record),
+                    seed: record === undefined ||
+                        workspaceUnavailable ||
+                        record.turnCount === 0 ||
+                        (identity.busy && record.turnCount === 1),
+                    stateRoot: this.stateRoot,
+                });
+            }
+            // A per-call turnId keeps these events visible in trajectories (which
+            // drop turn-less action events) without attributing them to a model turn.
+            if (record !== undefined) {
+                yield this.appendEvent(record.sessionId, {
+                    type: "actions.requested",
+                    turnId: callId,
+                    data: { calls: [{ callId, toolName, args: validation.value }] },
+                });
+            }
+            // A separate body from the model path, so it asks the same policy: a
+            // session-bound `POST /v1/tools/:name`, `call --session`, or
+            // `handle.callTool` performs a write just as readily.
+            const decision = decideToolCall(Object.assign(Object.assign(Object.assign({ dryRun: (record === null || record === void 0 ? void 0 : record.dryRun) === true, effect: tool.definition.effect }, (tool.advertised === true
+                ? { mcpTool: { name: tool.name, annotations: tool.annotations } }
+                : {})), { dryRunResult: tool.definition.dryRunResult, input: validation.value, asOf: record === null || record === void 0 ? void 0 : record.asOf, timeArgs: tool.definition.timeArgs }), (tool.advertised === true && (record === null || record === void 0 ? void 0 : record.asOf) !== undefined
+                ? { timeWindow: schemaTimeWindowKeys(tool.inputSchema) }
+                : {})));
+            const started = Date.now();
+            this.logger(`[session] tool ${toolName} start (direct ${callId})`);
+            let result;
+            let isError;
+            const stubbed = decision.kind === "answer";
+            const live = record;
+            const emit = live === undefined
+                ? undefined
+                : (payload) => {
+                    void this.appendEvent(live.sessionId, Object.assign(Object.assign({}, payload), { turnId: callId })).catch(() => { });
+                };
+            try {
+                if (decision.kind === "unbounded") {
+                    this.logger(`[session] tool ${toolName} refused, unbounded_time (direct ${callId})`);
+                    result = normalizeToolResult(toolErrorResult(decision.message));
+                    isError = true;
+                }
+                else if (decision.kind === "refuse") {
+                    this.logger(`[session] tool ${toolName} refused, effect unclassified (direct ${callId})`);
+                    emit === null || emit === void 0 ? void 0 : emit({
+                        type: "action.effect_unclassified",
+                        data: { callId, toolName },
+                    });
+                    result = normalizeToolResult(toolErrorResult(decision.message));
+                    isError = true;
+                }
+                else if (decision.kind === "answer") {
+                    this.logger(`[session] tool ${toolName} answered by host (direct ${callId})`);
+                    result = normalizeToolResult(decision.result);
+                    isError = false;
+                }
+                else {
+                    const run = () => execute(validation.value, Object.assign({ toolCallId: callId, session,
+                        workspaceDir, stateRoot: this.stateRoot, host: this.hostForSession(record === null || record === void 0 ? void 0 : record.sessionId), 
+                        // Scratch calls have no real session; their facade stays unbound.
+                        artifacts: record === undefined
+                            ? this.artifactsApi()
+                            : this.artifactsApi({
+                                sessionId: record.sessionId,
+                                turnId: callId,
+                            }), send: (channelId, message, sendOptions = {}) => this.send(channelId, message, Object.assign(Object.assign({}, sendOptions), { auth: sendOptions.auth !== undefined ? sendOptions.auth : session.auth })), getSession: (channelId, sessionId) => this.getChannelSession(channelId, sessionId), emit, now: sessionClock(record === null || record === void 0 ? void 0 : record.asOf) }, ((record === null || record === void 0 ? void 0 : record.asOf) === undefined ? {} : { asOf: record.asOf })));
+                    const executeBody = record !== undefined && emit !== undefined
+                        ? () => mcpAuthAls.run({
+                            sessionId: record.sessionId,
+                            turnId: callId,
+                            callId,
+                            toolName,
+                            emit,
+                        }, run)
+                        : run;
+                    result = normalizeToolResult(record !== undefined
+                        ? yield this.runToolExecute({
+                            record,
+                            turnId: callId,
+                            callId,
+                            toolName,
+                        }, executeBody)
+                        : yield executeBody());
+                    isError = isErrorEnvelope(result);
+                }
+            }
+            catch (error) {
+                this.logger(`[session] tool ${toolName} failed (direct ${callId}): ${describeError(error)}`);
+                // Same envelope the model path returns for a throwing tool body.
+                result = {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Tool "${toolName}" failed: ${describeError(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+                isError = true;
+            }
+            finally {
+                if (scratchDir !== undefined) {
+                    yield rm(scratchDir, { recursive: true, force: true }).catch(() => { });
+                }
+            }
+            const durationMs = Date.now() - started;
+            this.logger(`[session] tool ${toolName} done (direct ${callId}, ${durationMs}ms)`);
+            if (record !== undefined) {
+                yield this.appendEvent(record.sessionId, {
+                    type: "action.result",
+                    turnId: callId,
+                    data: Object.assign({ callId,
+                        toolName, output: result, isError }, (stubbed ? { stubbed: true } : {})),
+                });
+            }
+            const errorMessage = isError ? toolCallErrorMessage(result) : undefined;
+            return {
+                toolName,
+                callId,
+                isError,
+                result,
+                durationMs,
+                errorMessage,
+                sessionId: record === null || record === void 0 ? void 0 : record.sessionId,
+                scratchWorkspace: workspaceUnavailable ? true : undefined,
+            };
+        });
+    }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Read off the in-flight turn's context rather than the session store:
+            // the bridge already refuses a call with no active turn, so the record is
+            // in memory. The listing below is only paid inside a dry run.
+            const context = this.activeToolContexts.get(args.sessionId);
+            if ((context === null || context === void 0 ? void 0 : context.record.asOf) !== undefined) {
+                const decision = decideToolCall({
+                    dryRun: false,
+                    effect: undefined,
+                    input: args.input,
+                    asOf: context.record.asOf,
+                });
+                if (decision.kind === "unbounded") {
+                    this.logger(`[session] bridged tool ${args.toolName} refused, unbounded_time (${args.sessionId})`);
+                    return { answered: true, result: toolErrorResult(decision.message) };
+                }
+            }
+            if ((context === null || context === void 0 ? void 0 : context.record.dryRun) !== true) {
+                return { answered: false };
+            }
+            // A bridged tool carries no `defineTool`, so its effect comes from the
+            // server's own listing annotations; a tool the listing cannot classify
+            // refuses rather than being stubbed. A failed listing classifies nothing,
+            // which lands on the same refusal — never on a run.
+            const info = yield this.bridgedToolInfo(args.connectionName, args.toolName);
+            const decision = decideToolCall(Object.assign({ dryRun: true, effect: undefined, mcpTool: { name: args.toolName, annotations: info === null || info === void 0 ? void 0 : info.annotations }, input: args.input, asOf: context.record.asOf }, (context.record.asOf !== undefined
+                ? { timeWindow: schemaTimeWindowKeys(info === null || info === void 0 ? void 0 : info.inputSchema) }
+                : {})));
+            if (decision.kind === "run") {
+                return { answered: false };
+            }
+            if (decision.kind === "unbounded") {
+                this.logger(`[session] bridged tool ${args.toolName} refused, unbounded_time (${args.sessionId})`);
+                return { answered: true, result: toolErrorResult(decision.message) };
+            }
+            if (decision.kind === "refuse") {
+                this.logger(`[session] bridged tool ${args.toolName} refused, effect unclassified (${args.sessionId})`);
+                context.emit({
+                    type: "action.effect_unclassified",
+                    data: {
+                        callId: newToolCallId(args.toolName),
+                        toolName: args.toolName,
+                        connection: args.connectionName,
+                    },
+                });
+                return { answered: true, result: toolErrorResult(decision.message) };
+            }
+            this.logger(`[session] bridged tool ${args.toolName} answered by host (${args.sessionId})`);
+            return { answered: true, result: normalizeToolResult(decision.result) };
+        });
+    }
+    /**
+     * 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.
+     */
+    bridgedToolInfo(connectionName, toolName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const listed = yield this.host.mcp.listTools(connectionName);
+                return listed.find(tool => tool.name === toolName);
+            }
+            catch (_a) {
+                return undefined;
+            }
+        });
+    }
+    // ==========================================================================
+    // Events: append, dispatch to channel handlers + hooks
+    // ==========================================================================
+    appendEvent(sessionId, payload, context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const log = yield this.logs.get(sessionId);
+            const event = log.append(payload);
+            this.queueDispatch(sessionId, event, context);
+            return event;
+        });
+    }
+    queueDispatch(sessionId, event, context) {
+        var _a;
+        var _b;
+        // Single funnel for both append paths (appendEvent + the held-log emit),
+        // so the storage sink sees every durable event exactly once.
+        (_a = this.storage) === null || _a === void 0 ? void 0 : _a.event(event);
+        const chain = (_b = this.dispatchChains.get(sessionId)) !== null && _b !== void 0 ? _b : Promise.resolve();
+        const next = chain
+            .then(() => this.dispatchEvent(sessionId, event, context))
+            .catch(error => {
+            this.logger(`[agent-sdk] event dispatch failed for ${sessionId}: ${describeError(error)}`);
+        })
+            .then(() => {
+            var _a;
+            // Turn-end flush happens here — after the boundary event's handlers
+            // and their record updates settled — so the persisted record carries
+            // the turn's final channel state and continuation token.
+            (_a = this.storage) === null || _a === void 0 ? void 0 : _a.eventDispatched(event);
+        });
+        this.dispatchChains.set(sessionId, next);
+    }
+    dispatchEvent(sessionId, event, context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b, _c;
+            const record = yield this.sessions.get(sessionId);
+            if (record === undefined) {
+                return;
+            }
+            const channelState = context === undefined ? ((_b = record.channelState) !== null && _b !== void 0 ? _b : null) : context.channelState;
+            const sessionCtx = {
+                session: (_c = context === null || context === void 0 ? void 0 : context.session) !== null && _c !== void 0 ? _c : this.sessionInfo(record),
+                host: this.hostForSession(record.sessionId),
+                artifacts: this.artifactsApi({
+                    sessionId: record.sessionId,
+                    turnId: event.turnId,
+                }),
+            };
+            const channelEvents = this.channelEventHandlersFor(record.channelId);
+            if (channelEvents !== undefined) {
+                // Handlers are declared against the narrowed event for their key; the
+                // dispatch key always matches, so widening here is sound.
+                const handlers = [
+                    channelEvents[event.type],
+                    channelEvents["*"],
+                ];
+                const channelCtx = {
+                    channelId: record.channelId,
+                    state: channelState,
+                    continuationToken: record.continuationKey,
+                    setContinuationToken: (token) => this.setContinuationToken(sessionId, token),
+                };
+                for (const handler of handlers) {
+                    if (handler === undefined) {
+                        continue;
+                    }
+                    try {
+                        yield handler(event, channelCtx, sessionCtx);
+                    }
+                    catch (error) {
+                        this.logger(`[agent-sdk] channel "${record.channelId}" handler for ${event.type} threw: ${describeError(error)}`);
+                    }
+                }
+                if (context !== undefined) {
+                    context.channelState = channelCtx.state;
+                }
+                // Persist at turn boundaries only. Mid-turn mutations stay on the live
+                // context; merge turn-start → live so a last-event before/after cannot
+                // drop earlier handler writes.
+                if (context === undefined) {
+                    yield this.updateRecord(sessionId, current => (Object.assign({}, current)));
+                }
+                else if (isTurnBoundaryEvent(event.type)) {
+                    yield this.updateRecord(sessionId, current => (Object.assign(Object.assign({}, current), { channelState: mergeChannelStateMutation({
+                            current: current.channelState,
+                            before: context.channelStateAtTurnStart,
+                            after: context.channelState,
+                        }) })));
+                }
+            }
+            for (const hook of this.project.hooks) {
+                const handlers = [
+                    hook.definition.events[event.type],
+                    hook.definition.events["*"],
+                ];
+                for (const handler of handlers) {
+                    if (handler === undefined) {
+                        continue;
+                    }
+                    try {
+                        yield handler(event, Object.assign(Object.assign({}, sessionCtx), { agent: { name: this.project.name }, channel: {
+                                id: record.channelId,
+                                continuationToken: record.continuationKey,
+                            }, channelState, stateRoot: this.stateRoot }));
+                    }
+                    catch (error) {
+                        this.logger(`[agent-sdk] hook "${hook.name}" handler for ${event.type} threw: ${describeError(error)}`);
+                    }
+                }
+            }
+            (_a = this.otel) === null || _a === void 0 ? void 0 : _a.onEvent(event, sessionCtx.session);
+        });
+    }
+    channelEventHandlersFor(channelId) {
+        var _a;
+        if (channelId === HTTP_CHANNEL_ID) {
+            return this.project.httpChannel.events;
+        }
+        return (_a = this.channelsById.get(channelId)) === null || _a === void 0 ? void 0 : _a.events;
+    }
+    // ==========================================================================
+    // Session handles
+    // ==========================================================================
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.storage === undefined) {
+                return;
+            }
+            const chain = this.dispatchChains.get(sessionId);
+            if (chain !== undefined) {
+                yield chain.catch(() => { });
+            }
+            this.storage.flushSession(sessionId);
+            yield this.storage.whenIdle();
+        });
+    }
+    waitForCompletion(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            // Drain admission first so pendingTurns → activeTurns is visible before we
+            // decide the session is idle (reminders use this for queueBehindTurn).
+            // Wait for coalesce drain and any successor turn so hosted execute does
+            // not park mid-follow-up, but report the root turn's outcome: a drained
+            // successor failure must not un-ACK an already-finished owner.
+            let root;
+            for (;;) {
+                const chain = this.admissionChains.get(sessionId);
+                if (chain !== undefined) {
+                    yield chain.catch(() => { });
+                }
+                const active = this.activeTurns.get(sessionId);
+                if (active !== undefined) {
+                    const outcome = yield active;
+                    root !== null && root !== void 0 ? root : (root = outcome);
+                    continue;
+                }
+                const dispatch = this.dispatchChains.get(sessionId);
+                if (dispatch !== undefined) {
+                    yield dispatch.catch(() => { });
+                }
+                return (_a = root !== null && root !== void 0 ? root : this.lastOutcomes.get(sessionId)) !== null && _a !== void 0 ? _a : { status: "finished" };
+            }
+        });
+    }
+    /**
+     * 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, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return (yield this.listSessionsWithSource(caller, options)).sessions;
+        });
+    }
+    /**
+     * 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, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            let matches;
+            if ((options === null || options === void 0 ? void 0 : options.includeAll) !== true) {
+                const owned = yield this.ownedSessionIds(caller);
+                matches = record => record.sessionId !== undefined && owned.has(record.sessionId);
+            }
+            return this.artifactsStore.page({
+                kind: (_a = options === null || options === void 0 ? void 0 : options.filter) === null || _a === void 0 ? void 0 : _a.kind,
+                sessionId: (_b = options === null || options === void 0 ? void 0 : options.filter) === null || _b === void 0 ? void 0 : _b.sessionId,
+                limit: options === null || options === void 0 ? void 0 : options.limit,
+                cursor: options === null || options === void 0 ? void 0 : options.cursor,
+                matches,
+            });
+        });
+    }
+    /**
+     * 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, id, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const record = yield this.artifactsStore.get(id);
+            if (record === undefined || record.content === undefined) {
+                return undefined;
+            }
+            if ((options === null || options === void 0 ? void 0 : options.includeAll) !== true) {
+                if (record.sessionId === undefined) {
+                    return undefined;
+                }
+                const owned = yield this.ownedSessionIds(caller);
+                if (!owned.has(record.sessionId)) {
+                    return undefined;
+                }
+            }
+            const body = yield this.artifactsStore.getContent(id);
+            return body === undefined ? undefined : { record, body };
+        });
+    }
+    ownedSessionIds(caller) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const sessions = yield this.sessions.list();
+            return new Set(sessions.filter(record => samePrincipal(record.auth, caller)).map(record => record.sessionId));
+        });
+    }
+    /**
+     * Same as {@link listSessions}, plus which store answered
+     * (`cursor-hosted` = durable DB via the control-plane proxy; `local` =
+     * `--state-root`).
+     */
+    listSessionsWithSource(caller, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b;
+            const includeAll = (_b = options === null || options === void 0 ? void 0 : options.includeAll) !== null && _b !== void 0 ? _b : false;
+            if (((_a = this.storage) === null || _a === void 0 ? void 0 : _a.isCursorHosted) === true) {
+                try {
+                    const records = yield this.mergeStoredAndLocalSessions();
+                    return {
+                        sessions: this.summarizeSessionRecords(records, caller, includeAll),
+                        source: "cursor-hosted",
+                    };
+                }
+                catch (error) {
+                    this.logger(`[agent-sdk] cursor-hosted session list failed; falling back to local: ${describeError(error)}`);
+                }
+            }
+            const records = yield this.sessions.list();
+            // Local store is createdAt-asc; reverse so newest created leads.
+            return {
+                sessions: this.summarizeSessionRecords([...records].reverse(), caller, includeAll),
+                source: "local",
+            };
+        });
+    }
+    /**
+     * 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, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b;
+            const includeAll = (_b = options === null || options === void 0 ? void 0 : options.includeAll) !== null && _b !== void 0 ? _b : false;
+            const newestVisible = (records) => {
+                let newest;
+                for (const record of records) {
+                    if (!(includeAll || samePrincipal(record.auth, caller))) {
+                        continue;
+                    }
+                    if (newest === undefined || record.updatedAt.localeCompare(newest.updatedAt) > 0) {
+                        newest = record;
+                    }
+                }
+                return newest;
+            };
+            const local = newestVisible(yield this.sessions.list());
+            if (local !== undefined) {
+                return {
+                    sessions: this.summarizeSessionRecords([local], caller, includeAll),
+                    source: "local",
+                };
+            }
+            if (((_a = this.storage) === null || _a === void 0 ? void 0 : _a.isCursorHosted) === true) {
+                try {
+                    const window = yield this.storage.listNewestSessionsFromSink(LATEST_SESSION_SINK_WINDOW);
+                    if (window !== undefined) {
+                        const stored = newestVisible(window);
+                        if (stored !== undefined) {
+                            return {
+                                sessions: this.summarizeSessionRecords([stored], caller, includeAll),
+                                source: "cursor-hosted",
+                            };
+                        }
+                    }
+                }
+                catch (error) {
+                    this.logger(`[agent-sdk] cursor-hosted newest-session lookup failed; falling back to the full list: ${describeError(error)}`);
+                }
+            }
+            const listed = yield this.listSessionsWithSource(caller, options);
+            return { sessions: listed.sessions.slice(0, 1), source: listed.source };
+        });
+    }
+    /**
+     * 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.
+     */
+    mergeStoredAndLocalSessions() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const storage = this.storage;
+            if (storage === undefined) {
+                throw new Error("storage is not configured");
+            }
+            const stored = yield storage.listSessionsFromSink();
+            const local = yield this.sessions.list();
+            const byId = new Map();
+            for (const record of stored) {
+                byId.set(record.sessionId, record);
+            }
+            for (const record of local) {
+                const existing = byId.get(record.sessionId);
+                if (existing === undefined || record.updatedAt.localeCompare(existing.updatedAt) >= 0) {
+                    byId.set(record.sessionId, record);
+                }
+            }
+            return [...byId.values()].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        });
+    }
+    summarizeSessionRecords(records, caller, includeAll) {
+        return records
+            .filter(record => includeAll || samePrincipal(record.auth, caller))
+            .map(record => {
+            var _a;
+            const links = sessionExternalLinks(record);
+            return {
+                sessionId: record.sessionId,
+                channelId: record.channelId,
+                mode: record.mode,
+                title: record.title,
+                turnCount: record.turnCount,
+                running: this.activeTurns.has(record.sessionId) || this.pendingTurns.has(record.sessionId),
+                queued: this.turnGovernor.limited
+                    ? this.turnGovernor.isQueued(record.sessionId)
+                    : undefined,
+                createdAt: record.createdAt,
+                updatedAt: record.updatedAt,
+                dryRun: record.dryRun === true ? true : undefined,
+                continuationToken: record.httpContinuationKey !== undefined
+                    ? formatContinuationToken(HTTP_CHANNEL_ID, record.httpContinuationKey)
+                    : record.continuationKey === null
+                        ? null
+                        : formatContinuationToken(record.channelId, record.continuationKey),
+                externalUrl: (_a = links.slack) !== null && _a !== void 0 ? _a : links.github,
+                prUrl: links.github,
+            };
+        });
+    }
+    eventStream(sessionId_1) {
+        return __awaiter(this, arguments, void 0, function* (sessionId, startIndex = 0) {
+            // Playground Trace replays this stream; backfill before the snapshot
+            // so historical Sherlock-style cloud turns can show billed cost.
+            yield this.backfillCloudTurnCosts(sessionId);
+            const log = yield this.logs.get(sessionId);
+            return log.stream(startIndex);
+        });
+    }
+    /**
+     * 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, text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.isTurnRunning(sessionId)) {
+                throw new SessionBusyError(sessionId);
+            }
+            const existing = yield this.sessions.get(sessionId);
+            if (existing === undefined) {
+                throw new Error(`Unknown session: ${sessionId}`);
+            }
+            const record = yield this.updateRecord(sessionId, current => (Object.assign(Object.assign({}, current), { turnCount: current.turnCount + 1 })));
+            const turnId = `turn_${record.turnCount}`;
+            yield this.appendEvent(sessionId, {
+                type: "turn.started",
+                turnId,
+                data: {},
+            });
+            yield this.appendEvent(sessionId, {
+                type: "message.completed",
+                turnId,
+                data: { text, finishReason: "stop" },
+            });
+            yield this.appendEvent(sessionId, {
+                type: "turn.completed",
+                turnId,
+                data: { result: text },
+            });
+            yield this.appendEvent(sessionId, {
+                type: "session.waiting",
+                data: {},
+            });
+            this.lastOutcomes.set(sessionId, {
+                status: "finished",
+                result: text,
+            });
+        });
+    }
+    /**
+     * Billed/catalog cost for a session. Powers playground, traces, and
+     * `agent-sdk cost` via `GET /v1/session/:id/cost`.
+     */
+    sessionCost(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g;
+            const record = yield this.getOrRestoreSession(sessionId);
+            if (record === undefined) {
+                throw new Error(`Unknown session: ${sessionId}`);
+            }
+            yield this.backfillCloudTurnCosts(sessionId);
+            const events = yield this.listEvents(sessionId);
+            const sdkAgentId = (_a = (record.sdkAgentId !== undefined && record.sdkAgentId !== ""
+                ? record.sdkAgentId
+                : undefined)) !== null && _a !== void 0 ? _a : cloudSdkAgentIdFromEvents(events);
+            const model = (_b = this.project.agent.model) !== null && _b !== void 0 ? _b : DEFAULT_MODEL;
+            const priced = yield this.estimateTurnCost({
+                model,
+                agentId: sdkAgentId,
+                conversationId: sdkAgentId !== null && sdkAgentId !== void 0 ? sdkAgentId : sessionId,
+            });
+            if (priced !== undefined && (priced.source === "usage" || priced.totalUsd > 0)) {
+                return {
+                    sessionId,
+                    source: priced.source,
+                    cost: {
+                        rawCostCents: (_d = (_c = priced.rawCostCents) !== null && _c !== void 0 ? _c : priced.chargedCents) !== null && _d !== void 0 ? _d : 0,
+                        chargedCents: (_e = priced.chargedCents) !== null && _e !== void 0 ? _e : priced.totalUsd * 100,
+                    },
+                    costUsd: priced.totalUsd,
+                    rawCostUsd: roundCostUsd(((_g = (_f = priced.rawCostCents) !== null && _f !== void 0 ? _f : priced.chargedCents) !== null && _g !== void 0 ? _g : priced.totalUsd * 100) / 100),
+                    model: priced.model,
+                };
+            }
+            let costUsd = 0;
+            let rawCostUsd = 0;
+            let source = "unavailable";
+            let modelId;
+            for (const event of events) {
+                if (event.type !== "turn.completed" || event.data.cost === undefined) {
+                    continue;
+                }
+                costUsd = roundCostUsd(costUsd + event.data.cost.totalUsd);
+                const rawCents = event.data.cost.rawCostCents;
+                rawCostUsd = roundCostUsd(rawCostUsd + (rawCents !== undefined ? rawCents / 100 : event.data.cost.totalUsd));
+                source = event.data.cost.source;
+                modelId = event.data.cost.model;
+            }
+            return {
+                sessionId,
+                source,
+                cost: {
+                    rawCostCents: rawCostUsd * 100,
+                    chargedCents: costUsd * 100,
+                },
+                costUsd,
+                rawCostUsd,
+                model: modelId,
+            };
+        });
+    }
+    /** Snapshot of recorded events (for download / offline trace). */
+    listEvents(sessionId_1) {
+        return __awaiter(this, arguments, void 0, function* (sessionId, startIndex = 0, options) {
+            if ((options === null || options === void 0 ? void 0 : options.backfillCloudCost) === true) {
+                yield this.backfillCloudTurnCosts(sessionId);
+            }
+            const log = yield this.logs.get(sessionId);
+            return log.snapshot(startIndex);
+        });
+    }
+    /**
+     * 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.
+     */
+    backfillCloudTurnCosts(sessionId) {
+        if (this.cloudCostBackfillDone.has(sessionId)) {
+            return Promise.resolve();
+        }
+        const pending = this.cloudCostBackfill.get(sessionId);
+        if (pending !== undefined) {
+            return pending;
+        }
+        const work = this.runCloudTurnCostBackfill(sessionId)
+            .catch(error => {
+            this.logger(`[agent-sdk] cloud cost backfill failed for ${sessionId}: ${describeError(error)}`);
+        })
+            .finally(() => {
+            this.cloudCostBackfill.delete(sessionId);
+        });
+        this.cloudCostBackfill.set(sessionId, work);
+        return work;
+    }
+    runCloudTurnCostBackfill(sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b, _c;
+            const log = yield this.logs.get(sessionId);
+            const events = yield log.snapshot(0);
+            if (!events.some(event => isUnpricedCompletedTurn(event))) {
+                if (!this.isTurnRunning(sessionId) && events.some(event => event.type === "turn.completed")) {
+                    this.cloudCostBackfillDone.add(sessionId);
+                }
+                return;
+            }
+            const record = yield this.sessions.get(sessionId);
+            const sdkAgentId = (_b = (((_a = record === null || record === void 0 ? void 0 : record.sdkAgentId) === null || _a === void 0 ? void 0 : _a.startsWith("bc-")) ? record.sdkAgentId : undefined)) !== null && _b !== void 0 ? _b : cloudSdkAgentIdFromEvents(events);
+            if (sdkAgentId === undefined) {
+                return;
+            }
+            const billed = yield this.getCloudUsage(sdkAgentId);
+            if (billed === undefined) {
+                return;
+            }
+            const model = (_c = this.project.agent.model) !== null && _c !== void 0 ? _c : DEFAULT_MODEL;
+            const patched = applyCloudUsageToEvents(events, billed, model);
+            if (patched === undefined) {
+                return;
+            }
+            for (let i = 0; i < patched.length; i++) {
+                const next = patched[i];
+                const prev = events[i];
+                if (next === undefined || prev === next) {
+                    continue;
+                }
+                log.replace(i, next);
+            }
+            if (!(yield log.snapshot(0)).some(event => isUnpricedCompletedTurn(event))) {
+                this.cloudCostBackfillDone.add(sessionId);
+            }
+        });
+    }
+    setContinuationToken(sessionId, token) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const previous = yield this.sessions.get(sessionId);
+            yield this.updateRecord(sessionId, current => (Object.assign(Object.assign({}, current), { continuationKey: token })));
+            // Keep armed reminders addressed at the conversation across channel
+            // continuation rotation.
+            if ((previous === null || previous === void 0 ? void 0 : previous.continuationKey) != null && token !== null && token !== previous.continuationKey) {
+                yield (_a = this.reminderApi) === null || _a === void 0 ? void 0 : _a.rekeyContinuation(previous.channelId, previous.continuationKey, token);
+            }
+        });
+    }
+    isTurnRunning(sessionId) {
+        // Include the admit window (pendingTurns) and coalesce drain so busy
+        // policies do not treat a turn that has finished executeTurn but not yet
+        // resumed queued follow-ups as idle (avoids clearCoalesced races).
+        return (this.activeTurns.has(sessionId) ||
+            this.pendingTurns.has(sessionId) ||
+            this.coalesceDrains.has(sessionId));
+    }
+    sessionInfo(record) {
+        return Object.assign(Object.assign({ id: record.sessionId, channelId: record.channelId, mode: record.mode, purpose: record.purpose === "eval" ? "eval" : "live", dryRun: record.dryRun === true ? true : undefined, asOf: record.asOf, auth: record.auth, continuationKey: record.continuationKey }, (record.title === undefined ? {} : { title: record.title })), (record.sdkAgentId === undefined ? {} : { sdkAgentId: record.sdkAgentId }));
+    }
+    channelSession(sessionId, record, isNew, coalesced = false, since = 0) {
+        return Object.assign(Object.assign({ id: sessionId, continuationToken: record.continuationKey, isNew }, (coalesced ? { coalesced: true } : {})), { info: this.sessionInfo(record), getEventStream: (options) => { var _a; return this.eventStream(sessionId, (_a = options === null || options === void 0 ? void 0 : options.startIndex) !== null && _a !== void 0 ? _a : since); }, waitForCompletion: () => this.waitForCompletion(sessionId), setContinuationToken: (token) => this.setContinuationToken(sessionId, token) });
+    }
+    resolveChannelId(channel) {
+        if (typeof channel === "string") {
+            if (channel !== HTTP_CHANNEL_ID &&
+                !this.channelsById.has(channel) &&
+                !channel.startsWith(SCHEDULE_CHANNEL_PREFIX)) {
+                throw new UnknownChannelError(channel);
+            }
+            return channel;
+        }
+        if (channel.__agentServe === "http-channel") {
+            return HTTP_CHANNEL_ID;
+        }
+        for (const [id, definition] of this.channelsById) {
+            if (definition === channel) {
+                return id;
+            }
+        }
+        throw new UnknownChannelError("<unregistered channel definition>");
+    }
+    initialChannelState(channelId, override) {
+        if (override !== undefined) {
+            return structuredClone(override);
+        }
+        const definition = this.channelsById.get(channelId);
+        if ((definition === null || definition === void 0 ? void 0 : definition.state) === undefined) {
+            return undefined;
+        }
+        return structuredClone(definition.state);
+    }
+    /** Serialized, immutable record updates (latest-wins per session). */
+    updateRecord(sessionId, updater) {
+        var _a;
+        const chain = (_a = this.updateChains.get(sessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
+        const next = chain.then(() => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const current = yield this.sessions.get(sessionId);
+            if (current === undefined) {
+                throw new Error(`Session ${sessionId} not found`);
+            }
+            const updated = Object.assign(Object.assign({}, updater(current)), { updatedAt: new Date().toISOString() });
+            yield this.sessions.save(updated);
+            (_a = this.storage) === null || _a === void 0 ? void 0 : _a.sessionRecord(updated);
+            return updated;
+        }));
+        this.updateChains.set(sessionId, next.catch(() => { }));
+        return next;
+    }
+    // ==========================================================================
+    // Lifecycle
+    // ==========================================================================
+    /**
+     * 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() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const storage = this.storage;
+            if (storage === undefined || !storage.canBulkRestore) {
+                return;
+            }
+            const policy = storage.policy.restore;
+            if (policy === "off") {
+                return;
+            }
+            try {
+                yield this.runBulkRestore(storage, policy);
+            }
+            catch (error) {
+                this.logger(`[agent-sdk] session restore failed: ${describeError(error)}`);
+            }
+        });
+    }
+    runBulkRestore(storage, policy) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const loaded = yield storage.listSessions();
+            // Guardrails on whatever the sink returned: drop invalid rows and
+            // sessions older than the age window, then restore newest-first under
+            // the count cap. Anything filtered out here stays reachable through
+            // the lazy continuation-lookup path.
+            const cutoff = Date.now() - policy.maxAgeMs;
+            const candidates = loaded
+                .map(record => ({
+                record,
+                // Numeric timestamp for both the age filter and the sort; a
+                // non-string updatedAt (e.g. a raw DB Date from an untyped sink)
+                // parses to NaN and is dropped instead of crashing serve start.
+                updatedAt: typeof (record === null || record === void 0 ? void 0 : record.updatedAt) === "string" ? Date.parse(record.updatedAt) : Number.NaN,
+            }))
+                .filter(({ record, updatedAt }) => typeof (record === null || record === void 0 ? void 0 : record.sessionId) === "string" && record.sessionId !== "" && updatedAt >= cutoff)
+                .sort((a, b) => b.updatedAt - a.updatedAt)
+                .slice(0, policy.maxSessions)
+                .map(({ record }) => record);
+            let restored = 0;
+            let budget = policy.maxTotalBytes;
+            // Sink round trips dominate restore latency, so event streams are
+            // fetched with bounded parallelism; writes stay sequential, newest
+            // first, so the byte budget is enforced deterministically.
+            outer: for (let i = 0; i < candidates.length; i += RESTORE_FETCH_CONCURRENCY) {
+                const chunk = candidates.slice(i, i + RESTORE_FETCH_CONCURRENCY);
+                const fetched = yield Promise.all(chunk.map((record) => __awaiter(this, void 0, void 0, function* () {
+                    try {
+                        // Local state always wins over the sink.
+                        if ((yield this.sessions.get(record.sessionId)) !== undefined) {
+                            return undefined;
+                        }
+                        const events = yield storage.listSessionEvents(record.sessionId);
+                        return { record, events };
+                    }
+                    catch (error) {
+                        this.logger(`[agent-sdk] failed to restore session ${record.sessionId}: ${describeError(error)}`);
+                        return undefined;
+                    }
+                })));
+                for (const item of fetched) {
+                    if (item === undefined) {
+                        continue;
+                    }
+                    const ndjson = eventsNdjson(item.events);
+                    // Budget is checked BEFORE anything is written: one oversized
+                    // session cannot blow past maxTotalBytes on disk. Skipped sessions
+                    // stay reachable through the lazy path.
+                    const bytes = Buffer.byteLength(JSON.stringify(item.record), "utf8") +
+                        (ndjson === undefined ? 0 : Buffer.byteLength(ndjson, "utf8"));
+                    if (bytes > budget) {
+                        this.logger(`[agent-sdk] session restore stopped at the ${policy.maxTotalBytes}-byte budget after ${restored} session(s); remaining sessions restore lazily on resume`);
+                        break outer;
+                    }
+                    try {
+                        yield this.materializeSession(item.record, ndjson);
+                        budget -= bytes;
+                        restored += 1;
+                    }
+                    catch (error) {
+                        this.logger(`[agent-sdk] failed to restore session ${item.record.sessionId}: ${describeError(error)}`);
+                    }
+                }
+            }
+            if (restored > 0) {
+                this.logger(`[agent-sdk] restored ${restored} session(s) from storage`);
+            }
+        });
+    }
+    /**
+     * 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) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const local = yield this.sessions.get(sessionId);
+            if (local !== undefined) {
+                return local;
+            }
+            return this.restoreSessionById(sessionId);
+        });
+    }
+    /**
+     * 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}).
+     */
+    restoreSessionByContinuation(channelId, continuationKey) {
+        const storage = this.storage;
+        if (storage === undefined) {
+            return Promise.resolve(undefined);
+        }
+        const key = `${channelId}\u0000${continuationKey}`;
+        let pending = this.restoreInFlight.get(key);
+        if (pending === undefined) {
+            pending = this.loadAndMaterializeByContinuation(storage, channelId, continuationKey).finally(() => this.restoreInFlight.delete(key));
+            this.restoreInFlight.set(key, pending);
+        }
+        return pending;
+    }
+    restoreSessionById(sessionId) {
+        const storage = this.storage;
+        if (storage === undefined) {
+            return Promise.resolve(undefined);
+        }
+        const key = `id\u0000${sessionId}`;
+        let pending = this.restoreInFlight.get(key);
+        if (pending === undefined) {
+            pending = this.loadAndMaterializeById(storage, sessionId).finally(() => this.restoreInFlight.delete(key));
+            this.restoreInFlight.set(key, pending);
+        }
+        return pending;
+    }
+    loadAndMaterializeByContinuation(storage, channelId, continuationKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const record = yield storage.getSessionByContinuation(channelId, continuationKey);
+            if (record === undefined) {
+                // Definitive miss: the caller starts a fresh session under this token.
+                return undefined;
+            }
+            return this.materializeRestoredRecord(record);
+        });
+    }
+    loadAndMaterializeById(storage, sessionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const record = yield storage.getSessionById(sessionId);
+            if (record === undefined) {
+                return undefined;
+            }
+            return this.materializeRestoredRecord(record);
+        });
+    }
+    materializeRestoredRecord(record) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const local = yield this.sessions.get(record.sessionId);
+            if (local !== undefined) {
+                return local;
+            }
+            const storage = this.storage;
+            if (storage === undefined) {
+                return record;
+            }
+            const events = yield storage.listSessionEvents(record.sessionId);
+            // The durable record's bookkeeping may lag the event stream (the
+            // storage coordinator skips volatile-only record rewrites, bounded).
+            // New turnIds mint from turnCount, so clamp it to the highest turn the
+            // stream already used — otherwise a replaced pod re-mints turn_N ids
+            // and trajectory/cost grouping merges unrelated turns.
+            const restored = withTurnCountClampedToEvents(record, events);
+            yield this.materializeSession(restored, eventsNdjson(events));
+            this.logger(`[agent-sdk] lazily restored session ${restored.sessionId} from storage`);
+            return restored;
+        });
+    }
+    /**
+     * 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.
+     */
+    materializeSession(record, eventsNdjson) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (eventsNdjson !== undefined) {
+                const filePath = this.sessions.eventFilePath(record.sessionId);
+                yield mkdir(dirname(filePath), { recursive: true });
+                yield writeFile(filePath, eventsNdjson, "utf8");
+            }
+            yield this.sessions.save(record);
+        });
+    }
+    trackBackground(promise) {
+        this.backgroundWork.add(promise);
+        void promise
+            .catch(() => { })
+            .finally(() => {
+            this.backgroundWork.delete(promise);
+        });
+    }
+    /** In-process event-log residency (OOM-suspect cache vs durable count). */
+    eventLogMemoryStats() {
+        return this.logs.memoryStats();
+    }
+    /** Drain running turns, dispatches, and pending writes, then dispose. */
+    close() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e;
+            (_a = this.stopMemoryTelemetry) === null || _a === void 0 ? void 0 : _a.call(this);
+            this.approvals.cancelAll("deny");
+            this.auths.cancelAll("deny");
+            yield this.oauthHub.close();
+            yield Promise.allSettled([...this.activeTurns.values()]);
+            yield Promise.allSettled([...this.backgroundWork]);
+            yield Promise.allSettled([...this.dispatchChains.values()]);
+            yield Promise.allSettled([...this.updateChains.values()]);
+            // After the drain, so a successor need not wait out the heartbeat TTL.
+            yield this.turnLeases.releaseAll().catch(() => { });
+            yield this.logs.flushAll();
+            yield (_b = this.storage) === null || _b === void 0 ? void 0 : _b.close();
+            yield this.mcpHost.close();
+            yield (_d = (_c = this.runner).dispose) === null || _d === void 0 ? void 0 : _d.call(_c);
+            (_e = this.otel) === null || _e === void 0 ? void 0 : _e.close();
+        });
+    }
+}
+/** Parallel event-stream loads during the startup bulk restore. */
+const RESTORE_FETCH_CONCURRENCY = 8;
+/**
+ * Newest-written sink rows fetched for `GET /v1/sessions?latest=1` when the
+ * local store has nothing for the caller. Wide enough that the caller's own
+ * session is normally inside it even when other principals are busier.
+ */
+const LATEST_SESSION_SINK_WINDOW = 50;
+/** NDJSON payload for a restored event stream; undefined when empty. */
+function mergePendingImages(current, incoming) {
+    if (incoming === undefined) {
+        return current;
+    }
+    if (current === undefined || current.length === 0) {
+        return incoming;
+    }
+    return [...current, ...incoming];
+}
+function mergePendingWorkspaceFiles(current, incoming) {
+    if (incoming === undefined) {
+        return current;
+    }
+    if (current === undefined) {
+        return incoming;
+    }
+    return Object.assign(Object.assign({}, current), incoming);
+}
+function eventsNdjson(events) {
+    if (events.length === 0) {
+        return undefined;
+    }
+    return `${events.map(event => JSON.stringify(event)).join("\n")}\n`;
+}
+/**
+ * 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 function withTurnCountClampedToEvents(record, events) {
+    let maxTurn = 0;
+    for (const event of events) {
+        const turnId = event.turnId;
+        if (typeof turnId !== "string") {
+            continue;
+        }
+        const match = /^turn_(\d+)$/.exec(turnId);
+        if ((match === null || match === void 0 ? void 0 : match[1]) !== undefined) {
+            const turn = Number(match[1]);
+            if (Number.isSafeInteger(turn) && turn > maxTurn) {
+                maxTurn = turn;
+            }
+        }
+    }
+    return maxTurn > record.turnCount ? Object.assign(Object.assign({}, record), { turnCount: maxTurn }) : record;
+}
+function subagentPrompt(subagent) {
+    var _a;
+    if (subagent.instructions !== undefined && subagent.instructions !== "") {
+        return subagent.instructions;
+    }
+    return (_a = subagent.description) !== null && _a !== void 0 ? _a : subagent.name;
+}
+/**
+ * Subagents as the runner takes them. Shared by turns and by workspace
+ * warming, which has to describe the same agent a turn would to reach the
+ * executor that turn will run on.
+ */
+function buildRunnerSubagents(agent) {
+    return agent.subagents.map(subagent => { var _a; return (Object.assign({ name: subagent.name, description: (_a = subagent.description) !== null && _a !== void 0 ? _a : subagent.name, prompt: subagentPrompt(subagent) }, (subagent.model === undefined ? {} : { model: subagent.model }))); });
+}
+function toolErrorResult(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+function defaultGetCloudUsage(sdkAgentId) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const { Agent } = yield import("@cursor/sdk");
+            const billed = yield Agent.getUsage(sdkAgentId);
+            return {
+                usage: mapSdkTokenUsage(billed.usage),
+                cost: billed.cost,
+                runs: billed.runs.map(run => ({
+                    runId: run.runId,
+                    usage: mapSdkTokenUsage(run.usage),
+                    cost: run.cost,
+                })),
+            };
+        }
+        catch (_a) {
+            return undefined;
+        }
+    });
+}
+/** Detects the `{ content, isError: true }` rich-result error envelope. */
+function isErrorEnvelope(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        !Array.isArray(result) &&
+        Array.isArray(result.content) &&
+        result.isError === true);
+}
+function evaluateNeedsApproval(needsApproval, input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (needsApproval === undefined || needsApproval === false) {
+            return false;
+        }
+        if (needsApproval === true) {
+            return true;
+        }
+        return Boolean(yield needsApproval(input));
+    });
+}
+function approvalResolverLabel(auth) {
+    var _a;
+    if (auth === null) {
+        return undefined;
+    }
+    const slackUser = (_a = auth.attributes) === null || _a === void 0 ? void 0 : _a.user_id;
+    if (auth.authenticator === "slack" && slackUser !== undefined && slackUser !== "") {
+        return slackUser;
+    }
+    return auth.principalId;
+}
+/** Let the HTTP NDJSON writer flush before the next SDK update. */
+function yieldEventLoop() {
+    return new Promise(resolve => {
+        setImmediate(resolve);
+    });
+}
+function lastBotMessageTsOf(state) {
+    if (state === null || state === undefined || typeof state !== "object") {
+        return undefined;
+    }
+    const ts = state.lastBotMessageTs;
+    return typeof ts === "string" && ts.trim() !== "" ? ts.trim() : undefined;
+}
+function laterLastBotMessageTs(a, b) {
+    if (a === undefined) {
+        return b;
+    }
+    if (b === undefined) {
+        return a;
+    }
+    const aN = Number(a);
+    const bN = Number(b);
+    if (Number.isFinite(aN) && Number.isFinite(bN)) {
+        return aN >= bN ? a : b;
+    }
+    if (Number.isFinite(aN)) {
+        return a;
+    }
+    if (Number.isFinite(bN)) {
+        return b;
+    }
+    return a;
+}