@cursor/july 0.1.10 → 0.1.11

package/src/internal/session-engine.ts

@@ -82,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,
@@ -252,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.
@@ -271,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[] = [];
@@ -280,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")
@@ -350,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(),
     };
@@ -384,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
   // ==========================================================================
@@ -779,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);
@@ -1001,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();
@@ -1224,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;
@@ -1923,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:

package/src/internal/sessions-client.ts

@@ -165,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,
@@ -232,7 +233,7 @@ export function formatSessionsTable(
     s.channelId,
     s.mode,
     String(s.turnCount),
-    s.running ? "yes" : "no",
+    s.queued === true ? "queued" : s.running ? "yes" : "no",
     s.updatedAt,
   ]);
   return `${sourceLine}${renderTable(header, rows)}\n`;

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) {

package/src/internal/turn-governor.ts

@@ -0,0 +1,145 @@
+/**
+ * FIFO admission of model turns under `concurrency.maxRunningTurns`
+ * (see {@link AgentConcurrencyOptions}). One governor per session engine:
+ * every turn acquires a slot before its SDK run starts and releases it when
+ * the run settles, so at most `maxRunningTurns` turns execute at once and
+ * the rest wait in arrival order instead of failing.
+ *
+ * Waiting is cancellable: the engine passes the turn's abort signal, so a
+ * follow-up that preempts a queued turn (or an explicit `interrupt()`)
+ * removes the waiter without ever running it.
+ */
+
+import type { AgentConcurrencyOptions } from "../types.js";
+
+export interface TurnPermit {
+  /** Return the slot. Idempotent; wakes the oldest waiter, if any. */
+  release(): void;
+}
+
+export interface AcquireTurnSlotArgs {
+  sessionId: string;
+  /** Abort waiting (preemption / interrupt). Ignored once a slot is held. */
+  signal?: AbortSignal;
+  /**
+   * Called synchronously when the turn must wait, with its 1-based
+   * position among waiting turns at enqueue time.
+   */
+  onQueued?: (position: number) => void;
+}
+
+interface TurnWaiter {
+  sessionId: string;
+  grant: (permit: TurnPermit) => void;
+  cancel: () => void;
+  cleanup: () => void;
+}
+
+export class TurnGovernor {
+  /** The configured ceiling, or undefined for unlimited. */
+  readonly maxRunningTurns: number | undefined;
+  private running = 0;
+  private readonly waiters: TurnWaiter[] = [];
+  /** Sessions currently waiting for a slot (at most one turn per session). */
+  private readonly queuedSessions = new Set<string>();
+
+  constructor(concurrency: AgentConcurrencyOptions | undefined) {
+    this.maxRunningTurns = concurrency?.maxRunningTurns;
+  }
+
+  /** True when a `maxRunningTurns` ceiling is configured. */
+  get limited(): boolean {
+    return this.maxRunningTurns !== undefined;
+  }
+
+  /** True while `sessionId` has a turn waiting for a slot. */
+  isQueued(sessionId: string): boolean {
+    return this.queuedSessions.has(sessionId);
+  }
+
+  /** Turns currently waiting for a slot. */
+  get queuedCount(): number {
+    return this.waiters.length;
+  }
+
+  /** Turns currently holding a slot. */
+  get runningCount(): number {
+    return this.running;
+  }
+
+  /**
+   * Acquire a turn slot. Resolves with a permit once a slot is free (FIFO
+   * behind earlier waiters), or with `undefined` when the abort signal
+   * fires while waiting — the turn must then settle as cancelled without
+   * running. Unlimited governors grant immediately.
+   */
+  acquire(args: AcquireTurnSlotArgs): Promise<TurnPermit | undefined> {
+    const limit = this.maxRunningTurns;
+    if (limit === undefined) {
+      return Promise.resolve(NO_OP_PERMIT);
+    }
+    if (this.running < limit && this.waiters.length === 0) {
+      return Promise.resolve(this.grantSlot());
+    }
+    // Saturated. A turn that is already preempted never enqueues.
+    if (args.signal?.aborted === true) {
+      return Promise.resolve(undefined);
+    }
+    return new Promise<TurnPermit | undefined>((resolve) => {
+      const waiter: TurnWaiter = {
+        sessionId: args.sessionId,
+        grant: (permit) => resolve(permit),
+        cancel: () => resolve(undefined),
+        cleanup: () => {
+          this.queuedSessions.delete(args.sessionId);
+          args.signal?.removeEventListener("abort", onAbort);
+        },
+      };
+      const onAbort = (): void => {
+        const index = this.waiters.indexOf(waiter);
+        if (index === -1) {
+          return;
+        }
+        this.waiters.splice(index, 1);
+        waiter.cleanup();
+        waiter.cancel();
+      };
+      this.waiters.push(waiter);
+      this.queuedSessions.add(args.sessionId);
+      args.signal?.addEventListener("abort", onAbort, { once: true });
+      args.onQueued?.(this.waiters.length);
+    });
+  }
+
+  /** Take a slot and build its (idempotent) release handle. */
+  private grantSlot(): TurnPermit {
+    this.running += 1;
+    let released = false;
+    return {
+      release: () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        this.running -= 1;
+        this.wakeNextWaiter();
+      },
+    };
+  }
+
+  private wakeNextWaiter(): void {
+    const limit = this.maxRunningTurns;
+    if (limit === undefined || this.running >= limit) {
+      return;
+    }
+    const waiter = this.waiters.shift();
+    if (waiter === undefined) {
+      return;
+    }
+    waiter.cleanup();
+    waiter.grant(this.grantSlot());
+  }
+}
+
+/** Permit handed out by unlimited governors. */
+const NO_OP_PERMIT: TurnPermit = { release: () => {} };

package/src/prompt.ts

@@ -0,0 +1,83 @@
+/**
+ * Dedented multi-line strings for prompts, errors, and tool descriptions.
+ *
+ * Indent the body to match surrounding TypeScript; the common leading
+ * whitespace is stripped. A leading newline after `` prompt` `` is dropped so
+ * the usual multiline form stays flush in source.
+ *
+ * ```ts
+ * import { prompt } from "@cursor/july";
+ *
+ * export default defineTool({
+ *   description: prompt`
+ *     Deploy Anyship services for a merged PR.
+ *     Enforces HITL outside business hours.
+ *   `,
+ *   // ...
+ * });
+ *
+ * throw new Error(prompt`
+ *   It is outside business hours.
+ *   Use request_author_approval.
+ * `);
+ *
+ * // GitHub channel `context` wants string[]:
+ * context: prompt.lines`
+ *   Merged PR detected: ${url}.
+ *
+ *   Run the deploy flow.
+ * `
+ * ```
+ */
+
+function dedentLines(
+  strings: TemplateStringsArray,
+  values: readonly unknown[]
+): string[] {
+  let text = "";
+  for (let i = 0; i < strings.length; i++) {
+    text += strings[i] ?? "";
+    if (i < values.length) {
+      text += String(values[i]);
+    }
+  }
+  // Common form is prompt`\n  …\n`; drop the opening newline only.
+  if (text.startsWith("\n")) {
+    text = text.slice(1);
+  }
+  text = text.replace(/(?:\n[ \t]*)+$/u, "");
+
+  const lines = text.split("\n");
+  let minIndent = Number.POSITIVE_INFINITY;
+  for (const line of lines) {
+    if (line.trim() === "") {
+      continue;
+    }
+    const indent = /^[ \t]*/u.exec(line)?.[0]?.length ?? 0;
+    if (indent < minIndent) {
+      minIndent = indent;
+    }
+  }
+  if (!Number.isFinite(minIndent)) {
+    minIndent = 0;
+  }
+  return lines.map((line) => (line.trim() === "" ? "" : line.slice(minIndent)));
+}
+
+export type PromptTag = {
+  (strings: TemplateStringsArray, ...values: unknown[]): string;
+  /** Same as {@link prompt}, but as separate lines (e.g. GitHub `context`). */
+  lines(strings: TemplateStringsArray, ...values: unknown[]): string[];
+};
+
+/** Dedented multi-line string (blank lines preserved). */
+export const prompt: PromptTag = Object.assign(
+  function prompt(strings: TemplateStringsArray, ...values: unknown[]): string {
+    return dedentLines(strings, values).join("\n");
+  },
+  {
+    lines(strings: TemplateStringsArray, ...values: unknown[]): string[] {
+      return dedentLines(strings, values);
+    },
+  }
+);