@cursor/july 0.1.9 → 0.1.11

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);
+    },
+  }
+);

package/src/storage-backends/cursor-hosted.ts

@@ -80,9 +80,29 @@ export interface CursorHostedStorageOptions {
   fetch?: typeof fetch;
 }
 
+/**
+ * Marker stamped on {@link cursorHostedStorage} so the engine can prefer
+ * durable Bugbot rows for `GET /v1/sessions` (survives `defineStorage` spread).
+ * Explicit `unique symbol` annotation required for `--isolatedDeclarations`
+ * (TS9010).
+ */
+export const CURSOR_HOSTED_STORAGE: unique symbol = Symbol.for(
+  "@cursor/july.storage.cursor-hosted"
+);
+
+/** True when `value` is (or was built from) {@link cursorHostedStorage}. */
+export function isCursorHostedStorage(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<symbol, unknown>)[CURSOR_HOSTED_STORAGE] === true
+  );
+}
+
 type CursorHostedStorageMethods = Required<
   Pick<StorageConfig, "put" | "get" | "delete" | "list">
 > & {
+  readonly [CURSOR_HOSTED_STORAGE]: true;
   evals: StorageEvalsTable;
   abs: StorageABTable;
 };
@@ -155,6 +175,7 @@ export function cursorHostedStorage(
   options: CursorHostedStorageOptions = {}
 ): CursorHostedStorageMethods {
   return {
+    [CURSOR_HOSTED_STORAGE]: true,
     async put(key, value): Promise<void> {
       await storageRpc(options, "/internal/agent-serve/storage/kv/put", {
         key,

package/src/types.ts

@@ -194,8 +194,45 @@ export interface AgentConfig {
    * it and sends it with the deployment request. Ignored by local serving.
    */
   hosting?: AgentHostingOptions;
+  /**
+   * Engine-wide turn admission limits. See {@link AgentConcurrencyOptions}.
+   */
+  concurrency?: AgentConcurrencyOptions;
+}
+
+/**
+ * Turn admission limits on {@link AgentConfig.concurrency}.
+ *
+ * ```ts
+ * export default defineAgent({
+ *   // At most 3 sessions run a model turn at once; the rest queue FIFO.
+ *   concurrency: { maxRunningTurns: 3 },
+ * });
+ * ```
+ */
+export interface AgentConcurrencyOptions {
+  /**
+   * Max model turns running at once across **all** of this agent's
+   * sessions. When every slot is busy, newly admitted turns queue FIFO
+   * (surfaced as a durable `turn.queued` event and `queued: true` on
+   * `GET /v1/sessions`) instead of failing; each queued turn starts as
+   * soon as a slot frees. Positive integer, hard-capped at
+   * {@link MAX_RUNNING_TURNS_LIMIT}. Omit for unlimited.
+   *
+   * A queued turn still counts as `running` for busy semantics
+   * (follow-ups preempt it; direct tool calls get `SessionBusyError`),
+   * and a follow-up that preempts a queued turn re-queues at the back.
+   */
+  maxRunningTurns?: number;
 }
 
+/**
+ * Hard ceiling for {@link AgentConcurrencyOptions.maxRunningTurns}.
+ * Matches the eval harness ceiling: each running turn issues model
+ * provider requests, so unbounded parallelism is never meaningful.
+ */
+export const MAX_RUNNING_TURNS_LIMIT = 200;
+
 /**
  * Managed-hosting block on {@link AgentConfig.hosting}.
  */
@@ -367,6 +404,12 @@ export interface HostContext {
    * Slack follow-ups coalesce and drain at turn boundaries.
    */
   slackNudges?: SlackNudgeHostApi;
+  /**
+   * Playground eval batches (`/v1/dev/evals*`). Present once the serve host
+   * has attached an {@link import("./evals.js").HostEvalsApi}. Used by the
+   * built-in Slack `eval` directive and available to tools/handlers.
+   */
+  evals?: import("./evals.js").HostEvalsApi;
   /**
    * Author-facing durable JSON KV (`agentkit/v1/{agent}/kv/…`). Backed by
    * `agent/storage.ts` (`defineStorage`) when authored; otherwise files
@@ -531,6 +574,8 @@ export type ConnectionTransport =
       type?: "http" | "sse";
       url: string;
       headers?: Record<string, string>;
+      /** Host PKCE OAuth; `agentkit mcp oauth <name>`. No Authorization header. */
+      oauth?: true;
     }
   | {
       /** Slug of a peer agent mounted on the same serve host. */
@@ -578,13 +623,18 @@ export function isSymbolicConnectionTransport(
 export type ConnectionConfig = ConnectionTransport & {
   /** Documentation only; shown in `info` output. */
   description?: string;
+  /**
+   * Omit from SDK `mcpServers` (model never sees it). Still available on
+   * `host.mcp` for server tools / channel handlers. Does not affect
+   * cloud-native account connectors provisioned by the platform.
+   */
+  hostOnly?: boolean;
 };
 
 /**
- * An MCP connection is always available in three places:
- * - the Cursor agent (SDK `mcpServers`, local or cloud)
- * - the agent-serve host (`ctx.host.mcp` on in-process tools)
- * - channel / schedule handlers (`args.host.mcp`)
+ * An MCP connection is available to the agent (SDK `mcpServers`), host
+ * (`ctx.host.mcp`), and channel/schedule handlers — unless `hostOnly`,
+ * which keeps it off the model surface only.
  */
 export type ConnectionDefinition = ConnectionConfig &
   BrandedDefinition<"connection">;
@@ -671,6 +721,15 @@ export type SessionEventPayload =
       data: { sdkAgentId: string; url?: string };
     }
   | { type: "message.received"; data: { text: string } }
+  | {
+      /**
+       * The turn was admitted while every {@link AgentConcurrencyOptions.maxRunningTurns}
+       * slot was busy; it waits FIFO and `turn.started` follows once a slot
+       * frees. `position` is 1-based among waiting turns at enqueue time.
+       */
+      type: "turn.queued";
+      data: { position: number; maxRunningTurns: number };
+    }
   | { type: "turn.started"; data: Record<string, never> }
   | { type: "step.started"; data: { stepId: number } }
   | { type: "step.completed"; data: { stepId: number; durationMs: number } }
@@ -872,8 +931,14 @@ export interface SessionSummary {
   mode: SessionMode;
   title?: string;
   turnCount: number;
-  /** True while a turn is executing right now. */
+  /** True while a turn is executing right now (including queued turns). */
   running: boolean;
+  /**
+   * True while the session's admitted turn is waiting for a
+   * {@link AgentConcurrencyOptions.maxRunningTurns} slot (subset of
+   * {@link running}). Omitted when the agent has no turn limit.
+   */
+  queued?: boolean;
   createdAt: string;
   updatedAt: string;
   /** `<channelId>:<key>` wire token, or null when not addressable. */
@@ -886,6 +951,13 @@ export interface SessionSummary {
   externalUrl?: string;
 }
 
+/**
+ * Where `GET /v1/sessions` loaded rows from.
+ * - `cursor-hosted` — durable Bugbot `agent_serve_kv` via `cursorHostedStorage`
+ * - `local` — the serve process `--state-root` session store
+ */
+export type SessionListSource = "cursor-hosted" | "local";
+
 /**
  * A session handle scoped to the channel that owns it. This is what channel
  * route handlers get back from `send()` / `getSession()`.
@@ -1622,6 +1694,7 @@ export interface DiscoveredConnection {
   name: string;
   transport: ConnectionTransport;
   description?: string;
+  hostOnly?: boolean;
 }
 
 export interface DiscoveredChannel {
@@ -1676,6 +1749,8 @@ export interface ResolvedAgent {
   local?: AgentLocalOptions;
   /** Managed-hosting declarations from {@link AgentConfig.hosting}. */
   hosting?: AgentHostingOptions;
+  /** Validated turn admission limits from {@link AgentConfig.concurrency}. */
+  concurrency?: AgentConcurrencyOptions;
   tools: DiscoveredTool[];
   skills: DiscoveredSkill[];
   connections: DiscoveredConnection[];
@@ -1727,6 +1802,8 @@ export interface AgentProjectInfo {
   local?: { cwd?: string };
   /** Managed-hosting declarations when authored (egress allowlist, expected secrets). */
   hosting?: { egressDomains?: string[]; secretNames?: string[] };
+  /** Turn admission limits when authored (`concurrency` on `agent.ts`). */
+  concurrency?: { maxRunningTurns?: number };
   /**
    * The agent's own MCP surface (mounted at `<base>/v1/mcp`): other agents
    * and MCP clients delegate to this agent through these tools.
@@ -1741,7 +1818,7 @@ export interface AgentProjectInfo {
     inputSchema: JsonSchemaObject;
   }>;
   skills: Array<{ name: string; description: string }>;
-  connections: Array<{ name: string; transport: string }>;
+  connections: Array<{ name: string; transport: string; hostOnly?: boolean }>;
   subagents: Array<{
     name: string;
     description?: string;
@@ -1897,6 +1974,15 @@ export interface ServeOptions {
    * SSO/Okta proxy in front of the host).
    */
   allowAnonymousCursorGithub?: boolean;
+  /**
+   * Allow {@link allowAnonymous} together with
+   * `defineConnection({ cursorAccount: true })`. Without this opt-in, `serve`
+   * refuses to start because every admitted anonymous caller could drive the
+   * signed-in account's MCP connectors. Set it only when the network boundary
+   * already authenticates callers (e.g. an SSO/Okta proxy, or the hosted
+   * agent-serve alias token).
+   */
+  allowAnonymousCursorAccountMcp?: boolean;
   /**
    * Public base URL where this server is reachable from outside the host
    * (e.g. `https://agents.example.com`). Used to resolve peer