@cursor/july 0.1.32 → 0.1.34

package/src/bin/agent-serve.ts

@@ -10,6 +10,7 @@
  *   agent-serve run       [--dir .] [--message "..."] [--json|--text]
  *   agent-serve trajectory --events <file.ndjson>
  *   agent-serve init      [dir] [--json]
+ *   agent-serve convert-automation <url> [--dir <path>] [--json]
  *   agent-serve eval        [--dir .] [evalId...]
  *   agent-serve validate   [--dir .]
  *   agent-serve slack     <subcommand>
@@ -69,7 +70,7 @@ const HELP = `${CLI} — serve a filesystem-defined Cursor agent over channels
 Usage:
   ${CLI} serve       [--dir <path>] [--port <n>] [--host <host>] [--dev]
                           [--mode single|multi] [--api-key <key>] [--no-schedules]
-                          [--public-url <url>]
+                          [--public-url <url>] [--cloud-tools-url <url>]
                           [--cursor-events --repo <owner/name>]...
   ${CLI} dev         [path] [--port <n>] [--host <host>] …
                           Same flags as serve; implies --dev. Path defaults to
@@ -100,6 +101,7 @@ Usage:
   ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
                           [--session <id>] [--slug <slug>] [--team <id>]
   ${CLI} init        [dir] [--json]
+  ${CLI} convert-automation <url> [--dir <path>] [--json]
   ${CLI} install-skills [--print] [--json]
   ${CLI} mcp         --prod [--slug <slug>] [--team <id>] [--dir <path>]
                           | --url <baseUrl> [--bearer-token <t>]
@@ -188,6 +190,17 @@ Commands:
               run login when unsigned, then print next steps. --json is
               machine-readable and never blocks on login. No directory:
               print the setup guide.
+  convert-automation
+              Export a Cursor Automation into an agentkit project. <url> is
+              the dashboard URL (…/automations/<uuid> or
+              …/custom-agents/<uuid>) or a bare uuid. Fetches the definition
+              with your Cursor credentials, writes the converted files into
+              --dir (default ./<automation-name>), fills in the init scaffold
+              around them (existing files are kept), and installs npm
+              dependencies. MCP servers convert to Cursor-account connections
+              resolved at runtime (manage authorization in Cursor, dashboard
+              -> MCP). Review the project, then run \`validate\` / \`dev\`.
+              Warnings never fail the command.
   install-skills
               Install (or refresh) the Agent SDK skills for coding agents in
               ~/.cursor/skills/agentkit and print where they landed. \`init\`
@@ -299,6 +312,9 @@ Options:
                      (e.g. https://agent-serve.example.com). Required for peer
                      connections (defineConnection({ agent })) on cloud-runtime
                      turns; local turns always use loopback.
+  --cloud-tools-url  serve: authenticated HTTP MCP URL for this deployment's
+                     direct server-tool endpoint. Hosted AgentSDK deployments
+                     configure this automatically.
   --no-schedules     Disable the cron runner outside dev mode.
   --no-control-plane serve: do not start the bundled control plane (schedule
                      and reminder clocks). Cursor hosting passes this so the
@@ -358,7 +374,8 @@ Options:
   --no-artifacts     eval: do not write run artifacts.
   --skip-report      eval: ignore reporters from evals.config.ts / eval files.
   --no-stream        run/eval: silence live progress on stderr (JSON still prints).
-  --json             JSON output (init/install-skills/info/chat/eval/logs/
+  --json             JSON output (init/convert-automation/install-skills/
+                     info/chat/eval/logs/
                      sessions/session/github; run defaults to JSON). logs:
                      NDJSON progress/log events. session: trajectory JSON
                      (not raw events).
@@ -486,6 +503,7 @@ async function main(argv: string[]): Promise<number> {
       name: { type: "string" },
       env: { type: "string" },
       "public-url": { type: "string" },
+      "cloud-tools-url": { type: "string" },
       "mount-path": { type: "string" },
       "base-url": { type: "string" },
       print: { type: "boolean", default: false },
@@ -604,6 +622,21 @@ async function main(argv: string[]): Promise<number> {
       });
     }
 
+    case "convert-automation": {
+      const { cmdConvertAutomation } = await import(
+        "../internal/cli-convert-automation.js"
+      );
+      const dirFlagPassed =
+        rest.includes("--dir") || rest.some((arg) => arg.startsWith("--dir="));
+      return cmdConvertAutomation({
+        url: positionals[0],
+        // Default target is ./<automation-name-slug>, not the cwd.
+        dir: dirFlagPassed ? dir : undefined,
+        json: values.json,
+        apiKey: values["api-key"],
+      });
+    }
+
     case "install-skills": {
       const { cmdInstallSkills } = await import("../internal/cli-skills.js");
       return cmdInstallSkills({
@@ -1170,6 +1203,7 @@ async function main(argv: string[]): Promise<number> {
         playground: values["no-playground"] === true ? false : undefined,
         docs: values["no-docs"] === true ? false : undefined,
         publicUrl: values["public-url"],
+        cloudToolsUrl: values["cloud-tools-url"],
         cursorEvents:
           values["cursor-events"] === true
             ? { repos: values.repo ?? [] }

package/src/channels/github/types.ts

@@ -404,10 +404,12 @@ export type GitHubStatusHook = (
 ) => GitHubDispatchResult;
 
 /**
- * Catch-all for any webhook event (including ones with typed hooks). Runs
- * after the typed handler path when the typed hook is absent or returns
- * undefined-as-no-handler; for events with no typed hook, this is the only
- * dispatch path. Return `null` to ignore.
+ * Catch-all for webhook events with no typed hook (`push`,
+ * `pull_request_review`, `pull_request_review_thread`, …). Events that have
+ * a typed hook (`pull_request`, `issues`, `check_suite`, `check_run`,
+ * `workflow_run`, `status`, comments) NEVER reach this hook — when their
+ * typed hook is not declared, the delivery is skipped as `no_handler`
+ * instead of falling back here. Return `null` to ignore.
  */
 export type GitHubEventHook = (
   ctx: GitHubEventContext,
@@ -490,9 +492,10 @@ export interface GitHubChannelOptions {
   /** Opt-in legacy commit `status` webhook handler. No default dispatch. */
   onStatus?: GitHubStatusHook;
   /**
-   * Catch-all webhook handler. Invoked for events without a typed hook, and
-   * as a fallback when a typed hook is not declared. Prefer typed hooks when
-   * the event is known.
+   * Catch-all webhook handler for events without a typed hook (`push`,
+   * `pull_request_review`, …). NOT a fallback: events with a typed hook are
+   * skipped as `no_handler` when that hook is undeclared, and never reach
+   * this one. Prefer typed hooks when the event has one.
    */
   onEvent?: GitHubEventHook;
   /**

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

@@ -1,8 +1,10 @@
 /**
- * Re-export the agent-store SSRF pin used by `cursorHostedFiles`.
+ * Re-export bundled into dist by `scripts/bundle-publish-shims.mjs`.
  *
- * Source keeps a single dependency on `@anysphere/agent-store-sync` (dev-only
- * for publish). The build overwrites the emitted `dist` copy with an esbuild
- * bundle so the npm tarball does not need that private package at runtime.
+ * Imports the `presigned-url` entry point rather than the package root: the
+ * 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.
  */
-export { createAgentStorePresignedUrlValidatorForBackend } from "@anysphere/agent-store-sync";
+export { createAgentStorePresignedUrlValidatorForBackend } from "@anysphere/agent-store-sync/presigned-url";

package/src/files.ts

@@ -140,6 +140,33 @@ export const fileKeys = {
     `${STORAGE_KEY_ROOT}/${agent}/files/sessions/${sessionId}/`,
 } as const;
 
+/**
+ * Framework-owned keys for state that lives on the deployment's Agent Store
+ * but is not author `host.files` data: artifact rows and payloads, and the
+ * cross-session memory journal. Kept out of `files/` so author listings never
+ * see framework rows.
+ */
+export const agentStoreKeys = {
+  artifactRow: (agent: string, id: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/artifacts/rows/${encodeURIComponent(id)}.json`,
+  artifactRowPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/artifacts/rows/`,
+  artifactContent: (agent: string, id: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/artifacts/content/${encodeURIComponent(id)}`,
+  memoryDir: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/memory`,
+  memoryJournal: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/memory/journal.jsonl`,
+  memoryJournalRotated: (agent: string, stamp: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/memory/journal-${stamp}.jsonl`,
+} as const;
+
+/**
+ * Deployment store FUSE mount on cloud-runtime VMs. Mirrors
+ * `AGENT_STORE_MOUNT_ROOT` / `AGENT_SERVE_DEPLOYMENT_STORE_MOUNT_NAME` in
+ * `@anysphere/constants` (not a dependency of this published package).
+ */
+export const DEPLOYMENT_STORE_MOUNT_PATH = "/cursor/stores/deployment";
+
 /** Errors raised by the file surface. Thrown by sinks and by the framework. */
 export class FileConflictError extends Error {
   constructor(

package/src/index.ts

@@ -76,6 +76,7 @@ export {
   MCP_CHANNEL_ID,
   MCP_ENDPOINT_PATH,
   mcpEndpointToolNames,
+  TOOL_MCP_ENDPOINT_PATH,
 } from "./internal/mcp-endpoint.js";
 export {
   ReminderValidationError,
@@ -91,7 +92,11 @@ export {
   UnknownToolError,
 } from "./internal/session-engine.js";
 export type { MemoryBackend, TurnMemoryRecord } from "./memory.js";
-export { fileMemoryBackend, memoryHook } from "./memory.js";
+export {
+  agentStoreMemoryBackend,
+  fileMemoryBackend,
+  memoryHook,
+} from "./memory.js";
 export type { PromptTag } from "./prompt.js";
 export { prompt } from "./prompt.js";
 export type {

package/src/internal/artifacts-store.ts

@@ -1,9 +1,11 @@
 /**
- * Durable artifact rows behind `ctx.artifacts` ({@link ArtifactsApi}).
+ * Durable artifact rows and payloads behind `ctx.artifacts`
+ * ({@link ArtifactsApi}).
  *
- * Mirror of host-kv: when `defineStorage` is authored with `get` + `list`,
- * rows live in that sink under `storageKeys.artifact`; otherwise one
- * JSON file per row under `--state-root/artifacts`.
+ * On Cursor-managed hosting rows and file payloads live on the deployment's
+ * Agent Store (the same store behind `ctx.host.files`, so they survive
+ * deploys and are visible on cloud VMs under the store mount); otherwise
+ * they land under `--state-root/artifacts` on local disk.
  */
 
 import { createHash, randomUUID } from "node:crypto";
@@ -17,6 +19,11 @@ import {
 } from "node:fs/promises";
 import { join } from "node:path";
 import { resolveArtifactsMax } from "../artifacts.js";
+import { agentStoreKeys, type FileSink } from "../files.js";
+import {
+  cursorHostedFiles,
+  isCursorHostedFilesAvailable,
+} from "../files-backends/cursor-hosted.js";
 import type {
   ArtifactListFilter,
   ArtifactRecord,
@@ -24,23 +31,30 @@ import type {
   ArtifactTagInput,
   JsonValue,
 } from "../types.js";
-import type { StorageCoordinator } from "./storage-coordinator.js";
 
-// TODO(agent-stores): the KV backing store is migrating to Agent Stores.
-// Swap only this adapter to the Agent Stores API when that lands; the
-// engine, tool, HTTP, and playground layers must not change.
 interface ArtifactRowStore {
   get(id: string): Promise<ArtifactRecord | undefined>;
   put(record: ArtifactRecord): Promise<void>;
   delete(id: string): Promise<void>;
   list(): Promise<ArtifactRecord[]>;
+  /** Row count without hydrating bodies — the per-insert cap check. */
+  count(): Promise<number>;
+}
+
+/** File/blob payload bytes, keyed by artifact id (metadata lives on the row). */
+interface ArtifactContentStore {
+  get(id: string): Promise<Uint8Array | undefined>;
+  put(id: string, body: Uint8Array): Promise<void>;
+  delete(id: string): Promise<void>;
 }
 
 export interface CreateArtifactsStoreOptions {
   stateRoot: string;
-  storage?: StorageCoordinator;
+  agentName: string;
   /** `agent/artifacts.ts` config, when authored. */
   config?: ArtifactsConfig;
+  /** Explicit sink override (tests). Omitted → hosted store or local disk. */
+  sink?: FileSink;
 }
 
 /** Kind used by freeform tags when no kinds are declared. */
@@ -54,16 +68,23 @@ export const ARTIFACT_DEFAULT_KIND = "artifact";
  */
 export class ArtifactsStore {
   private readonly rows: ArtifactRowStore;
+  private readonly content: ArtifactContentStore;
   private readonly config: ArtifactsConfig | undefined;
   private readonly max: number;
   /** Serializes tags so read-modify-write upserts and eviction don't race. */
   private tagChain: Promise<unknown> = Promise.resolve();
 
   constructor(options: CreateArtifactsStoreOptions) {
-    this.rows =
-      options.storage?.supportsArtifacts === true
-        ? createCoordinatorRowStore(options.storage)
-        : createFilesystemRowStore(options.stateRoot);
+    const sink =
+      options.sink ??
+      (isCursorHostedFilesAvailable() ? cursorHostedFiles() : undefined);
+    if (sink === undefined) {
+      this.rows = createFilesystemRowStore(options.stateRoot);
+      this.content = createFilesystemContentStore(options.stateRoot);
+    } else {
+      this.rows = createSinkRowStore(sink, options.agentName);
+      this.content = createSinkContentStore(sink, options.agentName);
+    }
     this.config = options.config;
     this.max = resolveArtifactsMax(options.config);
   }
@@ -82,7 +103,9 @@ export class ArtifactsStore {
       input.key === undefined
         ? `art_${randomUUID()}`
         : artifactIdForKey(input.key);
-    const existing = await this.rows.get(id);
+    // Fresh random ids can't collide; only keyed tags upsert.
+    const existing =
+      input.key === undefined ? undefined : await this.rows.get(id);
     const now = new Date().toISOString();
     const record: ArtifactRecord = {
       id,
@@ -96,6 +119,25 @@ export class ArtifactsStore {
       createdAt: existing?.createdAt ?? now,
       updatedAt: now,
     };
+    if (input.contents !== undefined) {
+      const body =
+        typeof input.contents === "string"
+          ? Buffer.from(input.contents, "utf8")
+          : input.contents;
+      await this.content.put(id, body);
+      record.content = {
+        size: body.byteLength,
+        contentType: input.contentType,
+      };
+    } else if (existing?.content !== undefined) {
+      if (existing.sessionId === record.sessionId) {
+        record.content = existing.content;
+      } else {
+        // Keys are deployment-global: rebinding a keyed row to another
+        // session must not carry the prior session's payload with it.
+        await this.content.delete(id);
+      }
+    }
     await this.rows.put(record);
     if (existing === undefined) {
       await this.evictPastCap();
@@ -103,6 +145,15 @@ export class ArtifactsStore {
     return record;
   }
 
+  get(id: string): Promise<ArtifactRecord | undefined> {
+    return this.rows.get(id);
+  }
+
+  /** Payload bytes for one artifact; undefined when it carries none. */
+  getContent(id: string): Promise<Uint8Array | undefined> {
+    return this.content.get(id);
+  }
+
   async list(filter?: ArtifactListFilter): Promise<ArtifactRecord[]> {
     const records = await this.rows.list();
     return records
@@ -152,6 +203,9 @@ export class ArtifactsStore {
   }
 
   private async evictPastCap(): Promise<void> {
+    if ((await this.rows.count()) <= this.max) {
+      return;
+    }
     const records = await this.rows.list();
     if (records.length <= this.max) {
       return;
@@ -159,6 +213,9 @@ export class ArtifactsStore {
     const oldestFirst = records.sort((a, b) => byNewestUpdated(b, a));
     for (const record of oldestFirst.slice(0, records.length - this.max)) {
       await this.rows.delete(record.id);
+      if (record.content !== undefined) {
+        await this.content.delete(record.id);
+      }
     }
   }
 }
@@ -206,23 +263,90 @@ function isArtifactRecord(
   return true;
 }
 
-function createCoordinatorRowStore(
-  storage: StorageCoordinator
+function parseRecordBytes(
+  bytes: Uint8Array | undefined
+): ArtifactRecord | undefined {
+  if (bytes === undefined) {
+    return undefined;
+  }
+  let value: JsonValue;
+  try {
+    value = JSON.parse(Buffer.from(bytes).toString("utf8")) as JsonValue;
+  } catch {
+    // A corrupt row must not poison list().
+    return undefined;
+  }
+  return isArtifactRecord(value) ? value : undefined;
+}
+
+function sinkBody(
+  found: Awaited<ReturnType<FileSink["get"]>>
+): Uint8Array | undefined {
+  if (found === undefined) {
+    return undefined;
+  }
+  return found instanceof Uint8Array ? found : found.body;
+}
+
+/** Rows as one JSON file each on the deployment's Agent Store. */
+function createSinkRowStore(
+  sink: FileSink,
+  agentName: string
 ): ArtifactRowStore {
+  const key = (id: string): string => agentStoreKeys.artifactRow(agentName, id);
   return {
     async get(id): Promise<ArtifactRecord | undefined> {
-      const value = await storage.artifactGet(id);
-      return isArtifactRecord(value) ? value : undefined;
+      return parseRecordBytes(sinkBody(await sink.get(key(id))));
     },
     async put(record): Promise<void> {
-      await storage.artifactPut(record.id, record as unknown as JsonValue);
+      await sink.put(
+        key(record.id),
+        Buffer.from(JSON.stringify(record), "utf8")
+      );
     },
     async delete(id): Promise<void> {
-      await storage.artifactDelete(id);
+      await sink.delete(key(id));
     },
     async list(): Promise<ArtifactRecord[]> {
-      const values = await storage.artifactList();
-      return values.filter(isArtifactRecord);
+      const entries = await sink.list(
+        agentStoreKeys.artifactRowPrefix(agentName)
+      );
+      const bodies = await Promise.all(
+        entries.map((entry) => sink.get(entry.key))
+      );
+      const records: ArtifactRecord[] = [];
+      for (const body of bodies) {
+        const record = parseRecordBytes(sinkBody(body));
+        if (record !== undefined) {
+          records.push(record);
+        }
+      }
+      return records;
+    },
+    async count(): Promise<number> {
+      const entries = await sink.list(
+        agentStoreKeys.artifactRowPrefix(agentName)
+      );
+      return entries.length;
+    },
+  };
+}
+
+function createSinkContentStore(
+  sink: FileSink,
+  agentName: string
+): ArtifactContentStore {
+  const key = (id: string): string =>
+    agentStoreKeys.artifactContent(agentName, id);
+  return {
+    async get(id): Promise<Uint8Array | undefined> {
+      return sinkBody(await sink.get(key(id)));
+    },
+    async put(id, body): Promise<void> {
+      await sink.put(key(id), body);
+    },
+    async delete(id): Promise<void> {
+      await sink.delete(key(id));
     },
   };
 }
@@ -286,5 +410,44 @@ function createFilesystemRowStore(stateRoot: string): ArtifactRowStore {
       }
       return records;
     },
+    async count(): Promise<number> {
+      try {
+        const names = await readdir(dir);
+        return names.filter(
+          (name) => !name.startsWith(".") && name.endsWith(".json")
+        ).length;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return 0;
+        }
+        throw error;
+      }
+    },
+  };
+}
+
+function createFilesystemContentStore(stateRoot: string): ArtifactContentStore {
+  const dir = join(stateRoot, "artifacts", "content");
+  const filePath = (id: string): string => join(dir, encodeURIComponent(id));
+  return {
+    async get(id): Promise<Uint8Array | undefined> {
+      try {
+        return new Uint8Array(await readFile(filePath(id)));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return undefined;
+        }
+        throw error;
+      }
+    },
+    async put(id, body): Promise<void> {
+      await mkdir(dir, { recursive: true });
+      const tmp = join(dir, `.tmp-${randomUUID()}`);
+      await writeFile(tmp, body);
+      await rename(tmp, filePath(id));
+    },
+    async delete(id): Promise<void> {
+      await rm(filePath(id), { force: true });
+    },
   };
 }