@cursor/july 0.1.62 → 0.1.73

package/dist/internal/session-engine.js

@@ -18,6 +18,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { mergeABInstructions, resolveABMaxPlaygroundSessions, resolveABSplit, } from "../ab.js";
+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 { isCursorHostedFilesAvailable } from "../files-backends/cursor-hosted.js";
@@ -27,6 +29,7 @@ import { DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, isHostOauthConnectionTransp
 import { ABCollector } from "./ab-collector.js";
 import { foldABStream } from "./ab-fold.js";
 import { buildABSnapshot } from "./ab-snapshot.js";
+import { resolveAdvertisedTools } from "./advertise-tools.js";
 import { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
 import { SessionAuthError, samePrincipal } from "./auth.js";
@@ -54,7 +57,8 @@ import { StorageCoordinator } from "./storage-coordinator.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import { estimateTurnCostFromApi, roundCostUsd, } from "./turn-cost.js";
 import { TurnGovernor } from "./turn-governor.js";
-import { buildAgentsMdContent, buildCloudMemorySection, isNestedInGitRepo, materializeWorkspace, SERVER_TOOLS_MCP_SERVER_NAME, writeWorkspaceFiles, } from "./workspace.js";
+import { TurnLeaseStore } from "./turn-lease-store.js";
+import { buildAgentsMdContent, buildCloudMemorySection, ensureOwnGitRoot, isNestedInGitRepo, materializeWorkspace, SERVER_TOOLS_MCP_SERVER_NAME, writeWorkspaceFiles, } from "./workspace.js";
 export const HTTP_CHANNEL_ID = "http";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 export class SessionBusyError extends Error {
@@ -121,6 +125,12 @@ export class SessionEngine {
         this.activeTurns = new Map();
         /** Context used by the cloud turn's HTTP MCP callbacks. */
         this.activeToolContexts = 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). */
@@ -162,6 +172,7 @@ export class SessionEngine {
         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.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
@@ -405,6 +416,102 @@ export class SessionEngine {
             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;
+            }
+            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),
@@ -697,6 +804,61 @@ export class SessionEngine {
     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;
@@ -722,8 +884,17 @@ export class SessionEngine {
                 return;
             }
             this.coalesceQueues.delete(sessionId);
-            const message = this.formatCoalescedFollowups(queued);
-            this.logger(`[session] coalesce drain starting follow-up (${queued.length}) ${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,
@@ -741,6 +912,14 @@ export class SessionEngine {
                 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.
+            if (yield this.turnLeases.runningElsewhere(sessionId)) {
+                this.logger(`[session] coalesce; another server owns ${sessionId}`);
+                return true;
+            }
             // 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:
@@ -754,7 +933,20 @@ export class SessionEngine {
             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 {
                 let record = yield this.updateRecord(sessionId, (current) => (Object.assign(Object.assign({}, current), { turnCount: current.turnCount + 1 })));
                 // Arms must be on the record before tools/instructions see SessionInfo.
@@ -807,12 +999,21 @@ export class SessionEngine {
                             }
                         }
                     }
+                    // 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();
                     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;
         });
@@ -955,9 +1156,15 @@ export class SessionEngine {
             }
             const startedAt = Date.now();
             try {
-                const outcome = yield this.runner.prewarm(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 }, (agent.allowedTools === undefined
+                const outcome = yield this.runner.prewarm(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 }, (agent.allowedTools === undefined
                     ? {}
-                    : { tools: agent.allowedTools })), { mcpServers: this.buildMcpServers("local"), subagents: buildRunnerSubagents(agent) }), (agent.model === undefined ? {} : { model: agent.model })));
+                    : { tools: agent.allowedTools })), { 
+                    // 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()
+                    ? { 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.
@@ -1029,6 +1236,18 @@ export class SessionEngine {
                         seed: isFirstTurn,
                         stateRoot: this.stateRoot,
                     });
+                    // 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;
                     if (pendingFiles !== undefined &&
@@ -1052,7 +1271,7 @@ export class SessionEngine {
                     const instructionsInvisibleToHarness = isFirstTurn &&
                         (this.hasBorrowedWorkspace(record) ||
                             (yield isNestedInGitRepo(harnessCwd)));
-                    const request = this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, instructionsInvisibleToHarness, emit, (update) => __awaiter(this, void 0, void 0, function* () {
+                    const request = yield this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, instructionsInvisibleToHarness, emit, (update) => __awaiter(this, void 0, void 0, function* () {
                         mapper.handleUpdate(update);
                         // Yield so the HTTP NDJSON writer can flush tool start/result
                         // events while sibling parallel tools are still executing.
@@ -1061,6 +1280,9 @@ export class SessionEngine {
                             // 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();
                         }
                     }), signal, pendingImages);
@@ -1080,6 +1302,9 @@ export class SessionEngine {
                     permit.release();
                     this.approvals.cancelSession(sessionId, "deny");
                     yield this.clearPendingApprovals(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();
@@ -1143,88 +1368,106 @@ export class SessionEngine {
         });
     }
     buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, instructionsInvisibleToHarness, emit, onUpdate, signal, images) {
-        var _a, _b, _c;
-        // 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: the SDK cannot enforce the built-in tool allowlist on
-        // cloud agents yet, and a restriction that silently does not apply is
-        // worse than a refused turn. Cloud-runtime agents already fail
-        // discovery; this guards hybrid agents' per-send cloud sessions.
-        if (runtime === "cloud" && agent.allowedTools !== undefined) {
-            throw new Error(`Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on cloud turns yet. Refusing the cloud session rather than running it unrestricted.`);
-        }
-        const mergedCloud = runtime === "cloud"
-            ? mergeCloudOptions({
-                base: agent.cloud,
-                override: record.cloudOverride,
-            })
-            : undefined;
-        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",
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            // 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,
             });
-            turnPrompt = `${contextBlock}\n\n${prompt}`;
-        }
-        if (isFirstTurn) {
-            if (runtime === "cloud") {
-                // Cloud VMs have no materialized workspace: ship the full context,
-                // including agent tool script bodies. On hosted deployments the
-                // shared memory journal is on the store mount — 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 preamble = buildAgentsMdContent(agent, {
-                    includeScripts: true,
-                    serverToolsMcpName: this.cloudServerToolsConnection === undefined
-                        ? undefined
-                        : SERVER_TOOLS_MCP_SERVER_NAME,
+            // Fail closed: the SDK cannot enforce the built-in tool allowlist on
+            // cloud agents yet, and a restriction that silently does not apply is
+            // worse than a refused turn. Cloud-runtime agents already fail
+            // discovery; this guards hybrid agents' per-send cloud sessions.
+            if (runtime === "cloud" && agent.allowedTools !== undefined) {
+                throw new Error(`Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on cloud turns yet. Refusing the cloud 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 MCP config. A turn
+            // that silently runs without its per-session tools or identity is worse
+            // than a refused one. Cloud-runtime 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 === "cloud" && perSessionConnection !== undefined) {
+                throw new Error(`Agent "${agent.name}" connection "${perSessionConnection.name}" uses advertiseTools/auth, which only run on local turns. Refusing the cloud session rather than running it without the connection's tools or identity.`);
+            }
+            const mergedCloud = runtime === "cloud"
+                ? mergeCloudOptions({
+                    base: agent.cloud,
+                    override: record.cloudOverride,
+                })
+                : undefined;
+            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",
                 });
-                const memorySection = isCursorHostedFilesAvailable()
-                    ? `\n\n${buildCloudMemorySection(this.project.name)}`
-                    : "";
-                turnPrompt = `${preamble}${memorySection}\n\n${turnPrompt}`;
-            }
-            else if (instructionsInvisibleToHarness) {
-                // Local workspace whose AGENTS.md the harness will not load. With a
-                // borrowed harness cwd, agent tool scripts live only in the durable
-                // scaffold dir — embed bodies like cloud. Otherwise the catalog can
-                // reference on-disk paths under the harness cwd.
-                const includeScripts = this.hasBorrowedWorkspace(record);
-                const preamble = buildAgentsMdContent(agent, { includeScripts });
-                turnPrompt = `${preamble}\n\n${turnPrompt}`;
-            }
-        }
-        return 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: ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true }), (runtime === "local" && agent.allowedTools !== undefined
-            ? { tools: agent.allowedTools }
-            : {})), { runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { customTools: runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {}, mcpServers: this.buildMcpServers(runtime, record.sessionId), 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, onSdkAgentId: (sdkAgentId) => __awaiter(this, void 0, void 0, function* () {
-                if (record.sdkAgentId === sdkAgentId) {
-                    return;
+                turnPrompt = `${contextBlock}\n\n${prompt}`;
+            }
+            if (isFirstTurn) {
+                if (runtime === "cloud") {
+                    // Cloud VMs have no materialized workspace: ship the full context,
+                    // including agent tool script bodies. On hosted deployments the
+                    // shared memory journal is on the store mount — 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 preamble = buildAgentsMdContent(agent, {
+                        includeScripts: true,
+                        serverToolsMcpName: this.cloudServerToolsConnection === undefined
+                            ? undefined
+                            : SERVER_TOOLS_MCP_SERVER_NAME,
+                    });
+                    const memorySection = isCursorHostedFilesAvailable()
+                        ? `\n\n${buildCloudMemorySection(this.project.name)}`
+                        : "";
+                    turnPrompt = `${preamble}${memorySection}\n\n${turnPrompt}`;
                 }
-                yield this.updateRecord(record.sessionId, (current) => (Object.assign(Object.assign({}, current), { sdkAgentId })));
-                record.sdkAgentId = sdkAgentId;
-                yield this.appendEvent(record.sessionId, {
-                    type: "agent.bound",
-                    turnId,
-                    data: Object.assign({ sdkAgentId }, (sdkAgentId.startsWith("bc-")
-                        ? { url: `https://cursor.com/agents/${sdkAgentId}` }
-                        : {})),
-                });
-            }) });
+                else if (instructionsInvisibleToHarness) {
+                    // Local workspace whose AGENTS.md the harness will not load. With a
+                    // borrowed harness cwd, agent tool scripts live only in the durable
+                    // scaffold dir — embed bodies like cloud. Otherwise the catalog can
+                    // reference on-disk paths under the harness cwd.
+                    const includeScripts = this.hasBorrowedWorkspace(record);
+                    const preamble = buildAgentsMdContent(agent, { includeScripts });
+                    turnPrompt = `${preamble}\n\n${turnPrompt}`;
+                }
+            }
+            return 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: ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true }), (runtime === "local" && agent.allowedTools !== undefined
+                ? { tools: agent.allowedTools }
+                : {})), { runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { customTools: runtime === "local"
+                    ? yield this.buildCustomTools(record, agent, turnId, emit)
+                    : {}, mcpServers: this.buildMcpServers(runtime, record.sessionId, yield this.evaluateConnectionAuth(record)) }), (runtime === "local" && this.hasAttachedAuthedConnections()
+                ? { 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;
+                    yield this.appendEvent(record.sessionId, {
+                        type: "agent.bound",
+                        turnId,
+                        data: Object.assign({ sdkAgentId }, (sdkAgentId.startsWith("bc-")
+                            ? { url: `https://cursor.com/agents/${sdkAgentId}` }
+                            : {})),
+                    });
+                }) });
+        });
     }
     /**
      * Connection names a cloud turn can only reach through the host connection
@@ -1288,9 +1531,12 @@ export class SessionEngine {
      * mount as host connection bridges over the tool MCP endpoint instead of
      * being omitted or failing the turn closed.
      */
-    buildMcpServers(runtime, sessionId) {
+    buildMcpServers(runtime, sessionId, sessionAuth) {
+        // Advertised connections surface as named server tools instead of an
+        // attached MCP server (each tool appears exactly once), so they are
+        // excluded here alongside hostOnly.
         const hostOnlyNames = new Set(this.project.agent.connections
-            .filter((connection) => connection.hostOnly === true)
+            .filter((connection) => connection.hostOnly === true || connection.advertiseTools === true)
             .map((connection) => connection.name));
         const bridgedNames = new Set(runtime === "cloud" &&
             sessionId !== undefined &&
@@ -1327,6 +1573,20 @@ export class SessionEngine {
                 }
                 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) {
@@ -1365,32 +1625,88 @@ export class SessionEngine {
         }
         return servers;
     }
-    buildCustomTools(record, turnId, emit) {
-        const tools = {};
-        for (const tool of this.project.agent.tools) {
-            if (tool.execution !== "server") {
-                continue;
+    /**
+     * True when a connection with per-session `auth` attaches to the model
+     * (not `hostOnly`, 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.hostOnly !== true &&
+            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.hostOnly !== true &&
+                connection.advertiseTools !== true);
+            if (authed.length === 0) {
+                return undefined;
             }
-            const execute = tool.definition.execute;
-            if (typeof execute !== "function") {
-                continue;
+            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 });
+                }
             }
-            tools[tool.name] = {
-                description: tool.description,
-                inputSchema: tool.inputSchema,
-                execute: (args, context) => __awaiter(this, void 0, void 0, function* () {
-                    return this.executeServerTool({
-                        tool,
-                        input: args,
-                        toolCallId: context.toolCallId,
-                        record,
-                        turnId,
-                        emit,
-                    });
-                }),
+            return evaluated;
+        });
+    }
+    buildCustomTools(record, agent, turnId, emit) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const tools = {};
+            const register = (tool) => {
+                tools[tool.name] = Object.assign(Object.assign({ description: tool.description, inputSchema: tool.inputSchema }, (tool.outputSchema === undefined
+                    ? {}
+                    : { outputSchema: tool.outputSchema })), { execute: (args, context) => __awaiter(this, void 0, void 0, function* () {
+                        return this.executeServerTool({
+                            tool,
+                            input: args,
+                            toolCallId: context.toolCallId,
+                            record,
+                            turnId,
+                            emit,
+                        });
+                    }) });
             };
-        }
-        return tools;
+            for (const tool of agent.tools) {
+                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 resolveAdvertisedTools({
+                agent,
+                session: this.sessionInfo(record),
+                hostMcp: this.mcpHost,
+            })) {
+                register(tool);
+            }
+            return tools;
+        });
     }
     /**
      * True while `sessionId` has a turn in flight. The host connection bridge
@@ -2577,6 +2893,8 @@ export class SessionEngine {
             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 (_c = this.storage) === null || _c === void 0 ? void 0 : _c.close();
             yield this.mcpHost.close();