@cursor/july 0.1.34 → 0.1.35

package/dist/internal/storage-coordinator.js

@@ -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.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }

package/dist/internal/storage-roles.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=storage-roles.d.ts.map

package/dist/internal/storage-roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-roles.d.ts","sourceRoot":"","sources":["../../src/internal/storage-roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3C,uEAAuE;IACvE,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACjC,kEAAkE;IAClE,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3C,2EAA2E;IAC3E,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAEzE,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IAEjC,YAAY,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACzC,oBAAoB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACjD,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC9D,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IACtE,wBAAwB,CACtB,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;CACvC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IACzD,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,QAAQ,IAAI,cAAc,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,UAAU,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,mBAAmB,IAAI,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;CACxD"}

package/dist/internal/storage-roles.js

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+export {};

package/dist/internal/workspace.d.ts

@@ -32,6 +32,13 @@ export interface MaterializeWorkspaceOptions {
 export declare function buildCloudMemorySection(agentName: string): string;
 /** Relative path of an agent-side tool script inside the session workspace. */
 export declare function agentToolScriptPath(toolName: string): string;
+/**
+ * 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 declare 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)
@@ -52,15 +59,34 @@ export declare function withIdentityPreamble(name: string, instructions: string
 export declare function buildAgentToolsCatalog(tools: DiscoveredTool[], options?: {
     includeScripts: boolean;
 }): string;
+/**
+ * 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, and the agent-tool catalog teaches a "recreate the script if
+ * missing" pattern — without this section a cloud model that cannot find a
+ * script for a server tool improvises a local substitute instead of calling
+ * the real tool, so its host-side effects silently never happen.
+ */
+export declare function buildServerToolsCatalog(tools: DiscoveredTool[], options: {
+    mcpServerName: string;
+}): string;
 /**
  * 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. Local
+ * runtimes omit it — there the harness exposes server tools natively.
  */
 export declare function buildAgentsMdContent(agent: ResolvedAgent, options: {
     includeScripts: boolean;
+    serverToolsMcpName?: string;
 }): string;
 /**
  * True when `dir` sits strictly inside a git repository (a `.git` exists in

package/dist/internal/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA6CR;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAAE,GACnC,MAAM,CAUR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/internal/workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;IACd;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,GAAE;IAAE,cAAc,EAAE,OAAO,CAAA;CAA8B,GAC/D,MAAM,CA6CR;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GACjC,MAAM,CA4BR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAChE,MAAM,CAeR;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAcrE;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkCf;AAqGD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAO3D;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/internal/workspace.js

@@ -37,6 +37,13 @@ export function buildCloudMemorySection(agentName) {
 export function agentToolScriptPath(toolName) {
     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)
@@ -117,12 +124,53 @@ export function buildAgentToolsCatalog(tools, options = { includeScripts: false
     }
     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, and the agent-tool catalog teaches a "recreate the script if
+ * missing" pattern — without this section a cloud model that cannot find a
+ * script for a server tool improvises a local substitute instead of calling
+ * the real tool, so its host-side effects silently never happen.
+ */
+export function buildServerToolsCatalog(tools, options) {
+    const serverTools = tools.filter((tool) => tool.execution === "server");
+    if (serverTools.length === 0) {
+        return "";
+    }
+    const parts = [
+        "## 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 — list that server's tools and call them by name through your MCP tooling.`,
+        "There are no local scripts for these tools. NEVER create, edit, or run a local script or other substitute for them: a local re-implementation cannot produce their real effects on the host.",
+        "",
+    ];
+    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. Local
+ * runtimes omit it — there the harness exposes server tools natively.
  */
 export function buildAgentsMdContent(agent, options) {
     var _a;
@@ -133,6 +181,11 @@ export function buildAgentsMdContent(agent, options) {
         buildAgentToolsCatalog(agent.tools, {
             includeScripts: options.includeScripts,
         }),
+        options.serverToolsMcpName === undefined
+            ? ""
+            : buildServerToolsCatalog(agent.tools, {
+                mcpServerName: options.serverToolsMcpName,
+            }),
     ]
         .filter((part) => part !== "")
         .join("\n\n");