@cursor/july 0.1.10 → 0.1.11

package/dist/internal/session-engine.js

@@ -51,6 +51,7 @@ import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections
 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, materializeWorkspace, writeWorkspaceFiles, } from "./workspace.js";
 export const HTTP_CHANNEL_ID = "http";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
@@ -143,6 +144,7 @@ export class SessionEngine {
         this.stateRoot = options.stateRoot;
         this.runner = options.runner;
         this.logger = (_a = options.logger) !== null && _a !== void 0 ? _a : (() => { });
+        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"));
         this.askDedupe = new SlackAskDedupeStore(join(options.stateRoot, "slack-asks"));
@@ -186,13 +188,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() {
         return {
             mcp: this.mcpHost,
             github: this.platforms.github,
             slack: this.platforms.slack,
             reminders: this.reminderApi,
+            evals: this.evalsApi,
             kv: this.kvApi,
             slackNudges: this.slackNudgeHostApi(),
         };
@@ -212,6 +215,10 @@ export class SessionEngine {
     setReminders(api) {
         this.reminderApi = api;
     }
+    /** Attach the serve-host playground evals API (called from startServer). */
+    setEvals(api) {
+        this.evalsApi = api;
+    }
     // ==========================================================================
     // Sending messages
     // ==========================================================================
@@ -520,11 +527,8 @@ export class SessionEngine {
                     turnId,
                     data: { text: message },
                 });
-                yield 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);
                 // Lifecycle promise includes post-turn coalesce drain so waiters and
@@ -707,54 +711,77 @@ 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 = yield this.turnGovernor.acquire({
+                sessionId,
+                signal,
+                onQueued: (position) => {
+                    var _a;
+                    const maxRunningTurns = (_a = this.turnGovernor.maxRunningTurns) !== null && _a !== void 0 ? _a : 0;
+                    emit({ type: "turn.queued", data: { position, maxRunningTurns } });
+                    this.logger(`[session] ${sessionId} ${turnId} queued at position ${position} (${maxRunningTurns} turn slot(s) busy)`);
+                },
+            });
             let outcome;
-            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);
-                yield materializeWorkspace({
-                    agent,
-                    workspaceDir,
-                    seed: isFirstTurn,
-                });
-                const pendingFiles = record.pendingWorkspaceFiles;
-                if (pendingFiles !== undefined && Object.keys(pendingFiles).length > 0) {
-                    yield writeWorkspaceFiles(harnessCwd, pendingFiles);
-                    yield this.updateRecord(sessionId, (current) => {
-                        const { pendingWorkspaceFiles: _cleared } = current, rest = __rest(current, ["pendingWorkspaceFiles"]);
-                        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);
+                    yield materializeWorkspace({
+                        agent,
+                        workspaceDir,
+                        seed: isFirstTurn,
                     });
-                }
-                // 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 ||
-                        (yield isNestedInGitRepo(harnessCwd)));
-                const request = this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, instructionsInvisibleToHarness, emit, (update) => __awaiter(this, void 0, void 0, function* () {
-                    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.type === "tool-call-delta") {
-                        yield yieldEventLoop();
+                    const pendingFiles = record.pendingWorkspaceFiles;
+                    if (pendingFiles !== undefined &&
+                        Object.keys(pendingFiles).length > 0) {
+                        yield writeWorkspaceFiles(harnessCwd, pendingFiles);
+                        yield this.updateRecord(sessionId, (current) => {
+                            const { pendingWorkspaceFiles: _cleared } = current, rest = __rest(current, ["pendingWorkspaceFiles"]);
+                            return rest;
+                        });
                     }
-                }), signal);
-                outcome = yield this.runner.runTurn(request);
-            }
-            catch (error) {
-                this.approvals.cancelSession(sessionId, "deny");
-                outcome = { status: "error", errorMessage: describeError(error) };
-            }
-            finally {
-                this.approvals.cancelSession(sessionId, "deny");
-                yield 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 ||
+                            (yield isNestedInGitRepo(harnessCwd)));
+                    const request = this.buildTurnRequest(record, agent, turnId, message, isFirstTurn, instructionsInvisibleToHarness, emit, (update) => __awaiter(this, void 0, void 0, function* () {
+                        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.type === "tool-call-delta") {
+                            yield yieldEventLoop();
+                        }
+                    }), signal);
+                    outcome = yield 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");
+                    yield this.clearPendingApprovals(sessionId);
+                }
             }
             mapper.finish();
             if (mapper.title !== undefined) {
@@ -867,34 +894,37 @@ 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`. */
     buildMcpServers(runtime) {
+        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 = {};
         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] = Object.assign({ url }, (resolved.headers === undefined
-                ? {}
-                : { headers: resolved.headers }));
+            servers[resolved.name] = {
+                url,
+                headers: resolved.headers,
+            };
         }
         return servers;
     }
@@ -1434,7 +1464,9 @@ export class SessionEngine {
             .map((record) => {
             const externalUrl = externalUrlForSession(record);
             return Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId, channelId: record.channelId, mode: record.mode }, (record.title === undefined ? {} : { title: record.title })), { turnCount: record.turnCount, running: this.activeTurns.has(record.sessionId) ||
-                    this.pendingTurns.has(record.sessionId), createdAt: record.createdAt, updatedAt: record.updatedAt, continuationToken: record.continuationKey === null
+                    this.pendingTurns.has(record.sessionId), queued: this.turnGovernor.limited
+                    ? this.turnGovernor.isQueued(record.sessionId)
+                    : undefined, createdAt: record.createdAt, updatedAt: record.updatedAt, continuationToken: record.continuationKey === null
                     ? null
                     : formatContinuationToken(record.channelId, record.continuationKey) }), (externalUrl === undefined ? {} : { externalUrl }));
         });

package/dist/internal/sessions-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sessions-client.d.ts","sourceRoot":"","sources":["../../src/internal/sessions-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE5B;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,cAAc,CAAC,CAiC1B;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAuE1B;AAgCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,cAAc,GAAG,SAAS,CAU5B;AAED,+DAA+D;AAC/D,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO9B;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAIzE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACvC,MAAM,CAkBR"}
+{"version":3,"file":"sessions-client.d.ts","sourceRoot":"","sources":["../../src/internal/sessions-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE5B;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,cAAc,CAAC,CAiC1B;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAuE1B;AAiCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,cAAc,GAAG,SAAS,CAU5B;AAED,+DAA+D;AAC/D,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO9B;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAIzE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACvC,MAAM,CAkBR"}

package/dist/internal/sessions-client.js

@@ -143,6 +143,7 @@ function parseSessionSummary(value) {
         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,
@@ -194,7 +195,7 @@ export function formatSessionsTable(sessions, options) {
         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/dist/internal/stream-progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-progress.d.ts","sourceRoot":"","sources":["../../src/internal/stream-progress.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAC7C,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,cAAc,CAqNjB"}
+{"version":3,"file":"stream-progress.d.ts","sourceRoot":"","sources":["../../src/internal/stream-progress.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE;IAC7C,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GAAG,cAAc,CA6NjB"}

package/dist/internal/stream-progress.js

@@ -21,7 +21,7 @@ export function createStreamProgress(options) {
     const elapsed = (since) => `${Date.now() - since}ms`;
     return {
         onEvent(event) {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             switch (event.type) {
                 case "session.started": {
                     write(c.dim(`session ${event.sessionId}\n`));
@@ -35,12 +35,16 @@ export function createStreamProgress(options) {
                     }
                     break;
                 }
+                case "turn.queued": {
+                    write(c.dim(`  turn ${(_a = event.turnId) !== null && _a !== void 0 ? _a : "?"} queued (position ${event.data.position}, max ${event.data.maxRunningTurns} running)\n`));
+                    break;
+                }
                 case "turn.started": {
                     turnClock = Date.now();
                     if (event.turnId !== undefined) {
                         turnStartedAt.set(event.turnId, turnClock);
                     }
-                    write(c.dim(`  turn ${(_a = event.turnId) !== null && _a !== void 0 ? _a : "?"} started\n`));
+                    write(c.dim(`  turn ${(_b = event.turnId) !== null && _b !== void 0 ? _b : "?"} started\n`));
                     break;
                 }
                 case "message.received": {
@@ -131,11 +135,11 @@ export function createStreamProgress(options) {
                     const detail = event.data.description
                         ? ` — ${truncate(event.data.description, 60)}`
                         : "";
-                    write(`  ${c.magenta("task")} ${c.bold((_b = event.data.name) !== null && _b !== void 0 ? _b : "subagent")}${c.dim(detail)}\n`);
+                    write(`  ${c.magenta("task")} ${c.bold((_c = event.data.name) !== null && _c !== void 0 ? _c : "subagent")}${c.dim(detail)}\n`);
                     break;
                 }
                 case "subagent.completed": {
-                    write(`  ${c.magenta("✓")} ${c.bold((_c = event.data.name) !== null && _c !== void 0 ? _c : "subagent")} ${c.dim("done")}\n`);
+                    write(`  ${c.magenta("✓")} ${c.bold((_d = event.data.name) !== null && _d !== void 0 ? _d : "subagent")} ${c.dim("done")}\n`);
                     break;
                 }
                 case "turn.completed": {

package/dist/internal/turn-governor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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;
+}
+export declare class TurnGovernor {
+    /** The configured ceiling, or undefined for unlimited. */
+    readonly maxRunningTurns: number | undefined;
+    private running;
+    private readonly waiters;
+    /** Sessions currently waiting for a slot (at most one turn per session). */
+    private readonly queuedSessions;
+    constructor(concurrency: AgentConcurrencyOptions | undefined);
+    /** True when a `maxRunningTurns` ceiling is configured. */
+    get limited(): boolean;
+    /** True while `sessionId` has a turn waiting for a slot. */
+    isQueued(sessionId: string): boolean;
+    /** Turns currently waiting for a slot. */
+    get queuedCount(): number;
+    /** Turns currently holding a slot. */
+    get runningCount(): number;
+    /**
+     * 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>;
+    /** Take a slot and build its (idempotent) release handle. */
+    private grantSlot;
+    private wakeNextWaiter;
+}
+//# sourceMappingURL=turn-governor.d.ts.map

package/dist/internal/turn-governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-governor.d.ts","sourceRoot":"","sources":["../../src/internal/turn-governor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AASD,qBAAa,YAAY;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IAEpD,YAAY,WAAW,EAAE,uBAAuB,GAAG,SAAS,EAE3D;IAED,2DAA2D;IAC3D,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEnC;IAED,0CAA0C;IAC1C,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,sCAAsC;IACtC,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAoClE;IAED,6DAA6D;IAC7D,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,cAAc;CAYvB"}

package/dist/internal/turn-governor.js

@@ -0,0 +1,111 @@
+/**
+ * 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.
+ */
+export class TurnGovernor {
+    constructor(concurrency) {
+        this.running = 0;
+        this.waiters = [];
+        /** Sessions currently waiting for a slot (at most one turn per session). */
+        this.queuedSessions = new Set();
+        this.maxRunningTurns = concurrency === null || concurrency === void 0 ? void 0 : concurrency.maxRunningTurns;
+    }
+    /** True when a `maxRunningTurns` ceiling is configured. */
+    get limited() {
+        return this.maxRunningTurns !== undefined;
+    }
+    /** True while `sessionId` has a turn waiting for a slot. */
+    isQueued(sessionId) {
+        return this.queuedSessions.has(sessionId);
+    }
+    /** Turns currently waiting for a slot. */
+    get queuedCount() {
+        return this.waiters.length;
+    }
+    /** Turns currently holding a slot. */
+    get runningCount() {
+        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) {
+        var _a;
+        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 (((_a = args.signal) === null || _a === void 0 ? void 0 : _a.aborted) === true) {
+            return Promise.resolve(undefined);
+        }
+        return new Promise((resolve) => {
+            var _a, _b;
+            const waiter = {
+                sessionId: args.sessionId,
+                grant: (permit) => resolve(permit),
+                cancel: () => resolve(undefined),
+                cleanup: () => {
+                    var _a;
+                    this.queuedSessions.delete(args.sessionId);
+                    (_a = args.signal) === null || _a === void 0 ? void 0 : _a.removeEventListener("abort", onAbort);
+                },
+            };
+            const onAbort = () => {
+                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);
+            (_a = args.signal) === null || _a === void 0 ? void 0 : _a.addEventListener("abort", onAbort, { once: true });
+            (_b = args.onQueued) === null || _b === void 0 ? void 0 : _b.call(args, this.waiters.length);
+        });
+    }
+    /** Take a slot and build its (idempotent) release handle. */
+    grantSlot() {
+        this.running += 1;
+        let released = false;
+        return {
+            release: () => {
+                if (released) {
+                    return;
+                }
+                released = true;
+                this.running -= 1;
+                this.wakeNextWaiter();
+            },
+        };
+    }
+    wakeNextWaiter() {
+        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 = { release: () => { } };