@cursor/july 0.1.9 → 0.1.11

package/src/internal/session-engine.ts

@@ -45,6 +45,7 @@ import {
   type SessionEvent,
   type SessionEventPayload,
   type SessionInfo,
+  type SessionListSource,
   type SessionRecord,
   type SessionSummary,
   type SlackNudgeHostApi,
@@ -81,6 +82,7 @@ import type { AgentRunner } from "./sdk-runner.js";
 import { SessionStore } from "./session-store.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
+import { TurnGovernor } from "./turn-governor.js";
 import {
   buildAgentsMdContent,
   isNestedInGitRepo,
@@ -251,6 +253,8 @@ export class SessionEngine {
   private readonly turnAborts = new Map<string, AbortController>();
   /** Serializes turn admission per session (latest follow-up wins). */
   private readonly admissionChains = new Map<string, Promise<unknown>>();
+  /** FIFO turn slots under `concurrency.maxRunningTurns` (unlimited when unset). */
+  private readonly turnGovernor: TurnGovernor;
   /**
    * Per-session coalesce queue for `admission: "coalesce"` (Slack). Drained
    * into one follow-up turn when the active turn finishes without interrupt.
@@ -270,6 +274,7 @@ export class SessionEngine {
   private readonly approvals = new ApprovalGate();
   private readonly abCollector: ABCollector;
   private reminderApi: HostContext["reminders"];
+  private evalsApi: HostContext["evals"];
   private readonly kvApi: HostContext["kv"];
   /** Serve-time resolved connections (see {@link setResolvedConnections}). */
   private resolvedConnections: EngineResolvedConnection[] = [];
@@ -279,6 +284,7 @@ export class SessionEngine {
     this.stateRoot = options.stateRoot;
     this.runner = options.runner;
     this.logger = options.logger ?? (() => {});
+    this.turnGovernor = new TurnGovernor(options.project.agent.concurrency);
     this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
     this.nudgeStore = new SlackNudgeStore(
       join(options.stateRoot, "slack-nudges")
@@ -349,13 +355,14 @@ export class SessionEngine {
     }
   }
 
-  /** Shared host services (MCP / GitHub / Slack / reminders / kv / Slack nudges). */
+  /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / Slack nudges). */
   get host(): HostContext {
     return {
       mcp: this.mcpHost,
       github: this.platforms.github,
       slack: this.platforms.slack,
       reminders: this.reminderApi,
+      evals: this.evalsApi,
       kv: this.kvApi,
       slackNudges: this.slackNudgeHostApi(),
     };
@@ -383,6 +390,11 @@ export class SessionEngine {
     this.reminderApi = api;
   }
 
+  /** Attach the serve-host playground evals API (called from startServer). */
+  setEvals(api: HostContext["evals"]): void {
+    this.evalsApi = api;
+  }
+
   // ==========================================================================
   // Sending messages
   // ==========================================================================
@@ -778,11 +790,8 @@ export class SessionEngine {
         turnId,
         data: { text: message },
       });
-      await this.appendEvent(sessionId, {
-        type: "turn.started",
-        turnId,
-        data: {},
-      });
+      // `turn.started` is appended by executeTurn once the turn holds a
+      // governor slot; saturated engines emit `turn.queued` first.
 
       const abort = new AbortController();
       this.turnAborts.set(sessionId, abort);
@@ -1000,65 +1009,91 @@ export class SessionEngine {
     };
     const mapper = new TurnEventMapper(emit);
 
+    // Take a turn slot before any work happens. When every slot is busy the
+    // turn waits FIFO — durable `turn.queued` marks the wait — and a
+    // preempting follow-up (or interrupt) resolves the wait as cancelled
+    // without the turn ever running.
+    const permit = await this.turnGovernor.acquire({
+      sessionId,
+      signal,
+      onQueued: (position) => {
+        const maxRunningTurns = this.turnGovernor.maxRunningTurns ?? 0;
+        emit({ type: "turn.queued", data: { position, maxRunningTurns } });
+        this.logger(
+          `[session] ${sessionId} ${turnId} queued at position ${position} (${maxRunningTurns} turn slot(s) busy)`
+        );
+      },
+    });
+
     let outcome: TurnOutcome;
-    try {
-      // Scaffold agent files into the session workspace even when the harness
-      // cwd is overridden (e.g. a PR worktree). A/B variant instruction
-      // overlays are applied via agentForSession.
-      const agent = this.agentForSession(record);
-      await materializeWorkspace({
-        agent,
-        workspaceDir,
-        seed: isFirstTurn,
-      });
-      const pendingFiles = record.pendingWorkspaceFiles;
-      if (pendingFiles !== undefined && Object.keys(pendingFiles).length > 0) {
-        await writeWorkspaceFiles(harnessCwd, pendingFiles);
-        await this.updateRecord(sessionId, (current) => {
-          const { pendingWorkspaceFiles: _cleared, ...rest } = current;
-          return rest;
+    if (permit === undefined) {
+      // Preempted while waiting for a slot; settle as an interrupted turn.
+      outcome = { status: "cancelled" };
+    } else {
+      emit({ type: "turn.started", data: {} });
+      try {
+        // Scaffold agent files into the session workspace even when the harness
+        // cwd is overridden (e.g. a PR worktree). A/B variant instruction
+        // overlays are applied via agentForSession.
+        const agent = this.agentForSession(record);
+        await materializeWorkspace({
+          agent,
+          workspaceDir,
+          seed: isFirstTurn,
         });
+        const pendingFiles = record.pendingWorkspaceFiles;
+        if (
+          pendingFiles !== undefined &&
+          Object.keys(pendingFiles).length > 0
+        ) {
+          await writeWorkspaceFiles(harnessCwd, pendingFiles);
+          await this.updateRecord(sessionId, (current) => {
+            const { pendingWorkspaceFiles: _cleared, ...rest } = current;
+            return rest;
+          });
+        }
+        // The harness only loads the scaffolded AGENTS.md when the session
+        // workspace is its own project root. With a per-session cwd override
+        // (PR worktree) the scaffold lands elsewhere, and a workspace nested
+        // inside a git repo re-roots harness rules at that repo — in both
+        // cases deliver instructions inline on the first turn instead.
+        const instructionsInvisibleToHarness =
+          isFirstTurn &&
+          (record.workspaceOverride !== undefined ||
+            (await isNestedInGitRepo(harnessCwd)));
+        const request = this.buildTurnRequest(
+          record,
+          agent,
+          turnId,
+          message,
+          isFirstTurn,
+          instructionsInvisibleToHarness,
+          emit,
+          async (update) => {
+            mapper.handleUpdate(update);
+            // Yield so the HTTP NDJSON writer can flush tool start/result
+            // events while sibling parallel tools are still executing.
+            if (
+              update.type === "tool-call-started" ||
+              update.type === "tool-call-completed" ||
+              // Nested subagent progress (newer SDKs); string check keeps
+              // typecheck green against older published `@cursor/sdk` pins.
+              (update as { type: string }).type === "tool-call-delta"
+            ) {
+              await yieldEventLoop();
+            }
+          },
+          signal
+        );
+        outcome = await this.runner.runTurn(request);
+      } catch (error) {
+        this.approvals.cancelSession(sessionId, "deny");
+        outcome = { status: "error", errorMessage: describeError(error) };
+      } finally {
+        permit.release();
+        this.approvals.cancelSession(sessionId, "deny");
+        await this.clearPendingApprovals(sessionId);
       }
-      // The harness only loads the scaffolded AGENTS.md when the session
-      // workspace is its own project root. With a per-session cwd override
-      // (PR worktree) the scaffold lands elsewhere, and a workspace nested
-      // inside a git repo re-roots harness rules at that repo — in both
-      // cases deliver instructions inline on the first turn instead.
-      const instructionsInvisibleToHarness =
-        isFirstTurn &&
-        (record.workspaceOverride !== undefined ||
-          (await isNestedInGitRepo(harnessCwd)));
-      const request = this.buildTurnRequest(
-        record,
-        agent,
-        turnId,
-        message,
-        isFirstTurn,
-        instructionsInvisibleToHarness,
-        emit,
-        async (update) => {
-          mapper.handleUpdate(update);
-          // Yield so the HTTP NDJSON writer can flush tool start/result
-          // events while sibling parallel tools are still executing.
-          if (
-            update.type === "tool-call-started" ||
-            update.type === "tool-call-completed" ||
-            // Nested subagent progress (newer SDKs); string check keeps
-            // typecheck green against older published `@cursor/sdk` pins.
-            (update as { type: string }).type === "tool-call-delta"
-          ) {
-            await yieldEventLoop();
-          }
-        },
-        signal
-      );
-      outcome = await this.runner.runTurn(request);
-    } catch (error) {
-      this.approvals.cancelSession(sessionId, "deny");
-      outcome = { status: "error", errorMessage: describeError(error) };
-    } finally {
-      this.approvals.cancelSession(sessionId, "deny");
-      await this.clearPendingApprovals(sessionId);
     }
 
     mapper.finish();
@@ -1223,38 +1258,42 @@ export class SessionEngine {
     };
   }
 
-  /**
-   * MCP servers for a turn: authored concrete connections plus resolved
-   * serve-time resolved connections (peers, Cursor account bridge).
-   * Resolved connections pick their URL by runtime — loopback for local
-   * turns, `cloudUrl` for cloud turns — and are omitted from cloud turns
-   * when no cloud URL exists unless a `servers` filter requires the bridge
-   * (see {@link assertCloudCanHonorAccountServersFilters}).
-   */
+  /** Authored + resolved MCP servers for a turn; skips `hostOnly`. */
   private buildMcpServers(
     runtime: "local" | "cloud"
   ): Record<string, ConnectionTransport> {
+    const hostOnlyNames = new Set(
+      this.project.agent.connections
+        .filter((connection) => connection.hostOnly === true)
+        .map((connection) => connection.name)
+    );
     assertCloudCanHonorAccountServersFilters({
       runtime,
-      resolvedConnections: this.resolvedConnections,
+      resolvedConnections: this.resolvedConnections.filter(
+        (resolved) => !hostOnlyNames.has(resolved.name)
+      ),
     });
     const servers: Record<string, ConnectionTransport> = {};
     for (const connection of this.project.agent.connections) {
+      if (hostOnlyNames.has(connection.name)) {
+        continue;
+      }
       if (isSymbolicConnectionTransport(connection.transport)) {
         continue;
       }
       servers[connection.name] = connection.transport;
     }
     for (const resolved of this.resolvedConnections) {
+      if (hostOnlyNames.has(resolved.name)) {
+        continue;
+      }
       const url = runtime === "cloud" ? resolved.cloudUrl : resolved.localUrl;
       if (url === undefined) {
         continue;
       }
       servers[resolved.name] = {
         url,
-        ...(resolved.headers === undefined
-          ? {}
-          : { headers: resolved.headers }),
+        headers: resolved.headers,
       };
     }
     return servers;
@@ -1827,13 +1866,88 @@ export class SessionEngine {
    * observability surface across every principal (channel-driven runs,
    * schedule/task sessions, other callers). The route auth chain still
    * gates who may call this at all.
+   *
+   * When the project uses `cursorHostedStorage`, prefers durable Bugbot rows
+   * (merged with any newer local records not flushed yet). Falls back to the
+   * local `--state-root` store when the sink is unavailable.
    */
   async listSessions(
     caller: AuthContext | null,
     options?: { includeAll?: boolean }
   ): Promise<SessionSummary[]> {
+    return (await this.listSessionsWithSource(caller, options)).sessions;
+  }
+
+  /**
+   * Same as {@link listSessions}, plus which store answered
+   * (`cursor-hosted` = durable DB via the control-plane proxy; `local` =
+   * `--state-root`).
+   */
+  async listSessionsWithSource(
+    caller: AuthContext | null,
+    options?: { includeAll?: boolean }
+  ): Promise<{ sessions: SessionSummary[]; source: SessionListSource }> {
     const includeAll = options?.includeAll ?? false;
+    if (this.storage?.isCursorHosted === true) {
+      try {
+        const records = await this.mergeStoredAndLocalSessions();
+        return {
+          sessions: this.summarizeSessionRecords(records, caller, includeAll),
+          source: "cursor-hosted",
+        };
+      } catch (error) {
+        this.logger(
+          `[agentkit] cursor-hosted session list failed; falling back to local: ${describeError(error)}`
+        );
+      }
+    }
     const records = await this.sessions.list();
+    // Local store is createdAt-asc; reverse so newest created leads.
+    return {
+      sessions: this.summarizeSessionRecords(
+        [...records].reverse(),
+        caller,
+        includeAll
+      ),
+      source: "local",
+    };
+  }
+
+  /**
+   * Durable sink rows plus local records (local wins on the same id when
+   * newer — covers debounce windows that have not flushed yet). Newest
+   * `updatedAt` first.
+   */
+  private async mergeStoredAndLocalSessions(): Promise<SessionRecord[]> {
+    const storage = this.storage;
+    if (storage === undefined) {
+      throw new Error("storage is not configured");
+    }
+    const stored = await storage.listSessionsFromSink();
+    const local = await this.sessions.list();
+    const byId = new Map<string, SessionRecord>();
+    for (const record of stored) {
+      byId.set(record.sessionId, record);
+    }
+    for (const record of local) {
+      const existing = byId.get(record.sessionId);
+      if (
+        existing === undefined ||
+        record.updatedAt.localeCompare(existing.updatedAt) >= 0
+      ) {
+        byId.set(record.sessionId, record);
+      }
+    }
+    return [...byId.values()].sort((a, b) =>
+      b.updatedAt.localeCompare(a.updatedAt)
+    );
+  }
+
+  private summarizeSessionRecords(
+    records: readonly SessionRecord[],
+    caller: AuthContext | null,
+    includeAll: boolean
+  ): SessionSummary[] {
     return records
       .filter((record) => includeAll || samePrincipal(record.auth, caller))
       .map((record) => {
@@ -1847,6 +1961,9 @@ export class SessionEngine {
           running:
             this.activeTurns.has(record.sessionId) ||
             this.pendingTurns.has(record.sessionId),
+          queued: this.turnGovernor.limited
+            ? this.turnGovernor.isQueued(record.sessionId)
+            : undefined,
           createdAt: record.createdAt,
           updatedAt: record.updatedAt,
           continuationToken:
@@ -1858,8 +1975,7 @@ export class SessionEngine {
                 ),
           ...(externalUrl === undefined ? {} : { externalUrl }),
         };
-      })
-      .reverse();
+      });
   }
 
   /**

package/src/internal/sessions-client.ts

@@ -4,15 +4,33 @@
  * Customer-facing errors never include hosting URLs or infra jargon.
  */
 
-import type { SessionEvent, SessionSummary } from "../types.js";
+import type {
+  SessionEvent,
+  SessionListSource,
+  SessionSummary,
+} from "../types.js";
 import { sanitizeCustomerError } from "./logs-client.js";
 import { mergeRequestHeaders, type RequestAuth } from "./request-headers.js";
 
+export interface ListedSessions {
+  sessions: SessionSummary[];
+  /** Present when the server reports which store answered. */
+  source?: SessionListSource;
+}
+
 export async function listSessions(args: {
   baseUrl: string;
   auth?: RequestAuth;
   fetchImpl?: typeof fetch;
 }): Promise<SessionSummary[]> {
+  return (await listSessionsWithSource(args)).sessions;
+}
+
+export async function listSessionsWithSource(args: {
+  baseUrl: string;
+  auth?: RequestAuth;
+  fetchImpl?: typeof fetch;
+}): Promise<ListedSessions> {
   const baseUrl = args.baseUrl.replace(/\/$/, "");
   const fetchImpl = args.fetchImpl ?? fetch;
   let resp: Response;
@@ -30,18 +48,21 @@ export async function listSessions(args: {
   if (!resp.ok) {
     throw new Error(`Could not list sessions (HTTP ${resp.status}).`);
   }
-  const body = (await resp.json()) as { sessions?: unknown };
-  if (!Array.isArray(body.sessions)) {
-    return [];
-  }
-  const out: SessionSummary[] = [];
-  for (const row of body.sessions) {
-    const parsed = parseSessionSummary(row);
-    if (parsed !== undefined) {
-      out.push(parsed);
+  const body = (await resp.json()) as { sessions?: unknown; source?: unknown };
+  const sessions: SessionSummary[] = [];
+  if (Array.isArray(body.sessions)) {
+    for (const row of body.sessions) {
+      const parsed = parseSessionSummary(row);
+      if (parsed !== undefined) {
+        sessions.push(parsed);
+      }
     }
   }
-  return out;
+  const source =
+    body.source === "cursor-hosted" || body.source === "local"
+      ? body.source
+      : undefined;
+  return source === undefined ? { sessions } : { sessions, source };
 }
 
 export async function fetchSessionEvents(args: {
@@ -144,6 +165,7 @@ function parseSessionSummary(value: unknown): SessionSummary | undefined {
     title: typeof row.title === "string" ? row.title : undefined,
     turnCount: typeof row.turnCount === "number" ? row.turnCount : 0,
     running: row.running === true,
+    queued: typeof row.queued === "boolean" ? row.queued : undefined,
     createdAt: typeof row.createdAt === "string" ? row.createdAt : "",
     updatedAt: typeof row.updatedAt === "string" ? row.updatedAt : "",
     continuationToken,
@@ -186,10 +208,24 @@ export async function resolvePreviousSessionId(args: {
   return pickPreviousSession(sessions)?.sessionId;
 }
 
+/** Human label for {@link SessionListSource} in CLI output. */
+export function formatSessionListSource(source: SessionListSource): string {
+  return source === "cursor-hosted"
+    ? "Listing from cursor-hosted storage (durable DB)."
+    : "Listing from local session store.";
+}
+
 /** Format a sessions table (id, channel, mode, turns, running, updated). */
-export function formatSessionsTable(sessions: SessionSummary[]): string {
+export function formatSessionsTable(
+  sessions: SessionSummary[],
+  options?: { source?: SessionListSource }
+): string {
+  const sourceLine =
+    options?.source === undefined
+      ? ""
+      : `${formatSessionListSource(options.source)}\n`;
   if (sessions.length === 0) {
-    return "No sessions.\n";
+    return `${sourceLine}No sessions.\n`;
   }
   const header = ["SESSION", "CHANNEL", "MODE", "TURNS", "RUNNING", "UPDATED"];
   const rows = sessions.map((s) => [
@@ -197,10 +233,10 @@ export function formatSessionsTable(sessions: SessionSummary[]): string {
     s.channelId,
     s.mode,
     String(s.turnCount),
-    s.running ? "yes" : "no",
+    s.queued === true ? "queued" : s.running ? "yes" : "no",
     s.updatedAt,
   ]);
-  return `${renderTable(header, rows)}\n`;
+  return `${sourceLine}${renderTable(header, rows)}\n`;
 }
 
 function renderTable(header: string[], rows: string[][]): string {

package/src/internal/storage-coordinator.ts

@@ -24,6 +24,7 @@ import {
   type StorageDefinition,
   storageKeys,
 } from "../storage.js";
+import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
 import type { ABSnapshot } from "./ab-snapshot.js";
 import { describeError } from "./describe-error.js";
@@ -261,6 +262,14 @@ export class StorageCoordinator {
     return this.definition.list !== undefined;
   }
 
+  /**
+   * True when the authored sink is `cursorHostedStorage` (Bugbot via the
+   * control-plane proxy). `GET /v1/sessions` prefers this durable list.
+   */
+  get isCursorHosted(): boolean {
+    return isCursorHostedStorage(this.definition);
+  }
+
   /**
    * Saved session records for this agent (startup restore). Errors are
    * logged and read as "nothing saved" — a broken store must never block
@@ -275,6 +284,33 @@ export class StorageCoordinator {
       .filter((record) => record != null);
   }
 
+  /**
+   * Session records from the sink for the sessions API. Unlike
+   * {@link listSessions}, missing `list` or a thrown sink error **propagates**
+   * so the caller can fall back to the local session store.
+   */
+  async listSessionsFromSink(): Promise<SessionRecord[]> {
+    const list = this.definition.list;
+    if (list === undefined) {
+      throw new Error("storage sink has no list");
+    }
+    const entries = await list(
+      storageKeys.sessionPrefix(this.agentName),
+      this.context("restore")
+    );
+    if (!Array.isArray(entries)) {
+      throw new Error("storage list returned a non-array");
+    }
+    return entries
+      .map((entry) => entry.value as unknown as SessionRecord)
+      .filter(
+        (record) =>
+          record != null &&
+          typeof record.sessionId === "string" &&
+          record.sessionId !== ""
+      );
+  }
+
   /**
    * Saved event stream for one session: chunk values concatenated in key
    * order (chunks are keyed by their first event's index, zero-padded, so

package/src/internal/stream-progress.ts

@@ -50,6 +50,14 @@ export function createStreamProgress(options?: {
           }
           break;
         }
+        case "turn.queued": {
+          write(
+            c.dim(
+              `  turn ${event.turnId ?? "?"} queued (position ${event.data.position}, max ${event.data.maxRunningTurns} running)\n`
+            )
+          );
+          break;
+        }
         case "turn.started": {
           turnClock = Date.now();
           if (event.turnId !== undefined) {