@cursor/july 0.1.33 → 0.1.35

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 });
+    },
   };
 }

package/src/internal/cli-convert-automation.ts

@@ -0,0 +1,352 @@
+/**
+ * `agent-serve convert-automation <url>` — export a Cursor Automation into
+ * an agentkit project.
+ *
+ * Fetches the automation's workflow from the backend export endpoint
+ * (Bearer user API key, same credential chain as deploy), runs the pure
+ * converter, writes the converted files (wx — existing files are kept),
+ * fills in the init scaffold around them, and installs npm dependencies
+ * (like `init`). MCP servers convert to Cursor-account connections resolved
+ * at runtime (no URLs or credentials in the project; authorization is
+ * managed in Cursor, dashboard → MCP). The generated project is NEVER
+ * imported/executed here — it embeds server-derived data, so checking it is
+ * left to an explicit `validate` next step the user runs after review.
+ * Exit 0 even with warnings; nonzero only for bad args, auth/fetch
+ * failures, or filesystem write failures.
+ */
+
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import {
+  type ConvertedMcpConnection,
+  type ConvertWorkflowResult,
+  convertWorkflow,
+  type WorkflowJson,
+} from "./convert-automation/index.js";
+import { slugify } from "./convert-automation/slug.js";
+import {
+  cursorExternalApiUrl,
+  resolveApiKey,
+  SIGN_IN_HINT,
+} from "./cursor/credentials.js";
+import {
+  AgentServeDeployClient,
+  type AutomationExport,
+  DeployApiError,
+} from "./deploy-client.js";
+import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
+import {
+  formatCdCommand,
+  type InitFileEntry,
+  initProject,
+  installScaffoldDependencies,
+  isEexist,
+} from "./init-project.js";
+import { stdoutPalette } from "./terminal-style.js";
+
+export interface ConvertAutomationCliOptions {
+  /** Positional: automation URL or bare uuid. */
+  url?: string;
+  /** Target directory; defaults to ./<automation-name-slug>. */
+  dir?: string;
+  json?: boolean;
+  apiKey?: string;
+  /** Test seams. */
+  fetchImpl?: typeof fetch;
+  out?: (text: string) => void;
+  err?: (text: string) => void;
+  installImpl?: typeof installScaffoldDependencies;
+  cwd?: string;
+}
+
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Extract the automation uuid from a dashboard URL
+ * (`/automations/<uuid>` or `/custom-agents/<uuid>`, any origin — dev
+ * hosts included) or a bare uuid. Undefined when nothing matches.
+ */
+export function parseAutomationRef(input: string): string | undefined {
+  const trimmed = input.trim();
+  if (UUID_PATTERN.test(trimmed)) {
+    return trimmed.toLowerCase();
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return undefined;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return undefined;
+  }
+  const segments = parsed.pathname.split("/").filter((s) => s !== "");
+  if (segments.length !== 2) {
+    return undefined;
+  }
+  const [kind, uuid] = segments;
+  if (kind !== "automations" && kind !== "custom-agents") {
+    return undefined;
+  }
+  if (uuid === undefined || !UUID_PATTERN.test(uuid)) {
+    return undefined;
+  }
+  return uuid.toLowerCase();
+}
+
+export async function cmdConvertAutomation(
+  options: ConvertAutomationCliOptions
+): Promise<number> {
+  const out =
+    options.out ?? ((text: string) => void process.stdout.write(text));
+  const err =
+    options.err ?? ((text: string) => void process.stderr.write(text));
+  const json = options.json === true;
+  // Failures stay machine-readable under --json (stderr keeps the prose).
+  const fail = (message: string): 1 => {
+    if (json) {
+      out(`${JSON.stringify({ ok: false, error: message })}\n`);
+    }
+    err(`${message}\n`);
+    return 1;
+  };
+
+  if (options.url === undefined || options.url.trim() === "") {
+    return fail(
+      `Usage: ${CLI} convert-automation <automation-url-or-uuid> [--dir <path>] [--json]`
+    );
+  }
+  const uuid = parseAutomationRef(options.url);
+  if (uuid === undefined) {
+    return fail(
+      `Could not parse ${JSON.stringify(options.url)} — expected an automation URL (https://cursor.com/automations/<uuid> or .../custom-agents/<uuid>) or a bare uuid.`
+    );
+  }
+
+  const resolved = await resolveApiKey({ apiKey: options.apiKey });
+  if (resolved === undefined) {
+    return fail(`Not signed in to Cursor. ${SIGN_IN_HINT}`);
+  }
+  const client = new AgentServeDeployClient({
+    backendUrl: cursorExternalApiUrl(),
+    apiKey: resolved.apiKey,
+    fetchImpl: options.fetchImpl,
+  });
+
+  let payload: AutomationExport;
+  try {
+    payload = await client.exportAutomation({ uuid });
+  } catch (error) {
+    if (error instanceof DeployApiError) {
+      return fail(error.message);
+    }
+    throw error;
+  }
+
+  const result = convertWorkflow({
+    automation: payload.automation,
+    workflow: payload.workflow as WorkflowJson,
+    mcpServers: payload.mcpServers,
+    exportedAt: new Date().toISOString(),
+  });
+
+  const displayDir =
+    options.dir ?? `./${slugify(payload.automation.name, "automation")}`;
+  const rootDir = resolve(options.cwd ?? process.cwd(), displayDir);
+
+  let files: InitFileEntry[];
+  try {
+    files = await writeProjectFiles(rootDir, result);
+  } catch (error) {
+    return fail(
+      `Could not write project files under ${rootDir}: ${describe(error)}`
+    );
+  }
+
+  // Same npm install as `init`, so the printed `validate` / `dev` next steps
+  // work immediately. Failure (npm exit or spawn error) is loud but never
+  // fails the conversion.
+  const install = options.installImpl ?? installScaffoldDependencies;
+  if (!json) {
+    out("\nInstalling npm packages\n");
+  }
+  let installed: Awaited<ReturnType<typeof installScaffoldDependencies>>;
+  try {
+    installed = await install(rootDir, {
+      stdio: json ? "pipe" : "inherit",
+    });
+  } catch (error) {
+    installed = { ok: false, exitCode: -1, stderr: describe(error) };
+  }
+  if (!installed.ok && !json) {
+    const reason = installed.stderr.trim() || `exit ${installed.exitCode}`;
+    err(
+      `npm install failed (${reason}); run \`npm install\` in ${displayDir} before \`${CLI} dev\`.\n`
+    );
+  }
+
+  if (json) {
+    out(
+      `${JSON.stringify(
+        {
+          ok: true,
+          directory: rootDir,
+          files: files.map(({ path, action }) => ({ path, action })),
+          warnings: result.warnings,
+          setupSteps: result.setupSteps,
+          installed: installed.ok,
+          installError: installed.ok
+            ? null
+            : installed.stderr.trim() ||
+              `npm install exited ${installed.exitCode}`,
+          mcpConnections: result.mcpConnections.map((connection) => ({
+            name: connection.name,
+            kind: connection.kind,
+          })),
+        },
+        null,
+        2
+      )}\n`
+    );
+    return 0;
+  }
+
+  out(
+    renderSummary({
+      automationName: payload.automation.name,
+      displayDir,
+      rootDir,
+      cwd: options.cwd ?? process.cwd(),
+      files,
+      result,
+    })
+  );
+  return 0;
+}
+
+/**
+ * Converter files first (wx — existing files are kept), then the init
+ * scaffold fills in around them with the same skip-existing semantics.
+ */
+async function writeProjectFiles(
+  rootDir: string,
+  result: ConvertWorkflowResult
+): Promise<InitFileEntry[]> {
+  const entries: InitFileEntry[] = [];
+  const converterPaths = new Set<string>();
+  await mkdir(rootDir, { recursive: true });
+  for (const file of result.files) {
+    converterPaths.add(file.path);
+    const abs = join(rootDir, file.path);
+    await mkdir(dirname(abs), { recursive: true });
+    try {
+      await writeFile(abs, file.contents, { flag: "wx" });
+      entries.push({ path: file.path, action: "create" });
+    } catch (error) {
+      if (!isEexist(error)) {
+        throw error;
+      }
+      entries.push({ path: file.path, action: "exist" });
+    }
+  }
+
+  const init = await initProject({ dir: rootDir });
+
+  // Scaffold files that make sense in a fresh `init` but not in an exported
+  // automation: the default memory hook (only when the automation had memory
+  // enabled — the converter emits its own copy then) and the echo demo tool.
+  const dropPaths = new Set<string>();
+  for (const scaffoldPath of ["agent/hooks/memory.ts", "agent/tools/echo.ts"]) {
+    if (
+      !converterPaths.has(scaffoldPath) &&
+      init.created.includes(scaffoldPath)
+    ) {
+      dropPaths.add(scaffoldPath);
+      await rm(join(rootDir, scaffoldPath));
+    }
+  }
+  for (const entry of init.files) {
+    if (converterPaths.has(entry.path) || dropPaths.has(entry.path)) {
+      continue;
+    }
+    entries.push(entry);
+  }
+  return entries;
+}
+
+function renderSummary(args: {
+  automationName: string;
+  displayDir: string;
+  rootDir: string;
+  cwd: string;
+  files: InitFileEntry[];
+  result: ConvertWorkflowResult;
+}): string {
+  const c = stdoutPalette();
+  const lines: string[] = [];
+  lines.push("");
+  lines.push(`Converted "${args.automationName}" → ${args.displayDir}`);
+  lines.push("");
+  let anyExisting = false;
+  for (const file of args.files) {
+    if (file.path.endsWith(".gitkeep")) {
+      continue;
+    }
+    anyExisting ||= file.action === "exist";
+    lines.push(c.dim(`${file.action.padStart(12)}  ${file.path}`));
+  }
+  if (anyExisting) {
+    lines.push(c.dim(`\n  "exist" files already existed and were kept as-is.`));
+  }
+
+  const warnings = args.result.warnings;
+  if (warnings.length > 0) {
+    lines.push("");
+    lines.push("Warnings:");
+    for (const warning of warnings) {
+      lines.push(`  - ${warning}`);
+    }
+  }
+
+  if (args.result.setupSteps.length > 0) {
+    lines.push("");
+    lines.push("Setup steps:");
+    for (const [index, step] of args.result.setupSteps.entries()) {
+      lines.push(`  ${index + 1}. ${step}`);
+    }
+  }
+
+  if (args.result.mcpConnections.length > 0) {
+    lines.push("");
+    lines.push("MCP connections:");
+    for (const connection of args.result.mcpConnections) {
+      lines.push(`  - ${connection.name}: ${connectionStatus(connection)}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("Next steps:");
+  const cd = formatCdCommand(args.cwd, args.rootDir);
+  const steps = [
+    ...(cd === undefined ? [] : [cd]),
+    `${CLI} validate`,
+    `${CLI} dev`,
+  ];
+  for (const [index, step] of steps.entries()) {
+    lines.push(`  ${index + 1}. ${step}`);
+  }
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}
+
+function connectionStatus(connection: ConvertedMcpConnection): string {
+  if (connection.kind === "cursorAccount") {
+    return "resolved from your Cursor account at runtime — manage authorization in Cursor (dashboard → MCP)";
+  }
+  return "needs manual setup — see the stub file and warnings above";
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/internal/cli-deploy.ts

@@ -1345,7 +1345,7 @@ function promptHidden(
 }
 
 /** Buffered line reader over a piped stream; undefined once it ends. */
-function createLineReader(
+export function createLineReader(
   stream: NodeJS.ReadableStream
 ): () => Promise<string | undefined> {
   let buffer = "";