@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/tool-policy.ts

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

@@ -1,50 +0,0 @@
-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

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