@holon-run/agentinbox 1.0.3 → 1.0.5

package/README.md

@@ -13,8 +13,9 @@ In practice, that means `AgentInbox` can:
 
 - share one GitHub or Feishu source across multiple local agents
 - materialize those events into durable inboxes
-- wake or drive agent sessions running in `tmux` or `iTerm2`, even when the
-  agent runtime does not expose a notification API
+- activate terminal-backed sessions in `tmux` or `iTerm2`, or Holon agents
+  through runtime-provided webhook triggers, without embedding connector logic
+  in the agent runtime
 
 ## Event Flow
 
@@ -111,7 +112,7 @@ node dist/src/cli.js --help
 
 ## Recommended Onboarding
 
-If you are using Codex or Claude Code, start with the bundled AgentInbox skill:
+If you are using Codex, Claude Code, or Holon, start with the bundled AgentInbox skill:
 
 - repo copy: [`skills/agentinbox/SKILL.md`](./skills/agentinbox/SKILL.md)
 - docs site copy: `https://agentinbox.holon.run/skills/agentinbox/SKILL`
@@ -120,7 +121,7 @@ If you use the community `skills` installer, you can install the bundled skill
 directly:
 
 ```bash
-npx skills add holon-run/agentinbox --skill agentinbox -a codex -a claude-code
+npx skills add holon-run/agentinbox --skill agentinbox -a codex -a claude-code -a holon
 ```
 
 That skill is the recommended onboarding path. It can guide the agent through:
@@ -128,7 +129,8 @@ That skill is the recommended onboarding path. It can guide the agent through:
 - checking or installing `agentinbox`
 - checking or installing `uxc`
 - importing GitHub auth from the local `gh` CLI via `uxc auth credential import github --from gh`
-- registering the current terminal session as an agent
+- registering the current runtime/session as an agent, including Holon webhook
+  activation when running in Holon
 - adding GitHub sources and standing subscriptions using the docs-site examples
 
 ## Quick Start
@@ -139,15 +141,20 @@ Start the local daemon:
 agentinbox daemon start
 ```
 
-Register the current terminal session:
+Register the current runtime/session:
 
 ```bash
 agentinbox agent register
 agentinbox agent register --agent-id agent-alpha
+agentinbox agent register --agent-id agent-alpha --webhook-url <external-trigger-url>
 agentinbox agent register --notify-lease-ms 600000 --min-unacked-items 5
 agentinbox agent current
 ```
 
+Terminal-backed runtimes attach a terminal activation target. In Holon, the
+no-arg form uses `HOLON_AGENT_ID` and `HOLON_EXTERNAL_TRIGGER_URL` when present;
+otherwise pass `--webhook-url` explicitly.
+
 `notifyLeaseMs` and `minUnackedItems` are target-facing notification policy:
 they control how often a target may be reminded and how many unacked items must
 accumulate before AgentInbox notifies it. Service-wide activation batching

package/dist/src/adapters.js

@@ -208,6 +208,18 @@ class AdapterRegistry {
         }
         return module.invokeDeliveryOperation({ handle, operation, input, attempt, source });
     }
+    async listSourceOperations(source) {
+        if (source.sourceType === "local_event") {
+            return [];
+        }
+        return this.remoteSource.listSourceOperations(source);
+    }
+    async invokeSourceOperation(source, operation, input) {
+        if (source.sourceType === "local_event") {
+            throw new Error(`source operations are not supported for source type ${source.sourceType}`);
+        }
+        return this.remoteSource.invokeSourceOperation(source, operation, input);
+    }
     status() {
         return {
             remote: this.remoteSource.status?.() ?? {},

package/dist/src/cli.js

@@ -6,6 +6,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const commander_1 = require("commander");
 const adapters_1 = require("./adapters");
 const client_1 = require("./client");
 const control_server_1 = require("./control_server");
@@ -24,11 +25,16 @@ async function main() {
     const normalized = shouldTreatJsonFlagAsNoop(detectedArgs)
         ? stripNoopJsonFlag(detectedArgs)
         : detectedArgs;
+    const shell = parseCommanderShell(normalized);
     const command = normalized[0];
     if (!command || command === "help" || command === "--help" || command === "-h") {
         printHelp(normalized.slice(1));
         return;
     }
+    if (shell.isBareGroup) {
+        printHelp([command]);
+        return;
+    }
     if (command === "version" || command === "--version" || command === "-v") {
         if (hasHelpFlag(normalized.slice(1))) {
             printHelp(["version"]);
@@ -57,7 +63,7 @@ async function main() {
         printHelp([command]);
         return;
     }
-    const client = await createClient(normalized);
+    const client = await createClient(clientArgsForCommand(normalized));
     if (command === "host" && normalized[1] === "add") {
         const [hostType, hostKey] = normalized.slice(2, 4);
         if (!hostType || !hostKey) {
@@ -72,7 +78,10 @@ async function main() {
         return;
     }
     if (command === "host" && normalized[1] === "list") {
-        await printRemote(client, "/hosts", undefined, "GET");
+        const query = buildQuery({
+            limit: parseOptionalLimitArg(normalized),
+        });
+        await printRemote(client, `/hosts${query}`, undefined, "GET");
         return;
     }
     if (command === "host" && normalized[1] === "show") {
@@ -106,7 +115,10 @@ async function main() {
         return;
     }
     if (command === "stream" && normalized[1] === "list") {
-        await printRemote(client, "/streams", undefined, "GET");
+        const query = buildQuery({
+            limit: parseOptionalLimitArg(normalized),
+        });
+        await printRemote(client, `/streams${query}`, undefined, "GET");
         return;
     }
     if (command === "stream" && normalized[1] === "show") {
@@ -266,7 +278,10 @@ async function main() {
         return;
     }
     if (command === "source" && normalized[1] === "list") {
-        await printRemote(client, "/sources", undefined, "GET");
+        const query = buildQuery({
+            limit: parseOptionalLimitArg(normalized),
+        });
+        await printRemote(client, `/sources${query}`, undefined, "GET");
         return;
     }
     if (command === "source" && normalized[1] === "show") {
@@ -334,6 +349,27 @@ async function main() {
         await printRemote(client, `/sources/${encodeURIComponent(sourceRef)}/schema`, undefined, "GET");
         return;
     }
+    if (command === "source" && normalized[1] === "actions") {
+        const sourceId = normalized[2];
+        if (!sourceId) {
+            throw new Error("usage: agentinbox source actions <sourceId>");
+        }
+        await printRemote(client, `/sources/${encodeURIComponent(sourceId)}/actions`, undefined, "GET");
+        return;
+    }
+    if (command === "source" && normalized[1] === "invoke") {
+        const sourceId = normalized[2];
+        const operation = takeFlagValue(normalized, "--operation");
+        const inputJson = takeFlagValue(normalized, "--input-json");
+        if (!sourceId || !operation || !inputJson) {
+            throw new Error("usage: agentinbox source invoke <sourceId> --operation NAME --input-json JSON");
+        }
+        await printRemote(client, `/sources/${encodeURIComponent(sourceId)}/invoke`, {
+            operation,
+            input: (0, util_1.parseJsonArg)(inputJson, "--input-json"),
+        });
+        return;
+    }
     if (command === "source" && normalized[1] === "poll") {
         const sourceId = normalized[2];
         if (!sourceId) {
@@ -363,15 +399,18 @@ async function main() {
         const notifyLeaseMs = parseOptionalNumber(takeFlagValue(normalized, "--notify-lease-ms")) ?? undefined;
         const minUnackedItems = parseOptionalNumber(takeFlagValue(normalized, "--min-unacked-items")) ?? undefined;
         const webhookUrl = takeFlagValue(normalized, "--webhook-url");
+        const holonContext = (0, current_agent_1.detectHolonRuntimeContext)(process.env);
         if (webhookUrl) {
-            if (!agentId) {
-                throw new Error("usage: agentinbox agent register --agent-id ID --webhook-url URL [--webhook-activation-mode MODE] [--webhook-notify-lease-ms N] [--webhook-min-unacked-items N]");
+            const resolvedAgentId = agentId ?? holonContext?.agentId;
+            if (!resolvedAgentId) {
+                throw new Error("usage: agentinbox agent register --agent-id ID --webhook-url URL [--webhook-activation-mode MODE] [--webhook-notify-lease-ms N] [--webhook-min-unacked-items N] (or set HOLON_AGENT_ID in Holon)");
             }
             const webhookNotifyLeaseMs = parseOptionalNumber(takeFlagValue(normalized, "--webhook-notify-lease-ms")) ?? notifyLeaseMs;
             const webhookMinUnackedItems = parseOptionalNumber(takeFlagValue(normalized, "--webhook-min-unacked-items")) ?? minUnackedItems;
             await printRemote(client, "/agents", {
-                agentId,
+                agentId: resolvedAgentId,
                 forceRebind: normalized.includes("--force-rebind"),
+                ...(holonContext ? { runtimeKind: holonContext.runtimeKind } : {}),
                 webhook: {
                     url: webhookUrl,
                     activationMode: takeFlagValue(normalized, "--webhook-activation-mode") ?? undefined,
@@ -381,6 +420,28 @@ async function main() {
             });
             return;
         }
+        if ((0, current_agent_1.isHolonRuntimeEnv)(process.env)) {
+            if (!holonContext) {
+                throw new Error("agent register in Holon requires HOLON_AGENT_ID");
+            }
+            if (!holonContext.externalTriggerUrl) {
+                throw new Error("agent register in Holon requires --webhook-url or HOLON_EXTERNAL_TRIGGER_URL");
+            }
+            const webhookNotifyLeaseMs = parseOptionalNumber(takeFlagValue(normalized, "--webhook-notify-lease-ms")) ?? notifyLeaseMs;
+            const webhookMinUnackedItems = parseOptionalNumber(takeFlagValue(normalized, "--webhook-min-unacked-items")) ?? minUnackedItems;
+            await printRemote(client, "/agents", {
+                agentId: agentId ?? holonContext.agentId,
+                forceRebind: normalized.includes("--force-rebind"),
+                runtimeKind: holonContext.runtimeKind,
+                webhook: {
+                    url: holonContext.externalTriggerUrl,
+                    activationMode: takeFlagValue(normalized, "--webhook-activation-mode") ?? undefined,
+                    notifyLeaseMs: webhookNotifyLeaseMs,
+                    minUnackedItems: webhookMinUnackedItems,
+                },
+            });
+            return;
+        }
         const detected = (0, terminal_1.detectTerminalContext)(process.env);
         await printRemote(client, "/agents", {
             agentId,
@@ -399,7 +460,7 @@ async function main() {
         return;
     }
     if (command === "agent" && normalized[1] === "list") {
-        await printAgentList(client);
+        await printAgentList(client, parseOptionalLimitArg(normalized));
         return;
     }
     if (command === "agent" && normalized[1] === "current") {
@@ -448,9 +509,12 @@ async function main() {
     if (command === "agent" && normalized[1] === "target" && normalized[2] === "list") {
         const agentId = normalized[3];
         if (!agentId) {
-            throw new Error("usage: agentinbox agent target list <agentId>");
+            throw new Error("usage: agentinbox agent target list <agentId> [--limit N]");
         }
-        await printRemote(client, `/agents/${encodeURIComponent(agentId)}/targets`, undefined, "GET");
+        const query = buildQuery({
+            limit: parseOptionalLimitArg(normalized),
+        });
+        await printRemote(client, `/agents/${encodeURIComponent(agentId)}/targets${query}`, undefined, "GET");
         return;
     }
     if (command === "agent" && normalized[1] === "target" && normalized[2] === "remove") {
@@ -522,6 +586,7 @@ async function main() {
         const query = buildQuery({
             source_id: takeFlagValue(normalized, "--source-id"),
             agent_id: takeFlagValue(normalized, "--agent-id"),
+            limit: parseOptionalLimitArg(normalized),
         });
         await printRemote(client, `/subscriptions${query}`, undefined, "GET");
         return;
@@ -599,6 +664,7 @@ async function main() {
     if (command === "timer" && normalized[1] === "list") {
         const query = buildQuery({
             agent_id: takeFlagValue(normalized, "--agent-id"),
+            limit: parseOptionalLimitArg(normalized),
         });
         await printRemote(client, `/timers${query}`, undefined, "GET");
         return;
@@ -628,7 +694,10 @@ async function main() {
         return;
     }
     if (command === "inbox" && normalized[1] === "list") {
-        await printRemote(client, "/agents", undefined, "GET");
+        const query = buildQuery({
+            limit: parseOptionalLimitArg(normalized),
+        });
+        await printRemote(client, `/agents${query}`, undefined, "GET");
         return;
     }
     if (command === "inbox" && normalized[1] === "show") {
@@ -641,9 +710,9 @@ async function main() {
     }
     if (command === "inbox" && normalized[1] === "read") {
         const args = normalized.slice(2);
-        const allowedFlags = ["--agent-id", "--after-entry", "--include-acked"];
-        if (positionalArgs(args, ["--agent-id", "--after-entry"]).length > 0 || unexpectedFlags(args, allowedFlags).length > 0) {
-            throw new Error("usage: agentinbox inbox read [--agent-id ID] [--after-entry ID] [--include-acked]");
+        const allowedFlags = ["--agent-id", "--after-entry", "--include-acked", "--limit"];
+        if (positionalArgs(args, ["--agent-id", "--after-entry", "--limit"]).length > 0 || unexpectedFlags(args, allowedFlags).length > 0) {
+            throw new Error("usage: agentinbox inbox read [--agent-id ID] [--after-entry ID] [--include-acked] [--limit N]");
         }
         const selection = await selectAgentForCommand(client, {
             explicitAgentId: takeFlagValue(normalized, "--agent-id"),
@@ -652,6 +721,7 @@ async function main() {
         const query = buildQuery({
             after_entry_id: takeFlagValue(normalized, "--after-entry"),
             include_acked: hasFlag(normalized, "--include-acked") ? "true" : undefined,
+            limit: parseOptionalLimitArg(normalized),
         });
         const response = await requestRemote(client, `/agents/${encodeURIComponent(selection.agentId)}/inbox/entries${query}`, undefined, "GET");
         console.log((0, util_1.jsonResponse)(withCommandMetadata(response.data, selection)));
@@ -835,6 +905,53 @@ async function main() {
     }
     throw new Error(`unknown command: ${normalized.join(" ")}`);
 }
+const COMMAND_SHELL_SPECS = [
+    { name: "serve", group: false, summary: "Run the AgentInbox control server." },
+    { name: "daemon", group: true, summary: "Manage the local AgentInbox daemon." },
+    { name: "host", group: true, summary: "Manage source hosts." },
+    { name: "stream", group: true, summary: "Manage source streams." },
+    { name: "follow", group: true, summary: "Create high-level source subscriptions." },
+    { name: "source", group: true, summary: "Manage source streams through the source alias." },
+    { name: "agent", group: true, summary: "Manage local agent registrations and activation targets." },
+    { name: "timer", group: true, summary: "Manage agent reminder timers." },
+    { name: "subscription", group: true, summary: "Manage source subscriptions." },
+    { name: "inbox", group: true, summary: "Read and manage agent inboxes." },
+    { name: "gc", group: false, summary: "Run garbage collection." },
+    { name: "deliver", group: true, summary: "Send outbound delivery actions." },
+    { name: "status", group: false, summary: "Show daemon status." },
+    { name: "version", group: false, summary: "Show CLI version." },
+];
+const COMMANDER_SHELL = createCommanderShell();
+function createCommanderShell() {
+    const program = new commander_1.Command();
+    program
+        .name("agentinbox")
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .exitOverride()
+        .configureOutput({
+        writeOut: () => { },
+        writeErr: () => { },
+    });
+    for (const spec of COMMAND_SHELL_SPECS) {
+        program
+            .command(`${spec.name} [args...]`)
+            .description(spec.summary)
+            .allowUnknownOption(true)
+            .allowExcessArguments(true);
+    }
+    return program;
+}
+function parseCommanderShell(args) {
+    const command = args[0] ?? null;
+    if (!command || command === "help" || command === "--help" || command === "-h") {
+        return { isBareGroup: false };
+    }
+    const spec = COMMANDER_SHELL.commands.find((item) => item.name() === command);
+    return {
+        isBareGroup: Boolean(COMMAND_SHELL_SPECS.find((item) => item.name === spec?.name())?.group && args.length === 1),
+    };
+}
 async function runServe(args) {
     const port = parseOptionalNumber(takeFlagValue(args, "--port"));
     const homeOverride = takeFlagValue(args, "--home");
@@ -925,12 +1042,12 @@ async function createClient(args) {
     });
     return new client_1.AgentInboxClient(transport);
 }
-async function printAgentList(client) {
-    const records = await listAgentsWithTargets(client);
-    console.log((0, util_1.jsonResponse)((0, current_agent_1.annotateAgents)(records, tryDetectTerminalContext())));
+async function printAgentList(client, limit) {
+    const records = await listAgentsWithTargets(client, limit);
+    console.log((0, util_1.jsonResponse)((0, current_agent_1.annotateAgents)(records, tryDetectCurrentAgentContext())));
 }
 async function printCurrentAgent(client) {
-    const context = getRequiredTerminalContext();
+    const context = getRequiredCurrentAgentContext();
     const records = await listAgentsWithTargets(client);
     const current = (0, current_agent_1.resolveCurrentAgent)(records, context);
     if (!current) {
@@ -940,7 +1057,7 @@ async function printCurrentAgent(client) {
 }
 async function selectAgentForCommand(client, options) {
     const records = await listAgentsWithTargets(client);
-    const context = tryDetectTerminalContext();
+    const context = tryDetectCurrentAgentContext();
     if (options.explicitAgentId) {
         const current = context ? (0, current_agent_1.resolveCurrentAgent)(records, context) : null;
         const requested = records.find((entry) => entry.agent.agentId === options.explicitAgentId);
@@ -960,7 +1077,7 @@ async function selectAgentForCommand(client, options) {
             warnings,
         };
     }
-    const contextForCurrent = getRequiredTerminalContext();
+    const contextForCurrent = getRequiredCurrentAgentContext();
     const current = (0, current_agent_1.resolveCurrentAgent)(records, contextForCurrent);
     if (current) {
         return {
@@ -972,17 +1089,7 @@ async function selectAgentForCommand(client, options) {
     if (!options.autoRegister) {
         throw new Error(noCurrentAgentMessage());
     }
-    await requestRemote(client, "/agents", {
-        backend: contextForCurrent.backend,
-        runtimeKind: contextForCurrent.runtimeKind,
-        runtimeSessionId: contextForCurrent.runtimeSessionId ?? undefined,
-        runtimePid: contextForCurrent.runtimePid ?? undefined,
-        tmuxPaneId: contextForCurrent.tmuxPaneId ?? undefined,
-        tty: contextForCurrent.tty ?? undefined,
-        termProgram: contextForCurrent.termProgram ?? undefined,
-        itermSessionId: contextForCurrent.itermSessionId ?? undefined,
-        notifyLeaseMs: undefined,
-    });
+    await requestRemote(client, "/agents", registrationInputForCurrentContext(contextForCurrent));
     const refreshed = await listAgentsWithTargets(client);
     const registered = (0, current_agent_1.resolveCurrentAgent)(refreshed, contextForCurrent);
     if (!registered) {
@@ -994,8 +1101,38 @@ async function selectAgentForCommand(client, options) {
         warnings: [],
     };
 }
-async function listAgentsWithTargets(client) {
-    const response = await requestRemote(client, "/agents?include_targets=true", undefined, "GET");
+function registrationInputForCurrentContext(context) {
+    if ((0, current_agent_1.isHolonRuntimeContext)(context)) {
+        if (!context.externalTriggerUrl) {
+            throw new Error("unable to auto-register current Holon agent: HOLON_EXTERNAL_TRIGGER_URL is not set");
+        }
+        return {
+            agentId: context.agentId,
+            runtimeKind: context.runtimeKind,
+            webhook: {
+                url: context.externalTriggerUrl,
+                notifyLeaseMs: undefined,
+            },
+        };
+    }
+    return {
+        backend: context.backend,
+        runtimeKind: context.runtimeKind,
+        runtimeSessionId: context.runtimeSessionId ?? undefined,
+        runtimePid: context.runtimePid ?? undefined,
+        tmuxPaneId: context.tmuxPaneId ?? undefined,
+        tty: context.tty ?? undefined,
+        termProgram: context.termProgram ?? undefined,
+        itermSessionId: context.itermSessionId ?? undefined,
+        notifyLeaseMs: undefined,
+    };
+}
+async function listAgentsWithTargets(client, limit) {
+    const query = buildQuery({
+        include_targets: "true",
+        limit,
+    });
+    const response = await requestRemote(client, `/agents${query}`, undefined, "GET");
     return response.data.agents;
 }
 async function printRemote(client, endpoint, body, method = "POST") {
@@ -1005,13 +1142,38 @@ async function printRemote(client, endpoint, body, method = "POST") {
 async function requestRemote(client, endpoint, body, method = "POST") {
     const response = await client.request(endpoint, body, method);
     if (response.statusCode < 200 || response.statusCode >= 300) {
-        throw new Error((0, util_1.jsonResponse)(response.data));
+        const bodyText = (0, util_1.jsonResponse)(response.data);
+        throw new Error(`request ${method} ${endpoint} failed with HTTP ${response.statusCode}: ${bodyText}`);
     }
     return { data: response.data };
 }
 function noCurrentAgentMessage() {
     return "no current agent is registered for this terminal/runtime context; run `agentinbox agent list` to inspect offline agents, then `agentinbox agent register` or `agentinbox agent register --force-rebind --agent-id <agentId>` to rebind one";
 }
+function clientArgsForCommand(args) {
+    if (isAgentTargetAddWebhookCommand(args)) {
+        return withoutFlagValues(args, "--url");
+    }
+    return args;
+}
+function isAgentTargetAddWebhookCommand(args) {
+    return args[0] === "agent" && args[1] === "target" && args[2] === "add" && args[3] === "webhook";
+}
+function withoutFlagValues(args, flag) {
+    const filtered = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value !== flag) {
+            filtered.push(value);
+            continue;
+        }
+        const nextIndex = index + 1;
+        if (nextIndex < args.length && !args[nextIndex].startsWith("--")) {
+            index = nextIndex;
+        }
+    }
+    return filtered;
+}
 function takeFlagValue(args, flag) {
     const index = args.indexOf(flag);
     if (index === -1) {
@@ -1102,6 +1264,17 @@ function buildQuery(params) {
     const query = search.toString();
     return query ? `?${query}` : "";
 }
+function parseOptionalLimitArg(args) {
+    const raw = takeFlagValue(args, "--limit");
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 1 || String(parsed) !== raw) {
+        throw new Error("`--limit` must be a positive integer");
+    }
+    return String(parsed);
+}
 function readSubscriptionFilter(args) {
     const filterJson = takeFlagValue(args, "--filter-json");
     const filterFile = takeFlagValue(args, "--filter-file");
@@ -1193,7 +1366,14 @@ function normalizeSubscriptionAddOutput(data, shortcutUsed) {
     }
     return data;
 }
-function getRequiredTerminalContext() {
+function getRequiredCurrentAgentContext() {
+    const holonContext = (0, current_agent_1.detectHolonRuntimeContext)(process.env);
+    if (holonContext) {
+        return holonContext;
+    }
+    if ((0, current_agent_1.isHolonRuntimeEnv)(process.env)) {
+        throw new Error("unable to detect current Holon agent: HOLON_AGENT_ID is not set");
+    }
     try {
         return (0, terminal_1.detectTerminalContext)(process.env);
     }
@@ -1202,7 +1382,11 @@ function getRequiredTerminalContext() {
         throw new Error(`unable to resolve current agent: ${message}`);
     }
 }
-function tryDetectTerminalContext() {
+function tryDetectCurrentAgentContext() {
+    const holonContext = (0, current_agent_1.detectHolonRuntimeContext)(process.env);
+    if (holonContext || (0, current_agent_1.isHolonRuntimeEnv)(process.env)) {
+        return holonContext;
+    }
     try {
         return (0, terminal_1.detectTerminalContext)(process.env);
     }
@@ -1235,10 +1419,9 @@ function unexpectedFlags(args, allowedFlags) {
     const allowed = new Set(allowedFlags);
     return args.filter((token) => token.startsWith("--") && !allowed.has(token));
 }
-function printHelp(path = []) {
-    const key = path[0] ?? "root";
-    const helpByKey = {
-        root: `agentinbox
+function renderRootHelp() {
+    const commands = COMMAND_SHELL_SPECS.map((spec) => `  ${spec.name}`).join("\n");
+    return `agentinbox
 
 Usage:
   agentinbox <command> [options]
@@ -1247,19 +1430,13 @@ Usage:
   agentinbox --version, -v
 
 Commands:
-  serve
-  daemon
-  follow
-  source
-  agent
-  timer
-  subscription
-  inbox
-  gc
-  deliver
-  status
-  version
-`,
+${commands}
+`;
+}
+function printHelp(path = []) {
+    const key = path[0] ?? "root";
+    const helpByKey = {
+        root: renderRootHelp(),
         serve: `agentinbox serve
 
 Usage:
@@ -1277,7 +1454,7 @@ Usage:
 
 Usage:
   agentinbox host add <hostType> <hostKey> [--config-json JSON] [--config-ref REF]
-  agentinbox host list
+  agentinbox host list [--limit N]
   agentinbox host show <hostId>
   agentinbox host schema <hostId>
 `,
@@ -1285,7 +1462,7 @@ Usage:
 
 Usage:
   agentinbox stream add <hostId> <streamKind> <streamKey> [--config-json JSON] [--config-ref REF]
-  agentinbox stream list
+  agentinbox stream list [--limit N]
   agentinbox stream show <streamId>
   agentinbox stream update <streamId> [--config-json JSON] [--config-ref REF | --clear-config-ref]
   agentinbox stream remove <streamId> [--with-subscriptions]
@@ -1305,18 +1482,21 @@ Examples:
   agentinbox follow github repo --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox
   agentinbox follow github pr --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox --arg number=87 --arg withCi=true
   agentinbox follow github issue --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox --arg number=180
+  agentinbox follow feishu mentions --agent-id <agentId> --config-json '{"uxcAuth":"feishu-default"}'
 `,
         source: `agentinbox source
 
 Usage:
   agentinbox source add <hostId> <streamKind> <streamKey> [--config-json JSON] [--config-ref REF]
-  agentinbox source list
+  agentinbox source list [--limit N]
   agentinbox source show <sourceId>
   agentinbox source update <sourceId> [--config-json JSON] [--config-ref REF | --clear-config-ref]
   agentinbox source remove <sourceId> [--with-subscriptions]
   agentinbox source pause <remoteSourceId>
   agentinbox source resume <remoteSourceId>
   agentinbox source schema <sourceId>
+  agentinbox source actions <sourceId>
+  agentinbox source invoke <sourceId> --operation NAME --input-json JSON
   agentinbox source poll <sourceId>
   agentinbox source event <sourceId> --native-id ID --event EVENT [--occurred-at ISO8601] [--metadata-json JSON] [--payload-json JSON]
 `,
@@ -1325,13 +1505,13 @@ Usage:
 Usage:
   agentinbox agent register [--agent-id ID] [--force-rebind] [--notify-lease-ms N] [--min-unacked-items N]
   agentinbox agent register --agent-id ID --webhook-url URL [--webhook-activation-mode MODE] [--webhook-notify-lease-ms N] [--webhook-min-unacked-items N]
-  agentinbox agent list
+  agentinbox agent list [--limit N]
   agentinbox agent current
   agentinbox agent show <agentId>
   agentinbox agent remove <agentId>
   agentinbox agent resume <agentId>
   agentinbox agent target add webhook <agentId> --url URL [--activation-mode MODE] [--notify-lease-ms N] [--min-unacked-items N]
-  agentinbox agent target list <agentId>
+  agentinbox agent target list <agentId> [--limit N]
   agentinbox agent target remove <agentId> <targetId>
   agentinbox agent target resume <agentId> <targetId>
 `,
@@ -1339,7 +1519,7 @@ Usage:
 
 Usage:
   agentinbox timer add --agent-id ID (--at ISO8601 | --every DURATION | --cron EXPR) --message TEXT [--timezone TZ] [--sender SENDER]
-  agentinbox timer list [--agent-id ID]
+  agentinbox timer list [--agent-id ID] [--limit N]
   agentinbox timer pause <scheduleId>
   agentinbox timer resume <scheduleId>
   agentinbox timer remove <scheduleId>
@@ -1348,7 +1528,7 @@ Usage:
 
 Usage:
   agentinbox subscription add <sourceId> [--agent-id ID] [--shortcut NAME --shortcut-args-json JSON] [--filter-json JSON | --filter-file PATH | --filter-stdin] [--tracked-resource-ref REF] [--cleanup-policy-json JSON] [--start-policy POLICY] [--start-offset N] [--start-time ISO8601]
-  agentinbox subscription list [--source-id ID] [--agent-id ID]
+  agentinbox subscription list [--source-id ID] [--agent-id ID] [--limit N]
   agentinbox subscription show <subscriptionId>
   agentinbox subscription remove <subscriptionId>
   agentinbox subscription poll <subscriptionId>
@@ -1358,9 +1538,9 @@ Usage:
         inbox: `agentinbox inbox
 
 Usage:
-  agentinbox inbox list
+  agentinbox inbox list [--limit N]
   agentinbox inbox show <agentId>
-  agentinbox inbox read [--agent-id ID] [--after-entry ID] [--include-acked]
+  agentinbox inbox read [--agent-id ID] [--after-entry ID] [--include-acked] [--limit N]
   agentinbox inbox send --agent-id ID --message TEXT [--sender SENDER]
   agentinbox inbox watch [--agent-id ID] [--after-entry ID] [--include-acked] [--heartbeat-ms N]
   agentinbox inbox ack [--agent-id ID] (--through <entryId> | --entry <entryId> | --all)