npm - @cursor/july - Versions diffs - 0.1.34 → 0.1.35 - Mend

@cursor/july 0.1.34 → 0.1.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (75) hide show

package/dist/docs/404.html +1 -1
package/dist/docs/ab.html +2 -2
package/dist/docs/assets/{app.FPupl4SP.js → app.D5Mv1T0U.js} +1 -1
package/dist/docs/assets/chunks/@localSearchIndexroot.Cu7b6o1D.js +1 -0
package/dist/docs/assets/chunks/{VPLocalSearchBox.Cd182Cu0.js → VPLocalSearchBox.CMq_BQce.js} +1 -1
package/dist/docs/assets/chunks/{theme.BEM3Okcd.js → theme.C6D9UPLK.js} +2 -2
package/dist/docs/building-with-agents.html +2 -2
package/dist/docs/concepts.html +2 -2
package/dist/docs/deployment.html +2 -2
package/dist/docs/evals.html +2 -2
package/dist/docs/example-agents/approval-buddy.html +2 -2
package/dist/docs/example-agents/benny.html +2 -2
package/dist/docs/example-agents/bugbot.html +2 -2
package/dist/docs/example-agents/codebase-wiki.html +2 -2
package/dist/docs/example-agents/codeowners-review.html +2 -2
package/dist/docs/example-agents/concierge.html +2 -2
package/dist/docs/example-agents/fsd.html +2 -2
package/dist/docs/example-agents/index.html +2 -2
package/dist/docs/example-agents/knowledge-base.html +2 -2
package/dist/docs/example-agents/oncall.html +2 -2
package/dist/docs/example-agents/security-reviewer.html +2 -2
package/dist/docs/example-agents/slack-agent.html +2 -2
package/dist/docs/example-agents/weather-agent.html +2 -2
package/dist/docs/guides/agent-to-agent.html +2 -2
package/dist/docs/guides/cloud-runtime.html +2 -2
package/dist/docs/guides/github.html +2 -2
package/dist/docs/guides/human-in-the-loop.html +2 -2
package/dist/docs/guides/mcp-oauth.html +2 -2
package/dist/docs/guides/slack.html +2 -2
package/dist/docs/guides/webhooks.html +2 -2
package/dist/docs/hillclimbing.html +2 -2
package/dist/docs/index.html +2 -2
package/dist/docs/quickstart.html +2 -2
package/dist/docs/reference/agent-config.html +2 -2
package/dist/docs/reference/channels.html +2 -2
package/dist/docs/reference/cli.html +2 -2
package/dist/docs/reference/connections.html +2 -2
package/dist/docs/reference/hooks.html +2 -2
package/dist/docs/reference/http-api.html +2 -2
package/dist/docs/reference/instructions.html +2 -2
package/dist/docs/reference/playground.html +2 -2
package/dist/docs/reference/project-layout.html +2 -2
package/dist/docs/reference/prompt.html +2 -2
package/dist/docs/reference/schedules.html +2 -2
package/dist/docs/reference/sessions.html +2 -2
package/dist/docs/reference/skills.html +2 -2
package/dist/docs/reference/subagents.html +2 -2
package/dist/docs/reference/tools.html +2 -2
package/dist/docs/scaffolding-agents.html +2 -2
package/dist/docs/storage.html +2 -2
package/dist/docs/troubleshooting.html +2 -2
package/dist/internal/host-kv.d.ts +6 -2
package/dist/internal/host-kv.d.ts.map +1 -1
package/dist/internal/session-engine.d.ts.map +1 -1
package/dist/internal/session-engine.js +15 -6
package/dist/internal/storage-coordinator.d.ts +9 -1
package/dist/internal/storage-coordinator.d.ts.map +1 -1
package/dist/internal/storage-coordinator.js +7 -0
package/dist/internal/storage-roles.d.ts +78 -0
package/dist/internal/storage-roles.d.ts.map +1 -0
package/dist/internal/storage-roles.js +24 -0
package/dist/internal/workspace.d.ts +26 -0
package/dist/internal/workspace.d.ts.map +1 -1
package/dist/internal/workspace.js +53 -0
package/dist/playground/assets/{index-CDDWw0YX.js → index-D7OV8B_H.js} +40 -40
package/dist/playground/assets/index-DOb96C0M.css +1 -0
package/dist/playground/index.html +2 -2
package/package.json +1 -1
package/src/internal/host-kv.ts +6 -2
package/src/internal/session-engine.ts +20 -8
package/src/internal/storage-coordinator.ts +15 -1
package/src/internal/storage-roles.ts +86 -0
package/src/internal/workspace.ts +62 -1
package/dist/docs/assets/chunks/@localSearchIndexroot.WoYunhnT.js +0 -1
package/dist/playground/assets/index-MVuNTd8v.css +0 -1

package/dist/playground/index.html CHANGED Viewed

@@ -8,8 +8,8 @@
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agent-serve playground</title>
-    <script type="module" crossorigin src="./assets/index-CDDWw0YX.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-MVuNTd8v.css">
+    <script type="module" crossorigin src="./assets/index-D7OV8B_H.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-DOb96C0M.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {

package/src/internal/host-kv.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 also catalogs server tools under that MCP server name;
+        // without it a model told to "use <server tool>" finds no script
+        // and improvises a local substitute instead of calling the host.
+        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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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)
@@ -157,16 +165,64 @@ 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, 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: 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 — 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: ResolvedAgent,
-  options: { includeScripts: boolean }
+  options: { includeScripts: boolean; serverToolsMcpName?: string }
 ): string {
   return [
     agent.instructions?.trim() ?? "",
@@ -174,6 +230,11 @@ export function buildAgentsMdContent(
     buildAgentToolsCatalog(agent.tools, {
       includeScripts: options.includeScripts,
     }),
+    options.serverToolsMcpName === undefined
+      ? ""
+      : buildServerToolsCatalog(agent.tools, {
+          mcpServerName: options.serverToolsMcpName,
+        }),
   ]
     .filter((part) => part !== "")
     .join("\n\n");