@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/workspace.ts

@@ -1,505 +0,0 @@
-/**
- * Session workspace materialization. Each session gets its own working
- * directory that the Cursor harness treats as the project: skills land in
- * `.cursor/skills/<name>/SKILL.md`, agent-side tools land in
- * `.agent-serve/tools/<name>.sh`, and `agent/sandbox/workspace/**` seed files
- * are mirrored in. The harness picks all of this up natively through its
- * project setting source. Instructions are not written here: local turns
- * deliver them as the harness system prompt ({@link buildAgentsMdContent}),
- * and cloud / grokbot harnesses never read the session workspace.
- */
-
-import { execFile } from "node:child_process";
-import {
-  chmod,
-  copyFile,
-  lstat,
-  mkdir,
-  readlink,
-  rm,
-  stat,
-  symlink,
-  writeFile,
-} from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join, parse, relative, resolve, sep } from "node:path";
-import { promisify } from "node:util";
-import { agentStoreKeys, DEPLOYMENT_STORE_MOUNT_PATH } from "../files.js";
-import { MEMORY_DIR_NAME } from "../memory.js";
-import type { DiscoveredSkill, DiscoveredTool, ResolvedAgent } from "../types.js";
-import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
-import { buildIdentitySection } from "./prompt-context.js";
-
-const execFileAsync = promisify(execFile);
-
-export interface MaterializeWorkspaceOptions {
-  agent: ResolvedAgent;
-  workspaceDir: string;
-  /**
-   * When true (first turn), seed files are copied in. Instructions and
-   * skills are always rewritten so authored edits show up on the next turn.
-   */
-  seed: boolean;
-  /**
-   * Agent state root. `<stateRoot>/memory/` (the durable cross-session
-   * directory the memory hook journals into — on hosting a local mirror of
-   * the Agent Store journal) is created and symlinked into the workspace as
-   * `memory` so the agent reads it with plain file tools. Cloud VMs have no
-   * materialized workspace; they read the store mount directly (see
-   * {@link buildCloudMemorySection}).
-   */
-  stateRoot: string;
-}
-
-/**
- * First-turn preamble section for cloud-runtime sessions on hosted
- * deployments: cloud VMs read the memory journal from the store mount.
- */
-export function buildCloudMemorySection(agentName: string): string {
-  const dir = `${DEPLOYMENT_STORE_MOUNT_PATH}/${agentStoreKeys.memoryDir(agentName)}`;
-  return [
-    "## Shared session memory",
-    "",
-    `The cross-session memory journal (the \`memory/\` directory your instructions may reference) lives at \`${dir}\` on this machine — read \`${dir}/journal.jsonl\` with your normal file tools.`,
-  ].join("\n");
-}
-
-/**
- * First-turn preamble section for cloud-runtime sessions with authored
- * `agent/sandbox/workspace/**` seeds. Cloud VMs get no materialized
- * workspace; the seeds are synced onto the store mount instead (see
- * `syncWorkspaceToStore`), so the model has to be told where they are.
- */
-export function buildCloudWorkspaceSection(dir: string): string {
-  return [
-    "## Workspace files",
-    "",
-    `The agent's authored workspace files live at \`${dir}\` on this machine. Relative paths in your instructions that name these files resolve under that directory rather than your working directory. Read them with your normal file tools. The directory is shared across sessions, so copy a file into your working directory before editing it.`,
-  ].join("\n");
-}
-
-/**
- * Per-turn preamble for cloud `workspaceFiles` after they land on the
- * session store prefix (see `syncSessionWorkspaceFiles`). Omitted when
- * the sync did not land.
- *
- * Same shared Agent Store mount as authored seeds — the session path is
- * replace-per-send / task-end wipe lifetime, not a separate mount ACL.
- */
-export function buildCloudSessionWorkspaceSection(
-  dir: string,
-  relPaths: readonly string[],
-): string {
-  const listed = relPaths.map(path => `\`${path}\``).join(", ");
-  return [
-    "## Session workspace files",
-    "",
-    `This turn's workspace files live at \`${dir}\` on this machine (${listed}). Read them with your normal file tools. They sit on the same shared Agent Store mount as authored workspace seeds; the session directory is replaced on the next send for this session, and task sessions remove it when they finish.`,
-  ].join("\n");
-}
-
-/** Relative path of an agent-side tool script inside the session workspace. */
-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)
- * so agents know who they are without restating it in authored prose.
- */
-export function buildIdentityPreamble(name: string): string {
-  const trimmed = name.trim();
-  if (trimmed === "") {
-    return "";
-  }
-  return `You are ${trimmed}. That is your name; use it when people ask who you are.`;
-}
-
-/**
- * Prepend {@link buildIdentityPreamble} to authored instructions. Used when
- * loading `instructions.md` / `.ts` / dir into {@link ResolvedAgent.instructions}.
- */
-export function withIdentityPreamble(
-  name: string,
-  instructions: string | undefined,
-): string | undefined {
-  const preamble = buildIdentityPreamble(name);
-  const body = instructions?.trim() ?? "";
-  if (preamble === "" && body === "") {
-    return undefined;
-  }
-  if (preamble === "") {
-    return body === "" ? undefined : body;
-  }
-  if (body === "") {
-    return preamble;
-  }
-  return `${preamble}\n\n${body}`;
-}
-
-/**
- * Markdown catalog of agent-side tools for AGENTS.md / cloud first prompt.
- *
- * @param includeScripts — when true, embed full script bodies (cloud first prompt).
- *   Local workspaces omit bodies because the files already exist on disk.
- */
-export function buildAgentToolsCatalog(
-  tools: DiscoveredTool[],
-  options: { includeScripts: boolean } = { includeScripts: false },
-): string {
-  const agentTools = tools.filter(tool => tool.execution === "agent");
-  if (agentTools.length === 0) {
-    return "";
-  }
-
-  const parts: string[] = [
-    "## Agent tools",
-    "",
-    "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.",
-    "",
-  ];
-
-  for (const tool of agentTools) {
-    const rel = agentToolScriptPath(tool.name);
-    parts.push(`### \`${tool.name}\``);
-    parts.push("");
-    parts.push(tool.description.trim());
-    parts.push("");
-    parts.push(`Path: \`${rel}\``);
-    parts.push("");
-    parts.push("Input schema:");
-    parts.push("");
-    parts.push("```json");
-    parts.push(JSON.stringify(tool.inputSchema, null, 2));
-    parts.push("```");
-    parts.push("");
-    parts.push("Invoke:");
-    parts.push("");
-    parts.push("```bash");
-    parts.push(`printf '%s' '{"key":"value"}' | bash ${rel}`);
-    parts.push("```");
-    parts.push("");
-    if (options.includeScripts && tool.script !== undefined) {
-      parts.push("Script body (write to the path above if missing):");
-      parts.push("");
-      parts.push("```bash");
-      parts.push(normalizeScriptBody(tool.script));
-      parts.push("```");
-      parts.push("");
-    }
-  }
-
-  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 instructions context for an agent: instructions, identity
- * section, and the agent-side tool catalog. Local turns send it as the
- * harness system prompt (`AgentOptions.systemPrompt`, replacing Cursor's
- * built-in prompt), grokbot turns carry it into the hosted session's system
- * prompt, and cloud turns inline it into the first prompt because a cloud VM
- * has no materialized workspace to read it from.
- *
- * `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; serverToolsMcpName?: string },
-): string {
-  return [
-    agent.instructions?.trim() ?? "",
-    buildIdentitySection(agent),
-    options.serverToolsMcpName === undefined
-      ? ""
-      : buildServerToolsCatalog(agent.tools, {
-          mcpServerName: options.serverToolsMcpName,
-        }),
-    buildAgentToolsCatalog(agent.tools, {
-      includeScripts: options.includeScripts,
-    }),
-  ]
-    .filter(part => part !== "")
-    .join("\n\n");
-}
-
-/**
- * True when `dir` sits strictly inside a git repository (a `.git` exists in
- * an ancestor directory but not in `dir` itself). The Cursor harness resolves
- * its project root by walking up to the nearest git root, so a nested session
- * workspace loses its own `AGENTS.md` / `.cursor` scaffold: the enclosing
- * repo's rules load instead, and the (necessarily gitignored) workspace files
- * are skipped by nested rule discovery.
- */
-export async function isNestedInGitRepo(dir: string): Promise<boolean> {
-  let current = resolve(dir);
-  if (await exists(join(current, ".git"))) {
-    // The workspace is itself a repo root; the harness roots rules here.
-    return false;
-  }
-  const { root } = parse(current);
-  while (current !== root) {
-    current = dirname(current);
-    if (await exists(join(current, ".git"))) {
-      return true;
-    }
-  }
-  return false;
-}
-
-/** Default harness parent for a nested-git agent project. */
-export function defaultLocalHarnessCwd(dirName: string): string {
-  return join(homedir(), ".cache", "agent-serve", dirName);
-}
-
-/**
- * Give a session workspace its own git root so the harness roots *there*
- * rather than at the enclosing repo (see {@link isNestedInGitRepo}). Without
- * it the harness reads the outer repo's `.cursor/hooks.json`, rules, skills
- * and `mcp.json`, and never sees the ones written into this workspace —
- * instructions have an inline fallback, hooks have none.
- *
- * Best effort: a workspace that already has `.git` (a borrowed checkout or
- * worktree) is left alone, and a failed `git init` leaves the harness where
- * it already was.
- */
-export async function ensureOwnGitRoot(dir: string): Promise<boolean> {
-  if (!(await isNestedInGitRepo(dir))) {
-    return false;
-  }
-  try {
-    await execFileAsync("git", ["init", "--quiet"], { cwd: dir });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export async function materializeWorkspace(options: MaterializeWorkspaceOptions): Promise<void> {
-  const { agent, workspaceDir, seed, stateRoot } = options;
-  await mkdir(workspaceDir, { recursive: true });
-  if (seed) {
-    await linkSharedMemoryDir(workspaceDir, stateRoot);
-  }
-
-  for (const tool of agent.tools) {
-    if (tool.execution !== "agent" || tool.script === undefined) {
-      continue;
-    }
-    await materializeAgentTool(workspaceDir, tool);
-  }
-
-  for (const skill of agent.skills) {
-    await materializeSkill(workspaceDir, skill);
-  }
-
-  if (seed) {
-    for (const seedFile of agent.seedFiles) {
-      const target = resolveWorkspaceWritePath(workspaceDir, seedFile.relativePath);
-      if (await exists(target)) {
-        continue;
-      }
-      await mkdir(dirname(target), { recursive: true });
-      await copyFile(seedFile.sourcePath, target);
-    }
-  }
-}
-
-/**
- * Resolve a workspace-rooted write target, refusing escapes and the
- * reserved `memory` name. `memory` is a symlink into the agent's durable
- * cross-session state, so a caller-supplied `workspaceFiles` entry (or a
- * seed file) under it would write through the link and poison the journal
- * every other session trusts. The check runs on the *resolved* path so
- * `./memory/x` and `foo/../memory/x` cannot slip past.
- */
-function resolveWorkspaceWritePath(workspaceDir: string, relativePath: string): string {
-  const target = resolveInside(workspaceDir, relativePath);
-  const first = relative(workspaceDir, target).split(sep, 1)[0];
-  if (first === MEMORY_DIR_NAME) {
-    throw new Error(
-      `"${MEMORY_DIR_NAME}" is reserved for shared session memory; refusing to write ${relativePath}`,
-    );
-  }
-  return target;
-}
-
-/**
- * Symlink `<stateRoot>/memory` into the workspace as `memory`. Stale links
- * (a moved state root) are re-pointed; seeded files and symlink-refusing
- * platforms (unprivileged Windows) are left alone — memory then stays
- * reachable only via the state path.
- */
-async function linkSharedMemoryDir(workspaceDir: string, stateRoot: string): Promise<void> {
-  const target = join(stateRoot, MEMORY_DIR_NAME);
-  const linkPath = join(workspaceDir, MEMORY_DIR_NAME);
-  await mkdir(target, { recursive: true });
-  try {
-    await symlink(target, linkPath, "dir");
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-      return;
-    }
-    const existing = await lstat(linkPath);
-    if (!existing.isSymbolicLink() || (await readlink(linkPath)) === target) {
-      return;
-    }
-    await rm(linkPath);
-    await symlink(target, linkPath, "dir");
-  }
-}
-
-async function materializeAgentTool(workspaceDir: string, tool: DiscoveredTool): Promise<void> {
-  if (tool.script === undefined) {
-    return;
-  }
-  const relativePath = agentToolScriptPath(tool.name);
-  const target = resolveInside(workspaceDir, relativePath);
-  await mkdir(dirname(target), { recursive: true });
-  await writeFile(target, `${normalizeScriptBody(tool.script)}\n`, "utf8");
-  try {
-    await chmod(target, 0o755);
-  } catch {
-    // Best-effort on platforms that ignore mode bits.
-  }
-}
-
-async function materializeSkill(workspaceDir: string, skill: DiscoveredSkill): Promise<void> {
-  const skillDir = join(workspaceDir, ".cursor", "skills", skill.name);
-  await mkdir(skillDir, { recursive: true });
-  await writeFile(join(skillDir, "SKILL.md"), buildSkillMd(skill), "utf8");
-
-  for (const [relativePath, source] of Object.entries(skill.files)) {
-    const target = resolveInside(skillDir, relativePath);
-    await mkdir(dirname(target), { recursive: true });
-    if ("contents" in source) {
-      await writeFile(target, source.contents, "utf8");
-    } else {
-      await copyFile(source.sourcePath, target);
-    }
-  }
-}
-
-/**
- * Ensure the script has a shebang. Catalog fences stay tidy without a
- * trailing blank line inside the fence.
- */
-function normalizeScriptBody(script: string): string {
-  const trimmed = script.replace(/\r\n/g, "\n").trimEnd();
-  if (trimmed.startsWith("#!")) {
-    return trimmed;
-  }
-  return `#!/usr/bin/env bash\n${trimmed}`;
-}
-
-/**
- * Generate the SKILL.md the harness reads: `name` + `description`
- * frontmatter (any authored frontmatter was already stripped at discovery)
- * followed by the skill body.
- */
-export function buildSkillMd(skill: DiscoveredSkill): string {
-  const { body } = parseFrontmatter(skill.markdown);
-  const frontmatter = serializeFrontmatter({
-    name: skill.name,
-    description: skill.description,
-  });
-  return `${frontmatter}\n${body.trim()}\n`;
-}
-
-/**
- * Write relative path → contents under `workspaceDir`, refusing paths that
- * escape the directory. Values may be utf8 strings or base64 blob envelopes.
- */
-export async function writeWorkspaceFiles(
-  workspaceDir: string,
-  files: Record<string, string | { encoding: "base64"; data: string; mimeType?: string }>,
-): Promise<void> {
-  for (const [relativePath, contents] of Object.entries(files)) {
-    const target = resolveWorkspaceWritePath(workspaceDir, relativePath);
-    await mkdir(dirname(target), { recursive: true });
-    if (typeof contents === "string") {
-      await writeFile(target, contents, "utf8");
-    } else if (contents.encoding === "base64") {
-      await writeFile(target, Buffer.from(contents.data, "base64"));
-    } else {
-      throw new Error(`Unsupported workspace file encoding for ${relativePath}`);
-    }
-  }
-}
-
-function resolveInside(baseDir: string, relativePath: string): string {
-  const target = resolve(baseDir, relativePath);
-  const rel = relative(baseDir, target);
-  if (rel.startsWith("..") || rel === "" || relativePath.includes("\0")) {
-    throw new Error(`Refusing to write outside the workspace: ${relativePath}`);
-  }
-  return target;
-}
-
-async function exists(path: string): Promise<boolean> {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/kv/memory-kv.ts

@@ -1,94 +0,0 @@
-/**
- * In-memory {@link HostKvCasApi} — the test/dev implementation of
- * `@cursor/bdk/kv`.
- *
- * Internal only: SDK tests and Cursor factory code. Not a public Agent
- * SDK export.
- *
- * The memory KV *is* the test shim: tests and local runs exercise the
- * CAS contract, not a mock of an RPC. Values are deep-copied on both write and
- * read so callers can never observe (or cause) shared-reference mutation.
- */
-
-import type { StorageCasTable } from "../storage.js";
-import type { HostKvCasApi, JsonValue, KvCasResult, KvVersionedEntry } from "../types.js";
-
-/** Create an empty in-memory CAS-capable KV. */
-export function createMemoryKv(): HostKvCasApi {
-  const entries = new Map<string, { value: JsonValue; version: string }>();
-  let versionCounter = 0;
-
-  const nextVersion = (): string => {
-    versionCounter += 1;
-    return `v${versionCounter}`;
-  };
-
-  const snapshot = (key: string): KvVersionedEntry | undefined => {
-    const entry = entries.get(key);
-    if (entry === undefined) {
-      return undefined;
-    }
-    return { value: structuredClone(entry.value), version: entry.version };
-  };
-
-  return {
-    async get(key): Promise<JsonValue | undefined> {
-      return snapshot(key)?.value;
-    },
-
-    async put(key, value): Promise<void> {
-      entries.set(key, {
-        value: structuredClone(value),
-        version: nextVersion(),
-      });
-    },
-
-    async delete(key): Promise<void> {
-      entries.delete(key);
-    },
-
-    async getWithVersion(key): Promise<KvVersionedEntry | undefined> {
-      return snapshot(key);
-    },
-
-    async putIfAbsent(key, value): Promise<KvCasResult> {
-      if (entries.has(key)) {
-        return { ok: false, current: snapshot(key) };
-      }
-      const version = nextVersion();
-      entries.set(key, { value: structuredClone(value), version });
-      return { ok: true, version };
-    },
-
-    async putIfVersion(key, value, expectedVersion): Promise<KvCasResult> {
-      const entry = entries.get(key);
-      if (entry === undefined || entry.version !== expectedVersion) {
-        return { ok: false, current: snapshot(key) };
-      }
-      const version = nextVersion();
-      entries.set(key, { value: structuredClone(value), version });
-      return { ok: true, version };
-    },
-
-    async listKeys(prefix): Promise<string[]> {
-      return [...entries.keys()].filter(key => key.startsWith(prefix)).sort();
-    },
-  };
-}
-
-/**
- * In-memory `cas` group for `defineStorage` — a complete conditional-write
- * group for sinks whose plain methods are inert or live elsewhere (test
- * fixtures, an off-hosting no-op sink). Non-durable and process-local by
- * construction; a real deployment backend should implement CAS against
- * its own store instead.
- */
-export function memoryCasTable(): StorageCasTable {
-  const kv = createMemoryKv();
-  return {
-    getWithVersion: key => kv.getWithVersion(key),
-    putIfAbsent: (key, value) => kv.putIfAbsent(key, value),
-    putIfVersion: (key, value, expectedVersion) => kv.putIfVersion(key, value, expectedVersion),
-    listKeys: prefix => kv.listKeys(prefix),
-  };
-}

package/src/kv.ts

@@ -1,18 +0,0 @@
-/**
- * The CAS-capable KV **interface** — `@cursor/bdk/kv`.
- *
- * This module is implementation-free on purpose: it is the contract a
- * bring-your-own KV implements so conditional writes can run on it.
- * {@link HostKvCasApi} is the conditional-write superset of the plain
- * {@link HostKvApi}; {@link supportsKvCas} is the runtime probe for
- * stores of unknown provenance — a `defineStorage` backend declares CAS
- * through its `cas` group instead, so it never needs probing.
- *
- * Implementations live on the storage backends: they implement the same
- * operations as the `cas` group on the internal-only `defineStorage`
- * (its `StorageCasTable` member): `fileKv` (single-process) and
- * `cursorHostedStorage` (control-plane proxy). See `docs/storage.md`.
- */
-
-export type { HostKvApi, HostKvCasApi, KvCasResult, KvVersionedEntry } from "./types.js";
-export { supportsKvCas } from "./types.js";