@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

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

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

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

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

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

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

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

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

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