@cursor/bdk 0.2.1

package/src/internal/storage-roles.ts

@@ -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 EvalStore} is playground eval bookkeeping with its own dedicated
+ *   table, 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 { StorageContext } from "../storage.js";
+import type { JsonValue, SessionEvent, SessionRecord } from "../types.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[]>;
+  /**
+   * The `limit` most recently written session records from the sink,
+   * newest first; `undefined` when the sink has no `listNewest`.
+   */
+  listNewestSessionsFromSink(limit: number): Promise<SessionRecord[] | undefined>;
+  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, on their own table. */
+export interface EvalStore {
+  evalRuns(): EvalRunStorage | undefined;
+}

package/src/internal/storage.ts

@@ -0,0 +1 @@
+export * from "../storage.js";

package/src/internal/store-api-protocol.ts

@@ -0,0 +1,205 @@
+/**
+ * Domain-call wire contract for the factory store API:
+ * `POST /internal/agentsdk/store/api/<call>` carrying a versioned JSON
+ * envelope `{ v, call, payload }`. This is the lane where the **server** owns
+ * the storage pattern (journal sharding, rotation, compaction), so a
+ * pathological pattern is fixable in a backend deploy instead of a July
+ * release plus a rebake of every deployment. The verb lane (`/flush`,
+ * `/read`, `/list`) keeps carrying bulk presigned file IO.
+ *
+ * Deliberately duplicated on the backend
+ * (`backend/server/src/factory/agent-sdk/agentsdkStoreApiProtocol.ts`): this
+ * package is published to npm, so the backend cannot depend on it and it
+ * cannot depend on backend packages. A backend drift test compares the two
+ * sources — same shape as the hosted-delivery protocol twins — which is why
+ * every exported constant here stays a single `export const NAME = <literal>;`
+ * line and every schema field stays on its own line.
+ *
+ * Evolution rules (the compat contract): additive optional fields only; no
+ * renames, no retypes, no semantic reuse of an old field; unknown fields are
+ * ignored, never rejected; removing a field means deprecating it in place
+ * forever. A breaking change means a new `v`, and the server keeps serving
+ * every previous `v`.
+ */
+
+import { z } from "zod";
+
+export const STORE_API_PROTOCOL_VERSION = 1;
+
+/** Path family on the factory surface; one segment per call. */
+export const STORE_API_PATH = "/internal/agentsdk/store/api";
+
+export const STORE_API_MEMORY_APPEND_CALL = "memory.append";
+
+/**
+ * Semantic cap on one serialized memory record. Text fields are truncated
+ * client-side (`memoryHook` default 2000 chars per field), so a well-formed
+ * record is a few KiB; 16 KiB is generous headroom, not a target. The cap is
+ * part of the wire contract but rides the layers, not the schema: the
+ * backend's store controller enforces it as a typed 4xx, and the store API
+ * client (`cursor/store-api-client.ts`) pre-checks it before spending a
+ * doomed request.
+ */
+export const MEMORY_APPEND_MAX_RECORD_BYTES: number = 16 * 1024;
+
+/** Serialized size of a record, as counted against the byte cap. */
+export function serializedRecordBytes(record: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(record)).byteLength;
+}
+
+/**
+ * One turn's memory record as it crosses the wire — July's
+ * `TurnMemoryRecord` (memory.ts). The extra-key record mirrors the schema's
+ * `.passthrough()`: a newer client's additive optional fields are journaled
+ * verbatim rather than stripped by an older server.
+ */
+export type TurnMemoryRecordWire = {
+  at: string;
+  sessionId: string;
+  channelId: string;
+  status: "completed" | "failed";
+  title?: string;
+  sdkAgentId?: string;
+  userMessage?: string;
+  result?: string;
+  usage?: Record<string, unknown>;
+} & Record<string, unknown>;
+
+/**
+ * Wire schema for {@link TurnMemoryRecordWire}. Per-field caps are
+ * deliberately absent: the client truncates text at authoring time and
+ * {@link MEMORY_APPEND_MAX_RECORD_BYTES} bounds the whole record.
+ */
+export const turnMemoryRecordWireSchema: z.ZodType<TurnMemoryRecordWire> = z
+  .object({
+    at: z.string().min(1),
+    sessionId: z.string().min(1),
+    channelId: z.string().min(1),
+    status: z.enum(["completed", "failed"]),
+    title: z.string().optional(),
+    sdkAgentId: z.string().optional(),
+    userMessage: z.string().optional(),
+    result: z.string().optional(),
+    usage: z.object({}).passthrough().optional(),
+  })
+  .passthrough();
+
+/** `memory.append` validated payload. */
+export type MemoryAppendPayload = {
+  agent: string;
+  record: TurnMemoryRecordWire;
+};
+
+/**
+ * `memory.append` payload shape. The agent name becomes a store key segment
+ * on the server, so it must be exactly one segment. Unknown payload fields
+ * are stripped (= ignored), per the evolution rules. The byte cap is
+ * semantics, not shape — the backend's store controller owns it.
+ */
+export const memoryAppendPayloadSchema: z.ZodType<MemoryAppendPayload> = z.object({
+  agent: z
+    .string()
+    .min(1)
+    .max(256)
+    .refine(name => !name.includes("/") && !name.includes("\\") && name !== "." && name !== "..", {
+      message: "agent must be a single store key segment",
+    }),
+  record: turnMemoryRecordWireSchema,
+});
+
+/** The versioned request body for the `memory.append` call. */
+export type MemoryAppendEnvelope = {
+  v: typeof STORE_API_PROTOCOL_VERSION;
+  call: typeof STORE_API_MEMORY_APPEND_CALL;
+  payload: MemoryAppendPayload;
+};
+
+/** The whole request body. Unknown envelope fields are stripped (= ignored). */
+export const memoryAppendEnvelopeSchema: z.ZodType<MemoryAppendEnvelope> = z.object({
+  v: z.literal(STORE_API_PROTOCOL_VERSION),
+  call: z.literal(STORE_API_MEMORY_APPEND_CALL),
+  payload: memoryAppendPayloadSchema,
+});
+
+/** `memory.append` success body. */
+export type MemoryAppendResponse = {
+  v: typeof STORE_API_PROTOCOL_VERSION;
+  ok: true;
+};
+
+/**
+ * Success body. Failures answer the store surface's standard error JSON
+ * (`{ code, error }`) with a matching HTTP status.
+ */
+export const memoryAppendResponseSchema: z.ZodType<MemoryAppendResponse> = z.object({
+  v: z.literal(STORE_API_PROTOCOL_VERSION),
+  ok: z.literal(true),
+});
+
+export const STORE_API_MEMORY_READ_CALL = "memory.read";
+
+/** `memory.read` validated payload. */
+export type MemoryReadPayload = {
+  agent: string;
+};
+
+/**
+ * `memory.read` payload shape — the same single-segment agent name rule as
+ * `memory.append`, since the name addresses the same journal key family.
+ */
+export const memoryReadPayloadSchema: z.ZodType<MemoryReadPayload> = z.object({
+  agent: z
+    .string()
+    .min(1)
+    .max(256)
+    .refine(name => !name.includes("/") && !name.includes("\\") && name !== "." && name !== "..", {
+      message: "agent must be a single store key segment",
+    }),
+});
+
+/** The versioned request body for the `memory.read` call. */
+export type MemoryReadEnvelope = {
+  v: typeof STORE_API_PROTOCOL_VERSION;
+  call: typeof STORE_API_MEMORY_READ_CALL;
+  payload: MemoryReadPayload;
+};
+
+/** The whole request body. Unknown envelope fields are stripped (= ignored). */
+export const memoryReadEnvelopeSchema: z.ZodType<MemoryReadEnvelope> = z.object({
+  v: z.literal(STORE_API_PROTOCOL_VERSION),
+  call: z.literal(STORE_API_MEMORY_READ_CALL),
+  payload: memoryReadPayloadSchema,
+});
+
+/**
+ * `memory.read` success body. The call is flush-on-read: the server drains
+ * the agent's pending append buffer before presigning. Best-effort: when
+ * the drain succeeds the journal includes every append that preceded the
+ * read; a busy flush lock, a buffer outage, or an oversized backlog
+ * degrades to the already-flushed state (callers must not regress their
+ * local view on a shorter download). `journal` is null while the agent has
+ * no journal at all.
+ */
+export type MemoryReadResponse = {
+  v: typeof STORE_API_PROTOCOL_VERSION;
+  ok: true;
+  journal: {
+    url: string;
+    expiresAt: string;
+  } | null;
+};
+
+/**
+ * Success body. Failures answer the store surface's standard error JSON
+ * (`{ code, error }`) with a matching HTTP status.
+ */
+export const memoryReadResponseSchema: z.ZodType<MemoryReadResponse> = z.object({
+  v: z.literal(STORE_API_PROTOCOL_VERSION),
+  ok: z.literal(true),
+  journal: z
+    .object({
+      url: z.string().min(1),
+      expiresAt: z.string().min(1),
+    })
+    .nullable(),
+});

package/src/internal/store-mirror.ts

@@ -0,0 +1,73 @@
+/**
+ * Mirror an authored file tree onto an Agent Store prefix. Shared by the
+ * skills, workspace seed, and session workspaceFile syncs so they keep the
+ * same write-then-sweep discipline and the same path refusals.
+ */
+
+import { posix } from "node:path";
+import { FileConflictError, type FileSink } from "../files.js";
+
+/**
+ * Write every `desired` key, then delete keys under `prefix` (and the
+ * `legacyPrefixes`) that nothing claims, so a redeploy drops removed files.
+ * Writes land before stale deletes, so a failed sync never leaves a gap a
+ * concurrent cloud reader could see.
+ */
+export async function mirrorToStore(args: {
+  sink: FileSink;
+  prefix: string;
+  desired: ReadonlyMap<string, Uint8Array>;
+  /** Pre-native layouts emptied on every sync so a rolled-forward deploy does not leave undiscoverable copies. */
+  legacyPrefixes?: readonly string[];
+}): Promise<void> {
+  await Promise.all(
+    [...args.desired].map(([key, body]) => putLastWriterWins(args.sink, key, body)),
+  );
+  const listed = await Promise.all(
+    [args.prefix, ...(args.legacyPrefixes ?? [])].map(prefix => args.sink.list(prefix)),
+  );
+  await Promise.all(
+    listed
+      .flat()
+      .filter(entry => !args.desired.has(entry.key))
+      .map(entry => args.sink.delete(entry.key)),
+  );
+}
+
+/**
+ * Same refusals as local materialization's `resolveInside`: a rel that
+ * escapes its directory or would not round-trip through the FUSE mount
+ * (`..`, `.`, `//`, absolute) fails the sync, exactly as it fails a local
+ * turn's workspace write. Backslashes are refused too — the store
+ * normalizes `\` to `/` on write, so the stored key would differ from the
+ * desired one and the stale pass would delete the file it just wrote.
+ */
+export function storeRelPath(relPath: string, what: "skill file" | "workspace file"): string {
+  if (
+    relPath.includes("\0") ||
+    relPath.includes("\\") ||
+    posix.isAbsolute(relPath) ||
+    relPath.endsWith("/") ||
+    relPath.split("/").some(seg => seg === ".." || seg === ".") ||
+    posix.normalize(relPath) !== relPath
+  ) {
+    throw new Error(`Refusing ${what} path "${relPath}" (must be a normalized relative path)`);
+  }
+  return relPath;
+}
+
+/**
+ * Last writer wins. A raced conditional put (dual engine pods during a
+ * deploy rollover) clears the sink's cached etag, so one retry re-learns
+ * the current version and lands.
+ */
+async function putLastWriterWins(sink: FileSink, key: string, body: Uint8Array): Promise<void> {
+  try {
+    await sink.put(key, body);
+  } catch (error) {
+    if (!(error instanceof FileConflictError)) {
+      throw error;
+    }
+    await sink.put(key, body);
+  }
+}

package/src/internal/stream-progress.ts

@@ -0,0 +1,294 @@
+/**
+ * Live terminal rendering of session events for `run` / `eval`.
+ * Writes to a caller-provided sink (usually stderr) so stdout can stay JSON.
+ */
+
+import type { SessionEvent } from "../types.js";
+
+export interface StreamProgress {
+  onEvent(event: SessionEvent): void;
+  close(): void;
+}
+
+export function createStreamProgress(options?: {
+  write?: (s: string) => void;
+  color?: boolean;
+}): StreamProgress {
+  const write = options?.write ?? ((s: string) => process.stderr.write(s));
+  const color =
+    options?.color ?? (process.stderr.isTTY === true && process.env.NO_COLOR === undefined);
+  const c = makePalette(color);
+
+  let assistantOpen = false;
+  let thinkingShown = false;
+  const turnStartedAt = new Map<string, number>();
+  const toolStartedAt = new Map<string, number>();
+  let turnClock = 0;
+
+  const closeAssistant = (): void => {
+    if (assistantOpen) {
+      write("\n");
+      assistantOpen = false;
+    }
+  };
+
+  const elapsed = (since: number): string => `${Date.now() - since}ms`;
+
+  return {
+    onEvent(event: SessionEvent): void {
+      switch (event.type) {
+        case "session.started": {
+          write(c.dim(`session ${event.sessionId}\n`));
+          break;
+        }
+        case "agent.bound": {
+          closeAssistant();
+          write(`  ${c.cyan("agent")} ${c.bold(event.data.sdkAgentId)}\n`);
+          if (event.data.url !== undefined) {
+            write(`  ${c.dim(event.data.url)}\n`);
+          }
+          break;
+        }
+        case "turn.queued": {
+          write(
+            c.dim(
+              `  turn ${event.turnId ?? "?"} queued (position ${event.data.position}, max ${event.data.maxRunningTurns} running)\n`,
+            ),
+          );
+          break;
+        }
+        case "turn.started": {
+          turnClock = Date.now();
+          if (event.turnId !== undefined) {
+            turnStartedAt.set(event.turnId, turnClock);
+          }
+          write(c.dim(`  turn ${event.turnId ?? "?"} started\n`));
+          break;
+        }
+        case "message.received": {
+          thinkingShown = false;
+          write(`${c.bold("› user")}  ${truncate(event.data.text, 120)}\n`);
+          break;
+        }
+        case "reasoning.appended": {
+          if (event.data.parentCallId !== undefined) {
+            break;
+          }
+          if (!thinkingShown) {
+            thinkingShown = true;
+            write(c.dim("  · thinking…\n"));
+          }
+          break;
+        }
+        case "message.appended": {
+          // Nested subagent deltas stay inside the task chip/indent, not
+          // the parent agent stream.
+          if (event.data.parentCallId !== undefined) {
+            break;
+          }
+          if (!assistantOpen) {
+            write(`${c.green("‹ agent")}  `);
+            assistantOpen = true;
+          }
+          write(event.data.delta);
+          break;
+        }
+        case "message.completed": {
+          if (event.data.parentCallId !== undefined) {
+            break;
+          }
+          closeAssistant();
+          break;
+        }
+        case "step.started": {
+          write(c.dim(`  · step ${event.data.stepId}\n`));
+          break;
+        }
+        case "step.completed": {
+          write(c.dim(`  · step ${event.data.stepId} (${event.data.durationMs}ms)\n`));
+          break;
+        }
+        case "actions.requested": {
+          closeAssistant();
+          const now = Date.now();
+          for (const call of event.data.calls) {
+            if (call.toolName === "task" && call.parentCallId === undefined) {
+              // Covered by subagent.called; avoid a duplicate bare `task` line.
+              continue;
+            }
+            toolStartedAt.set(call.callId, now);
+            const indent =
+              call.parentCallId !== undefined || event.data.parentCallId !== undefined
+                ? "    "
+                : "  ";
+            write(
+              `${indent}${c.magenta("⚙")} ${c.bold(call.toolName)}${c.dim(
+                formatArgs(call.args),
+              )}\n`,
+            );
+          }
+          break;
+        }
+        case "action.approval_requested": {
+          closeAssistant();
+          write(
+            `    ${c.yellow("⏸")} ${c.bold(event.data.toolName)} ${c.dim(
+              "awaiting human approval",
+            )}\n`,
+          );
+          break;
+        }
+        case "action.approval_resolved": {
+          const mark = event.data.decision === "approve" ? c.green("✓") : c.red("✗");
+          write(
+            `    ${mark} ${c.bold(event.data.toolName)} ${c.dim(
+              event.data.decision === "approve" ? "approved" : "denied",
+            )}\n`,
+          );
+          break;
+        }
+        case "action.auth_requested": {
+          closeAssistant();
+          write(
+            `    ${c.yellow("⏸")} ${c.bold(event.data.connection)} ${c.dim(
+              "awaiting MCP authorization",
+            )}\n`,
+          );
+          break;
+        }
+        case "action.auth_resolved": {
+          const mark = event.data.decision === "approve" ? c.green("✓") : c.red("✗");
+          write(
+            `    ${mark} ${c.bold(event.data.connection)} ${c.dim(
+              event.data.decision === "approve" ? "connected" : "denied",
+            )}\n`,
+          );
+          break;
+        }
+        case "action.result": {
+          if (event.data.toolName === "task" && event.data.parentCallId === undefined) {
+            break;
+          }
+          const started = toolStartedAt.get(event.data.callId);
+          toolStartedAt.delete(event.data.callId);
+          const dur = started === undefined ? "" : c.dim(` ${elapsed(started)}`);
+          const mark = event.data.isError ? c.red("✗") : c.magenta("✓");
+          const indent = event.data.parentCallId !== undefined ? "      " : "    ";
+          write(
+            `${indent}${mark} ${c.bold(event.data.toolName)}${dur} ${c.dim(
+              truncate(stringify(event.data.output), 90),
+            )}\n`,
+          );
+          break;
+        }
+        case "subagent.called": {
+          closeAssistant();
+          const detail = event.data.description ? ` — ${truncate(event.data.description, 60)}` : "";
+          write(
+            `  ${c.magenta("task")} ${c.bold(event.data.name ?? "subagent")}${c.dim(detail)}\n`,
+          );
+          break;
+        }
+        case "subagent.completed": {
+          write(`  ${c.magenta("✓")} ${c.bold(event.data.name ?? "subagent")} ${c.dim("done")}\n`);
+          break;
+        }
+        case "turn.completed": {
+          closeAssistant();
+          const usage = event.data.usage;
+          const tokens = usage ? ` · in ${usage.inputTokens} out ${usage.outputTokens} tok` : "";
+          const turnStart =
+            event.turnId !== undefined ? turnStartedAt.get(event.turnId) : turnClock || undefined;
+          const wall =
+            turnStart !== undefined && turnStart > 0
+              ? ` · ${elapsed(turnStart)} wall`
+              : turnClock > 0
+                ? ` · ${elapsed(turnClock)} wall`
+                : "";
+          write(c.dim(`  ─ turn done${tokens}${wall}\n`));
+          if (event.turnId !== undefined) {
+            turnStartedAt.delete(event.turnId);
+          }
+          break;
+        }
+        case "turn.failed": {
+          closeAssistant();
+          write(`${c.red("  ✗ turn failed")} ${event.data.message}\n`);
+          break;
+        }
+        case "session.failed": {
+          closeAssistant();
+          write(`${c.red("  ✗ session failed")} ${event.data.message}\n`);
+          break;
+        }
+        case "session.waiting":
+        case "session.completed": {
+          closeAssistant();
+          break;
+        }
+        default:
+          break;
+      }
+    },
+    close: closeAssistant,
+  };
+}
+
+type Palette = {
+  dim: (s: string) => string;
+  bold: (s: string) => string;
+  cyan: (s: string) => string;
+  green: (s: string) => string;
+  red: (s: string) => string;
+  magenta: (s: string) => string;
+  yellow: (s: string) => string;
+};
+
+const IDENTITY = (s: string): string => s;
+
+function makePalette(enabled: boolean): Palette {
+  if (!enabled) {
+    return {
+      dim: IDENTITY,
+      bold: IDENTITY,
+      cyan: IDENTITY,
+      green: IDENTITY,
+      red: IDENTITY,
+      magenta: IDENTITY,
+      yellow: IDENTITY,
+    };
+  }
+  const wrap =
+    (code: string) =>
+    (s: string): string =>
+      `\u001b[${code}m${s}\u001b[0m`;
+  return {
+    dim: wrap("2"),
+    bold: wrap("1"),
+    cyan: wrap("36"),
+    green: wrap("32"),
+    red: wrap("31"),
+    magenta: wrap("35"),
+    yellow: wrap("33"),
+  };
+}
+
+function stringify(value: unknown): string {
+  if (value === undefined || value === null) {
+    return "(no output)";
+  }
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+function formatArgs(args: unknown): string {
+  if (args === undefined || args === null) {
+    return "";
+  }
+  const text = typeof args === "string" ? args : JSON.stringify(args);
+  return text === "{}" ? "" : `(${truncate(text, 80)})`;
+}
+
+function truncate(text: string, max: number): string {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}