@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/commands/agents.ts

@@ -1,923 +0,0 @@
-/**
- * `hq agents` — manage a company's cloud (fleet) agents from the terminal
- * instead of the web console. Mirrors the console's `AgentsClient`
- * (hq-console `src/lib/agents-client.ts`), targeting the hq-pro `/v1/agents`
- * control plane on `DEFAULT_VAULT_API_URL` via the shared `vaultApiFetch`
- * helper. No new HTTP client, no console-SDK import — same auth + company
- * resolution stack as `members.ts`.
- *
- * Subcommands:
- *   hq agents list                 — roster for the company
- *   hq agents status <uid>         — setup state + runtime detail
- *   hq agents rename <uid> <name>  — set the agent's display name
- *   hq agents set <uid> [...]      — patch profile (name/title/description)
- *   hq agents config <uid> [...]   — patch runtime config (model/effort/tier)
- *   hq agents start|stop <uid>     — EC2 start/stop
- *   hq agents retry <uid>          — resume setup from first non-done step
- *   hq agents rm <uid> --yes       — deprovision (destructive; flag-guarded)
- *
- * Agents are company-scoped. `--company <slug>` may sit on the group
- * (`hq agents --company acme list`) or on a subcommand
- * (`hq agents list --company acme`); when omitted, resolution falls back to
- * the caller's single active membership (same as `members.ts`).
- */
-
-import { Command } from "commander";
-import chalk from "chalk";
-import { randomUUID } from "node:crypto";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
-import {
-  AGENT_PRICE_CENTS,
-  confirmChargeOrExit,
-  parseBillingPayload,
-  surfaceBillingBlocked,
-  type BillingErrorPayload,
-} from "../utils/billing-gate.js";
-
-/** Reasoning-effort values hq-pro accepts on `runtime-config`. */
-export const VALID_EFFORTS = new Set([
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-]);
-/** Service-tier (speed) values hq-pro accepts on `runtime-config`. */
-export const VALID_TIERS = new Set(["default", "priority"]);
-
-/**
- * A non-2xx from the `/v1/agents` control plane. Carries the HTTP status and
- * the registry error `code` (when present) so callers can branch — notably a
- * 404 on `list`, which hq-pro returns for a company that has the agents
- * feature flag OFF (`src/agents/feature-flag.ts`).
- */
-export class AgentsHttpError extends Error {
-  status: number;
-  code?: string;
-  /** hq-pro's billing envelope on a `402 billing_required` provision block. */
-  billing?: BillingErrorPayload;
-  constructor(
-    status: number,
-    message: string,
-    code?: string,
-    billing?: BillingErrorPayload,
-  ) {
-    super(message);
-    this.name = "AgentsHttpError";
-    this.status = status;
-    this.code = code;
-    this.billing = billing;
-  }
-}
-
-/** Roster row from `GET /v1/agents` — a superset is returned; we keep what we render. */
-export interface CompanyAgentView {
-  uid: string;
-  name: string;
-  slug: string;
-  companyUid: string;
-  entityStatus?: string;
-  agentStatus?: string;
-  setupPhase?: string;
-  provider?: string;
-  codexModel?: string;
-  codexReasoningEffort?: string;
-  codexServiceTier?: string;
-  profile?: {
-    displayName?: string;
-    title?: string;
-    description?: string;
-  };
-  [key: string]: unknown;
-}
-
-export interface ProfilePatch {
-  displayName?: string;
-  title?: string;
-  description?: string;
-}
-
-export interface RuntimeConfigPatch {
-  codexModel?: string;
-  codexReasoningEffort?: string;
-  codexServiceTier?: string;
-}
-
-/**
- * Authenticated JSON round-trip against the agents control plane. Throws
- * `AgentsHttpError` on any non-2xx (never swallows — hq-never-swallow-errors),
- * decoding hq-pro's `{ error | message, code }` envelope for the reason.
- */
-export async function agentsRequest<T>(opts: {
-  token: string;
-  path: string;
-  method?: string;
-  body?: Record<string, unknown>;
-  query?: Record<string, string>;
-}): Promise<T> {
-  const res = await vaultApiFetch(opts);
-  if (!res.ok) {
-    const body = (await res.json().catch(() => ({}))) as {
-      error?: string;
-      message?: string;
-      code?: string;
-    };
-    throw new AgentsHttpError(
-      res.status,
-      // `message` FIRST: on a payment_failed envelope it carries the friendly
-      // decline copy ("Your card was declined…") while `error` is the generic
-      // "payment required" — error-first would feed surfaceBillingBlocked the
-      // generic string and lose the decline reason (mirrors outpostRequest).
-      body.message ?? body.error ?? res.statusText,
-      body.code,
-      parseBillingPayload(body),
-    );
-  }
-  return (await res.json()) as T;
-}
-
-/** Slugify an agent name into a lowercase, hyphen-separated slug. */
-export function slugifyAgentName(name: string): string {
-  return name
-    .toLowerCase()
-    .trim()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-}
-
-export interface ProvisionAgentInput {
-  companyUid: string;
-  name: string;
-  slug: string;
-  codexAuthMode: "subscription" | "apiKey";
-  provider?: "codex" | "grok";
-  codexApiKey?: string;
-  idempotencyKey: string;
-  title?: string;
-  description?: string;
-}
-
-export async function provisionAgent(
-  token: string,
-  input: ProvisionAgentInput,
-): Promise<{ uid?: string; slug?: string; [key: string]: unknown }> {
-  return agentsRequest({
-    token,
-    path: "/v1/agents",
-    method: "POST",
-    body: input as unknown as Record<string, unknown>,
-  });
-}
-
-export async function listAgents(
-  token: string,
-  companyUid: string,
-): Promise<CompanyAgentView[]> {
-  const data = await agentsRequest<{ agents: CompanyAgentView[] }>({
-    token,
-    path: "/v1/agents",
-    query: { companyUid },
-  });
-  return data.agents ?? [];
-}
-
-export async function getAgentStatus(
-  token: string,
-  agentUid: string,
-): Promise<Record<string, unknown>> {
-  return agentsRequest({
-    token,
-    path: `/v1/agents/${encodeURIComponent(agentUid)}/status`,
-  });
-}
-
-export async function patchAgentProfile(
-  token: string,
-  agentUid: string,
-  patch: ProfilePatch,
-): Promise<{
-  uid: string;
-  profile: ProfilePatch;
-  slackUpdated: boolean;
-}> {
-  return agentsRequest({
-    token,
-    path: `/v1/agents/${encodeURIComponent(agentUid)}/profile`,
-    method: "PATCH",
-    body: patch as Record<string, unknown>,
-  });
-}
-
-export async function patchAgentRuntimeConfig(
-  token: string,
-  agentUid: string,
-  patch: RuntimeConfigPatch,
-): Promise<{
-  uid: string;
-  codexModel?: string;
-  codexReasoningEffort?: string;
-  codexServiceTier?: string;
-  applied: boolean;
-}> {
-  return agentsRequest({
-    token,
-    path: `/v1/agents/${encodeURIComponent(agentUid)}/runtime-config`,
-    method: "PATCH",
-    body: patch as Record<string, unknown>,
-  });
-}
-
-export async function startStopAgent(
-  token: string,
-  agentUid: string,
-  action: "start" | "stop",
-): Promise<{ uid: string; runtime?: Record<string, unknown> }> {
-  return agentsRequest({
-    token,
-    path: `/v1/agents/${encodeURIComponent(agentUid)}/${action}`,
-    method: "POST",
-  });
-}
-
-export async function retryAgent(
-  token: string,
-  agentUid: string,
-): Promise<Record<string, unknown>> {
-  return agentsRequest({
-    token,
-    path: `/v1/agents/${encodeURIComponent(agentUid)}/retry`,
-    method: "POST",
-  });
-}
-
-export async function deprovisionAgent(
-  token: string,
-  agentUid: string,
-): Promise<{ uid: string; setupState?: string; terminal?: boolean }> {
-  return agentsRequest({
-    token,
-    path: `/v1/agents/${encodeURIComponent(agentUid)}`,
-    method: "DELETE",
-  });
-}
-
-/** Human-readable "hot-applied to the running box" vs "saved for next launch". */
-export function appliedHint(applied: boolean): string {
-  return applied
-    ? "applied to the running box now"
-    : "saved — takes effect on the agent's next launch";
-}
-
-// ---------------------------------------------------------------------------
-// Talking to agents (DM). Agents are members addressable over HQ's DM system:
-// a message rides `POST /v1/notify/dm` (the wire contract accepts `agt_*`), the
-// agent's box picks it up and replies over DM (a first-class agent reply
-// channel), and the two-way conversation is read back via `GET /v1/notify/thread`.
-// ---------------------------------------------------------------------------
-
-/** Agent uid shape (`agt_…`). */
-const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
-
-/** One message in a DM thread, as returned by `GET /v1/notify/thread`. */
-export interface DmThreadMessage {
-  eventId: string;
-  fromPersonUid: string;
-  fromDisplayName?: string;
-  fromEmail?: string;
-  body: string;
-  createdAt: string;
-  /** "out" = sent by the caller; "in" = received (the agent's reply). */
-  direction: "in" | "out";
-}
-
-/**
- * Resolve an agent reference to its `agt_` uid. An `agt_…` value is used
- * directly; anything else is treated as a slug or display name and resolved
- * against the company's roster (requires `--company` or a single active
- * membership).
- */
-export async function resolveAgentUid(
-  token: string,
-  ref: string,
-  companySlug: string | undefined,
-): Promise<string> {
-  if (AGENT_UID_PATTERN.test(ref.trim())) return ref.trim();
-  const companyUid = await getCompanyUid(token, companySlug);
-  const roster = await listAgents(token, companyUid);
-  const needle = ref.trim().toLowerCase();
-  const match = roster.find(
-    (a) =>
-      a.slug?.toLowerCase() === needle ||
-      a.name?.toLowerCase() === needle ||
-      a.uid === ref.trim(),
-  );
-  if (!match) {
-    throw new AgentsHttpError(
-      404,
-      `No agent named "${ref}" in this company. Run \`hq agents list\` to see slugs/uids, ` +
-        `or pass the agt_ uid directly.`,
-    );
-  }
-  return match.uid;
-}
-
-/** Send a DM to an agent. Returns nothing meaningful beyond success. */
-export async function sendAgentDm(
-  token: string,
-  agentUid: string,
-  message: string,
-): Promise<void> {
-  await agentsRequest({
-    token,
-    path: "/v1/notify/dm",
-    method: "POST",
-    body: { toPersonUid: agentUid, body: message },
-  });
-}
-
-/** Read the two-way DM conversation with an agent (most recent `limit`). */
-export async function readAgentThread(
-  token: string,
-  agentUid: string,
-  limit = 20,
-): Promise<DmThreadMessage[]> {
-  const data = await agentsRequest<{ messages: DmThreadMessage[] }>({
-    token,
-    path: "/v1/notify/thread",
-    query: { withPersonUid: agentUid, limit: String(limit) },
-  });
-  return data.messages ?? [];
-}
-
-/** Render one thread message as a labeled line for the terminal. */
-export function formatThreadMessage(m: DmThreadMessage, agentLabel: string): string {
-  const who =
-    m.direction === "out"
-      ? chalk.cyan("you")
-      : chalk.magenta(m.fromDisplayName || agentLabel);
-  const when = chalk.dim(shortTime(m.createdAt));
-  return `${who} ${when}\n  ${m.body.replace(/\n/g, "\n  ")}`;
-}
-
-function shortTime(iso: string): string {
-  // Keep it dependency-free and stable: trim the ISO string to `MM-DD HH:MM`.
-  const m = iso.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}:\d{2})/);
-  return m ? `${m[2]}-${m[3]} ${m[4]}` : iso;
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-// ---------------------------------------------------------------------------
-// Command registration
-// ---------------------------------------------------------------------------
-
-function fail(err: unknown): never {
-  if (err instanceof AgentsHttpError) {
-    console.error(chalk.red(err.message));
-  } else {
-    console.error(
-      chalk.red("Error:"),
-      err instanceof Error ? err.message : String(err),
-    );
-  }
-  process.exit(1);
-}
-
-export function registerAgentsCommand(program: Command): void {
-  const agents = program
-    .command("agents")
-    .description("Manage a company's cloud (fleet) agents")
-    .option("--company <slug>", "Company slug (resolves to companyUid)");
-
-  // `--company` may live on the group or the subcommand; the subcommand value
-  // wins so `hq agents list --company acme` works as well as
-  // `hq agents --company acme list`.
-  const companyOf = (sub: Command): string | undefined =>
-    (sub.opts().company as string | undefined) ??
-    (agents.opts().company as string | undefined);
-
-  agents
-    .command("message <agent> <message...>")
-    .alias("msg")
-    .description("Send a message to an agent and wait for its reply")
-    .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
-    .option("--no-wait", "Send without waiting for the agent's reply")
-    .option("--timeout <seconds>", "How long to wait for a reply", "90")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      agent: string,
-      messageParts: string[],
-      opts: { company?: string; wait?: boolean; timeout?: string; json?: boolean },
-    ) {
-      try {
-        const message = messageParts.join(" ").trim();
-        if (!message) {
-          console.error(chalk.red("No message given. Usage: hq agents message <agent> <text>"));
-          process.exit(1);
-        }
-        const token = await ensureCognitoToken();
-        const agentUid = await resolveAgentUid(token, agent, companyOf(this));
-
-        // Baseline the conversation so we can detect the agent's NEW reply.
-        const before = opts.wait === false ? [] : await readAgentThread(token, agentUid, 1);
-        const lastBeforeAt = before.length ? before[before.length - 1].createdAt : "";
-
-        await sendAgentDm(token, agentUid, message);
-
-        if (opts.wait === false) {
-          console.log(chalk.green(`Sent to ${agent}.`));
-          console.log(chalk.dim(`Read replies later: hq agents thread ${agent}`));
-          return;
-        }
-
-        // Poll the thread until a new inbound (agent) message appears or timeout.
-        const timeoutMs = Math.max(5, Number(opts.timeout) || 90) * 1000;
-        const deadline = Date.now() + timeoutMs;
-        if (!opts.json) console.log(chalk.dim(`Sent — waiting for ${agent} to reply…`));
-        let reply: DmThreadMessage | undefined;
-        while (Date.now() < deadline) {
-          await sleep(3000);
-          const msgs = await readAgentThread(token, agentUid, 10);
-          reply = msgs.find(
-            (m) => m.direction === "in" && m.createdAt > lastBeforeAt,
-          );
-          if (reply) break;
-        }
-
-        if (opts.json) {
-          process.stdout.write(
-            JSON.stringify({ agentUid, sent: message, reply: reply ?? null }, null, 2) + "\n",
-          );
-          return;
-        }
-        if (reply) {
-          console.log(formatThreadMessage(reply, agent));
-        } else {
-          console.log(
-            chalk.yellow(
-              `No reply within ${Math.round(timeoutMs / 1000)}s. The agent may still respond — ` +
-                `check with: hq agents thread ${agent}`,
-            ),
-          );
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  agents
-    .command("thread <agent>")
-    .alias("history")
-    .description("Show your recent conversation with an agent")
-    .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
-    .option("--limit <n>", "How many recent messages to show", "20")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      agent: string,
-      opts: { company?: string; limit?: string; json?: boolean },
-    ) {
-      try {
-        const token = await ensureCognitoToken();
-        const agentUid = await resolveAgentUid(token, agent, companyOf(this));
-        const limit = Math.max(1, Number(opts.limit) || 20);
-        const msgs = await readAgentThread(token, agentUid, limit);
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(msgs, null, 2) + "\n");
-          return;
-        }
-        if (msgs.length === 0) {
-          console.log(chalk.gray(`No conversation yet with ${agent}. Start one: hq agents message ${agent} "<text>"`));
-          return;
-        }
-        console.log(msgs.map((m) => formatThreadMessage(m, agent)).join("\n\n"));
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  agents
-    .command("provision <name>")
-    .alias("new")
-    .description("Provision a new cloud agent ($100/month — requires --yes)")
-    .option("--company <slug>", "Company slug (resolves to companyUid)")
-    .option("--slug <slug>", "Agent slug (defaults to a slug of <name>)")
-    .option("--provider <provider>", "Runtime: codex | grok (default codex)")
-    .option(
-      "--auth-mode <mode>",
-      "Codex auth: subscription | apiKey (default subscription)",
-      "subscription",
-    )
-    .option(
-      "--api-key-env <VAR>",
-      "Env var holding the API key for --auth-mode apiKey (never pass the key as a flag)",
-    )
-    .option("--title <title>", "Org-chart job title")
-    .option("--description <text>", "Short description / bio")
-    .option("--yes", "Confirm the $100/month charge (required to provision)")
-    .action(async function (
-      this: Command,
-      name: string,
-      opts: {
-        slug?: string;
-        provider?: string;
-        authMode?: string;
-        apiKeyEnv?: string;
-        title?: string;
-        description?: string;
-        yes?: boolean;
-      },
-    ) {
-      try {
-        const authMode = opts.authMode === "apiKey" ? "apiKey" : "subscription";
-        const provider =
-          opts.provider === "grok" ? "grok" : opts.provider ? "codex" : undefined;
-
-        // Resolve the API key from the environment (never from a flag value) when
-        // apiKey mode is requested — validated BEFORE the paid gate so we don't
-        // charge and then fail.
-        let codexApiKey: string | undefined;
-        if (authMode === "apiKey") {
-          const envVar = opts.apiKeyEnv;
-          if (!envVar) {
-            console.error(
-              chalk.red(
-                "--auth-mode apiKey requires --api-key-env <VAR> naming the env var that holds the key.",
-              ),
-            );
-            process.exit(1);
-          }
-          codexApiKey = process.env[envVar];
-          if (!codexApiKey) {
-            console.error(
-              chalk.red(`Env var ${envVar} is empty or unset — no API key to use.`),
-            );
-            process.exit(1);
-          }
-        }
-
-        const token = await ensureCognitoToken();
-        const companyUid = await getCompanyUid(token, companyOf(this));
-
-        // Paid gate: print the monthly cost and require --yes before any call.
-        confirmChargeOrExit({
-          resource: "agent",
-          unitCents: AGENT_PRICE_CENTS,
-          yes: opts.yes,
-        });
-
-        const slug = opts.slug ?? slugifyAgentName(name);
-        try {
-          const result = await provisionAgent(token, {
-            companyUid,
-            name,
-            slug,
-            codexAuthMode: authMode,
-            ...(provider ? { provider } : {}),
-            ...(codexApiKey ? { codexApiKey } : {}),
-            idempotencyKey: `hq-cli-${randomUUID()}`,
-            ...(opts.title ? { title: opts.title } : {}),
-            ...(opts.description ? { description: opts.description } : {}),
-          });
-          const uid = typeof result.uid === "string" ? result.uid : slug;
-          console.log(chalk.green(`Provisioning started for agent "${name}".`));
-          console.log(
-            chalk.dim(`Track setup: hq agents status ${uid} --company <slug>`),
-          );
-        } catch (err) {
-          // No card on file → surface the shareable payment link instead of an
-          // opaque 402, then exit non-zero so scripts can react.
-          if (
-            err instanceof AgentsHttpError &&
-            err.status === 402 &&
-            err.billing
-          ) {
-            await surfaceBillingBlocked(token, err.billing, err.message);
-            process.exit(1);
-          }
-          throw err;
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  agents
-    .command("list")
-    .description("List the company's agents")
-    .option("--company <slug>", "Company slug (resolves to companyUid)")
-    .option("--json", "Emit raw JSON")
-    .action(async function (this: Command, opts: { json?: boolean }) {
-      try {
-        const token = await ensureCognitoToken();
-        const companyUid = await getCompanyUid(token, companyOf(this));
-        let roster: CompanyAgentView[];
-        try {
-          roster = await listAgents(token, companyUid);
-        } catch (err) {
-          // A 404 here means the company doesn't have the agents feature
-          // enabled (hq-pro returns 404 on every /v1/agents route for a
-          // flag-OFF company) — surface that plainly rather than a raw error.
-          if (err instanceof AgentsHttpError && err.status === 404) {
-            console.log(
-              chalk.gray(
-                "No cloud agents are available for this company (the agents feature isn't enabled here).",
-              ),
-            );
-            return;
-          }
-          throw err;
-        }
-
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(roster, null, 2) + "\n");
-          return;
-        }
-        if (roster.length === 0) {
-          console.log(chalk.gray("No agents found for this company."));
-          return;
-        }
-        const nameW = Math.max(4, ...roster.map((a) => (a.name ?? "").length));
-        const slugW = Math.max(4, ...roster.map((a) => (a.slug ?? "").length));
-        const statusW = Math.max(
-          6,
-          ...roster.map((a) => (a.agentStatus ?? "").length),
-        );
-        const modelW = Math.max(
-          5,
-          ...roster.map((a) => (a.codexModel ?? "").length),
-        );
-        console.log(
-          chalk.bold(
-            [
-              "NAME".padEnd(nameW),
-              "SLUG".padEnd(slugW),
-              "STATUS".padEnd(statusW),
-              "MODEL".padEnd(modelW),
-              "UID",
-            ].join("  "),
-          ),
-        );
-        for (const a of roster) {
-          console.log(
-            [
-              (a.name ?? "").padEnd(nameW),
-              (a.slug ?? "").padEnd(slugW),
-              (a.agentStatus ?? "").padEnd(statusW),
-              (a.codexModel ?? "").padEnd(modelW),
-              a.uid,
-            ].join("  "),
-          );
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  agents
-    .command("status <agentUid>")
-    .description("Show an agent's setup state and runtime detail")
-    .option("--company <slug>", "Company slug (resolves to companyUid)")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      agentUid: string,
-      opts: { json?: boolean },
-    ) {
-      try {
-        const token = await ensureCognitoToken();
-        const status = await getAgentStatus(token, agentUid);
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(status, null, 2) + "\n");
-          return;
-        }
-        // Pretty but faithful: dump the top-level fields as key: value.
-        for (const [k, v] of Object.entries(status)) {
-          const rendered =
-            v && typeof v === "object" ? JSON.stringify(v) : String(v);
-          console.log(`${chalk.bold(k)}: ${rendered}`);
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  agents
-    .command("rename <agentUid> <name>")
-    .description("Set an agent's display name")
-    .option("--company <slug>", "Company slug (resolves to companyUid)")
-    .action(async function (
-      this: Command,
-      agentUid: string,
-      name: string,
-    ) {
-      try {
-        const token = await ensureCognitoToken();
-        const result = await patchAgentProfile(token, agentUid, {
-          displayName: name,
-        });
-        console.log(chalk.green(`Renamed agent ${agentUid} to "${name}"`));
-        if (result.slackUpdated) {
-          console.log(chalk.dim("Propagated to the agent's live Slack app."));
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  agents
-    .command("set <agentUid>")
-    .description("Update an agent's profile (name / title / description)")
-    .option("--company <slug>", "Company slug (resolves to companyUid)")
-    .option("--name <displayName>", "Display name")
-    .option("--title <title>", 'Org-chart job title (e.g. "Chief of Staff")')
-    .option("--description <text>", "Short description / bio")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      agentUid: string,
-      opts: {
-        name?: string;
-        title?: string;
-        description?: string;
-        json?: boolean;
-      },
-    ) {
-      try {
-        const patch: ProfilePatch = {};
-        if (opts.name !== undefined) patch.displayName = opts.name;
-        if (opts.title !== undefined) patch.title = opts.title;
-        if (opts.description !== undefined) patch.description = opts.description;
-        if (Object.keys(patch).length === 0) {
-          console.error(
-            chalk.red(
-              "Nothing to set. Pass at least one of --name, --title, --description.",
-            ),
-          );
-          process.exit(1);
-        }
-        const token = await ensureCognitoToken();
-        const result = await patchAgentProfile(token, agentUid, patch);
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-          return;
-        }
-        console.log(chalk.green(`Updated profile for agent ${agentUid}.`));
-        if (result.slackUpdated) {
-          console.log(chalk.dim("Propagated to the agent's live Slack app."));
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  agents
-    .command("config <agentUid>")
-    .description(
-      "Update an agent's runtime config (model / reasoning effort / service tier)",
-    )
-    .option("--company <slug>", "Company slug (resolves to companyUid)")
-    .option("--model <model>", "Codex model id")
-    .option(
-      "--effort <effort>",
-      "Reasoning effort: minimal | low | medium | high | xhigh",
-    )
-    .option("--tier <tier>", "Service tier (speed): default | priority")
-    .option("--json", "Emit raw JSON")
-    .action(async function (
-      this: Command,
-      agentUid: string,
-      opts: {
-        model?: string;
-        effort?: string;
-        tier?: string;
-        json?: boolean;
-      },
-    ) {
-      try {
-        const patch: RuntimeConfigPatch = {};
-        if (opts.model !== undefined) patch.codexModel = opts.model;
-        if (opts.effort !== undefined) {
-          const effort = opts.effort.trim().toLowerCase();
-          if (!VALID_EFFORTS.has(effort)) {
-            console.error(
-              chalk.red(
-                `Invalid --effort '${opts.effort}': must be one of minimal, low, medium, high, xhigh`,
-              ),
-            );
-            process.exit(1);
-          }
-          patch.codexReasoningEffort = effort;
-        }
-        if (opts.tier !== undefined) {
-          const tier = opts.tier.trim().toLowerCase();
-          if (!VALID_TIERS.has(tier)) {
-            console.error(
-              chalk.red(
-                `Invalid --tier '${opts.tier}': must be one of default, priority`,
-              ),
-            );
-            process.exit(1);
-          }
-          patch.codexServiceTier = tier;
-        }
-        if (Object.keys(patch).length === 0) {
-          console.error(
-            chalk.red(
-              "Nothing to change. Pass at least one of --model, --effort, --tier.",
-            ),
-          );
-          process.exit(1);
-        }
-        const token = await ensureCognitoToken();
-        const result = await patchAgentRuntimeConfig(token, agentUid, patch);
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-          return;
-        }
-        console.log(
-          chalk.green(
-            `Updated runtime config for agent ${agentUid} — ${appliedHint(result.applied)}.`,
-          ),
-        );
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  for (const action of ["start", "stop"] as const) {
-    agents
-      .command(`${action} <agentUid>`)
-      .description(`${action === "start" ? "Start" : "Stop"} an agent's box`)
-      .option("--company <slug>", "Company slug (resolves to companyUid)")
-      .action(async function (this: Command, agentUid: string) {
-        try {
-          const token = await ensureCognitoToken();
-          await startStopAgent(token, agentUid, action);
-          console.log(
-            chalk.green(
-              `${action === "start" ? "Started" : "Stopped"} agent ${agentUid}.`,
-            ),
-          );
-        } catch (err) {
-          fail(err);
-        }
-      });
-  }
-
-  agents
-    .command("retry <agentUid>")
-    .description("Resume an agent's setup from the first non-done step")
-    .option("--company <slug>", "Company slug (resolves to companyUid)")
-    .action(async function (this: Command, agentUid: string) {
-      try {
-        const token = await ensureCognitoToken();
-        await retryAgent(token, agentUid);
-        console.log(chalk.green(`Retry queued for agent ${agentUid}.`));
-      } catch (err) {
-        fail(err);
-      }
-    });
-
-  agents
-    .command("rm <agentUid>")
-    .alias("delete")
-    .description("Deprovision (permanently tear down) an agent")
-    .option("--company <slug>", "Company slug (resolves to companyUid)")
-    .option("--yes", "Confirm the irreversible teardown (required)")
-    .action(async function (
-      this: Command,
-      agentUid: string,
-      opts: { yes?: boolean },
-    ) {
-      if (!opts.yes) {
-        console.error(
-          chalk.yellow(
-            `This will permanently deprovision agent ${agentUid} and tear down its ` +
-              `cloud resources. This cannot be undone.\n` +
-              `Re-run with --yes to confirm: hq agents rm ${agentUid} --yes`,
-          ),
-        );
-        process.exit(1);
-      }
-      try {
-        const token = await ensureCognitoToken();
-        const result = await deprovisionAgent(token, agentUid);
-        if (result.terminal === false) {
-          console.log(
-            chalk.yellow(
-              `Deprovision in progress for agent ${agentUid} (not yet fully torn down — re-run to continue).`,
-            ),
-          );
-        } else {
-          console.log(chalk.green(`Deprovisioned agent ${agentUid}.`));
-        }
-      } catch (err) {
-        fail(err);
-      }
-    });
-}