@holon-run/agentinbox 1.2.0 → 1.3.1

package/dist/src/cli.js

@@ -533,6 +533,27 @@ async function main() {
         await printRemote(client, `/agents/${encodeURIComponent(agentId)}/targets/${encodeURIComponent(targetId)}/resume`, {});
         return;
     }
+    if (command === "agent" && normalized[1] === "target" && normalized[2] === "update") {
+        const [agentId, targetId] = normalized.slice(3, 5);
+        if (!agentId || !targetId) {
+            throw new Error("usage: agentinbox agent target update <agentId> <targetId> [--url URL] [--activation-mode MODE] [--notify-lease-ms N] [--min-unacked-items N]");
+        }
+        const body = {};
+        const url = takeFlagValue(normalized, "--url");
+        if (url)
+            body.url = url;
+        const activationMode = takeFlagValue(normalized, "--activation-mode");
+        if (activationMode)
+            body.activationMode = activationMode;
+        const notifyLeaseMs = takeFlagValue(normalized, "--notify-lease-ms");
+        if (notifyLeaseMs)
+            body.notifyLeaseMs = parseOptionalNumber(notifyLeaseMs);
+        const minUnackedItems = takeFlagValue(normalized, "--min-unacked-items");
+        if (minUnackedItems)
+            body.minUnackedItems = parseOptionalNumber(minUnackedItems);
+        await printRemote(client, `/agents/${encodeURIComponent(agentId)}/targets/${encodeURIComponent(targetId)}`, body, "PATCH");
+        return;
+    }
     if (command === "subscription" && normalized[1] === "add") {
         const args = normalized.slice(2);
         const positionals = positionalArgs(args, [
@@ -1154,11 +1175,17 @@ function clientArgsForCommand(args) {
     if (isAgentTargetAddWebhookCommand(args)) {
         return withoutFlagValues(args, "--url");
     }
+    if (isAgentTargetUpdateCommand(args)) {
+        return withoutFlagValues(args, "--url");
+    }
     return args;
 }
 function isAgentTargetAddWebhookCommand(args) {
     return args[0] === "agent" && args[1] === "target" && args[2] === "add" && args[3] === "webhook";
 }
+function isAgentTargetUpdateCommand(args) {
+    return args[0] === "agent" && args[1] === "target" && args[2] === "update";
+}
 function withoutFlagValues(args, flag) {
     const filtered = [];
     for (let index = 0; index < args.length; index += 1) {
@@ -1514,6 +1541,7 @@ Usage:
   agentinbox agent target list <agentId> [--limit N]
   agentinbox agent target remove <agentId> <targetId>
   agentinbox agent target resume <agentId> <targetId>
+  agentinbox agent target update <agentId> <targetId> [--url URL] [--activation-mode MODE] [--notify-lease-ms N] [--min-unacked-items N]
 `,
         timer: `agentinbox timer
 

package/dist/src/http.js

@@ -1061,6 +1061,45 @@ function buildFastifyServer(service) {
             minUnackedItems: body.minUnackedItems ?? null,
         });
     });
+    app.patch("/agents/:agentId/targets/:targetId", {
+        schema: {
+            tags: ["agents"],
+            params: {
+                type: "object",
+                required: ["agentId", "targetId"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                    targetId: { type: "string", minLength: 1 },
+                },
+            },
+            body: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    url: { type: "string" },
+                    activationMode: { type: "string" },
+                    notifyLeaseMs: { type: "integer", minimum: 1 },
+                    minUnackedItems: { type: "integer", minimum: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        const body = request.body;
+        if (!body.url && body.activationMode === undefined && body.notifyLeaseMs === undefined && body.minUnackedItems === undefined) {
+            throw new Error("at least one of --url, --activation-mode, --notify-lease-ms, --min-unacked-items must be provided");
+        }
+        return service.updateWebhookActivationTarget(decodeURIComponent(params.agentId), decodeURIComponent(params.targetId), {
+            url: body.url,
+            activationMode: body.activationMode,
+            notifyLeaseMs: body.notifyLeaseMs ?? null,
+            minUnackedItems: body.minUnackedItems ?? null,
+        });
+    });
     app.delete("/agents/:agentId/targets/:targetId", {
         schema: {
             tags: ["agents"],

package/dist/src/service.js

@@ -17,6 +17,8 @@ const DEFAULT_ACTIVATION_MAX_ITEMS = 20;
 const DEFAULT_NOTIFY_LEASE_MS = 10 * 60 * 1000;
 const DEFAULT_NOTIFY_RETRY_MS = 5_000;
 const MAX_TERMINAL_DEFER_RETRY_MS = 5 * 60 * 1000;
+const MAX_WEBHOOK_RETRY_MS = 5 * 60 * 1000;
+const MAX_WEBHOOK_CONSECUTIVE_FAILURES = 12;
 const DEFAULT_ACKED_RETENTION_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_OFFLINE_AGENT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 const DEFAULT_GC_INTERVAL_MS = 60 * 1000;
@@ -774,6 +776,29 @@ class AgentInboxService {
         this.markAgentActive(agentId);
         return target;
     }
+    updateWebhookActivationTarget(agentId, targetId, input) {
+        this.getAgent(agentId);
+        const existing = this.getActivationTarget(targetId);
+        if (existing.agentId !== agentId) {
+            throw new Error(`activation target ${targetId} does not belong to agent ${agentId}`);
+        }
+        if (existing.kind !== "webhook") {
+            throw new Error(`activation target ${targetId} is not a webhook target`);
+        }
+        validateNotifyLeaseMs(input.notifyLeaseMs);
+        validateMinUnackedItems(input.minUnackedItems);
+        const mode = normalizeWebhookActivationMode(input.activationMode ?? existing.mode);
+        const now = (0, util_1.nowIso)();
+        const target = this.store.updateWebhookActivationTarget(targetId, {
+            url: input.url ?? existing.url,
+            mode,
+            notifyLeaseMs: input.notifyLeaseMs ?? existing.notifyLeaseMs,
+            minUnackedItems: input.minUnackedItems !== undefined ? input.minUnackedItems : existing.minUnackedItems ?? null,
+            updatedAt: now,
+            lastSeenAt: now,
+        });
+        return target;
+    }
     listActivationTargets(agentId, limit) {
         if (agentId) {
             this.getAgent(agentId);
@@ -2074,6 +2099,10 @@ class AgentInboxService {
                         : uniqueSorted(entries.map((entry) => entry.sourceId)),
                     entries: unackedItems,
                 });
+                // Permanent errors and max-retries-exceeded signal "offline":
+                if (dispatched === "offline") {
+                    this.store.deleteActivationDispatchState(buffer.agentId, buffer.targetId);
+                }
                 if (dispatched === "retryable_failure") {
                     if (state && state.status === "dirty" && state.leaseExpiresAt == null) {
                         this.store.upsertActivationDispatchState({
@@ -2253,10 +2282,17 @@ class AgentInboxService {
             return;
         }
         if (dispatched === "retryable_failure") {
+            let backoffMs = DEFAULT_NOTIFY_RETRY_MS;
+            if (target.kind === "webhook") {
+                const updatedTarget = this.getActivationTargetIfExists(agentId, targetId);
+                if (updatedTarget) {
+                    backoffMs = webhookDeferRetryMs(updatedTarget.consecutiveFailures);
+                }
+            }
             this.store.upsertActivationDispatchState({
                 ...state,
                 status: "dirty",
-                leaseExpiresAt: new Date(Date.now() + DEFAULT_NOTIFY_RETRY_MS).toISOString(),
+                leaseExpiresAt: new Date(Date.now() + backoffMs).toISOString(),
                 deferReason: null,
                 deferAttempts: 0,
                 firstDeferredAt: null,
@@ -2525,6 +2561,35 @@ class AgentInboxService {
                     return "offline";
                 }
             }
+            if (target.kind === "webhook") {
+                const statusCode = extractHttpStatus(error);
+                // 404 / 410: endpoint gone
+                // 409 / 422: expired or invalid webhook config
+                if (statusCode === 404 || statusCode === 410 || statusCode === 409 || statusCode === 422) {
+                    this.logger.info("activation.webhook_permanent_error", {
+                        agentId: input.agentId,
+                        targetId: target.targetId,
+                        statusCode,
+                        message,
+                    });
+                    this.markActivationTargetOffline(target.targetId, message);
+                    this.reconcileAgentStatus(target.agentId);
+                    return "offline";
+                }
+                // Max consecutive transient failures exceeded
+                if (target.consecutiveFailures + 1 >= MAX_WEBHOOK_CONSECUTIVE_FAILURES) {
+                    this.logger.info("activation.webhook_max_retries_exceeded", {
+                        agentId: input.agentId,
+                        targetId: target.targetId,
+                        consecutiveFailures: target.consecutiveFailures + 1,
+                        maxRetries: MAX_WEBHOOK_CONSECUTIVE_FAILURES,
+                    });
+                    this.markActivationTargetOffline(target.targetId, message);
+                    this.reconcileAgentStatus(target.agentId);
+                    return "offline";
+                }
+                // Transient error: fall through to markActivationTargetDispatchFailure
+            }
             this.markActivationTargetDispatchFailure(target.targetId, message);
             return "retryable_failure";
         }
@@ -3351,7 +3416,9 @@ class ActivationDispatcher {
                 body: JSON.stringify(activation),
             });
             if (!response.ok) {
-                throw new Error(`activation dispatch failed for ${targetUrl}: ${response.status}`);
+                const error = new Error(`activation dispatch failed for ${targetUrl}: ${response.status}`);
+                error.statusCode = response.status;
+                throw error;
             }
         }
         catch (error) {
@@ -3570,6 +3637,19 @@ function terminalDeferRetryMs(attempts) {
     const multiplier = 2 ** (normalizedAttempts - 1);
     return Math.min(DEFAULT_NOTIFY_RETRY_MS * multiplier, MAX_TERMINAL_DEFER_RETRY_MS);
 }
+function webhookDeferRetryMs(consecutiveFailures) {
+    const normalized = Math.max(1, consecutiveFailures);
+    const multiplier = 2 ** (normalized - 1);
+    return Math.min(DEFAULT_NOTIFY_RETRY_MS * multiplier, MAX_WEBHOOK_RETRY_MS);
+}
+function extractHttpStatus(error) {
+    if (error instanceof Error) {
+        const code = error.statusCode;
+        if (typeof code === "number")
+            return code;
+    }
+    return null;
+}
 function summarizeSourceEvent(sourceType, sourceKey, eventVariant) {
     if (sourceType === "github_repo_ci") {
         const parts = eventVariant.split(".");

package/dist/src/sources/feishu.js

@@ -14,11 +14,9 @@ const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const node_os_1 = require("node:os");
 const node_util_1 = require("node:util");
 exports.FEISHU_OPENAPI_ENDPOINT = "https://open.feishu.cn/open-apis";
 exports.FEISHU_IM_SCHEMA_URL = "https://raw.githubusercontent.com/holon-run/uxc/main/skills/feishu-openapi-skill/references/feishu-im.openapi.json";
-const FEISHU_BOT_SCHEMA_FILE = (0, node_path_1.join)((0, node_os_1.tmpdir)(), "agentinbox-feishu-bot.openapi.json");
 exports.DEFAULT_FEISHU_EVENT_TYPES = ["im.message.receive_v1"];
 const DEFAULT_CONTEXT_BOUND_SECONDS = 7 * 24 * 60 * 60;
 const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
@@ -131,10 +129,8 @@ class FeishuUxcClient {
             operation: "get:/bot/v3/info",
             payload: {},
             options: {
-                auth: input.auth,
-                schema_url: ensureFeishuBotSchemaFile(),
-                refresh_schema: true,
-                no_cache: true,
+                auth: input.auth ?? undefined,
+                schema_url: exports.FEISHU_IM_SCHEMA_URL,
             },
         });
         const openId = findStringField(response.data, "open_id");
@@ -1873,50 +1869,3 @@ function asStringArray(value) {
         .map((item) => asString(item))
         .filter((item) => Boolean(item));
 }
-function ensureFeishuBotSchemaFile() {
-    const body = JSON.stringify(FEISHU_BOT_OPENAPI_SCHEMA);
-    (0, node_fs_1.writeFileSync)(FEISHU_BOT_SCHEMA_FILE, body, "utf8");
-    return FEISHU_BOT_SCHEMA_FILE;
-}
-const FEISHU_BOT_OPENAPI_SCHEMA = {
-    openapi: "3.0.3",
-    info: {
-        title: "Feishu Bot Info",
-        version: "1.0.0",
-    },
-    servers: [
-        {
-            url: exports.FEISHU_OPENAPI_ENDPOINT,
-        },
-    ],
-    // Feishu's docs site does not currently expose this as a stable
-    // machine-readable OpenAPI document to UXC, so keep the tiny operation
-    // schema needed for bot self-identification close to the adapter.
-    paths: {
-        "/bot/v3/info": {
-            get: {
-                operationId: "get:/bot/v3/info",
-                summary: "Get bot information for the current app",
-                responses: {
-                    "200": {
-                        description: "OK",
-                    },
-                },
-                security: [
-                    {
-                        bearerAuth: [],
-                    },
-                ],
-            },
-        },
-    },
-    components: {
-        securitySchemes: {
-            bearerAuth: {
-                type: "http",
-                scheme: "bearer",
-                bearerFormat: "tenant_access_token",
-            },
-        },
-    },
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {

package/skills/agentinbox/SKILL.md

@@ -193,6 +193,43 @@ agentinbox source invoke <sourceId> --operation get_message_context --input-json
 agentinbox deliver invoke --handle-json '<deliveryHandle-json>' --operation send_text --input-json '{"text":"Acknowledged","uxcAuth":"feishu-default"}'
 ```
 
+Feishu messages may carry files, images, or cloud document links. List the
+attachments first and then save them locally:
+
+```bash
+# List attachments for a message
+agentinbox source invoke <sourceId> \
+  --operation list_message_attachments \
+  --input-json '{"messageId":"<messageId>"}'
+
+# Save one attachment by messageId + attachmentId
+agentinbox source invoke <sourceId> \
+  --operation save_attachment \
+  --input-json '{"messageId":"<messageId>","attachmentId":"<attachmentId>","outputDir":"/tmp/agentinbox-feishu"}'
+
+# Save with explicit output path and identity
+agentinbox source invoke <sourceId> \
+  --operation save_attachment \
+  --input-json '{"messageId":"<messageId>","attachmentId":"<attachmentId>","outputPath":"/tmp/report.pdf","identity":"bot"}'
+```
+
+Output formats by attachment kind:
+
+| Kind | Default | `format` options |
+|---|---|---|
+| `image` / `file` | original binary | `"original"` only |
+| `doc` / `docx` / `wiki` | `.md` (Markdown) | N/A |
+| `sheet` | `.xlsx` | `"csv"` (requires `subId`) |
+| `bitable` / `base` | `.base` | `"csv"` (requires `subId`) |
+| `drive_file` | original file | `"original"` only |
+
+Optional `save_attachment` parameters: `outputPath`, `outputDir`, `fileName`,
+`format`, `subId`, `identity` (`"user"` or `"bot"`), `overwrite`.
+
+Rich text and file replies are available through `send_post`, `send_file`,
+and `send_file_from_path` delivery operations. Use `deliver actions` to
+inspect available schemas.
+
 Advanced source/subscription commands:
 
 ```bash