@indigoai-us/hq-cli 5.115.6 → 5.117.0

package/dist/lib/agent-kit/mcp/tools.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The `hq agent mcp` tool surface. Each tool wraps an existing hq CLI
+ * capability so a bot framework (OpenClaw, grokbot, any MCP client)
+ * can act as the enrolled agent without a token ever crossing the MCP
+ * channel: the machine identity lives in machine-creds.json and every call
+ * mints through hq-cloud.
+ *
+ * Two seams keep this testable and honest:
+ *   - `runHq(args)` — spawn the SAME hq binary for capabilities that are
+ *     already complete CLI commands (search, files, secrets exec, work mesh).
+ *   - `api` — token + vault-API fetch for the notify surface (DM, inbox).
+ *
+ * `hq_secrets_exec` runs a command with secrets injected and returns ONLY
+ * the command's exit code and (bounded) output — never an environment dump,
+ * never a secret value. `hq_secrets_list` names secrets; values are never a
+ * tool result.
+ */
+import type { ExternalMachineCreds } from "../creds.js";
+import { type McpTool } from "./jsonrpc.js";
+export interface HqRunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface McpToolClients {
+    creds: ExternalMachineCreds;
+    /** Run `hq <args…>` as the machine identity; never throws. */
+    runHq: (args: string[]) => Promise<HqRunResult>;
+    getToken: () => Promise<string>;
+    /** Authenticated JSON call against the control plane. */
+    apiJson: (token: string, path: string, init?: {
+        method?: string;
+        body?: Record<string, unknown>;
+        query?: Record<string, string>;
+    }) => Promise<{
+        status: number;
+        body: unknown;
+    }>;
+}
+export declare const MAX_TOOL_OUTPUT_CHARS = 40000;
+export declare function clampOutput(text: string, max?: number): string;
+/** Vault paths are company-anchored and must not escape. */
+export declare function assertVaultPath(p: string): string;
+export declare function buildAgentMcpTools(clients: McpToolClients): McpTool[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/lib/agent-kit/mcp/tools.js

@@ -0,0 +1,280 @@
+/**
+ * The `hq agent mcp` tool surface. Each tool wraps an existing hq CLI
+ * capability so a bot framework (OpenClaw, grokbot, any MCP client)
+ * can act as the enrolled agent without a token ever crossing the MCP
+ * channel: the machine identity lives in machine-creds.json and every call
+ * mints through hq-cloud.
+ *
+ * Two seams keep this testable and honest:
+ *   - `runHq(args)` — spawn the SAME hq binary for capabilities that are
+ *     already complete CLI commands (search, files, secrets exec, work mesh).
+ *   - `api` — token + vault-API fetch for the notify surface (DM, inbox).
+ *
+ * `hq_secrets_exec` runs a command with secrets injected and returns ONLY
+ * the command's exit code and (bounded) output — never an environment dump,
+ * never a secret value. `hq_secrets_list` names secrets; values are never a
+ * tool result.
+ */
+import { CLI_VERSION } from "../../../cli-version.js";
+import { peekIdToken } from "../../../utils/id-token.js";
+import { errorResult, McpToolInputError, textResult } from "./jsonrpc.js";
+export const MAX_TOOL_OUTPUT_CHARS = 40_000;
+function str(args, key, opts = {}) {
+    const v = args[key];
+    if (v === undefined || v === null) {
+        if (opts.required)
+            throw new McpToolInputError(`"${key}" is required`);
+        return undefined;
+    }
+    if (typeof v !== "string")
+        throw new McpToolInputError(`"${key}" must be a string`);
+    if (opts.required && v.trim().length === 0)
+        throw new McpToolInputError(`"${key}" must not be empty`);
+    if (opts.max !== undefined && v.length > opts.max)
+        throw new McpToolInputError(`"${key}" exceeds ${opts.max} characters`);
+    return v;
+}
+function int(args, key, opts) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return opts.fallback;
+    if (typeof v !== "number" || !Number.isInteger(v))
+        throw new McpToolInputError(`"${key}" must be an integer`);
+    return Math.min(opts.max, Math.max(opts.min, v));
+}
+function strList(args, key) {
+    const v = args[key];
+    if (!Array.isArray(v) || v.length === 0 || !v.every((x) => typeof x === "string" && x.length > 0)) {
+        throw new McpToolInputError(`"${key}" must be a non-empty array of strings`);
+    }
+    return v;
+}
+export function clampOutput(text, max = MAX_TOOL_OUTPUT_CHARS) {
+    return text.length > max ? `${text.slice(0, max)}\n… [truncated ${text.length - max} chars]` : text;
+}
+/** Vault paths are company-anchored and must not escape. */
+export function assertVaultPath(p) {
+    const clean = p.trim().replace(/^\/+/, "");
+    if (!/^companies\/[a-z0-9][a-z0-9-]*(\/[^\0]*)?$/i.test(clean) || clean.split("/").includes("..")) {
+        throw new McpToolInputError(`"path" must be vault-relative and start with companies/<slug>/ (got ${JSON.stringify(p)})`);
+    }
+    return clean;
+}
+const SECRET_NAME = /^[A-Z][A-Z0-9_]*(\/[A-Z][A-Z0-9_]+)*$/;
+function fromRun(r, label) {
+    const out = [r.stdout.trim(), r.stderr.trim()].filter(Boolean).join("\n");
+    if (r.code !== 0)
+        return errorResult(clampOutput(`${label} failed (exit ${r.code})\n${out}`));
+    return textResult(clampOutput(out || `${label}: (no output)`));
+}
+export function buildAgentMcpTools(clients) {
+    const { creds } = clients;
+    const company = creds.companySlug;
+    return [
+        {
+            name: "hq_whoami",
+            description: "Identity this MCP server acts as: the enrolled external agent, its company, and the control plane.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            handler: async () => {
+                let tokenOk;
+                let claimUid;
+                try {
+                    const claims = peekIdToken(await clients.getToken());
+                    claimUid = typeof claims["custom:entityUid"] === "string" ? claims["custom:entityUid"] : undefined;
+                    tokenOk = claimUid === creds.entityUid;
+                }
+                catch {
+                    tokenOk = false;
+                }
+                return textResult(JSON.stringify({
+                    agentUid: creds.entityUid,
+                    runtime: "external",
+                    companySlug: company,
+                    apiBaseUrl: creds.apiBaseUrl,
+                    cliVersion: CLI_VERSION,
+                    session: tokenOk ? "ok" : `unavailable${claimUid ? ` (token names ${claimUid})` : ""}`,
+                }, null, 2));
+            },
+        },
+        {
+            name: "hq_search",
+            description: "Search the synced company vault (local qmd index). Modes: keyword (default), semantic, hybrid.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search text" },
+                    mode: { type: "string", enum: ["keyword", "semantic", "hybrid"] },
+                    count: { type: "integer", minimum: 1, maximum: 50 },
+                },
+                required: ["query"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const query = str(args, "query", { required: true, max: 2000 });
+                const mode = str(args, "mode");
+                if (mode !== undefined && !["keyword", "semantic", "hybrid"].includes(mode)) {
+                    throw new McpToolInputError('"mode" must be keyword, semantic or hybrid');
+                }
+                const count = int(args, "count", { min: 1, max: 50, fallback: 10 });
+                const hqArgs = ["search", query, "--mode", mode ?? "keyword", "-n", String(count), "--json"];
+                return fromRun(await clients.runHq(hqArgs), "hq search");
+            },
+        },
+        {
+            name: "hq_files_list",
+            description: "List vault objects under a company path without syncing them (hq files browse).",
+            inputSchema: {
+                type: "object",
+                properties: { path: { type: "string", description: "companies/<slug>/<folder>" } },
+                required: ["path"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const p = assertVaultPath(str(args, "path", { required: true, max: 1000 }));
+                return fromRun(await clients.runHq(["files", "browse", p]), "hq files browse");
+            },
+        },
+        {
+            name: "hq_files_read",
+            description: "Read one vault file's contents (hq files cat). Text files only; output is truncated at 40k chars.",
+            inputSchema: {
+                type: "object",
+                properties: { path: { type: "string", description: "companies/<slug>/<file>" } },
+                required: ["path"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const p = assertVaultPath(str(args, "path", { required: true, max: 1000 }));
+                return fromRun(await clients.runHq(["files", "cat", p]), "hq files cat");
+            },
+        },
+        {
+            name: "hq_secrets_list",
+            description: "List the NAMES of company secrets this agent can use. Values are never returned.",
+            inputSchema: {
+                type: "object",
+                properties: { prefix: { type: "string", description: "Optional path prefix, e.g. DEV" } },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const prefix = str(args, "prefix", { max: 200 });
+                const hqArgs = ["secrets", "--company", company, "list"];
+                if (prefix)
+                    hqArgs.push("--prefix", prefix);
+                return fromRun(await clients.runHq(hqArgs), "hq secrets list");
+            },
+        },
+        {
+            name: "hq_secrets_exec",
+            description: "Run a command with the named company secrets injected as environment variables. " +
+                "Returns the command's exit code and output only — never the secret values. " +
+                "Do not run commands that print their environment.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    secrets: { type: "array", items: { type: "string" }, description: "Secret names to inject (UPPER_SNAKE, optional / path)" },
+                    command: { type: "array", items: { type: "string" }, description: "argv of the command to run" },
+                },
+                required: ["secrets", "command"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const secrets = strList(args, "secrets");
+                for (const s of secrets) {
+                    if (!SECRET_NAME.test(s))
+                        throw new McpToolInputError(`invalid secret name ${JSON.stringify(s)}`);
+                }
+                const command = strList(args, "command");
+                if (/^(env|printenv|export|set)$/.test(command[0])) {
+                    throw new McpToolInputError("refusing to run an environment-dumping command under hq_secrets_exec");
+                }
+                const r = await clients.runHq(["secrets", "--company", company, "exec", "--only", secrets.join(","), "--", ...command]);
+                const out = [r.stdout.trim(), r.stderr.trim()].filter(Boolean).join("\n");
+                const text = clampOutput(`exit ${r.code}\n${out}`);
+                return r.code === 0 ? textResult(text) : errorResult(text);
+            },
+        },
+        {
+            name: "hq_dm_send",
+            description: "Send an HQ direct message as this agent to a person (email or prs_…) or agent (agt_…).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    to: { type: "string", description: "Email, prs_… or agt_… uid" },
+                    message: { type: "string" },
+                },
+                required: ["to", "message"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const to = str(args, "to", { required: true, max: 320 }).trim();
+                const message = str(args, "message", { required: true, max: 20_000 }).trim();
+                const body = /^[^\s]+@[^\s]+$/.test(to)
+                    ? { toEmail: to.toLowerCase(), body: message }
+                    : /^(prs|agt)_[A-Za-z0-9_-]+$/.test(to)
+                        ? { toPersonUid: to, body: message }
+                        : (() => {
+                            throw new McpToolInputError('"to" must be an email, prs_… or agt_… uid');
+                        })();
+                const token = await clients.getToken();
+                const res = await clients.apiJson(token, "/v1/notify/dm", { method: "POST", body });
+                if (res.status < 200 || res.status >= 300) {
+                    return errorResult(`DM send failed (${res.status}): ${describeError(res.body)}`);
+                }
+                return textResult(`sent to ${to}`);
+            },
+        },
+        {
+            name: "hq_inbox_read",
+            description: "Read this agent's recent incoming direct messages (newest first). Optionally only unread.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    limit: { type: "integer", minimum: 1, maximum: 100 },
+                    unread_only: { type: "boolean" },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const limit = int(args, "limit", { min: 1, max: 100, fallback: 20 });
+                const unreadOnly = args.unread_only === true;
+                const token = await clients.getToken();
+                const res = await clients.apiJson(token, "/v1/notify/inbox", { query: { limit: String(limit) } });
+                if (res.status !== 200)
+                    return errorResult(`inbox read failed (${res.status}): ${describeError(res.body)}`);
+                const events = Array.isArray(res.body?.events)
+                    ? (res.body.events)
+                    : [];
+                const rows = events
+                    .filter((e) => !unreadOnly || !e.acknowledgedAt)
+                    .map((e) => ({
+                    eventId: e.eventId,
+                    from: e.fromDisplayName ?? e.fromEmail ?? e.fromPersonUid ?? "unknown",
+                    fromUid: e.fromPersonUid,
+                    at: e.createdAt,
+                    unread: !e.acknowledgedAt,
+                    body: e.body,
+                    ...(e.prompt ? { prompt: e.prompt } : {}),
+                }));
+                return textResult(clampOutput(JSON.stringify({ count: rows.length, messages: rows }, null, 2)));
+            },
+        },
+        {
+            name: "hq_work_mesh_status",
+            description: "Live read of what the team is working on right now (work-mesh session status for this agent's company).",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            handler: async () => fromRun(await clients.runHq(["mesh", "session", "status", "--company", company, "--json"]), "hq mesh session status"),
+        },
+    ];
+}
+function describeError(body) {
+    if (body && typeof body === "object") {
+        const b = body;
+        const code = typeof b.code === "string" ? `${b.code}: ` : "";
+        const msg = typeof b.message === "string" ? b.message : typeof b.error === "string" ? b.error : "";
+        if (code || msg)
+            return `${code}${msg}`;
+    }
+    return "request failed";
+}
+//# sourceMappingURL=tools.js.map

package/dist/lib/agent-kit/paths.d.ts

@@ -0,0 +1,42 @@
+/**
+ * On-host layout for an external agent (api-contract v1, "Host files"):
+ *
+ *   ~/.hq-agent/host-key             Ed25519 private key, PKCS8 PEM, 0600
+ *   ~/.hq-agent/host-key.pub         Ed25519 public key, SPKI PEM
+ *   ~/.hq-agent/machine-creds.json   credentials + hostKeyPath/companySlug/apiBaseUrl, 0600
+ *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
+ *   ~/.hq-agent/state/               component-{sync,mesh,inbox}, last-heartbeat.json
+ *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
+ *   ~/.hq-agent/logs/*.log           one log per kit service
+ *   ~/.hq-agent/skills/<name>/SKILL.md
+ *
+ * `HQ_AGENT_DIR` relocates the whole tree (tests, containers). The creds file
+ * additionally honours `HQ_MACHINE_CREDS_FILE`, the override hq-cloud reads,
+ * so a kit pointed at a custom creds path and hq-cloud's mint agree.
+ */
+export declare const AGENT_DIR_ENV = "HQ_AGENT_DIR";
+export declare const HOST_KEY_NAME = "host-key";
+export declare const HOST_KEY_PUB_NAME = "host-key.pub";
+export declare const MACHINE_CREDS_NAME = "machine-creds.json";
+export declare const KIT_CONFIG_NAME = "kit.json";
+export declare const LAST_HEARTBEAT_NAME = "last-heartbeat.json";
+export type KitComponent = "sync" | "mesh" | "inbox";
+export declare const KIT_COMPONENTS: readonly KitComponent[];
+export interface AgentKitPaths {
+    home: string;
+    agentDir: string;
+    hostKeyPath: string;
+    hostKeyPubPath: string;
+    machineCredsPath: string;
+    kitConfigPath: string;
+    stateDir: string;
+    inboxDir: string;
+    logsDir: string;
+    skillsDir: string;
+    lastHeartbeatPath: string;
+}
+export declare function agentDir(home?: string, env?: NodeJS.ProcessEnv): string;
+export declare function agentKitPaths(home?: string, env?: NodeJS.ProcessEnv): AgentKitPaths;
+export declare function componentStatePath(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent): string;
+export declare function serviceLogPath(paths: Pick<AgentKitPaths, "logsDir">, service: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/lib/agent-kit/paths.js

@@ -0,0 +1,56 @@
+/**
+ * On-host layout for an external agent (api-contract v1, "Host files"):
+ *
+ *   ~/.hq-agent/host-key             Ed25519 private key, PKCS8 PEM, 0600
+ *   ~/.hq-agent/host-key.pub         Ed25519 public key, SPKI PEM
+ *   ~/.hq-agent/machine-creds.json   credentials + hostKeyPath/companySlug/apiBaseUrl, 0600
+ *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
+ *   ~/.hq-agent/state/               component-{sync,mesh,inbox}, last-heartbeat.json
+ *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
+ *   ~/.hq-agent/logs/*.log           one log per kit service
+ *   ~/.hq-agent/skills/<name>/SKILL.md
+ *
+ * `HQ_AGENT_DIR` relocates the whole tree (tests, containers). The creds file
+ * additionally honours `HQ_MACHINE_CREDS_FILE`, the override hq-cloud reads,
+ * so a kit pointed at a custom creds path and hq-cloud's mint agree.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+export const AGENT_DIR_ENV = "HQ_AGENT_DIR";
+export const HOST_KEY_NAME = "host-key";
+export const HOST_KEY_PUB_NAME = "host-key.pub";
+export const MACHINE_CREDS_NAME = "machine-creds.json";
+export const KIT_CONFIG_NAME = "kit.json";
+export const LAST_HEARTBEAT_NAME = "last-heartbeat.json";
+export const KIT_COMPONENTS = ["sync", "mesh", "inbox"];
+export function agentDir(home = os.homedir(), env = process.env) {
+    const override = env[AGENT_DIR_ENV]?.trim();
+    if (override)
+        return override;
+    return path.join(home, ".hq-agent");
+}
+export function agentKitPaths(home = os.homedir(), env = process.env) {
+    const dir = agentDir(home, env);
+    const credsOverride = env.HQ_MACHINE_CREDS_FILE?.trim();
+    const stateDir = path.join(dir, "state");
+    return {
+        home,
+        agentDir: dir,
+        hostKeyPath: path.join(dir, HOST_KEY_NAME),
+        hostKeyPubPath: path.join(dir, HOST_KEY_PUB_NAME),
+        machineCredsPath: credsOverride || path.join(dir, MACHINE_CREDS_NAME),
+        kitConfigPath: path.join(dir, KIT_CONFIG_NAME),
+        stateDir,
+        inboxDir: path.join(dir, "inbox"),
+        logsDir: path.join(dir, "logs"),
+        skillsDir: path.join(dir, "skills"),
+        lastHeartbeatPath: path.join(stateDir, LAST_HEARTBEAT_NAME),
+    };
+}
+export function componentStatePath(paths, component) {
+    return path.join(paths.stateDir, `component-${component}`);
+}
+export function serviceLogPath(paths, service) {
+    return path.join(paths.logsDir, `${service}.log`);
+}
+//# sourceMappingURL=paths.js.map

package/dist/lib/agent-kit/run/heartbeat.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Kit service: heartbeat reporter.
+ *
+ * Every 60 s POST /v1/agents/{uid}/heartbeat with
+ * `{ components: { sync, mesh, inbox }, cliVersion, hostInfo }` — the
+ * external-agent body from api-contract v1, mirroring the hosted box's
+ * hq-agent-heartbeat.sh (which folds per-component stamp files into one
+ * beat). Component values are read from the stamps the other three services
+ * write; a missing or stale stamp reports `error`, never silence.
+ *
+ * The last successful beat is recorded at state/last-heartbeat.json so
+ * `hq agent probe` can report its age.
+ */
+import { type ComponentStatus } from "../creds.js";
+import type { KitLogger } from "../log.js";
+import { type AgentKitPaths, type KitComponent } from "../paths.js";
+/** A component stamp older than this reads as error. */
+export declare const COMPONENT_STALE_AFTER_MS: Record<KitComponent, number>;
+export interface HeartbeatBody {
+    components: Record<KitComponent, ComponentStatus>;
+    cliVersion: string;
+    hostInfo: {
+        os: string;
+        arch: string;
+        hostname: string;
+        cliVersion: string;
+    };
+}
+export declare function buildHeartbeatBody(paths: Pick<AgentKitPaths, "stateDir">, now?: () => Date, hostInfo?: HeartbeatBody["hostInfo"]): HeartbeatBody;
+export interface LastHeartbeat {
+    at: string;
+    components: Record<KitComponent, ComponentStatus>;
+    status: number;
+}
+export declare function writeLastHeartbeat(paths: Pick<AgentKitPaths, "stateDir" | "lastHeartbeatPath">, record: LastHeartbeat): void;
+export declare function readLastHeartbeat(paths: Pick<AgentKitPaths, "lastHeartbeatPath">): LastHeartbeat | null;
+export interface HeartbeatDeps {
+    paths: AgentKitPaths;
+    agentUid: string;
+    apiBaseUrl: string;
+    intervalMs: number;
+    getToken: () => Promise<string>;
+    log: KitLogger;
+    post?: (token: string, body: HeartbeatBody) => Promise<number>;
+    now?: () => Date;
+    sleep?: (ms: number) => Promise<void>;
+    maxBeats?: number;
+}
+export declare function defaultHeartbeatPost(agentUid: string, apiBaseUrl: string): (token: string, body: HeartbeatBody) => Promise<number>;
+export declare function beatOnce(deps: HeartbeatDeps): Promise<boolean>;
+export declare function runHeartbeatLoop(deps: HeartbeatDeps): Promise<void>;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/lib/agent-kit/run/heartbeat.js

@@ -0,0 +1,97 @@
+/**
+ * Kit service: heartbeat reporter.
+ *
+ * Every 60 s POST /v1/agents/{uid}/heartbeat with
+ * `{ components: { sync, mesh, inbox }, cliVersion, hostInfo }` — the
+ * external-agent body from api-contract v1, mirroring the hosted box's
+ * hq-agent-heartbeat.sh (which folds per-component stamp files into one
+ * beat). Component values are read from the stamps the other three services
+ * write; a missing or stale stamp reports `error`, never silence.
+ *
+ * The last successful beat is recorded at state/last-heartbeat.json so
+ * `hq agent probe` can report its age.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { CLI_VERSION } from "../../../cli-version.js";
+import { vaultApiFetch } from "../../../utils/vault-api.js";
+import { readComponentStatus } from "../creds.js";
+import { KIT_COMPONENTS } from "../paths.js";
+/** A component stamp older than this reads as error. */
+export const COMPONENT_STALE_AFTER_MS = {
+    sync: 3 * 60 * 60_000, // sync passes every 5 min; three hours of silence is real trouble
+    mesh: 3 * 60_000,
+    inbox: 3 * 60_000,
+};
+export function buildHeartbeatBody(paths, now = () => new Date(), hostInfo) {
+    const components = {};
+    for (const c of KIT_COMPONENTS) {
+        components[c] = readComponentStatus(paths, c, COMPONENT_STALE_AFTER_MS[c], now).status;
+    }
+    return {
+        components,
+        cliVersion: CLI_VERSION,
+        hostInfo: hostInfo ?? {
+            os: `${os.platform()} ${os.release()}`,
+            arch: os.arch(),
+            hostname: os.hostname(),
+            cliVersion: CLI_VERSION,
+        },
+    };
+}
+export function writeLastHeartbeat(paths, record) {
+    fs.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(paths.lastHeartbeatPath, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+}
+export function readLastHeartbeat(paths) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(paths.lastHeartbeatPath, "utf8"));
+        return typeof raw.at === "string" ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function defaultHeartbeatPost(agentUid, apiBaseUrl) {
+    return async (token, body) => {
+        const res = await vaultApiFetch({
+            token,
+            baseUrl: apiBaseUrl,
+            path: `/v1/agents/${encodeURIComponent(agentUid)}/heartbeat`,
+            method: "POST",
+            body: body,
+        });
+        return res.status;
+    };
+}
+export async function beatOnce(deps) {
+    const now = deps.now ?? (() => new Date());
+    const post = deps.post ?? defaultHeartbeatPost(deps.agentUid, deps.apiBaseUrl);
+    const body = buildHeartbeatBody(deps.paths, now);
+    try {
+        const token = await deps.getToken();
+        const status = await post(token, body);
+        const ok = status >= 200 && status < 300;
+        if (ok) {
+            writeLastHeartbeat(deps.paths, { at: now().toISOString(), components: body.components, status });
+        }
+        deps.log(ok ? "info" : "warn", `heartbeat ${status} sync=${body.components.sync} mesh=${body.components.mesh} inbox=${body.components.inbox}`);
+        return ok;
+    }
+    catch (err) {
+        deps.log("error", `heartbeat failed: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+export async function runHeartbeatLoop(deps) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let beats = 0;
+    for (;;) {
+        await beatOnce(deps);
+        beats += 1;
+        if (deps.maxBeats !== undefined && beats >= deps.maxBeats)
+            return;
+        await sleep(deps.intervalMs);
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/lib/agent-kit/run/inbox.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Kit service: inbox poller.
+ *
+ * Mirrors the poll half of the hosted box's hq-agent-inbox.sh: every
+ * `inboxPollMs` GET /v1/agents/{uid}/inbox, take `.messages[]`, and stamp
+ * `component-inbox` ok on a 200 (any other status → error, token re-minted
+ * on the next pass). The hosted watcher then dispatches each item to a
+ * provider and acks it; an external bot brings its own brain, so this
+ * service only MIRRORS: each new item is written once to
+ * ~/.hq-agent/inbox/<id>.json and appended to inbox.jsonl for the bot to
+ * consume, and the work-mesh conversation cache is refreshed so `hq dm`
+ * and the skills see the same state.
+ *
+ * Acking is opt-in (kit.json `inboxAck`): with it off the server keeps the
+ * item until the bot acks (`POST /v1/agents/{uid}/inbox/{id}/ack`), and the
+ * poller dedupes by id so the same item is never mirrored twice.
+ */
+import type { KitLogger } from "../log.js";
+import type { AgentKitPaths } from "../paths.js";
+export declare const SEEN_IDS_NAME = "seen-ids.json";
+export declare const INBOX_JSONL_NAME = "inbox.jsonl";
+export declare const MAX_SEEN_IDS = 5000;
+export interface InboxItem {
+    id: string;
+    raw: Record<string, unknown>;
+}
+/** Pull `{id}` out of each server item; items without a string id are dropped. */
+export declare function extractInboxItems(body: unknown): InboxItem[];
+export declare function readSeenIds(paths: Pick<AgentKitPaths, "inboxDir">): Set<string>;
+export declare function writeSeenIds(paths: Pick<AgentKitPaths, "inboxDir">, seen: Set<string>): void;
+export declare function mirrorInboxItem(paths: Pick<AgentKitPaths, "inboxDir">, item: InboxItem): string;
+export interface InboxDeps {
+    paths: AgentKitPaths;
+    agentUid: string;
+    apiBaseUrl: string;
+    pollMs: number;
+    ack: boolean;
+    getToken: () => Promise<string>;
+    log: KitLogger;
+    fetchInbox?: (token: string) => Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    ackItem?: (token: string, id: string) => Promise<number>;
+    warmCache?: (token: string, agentUid: string) => Promise<unknown>;
+    sleep?: (ms: number) => Promise<void>;
+    maxPolls?: number;
+}
+export declare function defaultFetchInbox(agentUid: string, apiBaseUrl: string): (token: string) => Promise<{
+    status: number;
+    body: unknown;
+}>;
+export declare function defaultAckItem(agentUid: string, apiBaseUrl: string): (token: string, id: string) => Promise<number>;
+export declare function pollInboxOnce(deps: InboxDeps): Promise<{
+    ok: boolean;
+    mirrored: number;
+}>;
+export declare function runInboxLoop(deps: InboxDeps): Promise<void>;
+//# sourceMappingURL=inbox.d.ts.map