@cursor/bdk 0.2.3 → 0.2.4

package/src/storage.ts

@@ -1,408 +0,0 @@
-/**
- * Durable storage plug-in for agent-serve.
- *
- * Author `agent/storage.ts` with {@link defineStorage} to mirror the
- * framework's durable state into storage you own (a database, S3, a data
- * pipeline, …). Without it, state lives under `--state-root` on local disk
- * only, and eval history stays in process memory.
- *
- * The sink is a plain key-value store — put/get/delete/list, no schema —
- * plus a conditional-write group ({@link StorageConfig.cas}; optional).
- * Implementing that small KV core is enough for
- * FULL functionality: eval-run history is derived over the core when the
- * optional dedicated table ({@link StorageConfig.evals}) is not authored —
- * that group exists as a backend-native optimization (a real table, an
- * analytics pipeline), not as a required-or-lose-history hook:
- *
- * ```ts
- * import { defineStorage } from "@cursor/bdk/internal/storage";
- *
- * export default defineStorage({
- *   put: (key, value) => db.upsert(key, value),
- *   get: (key) => db.get(key),
- *   delete: (key) => db.delete(key),
- *   list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
- *   cas: { getWithVersion: ..., putIfAbsent: ..., putIfVersion: ..., listKeys: ... },
- *   evals: { put: ..., delete: ..., list: ... }, // eval-runs table
- * });
- * ```
- *
- * The **framework mints every key** from a stable, versioned scheme (see
- * {@link storageKeys}) and decides **when** to call the sink: session
- * records and event chunks flush when a turn's handlers have settled,
- * reads happen at serve start (bulk restore), on continuation-token misses
- * (lazy restore), and at playground hydration. Authors do not schedule
- * reads or writes — the only timing knobs are {@link StoragePolicy}'s
- * `debounceMs` (event write batching) and `restore` (startup hydration).
- *
- * Because keys are opaque strings to the sink, new kinds of durable state
- * (channel cursors, thread affinity, …) are new key prefixes — existing
- * sinks store them with no code changes. Authors can also store their own
- * JSON under `agentkit/v1/{agent}/kv/…` via {@link HostContext.kv}; the
- * framework still mints the full key from the author-supplied segment.
- *
- * Delivery semantics: writes are **serialized** (one sink call in flight
- * per agent, in order), **bounded** (a sink that falls behind sheds writes
- * rather than growing memory), and **at-most-once** — a throwing `put` is
- * logged and dropped, never retried, and never fails a turn. The local
- * event log under `--state-root` remains the live source of truth; this
- * interface is the durable mirror.
- */
-
-import type { EvalRunSnapshot } from "./evals.js";
-import { brandDefinition } from "./internal/brand.js";
-import { storageKeys } from "./storage-protocol.js";
-import type { JsonValue, KvCasResult, KvVersionedEntry } from "./types.js";
-
-export type {
-  DurableSessionRecord,
-  DurableSessionSummary,
-  StorageKeys,
-} from "./storage-protocol.js";
-export {
-  AGENTSDK_STORAGE_KEY_ROOT,
-  agentSdkStorageKeys,
-  frameworkStartLogId,
-  GOLDEN_DURABLE_SESSION_RECORD,
-  isDurableSessionRecordKey,
-  keySegment,
-  MAX_KEY_SEGMENT_BYTES,
-  parseDurableSessionRecord,
-  STORAGE_KEY_ROOT,
-  storageKeys,
-  storageKeysForArchitecture,
-  summarizeDurableSessionRecord,
-} from "./storage-protocol.js";
-
-// ============================================================================
-// Sink interface
-// ============================================================================
-
-/** One `{ key, value }` pair returned by {@link StorageConfig.list}. */
-export interface StorageEntry {
-  key: string;
-  value: JsonValue;
-}
-
-/** Context passed to every sink call. */
-export interface StorageContext {
-  /** Agent name (also baked into every key; see {@link storageKeys}). */
-  agentName: string;
-  /** Absolute agent project root (directory that contains `agent/`). */
-  projectRoot: string;
-  /**
-   * Why the framework is calling:
-   * - `"policy"` — a flush trigger fired (turn end, debounce, change)
-   * - `"shutdown"` — the serve process is draining; last chance to write
-   * - `"restore"` — serve start or a lazy restore; reads rebuilding state
-   * - `"coordination"` — framework coordination driving
-   *   {@link StorageCasTable} (conditional writes)
-   */
-  reason: "policy" | "shutdown" | "restore" | "coordination";
-}
-
-export interface StoragePolicy {
-  /**
-   * Batch event-chunk writes on a quiet-period timer instead of flushing
-   * once per turn. The debounce **spans turn boundaries** — a rapid
-   * multi-turn exchange becomes one write when the session goes quiet —
-   * so it is the right choice for chatty sessions where per-turn writes
-   * are too many. Unset (default): one event chunk per turn.
-   */
-  debounceMs?: number;
-  /**
-   * Guardrails for the **startup bulk restore**. Whatever `list` returns
-   * is filtered to these caps before anything is written to local disk, so
-   * a large store cannot blow up `--state-root` or stall serve start.
-   * Newest sessions (by `updatedAt`) win within each cap.
-   *
-   * `"off"` disables the startup restore entirely — sessions then restore
-   * one at a time as follow-ups actually arrive (lazy-only; recommended
-   * for high-traffic deployments).
-   */
-  restore?: StorageRestorePolicy | "off";
-}
-
-/** Caps applied to the startup bulk restore. See {@link StoragePolicy.restore}. */
-export interface StorageRestorePolicy {
-  /** Max sessions materialized (default {@link STORAGE_DEFAULT_RESTORE_MAX_SESSIONS}). */
-  maxSessions?: number;
-  /**
-   * Skip sessions whose `updatedAt` is older than this (default
-   * {@link STORAGE_DEFAULT_RESTORE_MAX_AGE_MS}). Older sessions remain
-   * reachable lazily on their next follow-up.
-   */
-  maxAgeMs?: number;
-  /**
-   * Stop restoring once this many bytes of records + events have been
-   * written (default {@link STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES}).
-   * Checked before each session is written, so one oversized stream
-   * cannot blow past the budget.
-   */
-  maxTotalBytes?: number;
-}
-
-/**
- * Dedicated table for playground eval batches, keyed by `runId`. The
- * framework saves a full {@link EvalRunSnapshot} as a batch starts,
- * progresses, and finishes; prunes runs past the playground history
- * window; and lists everything back at serve start.
- */
-export interface StorageEvalsTable {
-  /** Upsert one run snapshot under `run.runId` (last write wins). */
-  put(run: EvalRunSnapshot, ctx: StorageContext): void | Promise<void>;
-  /** Remove a run pruned out of the playground history window. */
-  delete(runId: string, ctx: StorageContext): void | Promise<void>;
-  /** All saved runs (any order). Called once when the serve process hydrates. */
-  list(ctx: StorageContext): EvalRunSnapshot[] | Promise<EvalRunSnapshot[]>;
-}
-
-/**
- * Conditional writes (CAS) — the coordination tier of the storage backend
- * contract. Plain storage works without it, so existing backends keep
- * working across a platform upgrade. The built-in backends all include
- * it, so implementing this group yourself only comes up for BYO storage.
- *
- * Grouped under {@link StorageConfig.cas} rather than as loose methods —
- * matching the `evals` table group — so `defineStorage` validates the
- * whole group at once: there is no meaningful half-implementation.
- *
- * Version tokens are opaque per-key strings that change on every
- * successful write (counter, UUID, content hash — whatever is cheap for
- * the backend). See {@link KvVersionedEntry} / {@link KvCasResult}.
- */
-export interface StorageCasTable {
-  /** Read one value with its version token. Miss → `undefined`. */
-  getWithVersion(
-    key: string,
-    ctx: StorageContext,
-  ): Promise<KvVersionedEntry | undefined> | KvVersionedEntry | undefined;
-  /** Create the key only when absent. Conflict returns the existing entry. */
-  putIfAbsent(
-    key: string,
-    value: JsonValue,
-    ctx: StorageContext,
-  ): Promise<KvCasResult> | KvCasResult;
-  /**
-   * Replace the value only when the key still carries `expectedVersion`.
-   * Conflict (version moved, or key deleted) returns the current entry.
-   */
-  putIfVersion(
-    key: string,
-    value: JsonValue,
-    expectedVersion: string,
-    ctx: StorageContext,
-  ): Promise<KvCasResult> | KvCasResult;
-  /** All keys under a prefix, in ascending key order. */
-  listKeys(prefix: string, ctx: StorageContext): Promise<string[]> | string[];
-}
-
-export interface StorageConfig {
-  /** Optional label surfaced on `GET /v1/info` diagnostics. */
-  name?: string;
-  /** Timing knobs; see {@link StoragePolicy}. */
-  policy?: StoragePolicy;
-  /**
-   * Dedicated eval-runs table — a backend-native optimization, not a
-   * requirement. When omitted, `defineStorage` derives the table over the
-   * KV core (one key per run under `agentkit/v1/{agent}/eval-runs/`),
-   * which needs core `put`, `delete`, and `list`; only when the core
-   * lacks `delete` or `list` does playground eval history stay in process
-   * memory (lost on restart).
-   */
-  evals?: StorageEvalsTable;
-  /**
-   * Conditional writes (CAS). Optional for plain storage — existing
-   * backends keep working without it. The built-in backends (`fileKv`,
-   * `cursorHostedStorage`) both include it. See {@link StorageCasTable}.
-   */
-  cas?: StorageCasTable;
-  /**
-   * Store one value under a key (upsert, last-write-wins). Called on the
-   * framework's schedule — never concurrently, always in order. Keep it
-   * fast or buffer internally: the delivery queue is bounded, so a sink
-   * that falls behind sustained traffic sheds writes (logged) instead of
-   * growing memory; it never stalls the agent loop.
-   */
-  put(key: string, value: JsonValue, ctx: StorageContext): void | Promise<void>;
-  /**
-   * Store several values in one call. Optional — the coordinator uses it
-   * only when present, so authored sinks keep `put`'s strict one-at-a-time
-   * ordering. Entries belong to one flush and are independent keys; the
-   * implementation may write them in a single backend round trip. Report
-   * per-entry outcomes, index-aligned with the input: one key's failure
-   * must not take down its batch siblings. A thrown rejection is treated
-   * as every entry failing (logged and dropped, at-most-once) — reserve it
-   * for faults that genuinely precede any write.
-   */
-  putMany?(
-    entries: Array<{ key: string; value: JsonValue }>,
-    ctx: StorageContext,
-  ): Promise<Array<{ key: string; error?: unknown }>>;
-  /** Remove a key. Optional — without it, deletions are skipped. */
-  delete?(key: string, ctx: StorageContext): void | Promise<void>;
-  /**
-   * Point lookup. Optional — required for **lazy restore** (resolving a
-   * continuation token on a replacement host).
-   * Return `undefined`/`null` only for a **definitive** miss: on the lazy
-   * restore path a throw propagates and fails the follow-up (retryable) —
-   * a store outage must not read as "unknown token", which would fork the
-   * conversation onto a new session.
-   */
-  get?(
-    key: string,
-    ctx: StorageContext,
-  ): JsonValue | undefined | null | Promise<JsonValue | undefined | null>;
-  /**
-   * All entries under a key prefix, in ascending key order. Optional —
-   * required for the **startup bulk restore** (sessions + event streams)
-   * and, together with `delete`, for the derived eval-runs table
-   * (playground eval history).
-   */
-  list?(prefix: string, ctx: StorageContext): StorageEntry[] | Promise<StorageEntry[]>;
-  /**
-   * The `limit` most recently **written** entries under a prefix, newest
-   * first. Optional — a backend-native shortcut for `GET /v1/sessions?latest=1`
-   * on a replacement host, where the alternative is listing every session
-   * row. Without it the engine falls back to `list`. Write order is an
-   * approximation of the records' own `updatedAt`; callers tolerate that.
-   */
-  listNewest?(
-    prefix: string,
-    limit: number,
-    ctx: StorageContext,
-  ): StorageEntry[] | Promise<StorageEntry[]>;
-}
-
-export type StorageDefinition = StorageConfig & {
-  readonly __agentServe: "storage";
-};
-
-/**
- * Author the project storage sink (`agent/storage.ts`, default
- * export). Import from `@cursor/bdk/internal/storage`, not
- * `@cursor/bdk`. See the module doc for semantics and an example.
- */
-export function defineStorage(config: StorageConfig): StorageDefinition {
-  if (typeof config.put !== "function") {
-    throw new Error("defineStorage: config.put must be a function");
-  }
-  for (const hook of ["get", "list", "delete", "putMany"] as const) {
-    const value = config[hook];
-    if (value !== undefined && typeof value !== "function") {
-      throw new Error(`defineStorage: config.${hook} must be a function when set`);
-    }
-  }
-  if (config.evals !== undefined) {
-    for (const hook of ["put", "delete", "list"] as const) {
-      if (typeof config.evals[hook] !== "function") {
-        throw new Error(
-          `defineStorage: evals.${hook} must be a function when the evals table is set`,
-        );
-      }
-    }
-  }
-  if (config.cas !== undefined) {
-    const casHooks = ["getWithVersion", "putIfAbsent", "putIfVersion", "listKeys"] as const;
-    const cas = config.cas;
-    // A partial group is a bug, not a legacy config: half-implemented CAS
-    // would pass the capability probe.
-    const missingCasHooks = casHooks.filter(hook => typeof cas[hook] !== "function");
-    if (missingCasHooks.length > 0) {
-      throw new Error(
-        `defineStorage: ${missingCasHooks
-          .map(hook => `cas.${hook}`)
-          .join(
-            ", ",
-          )} must be ${missingCasHooks.length === 1 ? "a function" : "functions"} when the cas group is set`,
-      );
-    }
-  }
-  // Validate eagerly so a bad policy fails at discovery, not first flush.
-  resolveStoragePolicy(config.policy);
-  // A backend that implements only the KV core gets full functionality:
-  // the dedicated table is a backend-native optimization, derived over
-  // the core when absent. An authored group always wins.
-  const derivedEvals = config.evals === undefined ? deriveEvalsTable(config) : undefined;
-  return brandDefinition("storage", {
-    ...config,
-    ...(derivedEvals === undefined ? {} : { evals: derivedEvals }),
-  });
-}
-
-/**
- * Eval-runs table over the KV core: one key per run under
- * {@link storageKeys.evalRun}, hydrate via prefix `list`, prune via
- * `delete`. Requires core `put` + `delete` + `list`; without `delete` or
- * `list` there is no derivation (pruning or hydration would silently not
- * work) and eval history stays in process memory.
- */
-function deriveEvalsTable(config: StorageConfig): StorageEvalsTable | undefined {
-  if (config.delete === undefined || config.list === undefined) {
-    return undefined;
-  }
-  return {
-    put: (run, ctx) =>
-      config.put(storageKeys.evalRun(ctx.agentName, run.runId), run as unknown as JsonValue, ctx),
-    delete: (runId, ctx) => config.delete?.(storageKeys.evalRun(ctx.agentName, runId), ctx),
-    list: async ctx => {
-      const entries = (await config.list?.(storageKeys.evalRunsPrefix(ctx.agentName), ctx)) ?? [];
-      return entries.map(entry => entry.value as unknown as EvalRunSnapshot);
-    },
-  };
-}
-
-// ============================================================================
-// Policy resolution
-// ============================================================================
-
-export const STORAGE_DEFAULT_RESTORE_MAX_SESSIONS = 1_000;
-export const STORAGE_DEFAULT_RESTORE_MAX_AGE_MS: number = 30 * 24 * 60 * 60_000;
-export const STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES = 1_073_741_824; // 1 GiB
-
-/** {@link StoragePolicy} with defaults applied. */
-export interface ResolvedStoragePolicy {
-  /** Event-chunk flush trigger: per turn, or debounced across turns. */
-  events: "turnEnd" | { debounceMs: number };
-  restore: "off" | { maxSessions: number; maxAgeMs: number; maxTotalBytes: number };
-}
-
-/** Apply {@link StoragePolicy} defaults (exposed for tooling/tests). */
-export function resolveStoragePolicy(policy: StoragePolicy | undefined): ResolvedStoragePolicy {
-  return {
-    events:
-      policy?.debounceMs === undefined
-        ? "turnEnd"
-        : { debounceMs: clampInt(policy.debounceMs, 2_000, 0, 60_000) },
-    restore:
-      policy?.restore === "off"
-        ? "off"
-        : {
-            maxSessions: clampInt(
-              policy?.restore?.maxSessions,
-              STORAGE_DEFAULT_RESTORE_MAX_SESSIONS,
-              0,
-              1_000_000,
-            ),
-            maxAgeMs: clampInt(
-              policy?.restore?.maxAgeMs,
-              STORAGE_DEFAULT_RESTORE_MAX_AGE_MS,
-              0,
-              10 * 365 * 24 * 60 * 60_000,
-            ),
-            maxTotalBytes: clampInt(
-              policy?.restore?.maxTotalBytes,
-              STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES,
-              0,
-              1_099_511_627_776, // 1 TiB
-            ),
-          },
-  };
-}
-
-function clampInt(value: number | undefined, fallback: number, min: number, max: number): number {
-  if (value === undefined || !Number.isFinite(value)) {
-    return fallback;
-  }
-  return Math.min(max, Math.max(min, Math.floor(value)));
-}

package/src/tools.ts

@@ -1,166 +0,0 @@
-/**
- * `defineTool` — authored at `agent/tools/<name>.ts`.
- *
- * Each file under `agent/tools/` is one tool; the filename becomes the tool
- * name the model sees. Export the definition as the module's default export:
- *
- * ```ts
- * import { defineTool } from "@cursor/bdk/tools";
- * import { z } from "zod";
- *
- * // Runs in-process on the agent-serve host (default). Authored MCP
- * // connections are on ctx.host.mcp (also on the Cursor agent via SDK, and
- * // on channel handlers via args.host.mcp).
- * export default defineTool({
- *   description: "Get the current weather for a city.",
- *   inputSchema: z.object({ city: z.string() }),
- *   async execute({ city }, ctx) {
- *     // await ctx.host.mcp.callTool("linear", "list_issues", { ... })
- *     return { city, condition: "Sunny", temperatureF: 72 };
- *   },
- * });
- * ```
- *
- * Park the call for human approval (playground or
- * `POST /v1/session/:id/approvals/:callId`) before `execute` runs:
- *
- * ```ts
- * export default defineTool({
- *   description: "Post a weather alert to ops.",
- *   needsApproval: true,
- *   inputSchema: z.object({ city: z.string(), message: z.string() }),
- *   async execute({ city, message }) {
- *     return { posted: true, city, message };
- *   },
- * });
- * ```
- *
- * Agent-side tools materialize a shell script the Cursor agent invokes
- * (local harness or cloud). JSON args on stdin, result on stdout:
- *
- * ```ts
- * export default defineTool({
- *   description: "Echo a message from the agent workspace.",
- *   execution: "agent",
- *   inputSchema: z.object({ message: z.string() }),
- *   script: `#!/usr/bin/env bash
- * set -euo pipefail
- * message=$(python3 -c 'import json,sys; print(json.load(sys.stdin)["message"])')
- * printf '%s\\n' "$message"
- * `,
- * });
- * ```
- */
-
-import type { z } from "zod";
-import { forwardTimeArgument, missingTimeWindow, schemaTimeWindowKeys } from "./internal/as-of.js";
-import { brandDefinition } from "./internal/brand.js";
-import { classifyAnnotationsEffect } from "./internal/tool-policy.js";
-import type {
-  JsonObject,
-  JsonSchemaObject,
-  ToolContext,
-  ToolDefinition,
-  ToolEffectDeclaration,
-  ToolExecuteResult,
-  ToolNeedsApproval,
-} from "./types.js";
-
-export type {
-  HostMcpCallResult,
-  HostMcpRegistry,
-  HostMcpToolInfo,
-  ToolConfig,
-  ToolContext,
-  ToolDefinition,
-  ToolEffect,
-  ToolEffectDeclaration,
-  ToolExecuteResult,
-  ToolExecution,
-  ToolNeedsApproval,
-  ToolResultContent,
-} from "./types.js";
-/**
- * Time-window and effect classifiers the host applies to every tool call.
- * Re-exported for tools that reach other tools themselves (change-monitor
- * `script`): inner calls skip the host gate, so the sandbox applies the same
- * forward-time, omitted-window, and read-only filters.
- */
-export { classifyAnnotationsEffect, forwardTimeArgument, missingTimeWindow, schemaTimeWindowKeys };
-
-/** Input type for `execute`: inferred from a zod schema, JSON otherwise. */
-export type ToolInput<TSchema> = TSchema extends z.ZodTypeAny ? z.infer<TSchema> : JsonObject;
-
-type ServerToolConfig<TSchema> = {
-  description: string;
-  execution?: "server";
-  inputSchema?: TSchema;
-  /**
-   * JSON Schema for the tool's structured output (zod converted at
-   * discovery, never validated against). Advertised when declared.
-   */
-  outputSchema?: z.ZodTypeAny | JsonSchemaObject;
-  needsApproval?: ToolNeedsApproval<ToolInput<TSchema>>;
-  /**
-   * Whether this tool changes anything outside the session. Undeclared means
-   * write, so a dry-run session answers it instead of running it.
-   */
-  effect?: ToolEffectDeclaration<ToolInput<TSchema>>;
-  /**
-   * Input properties carrying time bounds. In an `asOf` session each named
-   * argument must be an absolute ISO-8601 instant with a timezone, no later
-   * than the frozen instant; a call that omits one, or supplies a relative
-   * or later value, is refused so the model retries with absolute bounds.
-   * Names must exist in {@link inputSchema} or the frozen session refuses to
-   * start. Ignored without `asOf`.
-   */
-  timeArgs?: readonly string[];
-  /** What a `"write"` tool returns in a dry-run session. */
-  dryRunResult?: ToolExecuteResult | ((input: ToolInput<TSchema>) => ToolExecuteResult);
-  execute: (
-    input: ToolInput<TSchema>,
-    ctx: ToolContext,
-  ) => ToolExecuteResult | Promise<ToolExecuteResult>;
-  script?: never;
-};
-
-type AgentToolConfig<TSchema> = {
-  description: string;
-  execution: "agent";
-  inputSchema?: TSchema;
-  /** Output JSON Schema; advertised when declared, never validated against. */
-  outputSchema?: z.ZodTypeAny | JsonSchemaObject;
-  /**
-   * Shell script written into the session workspace. Receives a JSON
-   * object on stdin and should print the result on stdout.
-   */
-  script: string;
-  execute?: never;
-  /** Human-in-the-loop approvals are only supported for server tools. */
-  needsApproval?: never;
-  /**
-   * Agent tools run inside the harness, not through the host's tool path, so
-   * a dry run cannot answer them and an `asOf` session cannot bound them.
-   * Classify the work as a server tool if it needs either.
-   */
-  effect?: never;
-  timeArgs?: never;
-  dryRunResult?: never;
-};
-
-/**
- * Define a tool. With a zod `inputSchema` the input is validated before
- * `execute` runs and typed via inference; with a plain JSON Schema object
- * (or no schema) the input is the raw JSON arguments.
- *
- * Set `execution: "agent"` to materialize a workspace script instead of
- * registering an in-process custom tool.
- *
- * Set `needsApproval: true` (or a predicate) so the host parks the
- * in-flight call until a human approves or denies it.
- */
-export function defineTool<TSchema extends z.ZodTypeAny | JsonSchemaObject | undefined = undefined>(
-  config: ServerToolConfig<TSchema> | AgentToolConfig<TSchema>,
-): ToolDefinition {
-  return brandDefinition("tool", config as ToolDefinition);
-}