@holon-run/agentinbox 1.0.4 → 1.1.0

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

@@ -197,7 +197,7 @@ class AdapterRegistry {
     async listDeliveryOperations(source, handle) {
         const module = await this.resolveDeliveryModule(source, handle);
         if (!module?.listDeliveryOperations) {
-            return [];
+            return null;
         }
         return module.listDeliveryOperations({ handle, source });
     }
@@ -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"]);
@@ -343,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) {
@@ -878,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");
@@ -1345,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]
@@ -1357,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:
@@ -1415,6 +1482,7 @@ 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
 
@@ -1427,6 +1495,8 @@ Usage:
   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]
 `,

package/dist/src/http.js

@@ -381,6 +381,60 @@ function buildFastifyServer(service) {
         const params = request.params;
         return service.getResolvedSourceSchema(decodeURIComponent(params.sourceId));
     });
+    app.get("/sources/:sourceId/actions", {
+        schema: {
+            tags: ["sources"],
+            params: {
+                type: "object",
+                required: ["sourceId"],
+                properties: {
+                    sourceId: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.listSourceOperations(decodeURIComponent(params.sourceId));
+    });
+    app.post("/sources/:sourceId/invoke", {
+        schema: {
+            tags: ["sources"],
+            params: {
+                type: "object",
+                required: ["sourceId"],
+                properties: {
+                    sourceId: { type: "string", minLength: 1 },
+                },
+            },
+            body: {
+                type: "object",
+                additionalProperties: false,
+                required: ["operation", "input"],
+                properties: {
+                    operation: { type: "string", minLength: 1 },
+                    input: jsonObjectSchema,
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        const body = request.body;
+        return service.invokeSourceOperation({
+            sourceId: decodeURIComponent(params.sourceId),
+            operation: body.operation,
+            input: body.input,
+        });
+    });
     app.patch("/streams/:streamId", {
         schema: {
             tags: ["sources"],
@@ -1816,10 +1870,15 @@ function isBadRequestError(message) {
         message.startsWith("deliver send is not supported") ||
         message.startsWith("deliveryHandle requires") ||
         message.startsWith("delivery operations are not supported") ||
+        message.startsWith("unsupported delivery surface") ||
+        message.startsWith("unsupported delivery operation") ||
+        message.startsWith("source operations are not supported") ||
         message.startsWith("unknown GitHub delivery operation") ||
         message.startsWith("unknown Feishu delivery operation") ||
+        message.startsWith("unknown Feishu source operation") ||
         message.startsWith("invalid GitHub targetRef") ||
-        message.includes("requires input.text") ||
+        message.startsWith("get_message_context requires") ||
+        message.includes("requires input.") ||
         message.includes("requires input.body") ||
         message.startsWith("subscriptions/reset requires") ||
         message.startsWith("agents requires") ||

package/dist/src/service.js

@@ -282,6 +282,22 @@ class AgentInboxService {
         const source = this.getSource(sourceId);
         return this.adapters.resolveSourceSchema(source);
     }
+    async listSourceOperations(sourceId) {
+        const source = this.getSource(sourceId);
+        return {
+            sourceId: source.sourceId,
+            operations: await this.adapters.listSourceOperations(source),
+        };
+    }
+    async invokeSourceOperation(request) {
+        const source = this.getSource(request.sourceId);
+        const data = await this.adapters.invokeSourceOperation(source, request.operation, request.input);
+        return {
+            sourceId: source.sourceId,
+            operation: request.operation,
+            data,
+        };
+    }
     async previewSourceSchema(input) {
         try {
             const source = buildPreviewSource(input);
@@ -1604,6 +1620,12 @@ class AgentInboxService {
         const handle = resolveDeliveryHandle(request);
         const source = resolveDeliverySource(this.store, request.sourceId, handle);
         const operations = await this.adapters.listDeliveryOperations(source, handle);
+        if (operations === null) {
+            throw new Error(`delivery operations are not supported for provider ${handle.provider}`);
+        }
+        if (operations.length === 0) {
+            throw new Error(noDeliveryOperationsMessage(handle));
+        }
         return {
             sourceId: source?.sourceId ?? null,
             handle,
@@ -1613,6 +1635,15 @@ class AgentInboxService {
     async invokeDelivery(request) {
         const handle = resolveDeliveryHandle(request);
         const source = resolveDeliverySource(this.store, request.sourceId, handle);
+        const operations = await this.adapters.listDeliveryOperations(source, handle);
+        if (operations !== null) {
+            if (operations.length === 0) {
+                throw new Error(noDeliveryOperationsMessage(handle));
+            }
+            if (!operations.some((operation) => operation.name === request.operation)) {
+                throw new Error(unsupportedDeliveryOperationMessage(handle, request.operation, operations));
+            }
+        }
         const attempt = {
             deliveryId: (0, util_1.generateCanonicalId)("dlv"),
             provider: handle.provider,
@@ -1632,9 +1663,9 @@ class AgentInboxService {
     }
     async sendCanonicalDeliveryViaModule(source, handle, payload, attempt) {
         const operations = await this.adapters.listDeliveryOperations(source, handle);
-        const canonicalOperation = operations.find((operation) => operation.canonicalTextAlias);
+        const canonicalOperation = operations?.find((operation) => operation.canonicalTextAlias);
         if (!canonicalOperation) {
-            throw new Error(`deliver send is not supported for ${handle.provider}/${handle.surface}; use deliver invoke`);
+            throw new Error(deliverSendUnsupportedMessage(handle, operations));
         }
         const input = payload.text != null ? { ...payload, body: String(payload.text) } : payload;
         return this.adapters.invokeDeliveryOperation(source, handle, canonicalOperation.name, input, attempt);
@@ -3869,6 +3900,43 @@ function listHostStreamKinds(hostType) {
             return ["default"];
     }
 }
+const KNOWN_DELIVERY_SURFACES = {
+    feishu: ["message_reply", "chat_message"],
+    github: ["issue_comment", "pull_request_comment", "review_comment"],
+};
+function unsupportedDeliverySurfaceMessage(handle) {
+    const supported = KNOWN_DELIVERY_SURFACES[handle.provider];
+    const supportedHint = supported?.length
+        ? ` Supported surfaces for ${handle.provider}: ${supported.join(", ")}.`
+        : "";
+    return `unsupported delivery surface for ${handle.provider}: ${handle.surface}.${supportedHint} ${deliveryActionsHelp(handle)}`;
+}
+function noDeliveryOperationsMessage(handle) {
+    if (!isKnownDeliverySurface(handle)) {
+        return unsupportedDeliverySurfaceMessage(handle);
+    }
+    return `delivery operations are not supported for ${handle.provider}/${handle.surface}. ${deliveryActionsHelp(handle)}`;
+}
+function unsupportedDeliveryOperationMessage(handle, operation, operations) {
+    const names = operations.map((item) => item.name).join(", ");
+    return `unsupported delivery operation for ${handle.provider}/${handle.surface}: ${operation}. Available operations: ${names}. ${deliveryActionsHelp(handle)}`;
+}
+function deliverSendUnsupportedMessage(handle, operations) {
+    if (!operations || operations.length === 0) {
+        if (!isKnownDeliverySurface(handle)) {
+            return unsupportedDeliverySurfaceMessage(handle);
+        }
+        return `deliver send is not supported for ${handle.provider}/${handle.surface}. ${deliveryActionsHelp(handle)}`;
+    }
+    const names = operations.map((item) => item.name).join(", ");
+    return `deliver send is not supported for ${handle.provider}/${handle.surface}; use deliver invoke with one of: ${names}. ${deliveryActionsHelp(handle)}`;
+}
+function deliveryActionsHelp(handle) {
+    return `Run \`agentinbox deliver actions --provider ${handle.provider} --surface ${handle.surface} --target ${handle.targetRef}\` to inspect supported operations and input schemas.`;
+}
+function isKnownDeliverySurface(handle) {
+    return KNOWN_DELIVERY_SURFACES[handle.provider]?.includes(handle.surface) === true;
+}
 function getHostConfigFields(hostType) {
     switch (hostType) {
         case "github":
@@ -3877,9 +3945,7 @@ function getHostConfigFields(hostType) {
             ];
         case "feishu":
             return [
-                { name: "appId", type: "string", description: "Feishu app ID.", required: true },
-                { name: "appSecret", type: "string", description: "Feishu app secret.", required: true },
-                { name: "uxcAuth", type: "string", description: "Optional shared Feishu auth/runtime profile.", required: false },
+                { name: "uxcAuth", type: "string", description: "Optional shared Feishu/Lark UXC auth profile.", required: false },
             ];
         case "local_event":
             return [];

package/dist/src/source_hosts.js

@@ -32,13 +32,11 @@ function resolveSourceRegistration(input) {
     if (input.sourceType === "feishu_bot") {
         return {
             hostType: "feishu",
-            hostKey: `app:${stringOrDefault(config.appId, input.configRef ?? input.sourceKey)}`,
+            hostKey: `uxcAuth:${stringOrDefault(config.uxcAuth, input.configRef ?? input.sourceKey)}`,
             hostConfig: {
-                ...(valueOrUndefined(config.appId) ? { appId: config.appId } : {}),
-                ...(valueOrUndefined(config.appSecret) ? { appSecret: config.appSecret } : {}),
+                ...(valueOrUndefined(config.uxcAuth) ? { uxcAuth: config.uxcAuth } : {}),
                 ...(valueOrUndefined(config.schemaUrl) ? { schemaUrl: config.schemaUrl } : {}),
                 ...(valueOrUndefined(config.replyInThread) ? { replyInThread: config.replyInThread } : {}),
-                ...(valueOrUndefined(config.uxcAuth) ? { uxcAuth: config.uxcAuth } : {}),
             },
             streamKind: "message_events",
             streamKey: input.sourceKey,

package/dist/src/source_schema.js

@@ -146,13 +146,11 @@ const SOURCE_SCHEMAS = {
         ],
         eventVariantExamples: ["im.message.receive_v1.text"],
         configFields: [
-            { name: "appId", type: "string", required: true, description: "Feishu app ID." },
-            { name: "appSecret", type: "string", required: true, description: "Feishu app secret." },
+            { name: "uxcAuth", type: "string", required: false, description: "Optional UXC auth profile for the Feishu/Lark app." },
             { name: "eventTypes", type: "string[]", required: false, description: "Optional Feishu event type allowlist." },
             { name: "chatIds", type: "string[]", required: false, description: "Optional Feishu chat allowlist." },
             { name: "schemaUrl", type: "string", required: false, description: "Optional Feishu OpenAPI schema URL." },
             { name: "replyInThread", type: "boolean", required: false, description: "Reply in thread when sending outbound messages." },
-            { name: "uxcAuth", type: "string", required: false, description: "Optional uxc auth profile." },
         ],
     },
 };