@indigoai-us/hq-cli 5.115.6 → 5.116.0

package/dist/commands/agent-mcp.js

@@ -0,0 +1,104 @@
+/**
+ * `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 { spawn } from "node:child_process";
+import * as os from "node:os";
+import { CLI_VERSION } from "../cli-version.js";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
+import { buildAgentMcpTools } from "../lib/agent-kit/mcp/tools.js";
+import { agentKitPaths } from "../lib/agent-kit/paths.js";
+import { requireExternalCreds } from "./agent-kit.js";
+export const AGENT_MCP_SERVER_NAME = "hq-agent";
+export const AGENT_MCP_INSTRUCTIONS = "You are acting inside HQ as an enrolled external agent. Tools run as that machine identity: " +
+    "hq_whoami (identity), hq_search / hq_files_list / hq_files_read (company vault), " +
+    "hq_secrets_list / hq_secrets_exec (secrets by NAME only — values are never returned), " +
+    "hq_dm_send / hq_inbox_read (direct messages), hq_work_mesh_status (what the team is doing). " +
+    "Never ask a user for a token or secret value; if a secret is missing, name it and ask an admin to add it.";
+export const HQ_SUBPROCESS_TIMEOUT_MS = 120_000;
+export function defaultRunHq(nodeBinary, hqBinary, env) {
+    return (args) => new Promise((resolve) => {
+        const child = spawn(nodeBinary, [hqBinary, ...args], {
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => child.kill("SIGKILL"), HQ_SUBPROCESS_TIMEOUT_MS);
+        child.stdout.on("data", (d) => (stdout += d.toString("utf8")));
+        child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ code: 127, stdout, stderr: `${stderr}\n${err.message}` });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}
+export function defaultMcpClients(creds, credsPath) {
+    const env = {
+        ...process.env,
+        HQ_MACHINE_CREDS_FILE: credsPath,
+        HQ_REQUIRE_MACHINE_IDENTITY: "1",
+        HQ_VAULT_API_URL: creds.apiBaseUrl,
+        NO_COLOR: "1",
+    };
+    return {
+        creds,
+        runHq: defaultRunHq(process.execPath, process.argv[1], env),
+        getToken: () => ensureCognitoToken({ tokenSource: "machine", interactive: false }),
+        apiJson: async (token, path, init) => {
+            const res = await vaultApiFetch({
+                token,
+                baseUrl: creds.apiBaseUrl,
+                path,
+                method: init?.method,
+                body: init?.body,
+                query: init?.query,
+            });
+            const body = await res.json().catch(() => ({}));
+            return { status: res.status, body };
+        },
+    };
+}
+export function createAgentMcpServer(clients) {
+    return new McpServer({
+        name: AGENT_MCP_SERVER_NAME,
+        version: CLI_VERSION,
+        instructions: AGENT_MCP_INSTRUCTIONS,
+        tools: buildAgentMcpTools(clients),
+    });
+}
+export function registerAgentMcpCommand(agent) {
+    agent
+        .command("mcp")
+        .description("Serve HQ as a stdio MCP server for the bot framework (whoami, search, files, secrets-exec, dm, inbox, work-mesh)")
+        .action(async () => {
+        const paths = agentKitPaths(os.homedir(), process.env);
+        let creds;
+        try {
+            creds = requireExternalCreds(paths);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
+        process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
+        process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
+        const server = createAgentMcpServer(defaultMcpClients(creds, paths.machineCredsPath));
+        process.stderr.write(`hq agent mcp: serving as ${creds.entityUid} (${creds.companySlug})\n`);
+        await server.serve(process.stdin, process.stdout);
+    });
+}
+//# sourceMappingURL=agent-mcp.js.map

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

@@ -0,0 +1,71 @@
+/**
+ * `hq agent probe` — end-to-end check that this host is a working external
+ * team member, one line per check, non-zero exit on any failure:
+ *
+ *   whoami       mint as the machine identity; token names this agent
+ *   team-sync    `hq sync pull --all` succeeds and the company folder exists
+ *   work-mesh    realtime credentials vend for this agent and the roster row
+ *                shows presence online/stale (heartbeat landed)
+ *   dm           send a DM to self via the notify surface and read it back
+ *   secrets      `GET /secrets/{companyUid}` answers 200
+ *
+ * Output is the exact shape the console recipes promise: one
+ * `PASS  <check>  <detail>` / `FAIL  <check>  <detail>` line per check, then
+ * `heartbeat  <age>`.
+ *
+ * The result is POSTed to /v1/agents/{uid}/probe-result (api-contract v1) so
+ * the console can flip the enrollment to "Enrolled". Also reports the age of
+ * the kit's last heartbeat.
+ */
+import { Command } from "commander";
+import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
+import type { ExternalMachineCreds } from "../lib/agent-kit/creds.js";
+export interface ProbeCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+export interface ProbeResult {
+    passed: boolean;
+    checks: ProbeCheck[];
+    at: string;
+    /** Seconds since the kit's last successful heartbeat, or null if never. */
+    heartbeatAgeSeconds: number | null;
+}
+export declare const DM_ROUNDTRIP_TIMEOUT_MS = 20000;
+export declare const DM_ROUNDTRIP_POLL_MS = 2000;
+export interface ProbeDeps {
+    paths: AgentKitPaths;
+    creds: ExternalMachineCreds;
+    hqRoot: string;
+    getToken: () => Promise<string>;
+    resolveCompanyUid: (token: string, slug: string) => Promise<string>;
+    runPull: (args: string[]) => Promise<number>;
+    vendRealtime: (token: string) => Promise<{
+        actorUid: string;
+    }>;
+    listRoster: (token: string, companyUid: string) => Promise<Array<Record<string, unknown>>>;
+    sendDm: (token: string, toUid: string, body: string) => Promise<void>;
+    readThread: (token: string, withUid: string) => Promise<Array<{
+        body: string;
+    }>>;
+    listSecrets: (token: string, companyUid: string) => Promise<number>;
+    postResult: (token: string, result: ProbeResult) => Promise<number>;
+    now?: () => Date;
+    sleep?: (ms: number) => Promise<void>;
+    nonce?: () => string;
+    dmTimeoutMs?: number;
+}
+export declare function heartbeatAgeSeconds(paths: Pick<AgentKitPaths, "lastHeartbeatPath">, now?: () => Date): number | null;
+export declare function runProbe(deps: ProbeDeps): Promise<ProbeResult>;
+export declare function formatHeartbeatAge(age: number | null): string;
+/**
+ * Recipe contract: `PASS  <check>  <detail>` / `FAIL  <check>  <detail>` per
+ * check, then `heartbeat  <age>`. Two-space separators; no trailing verdict
+ * line (the exit code carries it, and the console keys only on the POSTed
+ * probe-result).
+ */
+export declare function formatProbeReport(result: ProbeResult, color?: boolean): string[];
+export declare function defaultProbeDeps(paths: AgentKitPaths, creds: ExternalMachineCreds): ProbeDeps;
+export declare function registerAgentProbeCommand(agent: Command): void;
+//# sourceMappingURL=agent-probe.d.ts.map

package/dist/commands/agent-probe.js

@@ -0,0 +1,294 @@
+/**
+ * `hq agent probe` — end-to-end check that this host is a working external
+ * team member, one line per check, non-zero exit on any failure:
+ *
+ *   whoami       mint as the machine identity; token names this agent
+ *   team-sync    `hq sync pull --all` succeeds and the company folder exists
+ *   work-mesh    realtime credentials vend for this agent and the roster row
+ *                shows presence online/stale (heartbeat landed)
+ *   dm           send a DM to self via the notify surface and read it back
+ *   secrets      `GET /secrets/{companyUid}` answers 200
+ *
+ * Output is the exact shape the console recipes promise: one
+ * `PASS  <check>  <detail>` / `FAIL  <check>  <detail>` line per check, then
+ * `heartbeat  <age>`.
+ *
+ * The result is POSTed to /v1/agents/{uid}/probe-result (api-contract v1) so
+ * the console can flip the enrollment to "Enrolled". Also reports the age of
+ * the kit's last heartbeat.
+ */
+import chalk from "chalk";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
+import { CLI_VERSION } from "../cli-version.js";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { peekIdToken } from "../utils/id-token.js";
+import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { listAgents, readAgentThread, sendAgentDm } from "./agents.js";
+import { createContract3Fetcher } from "../lib/mesh/live/daemon/credentials.js";
+import { agentKitPaths } from "../lib/agent-kit/paths.js";
+import { readKitConfig } from "../lib/agent-kit/kit-config.js";
+import { readLastHeartbeat } from "../lib/agent-kit/run/heartbeat.js";
+import { defaultRunPull, syncPullArgs } from "../lib/agent-kit/run/sync.js";
+import { requireExternalCreds } from "./agent-kit.js";
+export const DM_ROUNDTRIP_TIMEOUT_MS = 20_000;
+export const DM_ROUNDTRIP_POLL_MS = 2_000;
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function heartbeatAgeSeconds(paths, now = () => new Date()) {
+    const last = readLastHeartbeat(paths);
+    if (!last)
+        return null;
+    const at = new Date(last.at).getTime();
+    if (Number.isNaN(at))
+        return null;
+    return Math.max(0, Math.round((now().getTime() - at) / 1000));
+}
+export async function runProbe(deps) {
+    const now = deps.now ?? (() => new Date());
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const nonce = (deps.nonce ?? (() => randomBytes(6).toString("hex")))();
+    const self = deps.creds.entityUid;
+    const checks = [];
+    let token = null;
+    let companyUid = null;
+    // 1. whoami
+    try {
+        token = await deps.getToken();
+        const claims = peekIdToken(token);
+        const uid = claims["custom:entityUid"];
+        const type = claims["custom:entityType"];
+        if (type === "agent" && uid === self) {
+            checks.push({ name: "whoami", ok: true, detail: `${self} (external, ${deps.creds.companySlug})` });
+        }
+        else {
+            checks.push({
+                name: "whoami",
+                ok: false,
+                detail: `token names ${String(type)}:${String(uid)}, expected agent:${self}`,
+            });
+            token = null;
+        }
+    }
+    catch (err) {
+        checks.push({ name: "whoami", ok: false, detail: `mint failed: ${errText(err)}` });
+    }
+    if (token) {
+        try {
+            companyUid = await deps.resolveCompanyUid(token, deps.creds.companySlug);
+        }
+        catch (err) {
+            checks.push({ name: "company", ok: false, detail: `cannot resolve ${deps.creds.companySlug}: ${errText(err)}` });
+        }
+    }
+    // 2. team-sync
+    if (token) {
+        try {
+            const code = await deps.runPull(syncPullArgs(deps.hqRoot));
+            const companyDir = path.join(deps.hqRoot, "companies", deps.creds.companySlug);
+            const present = fs.existsSync(companyDir);
+            const ok = code === 0 && present;
+            checks.push({
+                name: "team-sync",
+                ok,
+                detail: ok
+                    ? `synced into ${companyDir}`
+                    : code !== 0
+                        ? `hq sync pull exited ${code}`
+                        : `sync exited 0 but ${companyDir} is missing`,
+            });
+        }
+        catch (err) {
+            checks.push({ name: "team-sync", ok: false, detail: errText(err) });
+        }
+    }
+    else {
+        checks.push({ name: "team-sync", ok: false, detail: "skipped: no token" });
+    }
+    // 3. mesh-presence
+    if (token && companyUid) {
+        try {
+            const vend = await deps.vendRealtime(token);
+            if (vend.actorUid !== self) {
+                checks.push({ name: "work-mesh", ok: false, detail: `realtime vend is for ${vend.actorUid}` });
+            }
+            else {
+                const roster = await deps.listRoster(token, companyUid);
+                const row = roster.find((r) => r.uid === self);
+                const presence = typeof row?.presence === "string" ? row.presence : "unknown";
+                const last = typeof row?.lastHeartbeatAt === "string" ? row.lastHeartbeatAt : "never";
+                const ok = presence === "online" || presence === "stale";
+                checks.push({
+                    name: "work-mesh",
+                    ok,
+                    detail: row
+                        ? `realtime vend ok; presence=${presence} lastHeartbeatAt=${last}${ok ? "" : " — is `hq agent kit` installed and running?"}`
+                        : "realtime vend ok but this agent is not on the company roster",
+                });
+            }
+        }
+        catch (err) {
+            checks.push({ name: "work-mesh", ok: false, detail: errText(err) });
+        }
+    }
+    else {
+        checks.push({ name: "work-mesh", ok: false, detail: "skipped: no token/company" });
+    }
+    // 4. dm-roundtrip
+    if (token) {
+        try {
+            const body = `hq agent probe ${nonce}`;
+            await deps.sendDm(token, self, body);
+            const deadline = now().getTime() + (deps.dmTimeoutMs ?? DM_ROUNDTRIP_TIMEOUT_MS);
+            let found = false;
+            for (;;) {
+                const msgs = await deps.readThread(token, self);
+                if (msgs.some((m) => typeof m.body === "string" && m.body.includes(nonce))) {
+                    found = true;
+                    break;
+                }
+                if (now().getTime() >= deadline)
+                    break;
+                await sleep(DM_ROUNDTRIP_POLL_MS);
+            }
+            checks.push({
+                name: "dm",
+                ok: found,
+                detail: found ? "sent to self via /v1/notify/dm and read back" : `sent but not visible in thread after ${Math.round((deps.dmTimeoutMs ?? DM_ROUNDTRIP_TIMEOUT_MS) / 1000)}s`,
+            });
+        }
+        catch (err) {
+            checks.push({ name: "dm", ok: false, detail: errText(err) });
+        }
+    }
+    else {
+        checks.push({ name: "dm", ok: false, detail: "skipped: no token" });
+    }
+    // 5. secrets-list
+    if (token && companyUid) {
+        try {
+            const status = await deps.listSecrets(token, companyUid);
+            checks.push({
+                name: "secrets",
+                ok: status === 200,
+                detail: status === 200 ? `GET /secrets/${companyUid} → 200` : `GET /secrets/${companyUid} → ${status}`,
+            });
+        }
+        catch (err) {
+            checks.push({ name: "secrets", ok: false, detail: errText(err) });
+        }
+    }
+    else {
+        checks.push({ name: "secrets", ok: false, detail: "skipped: no token/company" });
+    }
+    const result = {
+        passed: checks.every((c) => c.ok),
+        checks,
+        at: now().toISOString(),
+        heartbeatAgeSeconds: heartbeatAgeSeconds(deps.paths, now),
+    };
+    if (token) {
+        try {
+            const status = await deps.postResult(token, result);
+            if (status < 200 || status >= 300) {
+                result.checks.push({ name: "report", ok: false, detail: `probe-result POST → ${status}` });
+                result.passed = false;
+            }
+        }
+        catch (err) {
+            result.checks.push({ name: "report", ok: false, detail: `probe-result POST failed: ${errText(err)}` });
+            result.passed = false;
+        }
+    }
+    return result;
+}
+export function formatHeartbeatAge(age) {
+    if (age === null)
+        return "never (kit heartbeat has not posted yet)";
+    if (age < 90)
+        return `${age}s ago`;
+    if (age < 3600)
+        return `${Math.round(age / 60)}m ago`;
+    return `${(age / 3600).toFixed(1)}h ago`;
+}
+/**
+ * Recipe contract: `PASS  <check>  <detail>` / `FAIL  <check>  <detail>` per
+ * check, then `heartbeat  <age>`. Two-space separators; no trailing verdict
+ * line (the exit code carries it, and the console keys only on the POSTed
+ * probe-result).
+ */
+export function formatProbeReport(result, color = true) {
+    const pass = color ? chalk.green("PASS") : "PASS";
+    const failTag = color ? chalk.red("FAIL") : "FAIL";
+    const lines = result.checks.map((c) => `${c.ok ? pass : failTag}  ${c.name}  ${c.detail}`);
+    lines.push(`heartbeat  ${formatHeartbeatAge(result.heartbeatAgeSeconds)}`);
+    return lines;
+}
+export function defaultProbeDeps(paths, creds) {
+    process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
+    process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
+    process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
+    const config = readKitConfig(paths, CLI_VERSION);
+    const base = creds.apiBaseUrl;
+    return {
+        paths,
+        creds,
+        hqRoot: config.hqRoot,
+        getToken: () => ensureCognitoToken({ tokenSource: "machine", interactive: false }),
+        resolveCompanyUid: (token, slug) => getCompanyUid(token, slug),
+        runPull: defaultRunPull(process.execPath, process.argv[1], process.env),
+        vendRealtime: async (token) => {
+            const bundle = await createContract3Fetcher({ token, baseUrl: base })();
+            return { actorUid: bundle.actorUid };
+        },
+        listRoster: async (token, companyUid) => (await listAgents(token, companyUid)),
+        sendDm: (token, to, body) => sendAgentDm(token, to, body),
+        readThread: async (token, withUid) => readAgentThread(token, withUid, 20),
+        listSecrets: async (token, companyUid) => {
+            const res = await vaultApiFetch({
+                token,
+                baseUrl: base,
+                path: `/secrets/${encodeURIComponent(companyUid)}`,
+            });
+            return res.status;
+        },
+        postResult: async (token, result) => {
+            const res = await vaultApiFetch({
+                token,
+                baseUrl: base,
+                path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/probe-result`,
+                method: "POST",
+                body: { passed: result.passed, checks: result.checks, at: result.at },
+            });
+            return res.status;
+        },
+    };
+}
+export function registerAgentProbeCommand(agent) {
+    agent
+        .command("probe")
+        .description("Verify identity, vault sync, work-mesh presence, DMs and secrets; report to the console")
+        .option("--json", "Print machine-readable JSON")
+        .action(async (opts) => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            const creds = requireExternalCreds(paths);
+            const result = await runProbe(defaultProbeDeps(paths, creds));
+            if (opts.json)
+                console.log(JSON.stringify(result, null, 2));
+            else
+                for (const line of formatProbeReport(result))
+                    console.log(line);
+            if (!result.passed)
+                process.exit(1);
+        }
+        catch (err) {
+            console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=agent-probe.js.map

package/dist/commands/agent.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `hq agent …` — commands a host runs to BE an external HQ agent (as opposed
+ * to `hq agents …`, which an admin runs to manage a company's agents):
+ *
+ *   hq agent enroll <code>        redeem a one-time enrollment code
+ *   hq agent kit install|status|uninstall|run <service>
+ *   hq agent probe                end-to-end membership check
+ *   hq agent mcp                  stdio MCP server for the bot framework
+ */
+import { Command } from "commander";
+export declare function registerAgentCommand(program: Command): void;
+//# sourceMappingURL=agent.d.ts.map

package/dist/commands/agent.js

@@ -0,0 +1,23 @@
+/**
+ * `hq agent …` — commands a host runs to BE an external HQ agent (as opposed
+ * to `hq agents …`, which an admin runs to manage a company's agents):
+ *
+ *   hq agent enroll <code>        redeem a one-time enrollment code
+ *   hq agent kit install|status|uninstall|run <service>
+ *   hq agent probe                end-to-end membership check
+ *   hq agent mcp                  stdio MCP server for the bot framework
+ */
+import { registerAgentEnrollCommand } from "./agent-enroll.js";
+import { registerAgentKitCommand } from "./agent-kit.js";
+import { registerAgentMcpCommand } from "./agent-mcp.js";
+import { registerAgentProbeCommand } from "./agent-probe.js";
+export function registerAgentCommand(program) {
+    const agent = program
+        .command("agent")
+        .description("Enroll and run this host as an external HQ agent");
+    registerAgentEnrollCommand(agent);
+    registerAgentKitCommand(agent);
+    registerAgentProbeCommand(agent);
+    registerAgentMcpCommand(agent);
+}
+//# sourceMappingURL=agent.js.map

package/dist/commands/agents.d.ts

@@ -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
@@ -350,5 +352,30 @@ export declare function sendAgentDm(token: string, agentUid: string, message: st
 export declare function readAgentThread(token: string, agentUid: string, limit?: number): Promise<DmThreadMessage[]>;
 /** Render one thread message as a labeled line for the terminal. */
 export declare function formatThreadMessage(m: DmThreadMessage, agentLabel: string): string;
+export interface EnrollmentIssue {
+    code: string;
+    expiresAt: string;
+    enrollmentId: string;
+}
+export interface RotateAgentResult {
+    agentUid: string;
+    enrollment: EnrollmentIssue;
+}
+/**
+ * POST /v1/agents/{uid}/rotate — invalidate the current secret and host key
+ * and issue a fresh one-time enrollment code (returned exactly once).
+ */
+export declare function rotateAgent(token: string, agentUid: string): Promise<RotateAgentResult>;
+/** Display form of a 24-char code: six groups of four. */
+export declare function groupEnrollmentCode(code: string): string;
+/**
+ * POST /v1/agents/{uid}/revoke — disable the Cognito user, drop membership,
+ * mark the enrollment revoked; `remove` also deletes the entity.
+ */
+export declare function revokeAgent(token: string, agentUid: string, remove: boolean): Promise<{
+    removed: boolean;
+}>;
+/** Lines printed after a rotate: the code is shown once and never stored. */
+export declare function formatRotateOutput(result: RotateAgentResult): string[];
 export declare function registerAgentsCommand(program: Command): void;
 //# sourceMappingURL=agents.d.ts.map