@cursor/july 0.1.62 → 0.1.68

package/src/internal/session-engine.ts

@@ -17,6 +17,8 @@ import {
   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,
@@ -73,6 +75,7 @@ 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 { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
 import { SessionAuthError, samePrincipal } from "./auth.js";
@@ -132,9 +135,11 @@ import {
   roundCostUsd,
 } from "./turn-cost.js";
 import { TurnGovernor } from "./turn-governor.js";
+import { TurnLeaseStore } from "./turn-lease-store.js";
 import {
   buildAgentsMdContent,
   buildCloudMemorySection,
+  ensureOwnGitRoot,
   isNestedInGitRepo,
   materializeWorkspace,
   SERVER_TOOLS_MCP_SERVER_NAME,
@@ -318,6 +323,8 @@ export class SessionEngine {
   readonly nudgeStore: SlackNudgeStore;
   /** Durable `channelId:ts` ask claims under `<stateRoot>/slack-asks`. */
   readonly askDedupe: SlackAskDedupeStore;
+  /** Cross-process turn ownership under `<stateRoot>/turn-leases`. */
+  readonly turnLeases: TurnLeaseStore;
   /**
    * Runtime for `agent/storage.ts` (`defineStorage`), when
    * authored. All durable state changes funnel through it (session
@@ -342,6 +349,12 @@ export class SessionEngine {
   private readonly activeTurns = new Map<string, Promise<TurnOutcome>>();
   /** Context used by the cloud turn's HTTP MCP callbacks. */
   private readonly activeToolContexts = new Map<string, ActiveToolContext>();
+  /**
+   * Delivered-nudge count per session at the last tool boundary. The carrier
+   * drains out-of-process, so a growing count is how the engine learns a
+   * follow-up reached the agent.
+   */
+  private readonly deliveredNudges = new Map<string, number>();
   /** Aborts the in-flight turn per session so a follow-up can preempt it. */
   private readonly turnAborts = new Map<string, AbortController>();
   /** Serializes turn admission per session (latest follow-up wins). */
@@ -415,6 +428,9 @@ export class SessionEngine {
     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) =>
@@ -731,6 +747,110 @@ 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.
+   */
+  private async materializeNudgeCarrier(
+    record: SessionRecord,
+    harnessCwd: string
+  ): Promise<void> {
+    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 {
+      await 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.
+   */
+  private async emitDeliveredNudges(
+    record: SessionRecord,
+    emit: (event: SessionEventPayload) => void
+  ): Promise<void> {
+    const delivered = await 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.
+   */
+  private async baselineDeliveredNudges(record: SessionRecord): Promise<void> {
+    const delivered = await this.readDeliveredNudges(record);
+    if (delivered !== undefined) {
+      this.deliveredNudges.set(record.sessionId, delivered);
+    }
+  }
+
+  private async readDeliveredNudges(
+    record: SessionRecord
+  ): Promise<number | undefined> {
+    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 await this.nudgeStore.deliveredCount(continuationKey);
+    } catch {
+      // A store read must never break the turn it is observing.
+      return undefined;
+    }
+  }
+
   private slackNudgeHostApi(): SlackNudgeHostApi {
     return {
       append: (input) => this.nudgeStore.append(input),
@@ -1126,6 +1246,67 @@ export class SessionEngine {
     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.
+   */
+  private async withoutNudgedFollowups(
+    sessionId: string,
+    queued: readonly CoalescedQueuedTurn[]
+  ): Promise<CoalescedQueuedTurn[]> {
+    const record = await this.sessions.get(sessionId);
+    const continuationKey = record?.continuationKey;
+    if (continuationKey === undefined || continuationKey === null) {
+      return [...queued];
+    }
+    const kept: CoalescedQueuedTurn[] = [];
+    for (const item of queued) {
+      if (item.sourceTs === undefined) {
+        kept.push(item);
+        continue;
+      }
+      try {
+        if (
+          !(await this.nudgeStore.isDelivered(continuationKey, item.sourceTs))
+        ) {
+          kept.push(item);
+        }
+      } catch {
+        // 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. */
+  private async settleDrainedFollowups(
+    sessionId: string,
+    items: readonly CoalescedQueuedTurn[]
+  ): Promise<void> {
+    const record = await this.sessions.get(sessionId);
+    const continuationKey = record?.continuationKey;
+    if (continuationKey === undefined || continuationKey === null) {
+      return;
+    }
+    for (const item of items) {
+      if (item.sourceTs === undefined) {
+        continue;
+      }
+      try {
+        await 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)}`
+        );
+      }
+    }
+  }
+
   private formatCoalescedFollowups(
     items: readonly CoalescedQueuedTurn[]
   ): string {
@@ -1152,9 +1333,20 @@ export class SessionEngine {
       return;
     }
     this.coalesceQueues.delete(sessionId);
-    const message = this.formatCoalescedFollowups(queued);
+    const pending = await 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.
+    await this.settleDrainedFollowups(sessionId, pending);
+    const message = this.formatCoalescedFollowups(pending);
     this.logger(
-      `[session] coalesce drain starting follow-up (${queued.length}) ${sessionId}`
+      `[session] coalesce drain starting follow-up (${pending.length}) ${sessionId}`
     );
     await this.startTurn(sessionId, message, {
       admission: "preempt",
@@ -1179,6 +1371,15 @@ export class SessionEngine {
       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 (await 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:
@@ -1192,8 +1393,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 = await this.turnLeases.acquire(sessionId, () => {
+      // 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}`);
+      this.turnAborts.get(sessionId)?.abort();
+    });
+    if (lease === undefined) {
+      this.logger(`[session] lease lost during admit ${sessionId}`);
+      return true;
+    }
     this.pendingTurns.add(sessionId);
 
+    let lifecycleInstalled = false;
     try {
       let record = await this.updateRecord(sessionId, (current) => ({
         ...current,
@@ -1259,11 +1472,20 @@ 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();
         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.
+        await lease.release();
+      }
     }
     return false;
   }
@@ -1435,7 +1657,13 @@ export class SessionEngine {
         ...(agent.allowedTools === undefined
           ? {}
           : { 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 }),
       });
@@ -1521,6 +1749,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)) {
+          await ensureOwnGitRoot(harnessCwd);
+        }
+        await 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.
+        await this.baselineDeliveredNudges(record);
         const pendingFiles = record.pendingWorkspaceFiles;
         const pendingImages = record.pendingImages;
         if (
@@ -1555,7 +1795,7 @@ export class SessionEngine {
           isFirstTurn &&
           (this.hasBorrowedWorkspace(record) ||
             (await isNestedInGitRepo(harnessCwd)));
-        const request = this.buildTurnRequest(
+        const request = await this.buildTurnRequest(
           record,
           agent,
           turnId,
@@ -1574,6 +1814,9 @@ export class SessionEngine {
               // typecheck green against older published `@cursor/sdk` pins.
               (update as { type: string }).type === "tool-call-delta"
             ) {
+              // Same boundary the carrier hook runs on, so a drain is visible
+              // by the time this fires.
+              await this.emitDeliveredNudges(record, emit);
               await yieldEventLoop();
             }
           },
@@ -1593,6 +1836,9 @@ export class SessionEngine {
         permit.release();
         this.approvals.cancelSession(sessionId, "deny");
         await 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);
       }
     }
 
@@ -1672,7 +1918,7 @@ export class SessionEngine {
     };
   }
 
-  private buildTurnRequest(
+  private async buildTurnRequest(
     record: SessionRecord,
     agent: ResolvedAgent,
     turnId: string,
@@ -1683,7 +1929,7 @@ export class SessionEngine {
     onUpdate: RunnerTurnRequest["onUpdate"],
     signal: AbortSignal,
     images?: Array<{ data: string; mimeType: string }>
-  ): RunnerTurnRequest {
+  ): Promise<RunnerTurnRequest> {
     // Per-session cloud attach (channel/tool handoff) forces cloud runtime
     // even when the agent defaults to local for chat server tools.
     const runtime = resolveSessionRuntime({
@@ -1699,6 +1945,21 @@ export class SessionEngine {
         `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({
@@ -1764,14 +2025,26 @@ export class SessionEngine {
       runtime,
       ...(mergedCloud === undefined ? {} : { cloud: mergedCloud }),
       customTools:
-        runtime === "local" ? this.buildCustomTools(record, turnId, emit) : {},
-      mcpServers: this.buildMcpServers(runtime, record.sessionId),
+        runtime === "local"
+          ? await this.buildCustomTools(record, agent, turnId, emit)
+          : {},
+      mcpServers: this.buildMcpServers(
+        runtime,
+        record.sessionId,
+        await 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: async (sdkAgentId) => {
         if (record.sdkAgentId === sdkAgentId) {
           return;
@@ -1871,11 +2144,18 @@ export class SessionEngine {
    */
   private buildMcpServers(
     runtime: "local" | "cloud",
-    sessionId?: string
+    sessionId?: string,
+    sessionAuth?: ReadonlyMap<string, Record<string, string>>
   ): Record<string, ConnectionTransport> {
+    // 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(
@@ -1920,6 +2200,23 @@ 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?.get(connection.name);
+        if (evaluated === undefined) {
+          continue;
+        }
+        const transport = connection.transport;
+        if ("url" in transport) {
+          servers[connection.name] = {
+            ...transport,
+            headers: { ...transport.headers, ...evaluated },
+          };
+        }
+        continue;
+      }
       servers[connection.name] = connection.transport;
     }
     for (const resolved of this.resolvedConnections) {
@@ -1966,20 +2263,67 @@ export class SessionEngine {
     return servers;
   }
 
-  private buildCustomTools(
+  /**
+   * 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.
+   */
+  private hasAttachedAuthedConnections(): boolean {
+    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.
+   */
+  private async evaluateConnectionAuth(
+    record: SessionRecord
+  ): Promise<ReadonlyMap<string, Record<string, string>> | undefined> {
+    const authed = this.project.agent.connections.filter(
+      (connection) =>
+        connection.auth !== undefined &&
+        connection.hostOnly !== true &&
+        connection.advertiseTools !== true
+    );
+    if (authed.length === 0) {
+      return undefined;
+    }
+    const session = this.sessionInfo(record);
+    const evaluated = new Map<string, Record<string, string>>();
+    for (const connection of authed) {
+      const auth = connection.auth;
+      if (auth === undefined) {
+        continue;
+      }
+      try {
+        evaluated.set(connection.name, (await auth(session)).headers);
+      } catch (error) {
+        throw new Error(
+          `Connection "${connection.name}" auth failed: ${describeError(error)}`,
+          { cause: error }
+        );
+      }
+    }
+    return evaluated;
+  }
+
+  private async buildCustomTools(
     record: SessionRecord,
+    agent: ResolvedAgent,
     turnId: string,
     emit: (payload: SessionEventPayload) => void
-  ): Record<string, SDKCustomTool> {
+  ): Promise<Record<string, SDKCustomTool>> {
     const tools: Record<string, SDKCustomTool> = {};
-    for (const tool of this.project.agent.tools) {
-      if (tool.execution !== "server") {
-        continue;
-      }
-      const execute = tool.definition.execute;
-      if (typeof execute !== "function") {
-        continue;
-      }
+    const register = (tool: ResolvedAgent["tools"][number]): void => {
       tools[tool.name] = {
         description: tool.description,
         inputSchema: tool.inputSchema as SDKCustomTool["inputSchema"],
@@ -1994,6 +2338,26 @@ export class SessionEngine {
           });
         },
       };
+    };
+    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 await resolveAdvertisedTools({
+      agent,
+      session: this.sessionInfo(record),
+      hostMcp: this.mcpHost,
+    })) {
+      register(tool);
     }
     return tools;
   }
@@ -3476,6 +3840,8 @@ export class SessionEngine {
     await Promise.allSettled([...this.backgroundWork]);
     await Promise.allSettled([...this.dispatchChains.values()]);
     await Promise.allSettled([...this.updateChains.values()]);
+    // After the drain, so a successor need not wait out the heartbeat TTL.
+    await this.turnLeases.releaseAll().catch(() => {});
     await this.logs.flushAll();
     await this.storage?.close();
     await this.mcpHost.close();