@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/commands/agent-enroll.js

@@ -0,0 +1,401 @@
+/**
+ * `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

@@ -0,0 +1,9 @@
+/**
+ * `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

@@ -0,0 +1,102 @@
+/**
+ * `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

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

@@ -0,0 +1,87 @@
+/**
+ * `hq agent kit install|status|uninstall|run <service>` — the resident
+ * services that make an external agent a full team member:
+ *
+ *   sync       company vault pull loop            → component-sync
+ *   inbox      inbox poller (mirror + optional ack) → component-inbox
+ *   heartbeat  60 s POST /v1/agents/{uid}/heartbeat with enabled component status
+ *
+ * `install` renders one user-level unit per enabled service (LaunchAgent on
+ * macOS, systemd --user on Linux), each of which just runs
+ * `node hq agent kit run <service>`. The Docker entrypoint runs
+ * `hq agent kit run all`, which supervises the services enabled in kit.json,
+ * including sync only when file mirroring is configured. Hosts where the
+ * service manager is unusable, such as a missing systemd user session bus or
+ * unavailable launchd, fall back to one
+ * detached `hq agent kit run all` supervisor (pid in ~/.hq-agent/kit.pid,
+ * output in ~/.hq-agent/logs/kit.log). Logs: ~/.hq-agent/logs/<service>.log. Skills:
+ * ~/.hq-agent/skills/<name>/SKILL.md.
+ */
+import { Command } from "commander";
+import { type ExternalMachineCreds } from "../lib/agent-kit/creds.js";
+import { type KitConfig } from "../lib/agent-kit/kit-config.js";
+import { type KitLogger } from "../lib/agent-kit/log.js";
+import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
+import { type KitService } from "../lib/agent-kit/services.js";
+import { type CronRunner, type RebootCronResult, type DetachedSpawn, type KillFn } from "../lib/agent-kit/fallback.js";
+import { type ServiceHostPaths, type ServiceManagerDeps, type ServiceSetResult } from "../lib/service-manager/index.js";
+import type { HeartbeatCredsSource } from "../lib/heartbeat-identity.js";
+export declare class KitError extends Error {
+    constructor(message: string);
+}
+/** Load the external creds or explain exactly what to run first. */
+export declare function requireExternalCreds(paths: AgentKitPaths): ExternalMachineCreds;
+export declare function ensureKitDirs(paths: AgentKitPaths): void;
+export declare function resolveServiceHost(paths: AgentKitPaths): ServiceHostPaths;
+export interface KitInstallOptions {
+    hqRoot?: string;
+    inboxAck?: boolean;
+    activate?: boolean;
+    /**
+     * Mirror the company vault onto local disk. Off unless asked for: a bot
+     * reads and writes vault files on demand through the `hq` MCP server, so the
+     * sync loop is not installed at all rather than installed and left failing
+     * on a host that cannot finish a full-copy download.
+     */
+    syncFiles?: boolean;
+}
+export interface KitFallbackInfo {
+    mode: "fallback";
+    pid: number;
+    pidFile: string;
+    logPath: string;
+    /** The @reboot entry that restarts the supervisor. */
+    crontab: string;
+    /** Whether that entry was installed for you, and why not if it was not. */
+    reboot: RebootCronResult;
+}
+export interface KitInstallResult {
+    config: KitConfig;
+    skills: string[];
+    services: ServiceSetResult;
+    fallback?: KitFallbackInfo;
+}
+export interface KitFallbackDeps {
+    spawn?: DetachedSpawn;
+    kill?: KillFn;
+    /** Injected crontab runner (tests). */
+    cron?: CronRunner;
+}
+export declare function installKit(paths: AgentKitPaths, opts: KitInstallOptions, host: ServiceHostPaths, deps?: ServiceManagerDeps, fallbackDeps?: KitFallbackDeps): KitInstallResult;
+export declare function formatServiceSet(result: ServiceSetResult): string[];
+/** Shared runtime for `kit run <service>`. */
+export interface KitRuntime {
+    paths: AgentKitPaths;
+    creds: ExternalMachineCreds;
+    config: KitConfig;
+    getToken: () => Promise<string>;
+    log: KitLogger;
+    credsSource?: HeartbeatCredsSource;
+}
+export declare function buildKitRuntime(service: KitService | "all"): KitRuntime;
+export declare function runKitService(service: KitService, rt: KitRuntime): Promise<void>;
+/** `kit run all`: supervise the kit services as child processes with restart backoff. */
+export declare function runAllKitServices(rt: KitRuntime, host: ServiceHostPaths): Promise<void>;
+export declare function formatFallbackStatus(paths: AgentKitPaths, kill?: KillFn): string[] | null;
+export declare function registerAgentKitCommand(agent: Command): void;
+//# sourceMappingURL=agent-kit.d.ts.map