@holon-run/agentinbox 1.0.4 → 1.0.5

package/dist/src/sources/remote.js

@@ -302,6 +302,30 @@ class RemoteSourceRuntime {
         }
         return module.summarizeDigestThread(items, moduleInputSource(source), grouping);
     }
+    async listSourceOperations(source) {
+        if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
+            return [];
+        }
+        const module = await this.moduleRegistry.resolve(source, this.homeDir);
+        if (typeof module.listSourceOperations !== "function") {
+            return [];
+        }
+        return module.listSourceOperations({ source: moduleInputSource(source) });
+    }
+    async invokeSourceOperation(source, operation, input) {
+        if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
+            throw new Error(`source operations are not supported for source type ${source.sourceType}`);
+        }
+        const module = await this.moduleRegistry.resolve(source, this.homeDir);
+        if (typeof module.invokeSourceOperation !== "function") {
+            throw new Error(`source operations are not supported for source type ${source.sourceType}`);
+        }
+        return module.invokeSourceOperation({
+            source: moduleInputSource(source),
+            operation,
+            input,
+        });
+    }
     async syncAll() {
         const sources = this.store
             .listSources()

package/dist/src/sources/remote_modules.js

@@ -111,6 +111,8 @@ function validateModuleContract(module, sourcePath) {
     validateOptionalHook(module.deriveNotificationGrouping, "deriveNotificationGrouping", sourcePath);
     validateOptionalHook(module.listDeliveryOperations, "listDeliveryOperations", sourcePath);
     validateOptionalHook(module.invokeDeliveryOperation, "invokeDeliveryOperation", sourcePath);
+    validateOptionalHook(module.listSourceOperations, "listSourceOperations", sourcePath);
+    validateOptionalHook(module.invokeSourceOperation, "invokeSourceOperation", sourcePath);
     validateOptionalHook(module.summarizeDigestThread, "summarizeDigestThread", sourcePath);
 }
 function validateOptionalHook(value, name, sourcePath) {
@@ -469,18 +471,22 @@ const FEISHU_BOT_MODULE = {
     async invokeDeliveryOperation(input) {
         return (0, feishu_1.invokeFeishuDeliveryOperation)(input.handle, input.operation, input.input);
     },
+    listSourceOperations() {
+        return (0, feishu_1.feishuSourceOperations)();
+    },
+    async invokeSourceOperation(input) {
+        return (0, feishu_1.invokeFeishuSourceOperation)(input.source, input.operation, input.input);
+    },
     describeCapabilities() {
         return {
             sourceKind: "feishu_bot",
             aliases: ["feishu_bot"],
             configSchema: [
-                { 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." },
             ],
             metadataFields: [
                 { name: "eventType", type: "string", description: "Feishu event type." },
@@ -502,6 +508,12 @@ const FEISHU_BOT_MODULE = {
     validateConfig(source) {
         (0, feishu_1.parseFeishuSourceConfig)(source);
     },
+    listFollowTemplates() {
+        return (0, feishu_1.feishuFollowTemplateSpec)();
+    },
+    async expandFollowTemplate(input) {
+        return (0, feishu_1.expandFeishuFollowTemplate)(input);
+    },
     buildManagedSourceSpec(source) {
         const config = (0, feishu_1.parseFeishuSourceConfig)(source);
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {
@@ -45,6 +45,7 @@
   "dependencies": {
     "@fastify/swagger": "^9.5.2",
     "@holon-run/uxc-daemon-client": "^0.15.4",
+    "commander": "^14.0.3",
     "fastify": "^5.6.1",
     "jexl": "^2.3.0",
     "sql.js": "^1.13.0"

package/skills/README.md

@@ -7,12 +7,12 @@ For `AgentInbox`, the preferred first-run path is skill-first onboarding:
 
 - hand the bundled `AgentInbox` skill to the agent
 - let the agent verify `agentinbox`, `uxc`, and GitHub auth
-- let the agent register the current session and set up standing subscriptions
+- let the agent register the current runtime/session and set up standing subscriptions
 
 <!-- INDEX:START -->
 
 - [agentinbox](./agentinbox/)
-  Use the local AgentInbox service to onboard the current session, connect GitHub through UXC, and operate sources, subscriptions, and the agent inbox.
+  Use the local AgentInbox service to onboard the current runtime/session, manage shared sources and subscriptions, connect external providers such as GitHub through UXC, and operate the agent inbox.
   <!-- mdorigin:index kind=article -->
 
 <!-- INDEX:END -->

package/skills/agentinbox/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: agentinbox
-description: Use the local AgentInbox service to onboard the current session, manage shared sources and subscriptions, connect external providers such as GitHub through UXC, and operate the agent inbox.
+description: Use the local AgentInbox service to onboard the current runtime/session, manage shared sources and subscriptions, connect external providers such as GitHub through UXC, and operate the agent inbox.
 metadata:
   short-description: Operate AgentInbox sources and subscriptions
 ---
 
 # AgentInbox Skill
 
-Use this skill when the current agent should set up or use the local
-`agentinbox` daemon.
+Use this skill when a Codex, Claude Code, Holon, or other supported agent
+runtime should set up or use the local `agentinbox` daemon.
 
 Primary docs:
 
@@ -41,7 +41,7 @@ UXC repository:
 Recommended first-run sequence:
 
 1. if GitHub access is needed and `gh` is already authenticated, import that auth into `uxc`
-2. register the current terminal session
+2. register the current runtime/session
 3. follow the required sources or resources using the docs examples
 
 If GitHub-backed adapters are needed:
@@ -53,12 +53,21 @@ uxc auth credential import github --from gh
 
 This `gh` import path requires `uxc` 0.15.3 or newer.
 
-Register the current terminal/runtime session:
+Register the current runtime/session:
 
 ```bash
 agentinbox agent register
 ```
 
+In Holon, the no-arg form uses `HOLON_AGENT_ID` and
+`HOLON_EXTERNAL_TRIGGER_URL` when they are available and registers a webhook
+activation target. If the trigger URL is not in the environment, pass it
+explicitly:
+
+```bash
+agentinbox agent register --agent-id <holonAgentId> --webhook-url <externalTriggerUrl>
+```
+
 Treat the returned `agentId` as the stable identity for later commands.
 
 ## Usage Discipline
@@ -96,19 +105,19 @@ Typical cases:
 
 Important boundary:
 
-- inbox items, subscriptions, and timers can outlive the current terminal
+- inbox items, subscriptions, and timers can outlive the current runtime
   session
-- terminal delivery does not automatically survive session boundaries just
-  because the inbox state does
-- if the original runtime/terminal disappears, items may keep accumulating in
-  the inbox while notifications stop reaching you
+- activation delivery does not automatically survive every session boundary
+  just because the inbox state does
+- if the original runtime/terminal or webhook trigger disappears, items may
+  keep accumulating in the inbox while notifications stop reaching you
 - if a later session should resume the same logical agent, re-register or
-  explicitly rebind that agent to the current terminal before assuming prompt
-  delivery is live again
+  explicitly rebind that agent to the current terminal or webhook target
+  before assuming prompt delivery is live again
 
 Lifecycle:
 
-1. register once per live terminal/runtime session
+1. register once per live runtime/session
 2. reuse broad shared sources
 3. add narrow task-scoped follows, subscriptions, or timers
 4. read inbox items in bounded batches and ack only the reviewed batch
@@ -117,6 +126,9 @@ Lifecycle:
 For PR and review workflows, prefer `follow` templates. They reuse shared
 sources, expand the source-specific filters, and attach cleanup behavior:
 
+For Holon, ensure `HOLON_EXTERNAL_TRIGGER_URL` is set or use `--webhook-url`
+when registering.
+
 ```bash
 agentinbox agent register
 agentinbox follow github pr --agent-id <agentId> --arg owner=holon-run --arg repo=agentinbox --arg number=87 --arg withCi=true
@@ -154,6 +166,33 @@ Use `follow` as the default path for GitHub repo, PR, and issue tracking. Drop
 to `source schema` plus `subscription add` only when you need a custom filter or
 the source has no follow template.
 
+Feishu/Lark follows require a UXC credential that can host the Feishu app
+connection. For bot mention workflows, prefer the global mention template so
+the user does not need to discover a group `chat_id` or bot `open_id` first:
+
+```bash
+agentinbox follow feishu mentions --agent-id <agentId> --config-json '{"uxcAuth":"feishu-default"}'
+```
+
+When `openId` is omitted, `AgentInbox` resolves the configured app bot's
+`open_id` through UXC before creating the subscription. Pass `--arg
+openId=<openId>` only when following mentions for a different user or bot.
+
+Use the chat-scoped templates when the task is explicitly limited to one group:
+
+```bash
+agentinbox follow feishu chat --agent-id <agentId> --arg chatId=<chatId> --config-json '{"uxcAuth":"feishu-default"}'
+agentinbox follow feishu mention --agent-id <agentId> --arg chatId=<chatId> --arg openId=<botOpenId> --config-json '{"uxcAuth":"feishu-default"}'
+```
+
+Feishu inbox items include `metadata.chatId`, `metadata.messageId`, and a
+`deliveryHandle`. Use `source invoke` for local context before replying:
+
+```bash
+agentinbox source invoke <sourceId> --operation get_message_context --input-json '{"messageId":"<messageId>","chatId":"<chatId>","windowBefore":5,"windowAfter":5}'
+agentinbox deliver invoke --handle-json '<deliveryHandle-json>' --operation send_text --input-json '{"text":"Acknowledged","uxcAuth":"feishu-default"}'
+```
+
 Advanced source/subscription commands:
 
 ```bash
@@ -206,6 +245,11 @@ agentinbox timer remove <scheduleId>
 
 Activation targets:
 
+`agent register` normally creates or refreshes the current runtime activation
+target automatically: a terminal target for terminal-backed runtimes, or a
+webhook target for Holon when a trigger URL is available. Add manual activation
+targets only when needed:
+
 ```bash
 agentinbox agent target list <agentId>
 agentinbox agent target add webhook <agentId> --url http://127.0.0.1:8787/webhook
@@ -220,13 +264,14 @@ instead of re-explaining the full architecture here.
 Do not start every task by checking daemon status; normal CLI commands should
 auto-connect or surface actionable errors. Use these checks after the first
 AgentInbox command fails, notifications stop arriving, or you suspect a stale
-terminal binding:
+terminal or webhook binding:
 
 ```bash
 agentinbox --version
 agentinbox daemon status
 agentinbox daemon start
 agentinbox agent register --agent-id <agentId> --force-rebind
+agentinbox agent register --agent-id <holonAgentId> --webhook-url <externalTriggerUrl> --force-rebind
 ```
 
 If GitHub-backed sources fail, verify UXC and imported GitHub auth only after