@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -0,0 +1,85 @@
+/**
+ * `hq agent kit run all` — supervise the four kit services in ONE process.
+ *
+ * The fallback for hosts with no usable service manager (a Linux box with no
+ * systemd user session bus, a container, launchd unavailable): each service
+ * runs as a child `node hq agent kit run <service>` whose output is appended
+ * to its own ~/.hq-agent/logs/<service>.log, and a child that exits is
+ * restarted with per-service exponential backoff (1 s doubling to 60 s,
+ * reset once a child has stayed up for a minute).
+ */
+export const SUPERVISOR_BACKOFF_BASE_MS = 1_000;
+export const SUPERVISOR_BACKOFF_MAX_MS = 60_000;
+/** A child that ran at least this long resets its backoff. */
+export const SUPERVISOR_HEALTHY_RUN_MS = 60_000;
+export function supervisorBackoffMs(attempt) {
+    return Math.min(SUPERVISOR_BACKOFF_MAX_MS, SUPERVISOR_BACKOFF_BASE_MS * 2 ** Math.max(0, attempt));
+}
+export function superviseKitServices(deps) {
+    const now = deps.now ?? Date.now;
+    const setT = deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearT = deps.clearTimeout ?? ((h) => clearTimeout(h));
+    const children = new Map();
+    const attempts = new Map();
+    const restarts = {};
+    const timers = new Map();
+    let stopped = false;
+    const start = (service) => {
+        if (stopped)
+            return;
+        timers.delete(service);
+        let child;
+        const startedAt = now();
+        try {
+            child = deps.spawnService(service);
+        }
+        catch (err) {
+            deps.log("error", `${service} failed to start: ${err instanceof Error ? err.message : String(err)}`);
+            scheduleRestart(service);
+            return;
+        }
+        children.set(service, child);
+        child.on("exit", (code, signal) => {
+            if (children.get(service) === child)
+                children.delete(service);
+            if (stopped)
+                return;
+            if (now() - startedAt >= SUPERVISOR_HEALTHY_RUN_MS)
+                attempts.set(service, 0);
+            deps.log("warn", `${service} exited (code=${code ?? "null"} signal=${signal ?? "none"})`);
+            scheduleRestart(service);
+        });
+    };
+    const scheduleRestart = (service) => {
+        if (stopped)
+            return;
+        const attempt = attempts.get(service) ?? 0;
+        attempts.set(service, attempt + 1);
+        const delay = supervisorBackoffMs(attempt);
+        restarts[service] = (restarts[service] ?? 0) + 1;
+        deps.log("info", `restarting ${service} in ${delay}ms (restart ${restarts[service]})`);
+        timers.set(service, setT(() => start(service), delay));
+    };
+    for (const s of deps.services)
+        start(s);
+    return {
+        stop: (signal = "SIGTERM") => {
+            stopped = true;
+            for (const h of timers.values())
+                clearT(h);
+            timers.clear();
+            for (const child of children.values()) {
+                try {
+                    child.kill(signal);
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            children.clear();
+        },
+        restarts: () => ({ ...restarts }),
+        running: () => [...children.keys()],
+    };
+}
+//# sourceMappingURL=supervisor.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * Kit service: company vault sync loop.
+ *
+ * Mirrors the hosted box's hq-agent-sync.service, which runs hq-cloud's
+ * `hq-sync-runner --companies --direction both --on-conflict keep` on a
+ * loop and writes `component-sync`. Here the equivalent is the CLI's own
+ * `hq sync pull --all --on-conflict keep --hq-root <kit hqRoot>`, run as a
+ * child of the same node + hq binary this service was launched with, so the
+ * machine identity, creds path and version are exactly the service's own.
+ *
+ * Honest health: exit 0 = ok, anything else = error (the heartbeat turns a
+ * stale stamp into error on its own).
+ */
+import type { KitLogger } from "../log.js";
+import type { AgentKitPaths } from "../paths.js";
+export interface SyncRunDeps {
+    paths: AgentKitPaths;
+    hqRoot: string;
+    intervalMs: number;
+    log: KitLogger;
+    nodeBinary?: string;
+    hqBinary?: string;
+    /** Injected child runner (tests). Resolves with the exit code. */
+    runPull?: (args: string[]) => Promise<number>;
+    sleep?: (ms: number) => Promise<void>;
+    /** Stop after this many passes (tests); default runs forever. */
+    maxPasses?: number;
+}
+export declare function syncPullArgs(hqRoot: string): string[];
+export declare function defaultRunPull(nodeBinary: string, hqBinary: string, env: NodeJS.ProcessEnv): (args: string[]) => Promise<number>;
+export declare function runSyncOnce(deps: SyncRunDeps): Promise<boolean>;
+export declare function runSyncLoop(deps: SyncRunDeps): Promise<void>;
+//# sourceMappingURL=sync.d.ts.map

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

@@ -0,0 +1,58 @@
+/**
+ * Kit service: company vault sync loop.
+ *
+ * Mirrors the hosted box's hq-agent-sync.service, which runs hq-cloud's
+ * `hq-sync-runner --companies --direction both --on-conflict keep` on a
+ * loop and writes `component-sync`. Here the equivalent is the CLI's own
+ * `hq sync pull --all --on-conflict keep --hq-root <kit hqRoot>`, run as a
+ * child of the same node + hq binary this service was launched with, so the
+ * machine identity, creds path and version are exactly the service's own.
+ *
+ * Honest health: exit 0 = ok, anything else = error (the heartbeat turns a
+ * stale stamp into error on its own).
+ */
+import { spawn } from "node:child_process";
+import { writeComponentStatus } from "../creds.js";
+export function syncPullArgs(hqRoot) {
+    return ["sync", "pull", "--all", "--on-conflict", "keep", "--hq-root", hqRoot];
+}
+export function defaultRunPull(nodeBinary, hqBinary, env) {
+    return (args) => new Promise((resolve) => {
+        const child = spawn(nodeBinary, [hqBinary, ...args], {
+            env,
+            stdio: ["ignore", "inherit", "inherit"],
+        });
+        child.on("error", () => resolve(127));
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+export async function runSyncOnce(deps) {
+    const runPull = deps.runPull ??
+        defaultRunPull(deps.nodeBinary ?? process.execPath, deps.hqBinary ?? process.argv[1], process.env);
+    const args = syncPullArgs(deps.hqRoot);
+    deps.log("info", `sync start hq-root=${deps.hqRoot}`);
+    let code;
+    try {
+        code = await runPull(args);
+    }
+    catch (err) {
+        deps.log("error", `sync spawn failed: ${err instanceof Error ? err.message : String(err)}`);
+        code = 1;
+    }
+    const ok = code === 0;
+    writeComponentStatus(deps.paths, "sync", ok ? "ok" : "error");
+    deps.log(ok ? "info" : "error", `sync ${ok ? "ok" : `failed exit=${code}`}`);
+    return ok;
+}
+export async function runSyncLoop(deps) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let passes = 0;
+    for (;;) {
+        await runSyncOnce(deps);
+        passes += 1;
+        if (deps.maxPasses !== undefined && passes >= deps.maxPasses)
+            return;
+        await sleep(deps.intervalMs);
+    }
+}
+//# sourceMappingURL=sync.js.map

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

@@ -0,0 +1,31 @@
+/**
+ * The kit services and how each is launched. Every unit runs
+ * `node hq agent kit run <service>`; the service reads kit.json and the
+ * machine-creds file itself, so the units carry paths and nothing else.
+ */
+import type { ServiceSpec } from "../service-manager/types.js";
+import type { AgentKitPaths } from "./paths.js";
+export type KitService = "sync" | "inbox" | "heartbeat";
+export declare const KIT_SERVICES: readonly KitService[];
+export declare function isKitService(value: string): value is KitService;
+/**
+ * Environment every service inherits. HQ_MACHINE_CREDS_FILE pins hq-cloud's
+ * mint to the kit's creds file; HQ_REQUIRE_MACHINE_IDENTITY makes a missing
+ * file a loud error instead of a browser-login hang; HQ_AGENT_DIR keeps a
+ * relocated kit consistent across restarts.
+ */
+export declare function kitServiceEnv(paths: AgentKitPaths): Record<string, string>;
+export declare function kitServiceSpec(service: KitService, paths: AgentKitPaths): ServiceSpec;
+/**
+ * Services to install. `sync` is included only when the kit is configured to
+ * mirror the vault to disk; by default a bot reads files on demand through the
+ * `hq` MCP server, so the loop (and its full-copy download) is not installed at
+ * all rather than installed and left failing.
+ */
+export declare function kitServiceSpecs(paths: AgentKitPaths, options?: {
+    syncFiles?: boolean;
+}): ServiceSpec[];
+export declare function enabledKitServices(options?: {
+    syncFiles?: boolean;
+}): readonly KitService[];
+//# sourceMappingURL=services.d.ts.map

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

@@ -0,0 +1,55 @@
+/**
+ * The kit services and how each is launched. Every unit runs
+ * `node hq agent kit run <service>`; the service reads kit.json and the
+ * machine-creds file itself, so the units carry paths and nothing else.
+ */
+import { serviceLogPath } from "./paths.js";
+export const KIT_SERVICES = ["sync", "inbox", "heartbeat"];
+const KIT_LABEL_PREFIX = "ai.getindigo.hq-agent";
+export function isKitService(value) {
+    return KIT_SERVICES.includes(value);
+}
+const DESCRIPTIONS = {
+    sync: "HQ agent kit: company vault sync loop",
+    inbox: "HQ agent kit: inbox poller",
+    heartbeat: "HQ agent kit: heartbeat reporter",
+};
+/**
+ * Environment every service inherits. HQ_MACHINE_CREDS_FILE pins hq-cloud's
+ * mint to the kit's creds file; HQ_REQUIRE_MACHINE_IDENTITY makes a missing
+ * file a loud error instead of a browser-login hang; HQ_AGENT_DIR keeps a
+ * relocated kit consistent across restarts.
+ */
+export function kitServiceEnv(paths) {
+    return {
+        HQ_AGENT_DIR: paths.agentDir,
+        HQ_MACHINE_CREDS_FILE: paths.machineCredsPath,
+        HQ_REQUIRE_MACHINE_IDENTITY: "1",
+    };
+}
+export function kitServiceSpec(service, paths) {
+    return {
+        name: service,
+        label: `${KIT_LABEL_PREFIX}.${service}`,
+        description: DESCRIPTIONS[service],
+        args: ["agent", "kit", "run", service],
+        logPath: serviceLogPath(paths, service),
+        workingDir: paths.agentDir,
+        env: kitServiceEnv(paths),
+        restartSec: 10,
+    };
+}
+/**
+ * Services to install. `sync` is included only when the kit is configured to
+ * mirror the vault to disk; by default a bot reads files on demand through the
+ * `hq` MCP server, so the loop (and its full-copy download) is not installed at
+ * all rather than installed and left failing.
+ */
+export function kitServiceSpecs(paths, options = {}) {
+    return enabledKitServices(options).map((s) => kitServiceSpec(s, paths));
+}
+export function enabledKitServices(options = {}) {
+    const syncFiles = options.syncFiles === true;
+    return KIT_SERVICES.filter((s) => s !== "sync" || syncFiles);
+}
+//# sourceMappingURL=services.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * The skills directory the kit ships to ~/.hq-agent/skills/<name>/SKILL.md.
+ *
+ * agentskills.io format: YAML frontmatter with `name` and `description`, then
+ * markdown the bot's framework loads as an instruction. Each skill drives
+ * the `hq` CLI, which authenticates as the machine identity on its own, so
+ * no skill ever embeds or asks for a token or secret value.
+ */
+import type { AgentKitPaths } from "./paths.js";
+export interface KitSkill {
+    name: string;
+    description: string;
+    body: string;
+}
+export declare const KIT_SKILLS: readonly KitSkill[];
+export declare function renderSkillMarkdown(skill: KitSkill): string;
+export declare function writeKitSkills(paths: Pick<AgentKitPaths, "skillsDir">): string[];
+//# sourceMappingURL=skills.d.ts.map

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

@@ -0,0 +1,151 @@
+/**
+ * The skills directory the kit ships to ~/.hq-agent/skills/<name>/SKILL.md.
+ *
+ * agentskills.io format: YAML frontmatter with `name` and `description`, then
+ * markdown the bot's framework loads as an instruction. Each skill drives
+ * the `hq` CLI, which authenticates as the machine identity on its own, so
+ * no skill ever embeds or asks for a token or secret value.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const KIT_SKILLS = [
+    {
+        name: "dm",
+        description: "Send and read HQ direct messages and channel messages as this agent using the hq CLI.",
+        body: `# HQ direct messages
+
+Use the \`hq dm\` command to talk to teammates (people and other agents) in HQ.
+The CLI authenticates as this agent automatically — never ask for a token.
+
+## Send
+
+\`\`\`bash
+hq dm <email-or-uid> "message text"        # 1:1 to a person (prs_…) or agent (agt_…)
+hq dm <uid1>,<uid2> "message text"         # group DM
+hq dm '#channel-name' "message text"       # channel
+\`\`\`
+
+## Read and handle incoming messages
+
+The kit's inbox poller mirrors every message addressed to you (DMs, channel
+mentions, jobs). Work through them like this:
+
+\`\`\`bash
+hq agent inbox                  # pending messages, oldest first (id, sender uid, channelId, text)
+hq dm <channelId> "reply"       # message came from a channel or group: answer in it
+hq dm <sender-uid> "reply"      # otherwise: answer the sender privately
+hq agent inbox done <id> [id…]  # mark handled so it is never answered twice
+\`\`\`
+
+Reply where the message arrived. A message with a \`channelId\` was posted in a
+channel or group DM, and the answer belongs there, not in a private DM to the
+sender. Do not reply to another bot's greeting, thanks or sign-off that asks
+for nothing: two bots acknowledging each other never stop.
+
+The MCP equivalents are \`hq_inbox_read\`, \`hq_dm_send\` and \`hq_inbox_done\`.
+If the kit has a wake configured (\`hq agent kit wake show\`), HQ pokes your
+framework whenever something is pending, so always drain the whole list and
+mark each item done.
+
+## Rules
+
+- Reply in the same thread you were messaged in.
+- Keep messages short; link to files in the vault instead of pasting them.
+- Never include secrets or credentials in a message.
+`,
+    },
+    {
+        name: "search",
+        description: "Find things in the company vault (documents, knowledge, meeting notes) with the hq CLI.",
+        body: `# HQ search
+
+By default this agent keeps no local copy of the vault, so search runs
+server-side and matches file NAMES and paths, not file contents:
+
+\`\`\`bash
+hq files search "<query>" --company <slug>   # find files by name/path
+hq files browse companies/<slug>/<folder>    # list a folder
+hq files cat companies/<slug>/<file>         # read one file
+\`\`\`
+
+A good pattern for a question you cannot answer from names alone: search or
+browse to narrow to a few likely files, then read them with \`hq files cat\`.
+
+Content and semantic search need a local copy and its index, which only exists
+if the kit was installed with \`--sync-files\`. In that case (check
+\`~/.hq-agent/kit.json\` → \`syncFiles\`) you also have:
+
+\`\`\`bash
+hq search "<query>"                 # ranked full-text over the local copy
+hq search "<query>" --mode hybrid   # keyword + semantic
+\`\`\`
+
+Cite the file path of anything you quote so a teammate can open it.
+`,
+    },
+    {
+        name: "files",
+        description: "Read, list and write files in the company vault through the hq CLI (hq files).",
+        body: `# HQ vault files
+
+\`\`\`bash
+hq files browse companies/<slug>/<folder>   # list a vault folder without syncing it
+hq files cat companies/<slug>/<file>        # print one file
+hq files get companies/<slug>/<file>        # fetch one file into the local HQ tree
+hq files share companies/<slug>/<path>      # share a path with a teammate
+hq files versions companies/<slug>/<file>   # version history
+\`\`\`
+
+Paths are vault-relative and start with \`companies/<slug>/\`. Read them on
+demand with the commands above — this agent keeps no local copy of the vault
+unless the kit was installed with \`--sync-files\` (check \`~/.hq-agent/kit.json\`
+→ \`syncFiles\`), so never assume a file is already on disk.
+
+To publish a change you need that local copy: with \`syncFiles\` on, edit under
+the kit's HQ root (\`kit.json\` → \`hqRoot\`) and run
+\`hq sync push --hq-root <hqRoot>\`. Without it, \`hq files get\` a file, and if
+you need to write one back, say so and ask — do not improvise an upload.
+
+Writes are audited under this agent's identity — only write where you were
+asked to, and prefer creating a new file over overwriting one you did not
+author.
+`,
+    },
+    {
+        name: "secrets-exec",
+        description: "Run a command with company secrets injected as environment variables, without ever printing them.",
+        body: `# Run with HQ secrets
+
+Secrets never appear in chat, logs or files. Inject them into a child
+process instead:
+
+\`\`\`bash
+hq secrets list                                   # names only, never values
+hq secrets exec --only <NAME>[,<NAME>] -- <cmd>   # run <cmd> with those vars set
+hq run <script>                                   # run a vault script with its declared secrets
+\`\`\`
+
+Rules:
+
+- Never \`echo\`, \`printenv\` or otherwise print a secret, even to "check" it.
+- Request the narrowest \`--only\` set the command needs.
+- If a secret is missing, say which NAME is missing and ask a human admin to
+  add it with \`hq secrets set\` — do not ask for the value in chat.
+`,
+    },
+];
+export function renderSkillMarkdown(skill) {
+    return `---\nname: ${skill.name}\ndescription: ${JSON.stringify(skill.description)}\n---\n\n${skill.body}`;
+}
+export function writeKitSkills(paths) {
+    const written = [];
+    for (const skill of KIT_SKILLS) {
+        const dir = path.join(paths.skillsDir, skill.name);
+        fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
+        const dest = path.join(dir, "SKILL.md");
+        fs.writeFileSync(dest, renderSkillMarkdown(skill), { mode: 0o644 });
+        written.push(dest);
+    }
+    return written;
+}
+//# sourceMappingURL=skills.js.map

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

@@ -0,0 +1,83 @@
+/**
+ * Wake hook: tell the bot's own framework that HQ mail is waiting.
+ *
+ * Hosted agents are woken by the box watcher, which runs the model per inbox
+ * item. An external bot brings its own brain, so the kit cannot run it, but
+ * it can poke it. Two kinds, stored in ~/.hq-agent/wake.json (0600):
+ *
+ *   url      POST a small JSON notice to a URL the framework gives you, such
+ *            as a Grok Bot routine webhook. The URL is treated as a secret:
+ *            it is never logged or printed in full.
+ *   command  Run a local command (argv, no shell) for frameworks with a CLI
+ *            (such as OpenClaw). The notice is written to its stdin. One run
+ *            at a time; mail that arrives mid-run triggers one more run after.
+ *
+ * The notice never carries message text. It only says how many items are
+ * pending and their ids; the bot reads them through HQ (`hq agent inbox`).
+ *
+ * The inbox poller fires the wake when new items are mirrored, and re-fires
+ * every `retryMs` while items stay pending, so a missed webhook heals.
+ */
+import { spawn } from "node:child_process";
+import type { KitLogger } from "./log.js";
+import type { AgentKitPaths } from "./paths.js";
+export declare const WAKE_FILE_NAME = "wake.json";
+export declare const WAKE_STATE_NAME = "wake-state.json";
+export declare const DEFAULT_WAKE_RETRY_MS: number;
+export declare const WAKE_URL_TIMEOUT_MS = 15000;
+export declare const DEFAULT_WAKE_COMMAND_TIMEOUT_MS: number;
+export type WakeConfig = {
+    kind: "url";
+    url: string;
+    retryMs: number;
+} | {
+    kind: "command";
+    command: string[];
+    timeoutMs: number;
+    retryMs: number;
+};
+export interface WakeNotice {
+    event: "hq.inbox.pending";
+    agentUid: string;
+    reason: "new" | "retry" | "test";
+    pending: number;
+    messageIds: string[];
+    at: string;
+    instructions: string;
+}
+export declare const WAKE_INSTRUCTIONS: string;
+export declare function wakePath(paths: Pick<AgentKitPaths, "agentDir">): string;
+export declare function validateWakeUrl(raw: string): string;
+/** Origin plus a masked path: enough to recognise, not enough to call. */
+export declare function redactWakeUrl(url: string): string;
+export declare function describeWake(config: WakeConfig | null): string;
+export declare function readWakeConfig(paths: Pick<AgentKitPaths, "agentDir">): WakeConfig | null;
+export declare function writeWakeConfig(paths: Pick<AgentKitPaths, "agentDir">, config: WakeConfig): void;
+export declare function clearWakeConfig(paths: Pick<AgentKitPaths, "agentDir">): boolean;
+export interface WakeDeps {
+    paths: Pick<AgentKitPaths, "agentDir" | "stateDir" | "logsDir">;
+    agentUid: string;
+    log: KitLogger;
+    now?: () => Date;
+    fetchImpl?: typeof fetch;
+    spawnImpl?: typeof spawn;
+    pidAlive?: (pid: number | undefined) => boolean;
+}
+export declare function buildWakeNotice(agentUid: string, reason: WakeNotice["reason"], ids: string[], now: Date): WakeNotice;
+/**
+ * Decide whether to wake now: always on new mail, otherwise only when items
+ * are still pending and the last wake is older than retryMs.
+ */
+export declare function shouldWake(config: WakeConfig, state: {
+    lastWakeAt?: string;
+}, freshCount: number, pendingCount: number, now: Date): WakeNotice["reason"] | null;
+export interface WakeResult {
+    fired: boolean;
+    ok: boolean;
+    detail: string;
+}
+export declare function fireWake(config: WakeConfig, notice: WakeNotice, deps: WakeDeps): Promise<WakeResult>;
+export declare function currentWakeState(paths: Pick<AgentKitPaths, "stateDir">): {
+    lastWakeAt?: string;
+};
+//# sourceMappingURL=wake.d.ts.map