@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/http-control-plane-session.ts

@@ -1,110 +0,0 @@
-/**
- * Built-in HTTP channel admission for control-plane session starts.
- *
- * `agent-sdk run --prod` reaches the authenticated CP start route, which
- * delivers `agentsdk.session` to the built-in `http` channel of every v2
- * agent. The wake is `send(message, { dryRun, asOf })`; the session id,
- * when the caller resumed an explicit `ses_…`, arrives through the hosted
- * execution (never through this payload), so authored code cannot pick
- * one. {@link HttpChannelDefinition.onAdmit} runs against the mailbox
- * key and the original message before that send is captured.
- */
-
-import type { ChannelHandlerArgs, HttpChannelDefinition } from "../types.js";
-import { skipped, turnStarted } from "./channel-dispatch.js";
-import { attachHostedAdmissionAdapter } from "./hosted-admission-adapter.js";
-import {
-  AGENT_SDK_HTTP_CHANNEL_KIND,
-  AGENT_SDK_SESSION_EVENT_TYPE,
-} from "./hosted-catch-protocol.js";
-import { isRecord } from "./is-record.js";
-
-export type ControlPlaneSessionPayload = {
-  message: string;
-  dryRun?: boolean | undefined;
-  asOf?: string | undefined;
-};
-
-const PAYLOAD_KEYS = new Set(["message", "dryRun", "asOf"]);
-const MAX_MESSAGE_CHARS = 64 * 1024;
-
-export function parseControlPlaneSessionPayload(
-  payload: unknown,
-): { ok: true; data: ControlPlaneSessionPayload } | { ok: false; error: string } {
-  if (!isRecord(payload)) {
-    return { ok: false, error: "payload must be an object" };
-  }
-  if (Object.keys(payload).some(key => !PAYLOAD_KEYS.has(key))) {
-    return { ok: false, error: "payload carries an unsupported field" };
-  }
-  const message = typeof payload.message === "string" ? payload.message.trim() : "";
-  if (message.length === 0 || message.length > MAX_MESSAGE_CHARS) {
-    return { ok: false, error: "payload.message is required" };
-  }
-  if (payload.dryRun !== undefined && typeof payload.dryRun !== "boolean") {
-    return { ok: false, error: "payload.dryRun must be a boolean" };
-  }
-  if (
-    payload.asOf !== undefined &&
-    (typeof payload.asOf !== "string" || payload.asOf.trim().length === 0)
-  ) {
-    return { ok: false, error: "payload.asOf must be a non-empty string" };
-  }
-  return {
-    ok: true,
-    data: {
-      message,
-      dryRun: payload.dryRun === true ? true : undefined,
-      asOf: typeof payload.asOf === "string" ? payload.asOf.trim() : undefined,
-    },
-  };
-}
-
-export async function dispatchHttpControlPlaneSession(input: {
-  eventType: string;
-  payload: unknown;
-  args: ChannelHandlerArgs;
-  mailboxContinuationKey: string;
-  onMessage?: HttpChannelDefinition["onMessage"];
-  onAdmit?: HttpChannelDefinition["onAdmit"];
-}): Promise<Response> {
-  if (input.eventType !== AGENT_SDK_SESSION_EVENT_TYPE) {
-    return skipped("not a control-plane session");
-  }
-  const parsed = parseControlPlaneSessionPayload(input.payload);
-  if (!parsed.ok) {
-    return Response.json({ ok: false, error: parsed.error }, { status: 400 });
-  }
-  const original = parsed.data.message;
-  if (input.onAdmit !== undefined) {
-    await input.onAdmit({
-      message: original,
-      sessionKey: input.mailboxContinuationKey,
-      dryRun: parsed.data.dryRun,
-      asOf: parsed.data.asOf,
-      host: input.args.host,
-    });
-  }
-  const message =
-    input.onMessage === undefined ? original : await input.onMessage(original, { auth: null });
-  const session = await input.args.send(message, {
-    dryRun: parsed.data.dryRun,
-    asOf: parsed.data.asOf,
-  });
-  return turnStarted(session);
-}
-
-export function attachHttpControlPlaneAdmission(definition: HttpChannelDefinition): void {
-  attachHostedAdmissionAdapter(definition, {
-    kind: AGENT_SDK_HTTP_CHANNEL_KIND,
-    dispatch: ({ eventType, payload, args, mailboxContinuationKey }) =>
-      dispatchHttpControlPlaneSession({
-        eventType,
-        payload,
-        args,
-        mailboxContinuationKey: mailboxContinuationKey ?? "",
-        onMessage: definition.onMessage,
-        onAdmit: definition.onAdmit,
-      }),
-  });
-}

package/src/internal/ids.ts

@@ -1,39 +0,0 @@
-import { randomBytes } from "node:crypto";
-
-/** Fresh session id (`ses_<24 hex>` — a single safe path segment). */
-export function newSessionId(): string {
-  return `ses_${randomBytes(12).toString("hex")}`;
-}
-
-export function newContinuationKey(): string {
-  return randomBytes(16).toString("hex");
-}
-
-/**
- * Unique server-tool call id (a single safe path segment). Used when the
- * SDK omits `context.toolCallId` and for direct (deterministic) tool calls.
- */
-export function newToolCallId(toolName: string): string {
-  const safe = toolName.replace(/[^A-Za-z0-9_]/g, "_").slice(0, 32);
-  return `tool_${safe}_${randomBytes(8).toString("hex")}`;
-}
-
-/**
- * Wire form of a continuation token: the owning channel id, a colon, then
- * the channel-local key (mirrors how platform channels key sessions by
- * thread identity).
- */
-export function formatContinuationToken(channelId: string, key: string): string {
-  return `${channelId}:${key}`;
-}
-
-export function parseContinuationToken(token: string): { channelId: string; key: string } | null {
-  const separator = token.indexOf(":");
-  if (separator <= 0 || separator === token.length - 1) {
-    return null;
-  }
-  return {
-    channelId: token.slice(0, separator),
-    key: token.slice(separator + 1),
-  };
-}

package/src/internal/incoming-headers-to-fetch.ts

@@ -1,45 +0,0 @@
-import type { IncomingHttpHeaders } from "node:http";
-
-/**
- * Fetch / RFC 9110 header-name token. HTTP/2 pseudo-headers (`:method`,
- * `:path`, `:authority`, `:scheme`) fail this and throw in `Headers.append`.
- */
-const FETCH_HEADER_NAME = /^[A-Za-z0-9!#$%&'*+\-.^_`|~]+$/;
-
-function isFetchHeaderName(name: string): boolean {
-  return FETCH_HEADER_NAME.test(name);
-}
-
-/**
- * Copy Node incoming headers into a Fetch `Headers` object, dropping names
- * the Fetch API rejects (HTTP/2 pseudo-headers and any other illegal token).
- * Real headers are unchanged.
- */
-export function incomingHeadersToFetch(headers: IncomingHttpHeaders): Headers {
-  const out = new Headers();
-  for (const [key, value] of Object.entries(headers)) {
-    if (value === undefined || !isFetchHeaderName(key)) {
-      continue;
-    }
-    if (Array.isArray(value)) {
-      for (const item of value) {
-        out.append(key, item);
-      }
-    } else {
-      out.set(key, value);
-    }
-  }
-  return out;
-}
-
-function firstHeaderValue(value: string | string[] | undefined): string | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-  return Array.isArray(value) ? value[0] : value;
-}
-
-/** HTTP/1 `Host`, or HTTP/2 `:authority` when Host was not copied. */
-export function incomingRequestHost(headers: IncomingHttpHeaders, fallback = "127.0.0.1"): string {
-  return firstHeaderValue(headers.host) ?? firstHeaderValue(headers[":authority"]) ?? fallback;
-}

package/src/internal/init-interview.ts

@@ -1,360 +0,0 @@
-/**
- * Template `init.json`: questions `init` asks, and string replacements
- * it applies while copying the scaffold.
- */
-
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-import { createInterface } from "node:readline";
-import { parseCursorGithubRepoScope } from "../channels/github/cursor-account.js";
-import { describeError } from "./describe-error.js";
-import { isRecord } from "./is-record.js";
-
-export const TEMPLATE_INIT_FILE = "init.json";
-
-export interface TemplateQuestion {
-  id: string;
-  prompt: string;
-  hint?: string;
-  placeholder?: string;
-  default?: string;
-  choices?: readonly string[];
-  parse?: "owner-repo-list";
-}
-
-export interface TemplateReplace {
-  file: string;
-  find: string;
-  answer: string;
-  as?: "json-array" | "first";
-  template?: string;
-}
-
-export interface TemplateInitSpec {
-  questions: TemplateQuestion[];
-  replace: TemplateReplace[];
-}
-
-export function posixRel(rel: string): string {
-  return rel.replaceAll("\\", "/");
-}
-
-export function isTemplateMetaPath(rel: string): boolean {
-  const normalized = posixRel(rel);
-  const top = normalized.split("/")[0];
-  if (top === "overlays") {
-    return true;
-  }
-  return normalized === TEMPLATE_INIT_FILE || normalized.endsWith(`/${TEMPLATE_INIT_FILE}`);
-}
-
-export function templateFileHasReplacements(spec: TemplateInitSpec, rel: string): boolean {
-  const file = posixRel(rel);
-  return spec.replace.some(rule => posixRel(rule.file) === file);
-}
-
-export async function loadTemplateInitSpec(
-  templateDir: string,
-): Promise<TemplateInitSpec | undefined> {
-  try {
-    const text = await readFile(join(templateDir, TEMPLATE_INIT_FILE), "utf8");
-    return parseTemplateInitSpec(JSON.parse(text));
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      return undefined;
-    }
-    throw error;
-  }
-}
-
-export function parseTemplateInitSpec(value: unknown): TemplateInitSpec {
-  if (!isRecord(value) || !Array.isArray(value.questions)) {
-    throw new Error(`${TEMPLATE_INIT_FILE} must have a questions array`);
-  }
-  const questions = value.questions.map((item, index) => parseQuestion(item, index));
-  const replace = Array.isArray(value.replace)
-    ? value.replace.map((item, index) => parseReplace(item, index))
-    : [];
-  return { questions, replace };
-}
-
-export function parseInitVars(flags: readonly string[] | undefined): Record<string, string> {
-  const vars: Record<string, string> = {};
-  if (flags === undefined) {
-    return vars;
-  }
-  for (const flag of flags) {
-    const eq = flag.indexOf("=");
-    if (eq <= 0) {
-      throw new Error(`--var must be id=value (got ${JSON.stringify(flag)})`);
-    }
-    vars[flag.slice(0, eq)] = flag.slice(eq + 1);
-  }
-  return vars;
-}
-
-export type ParseAnswersResult =
-  | { ok: true; answers: Record<string, string> }
-  | { ok: false; error: string };
-
-export type RunTemplateInitResult =
-  | { ok: true; spec?: TemplateInitSpec; answers?: Record<string, string> }
-  | { ok: false; error: string };
-
-/** Load `init.json`, apply `--var`, and prompt on a TTY. */
-export async function runTemplateInit(input: {
-  templateDir: string;
-  vars?: readonly string[];
-  interactive: boolean;
-}): Promise<RunTemplateInitResult> {
-  try {
-    const spec = await loadTemplateInitSpec(input.templateDir);
-    if (spec === undefined) {
-      return { ok: true };
-    }
-    const collected = await collectTemplateAnswers({
-      spec,
-      vars: parseInitVars(input.vars),
-      interactive: input.interactive,
-    });
-    if (!collected.ok) {
-      return collected;
-    }
-    return { ok: true, spec, answers: collected.answers };
-  } catch (error) {
-    return { ok: false, error: describeError(error) };
-  }
-}
-
-export function parseTemplateAnswers(
-  spec: TemplateInitSpec,
-  raw: Record<string, string>,
-): ParseAnswersResult {
-  const answers: Record<string, string> = {};
-  for (const question of spec.questions) {
-    if (!(question.id in raw)) {
-      continue;
-    }
-    const parsed = parseQuestionValue(question, raw[question.id] ?? "");
-    if (!parsed.ok) {
-      return parsed;
-    }
-    answers[question.id] = parsed.value;
-  }
-  return { ok: true, answers };
-}
-
-export interface CollectAnswersInput {
-  spec: TemplateInitSpec;
-  vars?: Record<string, string>;
-  interactive: boolean;
-  ask?: (question: TemplateQuestion) => Promise<string>;
-  out?: (text: string) => void;
-}
-
-export async function collectTemplateAnswers(
-  input: CollectAnswersInput,
-): Promise<ParseAnswersResult> {
-  const vars = input.vars ?? {};
-  const answers: Record<string, string> = {};
-  const ask = input.ask ?? promptTemplateQuestion;
-  const out = input.out ?? (text => process.stdout.write(text));
-
-  for (const question of input.spec.questions) {
-    if (question.id in vars) {
-      const parsed = parseQuestionValue(question, vars[question.id] ?? "");
-      if (!parsed.ok) {
-        return parsed;
-      }
-      answers[question.id] = parsed.value;
-      continue;
-    }
-    if (!input.interactive) {
-      continue;
-    }
-    for (;;) {
-      const line = await ask(question);
-      const value = line.trim() === "" && question.default !== undefined ? question.default : line;
-      const parsed = parseQuestionValue(question, value);
-      if (parsed.ok) {
-        answers[question.id] = parsed.value;
-        break;
-      }
-      out(`${parsed.error}\n`);
-    }
-  }
-
-  return { ok: true, answers };
-}
-
-export function applyInitReplacements(
-  contents: string,
-  rel: string,
-  spec: TemplateInitSpec,
-  answers: Record<string, string>,
-): string {
-  const file = posixRel(rel);
-  let next = contents;
-  for (const rule of spec.replace) {
-    if (posixRel(rule.file) !== file) {
-      continue;
-    }
-    const value = formatReplaceValue(rule, answers);
-    if (value === undefined) {
-      continue;
-    }
-    if (!next.includes(rule.find)) {
-      throw new Error(`${TEMPLATE_INIT_FILE}: ${rule.find} not found in ${rel}`);
-    }
-    next = replaceLiteral(next, rule.find, value);
-  }
-  return next;
-}
-
-export async function promptTemplateQuestion(
-  question: TemplateQuestion,
-  options: {
-    input?: NodeJS.ReadableStream;
-    output?: NodeJS.WritableStream;
-  } = {},
-): Promise<string> {
-  const input = options.input ?? process.stdin;
-  const output = options.output ?? process.stdout;
-  const rl = createInterface({ input, output });
-  const suffix = promptSuffix(question);
-  try {
-    if (question.hint !== undefined) {
-      output.write(`  ${question.hint}\n`);
-    }
-    return await new Promise<string>(resolve => {
-      rl.question(`${question.prompt}${suffix} `, resolve);
-    });
-  } finally {
-    rl.close();
-  }
-}
-
-function replaceLiteral(haystack: string, find: string, value: string): string {
-  return haystack.replaceAll(find, () => value);
-}
-
-function promptSuffix(question: TemplateQuestion): string {
-  if (question.choices !== undefined && question.choices.length > 0) {
-    return ` [${question.choices.join("/")}]`;
-  }
-  if (question.default !== undefined) {
-    return ` [${question.default}]`;
-  }
-  if (question.placeholder !== undefined) {
-    return ` (${question.placeholder})`;
-  }
-  return "";
-}
-
-function parseQuestionValue(
-  question: TemplateQuestion,
-  raw: string,
-): { ok: true; value: string } | { ok: false; error: string } {
-  const trimmed = raw.trim();
-  if (trimmed === "") {
-    return { ok: false, error: `${question.id} is required.` };
-  }
-  if (question.choices !== undefined && question.choices.length > 0) {
-    if (!question.choices.includes(trimmed)) {
-      return {
-        ok: false,
-        error: `${question.id} must be one of ${question.choices.join(", ")}.`,
-      };
-    }
-    return { ok: true, value: trimmed };
-  }
-  if (question.parse === "owner-repo-list") {
-    try {
-      const scope = parseCursorGithubRepoScope(trimmed.split(",").map(repo => repo.trim()));
-      return { ok: true, value: scope.repos.join(", ") };
-    } catch (error) {
-      return { ok: false, error: describeError(error) };
-    }
-  }
-  return { ok: true, value: trimmed };
-}
-
-function formatReplaceValue(
-  rule: TemplateReplace,
-  answers: Record<string, string>,
-): string | undefined {
-  const raw = answers[rule.answer];
-  if (raw === undefined || raw === "") {
-    return undefined;
-  }
-  const parts = raw.split(",").map(part => part.trim());
-  let value = raw;
-  if (rule.as === "json-array") {
-    value = `[${parts.map(part => JSON.stringify(part)).join(", ")}]`;
-  } else if (rule.as === "first") {
-    const first = parts[0];
-    if (first === undefined || first === "") {
-      return undefined;
-    }
-    value = first;
-  }
-  if (rule.template !== undefined) {
-    return replaceLiteral(rule.template, "{{value}}", value);
-  }
-  return value;
-}
-
-function parseQuestion(value: unknown, index: number): TemplateQuestion {
-  if (!isRecord(value) || typeof value.id !== "string" || value.id === "") {
-    throw new Error(`${TEMPLATE_INIT_FILE} questions[${index}] needs an id`);
-  }
-  if (typeof value.prompt !== "string" || value.prompt === "") {
-    throw new Error(`${TEMPLATE_INIT_FILE} questions[${value.id}] needs a prompt`);
-  }
-  const question: TemplateQuestion = {
-    id: value.id,
-    prompt: value.prompt,
-  };
-  if (typeof value.hint === "string") {
-    question.hint = value.hint;
-  }
-  if (typeof value.placeholder === "string") {
-    question.placeholder = value.placeholder;
-  }
-  if (typeof value.default === "string") {
-    question.default = value.default;
-  }
-  if (Array.isArray(value.choices)) {
-    question.choices = value.choices.map(choice => String(choice));
-  }
-  if (value.parse === "owner-repo-list") {
-    question.parse = "owner-repo-list";
-  }
-  return question;
-}
-
-function parseReplace(value: unknown, index: number): TemplateReplace {
-  if (
-    !isRecord(value) ||
-    typeof value.file !== "string" ||
-    value.file === "" ||
-    typeof value.find !== "string" ||
-    value.find === "" ||
-    typeof value.answer !== "string" ||
-    value.answer === ""
-  ) {
-    throw new Error(`${TEMPLATE_INIT_FILE} replace[${index}] needs file, find, and answer`);
-  }
-  const rule: TemplateReplace = {
-    file: value.file,
-    find: value.find,
-    answer: value.answer,
-  };
-  if (value.as === "json-array" || value.as === "first") {
-    rule.as = value.as;
-  }
-  if (typeof value.template === "string") {
-    rule.template = value.template;
-  }
-  return rule;
-}