@holon-run/agentinbox 1.0.0-beta.5 → 1.0.1

package/README.md

@@ -55,18 +55,19 @@ manually or relying on the agent runtime to expose its own notification API.
 
 ## Status
 
-`AgentInbox` is public beta software.
+`AgentInbox` is on the stable v1 release line.
 
 - the local control plane, daemon model, inbox model, and activation targets
   are implemented
 - GitHub repo, GitHub repo CI, Feishu bot, and local event ingress source
   adapters are implemented
-- filtering and source model are still evolving
+- filtering and source breadth are still evolving
 - first-run onboarding is currently skill-first rather than wizard-first
 
-## v1.0.0 Beta Upgrade Notes
+## v1 Upgrade Notes
 
-`v1.0.0-beta.0` was the first release on the final v1 storage and API boundary.
+`v1.0.0-beta.0` was the first release on the final v1 storage and API boundary,
+and `1.0.0` keeps that same boundary.
 
 - pre-v1 local databases are archived and replaced with a fresh v1 database
 - old local state is not imported into the new v1 database

package/dist/src/cli.js

@@ -355,9 +355,31 @@ async function main() {
         return;
     }
     if (command === "agent" && normalized[1] === "register") {
+        const agentId = takeFlagValue(normalized, "--agent-id") ?? undefined;
+        const notifyLeaseMs = parseOptionalNumber(takeFlagValue(normalized, "--notify-lease-ms")) ?? undefined;
+        const minUnackedItems = parseOptionalNumber(takeFlagValue(normalized, "--min-unacked-items")) ?? undefined;
+        const webhookUrl = takeFlagValue(normalized, "--webhook-url");
+        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 webhookNotifyLeaseMs = parseOptionalNumber(takeFlagValue(normalized, "--webhook-notify-lease-ms")) ?? notifyLeaseMs;
+            const webhookMinUnackedItems = parseOptionalNumber(takeFlagValue(normalized, "--webhook-min-unacked-items")) ?? minUnackedItems;
+            await printRemote(client, "/agents", {
+                agentId,
+                forceRebind: normalized.includes("--force-rebind"),
+                webhook: {
+                    url: webhookUrl,
+                    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: takeFlagValue(normalized, "--agent-id") ?? undefined,
+            agentId,
             forceRebind: normalized.includes("--force-rebind"),
             backend: detected.backend,
             runtimeKind: detected.runtimeKind,
@@ -367,8 +389,8 @@ async function main() {
             tty: detected.tty ?? undefined,
             termProgram: detected.termProgram ?? undefined,
             itermSessionId: detected.itermSessionId ?? undefined,
-            notifyLeaseMs: parseOptionalNumber(takeFlagValue(normalized, "--notify-lease-ms")) ?? undefined,
-            minUnackedItems: parseOptionalNumber(takeFlagValue(normalized, "--min-unacked-items")) ?? undefined,
+            notifyLeaseMs,
+            minUnackedItems,
         });
         return;
     }
@@ -1297,6 +1319,7 @@ 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 current
   agentinbox agent show <agentId>

package/dist/src/http.js

@@ -772,11 +772,34 @@ function buildFastifyServer(service) {
             body: {
                 type: "object",
                 additionalProperties: false,
-                required: ["backend"],
+                oneOf: [
+                    {
+                        required: ["backend"],
+                        properties: {
+                            backend: { type: "string", enum: ["tmux", "iterm2"] },
+                        },
+                    },
+                    {
+                        required: ["agentId", "webhook"],
+                        properties: {
+                            webhook: {
+                                type: "object",
+                                additionalProperties: false,
+                                required: ["url"],
+                                properties: {
+                                    url: { type: "string", minLength: 1 },
+                                    activationMode: { type: "string", enum: ["activation_only", "activation_with_items"] },
+                                    notifyLeaseMs: { type: "integer", minimum: 1 },
+                                    minUnackedItems: { type: "integer", minimum: 1 },
+                                },
+                            },
+                        },
+                    },
+                ],
                 properties: {
                     agentId: { type: "string" },
                     forceRebind: { type: "boolean" },
-                    backend: { type: "string", minLength: 1 },
+                    backend: { type: "string", enum: ["tmux", "iterm2"] },
                     runtimeKind: { type: "string" },
                     runtimeSessionId: { type: "string" },
                     runtimePid: { type: "integer", minimum: 1 },
@@ -786,6 +809,17 @@ function buildFastifyServer(service) {
                     itermSessionId: { type: "string" },
                     notifyLeaseMs: { type: "integer", minimum: 1 },
                     minUnackedItems: { type: "integer", minimum: 1 },
+                    webhook: {
+                        type: "object",
+                        additionalProperties: false,
+                        required: ["url"],
+                        properties: {
+                            url: { type: "string", minLength: 1 },
+                            activationMode: { type: "string", enum: ["activation_only", "activation_with_items"] },
+                            notifyLeaseMs: { type: "integer", minimum: 1 },
+                            minUnackedItems: { type: "integer", minimum: 1 },
+                        },
+                    },
                 },
             },
             response: {
@@ -795,10 +829,11 @@ function buildFastifyServer(service) {
         },
     }, async (request) => {
         const body = request.body;
+        const webhookBody = body.webhook;
         return service.registerAgent({
             agentId: optionalString(body.agentId) ?? null,
             forceRebind: body.forceRebind === true,
-            backend: String(body.backend),
+            backend: optionalString(body.backend),
             runtimeKind: optionalString(body.runtimeKind),
             runtimeSessionId: optionalString(body.runtimeSessionId),
             runtimePid: typeof body.runtimePid === "number" ? body.runtimePid : null,
@@ -809,6 +844,14 @@ function buildFastifyServer(service) {
             itermSessionId: optionalString(body.itermSessionId),
             notifyLeaseMs: typeof body.notifyLeaseMs === "number" ? body.notifyLeaseMs : null,
             minUnackedItems: typeof body.minUnackedItems === "number" ? body.minUnackedItems : null,
+            webhook: webhookBody
+                ? {
+                    url: String(webhookBody.url),
+                    activationMode: optionalString(webhookBody.activationMode),
+                    notifyLeaseMs: typeof webhookBody.notifyLeaseMs === "number" ? webhookBody.notifyLeaseMs : null,
+                    minUnackedItems: typeof webhookBody.minUnackedItems === "number" ? webhookBody.minUnackedItems : null,
+                }
+                : null,
         });
     });
     app.get("/agents/:agentId", {
@@ -1747,6 +1790,8 @@ function isBadRequestError(message) {
         message.startsWith("expected boolean") ||
         message.startsWith("expected integer") ||
         message.startsWith("expected positive integer") ||
+        message.startsWith("webhook agent registration requires") ||
+        message.startsWith("agent registration requires either") ||
         message.startsWith("notifyLeaseMs must be a positive integer") ||
         message.startsWith("minUnackedItems must be a positive integer") ||
         message.startsWith("invalid webhook activation target") ||

package/dist/src/service.js

@@ -516,18 +516,23 @@ class AgentInboxService {
     registerAgent(input) {
         validateNotifyLeaseMs(input.notifyLeaseMs);
         validateMinUnackedItems(input.minUnackedItems);
-        validateTerminalRegistration(input);
+        validateRegisterAgentInput(input);
+        const webhookInput = input.webhook ?? null;
         const runtimeKind = input.runtimeKind ?? "unknown";
-        const agentId = input.agentId ?? this.resolveAutoAgentId({
-            runtimeKind,
-            runtimeSessionId: input.runtimeSessionId ?? null,
-            backend: input.backend,
-            tmuxPaneId: input.tmuxPaneId ?? null,
-            itermSessionId: input.itermSessionId ?? null,
-            tty: input.tty ?? null,
-        });
+        const agentId = webhookInput
+            ? input.agentId
+            : input.agentId ?? this.resolveAutoAgentId({
+                runtimeKind,
+                runtimeSessionId: input.runtimeSessionId ?? null,
+                backend: input.backend,
+                tmuxPaneId: input.tmuxPaneId ?? null,
+                itermSessionId: input.itermSessionId ?? null,
+                tty: input.tty ?? null,
+            });
         const now = (0, util_1.nowIso)();
-        this.handleAgentRegistrationConflicts(agentId, input);
+        if (!webhookInput) {
+            this.handleAgentRegistrationConflicts(agentId, input);
+        }
         const existingAgent = this.store.getAgent(agentId);
         const agent = existingAgent
             ? this.store.updateAgent(agentId, {
@@ -552,11 +557,21 @@ class AgentInboxService {
                 this.store.insertAgent(created);
                 return created;
             })();
-        const terminalTarget = this.upsertTerminalActivationTarget(agent.agentId, input, now);
+        let terminalTarget = null;
+        let webhookTarget = null;
+        if (webhookInput) {
+            webhookTarget = this.upsertWebhookActivationTarget(agent.agentId, webhookInput, now);
+            this.removeTerminalActivationTargets(agent.agentId);
+        }
+        else {
+            terminalTarget = this.upsertTerminalActivationTarget(agent.agentId, input, now);
+        }
         const inbox = this.ensureInboxForAgent(agent.agentId);
         return {
             agent,
             terminalTarget,
+            webhookTarget,
+            activationChannel: webhookTarget ? "webhook" : terminalTarget ? "terminal" : null,
             inbox,
         };
     }
@@ -1197,7 +1212,7 @@ class AgentInboxService {
             subscriptionIds: [],
         });
         this.notifyInboxWatchers(agentId, [entry]);
-        const targets = this.store.listActivationTargetsForAgent(agentId).filter((target) => target.status === "active");
+        const targets = this.listEffectiveActiveActivationTargets(agentId);
         for (const target of targets) {
             this.enqueueActivationTarget(target, {
                 agentId,
@@ -1466,7 +1481,7 @@ class AgentInboxService {
                 limit: DEFAULT_SUBSCRIPTION_POLL_LIMIT,
             });
             const inbox = this.ensureInboxForAgent(subscription.agentId);
-            const targets = this.store.listActivationTargetsForAgent(subscription.agentId).filter((target) => target.status === "active");
+            const targets = this.listEffectiveActiveActivationTargets(subscription.agentId);
             let matched = 0;
             let inboxItemsCreated = 0;
             let lastProcessedOffset = null;
@@ -1796,6 +1811,12 @@ class AgentInboxService {
         throw new Error("unable to derive a unique agentId from terminal context");
     }
     handleAgentRegistrationConflicts(agentId, input) {
+        const activeWebhookTarget = this.store
+            .listActivationTargetsForAgent(agentId)
+            .find((target) => target.kind === "webhook" && target.status === "active");
+        if (activeWebhookTarget) {
+            throw new Error(`agent register conflict: agent ${agentId} already has active webhook target ${activeWebhookTarget.targetId}; terminal registration is disabled while webhook is active`);
+        }
         const currentTarget = findExistingTerminalActivationTarget(this.store, input);
         if (currentTarget && currentTarget.agentId !== agentId) {
             if (!input.forceRebind) {
@@ -1817,6 +1838,34 @@ class AgentInboxService {
             }
         }
     }
+    upsertWebhookActivationTarget(agentId, input, now) {
+        validateNotifyLeaseMs(input.notifyLeaseMs);
+        validateMinUnackedItems(input.minUnackedItems);
+        const mode = normalizeWebhookActivationMode(input.activationMode);
+        const targets = this.store
+            .listActivationTargetsForAgent(agentId)
+            .filter((target) => target.kind === "webhook");
+        const matching = targets.find((target) => target.url === input.url);
+        const existing = matching ?? targets[0] ?? null;
+        if (existing) {
+            const target = this.store.updateWebhookActivationTarget(existing.targetId, {
+                url: input.url,
+                mode,
+                notifyLeaseMs: input.notifyLeaseMs ?? existing.notifyLeaseMs,
+                minUnackedItems: input.minUnackedItems ?? existing.minUnackedItems ?? null,
+                updatedAt: now,
+                lastSeenAt: now,
+            });
+            for (const duplicate of targets) {
+                if (duplicate.targetId !== target.targetId) {
+                    this.store.deleteActivationTarget(agentId, duplicate.targetId);
+                }
+            }
+            this.markAgentActive(agentId);
+            return target;
+        }
+        return this.addWebhookActivationTarget(agentId, input);
+    }
     upsertTerminalActivationTarget(agentId, input, now) {
         const existing = findExistingTerminalActivationTarget(this.store, input);
         if (existing) {
@@ -1872,6 +1921,21 @@ class AgentInboxService {
         this.markAgentActive(agentId);
         return target;
     }
+    removeTerminalActivationTargets(agentId) {
+        const targets = this.store
+            .listActivationTargetsForAgent(agentId)
+            .filter((target) => target.kind === "terminal");
+        for (const target of targets) {
+            this.store.deleteActivationTarget(agentId, target.targetId);
+        }
+    }
+    listEffectiveActiveActivationTargets(agentId) {
+        const targets = this.store.listActivationTargetsForAgent(agentId).filter((target) => target.status === "active");
+        return effectiveActiveTargets(targets);
+    }
+    isEffectiveActiveTarget(agentId, targetId) {
+        return this.listEffectiveActiveActivationTargets(agentId).some((target) => target.targetId === targetId);
+    }
     enqueueActivationTarget(target, input) {
         const key = notificationBufferKey(target.agentId, target.targetId);
         let buffer = this.notificationBuffers.get(key);
@@ -2108,6 +2172,10 @@ class AgentInboxService {
             this.store.deleteActivationDispatchState(agentId, targetId);
             return;
         }
+        if (!this.isEffectiveActiveTarget(agentId, targetId)) {
+            this.store.deleteActivationDispatchState(agentId, targetId);
+            return;
+        }
         const inbox = this.ensureInboxForAgent(agentId);
         const unacked = this.store.listInboxEntries(inbox.inboxId, { includeAcked: false }).length;
         if (unacked === 0) {
@@ -2181,6 +2249,15 @@ class AgentInboxService {
         if (target.status === "offline") {
             return "offline";
         }
+        if (!this.isEffectiveActiveTarget(input.agentId, input.targetId)) {
+            this.logger.debug("activation.dispatch_suppressed", {
+                agentId: input.agentId,
+                targetId: target.targetId,
+                reason: "non_effective_target",
+                targetKind: target.kind,
+            });
+            return "suppressed";
+        }
         const state = this.store.getActivationDispatchState(input.agentId, input.targetId);
         const inbox = this.ensureInboxForAgent(input.agentId);
         const summary = summarizeActivation(inbox.inboxId, input.newItemCount, input.summary);
@@ -2781,7 +2858,7 @@ class AgentInboxService {
                     continue;
                 }
                 this.notifyInboxWatchers(inbox.ownerAgentId, [entry]);
-                const targets = this.store.listActivationTargetsForAgent(inbox.ownerAgentId).filter((target) => target.status === "active");
+                const targets = this.listEffectiveActiveActivationTargets(inbox.ownerAgentId);
                 for (const target of targets) {
                     this.enqueueActivationTarget(target, {
                         agentId: inbox.ownerAgentId,
@@ -3259,7 +3336,13 @@ class ActivationDispatcher {
     }
 }
 exports.ActivationDispatcher = ActivationDispatcher;
-function validateTerminalRegistration(input) {
+function validateRegisterAgentInput(input) {
+    if (input.webhook) {
+        if (!input.agentId) {
+            throw new Error("webhook agent registration requires agentId");
+        }
+        return;
+    }
     if (input.backend === "tmux") {
         if (!input.tmuxPaneId) {
             throw new Error("tmux agent registration requires tmuxPaneId");
@@ -3272,7 +3355,10 @@ function validateTerminalRegistration(input) {
         }
         return;
     }
-    throw new Error(`unsupported terminal backend: ${String(input.backend)}`);
+    if (input.backend) {
+        throw new Error(`unsupported terminal backend: ${input.backend}`);
+    }
+    throw new Error("agent registration requires either a terminal backend or webhook");
 }
 function validateNotifyLeaseMs(value) {
     if (value == null) {
@@ -3360,6 +3446,9 @@ function normalizeWebhookActivationMode(mode) {
     return resolved;
 }
 function findExistingTerminalActivationTarget(store, input) {
+    if (!input.backend) {
+        return null;
+    }
     if (input.runtimeSessionId) {
         const target = store.getTerminalActivationTargetByRuntimeSession(input.runtimeKind ?? "unknown", input.runtimeSessionId);
         if (target) {
@@ -3379,6 +3468,13 @@ function findExistingTerminalActivationTarget(store, input) {
     }
     return null;
 }
+function effectiveActiveTargets(targets) {
+    const activeWebhookTargets = targets.filter((target) => target.kind === "webhook" && target.status === "active");
+    if (activeWebhookTargets.length > 0) {
+        return activeWebhookTargets;
+    }
+    return targets.filter((target) => target.status === "active");
+}
 function isSameTerminalIdentity(target, input) {
     if (input.runtimeSessionId && target.runtimeKind === (input.runtimeKind ?? "unknown") && target.runtimeSessionId === input.runtimeSessionId) {
         return true;

package/dist/src/store.js

@@ -777,6 +777,28 @@ class AgentInboxStore {
         }
         return target;
     }
+    updateWebhookActivationTarget(targetId, input) {
+        this.db.run(`
+      update activation_targets
+      set kind = 'webhook', status = 'active', offline_since = null, last_error = null, consecutive_failures = 0,
+          mode = ?, notify_lease_ms = ?, min_unacked_items = ?, url = ?, updated_at = ?, last_seen_at = ?
+      where target_id = ? and kind = 'webhook'
+    `, [
+            input.mode,
+            input.notifyLeaseMs,
+            input.minUnackedItems,
+            input.url,
+            input.updatedAt,
+            input.lastSeenAt,
+            targetId,
+        ]);
+        this.persist();
+        const target = this.getActivationTarget(targetId);
+        if (!target || target.kind !== "webhook") {
+            throw new Error(`unknown webhook activation target: ${targetId}`);
+        }
+        return target;
+    }
     updateActivationTargetRuntime(targetId, input) {
         const current = this.getActivationTarget(targetId);
         if (!current) {

package/package.json

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