@indigoai-us/hq-cli 5.115.5 → 5.116.0

package/dist/commands/agent-enroll.js

@@ -0,0 +1,273 @@
+/**
+ * `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 { networkTransportErrorCode } from "../utils/network-transport-error.js";
+import { generateHostKeyPair, machineCredsFileExists, readExternalMachineCreds, writeHostKeyPair, writeMachineCreds, } from "../lib/agent-kit/creds.js";
+import { agentKitPaths } 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" };
+}
+export function refusalMessage(existing) {
+    switch (existing.kind) {
+        case "none":
+            return null;
+        case "human":
+            return (`A human HQ session exists at ${existing.file}. An agent identity must not ` +
+                `share a host account with a person's login. Run enrollment under a dedicated ` +
+                `user (or container), or pass --replace to enroll 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;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "EnrollError";
+    }
+}
+/** 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);
+    }
+    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",
+        },
+    };
+}
+/** 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 paths = deps.paths ?? agentKitPaths(os.homedir(), env);
+    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}.`);
+    }
+    const existing = 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)();
+    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) {
+        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,
+    };
+    writeMachineCreds(paths, creds);
+    return {
+        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 }
+            : {}),
+    };
+}
+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("--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,
+            });
+            console.log(chalk.green(`Enrolled as ${result.agentUid} in ${result.companySlug}.`));
+            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("  hq whoami                # should report the agent identity");
+            console.log("  hq agent kit install     # sync, work-mesh, inbox and heartbeat services");
+            console.log("  hq agent probe           # end-to-end check, reported to the console");
+        }
+        catch (err) {
+            console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=agent-enroll.js.map

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

@@ -0,0 +1,53 @@
+/**
+ * `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
+ *   mesh       work-mesh doorbell listener        → component-mesh
+ *   inbox      inbox poller (mirror + optional ack) → component-inbox
+ *   heartbeat  60 s POST /v1/agents/{uid}/heartbeat with the three above
+ *
+ * `install` renders one user-level unit per service (LaunchAgent on macOS,
+ * systemd --user on Linux), each of which just runs
+ * `node hq agent kit run <service>`; the Docker image runs the same four
+ * commands. 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 ServiceHostPaths, type ServiceManagerDeps, type ServiceSetResult } from "../lib/service-manager/index.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;
+}
+export interface KitInstallResult {
+    config: KitConfig;
+    skills: string[];
+    services: ServiceSetResult;
+}
+export declare function installKit(paths: AgentKitPaths, opts: KitInstallOptions, host: ServiceHostPaths, deps?: ServiceManagerDeps): 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;
+}
+export declare function buildKitRuntime(service: KitService): KitRuntime;
+export declare function runKitService(service: KitService, rt: KitRuntime): Promise<void>;
+export declare function registerAgentKitCommand(agent: Command): void;
+//# sourceMappingURL=agent-kit.d.ts.map

package/dist/commands/agent-kit.js

@@ -0,0 +1,260 @@
+/**
+ * `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
+ *   mesh       work-mesh doorbell listener        → component-mesh
+ *   inbox      inbox poller (mirror + optional ack) → component-inbox
+ *   heartbeat  60 s POST /v1/agents/{uid}/heartbeat with the three above
+ *
+ * `install` renders one user-level unit per service (LaunchAgent on macOS,
+ * systemd --user on Linux), each of which just runs
+ * `node hq agent kit run <service>`; the Docker image runs the same four
+ * commands. Logs: ~/.hq-agent/logs/<service>.log. Skills:
+ * ~/.hq-agent/skills/<name>/SKILL.md.
+ */
+import chalk from "chalk";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { CLI_VERSION } from "../cli-version.js";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { readExternalMachineCreds, } from "../lib/agent-kit/creds.js";
+import { defaultKitConfig, readKitConfig, writeKitConfig, } from "../lib/agent-kit/kit-config.js";
+import { createKitLogger } from "../lib/agent-kit/log.js";
+import { agentKitPaths } from "../lib/agent-kit/paths.js";
+import { isKitService, KIT_SERVICES, kitServiceSpecs, } from "../lib/agent-kit/services.js";
+import { writeKitSkills } from "../lib/agent-kit/skills.js";
+import { runHeartbeatLoop } from "../lib/agent-kit/run/heartbeat.js";
+import { runInboxLoop } from "../lib/agent-kit/run/inbox.js";
+import { startMeshListener } from "../lib/agent-kit/run/mesh-listener.js";
+import { runSyncLoop } from "../lib/agent-kit/run/sync.js";
+import { resolveHqBinary, resolveNodeBinary, } from "../lib/mesh/live/daemon/install.js";
+import { installServices, servicesStatus, uninstallServices, } from "../lib/service-manager/index.js";
+export class KitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "KitError";
+    }
+}
+/** Load the external creds or explain exactly what to run first. */
+export function requireExternalCreds(paths) {
+    const creds = readExternalMachineCreds(paths);
+    if (!creds) {
+        throw new KitError(`No external agent credentials at ${paths.machineCredsPath}. Run ` +
+            `\`hq agent enroll <code>\` first (an admin creates the code in the HQ console).`);
+    }
+    return creds;
+}
+export function ensureKitDirs(paths) {
+    for (const d of [paths.agentDir, paths.stateDir, paths.inboxDir, paths.logsDir, paths.skillsDir]) {
+        fs.mkdirSync(d, { recursive: true, mode: 0o700 });
+    }
+}
+export function resolveServiceHost(paths) {
+    return {
+        home: paths.home,
+        nodeBinary: resolveNodeBinary(),
+        hqBinary: resolveHqBinary(),
+    };
+}
+export function installKit(paths, opts, host, deps = {}) {
+    requireExternalCreds(paths);
+    ensureKitDirs(paths);
+    const existing = fs.existsSync(paths.kitConfigPath)
+        ? readKitConfig(paths, CLI_VERSION)
+        : defaultKitConfig(paths, CLI_VERSION);
+    const config = {
+        ...existing,
+        ...(opts.hqRoot ? { hqRoot: opts.hqRoot } : {}),
+        ...(opts.inboxAck !== undefined ? { inboxAck: opts.inboxAck } : {}),
+        cliVersion: CLI_VERSION,
+    };
+    fs.mkdirSync(config.hqRoot, { recursive: true, mode: 0o700 });
+    writeKitConfig(paths, config);
+    const skills = writeKitSkills(paths);
+    const services = installServices(kitServiceSpecs(paths), host, {
+        ...deps,
+        activate: opts.activate ?? deps.activate ?? true,
+    });
+    return { config, skills, services };
+}
+export function formatServiceSet(result) {
+    const lines = [];
+    for (const u of result.units) {
+        const state = !u.installed
+            ? chalk.dim("not installed")
+            : u.running === true
+                ? chalk.green("running")
+                : u.running === false
+                    ? chalk.yellow(u.error ? `not running — ${u.error}` : "installed (not running)")
+                    : chalk.dim("installed");
+        lines.push(`  ${u.name.padEnd(10)} ${state}${u.unitPath ? chalk.dim(`  ${u.unitPath}`) : ""}`);
+    }
+    if (result.manualCommands) {
+        lines.push("  No service manager on this platform. Run each service yourself:");
+        for (const c of result.manualCommands)
+            lines.push(`    ${c}`);
+    }
+    return lines;
+}
+export function buildKitRuntime(service) {
+    const paths = agentKitPaths(os.homedir(), process.env);
+    const creds = requireExternalCreds(paths);
+    ensureKitDirs(paths);
+    const config = readKitConfig(paths, CLI_VERSION);
+    // Pin every mint in this process (and any child `hq`) to the kit's creds
+    // and control plane — the same values the enrolled file carries.
+    process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
+    process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
+    process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
+    const log = createKitLogger(paths, service, { echo: true });
+    const getToken = () => ensureCognitoToken({ tokenSource: "machine", interactive: false });
+    return { paths, creds, config, getToken, log };
+}
+export async function runKitService(service, rt) {
+    rt.log("info", `${service} starting agent=${rt.creds.entityUid} cli=${CLI_VERSION}`);
+    switch (service) {
+        case "sync":
+            await runSyncLoop({
+                paths: rt.paths,
+                hqRoot: rt.config.hqRoot,
+                intervalMs: rt.config.syncIntervalMs,
+                log: rt.log,
+            });
+            return;
+        case "heartbeat":
+            await runHeartbeatLoop({
+                paths: rt.paths,
+                agentUid: rt.creds.entityUid,
+                apiBaseUrl: rt.creds.apiBaseUrl,
+                intervalMs: rt.config.heartbeatIntervalMs,
+                getToken: rt.getToken,
+                log: rt.log,
+            });
+            return;
+        case "inbox":
+            await runInboxLoop({
+                paths: rt.paths,
+                agentUid: rt.creds.entityUid,
+                apiBaseUrl: rt.creds.apiBaseUrl,
+                pollMs: rt.config.inboxPollMs,
+                ack: rt.config.inboxAck,
+                getToken: rt.getToken,
+                log: rt.log,
+            });
+            return;
+        case "mesh": {
+            const handle = await startMeshListener({
+                paths: rt.paths,
+                agentUid: rt.creds.entityUid,
+                apiBaseUrl: rt.creds.apiBaseUrl,
+                refreshMs: rt.config.meshRefreshMs,
+                getToken: rt.getToken,
+                log: rt.log,
+            });
+            const stop = () => {
+                void handle.stop().then(() => process.exit(0));
+            };
+            process.once("SIGTERM", stop);
+            process.once("SIGINT", stop);
+            await new Promise(() => {
+                /* resident until signalled */
+            });
+            return;
+        }
+    }
+}
+function fail(err) {
+    console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+    process.exit(1);
+}
+export function registerAgentKitCommand(agent) {
+    const kit = agent
+        .command("kit")
+        .description("Install, inspect, or run the external-agent background services");
+    kit
+        .command("install")
+        .description("Install sync, work-mesh, inbox and heartbeat services plus the skills directory")
+        .option("--hq-root <path>", "Local HQ tree to sync the company vault into (default: ~/.hq-agent/hq)")
+        .option("--inbox-ack", "Ack mirrored inbox items on the server (default: leave acking to the bot)")
+        .option("--no-activate", "Write unit files but do not load them")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            const result = installKit(paths, { hqRoot: opts.hqRoot, inboxAck: opts.inboxAck, activate: opts.activate }, resolveServiceHost(paths));
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+                return;
+            }
+            console.log(chalk.green("HQ agent kit installed."));
+            console.log(`  hq root:   ${result.config.hqRoot}`);
+            console.log(`  logs:      ${paths.logsDir}`);
+            console.log(`  skills:    ${paths.skillsDir} (${result.skills.length} skills)`);
+            console.log("  services:");
+            for (const line of formatServiceSet(result.services))
+                console.log(line);
+            console.log("");
+            console.log("Next: hq agent probe");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    kit
+        .command("status")
+        .description("Show whether each kit service is installed and running")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            const result = servicesStatus(kitServiceSpecs(paths), resolveServiceHost(paths));
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+                return;
+            }
+            for (const line of formatServiceSet(result))
+                console.log(line);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    kit
+        .command("uninstall")
+        .description("Stop and remove the kit services (credentials and skills are kept)")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            const result = uninstallServices(kitServiceSpecs(paths), resolveServiceHost(paths));
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+                return;
+            }
+            console.log(chalk.green("HQ agent kit services removed."));
+            for (const line of formatServiceSet(result))
+                console.log(line);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    kit
+        .command("run <service>")
+        .description(`Run one kit service in the foreground (${KIT_SERVICES.join("|")})`)
+        .action(async (service) => {
+        if (!isKitService(service)) {
+            console.error(chalk.red(`Unknown kit service "${service}". Expected one of: ${KIT_SERVICES.join(", ")}`));
+            process.exit(1);
+        }
+        try {
+            const rt = buildKitRuntime(service);
+            await runKitService(service, rt);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+//# sourceMappingURL=agent-kit.js.map

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

@@ -0,0 +1,22 @@
+/**
+ * `hq agent mcp` — stdio MCP server backed by ~/.hq-agent/machine-creds.json.
+ *
+ * The console recipes register HQ in the bot's framework as
+ *   { command: "hq", args: ["agent", "mcp"], env: { HQ_MACHINE_CREDS_FILE: … } }
+ * so this command must never print anything but JSON-RPC on stdout; all
+ * diagnostics go to stderr. Tools wrap existing CLI capability (see
+ * lib/agent-kit/mcp/tools.ts); subprocess tools re-invoke the same node +
+ * hq binary with the machine-identity env pinned.
+ */
+import { Command } from "commander";
+import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
+import { type HqRunResult, type McpToolClients } from "../lib/agent-kit/mcp/tools.js";
+import type { ExternalMachineCreds } from "../lib/agent-kit/creds.js";
+export declare const AGENT_MCP_SERVER_NAME = "hq-agent";
+export declare const AGENT_MCP_INSTRUCTIONS: string;
+export declare const HQ_SUBPROCESS_TIMEOUT_MS = 120000;
+export declare function defaultRunHq(nodeBinary: string, hqBinary: string, env: NodeJS.ProcessEnv): (args: string[]) => Promise<HqRunResult>;
+export declare function defaultMcpClients(creds: ExternalMachineCreds, credsPath: string): McpToolClients;
+export declare function createAgentMcpServer(clients: McpToolClients): McpServer;
+export declare function registerAgentMcpCommand(agent: Command): void;
+//# sourceMappingURL=agent-mcp.d.ts.map