@cursor/july 0.1.34 → 0.1.36

package/src/files-backends/agent-store-presigned-url.ts

@@ -5,6 +5,7 @@
  * root is a barrel over the whole library, and bundling through it inlines
  * every module the barrel can reach (sync engine, local sqlite index, secure
  * open) into the published tarball. This module has no imports of its own, so
- * the bundle stays limited to the validator.
+ * the bundle stays limited to the validator. The bundler resolves that entry
+ * via the `anysphere-source` export so it does not need a prebuilt `dist/`.
  */
 export { createAgentStorePresignedUrlValidatorForBackend } from "@anysphere/agent-store-sync/presigned-url";

package/src/internal/cli-github.ts

@@ -42,6 +42,7 @@ import {
   synthesizeGitHubEvent,
 } from "../channels/github/replay.js";
 import { resolveAgentMounts } from "./discovery.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
 import { startFanoutServer } from "./github-fanout.js";
 
 const execFileAsync = promisify(execFile);
@@ -88,21 +89,21 @@ export interface GithubCliOptions {
   out?: string;
 }
 
-const GITHUB_HELP = `agent-serve github — forward live GitHub webhooks to a local agent
+const GITHUB_HELP = `${CLI} github — forward live GitHub webhooks to a local agent
 
 Usage:
-  agent-serve github forward  [--dir .] [--slug S] [--channel C]
+  ${CLI} github forward  [--dir .] [--slug S] [--channel C]
                               [--repo owner/repo | --org ORG]
                               [--events a,b,c] [--url URL]
                               [--host 127.0.0.1] [--port 3000]
                               [--secret S] [--install]
-  agent-serve github replay   <pr_url|owner/repo#N> [--events a,b,c | *]
+  ${CLI} github replay   <pr_url|owner/repo#N> [--events a,b,c | *]
                               [--action A] [--conclusion C] [--comment "…"]
                               [--context CTX] [--dir .] [--slug S] [--channel C]
                               [--host H] [--port N] [--url URL] [--secret S]
                               [--dry-run] [--out DIR] [--json]
-  agent-serve github events   [--dir .] [--host H] [--port N] [--json]
-  agent-serve github doctor   [--install] [--json]
+  ${CLI} github events   [--dir .] [--host H] [--port N] [--json]
+  ${CLI} github doctor   [--install] [--json]
 
 Commands:
   forward   Run \`gh webhook forward\` for the discovered githubChannel()s.
@@ -122,8 +123,8 @@ Commands:
 
 Prerequisites:
   - gh CLI logged in (\`gh auth login\`).
-  - ${GITHUB_WEBHOOK_EXTENSION} extension (\`agent-serve github doctor --install\`).
-  - The agent already serving (\`agent-serve serve --dir . --dev\`).
+  - ${GITHUB_WEBHOOK_EXTENSION} extension (\`${CLI} github doctor --install\`).
+  - The agent already serving (\`${CLI} serve --dir . --dev\`).
 
 Notes:
   - Set GITHUB_WEBHOOK_SECRET (or pass --secret) so the forwarded deliveries

package/src/internal/cli-slack.ts

@@ -71,22 +71,22 @@ export interface SlackCliOptions {
   err?: (text: string) => void;
 }
 
-const SLACK_HELP = `agent-serve slack — Slack channel pack helpers (Socket Mode)
+const SLACK_HELP = `${CLI} slack — Slack channel pack helpers (Socket Mode)
 
 Usage:
-  agent-serve slack setup
-  agent-serve slack create    [--dir .] [--name NAME] [--slack-team T0123ABCD]
+  ${CLI} slack setup
+  ${CLI} slack create    [--dir .] [--name NAME] [--slack-team T0123ABCD]
                                 [--prod] [--team <id>] [--icon URL-or-FILE]
                                 [--force] [--prefix PREFIX | --no-prefix] [--json]
-  agent-serve slack destroy   [--dir .] [--slack-team T0123ABCD] [--prod]
+  ${CLI} slack destroy   [--dir .] [--slack-team T0123ABCD] [--prod]
                                 [--team <id>] [--json]
-  agent-serve slack icon      <URL-or-FILE> [--dir .] [--slack-team T0123ABCD]
+  ${CLI} slack icon      <URL-or-FILE> [--dir .] [--slack-team T0123ABCD]
                                 [--prod] [--team <id>] [--json]
-  agent-serve slack init      [--dir .] [--name NAME] [--prefix PREFIX | --no-prefix]
+  ${CLI} slack init      [--dir .] [--name NAME] [--prefix PREFIX | --no-prefix]
                                 [--channel-posts]
-  agent-serve slack manifest --env dev|prod|both [--dir .] [--name NAME]
+  ${CLI} slack manifest --env dev|prod|both [--dir .] [--name NAME]
                                 [--print]
-  agent-serve slack doctor [--dir .] [--prefix PREFIX | --no-prefix] [--json]
+  ${CLI} slack doctor [--dir .] [--prefix PREFIX | --no-prefix] [--json]
 
 create/destroy/icon — Cursor "Add to Slack" managed provisioning:
   create   One-command Path B setup: connects the Slack workspace (browser
@@ -94,7 +94,7 @@ create/destroy/icon — Cursor "Add to Slack" managed provisioning:
            Socket Mode app from the generated manifest, writes the token
            pair into <dir>/.env.local, then runs doctor (prose mode; --json
            reports without the doctor pass). Requires
-           \`agent-serve login\` (or CURSOR_API_KEY) and the feature gate.
+           \`${CLI} login\` (or CURSOR_API_KEY) and the feature gate.
            --prod provisions the prod app (default dev); --slack-team picks
            the workspace when several are connected. --icon sets the app's
            icon (best-effort: a bad icon warns, never fails the create).

package/src/internal/event-mapper.ts

@@ -11,6 +11,8 @@ import type {
 import type { SessionEventPayload, TurnUsage } from "../types.js";
 
 const CUSTOM_TOOLS_PROVIDER = "custom-user-tools";
+/** Authored server tools on cloud turns; keep in sync with `SERVER_TOOLS_MCP_SERVER_NAME`. */
+const SERVER_TOOLS_PROVIDER = "agentsdk-tools";
 
 /**
  * Nested interaction updates from a task/subagent tool-call-delta.
@@ -354,16 +356,19 @@ export class TurnEventMapper {
 }
 
 /**
- * Human-meaningful tool identity for stream events. In-process tools calls
- * arrive as MCP calls against the synthetic `custom-user-tools` server; they
- * surface under the customer's bare tool name.
+ * Human-meaningful tool identity for stream events. Authored server tools
+ * arrive as MCP calls against `custom-user-tools` (local) or `agentsdk-tools`
+ * (cloud); both surface under the customer's bare tool name.
  */
 export function describeToolCall(toolCall: ToolCall): ToolCallDescription {
   switch (toolCall.type) {
     case "mcp": {
       const providerIdentifier = toolCall.args.providerIdentifier;
       const toolName = toolCall.args.toolName;
-      if (providerIdentifier === CUSTOM_TOOLS_PROVIDER) {
+      if (
+        providerIdentifier === CUSTOM_TOOLS_PROVIDER ||
+        providerIdentifier === SERVER_TOOLS_PROVIDER
+      ) {
         return {
           toolName: toolName ?? "custom-tool",
           args: toolCall.args.args,

package/src/internal/host-kv.ts

@@ -11,12 +11,16 @@ import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { storageKeys } from "../storage.js";
 import type { HostKvApi, JsonValue } from "../types.js";
-import type { StorageCoordinator } from "./storage-coordinator.js";
+import type { AuthorKvStore } from "./storage-roles.js";
 
 export interface CreateHostKvApiOptions {
   agentName: string;
   stateRoot: string;
-  storage?: StorageCoordinator;
+  /**
+   * Author KV backend. Narrowed to {@link AuthorKvStore} so this path cannot
+   * reach framework session state, which is headed somewhere else entirely.
+   */
+  storage?: AuthorKvStore;
 }
 
 /** Build the host KV API for one agent process. */

package/src/internal/session-engine.ts

@@ -103,6 +103,7 @@ import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections
 import type { AgentRunner } from "./sdk-runner.js";
 import { SessionStore } from "./session-store.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
+import type { FrameworkSessionStore } from "./storage-roles.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import {
   type EstimateTurnCostFn,
@@ -115,6 +116,7 @@ import {
   buildCloudMemorySection,
   isNestedInGitRepo,
   materializeWorkspace,
+  SERVER_TOOLS_MCP_SERVER_NAME,
   writeWorkspaceFiles,
 } from "./workspace.js";
 
@@ -1463,8 +1465,18 @@ export class SessionEngine {
       if (runtime === "cloud") {
         // Cloud VMs have no materialized workspace: ship the full context,
         // including agent tool script bodies. On hosted deployments the
-        // shared memory journal is on the store mount — say where.
-        const preamble = buildAgentsMdContent(agent, { includeScripts: true });
+        // shared memory journal is on the store mount — say where. When the
+        // turn carries the session-bound server-tool MCP endpoint, the
+        // preamble catalogs server tools under that MCP server name *before*
+        // the agent-tool "write the script if missing" recipe, so a model
+        // told to "use <server tool>" calls MCP instead of inventing a .sh.
+        const preamble = buildAgentsMdContent(agent, {
+          includeScripts: true,
+          serverToolsMcpName:
+            this.cloudServerToolsConnection === undefined
+              ? undefined
+              : SERVER_TOOLS_MCP_SERVER_NAME,
+        });
         const memorySection = isCursorHostedFilesAvailable()
           ? `\n\n${buildCloudMemorySection(this.project.name)}`
           : "";
@@ -1677,16 +1689,16 @@ export class SessionEngine {
       this.cloudServerToolsConnection !== undefined &&
       this.project.agent.tools.some((tool) => tool.execution === "server")
     ) {
-      if (servers["agentsdk-tools"] !== undefined) {
+      if (servers[SERVER_TOOLS_MCP_SERVER_NAME] !== undefined) {
         throw new Error(
-          'MCP connection name "agentsdk-tools" is reserved for authored server tools on cloud turns.'
+          `MCP connection name "${SERVER_TOOLS_MCP_SERVER_NAME}" is reserved for authored server tools on cloud turns.`
         );
       }
       const connection = this.cloudServerToolsConnection;
       if ("url" in connection) {
         const url = new URL(connection.url);
         url.searchParams.set("agentkitSessionId", sessionId);
-        servers["agentsdk-tools"] = {
+        servers[SERVER_TOOLS_MCP_SERVER_NAME] = {
           ...connection,
           url: url.toString(),
         };
@@ -2938,7 +2950,7 @@ export class SessionEngine {
   }
 
   private async runBulkRestore(
-    storage: StorageCoordinator,
+    storage: FrameworkSessionStore,
     policy: { maxSessions: number; maxAgeMs: number; maxTotalBytes: number }
   ): Promise<void> {
     const loaded = await storage.listSessions();
@@ -3099,7 +3111,7 @@ export class SessionEngine {
   }
 
   private async loadAndMaterializeByContinuation(
-    storage: StorageCoordinator,
+    storage: FrameworkSessionStore,
     channelId: string,
     continuationKey: string
   ): Promise<SessionRecord | undefined> {
@@ -3115,7 +3127,7 @@ export class SessionEngine {
   }
 
   private async loadAndMaterializeById(
-    storage: StorageCoordinator,
+    storage: FrameworkSessionStore,
     sessionId: string
   ): Promise<SessionRecord | undefined> {
     const record = await storage.getSessionById(sessionId);

package/src/internal/storage-coordinator.ts

@@ -14,6 +14,13 @@
  * and A/B metrics go to their dedicated tables (`evals` / `abs`).
  * Reminder documents live on the control plane. Everything shares one
  * bounded, serialized queue.
+ *
+ * It does three unrelated jobs, declared separately as
+ * {@link FrameworkSessionStore}, {@link AuthorKvStore}, and
+ * {@link EvalAbStore} — see `storage-roles.ts` for why they differ and where
+ * each is headed. The queue stays shared: it is one bounded, serialized chain
+ * per agent, and splitting it would change backpressure behavior, which this
+ * seam deliberately does not touch.
  */
 
 import type { ABMetricSample } from "../ab.js";
@@ -30,6 +37,11 @@ import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
 import type { ABSnapshot } from "./ab-snapshot.js";
 import { describeError } from "./describe-error.js";
 import type { EvalRunStorage } from "./eval-run-store.js";
+import type {
+  AuthorKvStore,
+  EvalAbStore,
+  FrameworkSessionStore,
+} from "./storage-roles.js";
 
 /** Event types that close a unit of work — flush point for turn-end batching. */
 const TURN_BOUNDARY_EVENTS: ReadonlySet<SessionEvent["type"]> = new Set([
@@ -85,7 +97,9 @@ interface SessionBuffer {
   debounceTimer?: ReturnType<typeof setTimeout>;
 }
 
-export class StorageCoordinator {
+export class StorageCoordinator
+  implements FrameworkSessionStore, AuthorKvStore, EvalAbStore
+{
   readonly policy: ResolvedStoragePolicy;
 
   private readonly definition: StorageDefinition;

package/src/internal/storage-roles.ts

@@ -0,0 +1,86 @@
+/**
+ * The three unrelated jobs `defineStorage` currently does, named separately.
+ *
+ * {@link import("./storage-coordinator.js").StorageCoordinator} implements all
+ * three today over one sink and one delivery queue. Splitting the *types* is
+ * the seam that lets each job change independently:
+ *
+ * - {@link FrameworkSessionStore} is framework state. Session records, event
+ *   chunks, and the continuation index are how a session survives the process,
+ *   so they belong to Agent Serve, not to the agent. Today they persist only
+ *   when the author writes `agent/storage.ts` — the defect this seam exists to
+ *   let us fix, by giving the framework its own provider that is automatic and
+ *   not author-configurable.
+ * - {@link AuthorKvStore} is author state: whatever `ctx.host.kv` was handed.
+ *   It converges onto the author file plane, which is a different destination
+ *   from the one above.
+ * - {@link EvalAbStore} is playground/experiment bookkeeping with its own
+ *   dedicated tables, and follows neither.
+ *
+ * Consumers should depend on the narrowest role they use. That is what keeps a
+ * later change to framework persistence from silently reaching author KV, and
+ * it is why these are interfaces rather than a comment on one class.
+ */
+
+import type { ABMetricSample } from "../ab.js";
+import type { StorageContext } from "../storage.js";
+import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
+import type { ABSnapshot } from "./ab-snapshot.js";
+import type { EvalRunStorage } from "./eval-run-store.js";
+
+/**
+ * Framework-owned session durability: what has to be true for a session to
+ * outlive the process that served it.
+ *
+ * Writes are fire-and-forget by design — a throwing backend is logged and its
+ * write dropped, because storage must never stall or fail a turn. That is
+ * at-most-once, and it is the property Track F later has to tighten, since a
+ * dropped record is a session that cannot be restored.
+ */
+export interface FrameworkSessionStore {
+  /** Durable session-record update; coalesced until the next flush. */
+  sessionRecord(record: SessionRecord): void;
+  /** One appended session event; batched per turn or debounce window. */
+  event(event: SessionEvent): void;
+  /** Marks an event delivered, for backends that track dispatch. */
+  eventDispatched(event: SessionEvent): void;
+  /** Flush everything buffered for one session (ordered: events, record). */
+  flushSession(sessionId: string, reason?: StorageContext["reason"]): void;
+
+  /** True when the backend can list every session in one bulk read. */
+  readonly canBulkRestore: boolean;
+  /** True when the backend is the Cursor-hosted one rather than an authored sink. */
+  readonly isCursorHosted: boolean;
+
+  listSessions(): Promise<SessionRecord[]>;
+  listSessionsFromSink(): Promise<SessionRecord[]>;
+  listSessionEvents(sessionId: string): Promise<SessionEvent[]>;
+  getSessionById(sessionId: string): Promise<SessionRecord | undefined>;
+  getSessionByContinuation(
+    channelId: string,
+    continuationKey: string
+  ): Promise<SessionRecord | undefined>;
+}
+
+/**
+ * Author-facing durable JSON behind `ctx.host.kv`.
+ *
+ * Deployment-wide on purpose: the point is state an author saves in one
+ * session and reads back in a later one, so unlike `ctx.host.files` there is
+ * no session scope to default to.
+ */
+export interface AuthorKvStore {
+  /** False when no backend is configured; callers fall back to local disk. */
+  readonly supportsAuthorKv: boolean;
+  kvGet(authorKey: string): Promise<JsonValue | undefined>;
+  kvPut(authorKey: string, value: JsonValue): Promise<void>;
+  kvDelete(authorKey: string): Promise<void>;
+}
+
+/** Playground eval batches and live A/B metrics, on their own tables. */
+export interface EvalAbStore {
+  evalRuns(): EvalRunStorage | undefined;
+  abSample(sample: ABMetricSample): void;
+  abSnapshot(snapshot: ABSnapshot): void;
+  getLatestAbSnapshot(): Promise<ABSnapshot | undefined>;
+}

package/src/internal/workspace.ts

@@ -66,6 +66,14 @@ export function agentToolScriptPath(toolName: string): string {
   return `.agent-serve/tools/${toolName}.sh`;
 }
 
+/**
+ * Reserved MCP connection name under which authored server tools are served
+ * to cloud turns (the session-bound tool MCP endpoint). Shared between the
+ * turn's MCP config and the first-prompt server-tool catalog so the model is
+ * told exactly where those tools live.
+ */
+export const SERVER_TOOLS_MCP_SERVER_NAME = "agentsdk-tools";
+
 /**
  * Always-on identity line prepended when composing instructions. Sourced from
  * {@link ResolvedAgent.name} (`defineAgent({ name })`, else package/dir name)
@@ -121,6 +129,7 @@ export function buildAgentToolsCatalog(
     "",
     "These tools run in the agent environment (not on the agent-serve host).",
     "Pass a JSON object on stdin matching the input schema; read the result from stdout.",
+    "Only the tools in this section are scripts. Do not create, edit, or run a script for any other tool name.",
     "",
   ];
 
@@ -157,20 +166,76 @@ export function buildAgentToolsCatalog(
   return `${parts.join("\n").trimEnd()}\n`;
 }
 
+/**
+ * Markdown catalog of authored server tools for the cloud first prompt.
+ *
+ * Server tools execute on the serve host and reach cloud turns only as MCP
+ * tools on {@link SERVER_TOOLS_MCP_SERVER_NAME}. Instructions reference them
+ * by bare name. The agent-tool catalog still teaches "write the script if
+ * missing" for *agent* tools; this section must come first on cloud and
+ * say that server tools are MCP-only, or the model copies that recipe onto
+ * a host tool and the host-side marker never appears.
+ */
+export function buildServerToolsCatalog(
+  tools: DiscoveredTool[],
+  options: { mcpServerName: string }
+): string {
+  const serverTools = tools.filter((tool) => tool.execution === "server");
+  if (serverTools.length === 0) {
+    return "";
+  }
+
+  const parts: string[] = [
+    "## Server tools",
+    "",
+    `These tools execute on the agent-serve host, not in this environment. They are available ONLY as MCP tools on the \`${options.mcpServerName}\` MCP server.`,
+    "Call them through your MCP tooling: list that server's tools, then invoke the tool by its exact name (GetMcpTools / CallMcpTool, or the equivalent). There is no `.agent-serve/tools/<name>.sh` for any tool in this section.",
+    `If the \`${options.mcpServerName}\` server is not in your MCP server list, stop and report that. Do not write, edit, or run a local script or other substitute. A local re-implementation cannot produce the host-side marker, logs, or session events.`,
+    "",
+  ];
+
+  for (const tool of serverTools) {
+    parts.push(`### \`${tool.name}\``);
+    parts.push("");
+    parts.push(tool.description.trim());
+    parts.push("");
+    parts.push("Input schema:");
+    parts.push("");
+    parts.push("```json");
+    parts.push(JSON.stringify(tool.inputSchema, null, 2));
+    parts.push("```");
+    parts.push("");
+  }
+
+  return `${parts.join("\n").trimEnd()}\n`;
+}
+
 /**
  * The full AGENTS.md-equivalent context for an agent: instructions, identity
  * section, and the agent-side tool catalog. Written to the session workspace
  * as `AGENTS.md`, and inlined into the first turn's prompt when the harness
  * cannot discover that file (cloud runtime, or a local workspace the harness
  * will not treat as the project root — see {@link isNestedInGitRepo}).
+ *
+ * `serverToolsMcpName` is cloud-only: when the turn's MCP config carries the
+ * session-bound server-tool endpoint, the catalog names that server so the
+ * model calls the real tools instead of inventing local stand-ins. It is
+ * emitted *before* the agent-tool catalog so "write the script if missing"
+ * cannot be read as applying to server-tool names. Local runtimes omit it —
+ * there the harness exposes server tools natively.
  */
 export function buildAgentsMdContent(
   agent: ResolvedAgent,
-  options: { includeScripts: boolean }
+  options: { includeScripts: boolean; serverToolsMcpName?: string }
 ): string {
   return [
     agent.instructions?.trim() ?? "",
     buildIdentitySection(agent),
+    options.serverToolsMcpName === undefined
+      ? ""
+      : buildServerToolsCatalog(agent.tools, {
+          mcpServerName: options.serverToolsMcpName,
+        }),
     buildAgentToolsCatalog(agent.tools, {
       includeScripts: options.includeScripts,
     }),