@cursor/july 0.1.10 → 0.1.11

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. */
@@ -1629,6 +1694,7 @@ export interface DiscoveredConnection {
   name: string;
   transport: ConnectionTransport;
   description?: string;
+  hostOnly?: boolean;
 }
 
 export interface DiscoveredChannel {
@@ -1683,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[];
@@ -1734,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.
@@ -1748,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;