@cursor/july 0.1.95 → 0.1.97

package/dist/internal/session-engine.js

@@ -15,6 +15,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+import { AsyncLocalStorage } from "node:async_hooks";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { mergeABInstructions, resolveABMaxPlaygroundSessions, resolveABSplit, } from "../ab.js";
@@ -24,11 +25,11 @@ import { SlackAskDedupeStore, SlackNudgeStore, } from "../channels/slack/nudge-s
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
 import { AGENT_SERVE_USER_STORE_FILES_SOURCE_ID, agentStoreKeys, } from "../files.js";
 import { cursorHostedFiles, isCursorHostedFilesAvailable, isCursorUserStoreFilesAvailable, } from "../files-backends/cursor-hosted.js";
-import { DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, isHostOauthConnectionTransport, isSymbolicConnectionTransport, } from "../types.js";
+import { DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, isCursorAccountTransport, isHostOauthConnectionTransport, isSymbolicConnectionTransport, } from "../types.js";
 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 { resolveAdvertisedTools, } from "./advertise-tools.js";
 import { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
 import { SessionAuthError, samePrincipal } from "./auth.js";
@@ -47,19 +48,22 @@ import { createHostPlatforms, createHostSlackClient, } from "./host-platforms.js
 import { HostedAdmissionLocalSendError, isDuringHostedAdmission, } from "./hosted-admission-context.js";
 import { formatContinuationToken, newContinuationKey, newSessionId, newToolCallId, parseContinuationToken, } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
-import { McpHost } from "./mcp-host.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 } from "./storage-coordinator.js";
-import { decideToolCall, resolveEffect } from "./tool-policy.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 { 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";
@@ -133,6 +137,19 @@ export class ApprovalInterruptedError extends Error {
         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();
 export class SessionEngine {
     constructor(options) {
         var _a, _b, _c, _d, _e;
@@ -142,6 +159,13 @@ export class SessionEngine {
         /** 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();
         /**
@@ -178,6 +202,8 @@ export class SessionEngine {
         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). */
@@ -202,6 +228,7 @@ export class SessionEngine {
         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
@@ -283,10 +310,20 @@ export class SessionEngine {
     setCloudServerToolsConnection(connection) {
         this.cloudServerToolsConnection = connection;
     }
+    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.mcpHost,
+            mcp: this.wrapMcp(this.mcpHost),
             github: this.platforms.github,
             slack: this.platforms.slack,
             reminders: this.reminderApi,
@@ -396,6 +433,9 @@ export class SessionEngine {
                 this.hasBorrowedWorkspace(record)) {
                 return;
             }
+            if (steeringEnabled()) {
+                return;
+            }
             try {
                 yield materializeSlackNudgeCarrier({
                     harnessCwd,
@@ -580,12 +620,33 @@ export class SessionEngine {
             const now = new Date().toISOString();
             const channelState = this.initialChannelState(channelId, sendOptions.state);
             const purpose = sendOptions.purpose === "eval" ? "eval" : "live";
-            let record = Object.assign(Object.assign({ sessionId: (_d = sendOptions.hostedSessionId) !== null && _d !== void 0 ? _d : newSessionId(), channelId, mode: (_e = sendOptions.mode) !== null && _e !== void 0 ? _e : "chat", purpose }, (sendOptions.dryRun === true ? { dryRun: true } : {})), { continuationKey: (_f = sendOptions.continuationToken) !== null && _f !== void 0 ? _f : 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 });
+            let record = {
+                sessionId: (_d = sendOptions.hostedSessionId) !== null && _d !== void 0 ? _d : newSessionId(),
+                channelId,
+                mode: (_e = sendOptions.mode) !== null && _e !== void 0 ? _e : "chat",
+                purpose,
+                dryRun: sendOptions.dryRun === true ? true : undefined,
+                continuationKey: (_f = sendOptions.continuationToken) !== null && _f !== void 0 ? _f : 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);
             (_a = this.storage) === null || _a === void 0 ? void 0 : _a.sessionRecord(record);
             yield this.appendEvent(record.sessionId, {
                 type: "session.started",
-                data: { channelId },
+                data: {
+                    channelId,
+                    dryRun: record.dryRun === true ? true : undefined,
+                },
             });
             record = yield this.enrollABs(record);
             const since = (yield this.logs.get(record.sessionId)).count;
@@ -787,10 +848,28 @@ export class SessionEngine {
         const prior = (_a = this.admissionChains.get(sessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
         const admitted = prior
             .catch(() => { })
-            .then(() => this.admitTurn(sessionId, message, options));
+            .then(() => __awaiter(this, void 0, void 0, function* () {
+            // Another server holds the turn: hand the message to it and coalesce.
+            if (yield this.turnLeases.runningElsewhere(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 : [];
@@ -901,14 +980,46 @@ export class SessionEngine {
             });
         });
     }
+    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, Object.assign({ message }, (options.sourceTs === undefined
-                    ? {}
-                    : { sourceTs: options.sourceTs })));
+                this.enqueueCoalesced(sessionId, {
+                    message,
+                    sourceTs: options.sourceTs,
+                });
                 this.logger(`[session] coalesce enqueue ${sessionId}`);
                 return true;
             }
@@ -968,6 +1079,8 @@ export class SessionEngine {
                 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);
                     }
@@ -977,6 +1090,9 @@ export class SessionEngine {
                             errorMessage: describeError(error),
                         };
                     }
+                    finally {
+                        clearInterval(poll);
+                    }
                     this.lastOutcomes.set(sessionId, outcome);
                     const wasCurrent = this.activeTurns.get(sessionId) === lifecycle;
                     if (wasCurrent) {
@@ -1002,6 +1118,10 @@ 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();
+                    // 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);
@@ -1051,6 +1171,7 @@ export class SessionEngine {
                 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) {
@@ -1239,6 +1360,7 @@ export class SessionEngine {
                         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
@@ -1301,12 +1423,15 @@ export class SessionEngine {
                 }
                 catch (error) {
                     this.approvals.cancelSession(sessionId, "deny");
+                    this.auths.cancelSession(sessionId, "deny");
                     outcome = { status: "error", errorMessage: describeError(error) };
                 }
                 finally {
                     permit.release();
                     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);
@@ -1797,11 +1922,17 @@ export class SessionEngine {
             // 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({
+            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.mcpHost,
-            })) {
+                hostMcp: this.advertiseMcp(),
+            }))) {
                 register(tool);
             }
             return tools;
@@ -1909,7 +2040,13 @@ export class SessionEngine {
                 }
                 const started = Date.now();
                 this.logger(`[session] tool ${args.tool.name} start`);
-                const result = yield execute(validation.value, toolCtx);
+                const result = yield 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);
             }
@@ -1934,7 +2071,7 @@ export class SessionEngine {
                 args: args.args,
                 requestedAt,
             };
-            const resolutionPromise = this.approvals.wait(Object.assign({ sessionId: args.sessionId }, pendingRecord));
+            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,
@@ -2020,6 +2157,245 @@ export class SessionEngine {
             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);
+        });
+    }
+    authoredConnection(name) {
+        var _a;
+        var _b;
+        return ((_b = this.project.agent.connections.find((entry) => entry.name === name)) !== null && _b !== void 0 ? _b : (_a = this.project.agent.hostConnections) === null || _a === void 0 ? void 0 : _a.find((entry) => entry.name === name));
+    }
+    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)
     // ==========================================================================
@@ -2034,8 +2410,10 @@ export class SessionEngine {
      * 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.
-     * Rejected with {@link SessionBusyError} while a model turn is running.
-     * Without a session, the tool runs against an **ephemeral** scratch
+     * 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).
      *
@@ -2075,26 +2453,22 @@ export class SessionEngine {
                     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 turn serialization, same
-                // event recording as an explicit sessionId. Skipping those just
-                // because the caller addressed the session by token would fail open.
+                // 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) {
-                // Direct calls respect the same serialization as follow-up sends: a
-                // running model turn owns the session workspace and event stream.
-                if (this.activeTurns.has(record.sessionId) ||
-                    this.pendingTurns.has(record.sessionId)) {
-                    throw new SessionBusyError(record.sessionId);
-                }
                 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
@@ -2114,6 +2488,7 @@ export class SessionEngine {
                 },
                 workspaceDir: scratchDir,
                 scratchDir,
+                busy: false,
             };
         });
     }
@@ -2146,8 +2521,32 @@ export class SessionEngine {
             };
         });
     }
+    /**
+     * 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;
             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
@@ -2167,7 +2566,7 @@ export class SessionEngine {
                 const advertised = yield resolveAdvertisedTools({
                     agent: this.project.agent,
                     session,
-                    hostMcp: this.mcpHost,
+                    hostMcp: this.advertiseMcp(),
                 });
                 tool = advertised.find((t) => t.name === toolName);
             }
@@ -2184,6 +2583,17 @@ export class SessionEngine {
             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 });
@@ -2203,28 +2613,50 @@ export class SessionEngine {
                 // 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 ||
-                    resolveEffect(tool.definition.effect, validation.value) === "read";
+                    directCallEffect(tool, validation.value) === "read";
                 if (!relocatable) {
                     throw new WorkspaceUnavailableError(toolName, error);
                 }
-                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 });
+                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.
-            yield materializeWorkspace({
-                agent: this.project.agent,
-                workspaceDir: record === undefined || workspaceUnavailable
-                    ? workspaceDir
-                    : this.scaffoldDir(record),
-                seed: record === undefined || workspaceUnavailable || record.turnCount === 0,
-                stateRoot: this.stateRoot,
-            });
+            // 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 (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) {
@@ -2267,7 +2699,7 @@ export class SessionEngine {
                     isError = false;
                 }
                 else {
-                    result = normalizeToolResult(yield execute(validation.value, {
+                    const run = () => execute(validation.value, {
                         toolCallId: callId,
                         session,
                         workspaceDir,
@@ -2285,7 +2717,16 @@ export class SessionEngine {
                                 : session.auth })),
                         getSession: (channelId, sessionId) => this.getChannelSession(channelId, sessionId),
                         emit,
-                    }));
+                    });
+                    result = normalizeToolResult(record !== undefined && emit !== undefined
+                        ? yield mcpAuthAls.run({
+                            sessionId: record.sessionId,
+                            turnId: callId,
+                            callId,
+                            toolName,
+                            emit,
+                        }, run)
+                        : yield run());
                     isError = isErrorEnvelope(result);
                 }
             }
@@ -2513,6 +2954,29 @@ export class SessionEngine {
     // ==========================================================================
     // 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.
+     */
+    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(() => { });
+            }
+            yield this.storage.whenIdle();
+        });
+    }
     waitForCompletion(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
@@ -2629,6 +3093,64 @@ export class SessionEngine {
             };
         });
     }
+    /**
+     * 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
@@ -2675,6 +3197,7 @@ export class SessionEngine {
                     : 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
@@ -2947,7 +3470,7 @@ export class SessionEngine {
             this.coalesceDrains.has(sessionId));
     }
     sessionInfo(record) {
-        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ id: record.sessionId, channelId: record.channelId, mode: record.mode, purpose: record.purpose === "eval" ? "eval" : "live" }, (record.dryRun === true ? { dryRun: true } : {})), { auth: record.auth, continuationKey: record.continuationKey }), (record.abs === undefined ? {} : { abs: record.abs })), (record.title === undefined ? {} : { title: record.title })), (record.sdkAgentId === undefined
+        return Object.assign(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, auth: record.auth, continuationKey: record.continuationKey }, (record.abs === undefined ? {} : { abs: record.abs })), (record.title === undefined ? {} : { title: record.title })), (record.sdkAgentId === undefined
             ? {}
             : { sdkAgentId: record.sdkAgentId }));
     }
@@ -3232,6 +3755,8 @@ export class SessionEngine {
             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()]);
@@ -3248,6 +3773,12 @@ export class SessionEngine {
 }
 /** 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) {