@holon-run/agentinbox 1.4.1 → 1.5.0

package/dist/src/adapters.js

@@ -39,7 +39,7 @@ class AdapterRegistry {
     localEventSource = new NoopSourceAdapter("local_event");
     remoteSource;
     defaultDelivery = new NoopDeliveryAdapter();
-    feishuDelivery = new feishu_1.FeishuDeliveryAdapter();
+    feishuDelivery;
     githubDelivery = new github_1.GithubDeliveryAdapter();
     telegramDelivery;
     homeDir;
@@ -49,6 +49,7 @@ class AdapterRegistry {
         this.remoteModuleRegistry = options?.remoteModuleRegistry ?? new remote_modules_1.RemoteSourceModuleRegistry({
             githubCallClient: options?.githubCallClient,
         });
+        this.feishuDelivery = new feishu_1.FeishuDeliveryAdapter(options?.feishuClient);
         this.telegramDelivery = new telegram_1.TelegramDeliveryAdapter(options?.telegramClient);
         this.remoteSource = new remote_1.RemoteSourceRuntime(store, appendSourceEvent, {
             homeDir: this.homeDir,

package/dist/src/cli.js

@@ -22,9 +22,10 @@ const util_1 = require("./util");
 async function main() {
     const rawArgs = process.argv.slice(2);
     const detectedArgs = normalizeHelpArgs(rawArgs);
-    const normalized = shouldTreatJsonFlagAsNoop(detectedArgs)
+    const jsonStripped = shouldTreatJsonFlagAsNoop(detectedArgs)
         ? stripNoopJsonFlag(detectedArgs)
         : detectedArgs;
+    const normalized = normalizeAliases(jsonStripped);
     const shell = parseCommanderShell(normalized);
     const command = normalized[0];
     if (!command || command === "help" || command === "--help" || command === "-h") {
@@ -360,14 +361,23 @@ async function main() {
     if (command === "source" && normalized[1] === "invoke") {
         const sourceId = normalized[2];
         const operation = takeFlagValue(normalized, "--operation");
-        const inputJson = takeFlagValue(normalized, "--input-json");
+        const inputJson = takeFlagValue(normalized, "--input-json") ?? takeFlagValue(normalized, "--input");
         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"),
-        });
+        try {
+            await printRemote(client, `/sources/${encodeURIComponent(sourceId)}/invoke`, {
+                operation,
+                input: (0, util_1.parseJsonArg)(inputJson, "--input-json"),
+            });
+        }
+        catch (error) {
+            const suggestion = await suggestSourceOperation(client, sourceId, operation);
+            if (suggestion) {
+                throw new Error(`${error instanceof Error ? error.message : String(error)}\nDid you mean: --operation ${suggestion}?`);
+            }
+            throw error;
+        }
         return;
     }
     if (command === "source" && normalized[1] === "poll") {
@@ -731,9 +741,9 @@ async function main() {
     }
     if (command === "inbox" && normalized[1] === "read") {
         const args = normalized.slice(2);
-        const allowedFlags = ["--agent-id", "--after-entry", "--include-acked", "--limit"];
+        const allowedFlags = ["--agent-id", "--after-entry", "--include-acked", "--limit", "--full"];
         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]");
+            throw new Error("usage: agentinbox inbox read [--agent-id ID] [--after-entry ID] [--include-acked] [--limit N] [--full]");
         }
         const selection = await selectAgentForCommand(client, {
             explicitAgentId: takeFlagValue(normalized, "--agent-id"),
@@ -745,7 +755,11 @@ async function main() {
             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)));
+        const data = response.data;
+        if (!hasFlag(normalized, "--full") && Array.isArray(data.entries)) {
+            data.entries = data.entries.map(compactInboxEntry);
+        }
+        console.log((0, util_1.jsonResponse)(withCommandMetadata(data, selection)));
         return;
     }
     if (command === "inbox" && normalized[1] === "send") {
@@ -768,8 +782,9 @@ async function main() {
     if (command === "inbox" && normalized[1] === "watch") {
         const args = normalized.slice(2);
         if (positionalArgs(args, ["--agent-id", "--after-entry", "--heartbeat-ms"]).length > 0) {
-            throw new Error("usage: agentinbox inbox watch [--agent-id ID] [--after-entry ID] [--include-acked] [--heartbeat-ms N]");
+            throw new Error("usage: agentinbox inbox watch [--agent-id ID] [--after-entry ID] [--include-acked] [--heartbeat-ms N] [--full]");
         }
+        const fullMode = hasFlag(normalized, "--full");
         const selection = await selectAgentForCommand(client, {
             explicitAgentId: takeFlagValue(normalized, "--agent-id"),
             autoRegister: true,
@@ -788,18 +803,22 @@ async function main() {
             if (event.event !== "items") {
                 continue;
             }
-            console.log((0, util_1.jsonResponse)(event));
+            const output = fullMode ? event : {
+                ...event,
+                entries: event.entries.map((e) => compactInboxEntry(e)),
+            };
+            console.log((0, util_1.jsonResponse)(output));
         }
         return;
     }
     if (command === "inbox" && normalized[1] === "ack") {
         const args = normalized.slice(2);
         const itemId = takeFlagValue(normalized, "--entry-id") ?? takeFlagValue(normalized, "--entry");
-        const throughEntryId = takeFlagValue(normalized, "--through");
+        const throughEntryId = takeFlagValue(normalized, "--through") ?? takeFlagValue(normalized, "--through-entry-id");
         const ackAll = hasFlag(normalized, "--all");
         const modeCount = Number(Boolean(itemId)) + Number(Boolean(throughEntryId)) + Number(ackAll);
-        if (positionalArgs(args, ["--agent-id", "--entry", "--entry-id", "--through"]).length > 0 || modeCount !== 1) {
-            throw new Error("usage: agentinbox inbox ack [--agent-id ID] (--through <entryId> | --entry <entryId> | --entry-id <entryId> | --all)");
+        if (positionalArgs(args, ["--agent-id", "--entry", "--entry-id", "--through", "--through-entry-id"]).length > 0 || modeCount !== 1) {
+            throw new Error("usage: agentinbox inbox ack [--agent-id ID] (--through <entryId> | --through-entry-id <entryId> | --entry <entryId> | --entry-id <entryId> | --all)");
         }
         const selection = await selectAgentForCommand(client, {
             explicitAgentId: takeFlagValue(normalized, "--agent-id"),
@@ -893,11 +912,11 @@ async function main() {
         const targetRef = takeFlagValue(normalized, "--target");
         const handleJson = takeFlagValue(normalized, "--handle-json");
         const operation = takeFlagValue(normalized, "--operation");
-        const inputJson = takeFlagValue(normalized, "--input-json");
+        const inputJson = takeFlagValue(normalized, "--input-json") ?? takeFlagValue(normalized, "--input");
         if (!operation || !inputJson || (!handleJson && (!provider || !surface || !targetRef))) {
             throw new Error("usage: agentinbox deliver invoke (--handle-json JSON | --provider PROVIDER --surface SURFACE --target TARGET) --operation NAME --input-json JSON [--source-id SOURCE_ID]");
         }
-        await printRemote(client, "/deliveries/invoke", handleJson
+        const invokeBody = handleJson
             ? {
                 sourceId: takeFlagValue(normalized, "--source-id") ?? undefined,
                 deliveryHandle: (0, util_1.parseJsonArg)(handleJson),
@@ -913,7 +932,17 @@ async function main() {
                 replyMode: takeFlagValue(normalized, "--reply-mode") ?? undefined,
                 operation,
                 input: (0, util_1.parseJsonArg)(inputJson, "--input-json"),
-            });
+            };
+        try {
+            await printRemote(client, "/deliveries/invoke", invokeBody);
+        }
+        catch (error) {
+            const suggestion = await suggestDeliveryOperation(client, invokeBody);
+            if (suggestion) {
+                throw new Error(`${error instanceof Error ? error.message : String(error)}\nDid you mean: --operation ${suggestion}?`);
+            }
+            throw error;
+        }
         return;
     }
     if (command === "status") {
@@ -924,6 +953,10 @@ async function main() {
         await printRemote(client, "/gc", {});
         return;
     }
+    const suggestion = suggestUnknownCommand(normalized);
+    if (suggestion) {
+        throw new Error(`unknown command: ${normalized.join(" ")}\nDid you mean: ${suggestion}?`);
+    }
     throw new Error(`unknown command: ${normalized.join(" ")}`);
 }
 const COMMAND_SHELL_SPECS = [
@@ -1258,6 +1291,127 @@ function normalizeHelpArgs(args) {
     }
     return [args[1], "--help"];
 }
+function normalizeAliases(args) {
+    // Top-level command aliases
+    if (args[0] === "delivery") {
+        return ["deliver", ...args.slice(1)];
+    }
+    // Top-level shortcuts -> inbox subcommands
+    if (args[0] === "entries") {
+        return ["inbox", "read", ...args.slice(1)];
+    }
+    if (args[0] === "ack") {
+        return ["inbox", "ack", ...args.slice(1)];
+    }
+    // inbox subcommand aliases: get/entries/peek -> read
+    if (args[0] === "inbox" && (args[1] === "get" || args[1] === "entries" || args[1] === "peek")) {
+        return [args[0], "read", ...args.slice(2)];
+    }
+    return args;
+}
+function levenshtein(a, b) {
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++)
+        matrix[i] = [i];
+    for (let j = 0; j <= a.length; j++)
+        matrix[0][j] = j;
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            const cost = a[j - 1] === b[i - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[b.length][a.length];
+}
+function closestMatch(input, candidates) {
+    if (candidates.length === 0)
+        return null;
+    let best = null;
+    let bestDistance = Infinity;
+    for (const candidate of candidates) {
+        const distance = levenshtein(input.toLowerCase(), candidate.toLowerCase());
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    // Only suggest if the distance is reasonable (at most half the input length)
+    if (best && bestDistance <= Math.max(1, Math.floor(input.length / 2))) {
+        return best;
+    }
+    return null;
+}
+const KNOWN_SUBCOMMANDS = {
+    deliver: ["send", "actions", "invoke"],
+    inbox: ["list", "show", "read", "send", "watch", "ack", "policy", "compact"],
+    daemon: ["start", "stop", "status"],
+    host: ["add", "list", "show", "schema"],
+    stream: ["add", "list", "show", "update", "remove", "pause", "resume", "schema", "poll", "event"],
+    source: ["add", "list", "show", "update", "remove", "pause", "resume", "schema", "actions", "invoke", "poll", "event"],
+    agent: ["register", "list", "current", "show", "remove", "resume", "target"],
+    subscription: ["add", "list", "show", "remove", "poll", "lag", "reset"],
+    timer: ["add", "list", "pause", "resume", "remove"],
+};
+function suggestUnknownCommand(args) {
+    const command = args[0];
+    if (!command)
+        return null;
+    // Check top-level command suggestions
+    const topCommands = COMMAND_SHELL_SPECS.map((s) => s.name);
+    const topSuggestion = closestMatch(command, topCommands);
+    if (topSuggestion && topSuggestion !== command) {
+        return topSuggestion;
+    }
+    // Check subcommand suggestions
+    if (args[1]) {
+        const subcommands = KNOWN_SUBCOMMANDS[command];
+        if (subcommands) {
+            const subSuggestion = closestMatch(args[1], subcommands);
+            if (subSuggestion) {
+                return `${command} ${subSuggestion}`;
+            }
+        }
+    }
+    return null;
+}
+async function suggestDeliveryOperation(client, invokeBody) {
+    try {
+        const actionsBody = {};
+        if (invokeBody.deliveryHandle) {
+            actionsBody.deliveryHandle = invokeBody.deliveryHandle;
+        }
+        else {
+            if (invokeBody.sourceId)
+                actionsBody.sourceId = invokeBody.sourceId;
+            if (invokeBody.provider)
+                actionsBody.provider = invokeBody.provider;
+            if (invokeBody.surface)
+                actionsBody.surface = invokeBody.surface;
+            if (invokeBody.targetRef)
+                actionsBody.targetRef = invokeBody.targetRef;
+            if (invokeBody.threadRef)
+                actionsBody.threadRef = invokeBody.threadRef;
+            if (invokeBody.replyMode)
+                actionsBody.replyMode = invokeBody.replyMode;
+        }
+        const response = await requestRemote(client, "/deliveries/actions", actionsBody, "POST");
+        const operationNames = response.data.operations.map((op) => op.name);
+        return closestMatch(String(invokeBody.operation), operationNames);
+    }
+    catch {
+        return null;
+    }
+}
+async function suggestSourceOperation(client, sourceId, operation) {
+    try {
+        const response = await requestRemote(client, `/sources/${encodeURIComponent(sourceId)}/actions`, undefined, "GET");
+        const operationNames = response.data.operations.map((op) => op.name);
+        return closestMatch(operation, operationNames);
+    }
+    catch {
+        return null;
+    }
+}
 function stripNoopJsonFlag(args) {
     return args.filter((arg) => arg !== "--json");
 }
@@ -1380,6 +1534,34 @@ function withCommandMetadata(data, selection) {
         ...(selection.warnings.length > 0 ? { warnings: selection.warnings } : {}),
     };
 }
+const COMPACT_ENTRY_FIELDS = [
+    "entryId", "kind", "summary", "eventVariant",
+    "occurredAt", "ackedAt", "deliveryHandle", "metadata",
+];
+const COMPACT_DIGEST_FIELDS = [
+    "threadId", "revision", "groupKey", "resourceRef", "eventFamily",
+];
+/**
+ * Strip verbose/internal fields from an inbox entry, keeping only the fields
+ * an agent needs for decisions and ack. Use `--full` on `inbox read`/`watch`
+ * to bypass this and see the complete entry.
+ */
+function compactInboxEntry(entry) {
+    const compact = {};
+    for (const field of COMPACT_ENTRY_FIELDS) {
+        if (entry[field] !== undefined) {
+            compact[field] = entry[field];
+        }
+    }
+    if (entry.kind === "digest_snapshot") {
+        for (const field of COMPACT_DIGEST_FIELDS) {
+            if (entry[field] !== undefined) {
+                compact[field] = entry[field];
+            }
+        }
+    }
+    return compact;
+}
 function normalizeSubscriptionAddOutput(data, shortcutUsed) {
     if (shortcutUsed) {
         return data;
@@ -1568,20 +1750,24 @@ Usage:
 Usage:
   agentinbox inbox list [--limit N]
   agentinbox inbox show <agentId>
-  agentinbox inbox read [--agent-id ID] [--after-entry ID] [--include-acked] [--limit N]
+  agentinbox inbox read [--agent-id ID] [--after-entry ID] [--include-acked] [--limit N] [--full]  (aliases: inbox get, inbox entries, inbox peek)
   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> | --entry-id <entryId> | --all)
+  agentinbox inbox watch [--agent-id ID] [--after-entry ID] [--include-acked] [--heartbeat-ms N] [--full]
+  agentinbox inbox ack [--agent-id ID] (--through <entryId> | --through-entry-id <entryId> | --entry <entryId> | --entry-id <entryId> | --all)
   agentinbox inbox policy show [--agent-id ID]
   agentinbox inbox policy set [--agent-id ID] [--enabled|--disabled] [--window-ms N] [--max-items N] [--max-thread-age-ms N]
   agentinbox inbox compact <agentId>
+
+Aliases: inbox get/entries/peek -> inbox read, top-level entries -> inbox read, top-level ack -> inbox ack
 `,
         deliver: `agentinbox deliver
 
 Usage:
   agentinbox deliver send --provider PROVIDER --surface SURFACE --target TARGET [--source-id SOURCE_ID] [--kind KIND] [--payload-json JSON]
   agentinbox deliver actions (--handle-json JSON | --provider PROVIDER --surface SURFACE --target TARGET) [--source-id SOURCE_ID]
-  agentinbox deliver invoke (--handle-json JSON | --provider PROVIDER --surface SURFACE --target TARGET) --operation NAME --input-json JSON [--source-id SOURCE_ID]
+  agentinbox deliver invoke (--handle-json JSON | --provider PROVIDER --surface SURFACE --target TARGET) --operation NAME --input-json JSON [--source-id SOURCE_ID]  (--input alias for --input-json)
+
+Aliases: delivery -> deliver
 `,
         status: `agentinbox status
 

package/dist/src/http.js

@@ -75,6 +75,17 @@ const deliveryTargetByFieldsSchema = {
         replyMode: { type: "string" },
     },
 };
+const authDescriptorSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["type"],
+    properties: {
+        type: { type: "string", enum: ["bearer", "header"] },
+        token: { type: "string" },
+        headerName: { type: "string" },
+        headerValue: { type: "string" },
+    },
+};
 function buildFastifyServer(service) {
     const app = (0, fastify_1.default)({
         logger: false,
@@ -992,6 +1003,134 @@ function buildFastifyServer(service) {
         const params = request.params;
         return service.resumeAgent(decodeURIComponent(params.agentId));
     });
+    app.get("/agents/:agentId/operator-bindings", {
+        schema: {
+            tags: ["operators"],
+            params: {
+                type: "object",
+                required: ["agentId"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: {
+                    type: "object",
+                    required: ["bindings"],
+                    properties: {
+                        bindings: { type: "array", items: jsonObjectSchema },
+                    },
+                },
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return { bindings: service.listOperatorTransportBindings(decodeURIComponent(params.agentId)) };
+    });
+    app.post("/agents/:agentId/operator-bindings", {
+        schema: {
+            tags: ["operators"],
+            params: {
+                type: "object",
+                required: ["agentId"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                },
+            },
+            body: {
+                type: "object",
+                additionalProperties: false,
+                required: ["transport", "operatorActorId", "holonBaseUrl"],
+                properties: {
+                    bindingId: { type: "string" },
+                    transport: { type: "string", minLength: 1 },
+                    operatorActorId: { type: "string", minLength: 1 },
+                    holonBaseUrl: { type: "string", minLength: 1 },
+                    deliveryCallbackUrl: { type: "string" },
+                    deliveryAuth: authDescriptorSchema,
+                    holonAuth: authDescriptorSchema,
+                    defaultRouteId: { type: "string" },
+                    capabilities: { type: "array", items: { type: "string" } },
+                    provider: { type: "string" },
+                    metadata: jsonObjectSchema,
+                    syncWithHolon: { type: "boolean" },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        const body = request.body;
+        return service.registerOperatorTransportBinding(decodeURIComponent(params.agentId), {
+            bindingId: optionalString(body.bindingId) ?? null,
+            transport: String(body.transport),
+            operatorActorId: String(body.operatorActorId),
+            holonBaseUrl: String(body.holonBaseUrl),
+            deliveryCallbackUrl: optionalString(body.deliveryCallbackUrl) ?? null,
+            deliveryAuth: body.deliveryAuth ? body.deliveryAuth : null,
+            holonAuth: body.holonAuth ? body.holonAuth : null,
+            defaultRouteId: optionalString(body.defaultRouteId) ?? null,
+            capabilities: Array.isArray(body.capabilities) ? body.capabilities.map(String) : undefined,
+            provider: optionalString(body.provider) ?? null,
+            metadata: body.metadata && typeof body.metadata === "object" ? body.metadata : undefined,
+            syncWithHolon: typeof body.syncWithHolon === "boolean" ? body.syncWithHolon : undefined,
+        });
+    });
+    app.post("/agents/:agentId/operator-ingress", {
+        schema: {
+            tags: ["operators"],
+            params: {
+                type: "object",
+                required: ["agentId"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                },
+            },
+            body: {
+                type: "object",
+                additionalProperties: false,
+                required: ["text", "bindingId"],
+                properties: {
+                    text: { type: "string", minLength: 1 },
+                    bindingId: { type: "string", minLength: 1 },
+                    actorId: { type: "string" },
+                    replyRouteId: { type: "string" },
+                    provider: { type: "string" },
+                    upstreamProvider: { type: "string" },
+                    providerMessageRef: { type: "string" },
+                    correlationId: { type: "string" },
+                    causationId: { type: "string" },
+                    metadata: jsonObjectSchema,
+                    sourceItemId: { type: "string" },
+                    deliveryHandle: deliveryHandleSchema,
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        const body = request.body;
+        return service.forwardOperatorIngress(decodeURIComponent(params.agentId), {
+            text: String(body.text),
+            bindingId: String(body.bindingId),
+            actorId: optionalString(body.actorId) ?? null,
+            replyRouteId: optionalString(body.replyRouteId) ?? null,
+            provider: optionalString(body.provider) ?? null,
+            upstreamProvider: optionalString(body.upstreamProvider) ?? null,
+            providerMessageRef: optionalString(body.providerMessageRef) ?? null,
+            correlationId: optionalString(body.correlationId) ?? null,
+            causationId: optionalString(body.causationId) ?? null,
+            metadata: body.metadata && typeof body.metadata === "object" ? body.metadata : undefined,
+            sourceItemId: optionalString(body.sourceItemId) ?? null,
+            deliveryHandle: body.deliveryHandle ? body.deliveryHandle : null,
+        });
+    });
     app.get("/agents/:agentId/targets", {
         schema: {
             tags: ["agents"],
@@ -1812,6 +1951,52 @@ function buildFastifyServer(service) {
             },
         },
     }, async (request) => service.invokeDelivery(request.body));
+    app.post("/delivery-routes/:routeId/messages", {
+        schema: {
+            tags: ["deliveries"],
+            params: {
+                type: "object",
+                required: ["routeId"],
+                properties: {
+                    routeId: { type: "string", minLength: 1 },
+                },
+            },
+            body: {
+                type: "object",
+                additionalProperties: false,
+                required: ["text"],
+                properties: {
+                    text: { type: "string", minLength: 1 },
+                    kind: { type: "string" },
+                    targetAgentId: { type: "string" },
+                    target_agent_id: { type: "string" },
+                    delivery_intent_id: { type: "string" },
+                    binding_id: { type: "string" },
+                    route_id: { type: "string" },
+                    created_at: { type: "string" },
+                    correlation_id: { type: ["string", "null"] },
+                    causation_id: { type: ["string", "null"] },
+                    metadata: jsonObjectSchema,
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        const routeId = decodeURIComponent(params.routeId);
+        assertDeliveryRouteAuthorized(service, routeId, request.headers.authorization);
+        const body = request.body;
+        return service.deliverOperatorReply(routeId, {
+            text: String(body.text),
+            kind: optionalString(body.kind) ?? null,
+            targetAgentId: optionalString(body.targetAgentId) ?? optionalString(body.target_agent_id) ?? null,
+            metadata: body.metadata && typeof body.metadata === "object" ? body.metadata : undefined,
+        });
+    });
     app.setNotFoundHandler((_request, reply) => {
         void reply.code(404).send({ error: "not found" });
     });
@@ -1825,6 +2010,14 @@ function buildFastifyServer(service) {
             void reply.code(404).send({ error: message });
             return;
         }
+        if (message.startsWith("missing delivery route authorization")) {
+            void reply.code(401).send({ error: message });
+            return;
+        }
+        if (message.startsWith("invalid delivery route authorization")) {
+            void reply.code(403).send({ error: message });
+            return;
+        }
         if (isBadRequestError(message)) {
             void reply.code(400).send({ error: message });
             return;
@@ -1872,6 +2065,23 @@ function optionalString(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
+function assertDeliveryRouteAuthorized(service, routeId, authorization) {
+    const binding = service.getOperatorBindingForReplyRoute(routeId);
+    const deliveryAuth = binding?.deliveryAuth;
+    if (!deliveryAuth) {
+        return;
+    }
+    if (deliveryAuth.type !== "bearer" || !deliveryAuth.token) {
+        throw new Error("invalid delivery route authorization");
+    }
+    if (!authorization) {
+        throw new Error("missing delivery route authorization");
+    }
+    const [scheme, token] = authorization.split(/\s+/, 2);
+    if (scheme?.toLowerCase() !== "bearer" || token !== deliveryAuth.token) {
+        throw new Error("invalid delivery route authorization");
+    }
+}
 function parseOptionalPositiveInteger(value) {
     if (value === undefined) {
         return undefined;
@@ -1909,6 +2119,9 @@ function isBadRequestError(message) {
         message.startsWith("deliver send is not supported") ||
         message.startsWith("deliveryHandle requires") ||
         message.startsWith("delivery operations are not supported") ||
+        message.startsWith("operator binding requires") ||
+        message.startsWith("operator ingress requires") ||
+        message.startsWith("operator reply route requires") ||
         message.startsWith("unsupported delivery surface") ||
         message.startsWith("unsupported delivery operation") ||
         message.startsWith("source operations are not supported") ||

package/dist/src/service.js

@@ -23,7 +23,7 @@ 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;
 const DEFAULT_SYNC_INTERVAL_MS = 2_000;
-const DEFAULT_IDLE_SOURCE_GRACE_MS = 5 * 60 * 1000;
+const DEFAULT_IDLE_SOURCE_GRACE_MS = 30 * 60 * 1000;
 const DEFAULT_INBOX_AGGREGATION_WINDOW_MS = 30 * 1000;
 const DEFAULT_INBOX_AGGREGATION_MAX_ITEMS = 20;
 const DEFAULT_INBOX_AGGREGATION_MAX_THREAD_AGE_MS = 24 * 60 * 60 * 1000;
@@ -404,6 +404,7 @@ class AgentInboxService {
                 if (!templateSpec) {
                     continue;
                 }
+                validateFollowTemplateArgs(templateSpec.argsSchema ?? [], templateArgs, templateSpec.templateId);
                 await this.adapters.sourceAdapterFor(source.sourceType).validateSource?.(source);
                 return { source, templateSpec };
             }
@@ -1686,6 +1687,144 @@ class AgentInboxService {
         this.store.insertDelivery(storedAttempt);
         return { ...storedAttempt, note: result.note, operation: request.operation };
     }
+    async registerOperatorTransportBinding(agentId, input) {
+        if (!input.transport) {
+            throw new Error("operator binding requires transport");
+        }
+        if (!input.operatorActorId) {
+            throw new Error("operator binding requires operatorActorId");
+        }
+        if (!input.holonBaseUrl) {
+            throw new Error("operator binding requires holonBaseUrl");
+        }
+        const now = (0, util_1.nowIso)();
+        const current = input.bindingId ? this.store.getOperatorTransportBinding(input.bindingId) : null;
+        const binding = {
+            bindingId: input.bindingId ?? (0, util_1.generateCanonicalId)("opb"),
+            agentId,
+            transport: input.transport,
+            operatorActorId: input.operatorActorId,
+            holonBaseUrl: input.holonBaseUrl.replace(/\/+$/, ""),
+            deliveryCallbackUrl: input.deliveryCallbackUrl ?? null,
+            deliveryAuth: input.deliveryAuth ?? null,
+            holonAuth: input.holonAuth ?? null,
+            defaultRouteId: input.defaultRouteId ?? null,
+            capabilities: input.capabilities ?? ["prompt"],
+            provider: input.provider ?? null,
+            metadata: input.metadata ?? {},
+            createdAt: current?.createdAt ?? now,
+            updatedAt: now,
+        };
+        const stored = this.store.upsertOperatorTransportBinding(binding);
+        const holon = input.syncWithHolon === false ? undefined : await this.syncOperatorBindingToHolon(stored);
+        return holon === undefined ? stored : { ...stored, holon };
+    }
+    listOperatorTransportBindings(agentId) {
+        return this.store.listOperatorTransportBindings(agentId);
+    }
+    getOperatorBindingForReplyRoute(routeId) {
+        const route = this.store.getOperatorReplyRoute(routeId);
+        return route ? this.store.getOperatorTransportBinding(route.bindingId) : null;
+    }
+    async forwardOperatorIngress(agentId, input) {
+        if (!input.text) {
+            throw new Error("operator ingress requires text");
+        }
+        const binding = this.store.getOperatorTransportBinding(input.bindingId);
+        if (!binding || binding.agentId !== agentId) {
+            throw new Error(`unknown operator binding for agent ${agentId}: ${input.bindingId}`);
+        }
+        const replyRouteId = input.replyRouteId ?? binding.defaultRouteId ?? null;
+        if (replyRouteId && input.deliveryHandle) {
+            const now = (0, util_1.nowIso)();
+            this.store.upsertOperatorReplyRoute({
+                routeId: replyRouteId,
+                bindingId: binding.bindingId,
+                agentId,
+                deliveryHandle: input.deliveryHandle,
+                sourceId: typeof input.metadata?.sourceId === "string" ? input.metadata.sourceId : null,
+                metadata: input.metadata ?? {},
+                createdAt: now,
+                updatedAt: now,
+            });
+        }
+        const holon = await this.postHolonJson(binding, `/control/agents/${encodeURIComponent(agentId)}/operator-ingress`, {
+            text: input.text,
+            actor_id: input.actorId ?? binding.operatorActorId,
+            binding_id: binding.bindingId,
+            reply_route_id: replyRouteId,
+            provider: input.provider ?? binding.provider ?? binding.transport,
+            upstream_provider: input.upstreamProvider ?? binding.provider ?? binding.transport,
+            provider_message_ref: input.providerMessageRef ?? null,
+            correlation_id: input.correlationId ?? null,
+            causation_id: input.causationId ?? null,
+            metadata: {
+                ...(input.metadata ?? {}),
+                source_item_id: input.sourceItemId ?? undefined,
+            },
+        });
+        return {
+            accepted: true,
+            bindingId: binding.bindingId,
+            replyRouteId,
+            holon,
+        };
+    }
+    async deliverOperatorReply(routeId, input) {
+        if (!input.text) {
+            throw new Error("operator reply route requires text");
+        }
+        const route = this.store.getOperatorReplyRoute(routeId);
+        if (!route) {
+            throw new Error(`unknown operator reply route: ${routeId}`);
+        }
+        return this.sendDelivery({
+            sourceId: route.sourceId ?? undefined,
+            deliveryHandle: route.deliveryHandle,
+            kind: input.kind ?? "reply",
+            payload: {
+                text: input.text,
+                targetAgentId: input.targetAgentId ?? route.agentId,
+                routeId,
+                metadata: input.metadata ?? {},
+            },
+        });
+    }
+    async syncOperatorBindingToHolon(binding) {
+        if (!binding.defaultRouteId) {
+            throw new Error("operator binding sync requires defaultRouteId");
+        }
+        if (!binding.deliveryCallbackUrl) {
+            throw new Error("operator binding sync requires deliveryCallbackUrl");
+        }
+        return this.postHolonJson(binding, `/control/agents/${encodeURIComponent(binding.agentId)}/operator-bindings`, omitNullish({
+            binding_id: binding.bindingId,
+            transport: binding.transport,
+            operator_actor_id: binding.operatorActorId,
+            default_route_id: binding.defaultRouteId,
+            delivery_callback_url: binding.deliveryCallbackUrl,
+            delivery_auth: holonOperatorDeliveryAuth(binding.deliveryAuth),
+            capabilities: holonOperatorCapabilities(binding.capabilities),
+            provider: binding.provider,
+            metadata: binding.metadata,
+        }));
+    }
+    async postHolonJson(binding, path, payload) {
+        const response = await fetch(`${binding.holonBaseUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...authHeaders(binding.holonAuth),
+            },
+            body: JSON.stringify(payload),
+        });
+        const text = await response.text();
+        const body = text ? parseJsonResponse(text) : {};
+        if (!response.ok) {
+            throw new Error(`Holon operator route call failed: ${response.status} ${text}`);
+        }
+        return body;
+    }
     async sendCanonicalDeliveryViaModule(source, handle, payload, attempt) {
         const operations = await this.adapters.listDeliveryOperations(source, handle);
         const canonicalOperation = operations?.find((operation) => operation.canonicalTextAlias);
@@ -2111,6 +2250,14 @@ class AgentInboxService {
                 const pendingState = state?.status === "dirty" ? state : null;
                 const inbox = this.ensureInboxForAgent(buffer.agentId);
                 const unackedItems = this.store.listInboxEntries(inbox.inboxId, { includeAcked: false });
+                if (unackedItems.length === 0) {
+                    // All buffered items were acked before the flush window expired.
+                    // Nothing to dispatch — clean up and skip.
+                    this.store.deleteActivationDispatchState(buffer.agentId, buffer.targetId);
+                    buffer.inFlight = false;
+                    this.notificationBuffers.delete(key);
+                    return;
+                }
                 const dispatched = await this.dispatchActivationTarget({
                     agentId: buffer.agentId,
                     targetId: buffer.targetId,
@@ -2928,6 +3075,24 @@ class AgentInboxService {
                 await this.pollSubscription(subscription.subscriptionId);
             }
             catch (error) {
+                // Self-heal: if the subscription was deleted between listing and polling
+                // (race with lifecycle cleanup), skip silently.
+                if (!this.store.getSubscription(subscription.subscriptionId)) {
+                    continue;
+                }
+                // If the source was deleted but the subscription remains (orphaned),
+                // clean up the subscription to stop repeated errors on every cycle.
+                if (!this.store.getSource(subscription.sourceId)) {
+                    try {
+                        await this.removeSubscription(subscription.subscriptionId);
+                    }
+                    catch {
+                        this.store.deleteSubscription(subscription.subscriptionId);
+                        this.clearSubscriptionRuntimeState(subscription);
+                    }
+                    console.warn(`subscription ${subscription.subscriptionId} orphaned (source ${subscription.sourceId} no longer exists); removed`);
+                    continue;
+                }
                 console.warn(`subscription poll failed for ${subscription.subscriptionId}:`, error);
             }
         }
@@ -3439,6 +3604,26 @@ function providerForSourceType(sourceType) {
     }
     return null;
 }
+function authHeaders(auth) {
+    if (!auth) {
+        return {};
+    }
+    if (auth.type === "bearer" && auth.token) {
+        return { authorization: `Bearer ${auth.token}` };
+    }
+    if (auth.type === "header" && auth.headerName && auth.headerValue) {
+        return { [auth.headerName]: auth.headerValue };
+    }
+    return {};
+}
+function parseJsonResponse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { text };
+    }
+}
 class ActivationDispatcher {
     async dispatch(targetUrl, activation) {
         try {
@@ -3515,8 +3700,11 @@ function inboxAggregationPolicy(inbox) {
     };
 }
 function meetsNotificationThreshold(policy, totalUnackedCount) {
+    if (totalUnackedCount === 0) {
+        return false;
+    }
     if (policy.minUnackedItems == null) {
-        return true;
+        return totalUnackedCount > 0;
     }
     return totalUnackedCount >= policy.minUnackedItems;
 }
@@ -4045,6 +4233,26 @@ function deliverSendUnsupportedMessage(handle, operations) {
     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 omitNullish(record) {
+    return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== null && value !== undefined));
+}
+function holonOperatorDeliveryAuth(auth) {
+    if (!auth) {
+        throw new Error("operator binding sync requires deliveryAuth");
+    }
+    if (auth.type === "bearer" && auth.token) {
+        return { kind: "bearer", bearer_token: auth.token };
+    }
+    throw new Error("operator binding sync supports only bearer deliveryAuth with a token");
+}
+function holonOperatorCapabilities(capabilities) {
+    const normalized = new Set(capabilities.map((capability) => capability.trim().toLowerCase()).filter(Boolean));
+    return {
+        text: normalized.size === 0 || normalized.has("prompt") || normalized.has("text") || normalized.has("send_prompt"),
+        ...(normalized.has("markdown") ? { markdown: true } : {}),
+        ...(normalized.has("attachments") || normalized.has("attachment") ? { attachments: true } : {}),
+    };
+}
 function deliveryActionsHelp(handle) {
     return `Run \`agentinbox deliver actions --provider ${handle.provider} --surface ${handle.surface} --target ${handle.targetRef}\` to inspect supported operations and input schemas.`;
 }

package/dist/src/sources/remote.js

@@ -177,6 +177,10 @@ class RemoteSourceRuntime {
         }
         const binding = managedBindingForSource(source);
         await this.client.sourceDelete(binding.namespace, binding.sourceKey);
+        // Clean up in-memory state to prevent stale references after DB deletion
+        this.errorCounts.delete(sourceId);
+        this.nextRetryAt.delete(sourceId);
+        this.inFlight.delete(sourceId);
     }
     status() {
         return {

package/dist/src/store.js

@@ -1514,6 +1514,85 @@ class AgentInboxStore {
         const rows = this.getAll("select * from deliveries order by created_at desc");
         return rows.map((row) => this.mapDelivery(row));
     }
+    upsertOperatorTransportBinding(binding) {
+        this.run(`
+      insert into operator_transport_bindings (
+        binding_id, agent_id, transport, operator_actor_id, holon_base_url,
+        delivery_callback_url, delivery_auth_json, holon_auth_json, default_route_id,
+        capabilities_json, provider, metadata_json, created_at, updated_at
+      ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      on conflict(binding_id) do update set
+        agent_id = excluded.agent_id,
+        transport = excluded.transport,
+        operator_actor_id = excluded.operator_actor_id,
+        holon_base_url = excluded.holon_base_url,
+        delivery_callback_url = excluded.delivery_callback_url,
+        delivery_auth_json = excluded.delivery_auth_json,
+        holon_auth_json = excluded.holon_auth_json,
+        default_route_id = excluded.default_route_id,
+        capabilities_json = excluded.capabilities_json,
+        provider = excluded.provider,
+        metadata_json = excluded.metadata_json,
+        updated_at = excluded.updated_at
+    `, [
+            binding.bindingId,
+            binding.agentId,
+            binding.transport,
+            binding.operatorActorId,
+            binding.holonBaseUrl,
+            binding.deliveryCallbackUrl ?? null,
+            binding.deliveryAuth ? JSON.stringify(binding.deliveryAuth) : null,
+            binding.holonAuth ? JSON.stringify(binding.holonAuth) : null,
+            binding.defaultRouteId ?? null,
+            JSON.stringify(binding.capabilities),
+            binding.provider ?? null,
+            JSON.stringify(binding.metadata),
+            binding.createdAt,
+            binding.updatedAt,
+        ]);
+        this.persist();
+        return this.getOperatorTransportBinding(binding.bindingId);
+    }
+    getOperatorTransportBinding(bindingId) {
+        const row = this.getOne("select * from operator_transport_bindings where binding_id = ?", [bindingId]);
+        return row ? this.mapOperatorTransportBinding(row) : null;
+    }
+    listOperatorTransportBindings(agentId) {
+        const rows = agentId
+            ? this.getAll("select * from operator_transport_bindings where agent_id = ? order by created_at asc", [agentId])
+            : this.getAll("select * from operator_transport_bindings order by created_at asc");
+        return rows.map((row) => this.mapOperatorTransportBinding(row));
+    }
+    upsertOperatorReplyRoute(route) {
+        this.run(`
+      insert into operator_reply_routes (
+        route_id, binding_id, agent_id, source_id, delivery_handle_json,
+        metadata_json, created_at, updated_at
+      ) values (?, ?, ?, ?, ?, ?, ?, ?)
+      on conflict(route_id) do update set
+        binding_id = excluded.binding_id,
+        agent_id = excluded.agent_id,
+        source_id = excluded.source_id,
+        delivery_handle_json = excluded.delivery_handle_json,
+        metadata_json = excluded.metadata_json,
+        updated_at = excluded.updated_at
+    `, [
+            route.routeId,
+            route.bindingId,
+            route.agentId,
+            route.sourceId ?? null,
+            JSON.stringify(route.deliveryHandle),
+            JSON.stringify(route.metadata),
+            route.createdAt,
+            route.updatedAt,
+        ]);
+        this.persist();
+        return this.getOperatorReplyRoute(route.routeId);
+    }
+    getOperatorReplyRoute(routeId) {
+        const row = this.getOne("select * from operator_reply_routes where route_id = ?", [routeId]);
+        return row ? this.mapOperatorReplyRoute(row) : null;
+    }
     insertStream(stream) {
         this.run("insert into streams (stream_id, source_id, stream_key, backend, created_at) values (?, ?, ?, ?, ?)", [stream.streamId, stream.sourceId, stream.streamKey, stream.backend, stream.createdAt]);
         this.persist();
@@ -2030,6 +2109,36 @@ class AgentInboxStore {
             createdAt: String(row.created_at),
         };
     }
+    mapOperatorTransportBinding(row) {
+        return {
+            bindingId: String(row.binding_id),
+            agentId: String(row.agent_id),
+            transport: String(row.transport),
+            operatorActorId: String(row.operator_actor_id),
+            holonBaseUrl: String(row.holon_base_url),
+            deliveryCallbackUrl: row.delivery_callback_url ? String(row.delivery_callback_url) : null,
+            deliveryAuth: row.delivery_auth_json ? parseJson(row.delivery_auth_json) : null,
+            holonAuth: row.holon_auth_json ? parseJson(row.holon_auth_json) : null,
+            defaultRouteId: row.default_route_id ? String(row.default_route_id) : null,
+            capabilities: parseJson(row.capabilities_json),
+            provider: row.provider ? String(row.provider) : null,
+            metadata: parseJson(row.metadata_json),
+            createdAt: String(row.created_at),
+            updatedAt: String(row.updated_at),
+        };
+    }
+    mapOperatorReplyRoute(row) {
+        return {
+            routeId: String(row.route_id),
+            bindingId: String(row.binding_id),
+            agentId: String(row.agent_id),
+            sourceId: row.source_id ? String(row.source_id) : null,
+            deliveryHandle: parseJson(row.delivery_handle_json),
+            metadata: parseJson(row.metadata_json),
+            createdAt: String(row.created_at),
+            updatedAt: String(row.updated_at),
+        };
+    }
     resolveInboxEntryId(inboxId, refOrItemId) {
         try {
             return (0, util_1.parseEntryRef)(refOrItemId);

package/drizzle/migrations/0005_operator_transport_bindings.sql

@@ -0,0 +1,29 @@
+CREATE TABLE `operator_transport_bindings` (
+  `binding_id` text PRIMARY KEY NOT NULL,
+  `agent_id` text NOT NULL,
+  `transport` text NOT NULL,
+  `operator_actor_id` text NOT NULL,
+  `holon_base_url` text NOT NULL,
+  `delivery_callback_url` text,
+  `delivery_auth_json` text,
+  `holon_auth_json` text,
+  `default_route_id` text,
+  `capabilities_json` text NOT NULL,
+  `provider` text,
+  `metadata_json` text NOT NULL,
+  `created_at` text NOT NULL,
+  `updated_at` text NOT NULL
+);
+CREATE INDEX `idx_operator_bindings_agent_transport` ON `operator_transport_bindings` (`agent_id`,`transport`);
+
+CREATE TABLE `operator_reply_routes` (
+  `route_id` text PRIMARY KEY NOT NULL,
+  `binding_id` text NOT NULL,
+  `agent_id` text NOT NULL,
+  `source_id` text,
+  `delivery_handle_json` text NOT NULL,
+  `metadata_json` text NOT NULL,
+  `created_at` text NOT NULL,
+  `updated_at` text NOT NULL
+);
+CREATE INDEX `idx_operator_reply_routes_binding` ON `operator_reply_routes` (`binding_id`);

package/drizzle/schema.ts

@@ -282,6 +282,38 @@ export const deliveries = sqliteTable("deliveries", {
   createdAt: text("created_at").notNull(),
 });
 
+export const operatorTransportBindings = sqliteTable("operator_transport_bindings", {
+  bindingId: text("binding_id").primaryKey(),
+  agentId: text("agent_id").notNull(),
+  transport: text("transport").notNull(),
+  operatorActorId: text("operator_actor_id").notNull(),
+  holonBaseUrl: text("holon_base_url").notNull(),
+  deliveryCallbackUrl: text("delivery_callback_url"),
+  deliveryAuthJson: text("delivery_auth_json"),
+  holonAuthJson: text("holon_auth_json"),
+  defaultRouteId: text("default_route_id"),
+  capabilitiesJson: text("capabilities_json").notNull(),
+  provider: text("provider"),
+  metadataJson: text("metadata_json").notNull(),
+  createdAt: text("created_at").notNull(),
+  updatedAt: text("updated_at").notNull(),
+}, (table) => ({
+  agentTransportIdx: index("idx_operator_bindings_agent_transport").on(table.agentId, table.transport),
+}));
+
+export const operatorReplyRoutes = sqliteTable("operator_reply_routes", {
+  routeId: text("route_id").primaryKey(),
+  bindingId: text("binding_id").notNull(),
+  agentId: text("agent_id").notNull(),
+  sourceId: text("source_id"),
+  deliveryHandleJson: text("delivery_handle_json").notNull(),
+  metadataJson: text("metadata_json").notNull(),
+  createdAt: text("created_at").notNull(),
+  updatedAt: text("updated_at").notNull(),
+}, (table) => ({
+  bindingIdx: index("idx_operator_reply_routes_binding").on(table.bindingId),
+}));
+
 export const streams = sqliteTable("streams", {
   streamId: text("stream_id").primaryKey(),
   sourceId: text("source_id").notNull(),

package/package.json

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