@cursor/bdk 0.2.1

package/src/internal/tool-policy.ts

@@ -0,0 +1,222 @@
+/**
+ * The one decision every tool call passes through.
+ *
+ * A tool body can be reached by more than one path — the model's own calls on
+ * a local turn, a cloud turn's calls over the MCP endpoint, a direct
+ * `callTool`, the host connection bridge. Each of those is a separate code
+ * path, and a guarantee that holds on some of them is not a guarantee. So the
+ * decision lives here, in one pure function, and every path asks it rather
+ * than re-implementing it.
+ */
+
+import type {
+  DiscoveredTool,
+  McpToolAnnotations,
+  ToolEffect,
+  ToolEffectDeclaration,
+  ToolExecuteResult,
+} from "../types.js";
+import { forwardTimeArgument, missingTimeWindow, timeArgViolation } from "./as-of.js";
+
+/** What the host does with one tool call. */
+export type ToolDecision =
+  /** Run the tool body. */
+  | { kind: "run" }
+  /** Do not run it; return this to the model instead. */
+  | { kind: "answer"; result: ToolExecuteResult }
+  /**
+   * Do not run it; fail the call with this message. Only produced in a dry
+   * run, for an MCP tool nothing classifies: stubbing it would let the run
+   * reach a confident conclusion from no data, and running it could leak a
+   * real write — refusing is the one failure that is loud.
+   */
+  | { kind: "refuse"; message: string }
+  /**
+   * Do not run it; the `asOf` session was asked to read without absolute
+   * bounds, which would read the present.
+   */
+  | { kind: "unbounded"; message: string };
+
+/** What a policy decision needs to know about the call. */
+export interface ToolCallFacts {
+  /** The session answers writes instead of running them. */
+  dryRun: boolean;
+  /** The tool's declaration, if it made one. */
+  effect: ToolEffectDeclaration<never> | undefined;
+  /**
+   * Present when the call targets a tool nobody authored — an advertised MCP
+   * passthrough or a bridged MCP call. Consulted only when {@link effect} is
+   * undeclared: the server's own annotations classify the call, and a tool
+   * they cannot classify refuses in a dry run instead of being stubbed as a
+   * write the way an undeclared authored tool is.
+   */
+  mcpTool?: { name: string; annotations?: McpToolAnnotations };
+  /** What a stubbed write should answer with, if the tool supplied one. */
+  dryRunResult?: ToolExecuteResult | ((input: never) => ToolExecuteResult);
+  /**
+   * Validated input, as the tool body would receive it. Read by a per-call
+   * `effect` predicate, a `dryRunResult` function, and the {@link timeArgs}
+   * bound check, so a caller with none of those — a bridged MCP tool, which
+   * carries no declaration at all — can omit it.
+   */
+  input?: unknown;
+  /** The session's frozen instant, when it has one. */
+  asOf?: string;
+  /** The tool's declared time-bound argument names, if it made them. */
+  timeArgs?: readonly string[];
+  /**
+   * String-typed time-window property names a vendor tool's own input schema
+   * declares (`from`/`to`/`since`/...). In a frozen session a call that omits
+   * one is refused: the vendor fills an omitted window with a live default
+   * the argument walker can never see. Advertised/bridged MCP tools only —
+   * authored tools declare {@link timeArgs} instead.
+   */
+  timeWindow?: readonly string[];
+}
+
+/**
+ * What a stubbed write answers. Deliberately not self-describing: a model told
+ * mid-turn that its writes are not real starts hedging its conclusions, and
+ * the conclusion is the thing a dry run exists to read. Tell the agent once,
+ * in its opening prompt, not in a tool result.
+ */
+const ACKNOWLEDGED = "Operation acknowledged.";
+
+/**
+ * The effect of one specific call.
+ *
+ * Undeclared resolves to `"write"`. A dry run promises that nothing outside
+ * the session changed, and it cannot promise that about a tool it knows
+ * nothing about — so the unknown case is the one that costs a stubbed read
+ * rather than the one that leaks a real write.
+ */
+export function resolveEffect(
+  effect: ToolEffectDeclaration<never> | undefined,
+  input: unknown,
+): ToolEffect {
+  const declared = typeof effect === "function" ? effect(input as never) : effect;
+  return declared === "read" ? "read" : "write";
+}
+
+/**
+ * The effect an MCP server's own annotations declare, fail-closed.
+ *
+ * `readOnlyHint: true` without `destructiveHint: true` is a read; either
+ * negative signal is a write; anything else — absent annotations, or
+ * annotations that carry no effect signal (a bare `title`) — is `undefined`,
+ * unclassified. Mirrors `@anysphere/mcp-core/mcp-tool-annotations`
+ * (`classifyMcpToolAnnotationRisk`), which this package cannot import (npm
+ * publish, workspace-only dependency); keep the two in sync.
+ */
+export function classifyAnnotationsEffect(
+  annotations: McpToolAnnotations | undefined,
+): ToolEffect | undefined {
+  if (annotations === undefined) {
+    return undefined;
+  }
+  if (annotations.destructiveHint !== true && annotations.readOnlyHint === true) {
+    return "read";
+  }
+  if (annotations.readOnlyHint === false || annotations.destructiveHint === true) {
+    return "write";
+  }
+  return undefined;
+}
+
+/**
+ * The effect of one direct call on a discovered tool, the same way
+ * {@link decideToolCall} reads it: the authored declaration when there is
+ * one (possibly per input), else the MCP server's own annotations for an
+ * advertised passthrough. `undefined` is an advertised tool nothing
+ * classifies; callers gating on "read" treat it as a write.
+ */
+export function directCallEffect(
+  tool: Pick<DiscoveredTool, "advertised" | "annotations" | "definition">,
+  input: unknown,
+): ToolEffect | undefined {
+  if (tool.definition.effect === undefined && tool.advertised === true) {
+    return classifyAnnotationsEffect(tool.annotations);
+  }
+  return resolveEffect(tool.definition.effect, input);
+}
+
+/**
+ * What a dry run answers when nothing classifies an MCP tool. Deliberately
+ * reads as a strict API rather than disclosing the session's posture (see
+ * {@link ACKNOWLEDGED}), and names what is missing so the fix — the server
+ * annotating, or a server-side classification entry — is one step away.
+ */
+function unclassifiedRefusal(toolName: string): string {
+  return (
+    `Tool "${toolName}" is not available in this session: its MCP server ` +
+    `does not declare whether it reads or writes (readOnlyHint/` +
+    `destructiveHint), and no server-side classification exists for it, so ` +
+    `this session cannot tell whether calling it would change anything ` +
+    `outside the session. Use a tool that declares its effect.`
+  );
+}
+
+/** Decide what to do with one tool call. Pure; no I/O, no session state. */
+export function decideToolCall(facts: ToolCallFacts): ToolDecision {
+  // Before the dry-run split: a frozen session bounds its reads whether or
+  // not its writes are stubbed.
+  if (facts.asOf !== undefined) {
+    if (facts.timeArgs !== undefined && facts.timeArgs.length > 0) {
+      const violation = timeArgViolation(facts.input, facts.timeArgs, facts.asOf);
+      if (violation !== undefined) {
+        return { kind: "unbounded", message: violation };
+      }
+    }
+    const forward = forwardTimeArgument(facts.input, facts.asOf);
+    if (forward !== undefined) {
+      return { kind: "unbounded", message: forward };
+    }
+    // Present values are checked above; absent ones are the vendor's live
+    // default window, which no walker can see. Require them explicitly.
+    if (facts.timeWindow !== undefined) {
+      const omitted = missingTimeWindow(facts.input, facts.timeWindow, facts.asOf);
+      if (omitted !== undefined) {
+        return { kind: "unbounded", message: omitted };
+      }
+    }
+  }
+  if (!facts.dryRun) {
+    return { kind: "run" };
+  }
+  if (facts.effect === undefined && facts.mcpTool !== undefined) {
+    const effect = classifyAnnotationsEffect(facts.mcpTool.annotations);
+    if (effect === undefined) {
+      return {
+        kind: "refuse",
+        message: unclassifiedRefusal(facts.mcpTool.name),
+      };
+    }
+    if (effect === "read") {
+      return { kind: "run" };
+    }
+    return {
+      kind: "answer",
+      result: dryRunAnswer(facts.dryRunResult, facts.input),
+    };
+  }
+  if (resolveEffect(facts.effect, facts.input) === "read") {
+    return { kind: "run" };
+  }
+  return {
+    kind: "answer",
+    result: dryRunAnswer(facts.dryRunResult, facts.input),
+  };
+}
+
+function dryRunAnswer(
+  dryRunResult: ToolCallFacts["dryRunResult"],
+  input: unknown,
+): ToolExecuteResult {
+  if (dryRunResult === undefined) {
+    return ACKNOWLEDGED;
+  }
+  if (typeof dryRunResult === "function") {
+    return dryRunResult(input as never);
+  }
+  return dryRunResult;
+}

package/src/internal/tool-result.ts

@@ -0,0 +1,50 @@
+import type { SDKCustomToolResult } from "@cursor/sdk";
+import type { ToolExecuteResult } from "../types.js";
+
+/**
+ * Normalize a custom tool's return value for the SDK.
+ *
+ * Plain objects are round-tripped through JSON so fields whose value is
+ * `undefined` are dropped (JSON semantics). Without this, a return like
+ * `{ action: undefined }` reaches the SDK's protobuf `Struct.fromJson`,
+ * which throws `cannot decode google.protobuf.Value from JSON undefined` —
+ * the tool has already executed, but the model only sees an opaque encode
+ * error and typically retries the call.
+ */
+export function normalizeToolResult(result: ToolExecuteResult | undefined): SDKCustomToolResult {
+  if (result === undefined) {
+    return "";
+  }
+  if (typeof result === "string") {
+    return result;
+  }
+  try {
+    return JSON.parse(JSON.stringify(result)) as SDKCustomToolResult;
+  } catch {
+    return result as SDKCustomToolResult;
+  }
+}
+
+/**
+ * Pull a channel-friendly error string out of a normalized tool result
+ * (error envelopes with `{ content: [{ type: "text", text }] }`, or a
+ * bare string). Used for {@link import("../types.js").ToolCallOutcome.errorMessage}.
+ */
+export function toolCallErrorMessage(result: unknown): string | undefined {
+  if (typeof result === "string" && result.trim() !== "") {
+    return result;
+  }
+  if (
+    result === null ||
+    typeof result !== "object" ||
+    !("content" in result) ||
+    !Array.isArray((result as { content: unknown }).content)
+  ) {
+    return undefined;
+  }
+  const texts = (result as { content: Array<{ type?: string; text?: string }> }).content
+    .filter(part => part.type === "text" && typeof part.text === "string")
+    .map(part => part.text!.trim())
+    .filter(text => text !== "");
+  return texts.length === 0 ? undefined : texts.join("\n");
+}

package/src/internal/trajectory.ts

@@ -0,0 +1,418 @@
+/**
+ * Compact, agent-friendly views of a session's NDJSON event stream.
+ *
+ * Coding agents (and eval harnesses) want a stable JSON shape: user
+ * messages, assistant text, tool calls with args/results, and
+ * success/failure — not a firehose of streaming deltas.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { SessionEvent, TurnCost, TurnUsage } from "../types.js";
+
+export interface TrajectoryToolCall {
+  callId: string;
+  toolName: string;
+  args?: unknown;
+  output?: unknown;
+  isError: boolean;
+  /** Present when the tool required human approval before execute. */
+  approvalDecision?: "approve" | "deny";
+  /** Parent task/subagent call id when this tool ran inside a subagent. */
+  parentCallId?: string;
+}
+
+export interface TrajectorySubagent {
+  callId: string;
+  name?: string;
+  description?: string;
+  /** Nested tool calls streamed while this subagent was running. */
+  toolCalls: TrajectoryToolCall[];
+}
+
+export interface TrajectoryTurn {
+  turnId: string;
+  userMessage?: string;
+  assistantText: string;
+  reasoningText?: string;
+  toolCalls: TrajectoryToolCall[];
+  subagents: TrajectorySubagent[];
+  usage?: TurnUsage;
+  /** Estimated dollar cost of this turn (from the `turn.completed` event). */
+  cost?: TurnCost;
+  result?: string;
+  failed: boolean;
+  error?: string;
+}
+
+export interface Trajectory {
+  sessionId: string;
+  sdkAgentId?: string;
+  agentUrl?: string;
+  channelId?: string;
+  ok: boolean;
+  finalText: string;
+  turnsFailed: number;
+  toolCallCount: number;
+  /** Sum of per-turn estimated costs; present when any turn reported cost. */
+  totalCostUsd?: number;
+  turns: TrajectoryTurn[];
+}
+
+/**
+ * Collapse a session event list into a trajectory. Streaming deltas are
+ * folded into final assistant / reasoning text per turn.
+ */
+export function buildTrajectory(events: SessionEvent[]): Trajectory {
+  let sessionId = "";
+  let sdkAgentId: string | undefined;
+  let agentUrl: string | undefined;
+  let channelId: string | undefined;
+  const turnsById = new Map<string, TrajectoryTurn>();
+  const turnOrder: string[] = [];
+  const pendingCalls = new Map<string, TrajectoryToolCall>();
+
+  const ensureTurn = (turnId: string): TrajectoryTurn => {
+    const existing = turnsById.get(turnId);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const turn: TrajectoryTurn = {
+      turnId,
+      assistantText: "",
+      toolCalls: [],
+      subagents: [],
+      failed: false,
+    };
+    turnsById.set(turnId, turn);
+    turnOrder.push(turnId);
+    return turn;
+  };
+
+  for (const event of events) {
+    if (sessionId === "" && typeof event.sessionId === "string") {
+      sessionId = event.sessionId;
+    }
+    switch (event.type) {
+      case "session.started": {
+        channelId = event.data.channelId;
+        break;
+      }
+      case "agent.bound": {
+        sdkAgentId = event.data.sdkAgentId;
+        agentUrl = event.data.url;
+        break;
+      }
+      case "message.received": {
+        if (event.turnId !== undefined) {
+          ensureTurn(event.turnId).userMessage = event.data.text;
+        }
+        break;
+      }
+      case "message.completed": {
+        // Nested subagent text must not overwrite the parent turn reply.
+        if (event.data.parentCallId !== undefined) {
+          break;
+        }
+        if (event.turnId !== undefined && event.data.text !== "") {
+          ensureTurn(event.turnId).assistantText = event.data.text;
+        }
+        break;
+      }
+      case "reasoning.appended": {
+        // Nested subagent thinking stays off the parent turn transcript.
+        if (event.data.parentCallId !== undefined) {
+          break;
+        }
+        if (event.turnId !== undefined) {
+          ensureTurn(event.turnId).reasoningText = event.data.text;
+        }
+        break;
+      }
+      case "actions.requested": {
+        if (event.turnId === undefined) {
+          break;
+        }
+        const turn = ensureTurn(event.turnId);
+        for (const call of event.data.calls) {
+          const parentCallId = call.parentCallId ?? event.data.parentCallId;
+          // Keep bare top-level `task` in toolCalls so evals like
+          // `calledTool("task")` / `notCalledTool("task")` keep working.
+          // Nested progress also appears under `subagents`.
+          const entry: TrajectoryToolCall = {
+            callId: call.callId,
+            toolName: call.toolName,
+            isError: false,
+            args: call.args,
+            parentCallId,
+          };
+          pendingCalls.set(call.callId, entry);
+          if (parentCallId !== undefined) {
+            let sub = turn.subagents.find(s => s.callId === parentCallId);
+            if (sub === undefined) {
+              sub = { callId: parentCallId, toolCalls: [] };
+              turn.subagents.push(sub);
+            }
+            sub.toolCalls.push(entry);
+          } else {
+            turn.toolCalls.push(entry);
+          }
+        }
+        break;
+      }
+      case "action.approval_requested": {
+        // Traceability only — the call is already listed under actions.requested.
+        break;
+      }
+      case "action.approval_resolved": {
+        const pending = pendingCalls.get(event.data.callId);
+        if (pending !== undefined) {
+          pending.approvalDecision = event.data.decision;
+        }
+        break;
+      }
+      case "action.auth_requested": {
+        break;
+      }
+      case "action.auth_resolved": {
+        const pending = pendingCalls.get(event.data.callId);
+        if (pending !== undefined) {
+          pending.approvalDecision = event.data.decision;
+        }
+        break;
+      }
+      case "action.result": {
+        const pending = pendingCalls.get(event.data.callId);
+        if (pending !== undefined) {
+          pending.output = event.data.output;
+          pending.isError = event.data.isError;
+          pending.toolName = event.data.toolName;
+        } else if (event.turnId !== undefined) {
+          const turn = ensureTurn(event.turnId);
+          const entry: TrajectoryToolCall = {
+            callId: event.data.callId,
+            toolName: event.data.toolName,
+            output: event.data.output,
+            isError: event.data.isError,
+            parentCallId: event.data.parentCallId,
+          };
+          if (event.data.parentCallId !== undefined) {
+            let sub = turn.subagents.find(s => s.callId === event.data.parentCallId);
+            if (sub === undefined) {
+              sub = {
+                callId: event.data.parentCallId,
+                toolCalls: [],
+              };
+              turn.subagents.push(sub);
+            }
+            sub.toolCalls.push(entry);
+          } else {
+            turn.toolCalls.push(entry);
+          }
+        }
+        break;
+      }
+      case "subagent.called": {
+        if (event.turnId !== undefined) {
+          const turn = ensureTurn(event.turnId);
+          const existing = turn.subagents.find(s => s.callId === event.data.callId);
+          if (existing !== undefined) {
+            existing.name = event.data.name;
+            existing.description = event.data.description;
+          } else {
+            turn.subagents.push({
+              callId: event.data.callId,
+              name: event.data.name,
+              description: event.data.description,
+              toolCalls: [],
+            });
+          }
+        }
+        break;
+      }
+      case "turn.completed": {
+        if (event.turnId === undefined) {
+          break;
+        }
+        const turn = ensureTurn(event.turnId);
+        turn.failed = false;
+        if (event.data.usage !== undefined) {
+          turn.usage = event.data.usage;
+        }
+        if (event.data.cost !== undefined) {
+          turn.cost = event.data.cost;
+        }
+        if (event.data.result !== undefined) {
+          turn.result = event.data.result;
+          if (turn.assistantText === "") {
+            turn.assistantText = event.data.result;
+          }
+        }
+        break;
+      }
+      case "turn.failed": {
+        if (event.turnId !== undefined) {
+          const turn = ensureTurn(event.turnId);
+          turn.failed = true;
+          turn.error = event.data.message;
+        }
+        break;
+      }
+      case "session.failed": {
+        if (event.turnId !== undefined) {
+          const turn = ensureTurn(event.turnId);
+          turn.failed = true;
+          turn.error = event.data.message;
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const turns = turnOrder.map(id => turnsById.get(id)!);
+  const turnsFailed = turns.filter(t => t.failed).length;
+  const toolCallCount = turns.reduce(
+    (n, t) => n + t.toolCalls.length + t.subagents.reduce((m, s) => m + s.toolCalls.length, 0),
+    0,
+  );
+  const lastGood = [...turns].reverse().find(t => t.assistantText !== "");
+  const costedTurns = turns.filter(t => t.cost !== undefined);
+  const totalCostUsd =
+    costedTurns.length === 0
+      ? undefined
+      : roundCostUsd(costedTurns.reduce((sum, t) => sum + (t.cost?.totalUsd ?? 0), 0));
+  return {
+    sessionId,
+    ...(sdkAgentId === undefined ? {} : { sdkAgentId }),
+    ...(agentUrl === undefined ? {} : { agentUrl }),
+    ...(channelId === undefined ? {} : { channelId }),
+    ok: turnsFailed === 0 && turns.length > 0,
+    finalText: lastGood?.assistantText ?? "",
+    turnsFailed,
+    toolCallCount,
+    ...(totalCostUsd === undefined ? {} : { totalCostUsd }),
+    turns,
+  };
+}
+
+/** Micro-dollar precision so summed floats stay readable in JSON. */
+export function roundCostUsd(usd: number): number {
+  return Math.round(usd * 1e6) / 1e6;
+}
+
+/** Compact dollar display for estimated costs (`$0.0132`, `$1.25`). */
+export function formatCostUsd(usd: number): string {
+  if (!Number.isFinite(usd)) {
+    return "—";
+  }
+  if (usd === 0) {
+    return "$0.00";
+  }
+  if (usd >= 0.1) {
+    return `$${usd.toFixed(2)}`;
+  }
+  return `$${usd.toFixed(4)}`;
+}
+
+/** Parse an `events.ndjson` file (or any NDJSON blob of SessionEvents). */
+export function parseEventsNdjson(text: string): SessionEvent[] {
+  const events: SessionEvent[] = [];
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "") {
+      continue;
+    }
+    try {
+      events.push(JSON.parse(trimmed) as SessionEvent);
+    } catch {
+      // skip malformed lines
+    }
+  }
+  return events;
+}
+
+/** Load and summarize a durable session event log. */
+export async function loadTrajectoryFromEventsFile(path: string): Promise<Trajectory> {
+  const text = await readFile(path, "utf8");
+  return buildTrajectory(parseEventsNdjson(text));
+}
+
+/** Human-readable one-line-per-turn dump (for non-JSON CLI output). */
+export function formatTrajectoryText(trajectory: Trajectory): string {
+  const lines: string[] = [];
+  lines.push(`session ${trajectory.sessionId || "(unknown)"}  ok=${trajectory.ok}`);
+  if (trajectory.sdkAgentId !== undefined) {
+    lines.push(`sdkAgentId: ${trajectory.sdkAgentId}`);
+  }
+  if (trajectory.agentUrl !== undefined) {
+    lines.push(`url: ${trajectory.agentUrl}`);
+  }
+  lines.push(
+    `turns: ${trajectory.turns.length}  tools=${trajectory.toolCallCount}  failed: ${trajectory.turnsFailed}${
+      trajectory.totalCostUsd === undefined
+        ? ""
+        : `  cost: ${formatCostUsd(trajectory.totalCostUsd)}`
+    }`,
+  );
+  for (const turn of trajectory.turns) {
+    lines.push("");
+    lines.push(`── ${turn.turnId}${turn.failed ? " FAILED" : ""} ──`);
+    if (turn.userMessage !== undefined) {
+      lines.push(`  user: ${truncate(turn.userMessage, 200)}`);
+    }
+    for (const call of turn.toolCalls) {
+      const mark = call.isError ? "✗" : "→";
+      lines.push(`  ${mark} ${call.toolName}${formatArgs(call.args)}`);
+      if (call.output !== undefined) {
+        lines.push(`    ${truncate(stringify(call.output), 160)}`);
+      }
+    }
+    for (const sub of turn.subagents) {
+      const label = sub.name ?? "subagent";
+      const detail = sub.description !== undefined ? ` — ${truncate(sub.description, 80)}` : "";
+      lines.push(`  task ${label}${detail}`);
+      for (const call of sub.toolCalls) {
+        const mark = call.isError ? "✗" : "→";
+        lines.push(`    ${mark} ${call.toolName}${formatArgs(call.args)}`);
+        if (call.output !== undefined) {
+          lines.push(`      ${truncate(stringify(call.output), 160)}`);
+        }
+      }
+    }
+    if (turn.assistantText.length > 0) {
+      lines.push(`  agent: ${truncate(turn.assistantText, 400)}`);
+    }
+    if (turn.error !== undefined) {
+      lines.push(`  error: ${turn.error}`);
+    }
+    if (turn.usage !== undefined) {
+      lines.push(
+        `  usage: in ${turn.usage.inputTokens} out ${turn.usage.outputTokens}${
+          turn.cost === undefined ? "" : `  cost: ${formatCostUsd(turn.cost.totalUsd)}`
+        }`,
+      );
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+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;
+}