@cursor/bdk 0.2.1 → 0.2.3

package/src/bin/agent-serve.ts

@@ -48,6 +48,7 @@ import {
   cmdDeployments,
   cmdEventRepos,
   cmdKill,
+  cmdRollback,
   cmdRotateToken,
   cmdSecretsList,
   cmdSecretsSet,
@@ -66,6 +67,7 @@ import {
   PACKAGE_NAME,
   packageVersion,
 } from "../internal/distribution.js";
+import { v2HostedVerifyHint } from "../internal/legacy-command-guard.js";
 import { loadAgentLocalEnv } from "../internal/local-env.js";
 import {
   ENTER_RESTART_EXIT_CODE,
@@ -97,6 +99,7 @@ Usage:
                           [--slug <slug>] [--team <id>] [--dir <path>]
   ${CLI} sessions    [--url <baseUrl> | --prod] [--json]
                           [--slug <slug>] [--team <id>] [--dir <path>]
+                          v2: unsupported. ${v2HostedVerifyHint()}
   ${CLI} session     <sessionId> [--url <baseUrl> | --prod]
                           [--json | --text | --events] [--out <file.ndjson>]
                           [--slug <slug>] [--team <id>] [--dir <path>]
@@ -114,6 +117,7 @@ Usage:
   ${CLI} trajectory  --events <file.ndjson> [--text]
   ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
                           [--session <id>] [--slug <slug>] [--team <id>]
+                          v2: unsupported. ${v2HostedVerifyHint()}
   ${CLI} skill       <name> [--dir <path> | --url <baseUrl> | --prod]
                           [--slug <slug>] [--team <id>] [--text]
   ${CLI} init        [dir] [--template <name>] [--var id=value]... [--json]
@@ -157,6 +161,7 @@ Usage:
   ${CLI} cancel-runs <slug> [--team <id>] [--json]
   ${CLI} event-repos <slug> [--repo <owner/name>]... [--team <id>] [--json]
   ${CLI} upgrade     <slug> [--release <id|version>] [--team <id>] [--json]
+  ${CLI} rollback    <slug> [--release <id|version>] [--team <id>] [--json]
   ${CLI} delete      <slug> [--team <id>] [--json] [--no-wait]
   ${CLI} rotate-token <slug> [--team <id>]
   ${CLI} secrets     set <slug> NAME... | list <slug> | unset <slug> NAME
@@ -189,8 +194,10 @@ Commands:
               the current buffer. --prod shows deploy progress until the
               hosted deployment is running, then tails runtime logs. Without
               --prod, tails the local server (or --url).
-  sessions    List sessions on a running agent (or --prod hosted deployment).
-  session     Show one session. Default: text trajectory. --json for trajectory
+  sessions    List sessions on a running agent or a v1 --prod deployment.
+              Unsupported on architecture v2. ${v2HostedVerifyHint()}
+  session     Show one session. On v2: \`${CLI} session <ses_> --prod --slug <slug>\`.
+              Default: text trajectory. --json for trajectory
               JSON; --events for the raw event list. To continue interactively,
               use \`${CLI} resume [id]\`.
   cost        Pull cost metrics. With a session id: per-turn token usage and
@@ -208,13 +215,14 @@ Commands:
               Streams tool calls and reply text to stderr when stderr is a TTY.
               Pass --prod to hit the hosted deployment instead of a local server.
               On an AgentSDK v2 slug, --prod starts a hosted session through
-              the control plane (Temporal, no resident engine); --session
-              ses_… resumes that exact session. A 404 falls back to the v1
+              the control plane (Temporal, no resident engine). ${v2HostedVerifyHint()}
+              --session ses_… resumes that exact session. A 404 falls back to the v1
               engine alias.
   trajectory  Summarize an events.ndjson file into a trajectory.
   call        Call an authored server tool deterministically (no model turn)
               via POST /v1/tools/:toolName. --session runs it inside an
               existing session and records it on that session's event stream.
+              Unsupported on architecture v2. ${v2HostedVerifyHint()}
   skill       Read an authored skill deterministically (no model turn)
               via GET /v1/skills/:skillName. --text prints SKILL.md.
   init        Scaffold a project (skipping existing files), npm install,
@@ -234,8 +242,8 @@ Commands:
               -> MCP). Review the project, then run \`validate\` / \`dev\`.
               Warnings never fail the command.
   install-skills
-              Refresh the Agent SDK skills for coding agents in
-              ~/.cursor/skills/agentsdk and print where they landed.
+              Refresh the BDK skills for coding agents in
+              ~/.cursor/skills/bdk and print where they landed.
               Installed copies set alwaysApply so Cursor injects them
               into context. \`npm install\` / \`npx\` already copies them
               (postinstall); this command overwrites with the package
@@ -306,6 +314,9 @@ Commands:
   upgrade     Move this team's install onto a release, the newest ready one
               by default. Deploying a multi-tenant application publishes a
               release without moving any tenant onto it.
+  rollback    Move this team's install onto an earlier ready release, the
+              nearest one by default. Does not publish a release. Pass
+              --release to choose an older id or version.
   delete      Delete a deployment (teardown + purge the record) and wait
               until GET 404s. The slug is then free to redeploy.
   rotate-token Mint a new alias token for a deployment (shown once); the old
@@ -392,7 +403,10 @@ Options:
                      --dir basename. Mutually exclusive with --url. Requires
                      \`${CLI} login\`. For eval, this is how you opt into the
                      persisted server-side batch (default is local).
+                     v2: ${v2HostedVerifyHint()} call --prod and
+                     sessions --prod stay on v1.
   --dry-run          run/session --prod: mark the hosted v2 turn non-mutating.
+                     ${v2HostedVerifyHint()}
   --component        run/session --prod: wake this v2 component key,
                      not the application default.
   --as-of            run/session --prod: freeze the session clock at this
@@ -893,6 +907,13 @@ async function main(argv: string[]): Promise<number> {
       );
     }
 
+    case "rollback": {
+      return cmdRollback(
+        { slug: positionals[0], release: values.release },
+        deployOptionsFromValues(values),
+      );
+    }
+
     case "delete": {
       return cmdDelete(positionals[0], deployOptionsFromValues(values));
     }

package/src/channels/github/auth.ts

@@ -215,11 +215,50 @@ export async function createGitHubInstallationToken(input: {
     privateKey,
     ...(input.api?.apiBaseUrl === undefined ? {} : { baseUrl: input.api.apiBaseUrl }),
   });
-  const result = await auth({
-    type: "installation",
-    installationId: input.installationId,
-  });
-  return result.token;
+  try {
+    const result = await auth({
+      type: "installation",
+      installationId: input.installationId,
+    });
+    return result.token;
+  } catch (error) {
+    throw installationTokenMintError(error, {
+      appId,
+      installationId: input.installationId,
+    });
+  }
+}
+
+/**
+ * Octokit's bare mint failure ("Not Found - <docs url>") names neither the
+ * app nor the installation, which makes a revoked installation or an
+ * app/installation credential mismatch undiagnosable from production logs.
+ * Rewrap with both ids and, for 404, the two causes that produce it.
+ */
+function installationTokenMintError(
+  error: unknown,
+  context: { appId: string; installationId: number },
+): Error {
+  const status =
+    typeof error === "object" &&
+    error !== null &&
+    "status" in error &&
+    typeof (error as { status: unknown }).status === "number"
+      ? (error as { status: number }).status
+      : undefined;
+  const detail = error instanceof Error ? error.message : String(error);
+  const hint =
+    status === 404
+      ? " — the installation does not exist for this app: it was uninstalled or suspended, or the configured app credentials belong to a different GitHub App than the one this installation id refers to"
+      : "";
+  const wrapped = new Error(
+    `githubChannel: failed to mint an installation access token (app ${context.appId}, installation ${context.installationId}): ${detail}${hint}`,
+    error instanceof Error ? { cause: error } : undefined,
+  );
+  if (status !== undefined) {
+    (wrapped as Error & { status?: number }).status = status;
+  }
+  return wrapped;
 }
 
 /**

package/src/channels/slack/manifest.ts

@@ -133,6 +133,7 @@ export function buildSlackManifest(options: SlackManifestOptions): SlackAppManif
   const displayName = benny ? "benny-dev" : env === "dev" ? `${options.name} (dev)` : options.name;
   const botName = options.botDisplayName ?? toBotDisplayName(options.name, env);
   const description = options.description ?? defaultDescription(options.name);
+  const agentDescription = options.agentDescription ?? description;
   const includeAgentView = options.assistant !== false;
 
   const botScopes = includeAgentView
@@ -163,7 +164,7 @@ export function buildSlackManifest(options: SlackManifestOptions): SlackAppManif
       },
       agent_view: includeAgentView
         ? {
-            agent_description: description,
+            agent_description: agentDescription,
             suggested_prompts: suggested,
           }
         : undefined,

package/src/channels/slack/types.ts

@@ -752,8 +752,13 @@ export interface SlackManifestOptions {
   botDisplayName?: string;
   /** Env profile. Affects display name suffix. */
   env: "dev" | "prod";
-  /** Optional short description shown in the Slack app. */
+  /** Optional short description shown in the Slack app directory. Slack caps this at 140 characters. */
   description?: string;
+  /**
+   * Slack agent profile (`features.agent_view.agent_description`).
+   * Defaults to `description`. Separate from the 140-character marketplace line.
+   */
+  agentDescription?: string;
   /** Include `agent_view` + `assistant:write` for typing status. */
   assistant?: boolean;
   /**

package/src/connections.ts

@@ -18,7 +18,7 @@
  *
  * export default defineConnection({
  *   url: "https://mcp.linear.app/mcp",
- *   headers: { authorization: `Bearer ${process.env.LINEAR_TOKEN}` },
+ *   headers: { authorization: "Bearer ${LINEAR_TOKEN}" },
  * });
  *
  * // TypeScript tools, packaged as stdio MCP for the agent environment:

package/src/extensions/cursor-cloud-agents/extension.ts

@@ -18,14 +18,22 @@
  * Agents API, everything else through the BackgroundComposerService RPCs,
  * all under the serve host's Cursor API key (`CURSOR_API_KEY`, key file, or
  * `login`). Each launched agent stays bound to the principal that launched
- * it, and launches go to the configured repositories. The tools run on the
- * serve host, so they need the local runtime.
+ * it, and launches go to the configured repositories. `channels` limits
+ * launch, reply, and cancel to sessions on those channel ids, so a channel
+ * whose input is untrusted (an alert webhook) cannot start or steer an agent.
+ * The tools run on the serve host, so they need the local runtime.
  */
 
 import { z } from "zod";
 import { defineExtension } from "../../extensions.js";
 import type { AgentCloudOptions, Extension, ModelSetting } from "../../types.js";
 
+type CloudRepo = NonNullable<AgentCloudOptions["repos"]>[number];
+
+export type CursorCloudAgentsCloudOptions = Omit<AgentCloudOptions, "repos"> & {
+  repos?: CloudRepo[] | (() => CloudRepo[]);
+};
+
 /** Mount options; every field is optional. */
 export interface CursorCloudAgentsOptions {
   /**
@@ -34,8 +42,12 @@ export interface CursorCloudAgentsOptions {
    * allowlist for a launch's own `repo` / `prUrl`; model-chosen targets are
    * refused when no allowlist is configured. With none configured,
    * `needsApproval` defaults to true so prompt-only launches park first.
+   * `repos` may be a function, called on every launch, for an allowlist that
+   * is only known at request time (a multi-tenant deployment's per-install
+   * secrets). A launch against a function allowlist always targets exactly
+   * one of its repositories, never the whole list and never none.
    */
-  cloud?: AgentCloudOptions;
+  cloud?: CursorCloudAgentsCloudOptions;
   /** Model for launched agents. The account default when omitted. */
   model?: ModelSetting;
   /**
@@ -46,15 +58,17 @@ export interface CursorCloudAgentsOptions {
    * require the allowlist regardless of this flag.
    */
   needsApproval?: boolean;
+  channels?: string[];
   /** Cursor API key. Defaults to the serve host's own key. */
   apiKey?: string;
 }
 
 /** {@link CursorCloudAgentsOptions} with defaults applied. */
 export interface CursorCloudAgentsConfig {
-  cloud: AgentCloudOptions;
+  cloud: CursorCloudAgentsCloudOptions;
   model?: ModelSetting;
   needsApproval: boolean;
+  channels?: string[];
   apiKey?: string;
 }
 
@@ -64,7 +78,9 @@ const repo = z.object({
   prUrl: z.string().url().optional(),
 });
 
-const cloud: z.ZodType<AgentCloudOptions> = z.object({
+const repos = z.array(repo);
+
+const cloud: z.ZodType<CursorCloudAgentsCloudOptions> = z.object({
   env: z
     .discriminatedUnion("type", [
       z.object({ type: z.literal("cloud"), name: z.string().optional() }),
@@ -72,7 +88,7 @@ const cloud: z.ZodType<AgentCloudOptions> = z.object({
       z.object({ type: z.literal("machine"), name: z.string().optional() }),
     ])
     .optional(),
-  repos: z.array(repo).optional(),
+  repos: z.union([repos, z.function().args().returns(repos)]).optional(),
   workOnCurrentBranch: z.boolean().optional(),
   autoCreatePR: z.boolean().optional(),
   skipReviewerRequest: z.boolean().optional(),
@@ -96,6 +112,7 @@ const config: z.ZodType<
     cloud: cloud.default({}),
     model: model.optional(),
     needsApproval: z.boolean().optional(),
+    channels: z.array(z.string().min(1)).optional(),
     apiKey: z.string().optional(),
   })
   .default({})

package/src/extensions/cursor-cloud-agents/lib/channels.ts

@@ -0,0 +1,11 @@
+import type { ToolContext } from "../../../types.js";
+import extension from "../extension.js";
+
+export function assertWriteChannel(ctx: ToolContext): void {
+  const { channels } = extension.config;
+  if (channels !== undefined && !channels.includes(ctx.session.channelId)) {
+    throw new Error(
+      `Cloud agents cannot be launched or steered from the "${ctx.session.channelId}" channel.`,
+    );
+  }
+}

package/src/extensions/cursor-cloud-agents/lib/repos.ts

@@ -3,11 +3,13 @@
  * `prUrl` per call, but the author's `cloud.repos` are the allowlist.
  * Model-chosen targets always require that allowlist: an unbound mount
  * (no `cloud.repos`) must not accept an arbitrary URL under the host API
- * key, with or without `envVars`.
+ * key, with or without `envVars`. A function allowlist is resolved on every
+ * call and always narrows the launch to one of its repositories.
  */
 
 import { parsePrUrl } from "../../../internal/scm/pr-url.js";
 import type { AgentCloudOptions } from "../../../types.js";
+import type { CursorCloudAgentsCloudOptions } from "../extension.js";
 
 export interface LaunchTarget {
   repo?: string;
@@ -17,10 +19,20 @@ export interface LaunchTarget {
 
 export function launchRepos(
   target: LaunchTarget,
-  cloud: AgentCloudOptions,
+  cloud: CursorCloudAgentsCloudOptions,
 ): AgentCloudOptions["repos"] {
-  if (target.repo === undefined && target.ref === undefined && target.prUrl === undefined) {
-    return cloud.repos;
+  const resolved = typeof cloud.repos === "function";
+  const allowlist = typeof cloud.repos === "function" ? cloud.repos() : cloud.repos;
+  if (resolved && allowlist?.length === 0) {
+    throw new Error("No repositories are available to cloud agents for this deployment.");
+  }
+  if (
+    !resolved &&
+    target.repo === undefined &&
+    target.ref === undefined &&
+    target.prUrl === undefined
+  ) {
+    return allowlist;
   }
   const pr = target.prUrl === undefined ? undefined : parsePrUrl(target.prUrl);
   if (target.prUrl !== undefined && pr?.provider !== "github") {
@@ -28,7 +40,7 @@ export function launchRepos(
   }
   const prRepo = pr === undefined ? undefined : `https://github.com/${pr.owner}/${pr.repo}`;
   // A lone `ref` needs exactly one configured repository to apply to.
-  const configured = cloud.repos ?? [];
+  const configured = allowlist ?? [];
   const url = target.repo ?? prRepo ?? (configured.length === 1 ? configured[0]?.url : undefined);
   if (url === undefined) {
     throw new Error(
@@ -40,10 +52,10 @@ export function launchRepos(
   if (prRepo !== undefined && repoKey(prRepo) !== repoKey(url)) {
     throw new Error(`prUrl ${target.prUrl} is not a pull request of ${url}.`);
   }
-  const allowlisted = cloud.repos?.some(configured => repoKey(configured.url) === repoKey(url));
+  const allowlisted = allowlist?.some(configured => repoKey(configured.url) === repoKey(url));
   if (allowlisted !== true) {
     throw new Error(
-      cloud.repos === undefined
+      allowlist === undefined
         ? `Configure cloud.repos before launching against a model-chosen repository (${url}).`
         : `${url} is not one of this extension's configured repositories.`,
     );

package/src/extensions/cursor-cloud-agents/tools/cancel.ts

@@ -1,6 +1,7 @@
 import { defineTool } from "../../../tools.js";
 import type { ToolDefinition } from "../../../types.js";
 import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertWriteChannel } from "../lib/channels.js";
 import { assertOwned } from "../lib/fleet.js";
 import { agentRef } from "../lib/inputs.js";
 
@@ -10,6 +11,7 @@ const cancel: ToolDefinition = defineTool({
   effect: "write",
   inputSchema: agentRef,
   async execute(input, ctx) {
+    assertWriteChannel(ctx);
     await assertOwned(ctx, input.agent_id);
     await cloudAgentsBackend().pause(input.agent_id);
     return { agentId: input.agent_id, cancelled: true };

package/src/extensions/cursor-cloud-agents/tools/launch.ts

@@ -3,6 +3,7 @@ import { defineTool } from "../../../tools.js";
 import type { ToolDefinition } from "../../../types.js";
 import extension from "../extension.js";
 import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertWriteChannel } from "../lib/channels.js";
 import { recordLaunch } from "../lib/fleet.js";
 import { launchRepos } from "../lib/repos.js";
 
@@ -21,7 +22,7 @@ const launch: ToolDefinition = defineTool({
       .url()
       .optional()
       .describe(
-        "GitHub repository URL, one of the configured repositories. Defaults to the configured repository.",
+        "Repository clone URL (GitHub or Origin), one of the configured repositories. Defaults to the configured repository when there is exactly one.",
       ),
     starting_ref: z
       .string()
@@ -39,6 +40,7 @@ const launch: ToolDefinition = defineTool({
       .describe("Display name; derived from the prompt when omitted."),
   }),
   async execute(input, ctx) {
+    assertWriteChannel(ctx);
     const { cloud, model } = extension.config;
     const launched = await cloudAgentsBackend().launch({
       prompt: input.prompt,

package/src/extensions/cursor-cloud-agents/tools/reply.ts

@@ -3,6 +3,7 @@ import { defineTool } from "../../../tools.js";
 import type { ToolDefinition } from "../../../types.js";
 import extension from "../extension.js";
 import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertWriteChannel } from "../lib/channels.js";
 import { assertOwned } from "../lib/fleet.js";
 import { agentRef } from "../lib/inputs.js";
 
@@ -21,6 +22,7 @@ const reply: ToolDefinition = defineTool({
       ),
   }),
   async execute(input, ctx) {
+    assertWriteChannel(ctx);
     await assertOwned(ctx, input.agent_id);
     const { runId } = await cloudAgentsBackend().followUp(
       input.agent_id,

package/src/extensions/cursor-grokbot-agents/extension.ts

@@ -0,0 +1,132 @@
+/**
+ * Your Grok Bot agents as an extension. Mount it and the agent can talk to
+ * the Grok Bot agents of the host's account: send a message, read the
+ * reply, keep waiting on a long turn, interrupt one.
+ *
+ * ```ts
+ * // agent/extensions/grokbot.ts
+ * import cursorGrokBotAgents from "@cursor/bdk/extensions/cursor-grokbot-agents";
+ *
+ * export default cursorGrokBotAgents({
+ *   agents: [
+ *     { name: "Plan Keeper", description: "Keeps or moves outdoor plans." },
+ *   ],
+ * });
+ * ```
+ *
+ * Contributes `grokbot__ask`, `grokbot__check`, `grokbot__interrupt`,
+ * `grokbot__list` and the `grokbot__consult` skill (the namespace is the
+ * mount filename), over the same public `/v0/grokbot` session API the
+ * grokbot runtime uses, under the serve host's Cursor API key
+ * (`CURSOR_API_KEY`, key file, or `login`). Agents are addressed by name and
+ * resolved on the account the key belongs to; a message lands in that
+ * account's own conversation with the agent, and the reply is what the agent
+ * sends back during that turn. The tools run on the serve host, so they
+ * need the local runtime.
+ *
+ * This is the other direction from `defineAgent({ runtime: "grokbot" })`:
+ * the runtime runs *this* agent's turns on the hosted Grok Bot harness; the
+ * extension keeps the agent where it is and lets it talk to *other* Grok
+ * Bot agents.
+ */
+
+import { z } from "zod";
+import { defineExtension } from "../../extensions.js";
+import type { Extension } from "../../types.js";
+
+/**
+ * A Grok Bot agent the model may address, by the name shown in the app.
+ * Type alias, not an interface: `list` returns these.
+ */
+export type ConfiguredGrokBotAgent = {
+  name: string;
+  /** What the agent is for; shown to the model by `list`. */
+  description?: string;
+};
+
+/** Mount options; every field is optional. */
+export interface CursorGrokBotAgentsOptions {
+  /**
+   * The Grok Bot agents the model may talk to, by name. This is the
+   * allowlist for a call's own `agent`: names outside it are refused, and a
+   * lone configured agent is the default when a call names none. Without
+   * it, any name goes through and `needsApproval` defaults to true, since
+   * an unknown name creates an agent of that name on the account.
+   */
+  agents?: Array<string | ConfiguredGrokBotAgent>;
+  /**
+   * Park messages for a human approval. Defaults to `true` when no `agents`
+   * are configured; `false` once they are. Pass an explicit boolean to
+   * override. Configured names still bound the model's choice regardless.
+   */
+  needsApproval?: boolean;
+  /** Cursor API key. Defaults to the serve host's own key. */
+  apiKey?: string;
+  /**
+   * How often to read the agent's transcript while waiting for a reply, in
+   * milliseconds. Defaults to 750.
+   */
+  pollIntervalMs?: number;
+}
+
+/** {@link CursorGrokBotAgentsOptions} with defaults applied. */
+export interface CursorGrokBotAgentsConfig {
+  agents?: ConfiguredGrokBotAgent[];
+  needsApproval: boolean;
+  apiKey?: string;
+  pollIntervalMs: number;
+}
+
+/** The backend's session name limit. */
+export const AGENT_NAME_MAX_LENGTH = 255;
+const DEFAULT_POLL_INTERVAL_MS = 750;
+
+const agentName = z
+  .string()
+  .trim()
+  .min(1, "Grok Bot agent names must not be empty.")
+  .max(AGENT_NAME_MAX_LENGTH);
+
+const configuredAgent: z.ZodType<
+  ConfiguredGrokBotAgent,
+  z.ZodTypeDef,
+  string | ConfiguredGrokBotAgent
+> = z
+  .union([agentName, z.object({ name: agentName, description: z.string().optional() })])
+  .transform(agent => (typeof agent === "string" ? { name: agent } : agent));
+
+const agents = z
+  .array(configuredAgent)
+  .min(1, "agents must name at least one Grok Bot agent; omit it to allow any.")
+  .refine(
+    list => new Set(list.map(agent => agent.name.toLowerCase())).size === list.length,
+    "agents must not repeat a name (names match case-insensitively).",
+  );
+
+const config: z.ZodType<
+  CursorGrokBotAgentsConfig,
+  z.ZodTypeDef,
+  CursorGrokBotAgentsOptions | undefined
+> = z
+  .object({
+    agents: agents.optional(),
+    needsApproval: z.boolean().optional(),
+    apiKey: z.string().optional(),
+    pollIntervalMs: z.number().int().min(1).default(DEFAULT_POLL_INTERVAL_MS),
+  })
+  .default({})
+  .transform(options => ({
+    ...options,
+    needsApproval: options.needsApproval ?? options.agents === undefined,
+  }));
+
+const cursorGrokBotAgents: Extension<
+  CursorGrokBotAgentsConfig,
+  CursorGrokBotAgentsOptions | undefined
+> = defineExtension({
+  root: import.meta.dirname,
+  description: "Talk to your Grok Bot agents and read their replies.",
+  config,
+});
+
+export default cursorGrokBotAgents;

package/src/extensions/cursor-grokbot-agents/lib/agents.ts

@@ -0,0 +1,42 @@
+/**
+ * Which Grok Bot agent a call addresses. The model names one per call, but
+ * the author's `agents` are the allowlist: with them configured, a name
+ * outside the list is refused (the backend would create an agent of that
+ * name), and a lone configured agent stands in when the call names none.
+ * Matching is case-insensitive and resolves to the configured spelling,
+ * since the backend looks names up exactly.
+ */
+
+import type { ConfiguredGrokBotAgent } from "../extension.js";
+
+export function resolveAgentName(
+  requested: string | undefined,
+  configured: ConfiguredGrokBotAgent[] | undefined,
+): string {
+  const name = requested?.trim();
+  if (configured === undefined) {
+    if (name === undefined || name === "") {
+      throw new Error("`agent` is required: this extension has no configured Grok Bot agents.");
+    }
+    return name;
+  }
+  const names = configured.map(agent => `"${agent.name}"`).join(", ");
+  if (name === undefined || name === "") {
+    const only = configured.length === 1 ? configured[0] : undefined;
+    if (only === undefined) {
+      throw new Error(
+        `\`agent\` is required: this extension configures several Grok Bot agents (${names}).`,
+      );
+    }
+    return only.name;
+  }
+  const match =
+    configured.find(agent => agent.name === name) ??
+    configured.find(agent => agent.name.toLowerCase() === name.toLowerCase());
+  if (match === undefined) {
+    throw new Error(
+      `"${name}" is not one of this extension's configured Grok Bot agents (${names}).`,
+    );
+  }
+  return match.name;
+}