@cursor/bdk 0.2.1

package/dist/hooks.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `defineHook` — authored at `agent/hooks/<slug>.ts`.
+ *
+ * Hooks subscribe to the session event stream and run side effects after
+ * each event is durably recorded (audit logging, metrics, persisting
+ * transcripts to your own database). Handlers are observe-only.
+ *
+ * ```ts
+ * import { defineHook } from "@cursor/bdk/hooks";
+ *
+ * export default defineHook({
+ *   events: {
+ *     async "turn.completed"(event, ctx) {
+ *       const prior = await ctx.host.kv.get("last-result");
+ *       const notes = await ctx.host.files.read("notes.md");
+ *       console.log("turn done", ctx.session.id, event.data.usage, prior, notes);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+import type { HookConfig, HookDefinition } from "./types.js";
+export type { HookConfig, HookContext, HookDefinition, HookHandler } from "./types.js";
+export declare function defineHook(config: HookConfig): HookDefinition;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7D,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEvF,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAE7D"}

package/dist/hooks.js

@@ -0,0 +1,25 @@
+/**
+ * `defineHook` — authored at `agent/hooks/<slug>.ts`.
+ *
+ * Hooks subscribe to the session event stream and run side effects after
+ * each event is durably recorded (audit logging, metrics, persisting
+ * transcripts to your own database). Handlers are observe-only.
+ *
+ * ```ts
+ * import { defineHook } from "@cursor/bdk/hooks";
+ *
+ * export default defineHook({
+ *   events: {
+ *     async "turn.completed"(event, ctx) {
+ *       const prior = await ctx.host.kv.get("last-result");
+ *       const notes = await ctx.host.files.read("notes.md");
+ *       console.log("turn done", ctx.session.id, event.data.usage, prior, notes);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+import { brandDefinition } from "./internal/brand.js";
+export function defineHook(config) {
+    return brandDefinition("hook", config);
+}

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @cursor/bdk
+ *
+ * Filesystem-first framework for Cursor agents: define an agent as markdown
+ * and TypeScript files under an `agent/` directory, and serve it over
+ * channels with the Cursor SDK as the execution harness.
+ *
+ * ```ts
+ * import { serve } from "@cursor/bdk";
+ *
+ * const handle = await serve(".", { port: 3000 });
+ * console.log(`agent listening on ${handle.url}`);
+ * ```
+ */
+import { type LoadAgentProjectOptions } from "./internal/discovery.js";
+import type { AgentConfig, AgentConfigDefinition, AgentProject, AgentServeHandle, InstructionsConfig, InstructionsDefinition, ServeOptions } from "./types.js";
+export { defineArtifacts } from "./artifacts.js";
+export { allowAll, bearerAuth, DELETE, defineChannel, GET, localDev, localDevStrict, loopbackGitHubDev, loopbackOnly, PATCH, POST, PUT, publicEndpoint, } from "./channels.js";
+export { defineConnection } from "./connections.js";
+export { cursorPlugin, defineExtension, disable, disableArtifacts, disableChannel, disableConnection, disableHook, disableInstructions, disableSchedule, disableSkill, disableSubagent, disableTool, } from "./extensions.js";
+export type { DirEntry, EditQuery, EditResult, FileInfo, FileSystem, GlobOptions, GrepQuery, GrepResult, ListOptions, SearchQuery, SearchResult, } from "./filesystem.js";
+export { DeleteNotSupportedError, EditError, emptyFs, FILE_SYSTEM_SCAN_LIMIT, FileNotFoundError, hostFs, InvalidGrepPatternError, isFileNotFoundError, NoMountError, overlayFs, PathError, ReadOnlyMountError, strReplaceOnFileSystem, tempFs, unionFs, WriteFailedError, } from "./filesystem.js";
+export { defineHook } from "./hooks.js";
+export { InvalidAsOfError, VacuousTimeArgsError } from "./internal/as-of.js";
+export type { ContinuationBuiltin, ContinuationClaim, ContinuationIdentity, ContinuationSelector, ConversationType, MailboxContinuation, ParsedContinuation, } from "./internal/continuation-identity.js";
+export { mintClaim } from "./internal/continuation-identity.js";
+export type { LoadAgentProjectOptions } from "./internal/discovery.js";
+export { formatDiagnostics, hasErrorDiagnostics, isAgentProjectDir, loadAgentProject, loadAgentProjects, projectInfo, resolveAgentMounts, } from "./internal/discovery.js";
+export { nearestNeighborMissHint } from "./internal/filesystem/nearest.js";
+export type { AgentServeGitHubTriggerEvent, AgentServeGitHubTriggerTarget, AgentServeOriginTriggerEvent, AgentServeOriginTriggerTarget, AgentServeTriggerEvent, AgentServeTriggerResult, AgentServeTriggerTargetResult, } from "./internal/handleAgentServeTrigger.js";
+export { collectGitHubTriggerTargets, collectOriginTriggerTargets, handleAgentServeTrigger, } from "./internal/handleAgentServeTrigger.js";
+export { MCP_CHANNEL_ID, MCP_ENDPOINT_PATH, mcpEndpointToolNames, TOOL_MCP_ENDPOINT_PATH, } from "./internal/mcp-endpoint.js";
+export { REMINDER_ARGS_MAX_BYTES, ReminderValidationError, rejectAnonymousReminderHandlers, UnknownReminderError, } from "./internal/reminder-runner.js";
+export type { AgentMount } from "./internal/server.js";
+export { SessionBusyError, ToolInputError, ToolNotDirectlyCallableError, UnknownChannelError, UnknownSessionError, UnknownToolError, } from "./internal/session-engine.js";
+export type { MemoryBackend, TurnMemoryRecord } from "./memory.js";
+export { agentStoreMemoryBackend, fileMemoryBackend, memoryHook } from "./memory.js";
+export type { OtelConfig, OtelDefinition, OtelExporterConfig } from "./otel.js";
+export type { PromptTag } from "./prompt.js";
+export { prompt } from "./prompt.js";
+export type { ReminderBusyPolicy, ReminderCreateInput, ReminderDefinition, ReminderFireContext, ReminderFireResult, ReminderFollowupOptions, ReminderHandlerConfig, ReminderHostApi, ReminderInfo, ReminderReschedule, ReminderScheduleKind, ReminderStatus, ReminderTarget, ReminderUntilContext, } from "./reminders.js";
+export { defineReminder } from "./reminders.js";
+export { defineSchedule } from "./schedules.js";
+export { defineSkill } from "./skills.js";
+export { defineTool } from "./tools.js";
+export type * from "./types.js";
+export { cursorAccountServersHasMixedWildcard, DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, HttpSessionAdmitError, isCursorAccountTransport, isPeerConnectionTransport, isSymbolicConnectionTransport, isToolEffect, MAX_RUNNING_TURNS_LIMIT, normalizeConnectionEffects, normalizeConnectionTools, normalizeCursorAccountServers, supportsKvCas, } from "./types.js";
+/**
+ * Runtime config for an agent — authored at `agent/agent.ts` (the root
+ * agent) or `agent/subagents/<id>/agent.ts` (a subagent).
+ */
+export declare function defineAgent(config: AgentConfig): AgentConfigDefinition;
+/**
+ * Programmatic instructions — authored at `agent/instructions.ts` when the
+ * system prompt needs to be generated rather than written as markdown.
+ */
+export declare function defineInstructions(config: InstructionsConfig): InstructionsDefinition;
+/**
+ * Discover and serve one or more agents over HTTP.
+ *
+ * Defaults to multi-agent layout: each agent is mounted under `/<slug>/v1/*`
+ * and `/<slug>/playground`, with an index at `/`.
+ *
+ * - Given a directory that is itself an agent project, mounts it under its
+ *   directory name as the slug.
+ * - Given a directory whose immediate children are agent projects, mounts
+ *   each under its directory name.
+ * - Pass `mode: "single"` (or an {@link AgentProject}) for the unslugged
+ *   `/v1/*` surface.
+ *
+ * The built-in session channel lives under `/v1/session*`, custom channels
+ * under `/v1/channels/<id>`, plus `/v1/health` and `/v1/info`. Schedules run
+ * on their cron cadence unless dev mode or `schedules: false` disables them.
+ */
+export declare function serve(projectOrDir: string | AgentProject, options?: ServeOptions & {
+    discovery?: LoadAgentProjectOptions;
+    /**
+     * Mount layout. Defaults to `"multi"` (slugged routes + index).
+     * `"single"` serves one agent at `/v1/*` with an empty slug. Ignored when
+     * an {@link AgentProject} is passed (always single-mount).
+     */
+    mode?: "single" | "multi";
+}): Promise<AgentServeHandle>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,109 @@
+/**
+ * @cursor/bdk
+ *
+ * Filesystem-first framework for Cursor agents: define an agent as markdown
+ * and TypeScript files under an `agent/` directory, and serve it over
+ * channels with the Cursor SDK as the execution harness.
+ *
+ * ```ts
+ * import { serve } from "@cursor/bdk";
+ *
+ * const handle = await serve(".", { port: 3000 });
+ * console.log(`agent listening on ${handle.url}`);
+ * ```
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { registerAuthoredModuleLoaders } from "./internal/authored-loaders.js";
+import { brandDefinition } from "./internal/brand.js";
+import { setDevMode } from "./internal/dev-mode.js";
+import { resolveAgentMounts } from "./internal/discovery.js";
+import { startServer } from "./internal/server.js";
+export { defineArtifacts } from "./artifacts.js";
+// Authoring helpers (also available on their focused subpath exports).
+export { allowAll, bearerAuth, DELETE, defineChannel, GET, localDev, localDevStrict, loopbackGitHubDev, loopbackOnly, PATCH, POST, PUT, publicEndpoint, } from "./channels.js";
+export { defineConnection } from "./connections.js";
+export { cursorPlugin, defineExtension, disable, disableArtifacts, disableChannel, disableConnection, disableHook, disableInstructions, disableSchedule, disableSkill, disableSubagent, disableTool, } from "./extensions.js";
+export { DeleteNotSupportedError, EditError, emptyFs, FILE_SYSTEM_SCAN_LIMIT, FileNotFoundError, hostFs, InvalidGrepPatternError, isFileNotFoundError, NoMountError, overlayFs, PathError, ReadOnlyMountError, strReplaceOnFileSystem, tempFs, unionFs, WriteFailedError, } from "./filesystem.js";
+export { defineHook } from "./hooks.js";
+export { InvalidAsOfError, VacuousTimeArgsError } from "./internal/as-of.js";
+export { mintClaim } from "./internal/continuation-identity.js";
+export { formatDiagnostics, hasErrorDiagnostics, isAgentProjectDir, loadAgentProject, loadAgentProjects, projectInfo, resolveAgentMounts, } from "./internal/discovery.js";
+export { nearestNeighborMissHint } from "./internal/filesystem/nearest.js";
+export { collectGitHubTriggerTargets, collectOriginTriggerTargets, handleAgentServeTrigger, } from "./internal/handleAgentServeTrigger.js";
+export { MCP_CHANNEL_ID, MCP_ENDPOINT_PATH, mcpEndpointToolNames, TOOL_MCP_ENDPOINT_PATH, } from "./internal/mcp-endpoint.js";
+export { REMINDER_ARGS_MAX_BYTES, ReminderValidationError, rejectAnonymousReminderHandlers, UnknownReminderError, } from "./internal/reminder-runner.js";
+export { SessionBusyError, ToolInputError, ToolNotDirectlyCallableError, UnknownChannelError, UnknownSessionError, UnknownToolError, } from "./internal/session-engine.js";
+export { agentStoreMemoryBackend, fileMemoryBackend, memoryHook } from "./memory.js";
+export { prompt } from "./prompt.js";
+export { defineReminder } from "./reminders.js";
+export { defineSchedule } from "./schedules.js";
+export { defineSkill } from "./skills.js";
+export { defineTool } from "./tools.js";
+export { cursorAccountServersHasMixedWildcard, DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, HttpSessionAdmitError, isCursorAccountTransport, isPeerConnectionTransport, isSymbolicConnectionTransport, isToolEffect, MAX_RUNNING_TURNS_LIMIT, normalizeConnectionEffects, normalizeConnectionTools, normalizeCursorAccountServers, supportsKvCas, } from "./types.js";
+/**
+ * Runtime config for an agent — authored at `agent/agent.ts` (the root
+ * agent) or `agent/subagents/<id>/agent.ts` (a subagent).
+ */
+export function defineAgent(config) {
+    return brandDefinition("agent", config);
+}
+/**
+ * Programmatic instructions — authored at `agent/instructions.ts` when the
+ * system prompt needs to be generated rather than written as markdown.
+ */
+export function defineInstructions(config) {
+    return brandDefinition("instructions", config);
+}
+/**
+ * Discover and serve one or more agents over HTTP.
+ *
+ * Defaults to multi-agent layout: each agent is mounted under `/<slug>/v1/*`
+ * and `/<slug>/playground`, with an index at `/`.
+ *
+ * - Given a directory that is itself an agent project, mounts it under its
+ *   directory name as the slug.
+ * - Given a directory whose immediate children are agent projects, mounts
+ *   each under its directory name.
+ * - Pass `mode: "single"` (or an {@link AgentProject}) for the unslugged
+ *   `/v1/*` surface.
+ *
+ * The built-in session channel lives under `/v1/session*`, custom channels
+ * under `/v1/channels/<id>`, plus `/v1/health` and `/v1/info`. Schedules run
+ * on their cron cadence unless dev mode or `schedules: false` disables them.
+ */
+export function serve(projectOrDir_1) {
+    return __awaiter(this, arguments, void 0, function* (projectOrDir, options = {}) {
+        const { discovery, mode } = options, serveOptions = __rest(options, ["discovery", "mode"]);
+        // Programmatic embedders get the same authored-TypeScript loading as the
+        // CLI (idempotent; the bin registers earlier, source runs are a no-op).
+        yield registerAuthoredModuleLoaders();
+        // Set before discovery so channel factories (constructed at import time) can
+        // relax dev-only defaults — e.g. the GitHub channel accepting unsigned
+        // loopback-forwarded deliveries. No-op outside dev.
+        setDevMode(serveOptions.dev === true);
+        if (typeof projectOrDir !== "string") {
+            return startServer([{ slug: "", project: projectOrDir }], serveOptions);
+        }
+        const mounts = yield resolveAgentMounts(projectOrDir, Object.assign(Object.assign({}, discovery), (mode === undefined ? {} : { mode })));
+        return startServer(mounts, serveOptions);
+    });
+}

package/dist/internal/advertise-tools.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Advertised connection tools (`defineConnection({ advertiseTools: true })`).
+ *
+ * The session engine calls {@link resolveAdvertisedTools} while building
+ * every local turn: for each advertising connection it lists the server's
+ * tools and synthesizes a named 1:1 passthrough server tool per entry —
+ * the server's own names, descriptions, and live schemas — merged into the
+ * authored `agent/tools/` catalog. Because it runs at turn-build time it
+ * covers every way a turn starts (dispatcher sends, follow-ups, reminder
+ * fires that call the engine directly) and survives process restarts,
+ * since nothing is parked in memory between turns.
+ *
+ * Connections with per-session `auth` are listed and called through a
+ * one-off client carrying that session's headers (the registry's cached
+ * per-name client would leak one session's identity into another);
+ * auth-less connections go through the shared `host.mcp` registry, which
+ * also covers serve-resolved transports (Cursor account bridges, peers).
+ *
+ * Advertised names follow the Cursor-account MCP bridge
+ * (`packages/agent-serve/src/internal/cursor/account-mcp.ts`): slug
+ * `[^a-zA-Z0-9_-]` to `_`, collision suffixes `_2` / `_3`, and call the
+ * original advertised name. That is the same mapping `packages/agent`
+ * `normalizeMcpToolName` uses for IDE/Sand MCP tools. A listing failure
+ * still fails the turn rather than running it with a silently shrunken
+ * toolset.
+ *
+ * `defineConnection({ effects })` filters the listing before names are
+ * assigned: only tools whose MCP annotations classify as an intended
+ * effect are advertised. Unclassified tools are omitted, not guessed.
+ * `defineConnection({ tools: [...] })` keeps only the named tools.
+ * `disallowedTools` drops names. A name filter that matches nothing on
+ * the server fails the turn.
+ * Tools whose `annotations.title` is `do-not-call` are dropped as well
+ * (vendor host-UI / MCP Apps helpers that still carry `readOnlyHint`).
+ */
+import { type DiscoveredConnection, type DiscoveredTool, type HostMcpCallResult, type HostMcpToolInfo, type ResolvedAgent, type SessionInfo } from "../types.js";
+import type { HostMcpOneOff } from "./mcp-host.js";
+/**
+ * What the resolver needs from the host MCP registry: the shared cached
+ * clients for auth-less connections, and one-off clients (per-session
+ * headers, never cached) for auth'd ones. `McpHost` implements this.
+ */
+export interface AdvertiseHostMcp {
+    listTools(connectionName: string): Promise<HostMcpToolInfo[]>;
+    callTool(connectionName: string, toolName: string, args?: Record<string, unknown>): Promise<HostMcpCallResult>;
+    oneOff(connection: DiscoveredConnection): HostMcpOneOff;
+}
+/**
+ * Model-facing advertised names after {@link sanitizeMcpToolName} — the
+ * same MCP-client shape the Cursor-account bridge documents
+ * (`^[a-zA-Z0-9_-]{1,128}$`). Authored `agent/tools/` filenames stay on
+ * discovery's stricter `NAME_PATTERN` (must start alphanumeric).
+ */
+export declare const ADVERTISED_TOOL_NAME_PATTERN: RegExp;
+/** How one advertising connection is listed and called. */
+export interface AdvertisedToolSource {
+    listTools(): Promise<HostMcpToolInfo[]>;
+    callTool(toolName: string, args: Record<string, unknown>): Promise<HostMcpCallResult>;
+}
+/**
+ * Resolve the advertised tools for one session. Returns `[]` when no
+ * connection advertises; throws (failing the turn) when a listing fails
+ * or a definition is invalid.
+ */
+export declare function resolveAdvertisedTools(args: {
+    agent: ResolvedAgent;
+    session: SessionInfo;
+    hostMcp: AdvertiseHostMcp;
+    /**
+     * When set, a connection whose source or listing fails is reported here
+     * and skipped instead of throwing. Turns keep the throwing default (a
+     * turn must fail closed); the inspection catalog passes this so one
+     * broken connector does not hide every other tool.
+     */
+    onConnectionError?: (connection: string, error: unknown) => void;
+    /** Test seam; defaults to {@link sourceForConnection}. */
+    sourceFor?: (connection: DiscoveredConnection, session: SessionInfo, hostMcp: AdvertiseHostMcp) => Promise<AdvertisedToolSource>;
+}): Promise<DiscoveredTool[]>;
+/**
+ * The production source for one advertising connection: the shared
+ * `host.mcp` registry client for auth-less connections (which also covers
+ * serve-resolved transports — Cursor account bridges, peers), or a
+ * registry one-off with the session's headers substituted when the
+ * connection has per-session `auth`. The auth callback is evaluated once
+ * per turn, here; the one-off opens a fresh client per operation so one
+ * session's identity can never serve another's call.
+ */
+export declare function sourceForConnection(connection: DiscoveredConnection, session: SessionInfo, hostMcp: AdvertiseHostMcp): Promise<AdvertisedToolSource>;
+/**
+ * Render an MCP call result for the model: text parts joined, non-text
+ * parts noted by type, `isError` surfaced as a thrown error so the turn
+ * records a tool error instead of error-shaped prose.
+ */
+export declare function formatMcpToolResult(connectionName: string, toolName: string, result: HostMcpCallResult): string;
+//# sourceMappingURL=advertise-tools.d.ts.map

package/dist/internal/advertise-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advertise-tools.d.ts","sourceRoot":"","sources":["../../src/internal/advertise-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EAGpB,KAAK,aAAa,EAClB,KAAK,WAAW,EAGjB,MAAM,aAAa,CAAC;AAGrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAC9D,QAAQ,CACN,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC9B,MAAM,CAAC,UAAU,EAAE,oBAAoB,GAAG,aAAa,CAAC;CACzD;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAiC,CAAC;AAO7E,2DAA2D;AAC3D,MAAM,WAAW,oBAAoB;IACnC,SAAS,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACvF;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,WAAW,CAAC;IACrB,OAAO,EAAE,gBAAgB,CAAC;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACjE,0DAA0D;IAC1D,SAAS,CAAC,EAAE,CACV,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,oBAAoB,CAAC,CAAC;CACpC,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAmF5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,oBAAoB,CAAC,CAqB/B;AAkHD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,iBAAiB,GACxB,MAAM,CAgBR"}

package/dist/internal/advertise-tools.js

@@ -0,0 +1,265 @@
+/**
+ * Advertised connection tools (`defineConnection({ advertiseTools: true })`).
+ *
+ * The session engine calls {@link resolveAdvertisedTools} while building
+ * every local turn: for each advertising connection it lists the server's
+ * tools and synthesizes a named 1:1 passthrough server tool per entry —
+ * the server's own names, descriptions, and live schemas — merged into the
+ * authored `agent/tools/` catalog. Because it runs at turn-build time it
+ * covers every way a turn starts (dispatcher sends, follow-ups, reminder
+ * fires that call the engine directly) and survives process restarts,
+ * since nothing is parked in memory between turns.
+ *
+ * Connections with per-session `auth` are listed and called through a
+ * one-off client carrying that session's headers (the registry's cached
+ * per-name client would leak one session's identity into another);
+ * auth-less connections go through the shared `host.mcp` registry, which
+ * also covers serve-resolved transports (Cursor account bridges, peers).
+ *
+ * Advertised names follow the Cursor-account MCP bridge
+ * (`packages/agent-serve/src/internal/cursor/account-mcp.ts`): slug
+ * `[^a-zA-Z0-9_-]` to `_`, collision suffixes `_2` / `_3`, and call the
+ * original advertised name. That is the same mapping `packages/agent`
+ * `normalizeMcpToolName` uses for IDE/Sand MCP tools. A listing failure
+ * still fails the turn rather than running it with a silently shrunken
+ * toolset.
+ *
+ * `defineConnection({ effects })` filters the listing before names are
+ * assigned: only tools whose MCP annotations classify as an intended
+ * effect are advertised. Unclassified tools are omitted, not guessed.
+ * `defineConnection({ tools: [...] })` keeps only the named tools.
+ * `disallowedTools` drops names. A name filter that matches nothing on
+ * the server fails the turn.
+ * Tools whose `annotations.title` is `do-not-call` are dropped as well
+ * (vendor host-UI / MCP Apps helpers that still carry `readOnlyHint`).
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { connectionAllowsTool, } from "../types.js";
+import { brandDefinition } from "./brand.js";
+import { describeError } from "./describe-error.js";
+import { sanitizeMcpToolName, suffixMcpToolName } from "./sanitize-mcp-tool-name.js";
+import { classifyAnnotationsEffect } from "./tool-policy.js";
+/**
+ * Model-facing advertised names after {@link sanitizeMcpToolName} — the
+ * same MCP-client shape the Cursor-account bridge documents
+ * (`^[a-zA-Z0-9_-]{1,128}$`). Authored `agent/tools/` filenames stay on
+ * discovery's stricter `NAME_PATTERN` (must start alphanumeric).
+ */
+export const ADVERTISED_TOOL_NAME_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+const ANY_OBJECT_SCHEMA = {
+    type: "object",
+    additionalProperties: true,
+};
+/**
+ * Resolve the advertised tools for one session. Returns `[]` when no
+ * connection advertises; throws (failing the turn) when a listing fails
+ * or a definition is invalid.
+ */
+export function resolveAdvertisedTools(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const advertising = args.agent.connections.filter(connection => connection.advertiseTools === true);
+        if (advertising.length === 0) {
+            return [];
+        }
+        const sourceFor = (_a = args.sourceFor) !== null && _a !== void 0 ? _a : sourceForConnection;
+        const listings = yield Promise.all(advertising.map((connection) => __awaiter(this, void 0, void 0, function* () {
+            try {
+                const source = yield sourceFor(connection, args.session, args.hostMcp);
+                const listed = yield source.listTools();
+                return {
+                    connection,
+                    ok: true,
+                    source,
+                    listed: listed.filter(info => connectionAllowsTool(connection, info.name)),
+                };
+            }
+            catch (error) {
+                return { connection, ok: false, error };
+            }
+        })));
+        const claimed = new Set(args.agent.tools.map(tool => tool.name));
+        const resolved = [];
+        for (const listing of listings) {
+            const { connection } = listing;
+            if (!listing.ok) {
+                if (args.onConnectionError !== undefined) {
+                    args.onConnectionError(connection.name, listing.error);
+                    continue;
+                }
+                if (connection.optional === true) {
+                    continue;
+                }
+                throw new Error(`Failed to list tools on advertised connection "${connection.name}": ${describeError(listing.error)}`, { cause: listing.error });
+            }
+            const { source, listed } = listing;
+            if ((connection.tools !== undefined || connection.disallowedTools !== undefined) &&
+                listed.length === 0) {
+                const error = new Error(`Advertised connection "${connection.name}" tool filter matched no tools on the server.`);
+                if (args.onConnectionError !== undefined) {
+                    args.onConnectionError(connection.name, error);
+                    continue;
+                }
+                if (connection.optional === true) {
+                    continue;
+                }
+                throw error;
+            }
+            const intended = listed.filter(info => !isDoNotCallTool(info.annotations) &&
+                matchesIntendedEffects(info.annotations, connection.effects));
+            const exposed = exposeListedTools(intended, claimed);
+            for (const { info, exposedName } of exposed) {
+                resolved.push(toDiscoveredTool(connection, info, exposedName, source));
+                claimed.add(exposedName);
+            }
+        }
+        return resolved;
+    });
+}
+/**
+ * The production source for one advertising connection: the shared
+ * `host.mcp` registry client for auth-less connections (which also covers
+ * serve-resolved transports — Cursor account bridges, peers), or a
+ * registry one-off with the session's headers substituted when the
+ * connection has per-session `auth`. The auth callback is evaluated once
+ * per turn, here; the one-off opens a fresh client per operation so one
+ * session's identity can never serve another's call.
+ */
+export function sourceForConnection(connection, session, hostMcp) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (connection.auth === undefined) {
+            return {
+                listTools: () => hostMcp.listTools(connection.name),
+                callTool: (toolName, callArgs) => hostMcp.callTool(connection.name, toolName, callArgs),
+            };
+        }
+        const transport = connection.transport;
+        if (!("url" in transport)) {
+            // Discovery rejects auth on non-URL transports; guard for callers that
+            // bypass discovery (hand-built projects).
+            throw new Error(`Connection "${connection.name}" has per-session auth but no URL transport.`);
+        }
+        const evaluated = yield connection.auth(session);
+        return hostMcp.oneOff(Object.assign(Object.assign({}, connection), { transport: Object.assign(Object.assign({}, transport), { headers: Object.assign(Object.assign({}, transport.headers), evaluated.headers) }) }));
+    });
+}
+/**
+ * Same catalog rule as the Cursor-account bridge: slug illegal characters,
+ * then `_2` / `_3` … for colliders (including authored tools already in
+ * `claimed`). Suffix assignment is stable for a colliding group: sort by
+ * original advertised name, independent of `listTools` order.
+ */
+function exposeListedTools(listed, claimed) {
+    const byBase = new Map();
+    for (const info of listed) {
+        const base = sanitizeMcpToolName(info.name);
+        const group = byBase.get(base);
+        if (group === undefined) {
+            byBase.set(base, [info]);
+        }
+        else {
+            group.push(info);
+        }
+    }
+    const taken = new Set(claimed);
+    const exposedNameByInfo = new Map();
+    const sortedBases = [...byBase.keys()].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+    for (const base of sortedBases) {
+        const group = byBase.get(base);
+        group.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+        group.forEach((info, index) => {
+            let suffixIndex = index;
+            let exposedName = suffixMcpToolName(base, suffixIndex);
+            while (taken.has(exposedName)) {
+                suffixIndex++;
+                exposedName = suffixMcpToolName(base, suffixIndex);
+            }
+            taken.add(exposedName);
+            exposedNameByInfo.set(info, exposedName);
+        });
+    }
+    return listed.map(info => ({
+        info,
+        exposedName: exposedNameByInfo.get(info),
+    }));
+}
+/**
+ * Vendors (Datadog MCP Apps) stamp host-UI-only helpers with this title.
+ * They still look like reads (`readOnlyHint: true`), so the effects
+ * filter would keep them. The model and agsh should not see them; the
+ * raw MCP listing stays intact for the host.
+ */
+const DO_NOT_CALL_TITLE = "do-not-call";
+function isDoNotCallTool(annotations) {
+    var _a;
+    return ((_a = annotations === null || annotations === void 0 ? void 0 : annotations.title) === null || _a === void 0 ? void 0 : _a.trim()) === DO_NOT_CALL_TITLE;
+}
+function matchesIntendedEffects(annotations, effects) {
+    if (effects === undefined) {
+        return true;
+    }
+    const effect = classifyAnnotationsEffect(annotations);
+    return effect !== undefined && effects.includes(effect);
+}
+function toDiscoveredTool(connection, info, exposedName, source) {
+    var _a;
+    const description = info.description === undefined || info.description.trim() === ""
+        ? `${info.name} — MCP tool on the "${connection.name}" connection, forwarded 1:1.`
+        : info.description;
+    const inputSchema = (_a = info.inputSchema) !== null && _a !== void 0 ? _a : ANY_OBJECT_SCHEMA;
+    const outputSchema = info.outputSchema;
+    const effect = connection.effects === undefined ? undefined : classifyAnnotationsEffect(info.annotations);
+    const definition = brandDefinition("tool", {
+        description,
+        inputSchema,
+        outputSchema,
+        effect,
+        execute: (input) => __awaiter(this, void 0, void 0, function* () {
+            return formatMcpToolResult(connection.name, info.name, yield source.callTool(info.name, input !== null && input !== void 0 ? input : {}));
+        }),
+    });
+    return {
+        name: exposedName,
+        description,
+        inputSchema,
+        outputSchema,
+        execution: "server",
+        needsApproval: false,
+        effect,
+        // The server's own annotations ride along (bounded at listing time), so
+        // the harness listing carries them and effect classification can read
+        // them. Absent stays absent — the fail-closed state.
+        annotations: info.annotations,
+        advertised: true,
+        connection: connection.name,
+        definition,
+    };
+}
+/**
+ * Render an MCP call result for the model: text parts joined, non-text
+ * parts noted by type, `isError` surfaced as a thrown error so the turn
+ * records a tool error instead of error-shaped prose.
+ */
+export function formatMcpToolResult(connectionName, toolName, result) {
+    const parts = result.content.map(item => item.type === "text" && typeof item.text === "string"
+        ? item.text
+        : `[${item.type} content omitted]`);
+    const text = parts.join("\n").trim();
+    if (result.isError === true) {
+        throw new Error(text === "" ? `${connectionName} tool ${toolName} failed` : text);
+    }
+    if (text !== "") {
+        return text;
+    }
+    return result.structuredContent !== undefined
+        ? JSON.stringify(result.structuredContent, null, 2)
+        : "(empty result)";
+}