@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/storage-roles.ts

@@ -1,86 +0,0 @@
-/**
- * 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

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

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

@@ -1,205 +0,0 @@
-/**
- * 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

@@ -1,73 +0,0 @@
-/**
- * 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

@@ -1,294 +0,0 @@
-/**
- * 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;
-}