@indigoai-us/hq-cli 5.115.6 → 5.117.0

package/dist/commands/agents.js

@@ -15,6 +15,8 @@
  *   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)
+ *   hq agents rotate <uid>         — new enrollment code for an external agent
+ *   hq agents revoke <uid> --yes   — revoke an external agent (--remove deletes it)
  *   hq agents jobs list <uid>      — off-box job roster (schedule + rate)
  *   hq agents jobs pause <uid> <jobId>  — flip schedule State=DISABLED
  *   hq agents jobs cancel <uid> <jobId> — delete schedule + drop the job
@@ -387,6 +389,143 @@ export async function getAgentStatus(token, agentUid) {
         path: `/v1/agents/${encodeURIComponent(agentUid)}/status`,
     });
 }
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function safeActionUrl(value) {
+    const raw = nonEmptyString(value);
+    if (!raw)
+        return null;
+    try {
+        const url = new URL(raw);
+        return url.protocol === "https:" && !url.username && !url.password ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+function signInProviderName(url) {
+    const parsed = new URL(url);
+    if (parsed.hostname === "auth.openai.com" &&
+        parsed.pathname.startsWith("/codex/")) {
+        return "Codex";
+    }
+    if (parsed.hostname === "accounts.x.ai")
+        return "Grok";
+    if (parsed.hostname.endsWith("anthropic.com"))
+        return "Claude";
+    return "your provider";
+}
+function currentDeviceSignInAction(status) {
+    const pairing = recordValue(status.pairing);
+    const url = safeActionUrl(pairing?.url);
+    if (!url)
+        return null;
+    const rawCode = nonEmptyString(pairing?.code);
+    const code = rawCode && /^[A-Z0-9]{4,8}-[A-Z0-9]{4,8}$/i.test(rawCode)
+        ? rawCode
+        : undefined;
+    const provider = signInProviderName(url);
+    return {
+        type: provider === "Codex" ? "codex-device-sign-in" : "provider-sign-in",
+        title: `Sign in to ${provider}`,
+        summary: `sign in to ${provider}`,
+        instruction: code
+            ? "Open this page and enter the code."
+            : "Open this page and follow the sign-in instructions.",
+        url,
+        urlLabel: "Open",
+        code,
+    };
+}
+function pendingSlackAction(status) {
+    const agent = recordValue(status.agent);
+    const diagnostics = recordValue(agent?.channelDiagnostics);
+    const slack = recordValue(diagnostics?.slack);
+    const url = safeActionUrl(slack?.pendingInstallUrl);
+    if (!url)
+        return null;
+    if (slack?.inboundCapability === "socket-mode-degraded") {
+        return {
+            type: "slack-app-token",
+            title: "Finish setting up the Slack app",
+            summary: "finish setting up the Slack app",
+            instruction: "Open this page, create the app-level token, then provide it in the agent's Slack setup.",
+            url,
+            urlLabel: "Open",
+        };
+    }
+    if (slack?.inboundCapability !== "pending-install")
+        return null;
+    return {
+        type: "slack-install",
+        title: "Install the Slack app",
+        summary: "install the Slack app so it can talk to your workspace",
+        instruction: "Open this link and install the app in your workspace.",
+        url,
+        urlLabel: "Install",
+    };
+}
+/**
+ * The server owns action detection. This client converts its safe, current
+ * status fields into a list so another operator action can be added without
+ * changing the renderers or command control flow.
+ */
+function pendingOperatorActions(status) {
+    return [
+        currentDeviceSignInAction(status),
+        pendingSlackAction(status),
+    ].filter((action) => action !== null);
+}
+function pendingActionsJson(actions) {
+    return actions.map(({ type, title, instruction, url, code }) => ({
+        type,
+        title,
+        instruction,
+        ...(url ? { url } : {}),
+        ...(code ? { code } : {}),
+    }));
+}
+function statusAgentSlug(status) {
+    return nonEmptyString(recordValue(status.agent)?.slug);
+}
+/** The provision endpoint returns this nested identity; old response shapes omit it. */
+function provisionedAgentIdentity(result) {
+    const agent = recordValue(result.agent);
+    const uid = nonEmptyString(agent?.uid) ?? nonEmptyString(agent?.agentUid);
+    const slug = nonEmptyString(agent?.slug);
+    return uid && slug ? { uid, slug } : null;
+}
+function printPendingOperatorActions(slug, actions) {
+    if (actions.length === 0)
+        return;
+    const first = actions[0];
+    console.log(chalk.yellow(actions.length === 1
+        ? `Your agent's box is up. One step left: ${first.summary}.`
+        : "Your agent's box is up. A few steps remain before it can talk to your workspace."));
+    for (const action of actions) {
+        console.log("");
+        console.log(chalk.bold(`${action.title}:`));
+        console.log(action.instruction);
+        if (action.url)
+            console.log(chalk.cyan(`${action.urlLabel ?? "Open"}: ${action.url}`));
+        if (action.code)
+            console.log(chalk.bold(`Code: ${action.code}`));
+    }
+    const currentCodeHint = actions.some((action) => action.code)
+        ? "current sign-in code and instructions"
+        : "these instructions";
+    const statusCommand = slug
+        ? `Run \`hq agents status ${slug}\` any time to get ${currentCodeHint} again.`
+        : `Run \`hq agents status\` again any time to get ${currentCodeHint}.`;
+    console.log("");
+    console.log(chalk.dim(`Until that's done, the agent will show as still setting up. ${statusCommand}`));
+}
 export async function patchAgentProfile(token, agentUid, patch) {
     return agentsRequest({
         token,
@@ -656,6 +795,59 @@ function shortTime(iso) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * POST /v1/agents/{uid}/rotate — invalidate the current secret and host key
+ * and issue a fresh one-time enrollment code (returned exactly once).
+ */
+export async function rotateAgent(token, agentUid) {
+    const data = await agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/rotate`,
+        method: "POST",
+    });
+    const e = data.enrollment ?? {};
+    if (typeof e.code !== "string" || !e.code) {
+        throw new AgentsHttpError(502, "rotate succeeded but the response carried no enrollment code");
+    }
+    return {
+        agentUid: data.agentUid ?? agentUid,
+        enrollment: {
+            code: e.code,
+            expiresAt: typeof e.expiresAt === "string" ? e.expiresAt : "",
+            enrollmentId: typeof e.enrollmentId === "string" ? e.enrollmentId : "",
+        },
+    };
+}
+/** Display form of a 24-char code: six groups of four. */
+export function groupEnrollmentCode(code) {
+    const flat = code.replace(/[\s-]+/g, "").toUpperCase();
+    return flat.match(/.{1,4}/g)?.join("-") ?? flat;
+}
+/**
+ * POST /v1/agents/{uid}/revoke — disable the Cognito user, drop membership,
+ * mark the enrollment revoked; `remove` also deletes the entity.
+ */
+export async function revokeAgent(token, agentUid, remove) {
+    const data = await agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/revoke`,
+        method: "POST",
+        body: { remove },
+    });
+    return { removed: data.removed === true || remove };
+}
+/** Lines printed after a rotate: the code is shown once and never stored. */
+export function formatRotateOutput(result) {
+    const lines = [
+        `Rotated ${result.agentUid}. The old secret and host key no longer mint.`,
+        "",
+        `  enrollment code: ${groupEnrollmentCode(result.enrollment.code)}`,
+    ];
+    if (result.enrollment.expiresAt)
+        lines.push(`  expires:         ${result.enrollment.expiresAt} (15 minutes)`);
+    lines.push("", "Shown once. On the agent's host run:", `  hq agent enroll ${groupEnrollmentCode(result.enrollment.code)} --replace`, "  hq agent probe");
+    return lines;
+}
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -711,6 +903,11 @@ export function registerAgentsCommand(program) {
             // Interactive terminals are for humans: hq-pro serves no keyed
             // `/v1/keys/agents/{uid}/terminal` route, so machine keys fail closed.
             terminal: { capability: "agents:use", routeAvailable: false },
+            // External-agent lifecycle is an admin action on the JWT-only
+            // /v1/agents/{uid}/rotate|revoke routes (api-contract v1); no keyed
+            // parallel exists, so machine keys fail closed here too.
+            rotate: { capability: "agents:use", routeAvailable: false },
+            revoke: { capability: "agents:use", routeAvailable: false },
         },
     });
     // `--company` may live on the group or the subcommand; the subcommand value
@@ -955,13 +1152,34 @@ export function registerAgentsCommand(program) {
                     quoteCatalogVersion: createOptions.catalogVersion,
                     surface: CLI_AGENT_CREATE_SURFACE,
                 });
-                const uid = typeof result.uid === "string" ? result.uid : slug;
+                const identity = provisionedAgentIdentity(result);
+                const status = identity
+                    ? await getAgentStatus(token, identity.uid)
+                    : null;
+                const actions = status ? pendingOperatorActions(status) : [];
+                const slackInstall = actions.find((action) => action.type === "slack-install");
                 if (opts.json) {
-                    console.log(JSON.stringify(result));
+                    console.log(JSON.stringify({
+                        ...result,
+                        ...(actions.length > 0
+                            ? { pendingActions: pendingActionsJson(actions) }
+                            : {}),
+                        ...(slackInstall?.url
+                            ? {
+                                slackInstallPending: true,
+                                slackInstallUrl: slackInstall.url,
+                            }
+                            : {}),
+                    }));
                 }
                 else {
                     console.log(chalk.green(`Provisioning started for agent "${name}".`));
-                    console.log(chalk.dim(`Track setup: hq agents status ${uid} --company <slug>`));
+                    if (actions.length > 0) {
+                        printPendingOperatorActions(identity?.slug ?? null, actions);
+                    }
+                    else {
+                        console.log(chalk.dim(`Track setup: hq agents status ${identity?.slug ?? slug} --company <slug>`));
+                    }
                 }
             }
             catch (err) {
@@ -1050,16 +1268,28 @@ export function registerAgentsCommand(program) {
         }
     });
     agents
-        .command("status <agentUid>")
+        .command("status <agent>")
         .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 (agentUid, opts) {
+        .action(async function (agent, opts) {
         try {
             const token = (await resolveVaultCredential()).token;
+            const agentUid = await resolveAgentUid(token, agent, companyOf(this));
             const status = await getAgentStatus(token, agentUid);
+            const actions = pendingOperatorActions(status);
             if (opts.json) {
-                process.stdout.write(JSON.stringify(status, null, 2) + "\n");
+                process.stdout.write(JSON.stringify({
+                    ...status,
+                    ...(actions.length > 0
+                        ? { pendingActions: pendingActionsJson(actions) }
+                        : {}),
+                }, null, 2) + "\n");
+                return;
+            }
+            if (actions.length > 0) {
+                printPendingOperatorActions(statusAgentSlug(status) ??
+                    (AGENT_UID_PATTERN.test(agent.trim()) ? null : agent.trim()), actions);
                 return;
             }
             // Pretty but faithful: dump the top-level fields as key: value.
@@ -1268,6 +1498,50 @@ export function registerAgentsCommand(program) {
             fail(err);
         }
     });
+    agents
+        .command("rotate <agentUid>")
+        .description("Issue a fresh enrollment code for an external agent (old secret + host key stop minting)")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--json", "Emit raw JSON (code included — pipe carefully)")
+        .action(async function (agentUid, opts) {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await rotateAgent(token, agentUid);
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            for (const line of formatRotateOutput(result))
+                console.log(line);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    agents
+        .command("revoke <agentUid>")
+        .description("Revoke an external agent: disable its login and drop it from the team")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--remove", "Also delete the agent entity (it disappears from the roster)")
+        .option("--yes", "Confirm the revoke (required)")
+        .action(async function (agentUid, opts) {
+        if (!opts.yes) {
+            console.error(chalk.yellow(`This will revoke agent ${agentUid}: its credentials stop working immediately and it ` +
+                `leaves the team${opts.remove ? ", and the agent record is deleted" : ""}. ` +
+                `Re-run with --yes to confirm: hq agents revoke ${agentUid}${opts.remove ? " --remove" : ""} --yes`));
+            process.exit(1);
+        }
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await revokeAgent(token, agentUid, opts.remove === true);
+            console.log(chalk.green(result.removed
+                ? `Revoked and removed agent ${agentUid}.`
+                : `Revoked agent ${agentUid}. Its next mint will be refused (401).`));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     // Off-box job control (US-003). Nested group so `hq agents jobs --help`
     // lists list|pause|cancel. Same vaultApiFetch + person JWT as the rest of
     // this file; keyed HQ_API_KEY rewrites /v1/agents → /v1/keys/agents.

package/dist/commands/bot.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { type RuntimeSignInIssue } from "../lib/bot/runtime-sign-in.js";
-import { type BotKind, type BotMemoryMode, type BotRuntimeId, type LaunchctlExec } from "../lib/bot/index.js";
+import { type BotLocalConfig, type MyLocalBot, type BotKind, type BotMemoryMode, type BotNotRunnableReason, type BotConfig, type BotRuntimeId, type LaunchctlExec } from "../lib/bot/index.js";
 /** Real launchctl; every failure is a non-ok result, never a throw. */
 export declare const defaultLaunchctl: LaunchctlExec;
 /** The desktop app creates HQ's setup bot under this name, always from the `setup` worker. */
@@ -101,5 +101,144 @@ export declare function runBotSet(nameArg: string, opts: {
     effort?: string;
     json?: boolean;
 }): Promise<void>;
+/**
+ * The one bot the caller means. Matches the local folder name, the cloud slug,
+ * the display name, or the agt_ uid; an ambiguous name is refused rather than
+ * guessed at.
+ */
+export declare function matchRemoteBots(bots: readonly MyLocalBot[], wanted: string): MyLocalBot[];
+export declare function resolveRemoteBot(bots: readonly MyLocalBot[], wanted: string): MyLocalBot;
+/**
+ * Why HQ could not say which bots the account owns. The desktop app switches
+ * on these values, so they are contract, not prose:
+ *
+ *   server-unsupported  the HQ Cloud in front of us has no listing route
+ *   auth                the sign-in was refused
+ *   network             HQ could not be reached at all
+ *   server-error        HQ answered 5xx
+ *   error               anything else
+ */
+export type RemoteBotsUnavailableReason = "server-unsupported" | "auth" | "network" | "server-error" | "error";
+export interface RemoteBotsUnavailable {
+    reason: RemoteBotsUnavailableReason;
+    message: string;
+}
+/**
+ * Turn any failure of `GET /v1/agents/mine` into one plain sentence plus a
+ * stable reason. Production HQ Cloud does not serve that route yet, and an
+ * uncaught 404 reached the person verbatim as "HQ API /v1/agents/mine → 404:
+ * Not found" — and, under --json, as no document at all.
+ */
+export declare function remoteBotsUnavailable(err: unknown): RemoteBotsUnavailable;
+/**
+ * A cloud teardown that only got part of the way, said in the same vocabulary
+ * the desktop switches on, plus the one decision that follows from it.
+ *
+ * `DELETE /v1/agents/{uid}` answers 200 with `terminal:false` and a per-step
+ * `failures` map when it could do only part of the job. Those strings are raw
+ * infrastructure: one real answer carried the AWS account id, an assumed-role
+ * ARN and a DynamoDB table ARN. They are classified here and never repeated —
+ * `detail` is a plain clause, `steps` is the server's own step names and
+ * nothing of what they said.
+ *
+ * `retryable` is the local-state decision. Running `hq bot rm` again can only
+ * finish the job when the step that failed might behave differently next time.
+ * A refusal, or a step whose target was already gone, answers the same way
+ * forever, so the local copy goes and the message says the leftover is HQ's.
+ *
+ * `reason` reuses {@link RemoteBotsUnavailableReason}: `auth` for a refused
+ * step (a permission problem, on either side of the call), `error` for a step
+ * whose target was already gone, `server-error` for anything HQ may yet
+ * finish.
+ */
+export interface BotRemovalIncomplete {
+    reason: RemoteBotsUnavailableReason;
+    /** One plain clause naming what stopped. Never a transport string. */
+    detail: string;
+    /** Whether running the same command again can still finish the removal. */
+    retryable: boolean;
+    /** The server's step names only — no ids, ARNs or messages. */
+    steps: string[];
+}
+export declare function botRemovalIncomplete(failures?: Record<string, string>): BotRemovalIncomplete;
+/**
+ * Rebuild a bot.json from the settings the cloud kept for it. A bot created
+ * before HQ saved settings comes back on defaults, and anything this HQ can no
+ * longer provide (a worker that is not here, a thinking level the chosen
+ * runtime does not accept) is reported rather than silently kept.
+ */
+export declare function configFromLocalConfig(input: {
+    name: string;
+    agentUid: string;
+    ownerUid: string;
+    hqRoot: string;
+    dir: string;
+    local: BotLocalConfig | null;
+    overrides?: {
+        runtime?: BotRuntimeId;
+        model?: string;
+    };
+    now?: () => Date;
+}): {
+    config: BotConfig;
+    notes: string[];
+};
+export interface BotAdoptResult {
+    name: string;
+    agentUid: string;
+    runtime: BotRuntimeId;
+    kind: BotKind;
+    companies: string[];
+    dir: string;
+    worker: string;
+    memory: BotMemoryMode;
+    memoryDir: string;
+    /** True when the cloud had no saved settings and defaults were used. */
+    defaulted: boolean;
+    notes: string[];
+    daemon: string | null;
+}
+export declare function runBotAdopt(nameArg: string, opts: {
+    runtime?: string;
+    model?: string;
+    daemon?: boolean;
+    start?: boolean;
+    json?: boolean;
+}): Promise<void>;
+export interface BotRestoreRow {
+    name: string;
+    agentUid: string;
+    /** restored = brought back here; repaired = new credentials for one already here. */
+    action: "restored" | "repaired" | "skipped" | "failed" | "would-restore" | "would-repair" | "would-skip";
+    detail: string;
+    /** Present only on a bot skipped because this computer cannot run it. */
+    reason?: BotNotRunnableReason;
+}
+/**
+ * `hq bot restore` — every local bot this account owns that is not set up on
+ * this computer comes back. This is what the desktop app and a post-install
+ * hook call after a reinstall or on a new Mac.
+ */
+export declare function runBotRestore(opts: {
+    all?: boolean;
+    dryRun?: boolean;
+    daemon?: boolean;
+    start?: boolean;
+    json?: boolean;
+}): Promise<void>;
+export interface RemoteBotRow {
+    name: string;
+    agentUid: string;
+    kind: string;
+    online: boolean;
+    lastHeartbeatAt: string | null;
+    /** True when this bot is set up on this computer. */
+    here: boolean;
+    settings: string;
+    /** False when this computer cannot run it, whatever the listing says. */
+    runnable: boolean;
+    /** Why not, when `runnable` is false: the same vocabulary adopt and restore use. */
+    reason: BotNotRunnableReason | null;
+}
 export declare function registerBotCommand(program: Command): void;
 //# sourceMappingURL=bot.d.ts.map