@cursor/july 0.1.96 → 0.1.99

package/src/internal/session-engine.ts

@@ -7,6 +7,7 @@
  * event handlers and hooks.
  */
 
+import { AsyncLocalStorage } from "node:async_hooks";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { SDKCustomTool, SDKCustomToolResult } from "@cursor/sdk";
@@ -52,12 +53,15 @@ import {
   type DiscoveredTool,
   type HookHandler,
   type HostContext,
+  type HostMcpRegistry,
   type HttpChannelDefinition,
+  isCursorAccountTransport,
   isHostOauthConnectionTransport,
   isSymbolicConnectionTransport,
   type JsonValue,
   type McpToolAnnotations,
   type PendingApproval,
+  type PendingAuth,
   type ReceiveInput,
   type ResolvedAgent,
   type RunnerSubagent,
@@ -79,9 +83,13 @@ import {
 import { ABCollector } from "./ab-collector.js";
 import { foldABStream } from "./ab-fold.js";
 import { type ABSnapshot, buildABSnapshot } from "./ab-snapshot.js";
-import { resolveAdvertisedTools } from "./advertise-tools.js";
+import {
+  type AdvertiseHostMcp,
+  resolveAdvertisedTools,
+} from "./advertise-tools.js";
 import { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
+import { assertTimeArgs, normalizeAsOf, sessionClock } from "./as-of.js";
 import { SessionAuthError, samePrincipal } from "./auth.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import {
@@ -125,7 +133,8 @@ import {
   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 type { OtelCollector } from "./otel/collector.js";
 import {
   shouldStartProcessMemoryTelemetry,
@@ -143,7 +152,7 @@ import { syncSkillsToStore } from "./skills-sync.js";
 import { steeringEnabled } from "./steering.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
 import type { FrameworkSessionStore } from "./storage-roles.js";
-import { decideToolCall, resolveEffect } from "./tool-policy.js";
+import { decideToolCall, directCallEffect } from "./tool-policy.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import {
   type EstimateTurnCostFn,
@@ -152,6 +161,7 @@ import {
 } 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,
@@ -258,6 +268,22 @@ export class ApprovalInterruptedError extends Error {
   }
 }
 
+export class AuthNotFoundError extends Error {
+  constructor(sessionId: string, callId: string) {
+    super(`No pending MCP auth for session ${sessionId} call ${callId}`);
+    this.name = "AuthNotFoundError";
+  }
+}
+
+export class AuthInterruptedError extends Error {
+  constructor(sessionId: string, callId: string) {
+    super(
+      `MCP auth for session ${sessionId} call ${callId} is no longer live (host may have restarted while the tool was parked)`
+    );
+    this.name = "AuthInterruptedError";
+  }
+}
+
 export interface SessionEngineOptions {
   project: AgentProject;
   stateRoot: string;
@@ -312,6 +338,16 @@ interface ActiveToolContext {
   emit: (payload: SessionEventPayload) => void;
 }
 
+type McpAuthParkCtx = {
+  sessionId: string;
+  turnId: string;
+  callId: string;
+  toolName: string;
+  emit: (payload: SessionEventPayload) => void;
+};
+
+const mcpAuthAls = new AsyncLocalStorage<McpAuthParkCtx>();
+
 export interface EngineSendOptions extends SendMessageOptions {
   mode?: "chat" | "task";
   /**
@@ -346,6 +382,8 @@ export class SessionEngine {
   readonly askDedupe: SlackAskDedupeStore;
   /** Cross-process turn ownership under `<stateRoot>/turn-leases`. */
   readonly turnLeases: TurnLeaseStore;
+  /** Messages for turns another server owns, under `<stateRoot>/outbox`. */
+  readonly outbox: TurnOutbox<AdmitTurnOptions>;
   /**
    * Runtime for `agent/storage.ts` (`defineStorage`), when
    * authored. All durable state changes funnel through it (session
@@ -370,6 +408,13 @@ export class SessionEngine {
   /** Sessions with a turn being admitted (before the run promise exists). */
   private readonly pendingTurns = new Set<string>();
   private readonly activeTurns = new Map<string, Promise<TurnOutcome>>();
+  /**
+   * Sessions whose workspace a turn in this process has materialized. A
+   * session is busy from admit — before the governor slot and the turn's
+   * own materialize — so a read running alongside a turn consults this,
+   * not busy, to know whether the workspace is ready to be left alone.
+   */
+  private readonly materializedWorkspaces = new Set<string>();
   /** Context used by the cloud turn's HTTP MCP callbacks. */
   private readonly activeToolContexts = new Map<string, ActiveToolContext>();
   /**
@@ -410,6 +455,11 @@ export class SessionEngine {
   private readonly mcpHost: McpHost;
   private readonly platforms: HostPlatforms;
   private readonly approvals = new ApprovalGate();
+  private readonly auths = new ApprovalGate<PendingAuth>();
+  private readonly oauthHub = new McpOauthOnDemandHub();
+  private probeCursorAccount:
+    | ((connection: string) => Promise<string | undefined>)
+    | undefined;
   private readonly abCollector: ABCollector;
   private readonly otel: OtelCollector | undefined;
   private readonly otelHost: HostOtelSessionApi;
@@ -458,6 +508,7 @@ export class SessionEngine {
     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) =>
@@ -565,10 +616,25 @@ export class SessionEngine {
     this.cloudServerToolsConnection = connection;
   }
 
+  setMcpOauthCallbackUrl(url: string): void {
+    this.oauthHub.callbackUrl = url;
+    this.mcpHost.setOAuthRedirectUrl(url);
+  }
+
+  setCursorAccountAuthProbe(
+    probe: (connection: string) => Promise<string | undefined>
+  ): void {
+    this.probeCursorAccount = probe;
+  }
+
+  get oauthCallbackHub(): McpOauthOnDemandHub {
+    return this.oauthHub;
+  }
+
   /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / files / otel / Slack nudges). */
   get host(): HostContext {
     return {
-      mcp: this.mcpHost,
+      mcp: this.wrapMcp(this.mcpHost),
       github: this.platforms.github,
       slack: this.platforms.slack,
       reminders: this.reminderApi,
@@ -958,12 +1024,15 @@ export class SessionEngine {
     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);
     let record: SessionRecord = {
       sessionId: sendOptions.hostedSessionId ?? newSessionId(),
       channelId,
       mode: sendOptions.mode ?? "chat",
       purpose,
-      ...(sendOptions.dryRun === true ? { dryRun: true } : {}),
+      dryRun: sendOptions.dryRun === true ? true : undefined,
+      asOf: frozenAsOf,
       continuationKey: sendOptions.continuationToken ?? newContinuationKey(),
       auth,
       title: sendOptions.title,
@@ -981,7 +1050,10 @@ export class SessionEngine {
     this.storage?.sessionRecord(record);
     await this.appendEvent(record.sessionId, {
       type: "session.started",
-      data: { channelId },
+      data: {
+        channelId,
+        dryRun: record.dryRun === true ? true : undefined,
+      },
     });
     record = await this.enrollABs(record);
     const since = (await this.logs.get(record.sessionId)).count;
@@ -1231,7 +1303,14 @@ export class SessionEngine {
     const prior = this.admissionChains.get(sessionId) ?? Promise.resolve();
     const admitted = prior
       .catch(() => {})
-      .then(() => this.admitTurn(sessionId, message, options));
+      .then(async () => {
+        // Another server holds the turn: hand the message to it and coalesce.
+        if (await this.turnLeases.runningElsewhere(sessionId)) {
+          await this.outbox.post(sessionId, { message, options });
+          return true;
+        }
+        return this.admitTurn(sessionId, message, options);
+      });
     this.admissionChains.set(
       sessionId,
       admitted.catch(() => {})
@@ -1239,6 +1318,20 @@ export class SessionEngine {
     return admitted;
   }
 
+  /** Admit what other servers handed to this turn's holder. Never awaited by the lifecycle. */
+  private drainOutbox(sessionId: string): void {
+    void this.outbox
+      .takeAll(sessionId)
+      .then((items) => {
+        for (const item of items) {
+          void this.startTurn(sessionId, item.message, item.options).catch(
+            () => {}
+          );
+        }
+      })
+      .catch(() => {});
+  }
+
   private enqueueCoalesced(sessionId: string, item: CoalescedQueuedTurn): void {
     const queue = this.coalesceQueues.get(sessionId) ?? [];
     if (
@@ -1476,6 +1569,8 @@ export class SessionEngine {
       let lifecycle!: Promise<TurnOutcome>;
       lifecycle = (async (): Promise<TurnOutcome> => {
         let outcome: TurnOutcome;
+        const poll = setInterval(() => this.drainOutbox(sessionId), 1_000);
+        poll.unref();
         try {
           outcome = await this.executeTurn(
             record,
@@ -1489,6 +1584,8 @@ export class SessionEngine {
             status: "error",
             errorMessage: describeError(error),
           };
+        } finally {
+          clearInterval(poll);
         }
         this.lastOutcomes.set(sessionId, outcome);
         const wasCurrent = this.activeTurns.get(sessionId) === lifecycle;
@@ -1518,6 +1615,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.
         await 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);
@@ -1562,6 +1663,7 @@ export class SessionEngine {
       this.coalesceDrains.has(sessionId) ||
       (this.coalesceQueues.get(sessionId)?.length ?? 0) > 0;
     this.clearCoalesced(sessionId);
+    await this.outbox.clear(sessionId);
     const record = await this.sessions.get(sessionId);
     const continuationKey = record?.continuationKey;
     if (continuationKey !== undefined && continuationKey !== null) {
@@ -1795,6 +1897,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
@@ -1879,11 +1982,14 @@ 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");
         await this.clearPendingApprovals(sessionId);
+        await 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);
@@ -2105,6 +2211,8 @@ export class SessionEngine {
         channelId: record.channelId,
         channelKind: this.channelsById.get(record.channelId)?.meta?.kind,
         environment: isDevMode() ? "local dev server" : "hosted deployment",
+        now:
+          record.asOf === undefined ? undefined : sessionClock(record.asOf)(),
       });
       turnPrompt = `${contextBlock}\n\n${prompt}`;
     }
@@ -2518,11 +2626,21 @@ 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 await resolveAdvertisedTools({
-      agent,
-      session: this.sessionInfo(record),
-      hostMcp: this.mcpHost,
-    })) {
+    for (const tool of await 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;
@@ -2615,6 +2733,7 @@ export class SessionEngine {
       getSession: (channelId, sessionId) =>
         this.getChannelSession(channelId, sessionId),
       emit: args.emit,
+      now: sessionClock(args.record.asOf),
     };
     try {
       // Before the approval gate: a dry run is unattended, so parking a write
@@ -2632,6 +2751,8 @@ export class SessionEngine {
           : {}),
         dryRunResult: args.tool.definition.dryRunResult,
         input: validation.value,
+        asOf: args.record.asOf,
+        timeArgs: args.tool.definition.timeArgs,
       });
       if (decision.kind === "answer") {
         this.stubbedCallIds.get(args.record.sessionId)?.add(toolCallId);
@@ -2640,6 +2761,12 @@ export class SessionEngine {
         );
         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})`
@@ -2672,7 +2799,16 @@ export class SessionEngine {
       }
       const started = Date.now();
       this.logger(`[session] tool ${args.tool.name} start`);
-      const result = await execute(validation.value as never, toolCtx);
+      const result = await mcpAuthAls.run(
+        {
+          sessionId: args.record.sessionId,
+          turnId: args.turnId,
+          callId: toolCallId,
+          toolName: args.tool.name,
+          emit: args.emit,
+        },
+        () => execute(validation.value as never, toolCtx)
+      );
       this.logger(
         `[session] tool ${args.tool.name} done (${Date.now() - started}ms)`
       );
@@ -2708,10 +2844,10 @@ export class SessionEngine {
       args: args.args,
       requestedAt,
     };
-    const resolutionPromise = this.approvals.wait({
-      sessionId: args.sessionId,
-      ...pendingRecord,
-    });
+    const resolutionPromise = this.approvals.wait(
+      args.sessionId,
+      pendingRecord
+    );
     await this.updateRecord(args.sessionId, (current) => ({
       ...current,
       pendingApprovals: [
@@ -2831,6 +2967,318 @@ export class SessionEngine {
     }));
   }
 
+  private wrapMcp(inner: McpHost): HostMcpRegistry {
+    return {
+      names: () => inner.names(),
+      listTools: (name) => this.withMcpAuth(name, () => inner.listTools(name)),
+      callTool: (name, tool, args) =>
+        this.withMcpAuth(name, () => inner.callTool(name, tool, args)),
+    };
+  }
+
+  private advertiseMcp(): AdvertiseHostMcp {
+    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)),
+        };
+      },
+    };
+  }
+
+  private withMcpListAuth<T>(
+    connection: string,
+    run: () => Promise<T>
+  ): Promise<T> {
+    const ctx = mcpAuthAls.getStore();
+    if (ctx === undefined) {
+      return this.withMcpAuth(connection, run);
+    }
+    const toolName = `mcp:${connection}`;
+    return mcpAuthAls.run(
+      {
+        ...ctx,
+        callId: newToolCallId(toolName),
+        toolName,
+      },
+      () => this.withMcpAuth(connection, run)
+    );
+  }
+
+  private async withMcpAuth<T>(
+    connection: string,
+    run: () => Promise<T>
+  ): Promise<T> {
+    try {
+      return await run();
+    } catch (error) {
+      if (!isMcpNeedsAuthError(error)) {
+        throw error;
+      }
+      return await this.parkAndRetryMcp(connection, run, error);
+    }
+  }
+
+  private async parkAndRetryMcp<T>(
+    connection: string,
+    run: () => Promise<T>,
+    error: unknown
+  ): Promise<T> {
+    const ctx = mcpAuthAls.getStore();
+    if (ctx === undefined) {
+      throw error;
+    }
+    const minted = await this.mintAuthUrl(connection, ctx.sessionId);
+    if (minted === undefined) {
+      throw error;
+    }
+    if ("authorized" in minted) {
+      await this.persistHostedMcpOauth(connection);
+      await this.mcpHost.dropClient(connection);
+      return await this.withMcpAuth(connection, run);
+    }
+    if (minted.state !== "") {
+      const bind = this.oauthHub.bind(minted.state, ctx.sessionId, ctx.callId);
+      if (bind === "already_done") {
+        await this.persistHostedMcpOauth(connection);
+        await this.mcpHost.dropClient(connection);
+        return await this.withMcpAuth(connection, run);
+      }
+    }
+    const decision = await 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.`
+      );
+    }
+    await this.persistHostedMcpOauth(connection);
+    await this.mcpHost.dropClient(connection);
+    return await this.withMcpAuth(connection, run);
+  }
+
+  private async persistHostedMcpOauth(connection: string): Promise<void> {
+    const authored = this.authoredConnection(connection);
+    if (
+      authored === undefined ||
+      !isHostOauthConnectionTransport(authored.transport)
+    ) {
+      return;
+    }
+    await this.oauthHub.persistFor(connection, authored.transport.url);
+  }
+
+  private authoredConnection(name: string) {
+    return (
+      this.project.agent.connections.find((entry) => entry.name === name) ??
+      this.project.agent.hostConnections?.find((entry) => entry.name === name)
+    );
+  }
+
+  private async mintAuthUrl(
+    connection: string,
+    sessionId: string
+  ): Promise<
+    { authorized: true } | { authUrl: string; state: string } | undefined
+  > {
+    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 = await probe(connection);
+      if (authUrl === undefined || authUrl === "") {
+        return undefined;
+      }
+      return { authUrl, state: "" };
+    }
+    if (!isHostOauthConnectionTransport(authored.transport)) {
+      return undefined;
+    }
+    return await this.oauthHub.mint({
+      connection,
+      url: authored.transport.url,
+      type: authored.transport.type === "sse" ? "sse" : "http",
+      headers: authored.transport.headers,
+      sessionId,
+    });
+  }
+
+  private async parkForAuth(args: {
+    sessionId: string;
+    turnId: string;
+    callId: string;
+    toolName: string;
+    connection: string;
+    authUrl: string;
+    emit: (payload: SessionEventPayload) => void;
+  }): Promise<ApprovalDecision> {
+    const requestedAt = new Date().toISOString();
+    const pendingRecord: PendingAuth = {
+      callId: args.callId,
+      turnId: args.turnId,
+      toolName: args.toolName,
+      connection: args.connection,
+      authUrl: args.authUrl,
+      requestedAt,
+    };
+    const resolutionPromise = this.auths.wait(args.sessionId, pendingRecord);
+    await this.updateRecord(args.sessionId, (current) => ({
+      ...current,
+      pendingAuths: [
+        ...(current.pendingAuths ?? []).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 } = await resolutionPromise;
+    await this.updateRecord(args.sessionId, (current) => ({
+      ...current,
+      pendingAuths: (current.pendingAuths ?? []).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;
+  }
+
+  private async clearPendingAuths(sessionId: string): Promise<void> {
+    await this.oauthHub.abortSession(sessionId);
+    const current = await this.sessions.get(sessionId);
+    if (
+      current === undefined ||
+      current.pendingAuths === undefined ||
+      current.pendingAuths.length === 0
+    ) {
+      return;
+    }
+    await this.updateRecord(sessionId, (record) => ({
+      ...record,
+      pendingAuths: [],
+    }));
+  }
+
+  async listPendingAuths(sessionId: string): Promise<PendingAuth[]> {
+    const record = await this.sessions.get(sessionId);
+    if (record === undefined) {
+      return [];
+    }
+    const live = this.auths.list(sessionId);
+    if (live.length > 0) {
+      return live;
+    }
+    return record.pendingAuths ?? [];
+  }
+
+  async resolveAuth(
+    sessionId: string,
+    callId: string,
+    decision: ApprovalDecision,
+    auth: AuthContext | null,
+    options?: { asSessionOwner?: boolean }
+  ): Promise<PendingAuth> {
+    const record = await this.sessions.get(sessionId);
+    if (record === undefined) {
+      throw new AuthNotFoundError(sessionId, callId);
+    }
+    const ownershipAuth = options?.asSessionOwner === true ? record.auth : auth;
+    if (!samePrincipal(record.auth, ownershipAuth)) {
+      throw new SessionAuthError(sessionId);
+    }
+    const pending =
+      (record.pendingAuths ?? []).find((item) => item.callId === callId) ??
+      this.auths.list(sessionId).find((item) => item.callId === callId);
+    if (pending === undefined) {
+      throw new AuthNotFoundError(sessionId, callId);
+    }
+    const resolvedBy = approvalResolverLabel(auth);
+    if (decision === "deny") {
+      await this.oauthHub.abortCall(sessionId, callId);
+    }
+    if (!this.auths.resolve(sessionId, callId, decision, resolvedBy)) {
+      await this.removePendingAuth(sessionId, callId);
+      throw new AuthInterruptedError(sessionId, callId);
+    }
+    return pending;
+  }
+
+  private async removePendingAuth(
+    sessionId: string,
+    callId: string
+  ): Promise<void> {
+    await this.updateRecord(sessionId, (current) => ({
+      ...current,
+      pendingAuths: (current.pendingAuths ?? []).filter(
+        (item) => item.callId !== callId
+      ),
+    }));
+  }
+
+  async runWithMcpPark<T>(
+    sessionId: string,
+    toolName: string,
+    fn: () => Promise<T>
+  ): Promise<T> {
+    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)
   // ==========================================================================
@@ -2846,8 +3294,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).
    *
@@ -2873,6 +3323,12 @@ export class SessionEngine {
     session: SessionInfo;
     workspaceDir: string;
     scratchDir: string | undefined;
+    /**
+     * A model turn is running or queued on the session. Reported, not
+     * enforced: what it means depends on the call — a write waits, a read
+     * (including the catalog) runs alongside the turn.
+     */
+    busy: boolean;
   }> {
     if (
       options.sessionId !== undefined &&
@@ -2898,9 +3354,9 @@ export class SessionEngine {
         );
       }
       // 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 =
         (await this.sessions.findByContinuation(
           continuation.channelId,
@@ -2915,19 +3371,14 @@ export class SessionEngine {
       }
     }
     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
@@ -2947,6 +3398,7 @@ export class SessionEngine {
       },
       workspaceDir: scratchDir,
       scratchDir,
+      busy: false,
     };
   }
 
@@ -2989,6 +3441,43 @@ 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.
+   */
+  async describeCatalogTool(
+    toolName: string,
+    options: Pick<
+      CallToolOptions,
+      "auth" | "sessionId" | "continuationToken"
+    > = {}
+  ): Promise<
+    | { tool: DiscoveredTool }
+    | {
+        tool: undefined;
+        availableTools: string[];
+        connectionErrors: Array<{ connection: string; message: string }>;
+      }
+  > {
+    const authored = this.project.agent.tools.find(
+      (tool) => tool.name === toolName
+    );
+    if (authored !== undefined) {
+      return { tool: authored };
+    }
+    const catalog = await 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 };
+  }
+
   async callTool(
     toolName: string,
     input: unknown = {},
@@ -3015,7 +3504,7 @@ export class SessionEngine {
       const advertised = await resolveAdvertisedTools({
         agent: this.project.agent,
         session,
-        hostMcp: this.mcpHost,
+        hostMcp: this.advertiseMcp(),
       });
       tool = advertised.find((t) => t.name === toolName);
     }
@@ -3035,6 +3524,19 @@ 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 {
       await mkdir(workspaceDir, { recursive: true });
@@ -3053,35 +3555,59 @@ 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;
-      await mkdir(workspaceDir, { recursive: true });
+      if (this.project.agent.local?.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;
+        await 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.
-    await 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) {
+      await 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.
@@ -3104,6 +3630,8 @@ export class SessionEngine {
         : {}),
       dryRunResult: tool.definition.dryRunResult,
       input: validation.value,
+      asOf: record?.asOf,
+      timeArgs: tool.definition.timeArgs,
     });
 
     const started = Date.now();
@@ -3122,7 +3650,13 @@ export class SessionEngine {
             }).catch(() => {});
           };
     try {
-      if (decision.kind === "refuse") {
+      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})`
         );
@@ -3139,8 +3673,8 @@ export class SessionEngine {
         result = normalizeToolResult(decision.result);
         isError = false;
       } else {
-        result = normalizeToolResult(
-          await execute(validation.value as never, {
+        const run = () =>
+          execute(validation.value as never, {
             toolCallId: callId,
             session,
             workspaceDir,
@@ -3165,7 +3699,21 @@ export class SessionEngine {
             getSession: (channelId, sessionId) =>
               this.getChannelSession(channelId, sessionId),
             emit,
-          })
+            now: sessionClock(record?.asOf),
+          });
+        result = normalizeToolResult(
+          record !== undefined && emit !== undefined
+            ? await mcpAuthAls.run(
+                {
+                  sessionId: record.sessionId,
+                  turnId: callId,
+                  callId,
+                  toolName,
+                  emit,
+                },
+                run
+              )
+            : await run()
         );
         isError = isErrorEnvelope(result);
       }
@@ -3263,6 +3811,12 @@ export class SessionEngine {
     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})`
@@ -3585,6 +4139,75 @@ 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.
+   */
+  async latestSessionWithSource(
+    caller: AuthContext | null,
+    options?: { includeAll?: boolean }
+  ): Promise<{ sessions: SessionSummary[]; source: SessionListSource }> {
+    const includeAll = options?.includeAll ?? false;
+    const newestVisible = (
+      records: readonly SessionRecord[]
+    ): SessionRecord | undefined => {
+      let newest: SessionRecord | undefined;
+      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(await this.sessions.list());
+    if (local !== undefined) {
+      return {
+        sessions: this.summarizeSessionRecords([local], caller, includeAll),
+        source: "local",
+      };
+    }
+    if (this.storage?.isCursorHosted === true) {
+      try {
+        const window = await 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 = await 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
@@ -3638,6 +4261,7 @@ export class SessionEngine {
             : undefined,
           createdAt: record.createdAt,
           updatedAt: record.updatedAt,
+          dryRun: record.dryRun === true ? true : undefined,
           continuationToken:
             record.httpContinuationKey !== undefined
               ? formatContinuationToken(
@@ -3967,7 +4591,8 @@ export class SessionEngine {
       channelId: record.channelId,
       mode: record.mode,
       purpose: record.purpose === "eval" ? "eval" : "live",
-      ...(record.dryRun === true ? { dryRun: true } : {}),
+      dryRun: record.dryRun === true ? true : undefined,
+      asOf: record.asOf,
       auth: record.auth,
       continuationKey: record.continuationKey,
       ...(record.abs === undefined ? {} : { abs: record.abs }),
@@ -4340,6 +4965,8 @@ export class SessionEngine {
   async close(): Promise<void> {
     this.stopMemoryTelemetry?.();
     this.approvals.cancelAll("deny");
+    this.auths.cancelAll("deny");
+    await this.oauthHub.close();
     await Promise.allSettled([...this.activeTurns.values()]);
     await Promise.allSettled([...this.backgroundWork]);
     await Promise.allSettled([...this.dispatchChains.values()]);
@@ -4357,6 +4984,13 @@ 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: Array<{ data: string; mimeType: string }> | undefined,