@indigoai-us/hq-cli 5.117.3 → 5.118.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [5.118.0] — 2026-09-16
+
+### Added
+
+- External agents can now be woken the moment an HQ message arrives. `hq agent kit wake set-url --stdin` points the kit at a webhook, such as a Grok Bot routine webhook trigger. `hq agent kit wake set-command -- <cmd>` runs a local command for frameworks with a CLI. The kit sends a short notice with no message text when mail is pending, and again every 10 minutes until it is handled. The webhook URL is stored privately and never logged.
+- `hq agent inbox` lists an external agent's pending HQ messages and `hq agent inbox done <id>` marks them handled, so a woken bot never answers the same message twice. The MCP server gains a matching `hq_inbox_done` tool.
+
+### Fixed
+
+- The `hq_inbox_read` MCP tool no longer fails with 403 AGENT_ROUTE_NOT_SUPPORTED. It reads the agent's own inbox instead of the person-only DM inbox, and by default returns only messages not yet handled.
+- The HQ direct-message skill shipped to external agents no longer tells them to use person-only read commands.
+
 ## [5.117.3] — 2026-09-16
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -4218,6 +4218,83 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "Print machine-readable JSON";
             }];
             readonly subcommands: readonly [];
+        }, {
+            readonly name: "wake";
+            readonly description: "Wake this bot's own framework when HQ messages arrive (webhook URL or local command)";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] [command]";
+            readonly arguments: readonly [];
+            readonly options: readonly [];
+            readonly subcommands: readonly [{
+                readonly name: "set-url";
+                readonly description: "POST a notice to a webhook URL (e.g. a Grok Bot routine webhook) when mail is pending. Prefer --stdin so the URL stays out of shell history";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] [url]";
+                readonly arguments: readonly [{
+                    readonly name: "url";
+                    readonly required: false;
+                    readonly variadic: false;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--stdin";
+                    readonly description: "Read the URL from stdin";
+                }, {
+                    readonly flags: "--retry-minutes <n>";
+                    readonly description: "Re-wake while items stay pending (default 10, minimum 1)";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "set-command";
+                readonly description: "Run a local command (no shell) when mail is pending; the notice JSON arrives on stdin. Use -- before the command";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options] <argv...>";
+                readonly arguments: readonly [{
+                    readonly name: "argv";
+                    readonly required: true;
+                    readonly variadic: true;
+                }];
+                readonly options: readonly [{
+                    readonly flags: "--timeout-minutes <n>";
+                    readonly description: "Kill a run after this long (default 10)";
+                }, {
+                    readonly flags: "--retry-minutes <n>";
+                    readonly description: "Re-wake while items stay pending (default 10, minimum 1)";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "show";
+                readonly description: "Show the configured wake (the URL is masked)";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options]";
+                readonly arguments: readonly [];
+                readonly options: readonly [{
+                    readonly flags: "--json";
+                    readonly description: "Print machine-readable JSON";
+                }];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "clear";
+                readonly description: "Remove the wake configuration";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options]";
+                readonly arguments: readonly [];
+                readonly options: readonly [];
+                readonly subcommands: readonly [];
+            }, {
+                readonly name: "test";
+                readonly description: "Fire the wake once now with the current pending count";
+                readonly aliases: readonly [];
+                readonly hidden: false;
+                readonly usage: "[options]";
+                readonly arguments: readonly [];
+                readonly options: readonly [];
+                readonly subcommands: readonly [];
+            }];
         }, {
             readonly name: "run";
             readonly description: "Run one kit service in the foreground (sync|mesh|inbox|heartbeat), or `all` to supervise every service in one process";
@@ -4253,6 +4330,34 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly arguments: readonly [];
         readonly options: readonly [];
         readonly subcommands: readonly [];
+    }, {
+        readonly name: "inbox";
+        readonly description: "List this agent's pending HQ messages (mirrored by the kit), or mark them handled";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--all";
+            readonly description: "Include items already marked handled";
+        }, {
+            readonly flags: "--json";
+            readonly description: "Print machine-readable JSON";
+        }];
+        readonly subcommands: readonly [{
+            readonly name: "done";
+            readonly description: "Mark inbox items handled and ack them on the server";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <ids...>";
+            readonly arguments: readonly [{
+                readonly name: "ids";
+                readonly required: true;
+                readonly variadic: true;
+            }];
+            readonly options: readonly [];
+            readonly subcommands: readonly [];
+        }];
     }];
 }, {
     readonly name: "outposts";

package/dist/command-catalog.generated.js

@@ -5457,6 +5457,102 @@ export const COMMAND_CATALOG = [
                         ],
                         "subcommands": []
                     },
+                    {
+                        "name": "wake",
+                        "description": "Wake this bot's own framework when HQ messages arrive (webhook URL or local command)",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] [command]",
+                        "arguments": [],
+                        "options": [],
+                        "subcommands": [
+                            {
+                                "name": "set-url",
+                                "description": "POST a notice to a webhook URL (e.g. a Grok Bot routine webhook) when mail is pending. Prefer --stdin so the URL stays out of shell history",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] [url]",
+                                "arguments": [
+                                    {
+                                        "name": "url",
+                                        "required": false,
+                                        "variadic": false
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--stdin",
+                                        "description": "Read the URL from stdin"
+                                    },
+                                    {
+                                        "flags": "--retry-minutes <n>",
+                                        "description": "Re-wake while items stay pending (default 10, minimum 1)"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "set-command",
+                                "description": "Run a local command (no shell) when mail is pending; the notice JSON arrives on stdin. Use -- before the command",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options] <argv...>",
+                                "arguments": [
+                                    {
+                                        "name": "argv",
+                                        "required": true,
+                                        "variadic": true
+                                    }
+                                ],
+                                "options": [
+                                    {
+                                        "flags": "--timeout-minutes <n>",
+                                        "description": "Kill a run after this long (default 10)"
+                                    },
+                                    {
+                                        "flags": "--retry-minutes <n>",
+                                        "description": "Re-wake while items stay pending (default 10, minimum 1)"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "show",
+                                "description": "Show the configured wake (the URL is masked)",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options]",
+                                "arguments": [],
+                                "options": [
+                                    {
+                                        "flags": "--json",
+                                        "description": "Print machine-readable JSON"
+                                    }
+                                ],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "clear",
+                                "description": "Remove the wake configuration",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options]",
+                                "arguments": [],
+                                "options": [],
+                                "subcommands": []
+                            },
+                            {
+                                "name": "test",
+                                "description": "Fire the wake once now with the current pending count",
+                                "aliases": [],
+                                "hidden": false,
+                                "usage": "[options]",
+                                "arguments": [],
+                                "options": [],
+                                "subcommands": []
+                            }
+                        ]
+                    },
                     {
                         "name": "run",
                         "description": "Run one kit service in the foreground (sync|mesh|inbox|heartbeat), or `all` to supervise every service in one process",
@@ -5499,6 +5595,42 @@ export const COMMAND_CATALOG = [
                 "arguments": [],
                 "options": [],
                 "subcommands": []
+            },
+            {
+                "name": "inbox",
+                "description": "List this agent's pending HQ messages (mirrored by the kit), or mark them handled",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--all",
+                        "description": "Include items already marked handled"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "Print machine-readable JSON"
+                    }
+                ],
+                "subcommands": [
+                    {
+                        "name": "done",
+                        "description": "Mark inbox items handled and ack them on the server",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <ids...>",
+                        "arguments": [
+                            {
+                                "name": "ids",
+                                "required": true,
+                                "variadic": true
+                            }
+                        ],
+                        "options": [],
+                        "subcommands": []
+                    }
+                ]
             }
         ]
     },

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

@@ -0,0 +1,9 @@
+/**
+ * `hq agent inbox` — what a woken bot runs to see and clear its HQ mail.
+ *
+ *   hq agent inbox [--all] [--json]   pending items (oldest first), or all
+ *   hq agent inbox done <id...>       mark handled locally and ack on the server
+ */
+import { Command } from "commander";
+export declare function registerAgentInboxCommand(agent: Command): void;
+//# sourceMappingURL=agent-inbox.d.ts.map

package/dist/commands/agent-inbox.js

@@ -0,0 +1,81 @@
+/**
+ * `hq agent inbox` — what a woken bot runs to see and clear its HQ mail.
+ *
+ *   hq agent inbox [--all] [--json]   pending items (oldest first), or all
+ *   hq agent inbox done <id...>       mark handled locally and ack on the server
+ */
+import chalk from "chalk";
+import * as os from "node:os";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { markInboxDone, readDoneIds, readMirroredInbox, summarizeInboxEntry } from "../lib/agent-kit/inbox-state.js";
+import { agentKitPaths } from "../lib/agent-kit/paths.js";
+import { requireExternalCreds } from "./agent-kit.js";
+const ID_RE = /^[A-Za-z0-9._:-]{1,200}$/;
+export function registerAgentInboxCommand(agent) {
+    const inbox = agent
+        .command("inbox")
+        .description("List this agent's pending HQ messages (mirrored by the kit), or mark them handled")
+        .option("--all", "Include items already marked handled")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => {
+        const paths = agentKitPaths(os.homedir(), process.env);
+        const done = readDoneIds(paths);
+        const rows = readMirroredInbox(paths)
+            .filter((e) => opts.all || !done.has(e.id))
+            .map((e) => summarizeInboxEntry(e, done.has(e.id)));
+        if (opts.json) {
+            console.log(JSON.stringify({ count: rows.length, messages: rows }, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log(opts.all ? "Inbox is empty." : "No pending messages.");
+            return;
+        }
+        for (const r of rows) {
+            const state = r.done ? chalk.dim(" (done)") : "";
+            console.log(`${chalk.bold(r.id)}${state}  ${r.channel ?? "?"}  from ${r.from}${r.fromUid ? ` <${r.fromUid}>` : ""}  ${r.at ?? ""}`);
+            if (r.text)
+                console.log(`  ${r.text.replace(/\n/g, "\n  ")}`);
+        }
+        if (!opts.all)
+            console.log(chalk.dim(`\nReply with hq dm <uid> "…", then: hq agent inbox done <id>`));
+    });
+    inbox
+        .command("done <ids...>")
+        .description("Mark inbox items handled and ack them on the server")
+        .action(async (ids) => {
+        const bad = ids.filter((id) => !ID_RE.test(id));
+        if (bad.length) {
+            console.error(chalk.red(`Invalid id(s): ${bad.join(", ")}`));
+            process.exit(1);
+        }
+        const paths = agentKitPaths(os.homedir(), process.env);
+        const creds = requireExternalCreds(paths);
+        const added = markInboxDone(paths, ids);
+        process.env.HQ_MACHINE_CREDS_FILE = paths.machineCredsPath;
+        process.env.HQ_REQUIRE_MACHINE_IDENTITY = "1";
+        process.env.HQ_VAULT_API_URL = creds.apiBaseUrl;
+        let acked = 0;
+        try {
+            const token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
+            for (const id of ids) {
+                const res = await vaultApiFetch({
+                    token,
+                    baseUrl: creds.apiBaseUrl,
+                    path: `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox/${encodeURIComponent(id)}/ack`,
+                    method: "POST",
+                });
+                if (res.ok)
+                    acked += 1;
+                else
+                    console.error(chalk.yellow(`server ack ${id} → ${res.status}`));
+            }
+        }
+        catch (err) {
+            console.error(chalk.yellow(`server ack skipped: ${err instanceof Error ? err.message : String(err)}`));
+        }
+        console.log(`Marked ${added.length} handled (${ids.length - added.length} already done); server acked ${acked}.`);
+    });
+}
+//# sourceMappingURL=agent-inbox.js.map

package/dist/commands/agent-kit.js

@@ -34,6 +34,8 @@ import { fallbackStatus, rebootCrontabLine, shouldUseFallback, startFallback, st
 import { serviceLogPath } from "../lib/agent-kit/paths.js";
 import { spawn } from "node:child_process";
 import { startMeshListener } from "../lib/agent-kit/run/mesh-listener.js";
+import { pendingInbox } from "../lib/agent-kit/inbox-state.js";
+import { buildWakeNotice, clearWakeConfig, currentWakeState, DEFAULT_WAKE_RETRY_MS, describeWake, fireWake, readWakeConfig, validateWakeUrl, writeWakeConfig, } from "../lib/agent-kit/wake.js";
 import { runSyncLoop } from "../lib/agent-kit/run/sync.js";
 import { resolveHqBinary, resolveNodeBinary, } from "../lib/mesh/live/daemon/install.js";
 import { installServices, servicesStatus, uninstallServices, } from "../lib/service-manager/index.js";
@@ -245,6 +247,14 @@ export function formatFallbackStatus(paths, kill) {
         : chalk.yellow(st.pid === null ? "pidfile unreadable" : `not running (stale pid ${st.pid})`);
     return [`  mode: fallback supervisor (hq agent kit run all) ${state}${chalk.dim(`  ${st.pidFile}`)}`];
 }
+function retryMsFrom(raw) {
+    if (raw === undefined)
+        return DEFAULT_WAKE_RETRY_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1)
+        throw new Error("--retry-minutes must be at least 1");
+    return n * 60_000;
+}
 function fail(err) {
     console.error(chalk.red(err instanceof Error ? err.message : String(err)));
     process.exit(1);
@@ -341,6 +351,101 @@ export function registerAgentKitCommand(agent) {
             fail(err);
         }
     });
+    const wake = kit
+        .command("wake")
+        .description("Wake this bot's own framework when HQ messages arrive (webhook URL or local command)");
+    wake
+        .command("set-url [url]")
+        .description("POST a notice to a webhook URL (e.g. a Grok Bot routine webhook) when mail is pending. Prefer --stdin so the URL stays out of shell history")
+        .option("--stdin", "Read the URL from stdin")
+        .option("--retry-minutes <n>", "Re-wake while items stay pending (default 10, minimum 1)")
+        .action(async (url, opts) => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            requireExternalCreds(paths);
+            let raw = url;
+            if (opts.stdin) {
+                const chunks = [];
+                for await (const c of process.stdin)
+                    chunks.push(c);
+                raw = Buffer.concat(chunks).toString("utf8").trim();
+            }
+            if (!raw)
+                throw new Error("Provide the URL as an argument or with --stdin");
+            const config = { kind: "url", url: validateWakeUrl(raw), retryMs: retryMsFrom(opts.retryMinutes) };
+            writeWakeConfig(paths, config);
+            console.log(chalk.green(`Wake set: ${describeWake(config)}`));
+            console.log("Test it: hq agent kit wake test");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    wake
+        .command("set-command <argv...>")
+        .description("Run a local command (no shell) when mail is pending; the notice JSON arrives on stdin. Use -- before the command")
+        .option("--timeout-minutes <n>", "Kill a run after this long (default 10)")
+        .option("--retry-minutes <n>", "Re-wake while items stay pending (default 10, minimum 1)")
+        .action((argv, opts) => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            requireExternalCreds(paths);
+            const minutes = opts.timeoutMinutes ? Number(opts.timeoutMinutes) : 10;
+            if (!Number.isFinite(minutes) || minutes <= 0)
+                throw new Error("--timeout-minutes must be a positive number");
+            const config = { kind: "command", command: argv, timeoutMs: minutes * 60_000, retryMs: retryMsFrom(opts.retryMinutes) };
+            writeWakeConfig(paths, config);
+            console.log(chalk.green(`Wake set: ${describeWake(config)}`));
+            console.log("Test it: hq agent kit wake test");
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    wake
+        .command("show")
+        .description("Show the configured wake (the URL is masked)")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => {
+        const paths = agentKitPaths(os.homedir(), process.env);
+        const config = readWakeConfig(paths);
+        const state = currentWakeState(paths);
+        if (opts.json) {
+            console.log(JSON.stringify({ configured: !!config, wake: describeWake(config), lastWakeAt: state.lastWakeAt ?? null }, null, 2));
+            return;
+        }
+        console.log(`  wake:      ${describeWake(config)}`);
+        console.log(`  last wake: ${state.lastWakeAt ?? "never"}`);
+    });
+    wake
+        .command("clear")
+        .description("Remove the wake configuration")
+        .action(() => {
+        const paths = agentKitPaths(os.homedir(), process.env);
+        console.log(clearWakeConfig(paths) ? "Wake cleared." : "No wake was configured.");
+    });
+    wake
+        .command("test")
+        .description("Fire the wake once now with the current pending count")
+        .action(async () => {
+        try {
+            const paths = agentKitPaths(os.homedir(), process.env);
+            const creds = requireExternalCreds(paths);
+            ensureKitDirs(paths);
+            const config = readWakeConfig(paths);
+            if (!config)
+                throw new Error("No wake configured. Run hq agent kit wake set-url --stdin (or set-command).");
+            const log = createKitLogger(paths, "wake", { echo: false });
+            const ids = pendingInbox(paths).map((e) => e.id);
+            const result = await fireWake(config, buildWakeNotice(creds.entityUid, "test", ids, new Date()), { paths, agentUid: creds.entityUid, log });
+            console.log(result.ok ? chalk.green(result.detail) : chalk.red(result.detail));
+            if (!result.ok)
+                process.exit(1);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     kit
         .command("run <service>")
         .description(`Run one kit service in the foreground (${KIT_SERVICES.join("|")}), or \`all\` to supervise every service in one process`)

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

@@ -11,12 +11,13 @@
 import { Command } from "commander";
 import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
 import { type HqRunResult, type McpToolClients } from "../lib/agent-kit/mcp/tools.js";
+import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
 import type { ExternalMachineCreds } from "../lib/agent-kit/creds.js";
 export declare const AGENT_MCP_SERVER_NAME = "hq-agent";
 export declare const AGENT_MCP_INSTRUCTIONS: string;
 export declare const HQ_SUBPROCESS_TIMEOUT_MS = 120000;
 export declare function defaultRunHq(nodeBinary: string, hqBinary: string, env: NodeJS.ProcessEnv): (args: string[]) => Promise<HqRunResult>;
-export declare function defaultMcpClients(creds: ExternalMachineCreds, credsPath: string): McpToolClients;
+export declare function defaultMcpClients(creds: ExternalMachineCreds, credsPath: string, paths?: Pick<AgentKitPaths, "inboxDir">): McpToolClients;
 export declare function createAgentMcpServer(clients: McpToolClients): McpServer;
 export declare function registerAgentMcpCommand(agent: Command): void;
 //# sourceMappingURL=agent-mcp.d.ts.map

package/dist/commands/agent-mcp.js

@@ -21,7 +21,7 @@ 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). " +
+    "hq_inbox_read / hq_dm_send / hq_inbox_done (read pending HQ messages, reply, then mark each handled), 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) {
@@ -45,7 +45,7 @@ export function defaultRunHq(nodeBinary, hqBinary, env) {
         });
     });
 }
-export function defaultMcpClients(creds, credsPath) {
+export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.homedir(), process.env)) {
     const env = {
         ...process.env,
         HQ_MACHINE_CREDS_FILE: credsPath,
@@ -55,6 +55,7 @@ export function defaultMcpClients(creds, credsPath) {
     };
     return {
         creds,
+        paths,
         runHq: defaultRunHq(process.execPath, process.argv[1], env),
         getToken: () => ensureCognitoToken({ tokenSource: "machine", interactive: false }),
         apiJson: async (token, path, init) => {
@@ -96,7 +97,7 @@ export function registerAgentMcpCommand(agent) {
         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));
+        const server = createAgentMcpServer(defaultMcpClients(creds, paths.machineCredsPath, paths));
         process.stderr.write(`hq agent mcp: serving as ${creds.entityUid} (${creds.companySlug})\n`);
         await server.serve(process.stdin, process.stdout);
     });

package/dist/commands/agent.d.ts

@@ -6,6 +6,7 @@
  *   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
+ *   hq agent inbox [done <id…>]   pending HQ messages / mark handled
  */
 import { Command } from "commander";
 export declare function registerAgentCommand(program: Command): void;

package/dist/commands/agent.js

@@ -6,8 +6,10 @@
  *   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
+ *   hq agent inbox [done <id…>]   pending HQ messages / mark handled
  */
 import { registerAgentEnrollCommand } from "./agent-enroll.js";
+import { registerAgentInboxCommand } from "./agent-inbox.js";
 import { registerAgentKitCommand } from "./agent-kit.js";
 import { registerAgentMcpCommand } from "./agent-mcp.js";
 import { registerAgentProbeCommand } from "./agent-probe.js";
@@ -19,5 +21,6 @@ export function registerAgentCommand(program) {
     registerAgentKitCommand(agent);
     registerAgentProbeCommand(agent);
     registerAgentMcpCommand(agent);
+    registerAgentInboxCommand(agent);
 }
 //# sourceMappingURL=agent.js.map

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

@@ -0,0 +1,34 @@
+/**
+ * Local handled-state for the external agent's mirrored inbox.
+ *
+ * The inbox poller appends every new item to ~/.hq-agent/inbox/inbox.jsonl.
+ * A bot marks an item handled with `hq agent inbox done <id>` (or the
+ * `hq_inbox_done` MCP tool); ids land in done-ids.json. "Pending" is every
+ * mirrored item whose id is not done, oldest first. This works the same
+ * whether or not the kit acks on the server (`inboxAck`), so a woken bot can
+ * always drain exactly what it has not handled yet and never reply twice.
+ */
+import type { AgentKitPaths } from "./paths.js";
+export declare const DONE_IDS_NAME = "done-ids.json";
+export declare const MAX_DONE_IDS = 5000;
+export interface MirroredInboxEntry {
+    id: string;
+    mirroredAt?: string;
+    [key: string]: unknown;
+}
+export declare function readDoneIds(paths: Pick<AgentKitPaths, "inboxDir">): Set<string>;
+export declare function markInboxDone(paths: Pick<AgentKitPaths, "inboxDir">, ids: string[]): string[];
+/** Every mirrored entry, oldest first, de-duplicated by id (last write wins). */
+export declare function readMirroredInbox(paths: Pick<AgentKitPaths, "inboxDir">): MirroredInboxEntry[];
+export declare function pendingInbox(paths: Pick<AgentKitPaths, "inboxDir">): MirroredInboxEntry[];
+/** Compact view for bots: who, when, which channel, and the text. */
+export declare function summarizeInboxEntry(e: MirroredInboxEntry, done: boolean): {
+    id: string;
+    channel: string | undefined;
+    from: string;
+    fromUid: string | undefined;
+    at: string | undefined;
+    text: string | undefined;
+    done: boolean;
+};
+//# sourceMappingURL=inbox-state.d.ts.map

package/dist/lib/agent-kit/inbox-state.js

@@ -0,0 +1,86 @@
+/**
+ * Local handled-state for the external agent's mirrored inbox.
+ *
+ * The inbox poller appends every new item to ~/.hq-agent/inbox/inbox.jsonl.
+ * A bot marks an item handled with `hq agent inbox done <id>` (or the
+ * `hq_inbox_done` MCP tool); ids land in done-ids.json. "Pending" is every
+ * mirrored item whose id is not done, oldest first. This works the same
+ * whether or not the kit acks on the server (`inboxAck`), so a woken bot can
+ * always drain exactly what it has not handled yet and never reply twice.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const DONE_IDS_NAME = "done-ids.json";
+export const MAX_DONE_IDS = 5000;
+const INBOX_JSONL = "inbox.jsonl";
+export function readDoneIds(paths) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(paths.inboxDir, DONE_IDS_NAME), "utf8"));
+        return new Set(Array.isArray(raw) ? raw.filter((x) => typeof x === "string") : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+export function markInboxDone(paths, ids) {
+    const done = readDoneIds(paths);
+    const added = [];
+    for (const id of ids) {
+        if (!done.has(id)) {
+            done.add(id);
+            added.push(id);
+        }
+    }
+    fs.mkdirSync(paths.inboxDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(path.join(paths.inboxDir, DONE_IDS_NAME), JSON.stringify([...done].slice(-MAX_DONE_IDS)), { mode: 0o600 });
+    return added;
+}
+/** Every mirrored entry, oldest first, de-duplicated by id (last write wins). */
+export function readMirroredInbox(paths) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(paths.inboxDir, INBOX_JSONL), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const byId = new Map();
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (typeof entry.id === "string" && entry.id) {
+                byId.delete(entry.id);
+                byId.set(entry.id, entry);
+            }
+        }
+        catch {
+            /* skip a torn line */
+        }
+    }
+    return [...byId.values()];
+}
+export function pendingInbox(paths) {
+    const done = readDoneIds(paths);
+    return readMirroredInbox(paths).filter((e) => !done.has(e.id));
+}
+/** Compact view for bots: who, when, which channel, and the text. */
+export function summarizeInboxEntry(e, done) {
+    const pick = (...keys) => {
+        for (const k of keys)
+            if (typeof e[k] === "string" && e[k])
+                return e[k];
+        return undefined;
+    };
+    return {
+        id: e.id,
+        channel: pick("channel"),
+        from: pick("fromDisplayName", "fromEmail", "fromPersonUid") ?? "unknown",
+        fromUid: pick("fromPersonUid"),
+        at: pick("receivedAt", "createdAt", "mirroredAt"),
+        text: pick("text", "body"),
+        done,
+    };
+}
+//# sourceMappingURL=inbox-state.js.map

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

@@ -16,6 +16,7 @@
  * tool result.
  */
 import type { ExternalMachineCreds } from "../creds.js";
+import type { AgentKitPaths } from "../paths.js";
 import { type McpTool } from "./jsonrpc.js";
 export interface HqRunResult {
     code: number;
@@ -24,6 +25,8 @@ export interface HqRunResult {
 }
 export interface McpToolClients {
     creds: ExternalMachineCreds;
+    /** Kit layout; the inbox tools read the mirror and done-state here. */
+    paths: Pick<AgentKitPaths, "inboxDir">;
     /** Run `hq <args…>` as the machine identity; never throws. */
     runHq: (args: string[]) => Promise<HqRunResult>;
     getToken: () => Promise<string>;

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

@@ -17,6 +17,7 @@
  */
 import { CLI_VERSION } from "../../../cli-version.js";
 import { peekIdToken } from "../../../utils/id-token.js";
+import { markInboxDone, readDoneIds, readMirroredInbox, summarizeInboxEntry } from "../inbox-state.js";
 import { errorResult, McpToolInputError, textResult } from "./jsonrpc.js";
 export const MAX_TOOL_OUTPUT_CHARS = 40_000;
 function str(args, key, opts = {}) {
@@ -226,37 +227,87 @@ export function buildAgentMcpTools(clients) {
         },
         {
             name: "hq_inbox_read",
-            description: "Read this agent's recent incoming direct messages (newest first). Optionally only unread.",
+            description: "Read this agent's HQ inbox (DMs, channel mentions, jobs), oldest first. By default only items not yet " +
+                "marked handled. Reply with hq_dm_send, then mark each one handled with hq_inbox_done so it is never answered twice.",
             inputSchema: {
                 type: "object",
                 properties: {
                     limit: { type: "integer", minimum: 1, maximum: 100 },
-                    unread_only: { type: "boolean" },
+                    include_done: { type: "boolean", description: "Also return items already marked handled" },
+                    unread_only: { type: "boolean", description: "Deprecated alias: true is the default behaviour" },
                 },
                 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)));
+                const includeDone = args.include_done === true;
+                const done = readDoneIds(clients.paths);
+                // The kit mirror is the source of truth; merge the agent's own server
+                // inbox so items the poller has not mirrored yet are not missed.
+                const byId = new Map();
+                for (const e of readMirroredInbox(clients.paths))
+                    byId.set(e.id, e);
+                let serverNote;
+                try {
+                    const token = await clients.getToken();
+                    const res = await clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`);
+                    if (res.status === 200) {
+                        const messages = res.body?.messages;
+                        for (const m of Array.isArray(messages) ? messages : []) {
+                            if (!m || typeof m !== "object")
+                                continue;
+                            const raw = m;
+                            const id = typeof raw.id === "string" ? raw.id : typeof raw.messageId === "string" ? raw.messageId : null;
+                            if (id && !byId.has(id))
+                                byId.set(id, { ...raw, id });
+                        }
+                    }
+                    else {
+                        serverNote = `server inbox answered ${res.status}: ${describeError(res.body)}; showing the local mirror only`;
+                    }
+                }
+                catch (err) {
+                    serverNote = `server inbox unavailable (${err instanceof Error ? err.message : String(err)}); showing the local mirror only`;
+                }
+                const rows = [...byId.values()]
+                    .filter((e) => includeDone || !done.has(e.id))
+                    .slice(0, limit)
+                    .map((e) => summarizeInboxEntry(e, done.has(e.id)));
+                return textResult(clampOutput(JSON.stringify({ count: rows.length, messages: rows, ...(serverNote ? { note: serverNote } : {}) }, null, 2)));
+            },
+        },
+        {
+            name: "hq_inbox_done",
+            description: "Mark inbox items handled (after replying) so they stop showing as pending and the wake hook stops retrying.",
+            inputSchema: {
+                type: "object",
+                properties: { ids: { type: "array", items: { type: "string" }, description: "Item ids from hq_inbox_read" } },
+                required: ["ids"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const ids = strList(args, "ids");
+                for (const id of ids) {
+                    if (!/^[A-Za-z0-9._:-]{1,200}$/.test(id))
+                        throw new McpToolInputError(`invalid id ${JSON.stringify(id)}`);
+                }
+                const added = markInboxDone(clients.paths, ids);
+                const acked = [];
+                const failed = [];
+                try {
+                    const token = await clients.getToken();
+                    for (const id of ids) {
+                        const res = await clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox/${encodeURIComponent(id)}/ack`, { method: "POST" });
+                        if (res.status >= 200 && res.status < 300)
+                            acked.push(id);
+                        else
+                            failed.push(`${id} (${res.status})`);
+                    }
+                }
+                catch (err) {
+                    failed.push(`ack skipped: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                return textResult(JSON.stringify({ marked: added.length, alreadyDone: ids.length - added.length, serverAcked: acked.length, ...(failed.length ? { ackFailures: failed } : {}) }, null, 2));
             },
         },
         {

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

@@ -17,6 +17,7 @@
  */
 import type { KitLogger } from "../log.js";
 import type { AgentKitPaths } from "../paths.js";
+import { type WakeConfig, type WakeDeps, type WakeNotice, type WakeResult } from "../wake.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;
@@ -42,6 +43,10 @@ export interface InboxDeps {
     warmCache?: (token: string, agentUid: string) => Promise<unknown>;
     sleep?: (ms: number) => Promise<void>;
     maxPolls?: number;
+    /** Override wake config lookup (tests). `null` disables the wake. */
+    wakeConfig?: WakeConfig | null;
+    fireWake?: (config: WakeConfig, notice: WakeNotice, deps: WakeDeps) => Promise<WakeResult>;
+    now?: () => Date;
 }
 export declare const INBOX_ERROR_BODY_MAX = 300;
 export interface InboxFetchResult {

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

@@ -19,6 +19,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { vaultApiFetch } from "../../../utils/vault-api.js";
 import { writeComponentStatus } from "../creds.js";
+import { pendingInbox } from "../inbox-state.js";
+import { buildWakeNotice, currentWakeState, fireWake, readWakeConfig, shouldWake, } from "../wake.js";
 export const SEEN_IDS_NAME = "seen-ids.json";
 export const INBOX_JSONL_NAME = "inbox.jsonl";
 export const MAX_SEEN_IDS = 5000;
@@ -168,8 +170,27 @@ export async function pollInboxOnce(deps) {
             deps.log("warn", `cache refresh failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    await maybeWake(deps, fresh.length);
     return { ok: true, mirrored: fresh.length };
 }
+/** Poke the bot's framework when mail is new, or still pending past the retry window. */
+async function maybeWake(deps, freshCount) {
+    const config = deps.wakeConfig !== undefined ? deps.wakeConfig : readWakeConfig(deps.paths);
+    if (!config)
+        return;
+    const now = (deps.now ?? (() => new Date()))();
+    const pending = pendingInbox(deps.paths);
+    const reason = shouldWake(config, currentWakeState(deps.paths), freshCount, pending.length, now);
+    if (!reason)
+        return;
+    const notice = buildWakeNotice(deps.agentUid, reason, pending.map((e) => e.id), now);
+    try {
+        await (deps.fireWake ?? fireWake)(config, notice, { paths: deps.paths, agentUid: deps.agentUid, log: deps.log, now: deps.now });
+    }
+    catch (err) {
+        deps.log("warn", `wake failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 export async function runInboxLoop(deps) {
     const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     let polls = 0;

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

@@ -25,18 +25,21 @@ hq dm <uid1>,<uid2> "message text"         # group DM
 hq dm '#channel-name' "message text"       # channel
 \`\`\`
 
-## Read
+## 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 dm inbox --unread            # unread DMs addressed to you
-hq dm thread <email-or-uid>     # the 1:1 conversation
-hq dm inbox --mark-read         # mark what you have read
-hq dm channel <name>            # read a channel
+hq agent inbox                  # pending messages, oldest first (id, sender uid, text)
+hq dm <sender-uid> "reply"      # answer each one
+hq agent inbox done <id> [id…]  # mark handled so it is never answered twice
 \`\`\`
 
-New inbound messages are also mirrored by the kit's inbox poller to
-\`~/.hq-agent/inbox/<id>.json\` (and \`inbox.jsonl\`) — check there when
-you are asked whether anyone has messaged you.
+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
 

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

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

@@ -0,0 +1,236 @@
+/**
+ * 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 * as fs from "node:fs";
+import * as path from "node:path";
+export const WAKE_FILE_NAME = "wake.json";
+export const WAKE_STATE_NAME = "wake-state.json";
+export const DEFAULT_WAKE_RETRY_MS = 10 * 60_000;
+export const WAKE_URL_TIMEOUT_MS = 15_000;
+export const DEFAULT_WAKE_COMMAND_TIMEOUT_MS = 10 * 60_000;
+export const WAKE_INSTRUCTIONS = "New HQ messages are waiting. Run `hq agent inbox` (or the hq_inbox_read tool), reply to each " +
+    "with `hq dm <sender-uid> \"…\"` (or hq_dm_send), then mark each handled with `hq agent inbox done <id>` (or hq_inbox_done).";
+export function wakePath(paths) {
+    return path.join(paths.agentDir, WAKE_FILE_NAME);
+}
+function wakeStatePath(paths) {
+    return path.join(paths.stateDir, WAKE_STATE_NAME);
+}
+export function validateWakeUrl(raw) {
+    const url = raw.trim();
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error("wake URL is not a valid URL");
+    }
+    const local = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "::1";
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && local)) {
+        throw new Error("wake URL must use https (http is allowed only for localhost)");
+    }
+    if (parsed.username || parsed.password)
+        throw new Error("wake URL must not embed a username or password");
+    return url;
+}
+/** Origin plus a masked path: enough to recognise, not enough to call. */
+export function redactWakeUrl(url) {
+    try {
+        const u = new URL(url);
+        return `${u.origin}/…`;
+    }
+    catch {
+        return "(invalid url)";
+    }
+}
+export function describeWake(config) {
+    if (!config)
+        return "not configured";
+    return config.kind === "url"
+        ? `url ${redactWakeUrl(config.url)}`
+        : `command ${config.command[0]}${config.command.length > 1 ? " …" : ""}`;
+}
+export function readWakeConfig(paths) {
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(wakePath(paths), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    const retryMs = typeof raw.retryMs === "number" && raw.retryMs >= 60_000 ? raw.retryMs : DEFAULT_WAKE_RETRY_MS;
+    if (raw.kind === "url" && typeof raw.url === "string") {
+        try {
+            return { kind: "url", url: validateWakeUrl(raw.url), retryMs };
+        }
+        catch {
+            return null;
+        }
+    }
+    if (raw.kind === "command" && Array.isArray(raw.command) && raw.command.length > 0 && raw.command.every((x) => typeof x === "string" && x)) {
+        const timeoutMs = typeof raw.timeoutMs === "number" && raw.timeoutMs > 0 ? raw.timeoutMs : DEFAULT_WAKE_COMMAND_TIMEOUT_MS;
+        return { kind: "command", command: raw.command, timeoutMs, retryMs };
+    }
+    return null;
+}
+export function writeWakeConfig(paths, config) {
+    fs.mkdirSync(paths.agentDir, { recursive: true, mode: 0o700 });
+    const file = wakePath(paths);
+    fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+}
+export function clearWakeConfig(paths) {
+    try {
+        fs.unlinkSync(wakePath(paths));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readWakeState(paths) {
+    try {
+        return JSON.parse(fs.readFileSync(wakeStatePath(paths), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeWakeState(paths, state) {
+    fs.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(wakeStatePath(paths), JSON.stringify(state), { mode: 0o600 });
+}
+function pidAlive(pid) {
+    if (!pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function buildWakeNotice(agentUid, reason, ids, now) {
+    return {
+        event: "hq.inbox.pending",
+        agentUid,
+        reason,
+        pending: ids.length,
+        messageIds: ids.slice(0, 50),
+        at: now.toISOString(),
+        instructions: WAKE_INSTRUCTIONS,
+    };
+}
+/**
+ * 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 function shouldWake(config, state, freshCount, pendingCount, now) {
+    if (pendingCount === 0)
+        return null;
+    if (freshCount > 0)
+        return "new";
+    const last = state.lastWakeAt ? Date.parse(state.lastWakeAt) : NaN;
+    if (Number.isNaN(last) || now.getTime() - last >= config.retryMs)
+        return "retry";
+    return null;
+}
+export async function fireWake(config, notice, deps) {
+    const now = deps.now ?? (() => new Date());
+    const state = readWakeState(deps.paths);
+    const alive = deps.pidAlive ?? pidAlive;
+    if (config.kind === "url") {
+        const doFetch = deps.fetchImpl ?? fetch;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), WAKE_URL_TIMEOUT_MS);
+        const target = redactWakeUrl(config.url);
+        try {
+            const res = await doFetch(config.url, {
+                method: "POST",
+                headers: { "content-type": "application/json", "user-agent": "hq-agent-kit" },
+                body: JSON.stringify(notice),
+                signal: controller.signal,
+            });
+            writeWakeState(deps.paths, { ...state, lastWakeAt: now().toISOString() });
+            const ok = res.status >= 200 && res.status < 300;
+            const detail = `wake url ${target} → ${res.status} (${notice.reason}, ${notice.pending} pending)`;
+            deps.log(ok ? "info" : "warn", detail);
+            return { fired: true, ok, detail };
+        }
+        catch (err) {
+            const detail = `wake url ${target} failed: ${err instanceof Error ? err.name === "AbortError" ? "timeout" : err.message : String(err)}`;
+            deps.log("warn", detail);
+            return { fired: true, ok: false, detail };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    if (alive(state.runningPid)) {
+        writeWakeState(deps.paths, { ...state, rerun: true });
+        const detail = `wake command still running (pid ${state.runningPid}); will run again after it exits`;
+        deps.log("info", detail);
+        return { fired: false, ok: true, detail };
+    }
+    const doSpawn = deps.spawnImpl ?? spawn;
+    const logFd = fs.openSync(path.join(deps.paths.logsDir, "wake.log"), "a", 0o600);
+    let child;
+    try {
+        child = doSpawn(config.command[0], config.command.slice(1), {
+            stdio: ["pipe", logFd, logFd],
+            env: {
+                ...process.env,
+                HQ_WAKE_EVENT: notice.event,
+                HQ_WAKE_REASON: notice.reason,
+                HQ_WAKE_PENDING: String(notice.pending),
+                HQ_AGENT_UID: notice.agentUid,
+            },
+        });
+    }
+    catch (err) {
+        fs.closeSync(logFd);
+        const detail = `wake command failed to start: ${err instanceof Error ? err.message : String(err)}`;
+        deps.log("warn", detail);
+        return { fired: false, ok: false, detail };
+    }
+    fs.closeSync(logFd);
+    child.stdin?.end(`${JSON.stringify(notice)}\n`);
+    writeWakeState(deps.paths, { lastWakeAt: now().toISOString(), runningPid: child.pid, rerun: false });
+    const timer = setTimeout(() => child.kill("SIGTERM"), config.timeoutMs);
+    const detail = `wake command started pid ${child.pid} (${notice.reason}, ${notice.pending} pending)`;
+    deps.log("info", detail);
+    child.on("error", (err) => deps.log("warn", `wake command error: ${err.message}`));
+    child.on("exit", (code, signal) => {
+        clearTimeout(timer);
+        const after = readWakeState(deps.paths);
+        writeWakeState(deps.paths, { lastWakeAt: after.lastWakeAt, rerun: false });
+        deps.log(code === 0 ? "info" : "warn", `wake command exited ${signal ?? code}`);
+        if (after.rerun) {
+            void fireWake(config, { ...notice, reason: "new", at: now().toISOString() }, deps);
+        }
+    });
+    return { fired: true, ok: true, detail };
+}
+export function currentWakeState(paths) {
+    return { lastWakeAt: readWakeState(paths).lastWakeAt };
+}
+//# sourceMappingURL=wake.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.117.3",
+  "version": "5.118.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {