@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/brand.ts

@@ -1,28 +0,0 @@
-import type { BrandedDefinition, DefinitionKind } from "../types.js";
-
-export const DEFINITION_BRAND_FIELD = "__agentServe";
-
-export function brandDefinition<K extends DefinitionKind, T extends object>(
-  kind: K,
-  definition: T,
-): T & BrandedDefinition<K> {
-  return { ...definition, [DEFINITION_BRAND_FIELD]: kind } as T & BrandedDefinition<K>;
-}
-
-export function getDefinitionKind(value: unknown): DefinitionKind | undefined {
-  if (typeof value !== "object" || value === null) {
-    return undefined;
-  }
-  const kind = (value as Record<string, unknown>)[DEFINITION_BRAND_FIELD];
-  if (typeof kind !== "string") {
-    return undefined;
-  }
-  return kind as DefinitionKind;
-}
-
-export function isDefinitionOfKind<K extends DefinitionKind>(
-  value: unknown,
-  kind: K,
-): value is BrandedDefinition<K> {
-  return getDefinitionKind(value) === kind;
-}

package/src/internal/browser-origin-guard.ts

@@ -1,67 +0,0 @@
-/**
- * CSRF guard for mutating serve HTTP requests.
- *
- * Default serve trusts loopback (`localDevStrict`). CLI, webhooks, and the
- * control plane send no `Origin`. A page in the developer's browser is also
- * loopback, and a CORS-simple POST (e.g. text/plain) skips preflight, so any
- * site they visit can drive sessions, tools, and channel routes.
- *
- * `Origin` is the primary signal (forbidden header; `Origin: null` never
- * matches). No browser signals means a non-browser client. `Sec-Fetch-Site`
- * is the fallback when Origin is omitted.
- */
-
-const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
-
-export type BrowserOriginGuardOptions = {
-  /** Extra trusted `host[:port]` values (e.g. `--public-url` behind a Host-rewriting proxy). */
-  allowedOriginHosts?: ReadonlySet<string>;
-};
-
-export function browserOriginGuardOptionsForPublicUrl(
-  publicUrl: string | undefined,
-): BrowserOriginGuardOptions | undefined {
-  if (publicUrl === undefined) {
-    return undefined;
-  }
-  try {
-    return { allowedOriginHosts: new Set([new URL(publicUrl).host]) };
-  } catch {
-    return undefined;
-  }
-}
-
-export function isTrustedBrowserMutation(
-  request: Request,
-  options?: BrowserOriginGuardOptions,
-): boolean {
-  if (SAFE_METHODS.has(request.method.toUpperCase())) {
-    return true;
-  }
-  const origin = request.headers.get("origin");
-  if (origin !== null) {
-    return originHostMatches(origin, request.url, options?.allowedOriginHosts);
-  }
-  // Some Safari versions omit Origin on same-origin POST but still send Fetch Metadata.
-  const secFetchSite = request.headers.get("sec-fetch-site");
-  if (secFetchSite !== null) {
-    return secFetchSite === "same-origin" || secFetchSite === "none";
-  }
-  return true;
-}
-
-function originHostMatches(
-  origin: string,
-  requestUrl: string,
-  extraAllowedHosts: ReadonlySet<string> | undefined,
-): boolean {
-  let originUrl: URL;
-  let selfUrl: URL;
-  try {
-    originUrl = new URL(origin);
-    selfUrl = new URL(requestUrl);
-  } catch {
-    return false;
-  }
-  return originUrl.host === selfUrl.host || extraAllowedHosts?.has(originUrl.host) === true;
-}

package/src/internal/builtin-tools/artifacts.ts

@@ -1,62 +0,0 @@
-/**
- * The `tag_artifact` built-in tool, enabled by
- * `defineArtifacts({ agentTool: true })` rather than
- * `AgentConfig.builtinTools`: its input schema and description are
- * generated from the declared kinds registry.
- */
-
-import { z } from "zod";
-import { defineTool } from "../../tools.js";
-import type { ArtifactsConfig, ToolDefinition } from "../../types.js";
-
-export const TAG_ARTIFACT_TOOL_NAME = "tag_artifact";
-
-function kindVariant(name: string, schema: z.ZodType | undefined) {
-  return z.object({
-    kind: z.literal(name),
-    data:
-      schema ?? z.object({}).passthrough().describe("Freeform JSON object payload for this kind."),
-    title: z.string().optional().describe("Short human-readable label shown in artifact lists."),
-    key: z
-      .string()
-      .trim()
-      .min(1)
-      .optional()
-      .describe(
-        "Stable key, unique across kinds. Reusing it replaces that record instead of adding a new one.",
-      ),
-  });
-}
-
-export function tagArtifactTool(config: ArtifactsConfig): ToolDefinition {
-  const kinds = Object.entries(config.kinds ?? {});
-  const [first, ...rest] = kinds.map(([name, kind]) => kindVariant(name, kind.schema));
-  if (first === undefined) {
-    // Discovery already errors on agentTool without kinds.
-    throw new Error("tag_artifact requires at least one declared artifact kind");
-  }
-  const description = [
-    "Tag a finished output as an artifact. Artifacts persist across sessions and are listed for the people supervising this agent.",
-    "Kinds:",
-    ...kinds.map(([name, kind]) => `- ${name}: ${kind.description}`),
-  ].join("\n");
-  return defineTool({
-    description,
-    inputSchema: z.discriminatedUnion("kind", [first, ...rest]),
-    async execute(input, ctx) {
-      const record = await ctx.artifacts.tag({
-        kind: input.kind,
-        data: input.data,
-        title: input.title,
-        key: input.key,
-        source: "model",
-      });
-      return {
-        tagged: true,
-        id: record.id,
-        kind: record.kind,
-        key: record.key,
-      };
-    },
-  });
-}

package/src/internal/builtin-tools/index.ts

@@ -1,53 +0,0 @@
-/**
- * Built-in tools (`AgentConfig.builtinTools`): framework-provided
- * model-facing tools, materialized as ordinary server tools at discovery
- * time so turns, direct calls, `info`, and the playground treat them
- * exactly like authored tools.
- */
-
-import type {
-  ArtifactsConfig,
-  BuiltinToolsConfig,
-  DiscoveredTool,
-  ToolDefinition,
-} from "../../types.js";
-import { toolInputJsonSchema } from "../json-schema.js";
-import { TAG_ARTIFACT_TOOL_NAME, tagArtifactTool } from "./artifacts.js";
-import { reminderTools } from "./reminders.js";
-
-export { TAG_ARTIFACT_TOOL_NAME } from "./artifacts.js";
-
-/** Resolve the enabled built-in tools, in stable catalog order. */
-export function builtinTools(config: BuiltinToolsConfig | undefined): DiscoveredTool[] {
-  const tools: DiscoveredTool[] = [];
-  if (config?.reminders === true) {
-    tools.push(...toDiscovered(reminderTools));
-  }
-  return tools;
-}
-
-/**
- * The `tag_artifact` built-in, enabled by `defineArtifacts({ agentTool:
- * true })` (not `AgentConfig.builtinTools` — the tool is generated from
- * the kinds registry). Undefined without kinds: discovery already errors.
- */
-export function artifactBuiltinTool(
-  config: ArtifactsConfig | undefined,
-): DiscoveredTool | undefined {
-  if (config?.agentTool !== true || Object.keys(config.kinds ?? {}).length === 0) {
-    return undefined;
-  }
-  return toDiscovered({ [TAG_ARTIFACT_TOOL_NAME]: tagArtifactTool(config) })[0];
-}
-
-function toDiscovered(byName: Record<string, ToolDefinition>): DiscoveredTool[] {
-  return Object.entries(byName).map(([name, definition]) => ({
-    name,
-    description: definition.description,
-    inputSchema: toolInputJsonSchema(definition.inputSchema),
-    execution: "server",
-    needsApproval:
-      definition.needsApproval === true || typeof definition.needsApproval === "function",
-    definition,
-  }));
-}

package/src/internal/builtin-tools/reminders.ts

@@ -1,145 +0,0 @@
-/**
- * Built-in reminder tools (`builtinTools: { reminders: true }`): durable
- * wakes bound to the current conversation over `host.reminders`. The
- * framework's reminder fire prompt tells the model to call
- * `reminders_cancel` by name, so these tool names must not change.
- */
-
-import { z } from "zod";
-import { defineTool } from "../../tools.js";
-import type { ReminderHostApi, ReminderInfo, ToolContext, ToolDefinition } from "../../types.js";
-import { parseDuration } from "../duration.js";
-
-/** Floor for model-armed recurring wakes: each fire spends a model turn. */
-const MIN_EVERY_MS = 60_000;
-
-function api(ctx: ToolContext): ReminderHostApi {
-  const reminders = ctx.host.reminders;
-  if (reminders === undefined) {
-    throw new Error("Reminders are disabled on this host.");
-  }
-  return reminders;
-}
-
-function conversation(ctx: ToolContext): {
-  channelId: string;
-  continuationToken: string;
-} {
-  const token = ctx.session.continuationKey;
-  if (token == null) {
-    throw new Error(
-      "This session is not bound to a followable conversation; reminders cannot wake it.",
-    );
-  }
-  return { channelId: ctx.session.channelId, continuationToken: token };
-}
-
-/** Reminders visible to this conversation (tokens are channel-local). */
-async function listMine(
-  ctx: ToolContext,
-  status?: ReminderInfo["status"],
-): Promise<ReminderInfo[]> {
-  const conv = conversation(ctx);
-  const all = await api(ctx).list({
-    status,
-    continuationToken: conv.continuationToken,
-  });
-  return all.filter(r => r.channelId === conv.channelId);
-}
-
-function toResult(r: ReminderInfo) {
-  return {
-    reminderId: r.id,
-    purpose: r.purpose,
-    schedule: `${r.scheduleKind} ${r.scheduleValue}`,
-    nextFireAt: r.nextFireAt,
-    until: r.untilPrompt,
-  };
-}
-
-const create = defineTool({
-  description:
-    "Set a reminder for yourself in this conversation. When it fires, your prompt returns here as a follow-up turn. Use it to re-check state that needs time to settle. One-shot (delay) or recurring (every).",
-  inputSchema: z.object({
-    prompt: z
-      .string()
-      .min(1)
-      .describe(
-        "What to do when you wake. Keep it generic ('re-check CI and report only if the status changed') and re-read live state on wake instead of replaying stale details.",
-      ),
-    delay: z
-      .string()
-      .optional()
-      .describe(
-        'One-shot: wake once after this duration, e.g. "20m" or "2h". Provide exactly one of delay or every.',
-      ),
-    every: z
-      .string()
-      .optional()
-      .describe(
-        'Recurring: wake at this interval, e.g. "30m", until cancelled or the stop condition is met. Provide exactly one of delay or every.',
-      ),
-    purpose: z
-      .string()
-      .min(1)
-      .max(64)
-      .optional()
-      .describe('Short slug naming the reminder, e.g. "ci_recheck". Defaults to "follow_up".'),
-    until: z
-      .string()
-      .optional()
-      .describe(
-        "Recurring only: plain-language stop condition you will honor by calling reminders_cancel, e.g. 'Cancel once CI is green or the PR is merged.'",
-      ),
-  }),
-  async execute(input, ctx) {
-    if ((input.delay !== undefined) === (input.every !== undefined)) {
-      throw new Error("Provide exactly one of delay or every.");
-    }
-    if (input.every !== undefined && parseDuration(input.every) < MIN_EVERY_MS) {
-      throw new Error('Recurring reminders must use every >= "1m".');
-    }
-    const conv = conversation(ctx);
-    const reminder = await api(ctx).create({
-      purpose: input.purpose ?? "follow_up",
-      channelId: conv.channelId,
-      continuationToken: conv.continuationToken,
-      prompt: input.prompt,
-      delay: input.delay,
-      every: input.every,
-      until: input.until,
-    });
-    return toResult(reminder);
-  },
-});
-
-const list = defineTool({
-  description:
-    "List the armed reminders bound to this conversation. Check before arming duplicates.",
-  inputSchema: z.object({}),
-  async execute(_input, ctx) {
-    return { reminders: (await listMine(ctx, "armed")).map(toResult) };
-  },
-});
-
-const cancel = defineTool({
-  description:
-    "Cancel one of this conversation's reminders by id, the moment its stop condition is met or it is no longer needed.",
-  inputSchema: z.object({
-    id: z.string().min(1).describe("Reminder id from reminders_create or reminders_list."),
-  }),
-  async execute(input, ctx) {
-    const mine = (await listMine(ctx)).find(r => r.id === input.id);
-    if (mine === undefined) {
-      throw new Error(`No reminder "${input.id}" in this conversation.`);
-    }
-    const cancelled = await api(ctx).cancel(input.id);
-    return { reminderId: input.id, status: cancelled?.status ?? "cancelled" };
-  },
-});
-
-export const reminderTools: Record<string, ToolDefinition> = {
-  reminders_create: create,
-  reminders_list: list,
-  reminders_cancel: cancel,
-};

package/src/internal/channel-dispatch.ts

@@ -1,129 +0,0 @@
-import type { ChannelHandlerArgs, ChannelSession, SendMessageFn } from "../types.js";
-import { isDeferredChannelSession } from "./deferred-channel-session.js";
-
-/**
- * What a webhook dispatch decided. Hosted admission reads it off the
- * Response without parsing the body.
- */
-export type DispatchOutcome = "skip" | "send" | "task";
-
-const outcomeByResponse = new WeakMap<Response, DispatchOutcome>();
-
-export function tagOutcome(response: Response, outcome: DispatchOutcome): Response {
-  outcomeByResponse.set(response, outcome);
-  return response;
-}
-
-export function dispatchOutcome(response: Response): DispatchOutcome | undefined {
-  return outcomeByResponse.get(response);
-}
-
-export function skipped(reason: string, extra: Record<string, unknown> = {}): Response {
-  return tagOutcome(Response.json({ ok: true, skipped: true, reason, ...extra }), "skip");
-}
-
-/** 202 for a turn whose send completes after the response flushes. */
-export function acknowledgeTurn(): Response {
-  return tagOutcome(
-    Response.json({ ok: true, dispatched: true, mode: "turn" }, { status: 202 }),
-    "send",
-  );
-}
-
-/**
- * Report the session a send returned. Hosted admission returns a deferred
- * session: it captured the send and the control plane allocates the real
- * session after acknowledgement, so there is nothing to report yet.
- */
-export function turnStarted(session: ChannelSession): Response {
-  if (isDeferredChannelSession(session)) {
-    return acknowledgeTurn();
-  }
-  return tagOutcome(
-    Response.json({
-      ok: true,
-      sessionId: session.id,
-      isNew: session.isNew,
-      continuationToken: session.continuationToken,
-    }),
-    "send",
-  );
-}
-
-interface TaskDispatch {
-  task: (args: {
-    send: SendMessageFn;
-    waitUntil: (promise: Promise<unknown>) => void;
-  }) => void | Promise<void>;
-}
-
-export function isTaskDispatch<D extends object>(
-  dispatch: D,
-): dispatch is Extract<D, TaskDispatch> {
-  return "task" in dispatch;
-}
-
-/**
- * The task runs after the ack with the per-delivery send, so hosted
- * admission can capture task-initiated sends; a startup-captured send
- * bypasses capture.
- */
-export function acknowledgeTask(
-  args: ChannelHandlerArgs,
-  kind: string,
-  dispatch: TaskDispatch,
-  extra: Record<string, unknown>,
-): Response {
-  scheduleAfterAck(args, kind, () => dispatch.task({ send: args.send, waitUntil: args.waitUntil }));
-  return tagOutcome(
-    Response.json({ ok: true, dispatched: true, mode: "task", ...extra }, { status: 202 }),
-    "task",
-  );
-}
-
-const PROPAGATE_BACKGROUND_ERRORS = Symbol("propagateBackgroundErrors");
-
-type PropagatingHandlerArgs = ChannelHandlerArgs & {
-  [PROPAGATE_BACKGROUND_ERRORS]?: true;
-};
-
-/**
- * Hosted admission opts in so a failed background task rejects `waitUntil`
- * (a retryable 503 for the control plane) instead of being logged locally.
- */
-export function withPropagatingBackgroundErrors(args: ChannelHandlerArgs): ChannelHandlerArgs {
-  return Object.assign(args, { [PROPAGATE_BACKGROUND_ERRORS]: true as const });
-}
-
-/**
- * Run `work` after the current turn so the 202 flushes first, inside the
- * delivery's `waitUntil` window. Locally a failure is logged and swallowed;
- * see {@link withPropagatingBackgroundErrors} for hosted admission.
- */
-export function scheduleAfterAck(
-  args: ChannelHandlerArgs,
-  kind: string,
-  work: () => void | Promise<void>,
-): void {
-  args.waitUntil(
-    new Promise<void>((resolve, reject) => {
-      setImmediate(() => {
-        Promise.resolve()
-          .then(work)
-          .then(
-            () => resolve(),
-            (error: unknown) => {
-              if ((args as PropagatingHandlerArgs)[PROPAGATE_BACKGROUND_ERRORS] === true) {
-                reject(error);
-                return;
-              }
-              const detail =
-                error instanceof Error ? (error.stack ?? error.message) : String(error);
-              console.error(`[${kind}] background dispatch failed: ${detail}`);
-              resolve();
-            },
-          );
-      });
-    }),
-  );
-}

package/src/internal/channel-route-dispatch.ts

@@ -1,58 +0,0 @@
-import type { ChannelHandlerArgs, ChannelRoute } from "../types.js";
-import { jsonResponse } from "./http-channel.js";
-import { validateToolInput } from "./json-schema.js";
-
-/**
- * Run one authored channel route: validate the declared Zod query / body
- * schemas onto `handlerArgs`, then call the handler. Shared by the local
- * router mount and hosted catch replay so a caught request meets exactly
- * the same schema gate as a direct one.
- */
-export async function invokeChannelRoute(input: {
-  route: ChannelRoute;
-  request: Request;
-  handlerArgs: ChannelHandlerArgs;
-}): Promise<Response> {
-  const { route, handlerArgs } = input;
-  let request = input.request;
-
-  if (route.querySchema !== undefined) {
-    const rawQuery = Object.fromEntries(new URL(request.url).searchParams.entries());
-    const queryValidation = validateToolInput(route.querySchema, rawQuery);
-    if (!queryValidation.ok) {
-      return jsonResponse({ error: queryValidation.message }, { status: 400 });
-    }
-    handlerArgs.query = queryValidation.value;
-  }
-
-  if (route.bodySchema !== undefined) {
-    // Buffer once so handlers that need the raw body (e.g. GitHub HMAC) can
-    // still read `request.text()` / `request.json()`.
-    let bodyText: string;
-    try {
-      bodyText = await request.text();
-    } catch {
-      return jsonResponse({ error: "Failed to read request body" }, { status: 400 });
-    }
-    let rawBody: unknown;
-    try {
-      rawBody = bodyText === "" ? {} : JSON.parse(bodyText);
-    } catch {
-      return jsonResponse({ error: "Request body must be valid JSON" }, { status: 400 });
-    }
-    const bodyValidation = validateToolInput(route.bodySchema, rawBody);
-    if (!bodyValidation.ok) {
-      return jsonResponse({ error: bodyValidation.message }, { status: 400 });
-    }
-    handlerArgs.body = bodyValidation.value;
-    request = new Request(request.url, {
-      method: request.method,
-      headers: request.headers,
-      body: bodyText === "" ? undefined : bodyText,
-      // node: undici / fetch may require duplex for streamed bodies;
-      // a string body does not.
-    });
-  }
-
-  return route.handler(request, handlerArgs);
-}

package/src/internal/channel-state.ts

@@ -1,83 +0,0 @@
-import { isDeepStrictEqual } from "node:util";
-import type { JsonValue } from "../types.js";
-
-type JsonRecord = Record<string, JsonValue>;
-
-function asRecord(value: JsonValue | undefined): JsonRecord | undefined {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return undefined;
-  }
-  return value as JsonRecord;
-}
-
-/**
- * Shallow-merge a wake patch into durable channel state. Null / undefined
- * patch values leave the existing key alone so sticky fields survive.
- */
-export function mergeChannelStateSkipNull(
-  current: JsonValue | undefined,
-  patch: JsonValue | undefined,
-): JsonValue | undefined {
-  if (patch === undefined) {
-    return current;
-  }
-  const currentRecord = asRecord(current);
-  const patchRecord = asRecord(patch);
-  if (currentRecord === undefined || patchRecord === undefined) {
-    return structuredClone(patch);
-  }
-  const merged = { ...currentRecord };
-  for (const [key, value] of Object.entries(patchRecord)) {
-    if (value !== null && value !== undefined) {
-      merged[key] = value;
-    }
-  }
-  return merged;
-}
-
-/**
- * Apply handler mutations made against a turn snapshot without reverting
- * unchanged fields refreshed by a later delivery. At a changed path, objects
- * merge recursively, arrays and scalars replace, and deletions win.
- */
-export function mergeChannelStateMutation(args: {
-  current: JsonValue | undefined;
-  before: JsonValue;
-  after: JsonValue;
-}): JsonValue | undefined {
-  const { current, before, after } = args;
-  if (isDeepStrictEqual(before, after)) {
-    return current;
-  }
-  const currentRecord = asRecord(current);
-  const beforeRecord = asRecord(before);
-  const afterRecord = asRecord(after);
-  if (currentRecord === undefined || beforeRecord === undefined || afterRecord === undefined) {
-    return structuredClone(after);
-  }
-
-  const merged = structuredClone(currentRecord);
-  const keys = new Set([...Object.keys(beforeRecord), ...Object.keys(afterRecord)]);
-  for (const key of keys) {
-    const hadBefore = Object.hasOwn(beforeRecord, key);
-    const hasAfter = Object.hasOwn(afterRecord, key);
-    if (hadBefore && hasAfter && isDeepStrictEqual(beforeRecord[key], afterRecord[key])) {
-      continue;
-    }
-    if (!hasAfter) {
-      delete merged[key];
-      continue;
-    }
-    const currentValue = merged[key];
-    const afterValue = afterRecord[key]!;
-    merged[key] =
-      hadBefore || (asRecord(currentValue) !== undefined && asRecord(afterValue) !== undefined)
-        ? (mergeChannelStateMutation({
-            current: currentValue,
-            before: hadBefore ? beforeRecord[key]! : {},
-            after: afterValue,
-          }) as JsonValue)
-        : structuredClone(afterValue);
-  }
-  return merged;
-}