@cursor/bdk 0.2.3 → 0.2.5

package/src/extensions/cursor-grokbot-agents/tools/interrupt.ts

@@ -1,17 +0,0 @@
-import { z } from "zod";
-import { defineTool } from "../../../tools.js";
-import type { ToolDefinition } from "../../../types.js";
-import { interrupt as interruptAgent } from "../lib/conversation.js";
-import { agentName } from "../lib/inputs.js";
-
-const interrupt: ToolDefinition = defineTool({
-  description:
-    "Stop what a Grok Bot agent you asked is doing right now. It keeps its conversation; ask it again to continue.",
-  effect: "write",
-  inputSchema: z.object({ agent: agentName }),
-  async execute(input, ctx) {
-    return interruptAgent(ctx, { agent: input.agent });
-  },
-});
-
-export default interrupt;

package/src/extensions/cursor-grokbot-agents/tools/list.ts

@@ -1,26 +0,0 @@
-import { z } from "zod";
-import { defineTool } from "../../../tools.js";
-import type { ToolDefinition } from "../../../types.js";
-import extension from "../extension.js";
-import { listContacts } from "../lib/contacts.js";
-
-const list: ToolDefinition = defineTool({
-  description:
-    "List the Grok Bot agents you can talk to: the ones configured for this agent, with what each is for, and the ones you have already asked, most recent first.",
-  effect: "read",
-  inputSchema: z.object({}),
-  async execute(_input, ctx) {
-    const contacts = await listContacts(ctx);
-    return {
-      configured: extension.config.agents ?? [],
-      contacted: contacts.map(contact => ({
-        name: contact.name,
-        sessionId: contact.sessionId,
-        firstContactAt: contact.firstContactAt,
-        lastContactAt: contact.lastContactAt,
-      })),
-    };
-  },
-});
-
-export default list;

package/src/extensions/improve/extension.ts

@@ -1,69 +0,0 @@
-/**
- * Self-improvement as an extension. An agent's behaviour is source in a
- * repository, so changing how it behaves is a change to that source: a
- * one-off Cursor cloud agent does the coding on a branch and opens a pull
- * request, the agent that mounted this writes the brief and reports the
- * pull request. Durable behavior changes only after review, merge, and
- * deployment. A cloud-runtime turn may edit its ephemeral checkout while
- * preparing the pull request.
- *
- * ```ts
- * // agent/extensions/improve.ts
- * import improve from "@cursor/bdk/extensions/improve";
- *
- * export default improve({
- *   repo: "https://github.com/acme/agents",
- *   path: "agents/concierge",
- * });
- * ```
- *
- * Contributes the `<namespace>__yourself` skill; mount it as `improve` so
- * the skill reads `improve__yourself`. The coding goes through the
- * cursor-cloud-agents extension, so mount that too, with `repo` among its
- * `cloud.repos`. An agent whose own turns run on a cloud VM with the
- * repository checked out needs no second mount: the skill has it work in
- * that checkout.
- */
-
-import { z } from "zod";
-import { defineExtension } from "../../extensions.js";
-import type { Extension } from "../../types.js";
-
-export interface ImproveOptions {
-  /** Repository that holds the agent's source. One of the cloud agents mount's `cloud.repos`. */
-  repo: string;
-  /** The agent's directory in the repository, as `agent-sdk deploy --path` names it. */
-  path: string;
-  /** Ref the deployment tracks: branches start there and pull requests target it. Defaults to `main`. */
-  ref?: string;
-  /** What a coding agent must know about this tree beyond the Agent SDK layout, one line each. */
-  notes?: string[];
-  /** Who deploys a merged change and when it is live. Defaults to "It takes effect at the next deploy." */
-  deploy?: string;
-}
-
-/** {@link ImproveOptions} with defaults applied. */
-export interface ImproveConfig extends ImproveOptions {
-  ref: string;
-  notes: string[];
-  deploy: string;
-}
-
-const line = z.string().trim().min(1);
-
-const improve: Extension<ImproveConfig, ImproveOptions> = defineExtension({
-  root: import.meta.dirname,
-  description:
-    "Propose changes to your own source through a branch and pull request; durable behavior changes after review and deployment.",
-  config: z.object({
-    repo: z.string().url(),
-    path: z
-      .string()
-      .regex(/^[^\s/]+(\/[^\s/]+)*$/, "Expected a repository-relative path like agents/concierge"),
-    ref: line.default("main"),
-    notes: z.array(line).default([]),
-    deploy: line.default("It takes effect at the next deploy."),
-  }),
-});
-
-export default improve;

package/src/extensions/improve/skills/yourself.ts

@@ -1,50 +0,0 @@
-import { defineSkill } from "../../../skills.js";
-import type { SkillDefinition } from "../../../types.js";
-import extension from "../extension.js";
-
-const { repo, path, ref, notes, deploy } = extension.config;
-
-const treeNotes =
-  notes.length === 0
-    ? ""
-    : `\nAbout this tree in particular; copy these into the brief verbatim:\n\n${notes.map(note => `- ${note}`).join("\n")}\n`;
-
-const yourself: SkillDefinition = defineSkill({
-  description:
-    "Change your own source (instructions, skills, tools, channels, connections, model, deployment) through a one-off Cursor cloud agent and a pull request. Use whenever the ask is about how you yourself behave, including adding or editing a skill, so the change lands in the repository instead of the tree you happen to be running from.",
-  markdown: `# Improve yourself
-
-You are the Agent SDK agent at \`${path}\` in ${repo}, deployed from \`${ref}\`. A change to how you behave is a change to that source, and it goes through the repository like any other change: a branch, a pull request, review, a deploy. Nothing about it is special except that people describe it in the second person.
-
-## What changes where
-
-Under \`${path}/agent/\`:
-
-- \`instructions.md\` is the always-on system prompt: identity, tool-choice rules, the output contract.
-- \`skills/<name>.md\` is a procedure loaded on demand; a \`<name>/SKILL.md\` directory carries sibling files. The \`description\` frontmatter is the routing rule the model sees.
-- \`tools/<name>.ts\` is typed, executable behaviour: anything that must be right every time.
-- \`channels/\`, \`mcp-connections/\`, and \`host-connections/\` are the surfaces and connectors.
-- \`agent.ts\` is the model, its parameters, and the runtime.
-- \`extensions/<ns>.ts\` mounts an extension. This skill arrives through one.
-${treeNotes}
-## The change is made on a clean checkout
-
-Durable source changes happen on a branch from a clean checkout of ${repo} at \`${ref}\`, never by mutating a deployed local-runtime copy. When your own turn runs on a cloud VM with that repository checked out, its ephemeral tree is the checkout: branch there. Otherwise hand the coding to a one-off Cursor cloud agent through the cloud agents extension, with \`launch\` under its mount namespace, \`repo\` set to ${repo}, and \`starting_ref\` to \`${ref}\`. One agent per change; steer it with \`reply\` instead of launching another.
-
-## The brief
-
-Whoever makes the change works from the same brief. For a cloud agent it is the whole handoff, because it cannot see this conversation:
-
-- Who and why. A change to the source of the Agent SDK agent at \`${path}\`, asked for by the person in front of you: the change in their words, and what you know about why they want it.
-- Where. Repository ${repo}, ref \`${ref}\`, directory \`${path}\`, the layout above, and the files you expect to change.
-- How. Follow the repository's own conventions (its \`AGENTS.md\` files and rules along the paths touched). Keep the diff to the change. Run the checks the repository defines for \`${path}\`. Open a pull request against \`${ref}\`; never merge it.
-- Report. The pull request URL, what changed, what was verified and how, and anything left unverified.
-
-## Report
-
-If you launched a cloud agent, give the person its URL with the full id, read its report with \`dump\` (\`get\` for status), and read the pull request before repeating its claims. Report the pull request, not that you delegated.
-
-A merged pull request changes nothing by itself. ${deploy} Never say you have already changed yourself. Editing your own source is still an edit: do it when asked, and stop at the pull request. Deploying is a separate authorization.`,
-});
-
-export default yourself;

package/src/extensions/jev/extension.ts

@@ -1,95 +0,0 @@
-/**
- * Jev decisions as an extension. Mount it and the agent can ask Jev for
- * typed boolean, choice, and score answers, then call `decide` from your
- * own channel hooks and tools before they start a turn or write.
- *
- * ```ts
- * // agent/extensions/jev.ts
- * import jev from "@cursor/bdk/extensions/jev";
- *
- * export default jev();
- * ```
- *
- * Contributes `<namespace>__evaluate` plus the `questions` and
- * `gated-write` skills (the namespace is the mount filename). Auth is
- * `TYPESAFE_API_KEY`. The default model is `jev-latest`. Custom tools
- * import `decide`, `above`, and `needsHuman` from this same module. Set
- * `harnessTools` or `skills` to false when the agent should not see those
- * contributions.
- */
-
-import { z } from "zod";
-import { defineExtension } from "../../extensions.js";
-import type { Extension } from "../../types.js";
-import { DEFAULT_EVALUATION_MODEL } from "./lib/evaluate.js";
-
-/** Mount options; every field is optional. */
-export interface JevOptions {
-  /** TypeSafe API key. Defaults to `TYPESAFE_API_KEY`. */
-  apiKey?: string;
-  /** TypeSafe model id. Defaults to `jev-latest`. */
-  model?: string;
-  /** Mount the namespaced `evaluate` harness tool. Defaults to true. */
-  harnessTools?: boolean;
-  /** Mount the `questions` and `gated-write` skills. Defaults to true. */
-  skills?: boolean;
-}
-
-/** {@link JevOptions} with defaults applied. */
-export interface JevConfig {
-  apiKey?: string;
-  model: string;
-  harnessTools: boolean;
-  skills: boolean;
-}
-
-const config: z.ZodType<JevConfig, z.ZodTypeDef, JevOptions | undefined> = z
-  .object({
-    apiKey: z.string().min(1).optional(),
-    model: z.string().min(1).optional(),
-    harnessTools: z.boolean().default(true),
-    skills: z.boolean().default(true),
-  })
-  .default({})
-  .transform(options => ({
-    apiKey: options.apiKey,
-    model: options.model ?? DEFAULT_EVALUATION_MODEL,
-    harnessTools: options.harnessTools,
-    skills: options.skills,
-  }));
-
-const jev: Extension<JevConfig, JevOptions | undefined> = defineExtension({
-  root: import.meta.dirname,
-  description: "Ask Jev for typed choice, score, and boolean answers.",
-  config,
-  contributions: options => ({
-    tools: options.harnessTools,
-    skills: options.skills,
-  }),
-});
-
-export type {
-  AnswersFor,
-  BooleanAnswer,
-  BooleanQuestion,
-  ChoiceAnswer,
-  ChoiceQuestion,
-  EvaluateArgs,
-  EvaluateResult,
-  EvaluationAnswer,
-  EvaluationQuestion,
-  EvaluationState,
-  QuestionMap,
-  ScoreAnswer,
-  ScoreQuestion,
-} from "./lib/evaluate.js";
-export {
-  above,
-  DEFAULT_EVALUATION_MODEL,
-  DEFAULT_HUMAN_THRESHOLD,
-  decide,
-  evaluate,
-  needsHuman,
-} from "./lib/evaluate.js";
-
-export default jev;

package/src/extensions/jev/lib/evaluate.ts

@@ -1,266 +0,0 @@
-/**
- * System One decisions for Agent SDK host code.
- *
- * Chat models write. {@link evaluate} asks Jev for typed choice / score /
- * boolean answers over shared state. Call it from a project tool, a
- * router, or other host code after mounting `@cursor/bdk/extensions/jev`.
- * Do not set Jev as the `defineAgent` turn model.
- *
- * ```ts
- * import { evaluate, decide, above, needsHuman } from "@cursor/bdk/extensions/jev";
- *
- * const { answers } = await evaluate({
- *   state: draft,
- *   questions: {
- *     route: {
- *       type: "choice",
- *       instructions: "Which queue should handle this?",
- *       criteria: {
- *         billing: "charges, invoices, refunds",
- *         shipping: "delivery",
- *         technical: "bugs and outages",
- *       },
- *     },
- *     post: {
- *       type: "boolean",
- *       instructions: "Is this safe to post publicly?",
- *     },
- *   },
- * });
- *
- * if (needsHuman(answers.route) || !above(answers.post, 0.85)) {
- *   return { action: "review" };
- * }
- * ```
- *
- * Auth is `TYPESAFE_API_KEY`. `model` is a TypeSafe id (`jev-latest` by
- * default).
- */
-
-/** TypeSafe model used when {@link EvaluateArgs.model} is omitted. */
-export const DEFAULT_EVALUATION_MODEL = "jev-latest";
-
-/** Default bar for {@link needsHuman} when the caller does not pass one. */
-export const DEFAULT_HUMAN_THRESHOLD = 0.7;
-
-const DEFAULT_BASE_URL = "https://api.typesafe.ai/v1";
-
-export type EvaluationState = string | Record<string, unknown> | readonly unknown[];
-
-export type BooleanQuestion = {
-  type: "boolean";
-  instructions: string;
-};
-
-export type ChoiceCriterion = string | readonly string[] | { includes: readonly string[] } | null;
-
-export type ChoiceQuestion<
-  C extends Record<string, ChoiceCriterion> = Record<string, ChoiceCriterion>,
-> = {
-  type: "choice";
-  instructions: string;
-  criteria: C;
-};
-
-export type ScoreQuestion = {
-  type: "score";
-  instructions: string;
-  criteria: readonly string[];
-};
-
-export type EvaluationQuestion = BooleanQuestion | ChoiceQuestion | ScoreQuestion;
-
-export type QuestionMap = Record<string, EvaluationQuestion>;
-
-export type BooleanAnswer = {
-  type: "boolean";
-  probability: number;
-};
-
-export type ChoiceAnswer<C extends Record<string, unknown> = Record<string, unknown>> = {
-  type: "choice";
-  choice: keyof C & string;
-  probabilities: { [K in keyof C]: number };
-};
-
-export type ScoreAnswer = {
-  type: "score";
-  score: number;
-  probabilities: Record<string, number>;
-};
-
-export type EvaluationAnswer = BooleanAnswer | ChoiceAnswer | ScoreAnswer;
-
-export type AnswerFor<Q> = Q extends BooleanQuestion
-  ? BooleanAnswer
-  : Q extends ChoiceQuestion<infer C>
-    ? ChoiceAnswer<C>
-    : Q extends ScoreQuestion
-      ? ScoreAnswer
-      : never;
-
-export type AnswersFor<Q extends QuestionMap> = {
-  [K in keyof Q]: AnswerFor<Q[K]>;
-};
-
-export type EvaluateResult<Q extends QuestionMap = QuestionMap> = {
-  answers: AnswersFor<Q>;
-};
-
-export type EvaluateArgs<Q extends QuestionMap = QuestionMap> = {
-  model?: string;
-  state: EvaluationState;
-  questions: Q;
-  apiKey?: string;
-  baseUrl?: string;
-  fetch?: typeof globalThis.fetch;
-};
-
-type WireQuestion =
-  | { type: "noul"; instructions: string }
-  | {
-      type: "choice";
-      instructions: string;
-      criteria: ChoiceQuestion["criteria"];
-    }
-  | { type: "score"; instructions: string; criteria: readonly string[] };
-
-function resolveApiKey(explicit: string | undefined): string {
-  const key = (explicit ?? process.env.TYPESAFE_API_KEY)?.trim();
-  if (key === undefined || key === "") {
-    throw new Error("evaluate requires TYPESAFE_API_KEY");
-  }
-  return key;
-}
-
-function toWireQuestion(question: EvaluationQuestion): WireQuestion {
-  if (question.type === "boolean") {
-    return { type: "noul", instructions: question.instructions };
-  }
-  return question;
-}
-
-function asRecord(value: unknown, label: string): Record<string, unknown> {
-  if (value === null || typeof value !== "object") {
-    throw new Error(`evaluate ${label}`);
-  }
-  return value as Record<string, unknown>;
-}
-
-function decodeAnswer(question: EvaluationQuestion, raw: unknown): EvaluationAnswer {
-  const value = asRecord(raw, "answer is missing");
-  if (question.type === "boolean") {
-    if (typeof value.noul !== "number") {
-      throw new Error("evaluate noul is not a number");
-    }
-    return { type: "boolean", probability: value.noul };
-  }
-  if (question.type === "choice") {
-    if (typeof value.choice !== "string") {
-      throw new Error("evaluate choice is not a string");
-    }
-    return {
-      type: "choice",
-      choice: value.choice,
-      probabilities: asRecord(
-        value.probabilities,
-        "choice probabilities are missing",
-      ) as ChoiceAnswer["probabilities"],
-    };
-  }
-  if (typeof value.score !== "number") {
-    throw new Error("evaluate score is not a number");
-  }
-  return {
-    type: "score",
-    score: value.score,
-    probabilities: asRecord(
-      value.probabilities,
-      "score probabilities are missing",
-    ) as ScoreAnswer["probabilities"],
-  };
-}
-
-async function postSystemOne(args: {
-  url: string;
-  apiKey: string;
-  body: {
-    model: string;
-    state: EvaluationState;
-    questions: Record<string, WireQuestion>;
-  };
-  fetch: typeof globalThis.fetch;
-}): Promise<Record<string, unknown>> {
-  const response = await args.fetch(args.url, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${args.apiKey}`,
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(args.body),
-  });
-  const text = await response.text();
-  let parsed: unknown;
-  try {
-    parsed = text.length === 0 ? {} : JSON.parse(text);
-  } catch {
-    throw new Error(`evaluate returned non-JSON (${response.status})`);
-  }
-  if (!response.ok) {
-    throw new Error(`evaluate failed (${response.status}): ${text.slice(0, 240)}`);
-  }
-  return asRecord(
-    asRecord(parsed, "response is not an object").answers,
-    "response is missing answers",
-  );
-}
-
-/** Ask Jev for typed answers over one state. */
-export async function evaluate<const Q extends QuestionMap>(
-  args: EvaluateArgs<Q>,
-): Promise<EvaluateResult<Q>> {
-  const questions: Record<string, WireQuestion> = {};
-  for (const [id, question] of Object.entries(args.questions)) {
-    questions[id] = toWireQuestion(question);
-  }
-  const raw = await postSystemOne({
-    url: `${(args.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/u, "")}/systemone`,
-    apiKey: resolveApiKey(args.apiKey),
-    fetch: args.fetch ?? globalThis.fetch,
-    body: {
-      model: args.model ?? DEFAULT_EVALUATION_MODEL,
-      state: args.state,
-      questions,
-    },
-  });
-  const answers = {} as AnswersFor<Q>;
-  for (const id of Object.keys(args.questions) as (keyof Q & string)[]) {
-    answers[id] = decodeAnswer(args.questions[id], raw[id]) as AnswersFor<Q>[typeof id];
-  }
-  return { answers };
-}
-
-/** Same as {@link evaluate}, returning only `answers`. */
-export async function decide<const Q extends QuestionMap>(
-  args: EvaluateArgs<Q>,
-): Promise<AnswersFor<Q>> {
-  const result = await evaluate(args);
-  return result.answers;
-}
-
-export function above(answer: BooleanAnswer | ScoreAnswer, threshold: number): boolean {
-  if (answer.type === "boolean") {
-    return answer.probability >= threshold;
-  }
-  return answer.score >= threshold;
-}
-
-export function needsHuman(
-  answer: BooleanAnswer | ChoiceAnswer,
-  threshold: number = DEFAULT_HUMAN_THRESHOLD,
-): boolean {
-  if (answer.type === "boolean") {
-    return answer.probability < threshold;
-  }
-  return answer.probabilities[answer.choice] < threshold;
-}

package/src/extensions/jev/skills/gated-write.md

@@ -1,25 +0,0 @@
----
-description: "Gate a channel wake, approval, or review comment on Jev by calling decide, then continuing or holding."
----
-
-# Gating a GitHub write on Jev
-
-Channel hooks can call `decide` before they start a model turn. Return
-`null` when the answer misses the bar; return `{ auth }` or `{ task }`
-when the agent should run.
-
-This extension's `evaluate` tool does not write to GitHub. When an
-approval or a review comment must follow the judgment, add a server tool
-in this project that calls `decide`, then writes or holds in the same
-`execute`.
-
-```ts
-import { above, decide, needsHuman } from "@cursor/bdk/extensions/jev";
-```
-
-Hold when `needsHuman` is true or `above` misses the bar. Very low and
-low risk can approve; medium and above hold. A finding comment posts
-only when the draft is a real bug. Calibrate those numbers on labeled
-pull requests from this workflow. Pass the pull request title, summary,
-and draft, not the checkout. Return without writing when
-`ctx.session.purpose === "eval"`.

package/src/extensions/jev/skills/questions.md

@@ -1,33 +0,0 @@
----
-description: "Ask Jev for a risk tier, a finding judgment, or a score when you are not about to approve or comment."
----
-
-# Asking Jev
-
-Call this extension's `evaluate` tool when you need a typed judgment over
-a pull request and you are not about to approve or comment. It returns
-answers only. The tool appears as `<namespace>__evaluate`.
-
-## Questions
-
-Pass `state` (the pull request title, a short summary of the diff, and
-any draft finding) and one or more questions. Each question has an `id`,
-a `type`, and `instructions`.
-
-- `boolean`: probability of true between 0 and 1
-- `choice`: `criteria` maps each option name to a short description; the
-  answer names one option
-- `score`: `criteria` from lowest to highest; the answer is a number
-  along that rubric
-
-`instructions` can set the decision, who the review is for, and which
-evidence to weigh. Pass the pull request summary, not the checkout.
-
-## Reading answers
-
-A boolean answer has `probability`. A choice has `choice` and
-`probabilities`. A score has `score` and `probabilities`.
-
-When an approval or a review comment must follow the judgment, use a
-project tool that calls `decide` itself. Do not treat these answers as
-a GitHub write.

package/src/extensions/jev/tools/evaluate.ts

@@ -1,82 +0,0 @@
-import { z } from "zod";
-import { defineTool } from "../../../tools.js";
-import type { ToolDefinition } from "../../../types.js";
-import extension from "../extension.js";
-import { evaluate, type QuestionMap } from "../lib/evaluate.js";
-
-const booleanQuestion = z.object({
-  id: z.string().min(1),
-  type: z.literal("boolean"),
-  instructions: z.string().min(1),
-});
-
-const choiceQuestion = z.object({
-  id: z.string().min(1),
-  type: z.literal("choice"),
-  instructions: z.string().min(1),
-  criteria: z.record(z.string()),
-});
-
-const scoreQuestion = z.object({
-  id: z.string().min(1),
-  type: z.literal("score"),
-  instructions: z.string().min(1),
-  criteria: z.array(z.string()).min(2),
-});
-
-const question = z.discriminatedUnion("type", [booleanQuestion, choiceQuestion, scoreQuestion]);
-
-function toQuestionMap(questions: z.infer<typeof question>[]): QuestionMap {
-  const map: QuestionMap = {};
-  for (const item of questions) {
-    if (item.type === "boolean") {
-      map[item.id] = {
-        type: "boolean",
-        instructions: item.instructions,
-      };
-    } else if (item.type === "choice") {
-      map[item.id] = {
-        type: "choice",
-        instructions: item.instructions,
-        criteria: item.criteria,
-      };
-    } else {
-      map[item.id] = {
-        type: "score",
-        instructions: item.instructions,
-        criteria: item.criteria,
-      };
-    }
-  }
-  return map;
-}
-
-const evaluateTool: ToolDefinition = defineTool({
-  description:
-    "Ask Jev for typed boolean, choice, or score answers over one state. Returns answers only; it does not post, assign, or merge.",
-  effect: "read",
-  inputSchema: z
-    .object({
-      state: z
-        .union([z.string(), z.array(z.unknown()), z.record(z.unknown())])
-        .describe("Ticket, pull request, or other state Jev should judge. Not repo source."),
-      questions: z
-        .array(question)
-        .min(1)
-        .describe("One or more typed questions over the same state."),
-    })
-    .refine(
-      input => new Set(input.questions.map(item => item.id)).size === input.questions.length,
-      "questions must not repeat an id",
-    ),
-  async execute(input) {
-    return evaluate({
-      state: input.state,
-      questions: toQuestionMap(input.questions),
-      apiKey: extension.config.apiKey,
-      model: extension.config.model,
-    });
-  },
-});
-
-export default evaluateTool;