agent-relay-server 0.32.4 → 0.33.1

package/src/cli/provider.ts

@@ -0,0 +1,209 @@
+// Provider shim commands — auto-split from cli.ts (#294). `provider wrap|unwrap`
+// installs/removes the claude/codex PATH shims, and prunes legacy Codex
+// SessionStart hook entries left by older versions (migration cruft, still wired
+// because re-wrapping must clean a previously-hooked ~/.codex/config.toml).
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export async function handleProviderCommand(args: string[]): Promise<void> {
+  const action = args[0];
+  const provider = args[1];
+  if ((action !== "wrap" && action !== "unwrap") || (provider !== "claude" && provider !== "codex")) {
+    throw new Error("Usage: agent-relay provider <wrap|unwrap> <claude|codex>");
+  }
+  const dir = join(process.env.HOME || homedir(), ".agent-relay", "bin");
+  const shims = providerShimPaths(provider);
+  if (provider === "codex") cleanLegacyCodexSessionStartHook();
+  if (action === "wrap") {
+    for (const shim of shims) {
+      mkdirSync(dirname(shim), { recursive: true });
+      writeFileSync(shim, providerShimContent(provider), "utf8");
+      chmodSync(shim, 0o755);
+      console.log(`Wrapped ${provider}: ${shim}`);
+    }
+    console.log(`Ensure ${dir} is before the provider binary on PATH.`);
+    return;
+  }
+  for (const shim of shims) {
+    if (existsSync(shim)) unlinkSync(shim);
+    console.log(`Unwrapped ${provider}: ${shim}`);
+  }
+}
+
+function cleanLegacyCodexSessionStartHook(): void {
+  const configPath = join(process.env.HOME || homedir(), ".codex", "config.toml");
+  if (!existsSync(configPath)) return;
+  const before = readFileSync(configPath, "utf8");
+  const after = removeLegacyCodexSessionStartHookToml(before);
+  if (after === before) return;
+  writeFileSync(configPath, after, "utf8");
+  console.log(`Removed legacy Agent Relay Codex hook entries from ${configPath}`);
+}
+
+export function removeLegacyCodexSessionStartHookToml(input: string): string {
+  const blocks = tomlHookBlocks(input);
+  let output = "";
+  for (let index = 0; index < blocks.length;) {
+    const block = blocks[index];
+    if (isCodexHookGroupHeader(block?.header)) {
+      const group = block!;
+      const hooks: typeof blocks = [];
+      const hookHeader = codexHookHandlerHeader(group.header!);
+      index += 1;
+      while (index < blocks.length && blocks[index]?.header?.trim() === hookHeader) {
+        hooks.push(blocks[index]!);
+        index += 1;
+      }
+
+      const keptHooks = hooks.filter((hook) => !isLegacyCodexSessionStartHook(hook.text));
+      const groupIsLegacyOnly = isLegacyCodexSessionStartHook(group.text) || (hooks.length > 0 && keptHooks.length === 0);
+      if (!groupIsLegacyOnly || keptHooks.length > 0) {
+        output += `${group.text}\n`;
+        for (const hook of keptHooks) output += `${hook.text}\n`;
+      }
+      continue;
+    }
+
+    if (isCodexHookHandlerHeader(block?.header) && isLegacyCodexSessionStartHook(block?.text ?? "")) {
+      index += 1;
+      continue;
+    }
+
+    if (block) output += `${block.text}\n`;
+    index += 1;
+  }
+  return output.trimEnd() + "\n";
+}
+
+function tomlHookBlocks(input: string): Array<{ header: string | null; text: string }> {
+  const lines = input.split(/\r?\n/);
+  const blocks: Array<{ header: string | null; text: string }> = [];
+  let current: { header: string | null; lines: string[] } = { header: null, lines: [] };
+  for (const line of lines) {
+    const header = line.match(/^\s*\[\[hooks\.[^\]]+\]\]\s*$/)?.[0] ?? null;
+    if (header) {
+      if (current.lines.length > 0) blocks.push({ header: current.header, text: current.lines.join("\n").trimEnd() });
+      current = { header, lines: [line] };
+    } else {
+      current.lines.push(line);
+    }
+  }
+  if (current.lines.length > 0) blocks.push({ header: current.header, text: current.lines.join("\n").trimEnd() });
+  return blocks.filter((block) => block.text.trim().length > 0);
+}
+
+function isCodexHookGroupHeader(header: string | null | undefined): boolean {
+  return /^\[\[hooks\.[^.]+\]\]$/.test(header?.trim() ?? "");
+}
+
+function isCodexHookHandlerHeader(header: string | null | undefined): boolean {
+  return /^\[\[hooks\.[^.]+\.hooks\]\]$/.test(header?.trim() ?? "");
+}
+
+function codexHookHandlerHeader(groupHeader: string): string {
+  return groupHeader.trim().replace(/\]\]$/, ".hooks]]");
+}
+
+function isLegacyCodexSessionStartHook(text: string): boolean {
+  return /\.agent-relay\/codex\/package\/hooks\//.test(text) ||
+    /agent-relay-codex.*hook/i.test(text) ||
+    /agent-relay.*(SessionStart|UserPromptSubmit|Stop).*hook/i.test(text);
+}
+
+function providerShimPaths(provider: "claude" | "codex"): string[] {
+  const root = join(process.env.HOME || homedir(), ".agent-relay");
+  const paths = [join(root, "bin", provider)];
+  if (provider === "codex") paths.push(join(root, "codex", "bin", "codex"));
+  return paths;
+}
+
+function providerShimContent(provider: "claude" | "codex"): string {
+  if (provider === "claude") {
+    return `#!/usr/bin/env bash\nexec claude-relay claude -- "$@"\n`;
+  }
+  return `#!/usr/bin/env bash
+set -e
+
+resolve_path() {
+  if command -v realpath >/dev/null 2>&1; then
+    realpath "$1" 2>/dev/null || printf '%s\\n' "$1"
+  elif command -v readlink >/dev/null 2>&1; then
+    readlink -f "$1" 2>/dev/null || printf '%s\\n' "$1"
+  else
+    printf '%s\\n' "$1"
+  fi
+}
+
+find_real_codex() {
+  local self resolved candidate
+  self="$(resolve_path "$0")"
+  IFS=: read -r -a path_parts <<< "$PATH"
+  for dir in "\${path_parts[@]}"; do
+    candidate="$dir/codex"
+    [ -x "$candidate" ] || continue
+    resolved="$(resolve_path "$candidate")"
+    [ "$resolved" = "$self" ] && continue
+    printf '%s\\n' "$candidate"
+    return 0
+  done
+  return 1
+}
+
+first_command() {
+  local skip_next=0
+  for arg in "$@"; do
+    if [ "$skip_next" = 1 ]; then
+      skip_next=0
+      continue
+    fi
+    case "$arg" in
+      --) break ;;
+      -c|--config|--enable|--disable|-i|--image|-m|--model|--local-provider|-p|--profile|-s|--sandbox|-C|--cd|--add-dir|-a|--ask-for-approval|--remote|--remote-auth-token-env)
+        skip_next=1
+        ;;
+      --config=*|--enable=*|--disable=*|--image=*|--model=*|--local-provider=*|--profile=*|--sandbox=*|--cd=*|--add-dir=*|--ask-for-approval=*|--remote=*|--remote-auth-token-env=*)
+        ;;
+      -*)
+        ;;
+      *)
+        printf '%s\\n' "$arg"
+        return 0
+        ;;
+    esac
+  done
+  return 0
+}
+
+has_passthrough_option() {
+  for arg in "$@"; do
+    case "$arg" in
+      -h|--help|-V|--version)
+        return 0
+        ;;
+    esac
+  done
+  return 1
+}
+
+exec_real_codex() {
+  real_codex="$(find_real_codex)" || {
+    echo "agent-relay codex shim could not find the real codex binary on PATH" >&2
+    exit 127
+  }
+  exec "$real_codex" "$@"
+}
+
+if has_passthrough_option "$@"; then
+  exec_real_codex "$@"
+fi
+
+case "$(first_command "$@")" in
+  exec|e|review|login|logout|mcp|plugin|mcp-server|app-server|remote-control|completion|update|sandbox|debug|apply|a|cloud|exec-server|features|help)
+    exec_real_codex "$@"
+    ;;
+esac
+
+exec codex-relay codex -- "$@"
+`;
+}

package/src/cli/recipe.ts

@@ -0,0 +1,110 @@
+// Recipe commands — auto-split from cli.ts (#294). list/show/start/stop/status for
+// multi-agent recipes.
+import { apiRequest } from "./_shared";
+
+export async function handleRecipeCommand(args: string[]): Promise<void> {
+  const action = args[0] ?? "list";
+  const rest = args.slice(1);
+  if (action === "list") {
+    const json = rest.includes("--json");
+    const recipes = await apiRequest("GET", "/api/recipes");
+    if (json) console.log(JSON.stringify(recipes, null, 2));
+    else console.log(formatRecipes(recipes as any[]));
+    return;
+  }
+  if (action === "show") {
+    const name = rest.find((arg) => !arg.startsWith("--"));
+    const json = rest.includes("--json");
+    if (!name) throw new Error("Usage: agent-relay recipe show NAME [--json]");
+    const recipe = await apiRequest("GET", `/api/recipes/${encodeURIComponent(name)}`);
+    if (json) console.log(JSON.stringify(recipe, null, 2));
+    else console.log(formatRecipe(recipe as any));
+    return;
+  }
+  if (action === "start") {
+    const name = rest[0];
+    if (!name || name.startsWith("--")) throw new Error("Usage: agent-relay recipe start NAME [--cwd PATH] [--orchestrator ID] [--by NAME] [--json]");
+    let cwd: string | undefined;
+    let orchestratorId: string | undefined;
+    let startedBy: string | undefined;
+    let json = false;
+    for (let i = 1; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--cwd" && i + 1 < rest.length) cwd = rest[++i];
+      else if ((arg === "--orchestrator" || arg === "--orchestrator-id") && i + 1 < rest.length) orchestratorId = rest[++i];
+      else if (arg === "--by" && i + 1 < rest.length) startedBy = rest[++i];
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown recipe start option "${arg}"`);
+    }
+    const result = await apiRequest("POST", "/api/recipes/start", { name, cwd, orchestratorId, startedBy });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else {
+      const payload = result as any;
+      console.log(`Recipe ${payload.instance.recipeName} started: ${payload.instance.id} (${payload.commands.length} command(s))`);
+    }
+    return;
+  }
+  if (action === "stop") {
+    const id = rest[0];
+    if (!id || id.startsWith("--")) throw new Error("Usage: agent-relay recipe stop INSTANCE_ID [--by NAME] [--json]");
+    let stoppedBy: string | undefined;
+    let json = false;
+    for (let i = 1; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--by" && i + 1 < rest.length) stoppedBy = rest[++i];
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown recipe stop option "${arg}"`);
+    }
+    const result = await apiRequest("POST", `/api/recipes/instances/${encodeURIComponent(id)}/stop`, { stoppedBy });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else {
+      const payload = result as any;
+      console.log(`Recipe ${payload.instance.recipeName} stopped: ${payload.instance.id} (${payload.commands.length} command(s))`);
+    }
+    return;
+  }
+  if (action === "status" || action === "instances") {
+    const json = rest.includes("--json");
+    const instances = await apiRequest("GET", "/api/recipes/instances");
+    if (json) console.log(JSON.stringify(instances, null, 2));
+    else console.log(formatRecipeInstances(instances as any[]));
+    return;
+  }
+  throw new Error("Usage: agent-relay recipe <list|show|start|stop|status> [options]");
+}
+
+function formatRecipes(recipes: any[]): string {
+  if (!recipes.length) return "No recipes.";
+  return recipes
+    .map((entry) => {
+      const recipe = entry.recipe ?? {};
+      const agents = Array.isArray(recipe.agents)
+        ? recipe.agents.map((agent: any) => `${agent.count ?? 1}x ${agent.provider}:${agent.role}`).join(", ")
+        : "no agents";
+      return `${entry.name}  ${entry.source}  ${agents}  ${recipe.description ?? ""}`.trim();
+    })
+    .join("\n");
+}
+
+function formatRecipe(entry: any): string {
+  const recipe = entry.recipe ?? {};
+  const agents = Array.isArray(recipe.agents)
+    ? recipe.agents.map((agent: any) => `  - ${agent.count ?? 1}x ${agent.provider}:${agent.role}`).join("\n")
+    : "  (none)";
+  return [
+    `${entry.name} (${entry.source})`,
+    recipe.description,
+    "Agents:",
+    agents,
+  ].filter(Boolean).join("\n");
+}
+
+function formatRecipeInstances(instances: any[]): string {
+  if (!instances.length) return "No recipe instances.";
+  return instances
+    .map((instance) => {
+      const agents = Array.isArray(instance.agents) ? instance.agents.length : 0;
+      return `${instance.id}  ${instance.status}  ${instance.recipeName}  agents=${agents}  cwd=${instance.cwd}`;
+    })
+    .join("\n");
+}

package/src/cli/reply.ts

@@ -0,0 +1,141 @@
+// Reply command — auto-split from cli.ts (#294). Replies to a message by id
+// (auto-routes to the sender). Large bodies are uploaded as an artifact and sent
+// as a concise attached reply.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { MAX_BODY_BYTES } from "../config";
+import { apiRawRequest, apiRequest, encodedLength, readStdin, truncateText } from "./_shared";
+import { detectAgentId } from "./agent-detect";
+
+export async function handleReplyCommand(args: string[]): Promise<void> {
+  const msgIdRaw = args[0];
+  if (!msgIdRaw || msgIdRaw.startsWith("--")) {
+    throw new Error("Usage: agent-relay /reply <messageId> <body|--stdin|--body-file PATH> [--from AGENT_ID] [--subject TEXT] [--format text|markdown|markdownv2] [--json]");
+  }
+  const replyTo = Number.parseInt(msgIdRaw, 10);
+  if (!Number.isFinite(replyTo) || replyTo <= 0) throw new Error("messageId must be a positive integer");
+
+  let from = await detectAgentId();
+  let subject: string | undefined;
+  let format: string | undefined;
+  let json = false;
+  let stdinBody = false;
+  let bodyFile: string | undefined;
+  const bodyParts: string[] = [];
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--from" && i + 1 < args.length) from = args[++i];
+    else if (arg === "--subject" && i + 1 < args.length) subject = args[++i];
+    else if (arg === "--stdin") stdinBody = true;
+    else if ((arg === "--body-file" || arg === "--file") && i + 1 < args.length) bodyFile = args[++i];
+    else if (arg === "--format" && i + 1 < args.length) {
+      const parsed = parseReplyFormat(args[++i]!);
+      if (!parsed) throw new Error("--format must be text, markdown, or markdownv2");
+      format = parsed;
+    }
+    else if (arg === "--json") json = true;
+    else bodyParts.push(arg!);
+  }
+
+  const body = (await resolveBodyInput({ bodyParts, stdinBody, bodyFile })).trim();
+  if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
+  if (!body) throw new Error("Reply body required.");
+
+  const prepared = await prepareReplyBody({ body, from, replyTo, format, subject });
+  const message = await apiRequest("POST", "/api/messages", {
+    from,
+    body: prepared.body,
+    subject: prepared.subject,
+    replyTo,
+    attachments: prepared.attachments,
+    payload: prepared.payload,
+  });
+  const msg = message as any;
+  if (json) console.log(JSON.stringify(msg, null, 2));
+  else console.log(`Reply sent: ${msg.id} -> ${msg.to} (reply to #${replyTo})`);
+}
+
+function parseReplyFormat(value: string): "text" | "markdown" | "markdownv2" | undefined {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "text" || normalized === "markdown" || normalized === "markdownv2") return normalized;
+  return undefined;
+}
+
+const MAX_DIRECT_REPLY_BODY_BYTES = Math.floor(MAX_BODY_BYTES * 0.75);
+
+async function resolveBodyInput(options: {
+  bodyParts: string[];
+  stdinBody: boolean;
+  bodyFile?: string;
+}): Promise<string> {
+  const sources = [
+    options.bodyParts.length > 0 ? "argv" : "",
+    options.stdinBody ? "stdin" : "",
+    options.bodyFile ? "body file" : "",
+  ].filter(Boolean);
+  if (sources.length > 1) throw new Error("Reply body must come from exactly one source: arguments, --stdin, or --body-file.");
+  if (options.stdinBody) return readStdin();
+  if (options.bodyFile) return readFileSync(resolve(options.bodyFile), "utf8");
+  return options.bodyParts.join(" ");
+}
+
+async function prepareReplyBody(options: {
+  body: string;
+  from: string;
+  replyTo: number;
+  format?: string;
+  subject?: string;
+}): Promise<{
+  body: string;
+  subject?: string;
+  attachments?: Array<Record<string, unknown>>;
+  payload?: Record<string, unknown>;
+}> {
+  const payload: Record<string, unknown> = options.format ? { message: { format: options.format } } : {};
+  if (encodedLength(options.body) <= MAX_DIRECT_REPLY_BODY_BYTES) {
+    return {
+      body: options.body,
+      subject: options.subject,
+      payload: Object.keys(payload).length ? payload : undefined,
+    };
+  }
+
+  const filename = `relay-reply-${options.replyTo}-${Date.now()}.${options.format === "markdown" ? "md" : "txt"}`;
+  const artifact = await apiRawRequest("POST", "/api/artifacts", options.body, {
+    "Content-Type": options.format === "markdown" ? "text/markdown; charset=utf-8" : "text/plain; charset=utf-8",
+    "X-Artifact-Filename": filename,
+    "X-Artifact-Kind": "document",
+    "X-Artifact-Sensitivity": "normal",
+  }) as { id: string; size?: number };
+  const preview = truncateText(options.body, 1800);
+  const body = [
+    `Full reply attached as Agent Relay artifact ${artifact.id} (${filename}).`,
+    "",
+    "Preview:",
+    preview,
+  ].join("\n");
+  return {
+    body,
+    subject: options.subject ?? "Long reply attached",
+    attachments: [{
+      artifactId: artifact.id,
+      kind: "document",
+      role: "report",
+      title: "Full reply",
+      metadata: {
+        source: "agent-relay-cli",
+        replyTo: options.replyTo,
+        originalBytes: encodedLength(options.body),
+      },
+    }],
+    payload: {
+      ...payload,
+      relay: {
+        longReply: true,
+        artifactId: artifact.id,
+        originalBytes: encodedLength(options.body),
+      },
+    },
+  };
+}

package/src/cli/setup.ts

@@ -0,0 +1,57 @@
+// Setup command — auto-split from cli.ts (#294). Generates the relay env file.
+import { createSetupPlan, executeSetupPlan, formatSetupPlan, pathExists } from "../setup";
+import { confirm } from "./_shared";
+
+export async function handleSetupCommand(args: string[]): Promise<void> {
+  let envFile: string | undefined;
+  let host: string | undefined;
+  let port: number | undefined;
+  let dbPath: string | undefined;
+  let runtimePrefix: string | undefined;
+  let token: string | undefined;
+  let generateToken = true;
+  let dryRun = false;
+  let force = false;
+  let yes = false;
+  let json = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--env-file" && i + 1 < args.length) envFile = args[++i];
+    else if (arg === "--host" && i + 1 < args.length) host = args[++i];
+    else if (arg === "--port" && i + 1 < args.length) port = parseInt(args[++i]!, 10);
+    else if (arg === "--db-path" && i + 1 < args.length) dbPath = args[++i];
+    else if (arg === "--runtime-prefix" && i + 1 < args.length) runtimePrefix = args[++i];
+    else if (arg === "--token" && i + 1 < args.length) token = args[++i];
+    else if (arg === "--generate-token") generateToken = true;
+    else if (arg === "--no-token") generateToken = false;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--force") force = true;
+    else if (arg === "--yes") yes = true;
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown setup option "${arg}"`);
+  }
+
+  const plan = createSetupPlan({
+    ...(envFile ? { envFile } : {}),
+    ...(host ? { host } : {}),
+    ...(port !== undefined ? { port } : {}),
+    ...(dbPath ? { dbPath } : {}),
+    ...(runtimePrefix ? { runtimePrefix } : {}),
+    ...(token ? { token } : {}),
+    generateToken,
+    force,
+  });
+
+  if (!dryRun && !yes && await pathExists(plan.envFile)) {
+    const ok = await confirm(`Overwrite ${plan.envFile}?`);
+    if (!ok) {
+      console.log("Setup cancelled.");
+      return;
+    }
+  }
+
+  const result = await executeSetupPlan(plan, { dryRun, force });
+  if (json) console.log(JSON.stringify({ plan, output: result }, null, 2));
+  else console.log(dryRun ? formatSetupPlan(plan) : result);
+}

package/src/cli/steward.ts

@@ -0,0 +1,59 @@
+// Steward commands — auto-split from cli.ts (#294). Briefing rail for the steward
+// (#208): the attention queue, per-workspace diagnostics, and check suggestions.
+import { apiRequest } from "./_shared";
+
+// Steward briefing commands (#208): queue of workspaces needing attention, a
+// per-workspace diagnostics inspection, and a check-command suggestion.
+export async function handleStewardCommand(args: string[]): Promise<void> {
+  const action = args[0];
+  if (!action || !["queue", "inspect", "checks"].includes(action)) {
+    throw new Error("Usage: agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]");
+  }
+
+  let repo: string | undefined;
+  let json = false;
+  const positional: string[] = [];
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--repo" && i + 1 < args.length) repo = args[++i];
+    else if (arg === "--json") json = true;
+    else if (!arg!.startsWith("--")) positional.push(arg!);
+    else throw new Error(`Unknown steward option "${arg}".`);
+  }
+
+  if (action === "queue") {
+    const all = await apiRequest("GET", "/api/workspaces") as any[];
+    const attention = new Set(["conflict", "review_requested", "merge_planned"]);
+    const queue = all.filter((ws) => attention.has(ws.status) && (!repo || ws.repoRoot === repo));
+    if (json) { console.log(JSON.stringify(queue, null, 2)); return; }
+    if (!queue.length) { console.log("Steward queue empty — no workspaces awaiting review, merge, or conflict resolution."); return; }
+    for (const ws of queue) console.log(`${ws.status.padEnd(16)} ${ws.branch ?? ws.id}  (${ws.repoRoot})`);
+    return;
+  }
+
+  const id = positional[0];
+  if (!id) throw new Error(`Usage: agent-relay steward ${action} WORKSPACE_ID [--json]`);
+
+  if (action === "inspect") {
+    console.log(JSON.stringify(await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diagnostics`), null, 2));
+    return;
+  }
+
+  // checks: suggest validation commands from the workspace's changed files.
+  const diff = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diff?patch=0`) as any;
+  const files: string[] = Array.isArray(diff?.files) ? diff.files.map((f: any) => f.path) : [];
+  const checks = suggestStewardChecks(files);
+  console.log(JSON.stringify({ workspaceId: id, changedFiles: files.length, checks }, null, 2));
+}
+
+// Heuristic check suggestions from changed file paths. Repo-agnostic defaults a
+// steward can refine; cheaper than re-deriving from project docs every run.
+function suggestStewardChecks(files: string[]): Array<{ command: string; reason: string }> {
+  const checks: Array<{ command: string; reason: string }> = [];
+  const has = (re: RegExp) => files.some((f) => re.test(f));
+  if (has(/\.(ts|tsx|mts|cts)$/)) checks.push({ command: "bun run typecheck", reason: "TypeScript files changed" });
+  if (has(/\.test\.|(^|\/)tests?\//)) checks.push({ command: "bun test", reason: "test files changed" });
+  else if (files.length) checks.push({ command: "bun test", reason: "repo default" });
+  if (has(/(^|\/)dashboard\//)) checks.push({ command: "bun run build:dashboard", reason: "dashboard sources changed" });
+  return checks;
+}

package/src/cli/token.ts

@@ -0,0 +1,81 @@
+// Token commands — auto-split from cli.ts (#294). create/list/revoke/verify for
+// component JWTs.
+import { apiRequest, splitTagArgs } from "./_shared";
+
+export async function handleTokenCommand(args: string[]): Promise<void> {
+  const action = args[0] ?? "list";
+  const rest = args.slice(1);
+  if (action === "list") {
+    const json = rest.includes("--json");
+    const tokens = await apiRequest("GET", "/api/tokens");
+    if (json) console.log(JSON.stringify(tokens, null, 2));
+    else console.log(formatTokens(tokens as any[]));
+    return;
+  }
+  if (action === "create") {
+    let role: string | undefined;
+    let sub: string | undefined;
+    let ttlSeconds: number | undefined;
+    let json = false;
+    let scope: string[] | undefined;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--role" && i + 1 < rest.length) role = rest[++i];
+      else if (arg === "--sub" && i + 1 < rest.length) sub = rest[++i];
+      else if ((arg === "--scope" || arg === "--scopes") && i + 1 < rest.length) scope = splitTagArgs(rest[++i]!);
+      else if ((arg === "--ttl" || arg === "--ttl-seconds") && i + 1 < rest.length) ttlSeconds = parseInt(rest[++i]!, 10);
+      else if (arg === "--json") json = true;
+      else throw new Error(`Unknown token create option "${arg}"`);
+    }
+    if (!role) throw new Error("Usage: agent-relay token create --role ROLE [--sub SUBJECT] [--scope a,b] [--ttl SECONDS]");
+    const result = await apiRequest("POST", "/api/tokens", { role, sub, scope, ttlSeconds, createdBy: "cli" });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else {
+      const payload = result as any;
+      console.log(payload.token);
+      console.error(`Issued ${payload.record.role} token ${payload.record.jti} for ${payload.record.sub}`);
+    }
+    return;
+  }
+  if (action === "revoke") {
+    const jti = rest.find((arg) => !arg.startsWith("--"));
+    if (!jti) throw new Error("Usage: agent-relay token revoke JTI");
+    await apiRequest("POST", `/api/tokens/${encodeURIComponent(jti)}/revoke`, {});
+    console.log(`Token revoked: ${jti}`);
+    return;
+  }
+  if (action === "verify") {
+    const token = rest.find((arg) => !arg.startsWith("--")) ?? process.env.AGENT_RELAY_TOKEN;
+    if (!token) throw new Error("Usage: agent-relay token verify TOKEN");
+    const payload = decodeJwtPayload(token);
+    if (!payload) throw new Error("not a component JWT");
+    let record: unknown = null;
+    if (typeof payload.jti === "string") {
+      record = await apiRequest("GET", `/api/tokens/${encodeURIComponent(payload.jti)}`).catch(() => null);
+    }
+    console.log(JSON.stringify({ payload, record }, null, 2));
+    return;
+  }
+  throw new Error("Usage: agent-relay token <create|list|revoke|verify> [options]");
+}
+
+function formatTokens(tokens: any[]): string {
+  if (!tokens.length) return "No component tokens.";
+  return tokens
+    .map((token) => {
+      const state = token.revokedAt ? "revoked" : token.expiresAt && token.expiresAt <= Math.floor(Date.now() / 1000) ? "expired" : "active";
+      return `${token.jti}  ${state}  ${token.role}  ${token.sub}  ${(token.scope ?? []).join(",")}`;
+    })
+    .join("\n");
+}
+
+function decodeJwtPayload(token: string): Record<string, unknown> | null {
+  const payload = token.split(".")[1];
+  if (!payload) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}