@cursor/bdk 0.2.1

package/dist/internal/testing/scm-continuation-fixtures.js

@@ -0,0 +1,253 @@
+/**
+ * GitLab / Bitbucket continuation fixtures shared by the two continuation
+ * vocabulary copies — `internal/continuation-identity.ts` (July) and the
+ * control plane's `agentSdkConversationIdentity.ts` (server-shared). Both
+ * suites import this one module, so a payload shape or key format that only
+ * one copy understands fails CI on the other side.
+ *
+ * Pure data: no imports, so the server-shared suite can load it by relative
+ * path without pulling `@cursor/bdk` into the control plane.
+ */
+const GITLAB_PROJECT = {
+    id: 1234,
+    name: "api",
+    path_with_namespace: "Acme/platform/api",
+    web_url: "https://gitlab.com/Acme/platform/api",
+    default_branch: "main",
+};
+const GITLAB_MERGE_REQUEST = {
+    id: 9001,
+    iid: 42,
+    title: "Add widgets",
+    state: "opened",
+    source_branch: "feature/widgets",
+    target_branch: "main",
+    url: "https://gitlab.com/Acme/platform/api/-/merge_requests/42",
+    last_commit: { id: "0123456789abcdef0123456789abcdef01234567" },
+};
+const BITBUCKET_CLOUD_REPOSITORY = {
+    type: "repository",
+    full_name: "acme/widgets",
+    name: "widgets",
+    uuid: "{5f2d1d5e-6d66-4f5b-9d3e-1b6e5b1c2f3a}",
+    workspace: { slug: "acme", uuid: "{a4f1c5d0-1111-4a2b-8c3d-9e0f1a2b3c4d}" },
+    links: { html: { href: "https://bitbucket.org/acme/widgets" } },
+};
+const BITBUCKET_DC_REPOSITORY = {
+    slug: "widgets",
+    id: 17,
+    name: "widgets",
+    project: { key: "ACME", id: 3, name: "Acme" },
+};
+export const SCM_CONTINUATION_FIXTURES = [
+    {
+        name: "gitlab merge_request open",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "merge_request",
+        payload: {
+            object_kind: "merge_request",
+            event_type: "merge_request",
+            user: { id: 7, username: "alice", name: "Alice" },
+            project: GITLAB_PROJECT,
+            object_attributes: Object.assign(Object.assign({}, GITLAB_MERGE_REQUEST), { action: "open" }),
+        },
+        expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+    },
+    {
+        name: "gitlab merge_request update (new commits)",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "merge_request",
+        payload: {
+            object_kind: "merge_request",
+            event_type: "merge_request",
+            user: { id: 7, username: "alice", name: "Alice" },
+            project: GITLAB_PROJECT,
+            object_attributes: Object.assign(Object.assign({}, GITLAB_MERGE_REQUEST), { action: "update", oldrev: "fedcba9876543210fedcba9876543210fedcba98" }),
+        },
+        expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+    },
+    {
+        name: "gitlab note on merge request",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "note",
+        payload: {
+            object_kind: "note",
+            event_type: "note",
+            user: { id: 8, username: "bob", name: "Bob" },
+            project: GITLAB_PROJECT,
+            object_attributes: {
+                id: 501,
+                note: "Looks good",
+                noteable_type: "MergeRequest",
+                noteable_id: 9001,
+            },
+            merge_request: GITLAB_MERGE_REQUEST,
+        },
+        expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+    },
+    {
+        name: "gitlab note on issue",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "note",
+        payload: {
+            object_kind: "note",
+            event_type: "note",
+            user: { id: 8, username: "bob", name: "Bob" },
+            project: GITLAB_PROJECT,
+            object_attributes: {
+                id: 502,
+                note: "Tracking",
+                noteable_type: "Issue",
+                noteable_id: 300,
+            },
+            issue: { id: 300, iid: 9, title: "Bug" },
+        },
+        expectedKey: undefined,
+    },
+    {
+        name: "gitlab pipeline attached to a merge request",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "pipeline",
+        payload: {
+            object_kind: "pipeline",
+            project: GITLAB_PROJECT,
+            object_attributes: { id: 77, status: "success", sha: "0123456789ab" },
+            merge_request: { iid: 42, id: 9001, title: "Add widgets" },
+        },
+        expectedKey: "cont:gitlab-mr:acme/platform/api!42",
+    },
+    {
+        name: "gitlab pipeline without a merge request",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "pipeline",
+        payload: {
+            object_kind: "pipeline",
+            project: GITLAB_PROJECT,
+            object_attributes: { id: 78, status: "success", sha: "0123456789ab" },
+            merge_request: null,
+        },
+        expectedKey: undefined,
+    },
+    {
+        name: "gitlab push",
+        kind: "gitlab",
+        type: "gitlab-mr",
+        eventType: "push",
+        payload: {
+            object_kind: "push",
+            event_name: "push",
+            ref: "refs/heads/main",
+            project: GITLAB_PROJECT,
+            commits: [],
+        },
+        expectedKey: undefined,
+    },
+    {
+        name: "bitbucket cloud pullrequest:created",
+        kind: "bitbucket",
+        type: "bitbucket-pr",
+        eventType: "pullrequest:created",
+        payload: {
+            repository: BITBUCKET_CLOUD_REPOSITORY,
+            actor: { display_name: "Alice", uuid: "{u-1}" },
+            pullrequest: {
+                id: 7,
+                title: "Add widgets",
+                state: "OPEN",
+                source: {
+                    branch: { name: "feature/widgets" },
+                    commit: { hash: "0123456789ab" },
+                },
+                destination: { branch: { name: "main" }, commit: { hash: "fedcba98" } },
+                links: {
+                    html: { href: "https://bitbucket.org/acme/widgets/pull-requests/7" },
+                },
+            },
+        },
+        expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+    },
+    {
+        name: "bitbucket data center pr:opened (normalized to pullrequest:created)",
+        kind: "bitbucket",
+        type: "bitbucket-pr",
+        eventType: "pullrequest:created",
+        payload: {
+            eventKey: "pr:opened",
+            date: "2026-09-01T12:00:00+0000",
+            actor: { name: "alice", displayName: "Alice", id: 1 },
+            pullRequest: {
+                id: 7,
+                title: "Add widgets",
+                state: "OPEN",
+                open: true,
+                fromRef: {
+                    id: "refs/heads/feature/widgets",
+                    displayId: "feature/widgets",
+                    latestCommit: "0123456789ab",
+                    repository: BITBUCKET_DC_REPOSITORY,
+                },
+                toRef: {
+                    id: "refs/heads/main",
+                    displayId: "main",
+                    latestCommit: "fedcba98",
+                    repository: BITBUCKET_DC_REPOSITORY,
+                },
+            },
+        },
+        expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+    },
+    {
+        name: "bitbucket cloud pullrequest:comment_created",
+        kind: "bitbucket",
+        type: "bitbucket-pr",
+        eventType: "pullrequest:comment_created",
+        payload: {
+            repository: BITBUCKET_CLOUD_REPOSITORY,
+            actor: { display_name: "Bob", uuid: "{u-2}" },
+            pullrequest: { id: 7, title: "Add widgets", state: "OPEN" },
+            comment: { id: 11, content: { raw: "Looks good" } },
+        },
+        expectedKey: "cont:bitbucket-pr:acme/widgets#7",
+    },
+    {
+        name: "bitbucket cloud repo:push",
+        kind: "bitbucket",
+        type: "bitbucket-pr",
+        eventType: "repo:push",
+        payload: {
+            repository: BITBUCKET_CLOUD_REPOSITORY,
+            actor: { display_name: "Alice", uuid: "{u-1}" },
+            push: { changes: [] },
+        },
+        expectedKey: undefined,
+    },
+];
+export const SCM_DEFAULT_SELECTOR_FIXTURES = [
+    { kind: "gitlab", eventTypes: ["merge_request"], expected: "gitlab.mr/v2" },
+    {
+        kind: "gitlab",
+        eventTypes: ["merge_request", "note"],
+        expected: "gitlab.mr/v2",
+    },
+    {
+        kind: "gitlab",
+        eventTypes: ["merge_request", "push"],
+        expected: "gitlab.none/v2",
+    },
+    {
+        kind: "bitbucket",
+        eventTypes: ["pullrequest:created", "pullrequest:updated"],
+        expected: "bitbucket.pr/v2",
+    },
+    {
+        kind: "bitbucket",
+        eventTypes: ["pullrequest:created", "repo:push"],
+        expected: "bitbucket.none/v2",
+    },
+];

package/dist/internal/tool-catalog.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Projections for the live tool catalog (`GET /v1/tools` and
+ * `GET /v1/tools/:name`): the session's tool namespace exactly as a turn
+ * would assemble it — authored server tools plus advertised MCP
+ * passthroughs — under model-facing names.
+ *
+ * Titles are curated data, never derived from descriptions: advertised
+ * tools inherit the upstream server's MCP `annotations.title` (bounded at
+ * listing time), and the well-known non-MCP tool names carry a hardcoded
+ * title here so every deployment shows the same display names.
+ */
+import type { DiscoveredTool, JsonSchemaObject, ToolEffect, ToolExecution } from "../types.js";
+/** Light listing entry: identifiers and curated display data only. */
+export interface CatalogListEntry {
+    name: string;
+    title?: string;
+    /** Connection name for advertised MCP tools; absent for authored tools. */
+    source?: string;
+}
+/** Full description behind `GET /v1/tools/:name`. */
+export interface CatalogDetailEntry extends CatalogListEntry {
+    description: string;
+    execution: ToolExecution;
+    needsApproval: boolean;
+    effect?: ToolEffect | "dynamic";
+    inputSchema: JsonSchemaObject;
+    outputSchema?: JsonSchemaObject;
+}
+export declare function catalogListEntry(tool: DiscoveredTool): CatalogListEntry;
+export declare function catalogDetailEntry(tool: DiscoveredTool): CatalogDetailEntry;
+//# sourceMappingURL=tool-catalog.d.ts.map

package/dist/internal/tool-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-catalog.d.ts","sourceRoot":"","sources":["../../src/internal/tool-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAuD/F,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,aAAa,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CAMvE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,kBAAkB,CAU3E"}

package/dist/internal/tool-catalog.js

@@ -0,0 +1,70 @@
+/**
+ * Projections for the live tool catalog (`GET /v1/tools` and
+ * `GET /v1/tools/:name`): the session's tool namespace exactly as a turn
+ * would assemble it — authored server tools plus advertised MCP
+ * passthroughs — under model-facing names.
+ *
+ * Titles are curated data, never derived from descriptions: advertised
+ * tools inherit the upstream server's MCP `annotations.title` (bounded at
+ * listing time), and the well-known non-MCP tool names carry a hardcoded
+ * title here so every deployment shows the same display names.
+ */
+/**
+ * Display names for the well-known tool names that do not come from MCP
+ * (authored tools have no title field; adding one to `defineTool` for a
+ * presentation concern is not worth the authoring surface).
+ */
+const WELL_KNOWN_TOOL_TITLES = {
+    Delete: "Delete a file",
+    Diff: "Show change diffs",
+    Glob: "Find files by pattern",
+    Grep: "Search file contents",
+    LS: "List a directory",
+    Read: "Read a file",
+    StrReplace: "Replace text in a file",
+    Write: "Write a file",
+    script: "Run a TypeScript program",
+    search: "Search with a typed query",
+};
+function catalogTitle(tool) {
+    var _a;
+    if (tool.advertised === true) {
+        return (_a = tool.annotations) === null || _a === void 0 ? void 0 : _a.title;
+    }
+    return WELL_KNOWN_TOOL_TITLES[tool.name];
+}
+/**
+ * Sand connector identifiers scope the connector name by owner
+ * (`dashboard-team-<id>-Buildkite`, `dashboard-<Name>`, `user-<Name>`);
+ * the suffix is the human-meaningful name.
+ */
+const CONNECTOR_SCOPE_PREFIX = /^(?:dashboard-team-\d+-|dashboard-|user-)/;
+/**
+ * Where a tool comes from, for humans: the upstream connector/plugin name
+ * when the tool declares one (the reserved `__conn__` selector's values
+ * name it), the connection name otherwise. One aggregating connection
+ * (e.g. a tenant `plugins` endpoint) hosts tools from several connectors,
+ * and "plugins" tells an operator nothing — "Buildkite" does.
+ */
+function catalogSource(tool) {
+    var _a, _b;
+    if (tool.advertised !== true) {
+        return undefined;
+    }
+    const properties = tool.inputSchema.properties;
+    const first = (_b = (_a = properties === null || properties === void 0 ? void 0 : properties.__conn__) === null || _a === void 0 ? void 0 : _a.enum) === null || _b === void 0 ? void 0 : _b[0];
+    if (typeof first === "string" && first !== "") {
+        return first.replace(CONNECTOR_SCOPE_PREFIX, "");
+    }
+    return tool.connection;
+}
+export function catalogListEntry(tool) {
+    return {
+        name: tool.name,
+        title: catalogTitle(tool),
+        source: catalogSource(tool),
+    };
+}
+export function catalogDetailEntry(tool) {
+    return Object.assign(Object.assign({}, catalogListEntry(tool)), { description: tool.description, execution: tool.execution, needsApproval: tool.needsApproval, effect: tool.effect, inputSchema: tool.inputSchema, outputSchema: tool.outputSchema });
+}

package/dist/internal/tool-policy.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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";
+/** 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[];
+}
+/**
+ * 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 declare function resolveEffect(effect: ToolEffectDeclaration<never> | undefined, input: unknown): ToolEffect;
+/**
+ * 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 declare function classifyAnnotationsEffect(annotations: McpToolAnnotations | undefined): ToolEffect | 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 declare function directCallEffect(tool: Pick<DiscoveredTool, "advertised" | "annotations" | "definition">, input: unknown): ToolEffect | undefined;
+/** Decide what to do with one tool call. Pure; no I/O, no session state. */
+export declare function decideToolCall(facts: ToolCallFacts): ToolDecision;
+//# sourceMappingURL=tool-policy.d.ts.map

package/dist/internal/tool-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-policy.d.ts","sourceRoot":"","sources":["../../src/internal/tool-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,UAAU,EACV,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAGrB,6CAA6C;AAC7C,MAAM,MAAM,YAAY;AACtB,yBAAyB;AACvB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE;AACjB,uDAAuD;GACrD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE;AAC/C;;;;;GAKG;GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACrC;;;GAGG;GACD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IACjD;;;;;;OAMG;IACH,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;KAAE,CAAC;IAC7D,yEAAyE;IACzE,YAAY,CAAC,EAAE,iBAAiB,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,iBAAiB,CAAC,CAAC;IACzE;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAUD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,SAAS,EAChD,KAAK,EAAE,OAAO,GACb,UAAU,CAGZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,kBAAkB,GAAG,SAAS,GAC1C,UAAU,GAAG,SAAS,CAWxB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,GAAG,aAAa,GAAG,YAAY,CAAC,EACvE,KAAK,EAAE,OAAO,GACb,UAAU,GAAG,SAAS,CAKxB;AAkBD,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAiDjE"}

package/dist/internal/tool-policy.js

@@ -0,0 +1,138 @@
+/**
+ * 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 { forwardTimeArgument, missingTimeWindow, timeArgViolation } from "./as-of.js";
+/**
+ * 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, input) {
+    const declared = typeof effect === "function" ? effect(input) : 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) {
+    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, input) {
+    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) {
+    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) {
+    // 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, input) {
+    if (dryRunResult === undefined) {
+        return ACKNOWLEDGED;
+    }
+    if (typeof dryRunResult === "function") {
+        return dryRunResult(input);
+    }
+    return dryRunResult;
+}

package/dist/internal/tool-result.d.ts

@@ -0,0 +1,20 @@
+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 declare function normalizeToolResult(result: ToolExecuteResult | undefined): 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 declare function toolCallErrorMessage(result: unknown): string | undefined;
+//# sourceMappingURL=tool-result.d.ts.map

package/dist/internal/tool-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result.d.ts","sourceRoot":"","sources":["../../src/internal/tool-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,mBAAmB,CAY9F;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAiBxE"}