@cursor/bdk 0.2.3 → 0.2.5

package/src/memory.ts

@@ -1,487 +0,0 @@
-/**
- * Session memory — a journal of what every session of this agent did, so
- * later sessions can recall and build on past work.
- *
- * The write side is {@link memoryHook}, authored as a thin re-export at
- * `agent/hooks/memory.ts` (scaffolded by `agent-sdk init`): after each turn
- * it appends one record (timestamp, session, user message, final result,
- * usage) to `<stateRoot>/memory/journal.jsonl`.
- *
- * There is no read-side API. The framework symlinks `<stateRoot>/memory`
- * into every session workspace as `memory/`, so agents read the journal
- * with their normal file tools (`instructions.md` points them at it). That
- * filesystem visibility is why memory does not route through
- * `defineStorage` sinks, which are opaque to the model. A custom
- * {@link MemoryBackend} (database, vector store, …) supplies its own read
- * path — typically a server tool under `agent/tools/`, which can resolve
- * state via `ctx.stateRoot`.
- *
- * On Cursor-managed hosting the default is {@link agentStoreMemoryBackend}:
- * the journal lives on the deployment's Agent Store (survives deploys,
- * visible on cloud VMs under the store mount), written exclusively through
- * the `memory.append` domain call — the server owns the journal pattern —
- * and mirrored to `<stateRoot>/memory/journal.jsonl` (hydrated per session
- * via `memory.read`, appended locally per turn) so the workspace symlink
- * read path keeps working for local-runtime turns. The
- * `factory-api-v1` pin file exists only on hosted pods — plain local dev
- * runs {@link fileMemoryBackend} and never sees the hosted lane.
- */
-
-import { randomUUID } from "node:crypto";
-import { appendFile, mkdir, rename, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { agentStoreKeys } from "./files.js";
-import {
-  type CursorHostedFilesOptions,
-  isCursorHostedFilesAvailable,
-} from "./files-backends/cursor-hosted.js";
-import { defineHook } from "./hooks.js";
-import {
-  createStoreApiClient,
-  isStoreApiLaneEnabled,
-  type StoreApiClient,
-} from "./internal/cursor/store-api-client.js";
-import type { HookContext, HookDefinition, TurnUsage } from "./types.js";
-
-/** Name of the shared memory directory under the agent state root. */
-export const MEMORY_DIR_NAME = "memory";
-
-/** One journal line: what a single turn did. */
-export type TurnMemoryRecord = {
-  /** ISO timestamp of when the turn finished. */
-  at: string;
-  sessionId: string;
-  channelId: string;
-  status: "completed" | "failed";
-  /** Session title, when the channel set one. */
-  title?: string;
-  /** Cursor SDK agent id (cloud: `bc-…`; local: the session id). */
-  sdkAgentId?: string;
-  /** The user message that started the turn (truncated). */
-  userMessage?: string;
-  /** Final assistant text of the turn, or the failure message (truncated). */
-  result?: string;
-  usage?: TurnUsage;
-};
-
-/** Where turn records go. Receives the agent's state root and name per append. */
-export interface MemoryBackend {
-  appendTurn(
-    record: TurnMemoryRecord,
-    ctx: { stateRoot: string; agentName: string },
-  ): Promise<void>;
-  /**
-   * Optional session-start hook: bring the backend's local read path up to
-   * date before the session's first turn reads it. A freshness upgrade, not
-   * a correctness gate — implementations soft-fail and keep whatever read
-   * state already exists.
-   */
-  prepareSession?(ctx: { stateRoot: string; agentName: string }): Promise<void>;
-}
-
-export interface FileMemoryBackendOptions {
-  /**
-   * Rotate `journal.jsonl` to a timestamped sibling once it exceeds this
-   * size, keeping the file agents grep small. Default 5 MiB.
-   */
-  maxJournalBytes?: number;
-}
-
-/**
- * Local default backend: append-only JSONL at `<stateRoot>/memory/journal.jsonl`
- * — the directory the framework symlinks into session workspaces. Rotated
- * segments stay alongside as `journal-<epoch-ms>.jsonl`.
- */
-export function fileMemoryBackend(options: FileMemoryBackendOptions = {}): MemoryBackend {
-  const maxJournalBytes = options.maxJournalBytes ?? 5 * 1024 * 1024;
-  // Event dispatch is serialized per session but concurrent across
-  // sessions, so appends to the shared journal are chained per path. A
-  // failed append must not poison the chain for later turns.
-  const appendChains = new Map<string, Promise<void>>();
-  // Same-millisecond rotations must not reuse a segment name — POSIX
-  // rename would silently replace the earlier archive.
-  let rotationSeq = 0;
-  return {
-    async appendTurn(record, ctx) {
-      const dir = join(ctx.stateRoot, MEMORY_DIR_NAME);
-      const path = join(dir, "journal.jsonl");
-      const prior = appendChains.get(path) ?? Promise.resolve();
-      const next = prior
-        .catch(() => {})
-        .then(async () => {
-          await mkdir(dir, { recursive: true });
-          const size = (await stat(path).catch(() => undefined))?.size ?? 0;
-          if (size >= maxJournalBytes) {
-            rotationSeq += 1;
-            await rename(path, join(dir, `journal-${Date.now()}-${rotationSeq}.jsonl`));
-          }
-          await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
-        });
-      appendChains.set(path, next);
-      await next;
-    },
-  };
-}
-
-export interface AgentStoreMemoryBackendOptions {
-  /**
-   * Local mirror rotation threshold, same meaning as
-   * {@link FileMemoryBackendOptions}. The durable journal's rotation is the
-   * server's (`memory.append` controller), not this.
-   */
-  maxJournalBytes?: number;
-  /**
-   * Cursor-hosted transport overrides (tests): base URL, credential, store
-   * source id, protocol pin, fetch. Feeds the default
-   * {@link storeApiClient} and the lane-availability check.
-   */
-  hosted?: CursorHostedFilesOptions;
-  /**
-   * Domain-lane client override (tests). Defaults to
-   * {@link createStoreApiClient} over {@link hosted} — the module that owns
-   * the `memory.append` / `memory.read` transport, typed errors, and
-   * bounded backoff.
-   */
-  storeApiClient?: StoreApiClient;
-}
-
-/**
- * Journal on the deployment's Agent Store — durable across deploys, visible
- * on cloud VMs under the store mount, written exclusively through the
- * `memory.append` domain call: the server owns the journal's storage
- * pattern (Redis-buffered flush, rotation), so a pathological pattern is
- * fixable in a backend deploy instead of a July release plus a rebake.
- *
- * There is no client-composed fallback. The read-modify-write CAS lane that
- * predated the domain call (and caused the 2026-09-18 Agent Store read
- * storm) was removed in 0.2.1 together with v2 hosting binding the
- * `factory-api-v1` pin unconditionally and refusing artifacts frozen on an
- * older July. A hosted pod without the pin is therefore a misconfiguration
- * (a server predating the pin change, or a local env naming a hosted store
- * without one): records are dropped loudly, never written client-side.
- */
-export function agentStoreMemoryBackend(
-  options: AgentStoreMemoryBackendOptions = {},
-): MemoryBackend {
-  const hosted = options.hosted ?? {};
-  const maxJournalBytes = options.maxJournalBytes ?? 5 * 1024 * 1024;
-  // Mirror work is chained per journal key (same shape as
-  // fileMemoryBackend): hydration and appends on one agent's mirror never
-  // interleave, and a failed step must not poison the chain for later turns.
-  const appendChains = new Map<string, Promise<void>>();
-
-  // Transport, envelope, typed errors, and bounded backoff all live in the
-  // client; this module only decides which lane an append takes.
-  const storeApiClient = options.storeApiClient ?? createStoreApiClient(hosted);
-
-  /**
-   * The domain lane still owes local-runtime sessions their read path:
-   * cloud-runtime turns read the journal through the store mount, but
-   * local-runtime turns on hosted pods (the default `runtime: "local"`)
-   * read `<stateRoot>/memory/journal.jsonl` via the workspace symlink, and
-   * on hosting the only writer of that file is this backend. So the lane
-   * keeps the mirror live without reintroducing the CAS read pattern:
-   * hydrate it once from the store when the file is absent (a fresh pod
-   * after a deploy), then append each successfully posted record locally,
-   * rotating at {@link maxJournalBytes} like {@link fileMemoryBackend}.
-   * Server-buffered records not yet flushed when a pod hydrates are the
-   * lane's documented staleness window (~30 s / 64 KiB), and other pods'
-   * appends surface on the next hydration — advisory memory, same envelope
-   * as the server side.
-   */
-  const hydratedMirrors = new Set<string>();
-  let mirrorRotationSeq = 0;
-  const maintainLocalMirror = async (
-    record: TurnMemoryRecord,
-    ctx: { stateRoot: string; agentName: string },
-  ): Promise<void> => {
-    const dir = join(ctx.stateRoot, MEMORY_DIR_NAME);
-    const path = join(dir, "journal.jsonl");
-    if (!hydratedMirrors.has(path)) {
-      // Appends are chained per journal key, so this guard never races
-      // itself for one agent. Backstop for a session that appended before
-      // any prepareSession hydration ran (e.g. a custom hook ordering).
-      hydratedMirrors.add(path);
-      const existing = await stat(path).catch(() => undefined);
-      if (existing === undefined) {
-        const content = await storeApiClient.memoryReadContent({
-          agent: ctx.agentName,
-        });
-        if (content !== undefined) {
-          await mirrorJournalLocally(ctx.stateRoot, content);
-        }
-      }
-    }
-    await mkdir(dir, { recursive: true });
-    const size = (await stat(path).catch(() => undefined))?.size ?? 0;
-    if (size >= maxJournalBytes) {
-      mirrorRotationSeq += 1;
-      await rename(path, join(dir, `journal-${Date.now()}-${mirrorRotationSeq}.jsonl`));
-    }
-    await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
-  };
-
-  /**
-   * One `memory.append` domain call; the server appends to the server-owned
-   * journal. On success the record is also appended to the local mirror so
-   * the workspace symlink read path stays live (see
-   * {@link maintainLocalMirror}).
-   *
-   * Failure policy: log and give up for this record. Memory is advisory and
-   * the hook runner treats an append failure as non-fatal to the turn;
-   * falling back to the CAS path per-record would reintroduce the write
-   * storm under exactly the server brownout that makes this call fail. A
-   * failed POST also skips the mirror — the mirror must never show a record
-   * the durable journal will not have.
-   */
-  const appendViaStoreApi = async (
-    record: TurnMemoryRecord,
-    ctx: { stateRoot: string; agentName: string },
-  ): Promise<void> => {
-    try {
-      await storeApiClient.memoryAppend({ agent: ctx.agentName, record });
-    } catch (error) {
-      console.warn(
-        `[agent-serve] memory.append dropped one record for "${ctx.agentName}": ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      );
-      return;
-    }
-    try {
-      await maintainLocalMirror(record, ctx);
-    } catch (error) {
-      console.warn(
-        `[agent-serve] memory mirror update failed for "${ctx.agentName}" (journal record is durable): ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      );
-    }
-  };
-
-  /**
-   * Session-start hydration: one `memory.read` (flush-on-read server-side,
-   * so the pending buffer — including a burst another pod appended — lands
-   * first) and the mirror is rewritten to global state; the session then
-   * reads everything appended before it started. Soft-fail: a failed
-   * hydration keeps the existing mirror.
-   */
-  const hydrateMirror = async (ctx: { stateRoot: string; agentName: string }): Promise<void> => {
-    const path = join(ctx.stateRoot, MEMORY_DIR_NAME, "journal.jsonl");
-    try {
-      const content = await storeApiClient.memoryReadContent({
-        agent: ctx.agentName,
-      });
-      if (content !== undefined) {
-        // Never regress the read path: every mirrored record was
-        // server-acked before it was written locally, so a download SHORTER
-        // than the mirror means the server's flush-on-read was degraded (a
-        // busy lock, a Redis outage — the acked tail is still buffered) or
-        // the journal rotated. Keeping the richer mirror loses nothing;
-        // rewriting would hide records the agent has already seen.
-        const mirroredBytes = (await stat(path).catch(() => undefined))?.size ?? 0;
-        if (content.byteLength >= mirroredBytes) {
-          await mirrorJournalLocally(ctx.stateRoot, content);
-        }
-      }
-      // Either way the read answered: skip the append path's absent-file
-      // hydration for the rest of this process.
-      hydratedMirrors.add(path);
-    } catch (error) {
-      console.warn(
-        `[agent-serve] memory hydration failed for "${ctx.agentName}" (keeping the existing mirror): ${
-          error instanceof Error ? error.message : String(error)
-        }`,
-      );
-    }
-  };
-
-  /**
-   * Hosted pods carry the pin and a provisioned store by construction (v2
-   * hosting binds `factory-api-v1` unconditionally and refuses pre-0.2.1
-   * artifacts). Reaching this without them means a misconfigured
-   * environment; there is no client-side write to fall back to.
-   */
-  const refuseMisconfiguredLane = (agentName: string, verb: string): void => {
-    console.error(
-      `[agent-serve] memory ${verb} for "${agentName}" dropped: the store API lane is unavailable (missing/foreign AGENT_SERVE_STORE_PROTOCOL pin or no provisioned store). This July has no client-side journal fallback; fix the hosting pin.`,
-    );
-  };
-
-  return {
-    async prepareSession(ctx) {
-      // Chained on the same per-journal key as appends, so hydration never
-      // interleaves with an append's mirror write.
-      const key = agentStoreKeys.memoryJournal(ctx.agentName);
-      const prior = appendChains.get(key) ?? Promise.resolve();
-      const next = prior
-        .catch(() => {})
-        .then(async () => {
-          if (!isStoreApiLaneEnabled(hosted)) {
-            refuseMisconfiguredLane(ctx.agentName, "hydration");
-            return;
-          }
-          await hydrateMirror(ctx);
-        });
-      appendChains.set(key, next);
-      await next;
-    },
-
-    async appendTurn(record, ctx) {
-      // Soft-fail by construction (appendViaStoreApi never throws), but
-      // still chained per journal key: the local mirror's hydrate-then-
-      // append must not interleave with itself. Lane availability is
-      // re-resolved lazily per append, so a pin bound after serve start
-      // takes effect without a restart.
-      const key = agentStoreKeys.memoryJournal(ctx.agentName);
-      const prior = appendChains.get(key) ?? Promise.resolve();
-      const next = prior
-        .catch(() => {})
-        .then(async () => {
-          if (!isStoreApiLaneEnabled(hosted)) {
-            refuseMisconfiguredLane(ctx.agentName, "append");
-            return;
-          }
-          await appendViaStoreApi(record, ctx);
-        });
-      appendChains.set(key, next);
-      await next;
-    },
-  };
-}
-
-/** Atomic full rewrite of the local mirror; also hydrates a fresh pod after a deploy. */
-async function mirrorJournalLocally(stateRoot: string, contents: Uint8Array): Promise<void> {
-  const dir = join(stateRoot, MEMORY_DIR_NAME);
-  await mkdir(dir, { recursive: true });
-  const tmp = join(dir, `.tmp-${randomUUID()}`);
-  await writeFile(tmp, contents);
-  await rename(tmp, join(dir, "journal.jsonl"));
-}
-
-/** Hosted deployments journal to the Agent Store; local dev to plain files. */
-function defaultMemoryBackend(): MemoryBackend {
-  return isCursorHostedFilesAvailable() ? agentStoreMemoryBackend() : fileMemoryBackend();
-}
-
-export interface MemoryHookOptions {
-  /** Where records go. Defaults to {@link fileMemoryBackend}. */
-  backend?: MemoryBackend;
-  /** Truncation cap for stored userMessage / result text. Default 2000. */
-  maxTextLength?: number;
-}
-
-function truncate(text: string, max: number): string {
-  return text.length <= max ? text : `${text.slice(0, max)}…`;
-}
-
-/**
- * Observe-only hook that journals every turn. Author it as
- * `agent/hooks/memory.ts`:
- *
- * ```ts
- * import { memoryHook } from "@cursor/bdk/memory";
- * export default memoryHook();
- * ```
- *
- * The journal is shared across every session — and every user — of the
- * agent. Pass your own {@link MemoryHookOptions.backend} to change where
- * memories live; delete the hook file to opt out entirely.
- */
-export function memoryHook(options: MemoryHookOptions = {}): HookDefinition {
-  const backend = options.backend ?? defaultMemoryBackend();
-  const maxTextLength = options.maxTextLength ?? 2000;
-  // Inbound message per turn (truncated at receipt so large pastes are not
-  // retained), keyed `<sessionId>/<turnId>` — `message.received` and the
-  // turn-end events share a turnId. Entries drop at turn end and any
-  // stragglers (turns that never reached a terminal event) at session end.
-  const pendingMessages = new Map<string, string>();
-  const pendingKey = (ctx: HookContext, turnId: string | undefined): string =>
-    `${ctx.session.id}/${turnId ?? "?"}`;
-
-  const record = async (
-    ctx: HookContext,
-    turnId: string | undefined,
-    status: TurnMemoryRecord["status"],
-    result: string | undefined,
-    usage: TurnUsage | undefined,
-  ): Promise<void> => {
-    const key = pendingKey(ctx, turnId);
-    const userMessage = pendingMessages.get(key);
-    pendingMessages.delete(key);
-    const entry: TurnMemoryRecord = {
-      at: new Date().toISOString(),
-      sessionId: ctx.session.id,
-      channelId: ctx.channel.id,
-      status,
-    };
-    if (ctx.session.title !== undefined) {
-      entry.title = ctx.session.title;
-    }
-    if (ctx.session.sdkAgentId !== undefined) {
-      entry.sdkAgentId = ctx.session.sdkAgentId;
-    }
-    if (userMessage !== undefined) {
-      entry.userMessage = userMessage;
-    }
-    if (result !== undefined) {
-      entry.result = truncate(result, maxTextLength);
-    }
-    if (usage !== undefined) {
-      entry.usage = usage;
-    }
-    await backend.appendTurn(entry, {
-      stateRoot: ctx.stateRoot,
-      agentName: ctx.agent.name,
-    });
-  };
-
-  const sweepSession = (ctx: HookContext): void => {
-    for (const key of pendingMessages.keys()) {
-      if (key.startsWith(`${ctx.session.id}/`)) {
-        pendingMessages.delete(key);
-      }
-    }
-  };
-
-  return defineHook({
-    events: {
-      async "session.started"(_event, ctx) {
-        // Bring the mirror (the workspace symlink read path) up to date
-        // before the session's first turn reads it. Backends without a
-        // prepareSession (plain files) have nothing to freshen. Soft-fail:
-        // hydration is a freshness upgrade, never a turn blocker.
-        try {
-          await backend.prepareSession?.({
-            stateRoot: ctx.stateRoot,
-            agentName: ctx.agent.name,
-          });
-        } catch (error) {
-          console.warn(
-            `[agent-serve] memory hydration at session start failed: ${
-              error instanceof Error ? error.message : String(error)
-            }`,
-          );
-        }
-      },
-      async "message.received"(event, ctx) {
-        pendingMessages.set(
-          pendingKey(ctx, event.turnId),
-          truncate(event.data.text, maxTextLength),
-        );
-      },
-      async "turn.completed"(event, ctx) {
-        await record(ctx, event.turnId, "completed", event.data.result, event.data.usage);
-      },
-      async "turn.failed"(event, ctx) {
-        await record(ctx, event.turnId, "failed", event.data.message, undefined);
-      },
-      async "session.completed"(_event, ctx) {
-        sweepSession(ctx);
-      },
-      async "session.failed"(_event, ctx) {
-        sweepSession(ctx);
-      },
-    },
-  });
-}

package/src/otel-public.ts

@@ -1,24 +0,0 @@
-/**
- * Public `@cursor/bdk/otel` surface: types and W3C `traceparent`
- * helpers. `defineOtel` is `@cursor/bdk/internal/otel`.
- */
-
-export type {
-  OtelConfig,
-  OtelConfigFactory,
-  OtelDefinition,
-  OtelExporterConfig,
-  OtelLogOptions,
-  OtelMetricOptions,
-  OtelSignal,
-  OtelTraceOptions,
-} from "./otel.js";
-export {
-  activeTraceparent,
-  BACKEND_TRACEPARENT_HEADER,
-  formatTraceparent,
-  injectActiveTraceContext,
-  installOutboundFetchInstrumentation,
-  instrumentedFetch,
-  TRACEPARENT_HEADER,
-} from "./otel.js";