blume 2.0.2 → 2.1.0

package/src/captcha/client.ts

@@ -0,0 +1,152 @@
+/**
+ * The browser half of the bot check: a fresh token for each question the
+ * assistant sends (both providers' tokens are single-use). The provider's
+ * script loads with the first question rather than with the page, and one
+ * widget serves every question after it: an invisible hCaptcha, or a
+ * Turnstile that only shows itself when it needs the reader to interact,
+ * in a small container at the foot of the viewport.
+ *
+ * The client router swaps `<body>` on every navigation, taking the container
+ * and its widget with it, so a question after a swap mounts a new one.
+ */
+import type { CaptchaSettings } from "./schema.ts";
+
+/** Each provider's script, rendering only when asked to. */
+export const CAPTCHA_SCRIPTS = {
+  hcaptcha: "https://js.hcaptcha.com/1/api.js?render=explicit",
+  turnstile:
+    "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit",
+} as const;
+
+/** What Blume asks a Turnstile widget for. */
+interface TurnstileRenderOptions {
+  appearance: "interaction-only";
+  callback: (token: string) => void;
+  "error-callback": () => void;
+  execution: "execute";
+  sitekey: string;
+}
+
+/** The slice of `window.turnstile` the check uses. */
+export interface TurnstileApi {
+  execute: (widget: string) => void;
+  render: (container: HTMLElement, options: TurnstileRenderOptions) => string;
+  reset: (widget: string) => void;
+}
+
+/** What Blume asks an hCaptcha widget for. */
+interface HcaptchaRenderOptions {
+  sitekey: string;
+  size: "invisible";
+}
+
+/** The slice of `window.hcaptcha` the check uses. */
+export interface HcaptchaApi {
+  execute: (
+    widget: string,
+    options: { async: true }
+  ) => Promise<{ response: string }>;
+  render: (container: HTMLElement, options: HcaptchaRenderOptions) => string;
+  reset: (widget: string) => void;
+}
+
+/** The window, with the providers' globals once their scripts ran. */
+type CaptchaWindow = Window & {
+  hcaptcha?: HcaptchaApi;
+  turnstile?: TurnstileApi;
+};
+
+/** A Turnstile token on its way. */
+interface PendingToken {
+  reject: (error: Error) => void;
+  resolve: (token: string) => void;
+}
+
+/** Get a token for the next question. */
+export type CaptchaTokenGetter = (settings: CaptchaSettings) => Promise<string>;
+
+/** A token getter with its own script, container, and widget. */
+export const createCaptchaClient = (): CaptchaTokenGetter => {
+  let loaded: Promise<void> | undefined;
+  let host: HTMLElement | undefined;
+  let widget: string | undefined;
+  let pending: PendingToken | undefined;
+
+  const load = (kind: CaptchaSettings["kind"]): Promise<void> => {
+    // oxlint-disable-next-line promise/avoid-new -- adapt the script tag's load events
+    loaded ??= new Promise<void>((resolve, reject) => {
+      const tag = document.createElement("script");
+      tag.async = true;
+      tag.src = CAPTCHA_SCRIPTS[kind];
+      tag.addEventListener("load", () => resolve());
+      tag.addEventListener("error", () => {
+        // Let the next question try again.
+        loaded = undefined;
+        reject(new Error(`The ${kind} script didn't load.`));
+      });
+      document.head.append(tag);
+    });
+    return loaded;
+  };
+
+  // The widget's container, mounted again when a swap took the last one.
+  const mount = (): HTMLElement => {
+    if (host?.isConnected) {
+      return host;
+    }
+    host = document.createElement("div");
+    host.className = "fixed bottom-4 left-1/2 z-[60] -translate-x-1/2";
+    host.dataset.blumeCaptcha = "";
+    document.body.append(host);
+    widget = undefined;
+    return host;
+  };
+
+  const turnstileToken = (api: TurnstileApi, siteKey: string) =>
+    // oxlint-disable-next-line promise/avoid-new -- adapt Turnstile's token callbacks
+    new Promise<string>((resolve, reject) => {
+      pending = { reject, resolve };
+      const target = mount();
+      if (widget === undefined) {
+        widget = api.render(target, {
+          appearance: "interaction-only",
+          callback: (token) => pending?.resolve(token),
+          "error-callback": () =>
+            pending?.reject(new Error("The Turnstile check failed.")),
+          execution: "execute",
+          sitekey: siteKey,
+        });
+      } else {
+        api.reset(widget);
+      }
+      api.execute(widget);
+    });
+
+  const hcaptchaToken = async (api: HcaptchaApi, siteKey: string) => {
+    const target = mount();
+    if (widget === undefined) {
+      widget = api.render(target, { sitekey: siteKey, size: "invisible" });
+    } else {
+      api.reset(widget);
+    }
+    const { response } = await api.execute(widget, { async: true });
+    return response;
+  };
+
+  return async (settings) => {
+    await load(settings.kind);
+    // SAFETY: CaptchaWindow only adds the providers' optional globals, each
+    // checked before use.
+    const { hcaptcha, turnstile } = window as CaptchaWindow;
+    if (settings.kind === "hcaptcha" && hcaptcha) {
+      return hcaptchaToken(hcaptcha, settings.siteKey);
+    }
+    if (settings.kind === "turnstile" && turnstile) {
+      return turnstileToken(turnstile, settings.siteKey);
+    }
+    throw new Error(`The ${settings.kind} script loaded without its API.`);
+  };
+};
+
+/** The page's token getter: one script and one widget per page load. */
+export const captchaToken = createCaptchaClient();

package/src/captcha/hcaptcha.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** Options for {@link hcaptcha}. */
+export interface HcaptchaOptions {
+  /** The site key, from the hCaptcha dashboard. */
+  siteKey: string;
+}
+
+export const hcaptchaOptionsSchema = z.strictObject({
+  siteKey: z.string().min(1),
+});
+
+export type HcaptchaAdapter = AdapterDescriptor<"hcaptcha", HcaptchaOptions>;
+
+export const hcaptchaAdapterSchema = adapterDescriptorSchema(
+  "hcaptcha",
+  hcaptchaOptionsSchema
+);
+
+/** Where the assistant's route checks an hCaptcha token. */
+export const HCAPTCHA_VERIFY_URL = "https://api.hcaptcha.com/siteverify";
+
+/**
+ * hCaptcha, as an invisible check: most readers never see a challenge. The
+ * site key is public and goes to the browser; the secret the route checks
+ * tokens with comes from `HCAPTCHA_SECRET_KEY`.
+ */
+export const hcaptcha = (options: HcaptchaOptions): HcaptchaAdapter => ({
+  kind: "hcaptcha",
+  options,
+  requiredSecrets: ["HCAPTCHA_SECRET_KEY"],
+  runtimeDeps: [],
+});

package/src/captcha/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Bot checks for the assistant (`ai.assistant.captcha` in `blume.config.ts`).
+ * The assistant gets a token from the check before each question and the
+ * generated route verifies it before calling the model:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { turnstile } from "blume/captcha";
+ *
+ * export default defineConfig({
+ *   ai: {
+ *     assistant: {
+ *       enabled: true,
+ *       captcha: turnstile({ siteKey: "0x4AAAAAAA…" }),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * Each factory returns a plain descriptor (see `core/adapter.ts`); the browser
+ * half is `client.ts`, the server half `verify.ts`.
+ */
+export type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+export { hcaptcha } from "./hcaptcha.ts";
+export type { HcaptchaAdapter, HcaptchaOptions } from "./hcaptcha.ts";
+export type { CaptchaAdapter, CaptchaSettings } from "./schema.ts";
+export { turnstile } from "./turnstile.ts";
+export type { TurnstileAdapter, TurnstileOptions } from "./turnstile.ts";

package/src/captcha/schema.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+import { hcaptchaAdapterSchema } from "./hcaptcha.ts";
+import { turnstileAdapterSchema } from "./turnstile.ts";
+
+/**
+ * The configured bot check, as its factory returned it. Anything that isn't
+ * one fails with the adapter hint; an adapter's own option errors keep their
+ * messages.
+ */
+export const captchaAdapterSchema = z.discriminatedUnion(
+  "kind",
+  [hcaptchaAdapterSchema, turnstileAdapterSchema],
+  {
+    error:
+      'captcha takes one adapter — e.g. `captcha: turnstile({ siteKey })` or `captcha: hcaptcha({ siteKey })`, imported from "blume/captcha".',
+  }
+);
+
+export type CaptchaAdapter = z.output<typeof captchaAdapterSchema>;
+
+/** What the browser needs to run the check: never the secret. */
+export interface CaptchaSettings {
+  kind: CaptchaAdapter["kind"];
+  siteKey: string;
+}
+
+/** The public half of an adapter, for the data snapshot. */
+export const captchaSettings = (adapter: CaptchaAdapter): CaptchaSettings => ({
+  kind: adapter.kind,
+  siteKey: adapter.options.siteKey,
+});

package/src/captcha/turnstile.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** Options for {@link turnstile}. */
+export interface TurnstileOptions {
+  /** The widget's site key, from the Cloudflare dashboard. */
+  siteKey: string;
+}
+
+export const turnstileOptionsSchema = z.strictObject({
+  siteKey: z.string().min(1),
+});
+
+export type TurnstileAdapter = AdapterDescriptor<"turnstile", TurnstileOptions>;
+
+export const turnstileAdapterSchema = adapterDescriptorSchema(
+  "turnstile",
+  turnstileOptionsSchema
+);
+
+/** Where the assistant's route checks a Turnstile token. */
+export const TURNSTILE_VERIFY_URL =
+  "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+
+/**
+ * Cloudflare Turnstile. The site key is public and goes to the browser; the
+ * secret key the route checks tokens with comes from `TURNSTILE_SECRET_KEY`.
+ * Set the widget to Invisible or Managed in the Cloudflare dashboard: most
+ * readers never see a challenge.
+ */
+export const turnstile = (options: TurnstileOptions): TurnstileAdapter => ({
+  kind: "turnstile",
+  options,
+  requiredSecrets: ["TURNSTILE_SECRET_KEY"],
+  runtimeDeps: [],
+});

package/src/captcha/verify.ts

@@ -0,0 +1,71 @@
+/**
+ * The server half of the bot check: the generated assistant route verifies
+ * the token the browser sent with the question against the provider before
+ * it calls the model. A failed or unreachable check refuses the question
+ * (and logs why), so a server that can't reach the provider shows up as a
+ * refused question rather than a silently unprotected route.
+ */
+import { clientAddressOf } from "../core/client-address.ts";
+import type { ClientContext } from "../core/client-address.ts";
+import { HCAPTCHA_VERIFY_URL } from "./hcaptcha.ts";
+import type { CaptchaAdapter } from "./schema.ts";
+import { TURNSTILE_VERIFY_URL } from "./turnstile.ts";
+
+/** The longest token either provider issues, with room to spare. */
+const MAX_TOKEN_LENGTH = 4096;
+
+/** What the provider answers about a token. */
+interface VerifyReply {
+  "error-codes"?: string[];
+  success?: boolean;
+}
+
+/** What the route hands the check from its runtime. */
+export interface VerifyOptions {
+  /** For tests; defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+  /** The provider's secret key. */
+  secret: string;
+}
+
+/**
+ * Whether the provider confirms `token` came from a person on this site. The
+ * route passes the request body's `captcha` when it's a string.
+ */
+export const verifyCaptcha = async (
+  adapter: CaptchaAdapter,
+  token: string | undefined,
+  context: ClientContext,
+  options: VerifyOptions
+): Promise<boolean> => {
+  if (!token || token.length > MAX_TOKEN_LENGTH) {
+    return false;
+  }
+  const form = new URLSearchParams({ response: token, secret: options.secret });
+  const address = clientAddressOf(context);
+  if (address) {
+    form.set("remoteip", address);
+  }
+  if (adapter.kind === "hcaptcha") {
+    form.set("sitekey", adapter.options.siteKey);
+  }
+  try {
+    const response = await (options.fetch ?? fetch)(
+      adapter.kind === "hcaptcha" ? HCAPTCHA_VERIFY_URL : TURNSTILE_VERIFY_URL,
+      { body: form, method: "POST" }
+    );
+    // SAFETY: both providers answer JSON with a `success` flag; anything
+    // else reads as a failure below.
+    const reply = (await response.json()) as VerifyReply;
+    if (reply.success === true) {
+      return true;
+    }
+    console.warn(
+      `The ${adapter.kind} check refused a question:`,
+      reply["error-codes"] ?? response.status
+    );
+  } catch (error) {
+    console.error(`The ${adapter.kind} check could not be reached:`, error);
+  }
+  return false;
+};

package/src/cli/args.ts

@@ -21,3 +21,35 @@ export const parsePort = (value?: string): number | undefined => {
   }
   return port;
 };
+
+/**
+ * The longest `--timeout` a timer can hold, in seconds. Node clamps a
+ * `setTimeout` delay above 2^31−1 ms (about 24.8 days) to 1 ms, so a larger
+ * value would time every agent out the moment it starts.
+ */
+export const MAX_TIMEOUT_S = Math.floor(2_147_483_647 / 1000);
+
+/**
+ * Parse a `--timeout` value in whole seconds, or return `fallback` when unset.
+ * A non-integer, non-positive, or too-long value exits with an error.
+ */
+export const parseTimeoutSeconds = (
+  value: string | undefined,
+  fallback: number
+): number => {
+  if (value === undefined) {
+    return fallback;
+  }
+  const timeout = Number(value);
+  if (!Number.isInteger(timeout) || timeout <= 0) {
+    logger.error(`Invalid --timeout "${value}" (whole seconds).`);
+    process.exit(1);
+  }
+  if (timeout > MAX_TIMEOUT_S) {
+    logger.error(
+      `Invalid --timeout "${value}" (at most ${MAX_TIMEOUT_S} seconds, about 24 days).`
+    );
+    process.exit(1);
+  }
+  return timeout;
+};

package/src/cli/command-meta.ts

@@ -62,6 +62,11 @@ export const commandMeta = {
     description: "Preview the last production build.",
     name: "preview",
   },
+  skill: {
+    description:
+      "Write the docs site's agent skill with a coding agent, in place of the generated one.",
+    name: "skill",
+  },
   sync: {
     description: "Re-fetch remote content sources and regenerate the runtime.",
     name: "sync",

package/src/cli/commands/audit.ts

@@ -238,7 +238,10 @@ export const auditCommand = defineCommand({
     process.stderr.write(formatReport(result, root, { verbose: args.verbose }));
 
     if (shouldFail(result, gate)) {
-      process.exit(1);
+      // Set the code and return rather than `process.exit`, which doesn't wait
+      // for a piped stderr: a long report was cut off after the first 64 KiB,
+      // in exactly the CI logs that need to show every finding.
+      process.exitCode = 1;
     }
   },
 });

package/src/cli/commands/doctor.ts

@@ -14,6 +14,7 @@ import {
 import { BlumeError } from "../../core/diagnostics.ts";
 import { packageRoot } from "../../core/package-root.ts";
 import { scanProject } from "../../core/project-graph.ts";
+import type { ResolvedConfig } from "../../core/schema.ts";
 import { serverFeatures } from "../../core/server-features.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { unregisteredSnapshotDiagnostics } from "../../core/version-cut.ts";
@@ -71,6 +72,25 @@ const supportedNodeRange = (): string => {
   }
 };
 
+/** The adapters a project runs, one line per kind, for the doctor summary. */
+const integrationSummary = (config: ResolvedConfig): string[] => {
+  const { assistant } = config.ai;
+  let assistantSummary = "off";
+  if (assistant?.enabled) {
+    assistantSummary = assistant.endpoint
+      ? "external endpoint"
+      : assistant.provider.kind;
+  }
+  return [
+    `References: ${config.reference.map((adapter) => adapter.kind).join(", ") || "none"}`,
+    `Analytics: ${config.analytics.map((adapter) => adapter.kind).join(", ") || "none"}`,
+    `Consent: ${config.consent?.kind ?? "none"}`,
+    `Rate limiting: ${config.rateLimit?.kind ?? "off"}`,
+    `Sources: ${config.content.sources.map((source) => source.kind).join(", ")}`,
+    `Assistant: ${assistantSummary}`,
+  ];
+};
+
 export const doctorCommand = defineCommand({
   args: {
     json: {
@@ -144,23 +164,9 @@ export const doctorCommand = defineCommand({
         logger.info(`Output: ${config.deployment.options.output}`);
         logger.info(`Adapter: ${config.deployment.kind}`);
         logger.info(`Search: ${config.search.provider.kind}`);
-        logger.info(
-          `References: ${config.reference.map((adapter) => adapter.kind).join(", ") || "none"}`
-        );
-        logger.info(
-          `Analytics: ${config.analytics.map((adapter) => adapter.kind).join(", ") || "none"}`
-        );
-        logger.info(
-          `Sources: ${config.content.sources.map((source) => source.kind).join(", ")}`
-        );
-        const { assistant } = config.ai;
-        let assistantSummary = "off";
-        if (assistant?.enabled) {
-          assistantSummary = assistant.endpoint
-            ? "external endpoint"
-            : assistant.provider.kind;
+        for (const line of integrationSummary(config)) {
+          logger.info(line);
         }
-        logger.info(`Assistant: ${assistantSummary}`);
       }
     } catch (error) {
       if (error instanceof BlumeError) {
@@ -187,7 +193,9 @@ export const doctorCommand = defineCommand({
       logger.success("No problems found.");
     }
     if (hadErrors) {
-      process.exit(1);
+      // Set the code and return rather than `process.exit`, which doesn't wait
+      // for a piped stderr: a long diagnostic list would be cut off.
+      process.exitCode = 1;
     }
   },
 });

package/src/cli/commands/eval.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 
 import { defineCommand } from "citty";
-import { join } from "pathe";
+import { resolve } from "pathe";
 
 import { AGENTS, launchAgent } from "../../audit/agent.ts";
 import type { AgentKind } from "../../audit/agent.ts";
@@ -22,6 +22,7 @@ import {
 import { passFraction, runEval } from "../../eval/run.ts";
 import type { EvalResult } from "../../eval/run.ts";
 import { EvalsFileError, loadEvalsFile } from "../../eval/schema.ts";
+import { parseTimeoutSeconds } from "../args.ts";
 import { commandMeta } from "../command-meta.ts";
 import { reportInternalError } from "../internal-error.ts";
 import { flushStdout, logger, reportDiagnostics } from "../log.ts";
@@ -88,16 +89,18 @@ const parseFlags = (args: EvalFlags) => {
     process.exit(1);
   }
   const threshold = args.threshold === undefined ? 1 : Number(args.threshold);
-  if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+  // A bare `--threshold` (or `--threshold $UNSET_VAR`) arrives as "", which
+  // `Number` reads as 0 — a gate that passes every run — so it's rejected.
+  if (
+    args.threshold?.trim() === "" ||
+    !Number.isFinite(threshold) ||
+    threshold < 0 ||
+    threshold > 1
+  ) {
     logger.error(`Invalid --threshold "${args.threshold}" (use 0..1).`);
     process.exit(1);
   }
-  const timeoutS =
-    args.timeout === undefined ? DEFAULT_TIMEOUT_S : Number(args.timeout);
-  if (!Number.isInteger(timeoutS) || timeoutS <= 0) {
-    logger.error(`Invalid --timeout "${args.timeout}" (whole seconds).`);
-    process.exit(1);
-  }
+  const timeoutS = parseTimeoutSeconds(args.timeout, DEFAULT_TIMEOUT_S);
   return { agent: args.agent, threshold, timeoutS };
 };
 
@@ -125,7 +128,7 @@ const runFixHandoff = async (
 
 /** `blume eval init`: draft a starter evals file via the interactive agent. */
 const runInit = async (agent: AgentKind, file: string): Promise<void> => {
-  const path = join(process.cwd(), file);
+  const path = resolve(process.cwd(), file);
   if (existsSync(path)) {
     logger.error(
       `${file} already exists — edit it directly, or pass --file to draft elsewhere.`
@@ -193,7 +196,9 @@ export const evalCommand = defineCommand({
       // and never regenerates the runtime, so it doesn't contend with a
       // running dev server. Same reasoning as `blume audit`.
       const project = await scanProject(root, { mode: "build" });
-      const evalsPath = join(root, args.file);
+      // `resolve`, not `join`: an absolute `--file` (`/ci/evals.yaml`) is
+      // used as given instead of being nested under the project root.
+      const evalsPath = resolve(root, args.file);
       const { evals, raw } = await loadEvalsFile(evalsPath);
 
       process.stderr.write(`${headerLine(evals.questions.length, agent)}\n\n`);
@@ -270,7 +275,10 @@ export const evalCommand = defineCommand({
     }
 
     if (failed) {
-      process.exit(1);
+      // Set the code and return rather than `process.exit`, which doesn't wait
+      // for a piped stderr: a long `--verbose` report was cut off mid-write, in
+      // exactly the CI logs that need to show every failure.
+      process.exitCode = 1;
     }
   },
 });

package/src/cli/commands/skill.ts

@@ -0,0 +1,96 @@
+import { defineCommand } from "citty";
+import { join } from "pathe";
+
+import {
+  planSkill,
+  WRITE_SKILL_DIR,
+  writeSkillPrompt,
+} from "../../ai/write-skill.ts";
+import { AGENTS, launchInstalledAgent } from "../../audit/agent.ts";
+import type { AgentKind } from "../../audit/agent.ts";
+import { BlumeError } from "../../core/diagnostics.ts";
+import { packageRoot } from "../../core/package-root.ts";
+import { scanProject } from "../../core/project-graph.ts";
+import { getBlumeVersion } from "../../core/version.ts";
+import { commandMeta } from "../command-meta.ts";
+import { reportInternalError } from "../internal-error.ts";
+import { logger, reportDiagnostics } from "../log.ts";
+
+/**
+ * `blume skill` — write the docs site's agent skill with a coding agent. Every
+ * build publishes a generated skill at `/skill.md` (a map of the docs); this
+ * opens Claude Code or Codex on the `blume-write-skill` skill bundled in this
+ * package to write the richer one, grounded in the docs, under the same name
+ * so it takes the generated one's place. The judgment stays in the skill; the
+ * command is the front door, like `blume migrate`. Status lines go straight to
+ * stderr: consola drops info-level lines in test and CI environments.
+ */
+export const skillCommand = defineCommand({
+  args: {
+    claude: {
+      description: "Write the skill with Claude Code.",
+      type: "boolean",
+    },
+    codex: {
+      description: "Write the skill with Codex.",
+      type: "boolean",
+    },
+  },
+  meta: commandMeta.skill,
+  async run({ args }) {
+    const root = process.cwd();
+    // SAFETY: AGENTS is a closed record keyed by AgentKind, so its keys are
+    // exactly the agent kinds.
+    const agents = (Object.keys(AGENTS) as AgentKind[]).filter(
+      (kind) => args[kind]
+    );
+    if (agents.length > 1) {
+      logger.error("Pass at most one of --codex or --claude.");
+      process.exit(1);
+    }
+    const [agent] = agents;
+
+    try {
+      // A scan, not `prepareProject`: the agent reads the content tree and
+      // the runtime isn't touched, so a running dev server is left alone.
+      const plan = planSkill(await scanProject(root, { mode: "build" }));
+      const skillDir = join(packageRoot(), WRITE_SKILL_DIR);
+      process.stderr.write(
+        `  ${plan.exists ? "Updating" : "Writing"} the "${plan.name}" skill at ${plan.file}.\n`
+      );
+
+      // Without an agent flag the command is the pointer for any other agent:
+      // the bundled skill's path, and the install line that puts the skill
+      // where agents look for it.
+      if (!agent) {
+        process.stderr.write(
+          `  blume skill writes it with a coding agent: rerun with --codex or --claude.\n  Using another agent? Point it at ${join(skillDir, "SKILL.md")},\n  or install the skill where your agent looks for skills: npx skills add haydenbleasel/blume --skill blume-write-skill\n`
+        );
+        return;
+      }
+
+      const cli = AGENTS[agent];
+      process.stderr.write(`  Handing it to ${cli.name}…\n\n`);
+      const code = await launchInstalledAgent(
+        cli.bin,
+        writeSkillPrompt(plan, { skillDir, version: getBlumeVersion() })
+      );
+      if (code === null) {
+        logger.error(
+          `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
+        );
+        process.exit(1);
+      }
+      if (code !== 0) {
+        process.exit(code);
+      }
+    } catch (error) {
+      if (error instanceof BlumeError) {
+        reportDiagnostics([error.diagnostic], root);
+        process.exit(1);
+      }
+      reportInternalError(error);
+      process.exit(1);
+    }
+  },
+});