@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

package/dist/commands/agent-enroll.d.ts

@@ -1,146 +0,0 @@
-/**
- * `hq agent enroll <code>` — turn this host into an external HQ agent.
- *
- * Flow (api-contract v1, POST /v1/agents/enroll):
- *   1. refuse if this host already carries an identity (human session file or
- *      a machine-creds file) unless --replace
- *   2. generate an Ed25519 key pair at ~/.hq-agent/host-key{,.pub} (0600)
- *   3. POST { code, hostPublicKey, hostInfo } — unauthenticated, one-shot
- *   4. write ~/.hq-agent/machine-creds.json (0600) with runtime "external",
- *      hostKeyPath, companySlug and apiBaseUrl
- *
- * The code is single-use and expires 15 minutes after an admin creates it,
- * so every failure names the fix. The human session file is only checked
- * for EXISTENCE — its contents are never read (policy
- * never-extract-stored-session-tokens-to-forge-privileged-calls).
- */
-import { Command } from "commander";
-import { generateHostKeyPair } from "../lib/agent-kit/creds.js";
-import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
-export declare const ENROLL_PATH = "/v1/agents/enroll";
-/** Canonical code: un-grouped, uppercase (server hashes exactly this). */
-export declare function normalizeEnrollmentCode(raw: string): string;
-/** 24 chars of Crockford base32 (no I, L, O, U). */
-export declare function isWellFormedEnrollmentCode(code: string): boolean;
-export interface HostInfo {
-    os: string;
-    arch: string;
-    hostname: string;
-    cliVersion: string;
-}
-export declare function collectHostInfo(): HostInfo;
-export type ExistingIdentity = {
-    kind: "none";
-} | {
-    kind: "human";
-    file: string;
-} | {
-    kind: "machine";
-    file: string;
-    agentUid?: string;
-};
-/**
- * What identity already lives on this host. Existence checks only: the
- * human token file is never opened.
- */
-export declare function detectExistingIdentity(paths: Pick<AgentKitPaths, "machineCredsPath" | "home">, env?: NodeJS.ProcessEnv): ExistingIdentity;
-export declare function refusalMessage(existing: ExistingIdentity): string | null;
-export declare class EnrollError extends Error {
-    readonly status?: number | undefined;
-    readonly code?: string | undefined;
-    readonly upgradeUrl?: string | undefined;
-    constructor(message: string, status?: number | undefined, code?: string | undefined, upgradeUrl?: string | undefined);
-}
-export declare function formatEnrollFailureMessage(error: EnrollError, options?: {
-    urlOnly?: boolean;
-}): string;
-/** Map a non-2xx enroll response to an actionable message (contract codes). */
-export declare function mapEnrollFailure(status: number, body: {
-    code?: unknown;
-    error?: unknown;
-    message?: unknown;
-    attemptsRemaining?: unknown;
-    upgradeUrl?: unknown;
-}, headers?: {
-    retryAfter?: string | null;
-}): EnrollError;
-export declare function mapEnrollTransportError(err: unknown, apiBaseUrl: string): EnrollError;
-export interface EnrollResponse {
-    agentUid: string;
-    companyUid: string;
-    companySlug: string;
-    credentials: {
-        username: string;
-        secret: string;
-        userPoolId?: string;
-        clientId: string;
-        region: string;
-        entityType: "agent";
-        entityUid: string;
-        runtime: "external";
-    };
-    hostFingerprint: string;
-}
-export interface EnrollDeps {
-    fetch?: typeof fetch;
-    paths?: AgentKitPaths;
-    env?: NodeJS.ProcessEnv;
-    hostInfo?: HostInfo;
-    generateKeyPair?: typeof generateHostKeyPair;
-    /** Home directory the enroll target resolves under (defaults to os.homedir()). */
-    home?: string;
-}
-export interface EnrollOptions {
-    code: string;
-    company?: string;
-    replace?: boolean;
-    apiBaseUrl?: string;
-    /** Enroll into `~/.hq-agent/<name>/` — a bot sharing a host with a person. */
-    name?: string;
-}
-/**
- * Where this enrollment should write, given what already lives on the host.
- *
- * A bot that runs on its owner's own computer is the common case, not an
- * error: the machine has the owner's HQ session, and the two identities have
- * to coexist. So an unpinned enrollment onto such a host does NOT refuse and
- * does NOT overwrite anything — it moves into `~/.hq-agent/<name>/`, its own
- * tree with its own credentials, key, state and logs. The person's session
- * file is neither read nor touched, and `hq agent …` finds the bot's tree on
- * its own afterwards (see agentDir).
- */
-export declare function resolveEnrollTarget(opts: {
-    name?: string;
-    replace?: boolean;
-}, env?: NodeJS.ProcessEnv, home?: string): {
-    paths: AgentKitPaths;
-    local: boolean;
-};
-/** Lowercase slug, so the directory name can never escape `~/.hq-agent`. */
-export declare function validateLocalAgentName(name: string): string;
-export interface EnrollResult {
-    agentUid: string;
-    companySlug: string;
-    companyUid: string;
-    hostFingerprint: string;
-    credsPath: string;
-    hostKeyPath: string;
-    /** Set when --company disagreed with the server's company. */
-    companyMismatch?: string;
-    /** True when this enrolled beside a person's session in its own directory. */
-    local: boolean;
-    /**
-     * False when the filesystem could not make the credential owner-only — a
-     * share mounted with a fixed file_mode. The identity works; anything else
-     * with access to that share can read it.
-     */
-    permissionsEnforced: boolean;
-    /** errno of the refused chmod, when there was one (EPERM on Azure Files). */
-    permissionsError?: string;
-    /** The tree this identity lives in. */
-    agentDir: string;
-}
-/** Pure-ish orchestration so tests can drive it without a TTY or network. */
-export declare function enrollHost(opts: EnrollOptions, deps?: EnrollDeps): Promise<EnrollResult>;
-export declare function registerAgentEnrollCommand(agent: Command): void;
-//# sourceMappingURL=agent-enroll.d.ts.map

package/dist/commands/agent-enroll.js

@@ -1,401 +0,0 @@
-/**
- * `hq agent enroll <code>` — turn this host into an external HQ agent.
- *
- * Flow (api-contract v1, POST /v1/agents/enroll):
- *   1. refuse if this host already carries an identity (human session file or
- *      a machine-creds file) unless --replace
- *   2. generate an Ed25519 key pair at ~/.hq-agent/host-key{,.pub} (0600)
- *   3. POST { code, hostPublicKey, hostInfo } — unauthenticated, one-shot
- *   4. write ~/.hq-agent/machine-creds.json (0600) with runtime "external",
- *      hostKeyPath, companySlug and apiBaseUrl
- *
- * The code is single-use and expires 15 minutes after an admin creates it,
- * so every failure names the fix. The human session file is only checked
- * for EXISTENCE — its contents are never read (policy
- * never-extract-stored-session-tokens-to-forge-privileged-calls).
- */
-import chalk from "chalk";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import { CLI_VERSION } from "../cli-version.js";
-import { DEFAULT_VAULT_API_URL, personTokenCacheFile, } from "../utils/cognito-session.js";
-import { HQ_CLIENT_NAME } from "../utils/vault-api.js";
-import { queueCliLimitNoticeEngagement, queueCliLimitNoticeExposure, } from "../utils/cli-telemetry.js";
-import { networkTransportErrorCode } from "../utils/network-transport-error.js";
-import { canOfferTeamUpgrade, formatUpgradeRefusal, isPlanGateError, offerUpgradeLink, planGateErrorFromPayload, } from "../utils/plan-gate-error.js";
-import { generateHostKeyPair, machineCredsFileExists, readExternalMachineCreds, writeHostKeyPair, writeMachineCreds, } from "../lib/agent-kit/creds.js";
-import { DEFAULT_LOCAL_AGENT_NAME, agentKitPaths, localAgentDir, } from "../lib/agent-kit/paths.js";
-export const ENROLL_PATH = "/v1/agents/enroll";
-/** Canonical code: un-grouped, uppercase (server hashes exactly this). */
-export function normalizeEnrollmentCode(raw) {
-    return raw.replace(/[\s-]+/g, "").toUpperCase();
-}
-/** 24 chars of Crockford base32 (no I, L, O, U). */
-export function isWellFormedEnrollmentCode(code) {
-    return /^[0-9A-HJKMNP-TV-Z]{24}$/.test(code);
-}
-export function collectHostInfo() {
-    return {
-        os: `${os.platform()} ${os.release()}`,
-        arch: os.arch(),
-        hostname: os.hostname(),
-        cliVersion: CLI_VERSION,
-    };
-}
-/**
- * What identity already lives on this host. Existence checks only: the
- * human token file is never opened.
- */
-export function detectExistingIdentity(paths, env = process.env) {
-    const humanFile = personTokenCacheFile(paths.home, env);
-    if (fs.existsSync(humanFile))
-        return { kind: "human", file: humanFile };
-    if (machineCredsFileExists(paths)) {
-        const existing = readExternalMachineCreds(paths);
-        return {
-            kind: "machine",
-            file: paths.machineCredsPath,
-            ...(existing ? { agentUid: existing.entityUid } : {}),
-        };
-    }
-    return { kind: "none" };
-}
-/** Machine identity already enrolled in a local agent directory, if any. */
-function existingLocalIdentity(paths) {
-    if (!machineCredsFileExists(paths))
-        return { kind: "none" };
-    const existing = readExternalMachineCreds(paths);
-    return {
-        kind: "machine",
-        file: paths.machineCredsPath,
-        ...(existing ? { agentUid: existing.entityUid } : {}),
-    };
-}
-export function refusalMessage(existing) {
-    switch (existing.kind) {
-        case "none":
-            return null;
-        case "human":
-            // Reached only when a caller pins the tree (HQ_AGENT_DIR / --dir) at a
-            // home that would sit on top of a person's login. The unpinned path
-            // enrolls into a sibling directory instead of refusing — see
-            // resolveEnrollTarget.
-            return (`A human HQ session exists at ${existing.file}. An agent identity must not ` +
-                `share a host account with a person's login. Enroll into a directory of its ` +
-                `own (drop HQ_AGENT_DIR and this happens automatically, or pass ` +
-                `--name <bot>), or pass --replace to enroll here anyway — the human session ` +
-                `file is left untouched and never read.`);
-        case "machine":
-            return (`This host already has a machine identity at ${existing.file}` +
-                `${existing.agentUid ? ` (${existing.agentUid})` : ""}. Re-run with --replace ` +
-                `to enroll as a new agent; the old creds and host key will be overwritten.`);
-    }
-}
-export class EnrollError extends Error {
-    status;
-    code;
-    upgradeUrl;
-    constructor(message, status, code, upgradeUrl) {
-        super(message);
-        this.status = status;
-        this.code = code;
-        this.upgradeUrl = upgradeUrl;
-        this.name = "EnrollError";
-    }
-}
-export function formatEnrollFailureMessage(error, options = {}) {
-    return formatUpgradeRefusal(error.message, error.upgradeUrl, options);
-}
-/** Map a non-2xx enroll response to an actionable message (contract codes). */
-export function mapEnrollFailure(status, body, headers) {
-    const code = typeof body.code === "string" ? body.code : undefined;
-    const attemptsRemaining = typeof body.attemptsRemaining === "number" ? body.attemptsRemaining : undefined;
-    const attemptsNote = attemptsRemaining !== undefined
-        ? ` ${attemptsRemaining} attempt${attemptsRemaining === 1 ? "" : "s"} left before the code is revoked.`
-        : "";
-    const serverText = typeof body.message === "string"
-        ? body.message
-        : typeof body.error === "string"
-            ? body.error
-            : "";
-    const suffix = serverText ? ` (${serverText})` : "";
-    if (status === 410 || code === "expired") {
-        return new EnrollError(`Enrollment code expired — codes last 15 minutes. Ask a company admin for a ` +
-            `fresh one: console → Agents → the bot → Regenerate, or \`hq agents rotate <agentUid>\`.${suffix}`, status, code);
-    }
-    if (status === 409 || code === "already_redeemed") {
-        return new EnrollError(`This enrollment code was already used. Each code enrolls exactly one host; ` +
-            `ask an admin to rotate the agent (\`hq agents rotate <agentUid>\`) for a new code.${suffix}`, status, code);
-    }
-    if (status === 404 || code === "invalid_code") {
-        return new EnrollError(`Enrollment code not recognised. Check for typos (codes are 24 characters, ` +
-            `groups of 4, no I/L/O/U) and that you copied the whole code.${suffix}`, status, code);
-    }
-    if (status === 423 || code === "revoked") {
-        return new EnrollError(`This agent was revoked; its enrollment code no longer works. An admin must ` +
-            `create a new external agent or rotate this one.${suffix}`, status, code);
-    }
-    if (status === 402 || code === "billing_required") {
-        return new EnrollError(`External agents are available on paid HQ plans only. A company admin must ` +
-            `upgrade the plan (\`hq billing\` or the console billing page) before enrolling.${suffix}`, status, code, typeof body.upgradeUrl === "string" ? body.upgradeUrl : undefined);
-    }
-    if (status === 429 || code === "rate_limited") {
-        const retryAfter = headers?.retryAfter?.trim();
-        const wait = retryAfter && /^\d+$/.test(retryAfter) ? `wait ${retryAfter}s and retry` : "wait a minute and retry";
-        return new EnrollError(`Too many enrollment attempts from this host — ${wait}. ` +
-            `After 5 failed attempts a code is revoked and must be regenerated.${suffix}`, status, code ?? "rate_limited");
-    }
-    if (code === "invalid_host_key") {
-        return new EnrollError(`The server rejected this host's public key (expected an Ed25519 SPKI PEM). ` +
-            `Re-run \`hq agent enroll\` to generate a fresh key; if it keeps failing, upgrade hq-cli.${attemptsNote}${suffix}`, status, code);
-    }
-    if (code === "invalid_host_info") {
-        return new EnrollError(`The server rejected this host's info block (os/arch/hostname/cliVersion). ` +
-            `Upgrade hq-cli and retry.${attemptsNote}${suffix}`, status, code);
-    }
-    return new EnrollError(`Enrollment failed (HTTP ${status}${code ? ` ${code}` : ""})${suffix}`, status, code);
-}
-export function mapEnrollTransportError(err, apiBaseUrl) {
-    const code = networkTransportErrorCode(err);
-    const detail = err instanceof Error ? err.message : String(err);
-    return new EnrollError(`Could not reach ${apiBaseUrl}${code ? ` (${code})` : ""}: ${detail}. Check network ` +
-        `access / proxy settings; the HQ_VAULT_API_URL env var overrides the control plane.`);
-}
-function parseEnrollResponse(raw) {
-    const r = (raw ?? {});
-    const c = (r.credentials ?? {});
-    const need = (obj, k) => {
-        const v = obj[k];
-        if (typeof v !== "string" || v.length === 0) {
-            throw new EnrollError(`Enrollment response is missing "${k}"`);
-        }
-        return v;
-    };
-    const entityUid = need(c, "entityUid");
-    if (!entityUid.startsWith("agt_")) {
-        throw new EnrollError(`Enrollment response entityUid is not an agent uid: ${entityUid}`);
-    }
-    return {
-        agentUid: need(r, "agentUid"),
-        companyUid: need(r, "companyUid"),
-        companySlug: need(r, "companySlug"),
-        hostFingerprint: need(r, "hostFingerprint"),
-        credentials: {
-            username: need(c, "username"),
-            secret: need(c, "secret"),
-            ...(typeof c.userPoolId === "string" && c.userPoolId ? { userPoolId: c.userPoolId } : {}),
-            clientId: need(c, "clientId"),
-            region: need(c, "region"),
-            entityType: "agent",
-            entityUid,
-            runtime: "external",
-        },
-    };
-}
-/**
- * Where this enrollment should write, given what already lives on the host.
- *
- * A bot that runs on its owner's own computer is the common case, not an
- * error: the machine has the owner's HQ session, and the two identities have
- * to coexist. So an unpinned enrollment onto such a host does NOT refuse and
- * does NOT overwrite anything — it moves into `~/.hq-agent/<name>/`, its own
- * tree with its own credentials, key, state and logs. The person's session
- * file is neither read nor touched, and `hq agent …` finds the bot's tree on
- * its own afterwards (see agentDir).
- */
-export function resolveEnrollTarget(opts, env = process.env, home = os.homedir()) {
-    const pinned = Boolean(env.HQ_AGENT_DIR?.trim() || env.HQ_MACHINE_CREDS_FILE?.trim());
-    // A pinned tree is the environment's explicit choice and wins over --name:
-    // a bot that set HQ_AGENT_DIR to its persistent storage must never be
-    // redirected to a directory under $HOME, which may be erased on rebuild.
-    if (pinned)
-        return { paths: agentKitPaths(home, env), local: false };
-    if (opts.name) {
-        const dir = localAgentDir(validateLocalAgentName(opts.name), home);
-        return { paths: agentKitPaths(home, { ...env, HQ_AGENT_DIR: dir }), local: true };
-    }
-    const base = agentKitPaths(home, env);
-    // --replace is an explicit choice too; it is not silently redirected.
-    if (opts.replace)
-        return { paths: base, local: false };
-    if (detectExistingIdentity(base, env).kind !== "human") {
-        return { paths: base, local: false };
-    }
-    const dir = localAgentDir(DEFAULT_LOCAL_AGENT_NAME, home);
-    return { paths: agentKitPaths(home, { ...env, HQ_AGENT_DIR: dir }), local: true };
-}
-/** Lowercase slug, so the directory name can never escape `~/.hq-agent`. */
-export function validateLocalAgentName(name) {
-    const trimmed = (name ?? "").trim();
-    if (!/^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/.test(trimmed) || trimmed.includes("--")) {
-        throw new EnrollError(`Invalid --name "${name}": use 1–40 lowercase letters, digits and single hyphens (e.g. "grokbot").`);
-    }
-    return trimmed;
-}
-/** Pure-ish orchestration so tests can drive it without a TTY or network. */
-export async function enrollHost(opts, deps = {}) {
-    const env = deps.env ?? process.env;
-    const target = deps.paths
-        ? { paths: deps.paths, local: false }
-        : resolveEnrollTarget({ name: opts.name, replace: opts.replace }, env, deps.home);
-    const paths = target.paths;
-    const doFetch = deps.fetch ?? fetch;
-    const apiBaseUrl = (opts.apiBaseUrl ?? env.HQ_VAULT_API_URL ?? DEFAULT_VAULT_API_URL).replace(/\/+$/, "");
-    const code = normalizeEnrollmentCode(opts.code);
-    if (!isWellFormedEnrollmentCode(code)) {
-        throw new EnrollError(`Enrollment code must be 24 base32 characters (shown as XXXX-XXXX-XXXX-XXXX-XXXX-XXXX); got ${code.length}.`);
-    }
-    // A local target sits in its own ~/.hq-agent/<name>/ beside the person's
-    // login by design, so only an identity already in that directory blocks it.
-    const existing = target.local
-        ? existingLocalIdentity(paths)
-        : detectExistingIdentity(paths, env);
-    const refusal = refusalMessage(existing);
-    if (refusal && !opts.replace)
-        throw new EnrollError(refusal);
-    // Key first, then the network call: the public half must exist before the
-    // server can bind the code to it, and a failed call leaves a harmless
-    // unenrolled key behind (regenerated on the next attempt).
-    const pair = (deps.generateKeyPair ?? generateHostKeyPair)();
-    const keyWrite = writeHostKeyPair(paths, pair);
-    let res;
-    try {
-        res = await doFetch(`${apiBaseUrl}${ENROLL_PATH}`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "x-hq-client-name": HQ_CLIENT_NAME,
-                "x-hq-client-version": CLI_VERSION,
-            },
-            body: JSON.stringify({
-                code,
-                hostPublicKey: pair.publicPem,
-                hostInfo: deps.hostInfo ?? collectHostInfo(),
-            }),
-        });
-    }
-    catch (err) {
-        throw mapEnrollTransportError(err, apiBaseUrl);
-    }
-    const body = (await res.json().catch(() => ({})));
-    if (!res.ok) {
-        const planGate = planGateErrorFromPayload(res.status, body);
-        if (planGate)
-            throw planGate;
-        throw mapEnrollFailure(res.status, body, { retryAfter: res.headers.get("retry-after") });
-    }
-    const parsed = parseEnrollResponse(body);
-    if (parsed.hostFingerprint !== pair.fingerprint) {
-        throw new EnrollError(`Server bound the code to fingerprint ${parsed.hostFingerprint} but this host's key is ` +
-            `${pair.fingerprint}. Refusing to write credentials; ask an admin to rotate the agent.`);
-    }
-    const creds = {
-        ...parsed.credentials,
-        hostKeyPath: paths.hostKeyPath,
-        companySlug: parsed.companySlug,
-        apiBaseUrl,
-    };
-    const credsWrite = writeMachineCreds(paths, creds);
-    const enforced = keyWrite.enforced && credsWrite.enforced;
-    const permissionsError = keyWrite.chmodError ?? credsWrite.chmodError;
-    return {
-        permissionsEnforced: enforced,
-        ...(permissionsError ? { permissionsError } : {}),
-        local: target.local,
-        agentDir: paths.agentDir,
-        agentUid: parsed.agentUid,
-        companySlug: parsed.companySlug,
-        companyUid: parsed.companyUid,
-        hostFingerprint: parsed.hostFingerprint,
-        credsPath: paths.machineCredsPath,
-        hostKeyPath: paths.hostKeyPath,
-        ...(opts.company && opts.company !== parsed.companySlug && opts.company !== parsed.companyUid
-            ? { companyMismatch: opts.company }
-            : {}),
-    };
-}
-/** Directory label for the permissions note — never the credential itself. */
-function paths_agentDirLabel() {
-    return agentKitPaths(os.homedir(), process.env).agentDir;
-}
-export function registerAgentEnrollCommand(agent) {
-    agent
-        .command("enroll <code>")
-        .description("Enroll this host as an external HQ agent using a one-time code")
-        .option("--company <slug>", "Expected company slug (warns when the code belongs elsewhere)")
-        .option("--replace", "Overwrite an existing machine identity on this host")
-        .option("--name <bot>", "Enroll into ~/.hq-agent/<bot>/ — for a bot sharing a computer with its owner")
-        .option("--api-base-url <url>", "hq-pro control plane (default: HQ_VAULT_API_URL or production)")
-        .action(async (code, opts) => {
-        try {
-            const result = await enrollHost({
-                code,
-                company: opts.company,
-                replace: opts.replace,
-                apiBaseUrl: opts.apiBaseUrl,
-                name: opts.name,
-            });
-            console.log(chalk.green(`Enrolled as ${result.agentUid} in ${result.companySlug}.`));
-            if (result.local) {
-                // Say it plainly: this host belongs to a person, and the bot is a
-                // guest on it. Nothing of theirs was read, moved or overwritten.
-                console.log(chalk.dim(`  This computer already has a person signed in, so this agent lives in its own\n` +
-                    `  directory beside them: ${result.agentDir}. Their session was not read or changed.\n` +
-                    `  Every hq agent command finds this tree on its own — no environment to set.`));
-            }
-            if (!result.permissionsEnforced) {
-                // Not a warning to bury: the credential is on disk and working,
-                // but this filesystem cannot keep it to one owner.
-                console.log(chalk.yellow(`  note: this filesystem could not make the credential owner-only` +
-                    `${result.permissionsError ? ` (chmod: ${result.permissionsError})` : ""}.\n` +
-                    `        Anything with access to ${paths_agentDirLabel()} can read it. That is\n` +
-                    `        usually a network share mounted with a fixed file_mode. Keep the\n` +
-                    `        share itself restricted, or move the identity to local storage.`));
-            }
-            console.log(`  host fingerprint: ${result.hostFingerprint}`);
-            console.log(`  credentials:      ${result.credsPath} (0600)`);
-            console.log(`  host key:         ${result.hostKeyPath} (0600)`);
-            if (result.companyMismatch) {
-                console.log(chalk.yellow(`  note: --company ${result.companyMismatch} did not match the code's company ` +
-                    `(${result.companySlug}); the code's company wins.`));
-            }
-            console.log("");
-            console.log("Next:");
-            console.log(result.local
-                ? "  hq agent probe           # its first line reports this agent, not you"
-                : "  hq whoami                # should report the agent identity");
-            console.log("  hq agent kit install     # inbox poller and heartbeat services");
-            console.log("  hq agent probe           # end-to-end check, reported to the console");
-        }
-        catch (err) {
-            if (isPlanGateError(err)) {
-                throw err;
-            }
-            else if (err instanceof EnrollError && err.upgradeUrl) {
-                const interactive = canOfferTeamUpgrade();
-                console.error(chalk.red(formatEnrollFailureMessage(err, { urlOnly: !interactive })));
-                const exposure = err.code === "billing_required"
-                    ? queueCliLimitNoticeExposure("agents", "refusal")
-                    : null;
-                if (interactive) {
-                    try {
-                        const opened = await offerUpgradeLink(err.upgradeUrl, { interactive: true });
-                        if (opened)
-                            queueCliLimitNoticeEngagement(exposure);
-                    }
-                    catch (openErr) {
-                        const message = openErr instanceof Error ? openErr.message : String(openErr);
-                        console.error(chalk.dim(`Could not open the upgrade link automatically: ${message}`));
-                    }
-                }
-            }
-            else {
-                console.error(chalk.red(err instanceof Error ? err.message : String(err)));
-            }
-            // Let the CLI's bounded finalization flush the best-effort prompt
-            // telemetry before the process exits with the same failure status.
-            process.exitCode = 1;
-        }
-    });
-}
-//# sourceMappingURL=agent-enroll.js.map

package/dist/commands/agent-inbox.d.ts

@@ -1,9 +0,0 @@
-/**
- * `hq agent inbox` — what a woken bot runs to see and clear its HQ mail.
- *
- *   hq agent inbox [--all] [--json]   pending items (oldest first), or all
- *   hq agent inbox done <id...>       mark handled locally and ack on the server
- */
-import { Command } from "commander";
-export declare function registerAgentInboxCommand(agent: Command): void;
-//# sourceMappingURL=agent-inbox.d.ts.map

package/dist/commands/agent-inbox.js

@@ -1,102 +0,0 @@
-/**
- * `hq agent inbox` — what a woken bot runs to see and clear its HQ mail.
- *
- *   hq agent inbox [--all] [--json]   pending items (oldest first), or all
- *   hq agent inbox done <id...>       mark handled locally and ack on the server
- */
-import chalk from "chalk";
-import * as os from "node:os";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch } from "../utils/vault-api.js";
-import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../lib/agent-kit/inbox-state.js";
-import { agentKitPaths } from "../lib/agent-kit/paths.js";
-import { requireExternalCreds } from "./agent-kit.js";
-const ID_RE = /^[A-Za-z0-9._:-]{1,200}$/;
-export function registerAgentInboxCommand(agent) {
-    const inbox = agent
-        .command("inbox")
-        .description("List this agent's pending HQ messages (mirrored by the kit), or mark them handled")
-        .option("--all", "Include items already marked handled")
-        .option("--json", "Print machine-readable JSON")
-        .action(async (opts) => {
-        const paths = agentKitPaths(os.homedir(), process.env);
-        const creds = requireExternalCreds(paths);
-        const done = readDoneIds(paths);
-        // Merged with the server, never the local mirror alone: a dead kit
-        // poller would otherwise make this command answer confidently with
-        // yesterday's mail and no sign anything was wrong.
-        const { entries, note } = await mergeAgentInbox(paths, async () => {
-            const token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
-            const res = await vaultApiFetch({
-                token,
-                baseUrl: creds.apiBaseUrl,
-                path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`,
-            });
-            return { status: res.status, body: await res.json().catch(() => ({})) };
-        });
-        const rows = entries
-            .filter((e) => opts.all || !done.has(e.id))
-            .map((e) => summarizeInboxEntry(e, done.has(e.id)));
-        if (opts.json) {
-            console.log(JSON.stringify({ count: rows.length, messages: rows, ...(note ? { note } : {}) }, null, 2));
-            return;
-        }
-        if (note)
-            console.error(chalk.yellow(note));
-        if (rows.length === 0) {
-            console.log(opts.all ? "Inbox is empty." : "No pending messages.");
-            return;
-        }
-        for (const r of rows) {
-            const state = r.done ? chalk.dim(" (done)") : "";
-            console.log(`${chalk.bold(r.id)}${state}  ${r.channel ?? "?"}  from ${r.from}${r.fromUid ? ` <${r.fromUid}>` : ""}  ${r.at ?? ""}`);
-            if (r.text)
-                console.log(`  ${r.text.replace(/\n/g, "\n  ")}`);
-            for (const f of r.attachments ?? []) {
-                const label = f.name ?? f.vaultPath.split("/").pop() ?? "file";
-                const type = f.contentType ? ` (${f.contentType})` : "";
-                console.log(`  ${chalk.dim("[file]")} ${label}${type}`);
-                console.log(`    ${chalk.dim(`vault: ${f.vaultPath}`)}`);
-            }
-        }
-        if (!opts.all)
-            console.log(chalk.dim(`\nReply with hq dm <uid> "…", then: hq agent inbox done <id>`));
-    });
-    inbox
-        .command("done <ids...>")
-        .description("Mark inbox items handled and ack them on the server")
-        .action(async (ids) => {
-        const bad = ids.filter((id) => !ID_RE.test(id));
-        if (bad.length) {
-            console.error(chalk.red(`Invalid id(s): ${bad.join(", ")}`));
-            process.exit(1);
-        }
-        const paths = agentKitPaths(os.homedir(), process.env);
-        const creds = requireExternalCreds(paths);
-        const added = markInboxDone(paths, ids);
-        process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
-        process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
-        process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
-        let acked = 0;
-        try {
-            const token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
-            for (const id of ids) {
-                const res = await vaultApiFetch({
-                    token,
-                    baseUrl: creds.apiBaseUrl,
-                    path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox/${encodeURIComponent(id)}/ack`,
-                    method: "POST",
-                });
-                if (res.ok)
-                    acked += 1;
-                else
-                    console.error(chalk.yellow(`server ack ${id} → ${res.status}`));
-            }
-        }
-        catch (err) {
-            console.error(chalk.yellow(`server ack skipped: ${err instanceof Error ? err.message : String(err)}`));
-        }
-        console.log(`Marked ${added.length} handled (${ids.length - added.length} already done); server acked ${acked}.`);
-    });
-}
-//# sourceMappingURL=agent-inbox.js.map