@holon-run/agentinbox 1.3.2 → 1.4.0

package/dist/src/adapters.js

@@ -4,6 +4,7 @@ exports.AdapterRegistry = void 0;
 const paths_1 = require("./paths");
 const feishu_1 = require("./sources/feishu");
 const github_1 = require("./sources/github");
+const telegram_1 = require("./sources/telegram");
 const remote_1 = require("./sources/remote");
 const remote_modules_1 = require("./sources/remote_modules");
 const source_resolution_1 = require("./source_resolution");
@@ -40,6 +41,7 @@ class AdapterRegistry {
     defaultDelivery = new NoopDeliveryAdapter();
     feishuDelivery = new feishu_1.FeishuDeliveryAdapter();
     githubDelivery = new github_1.GithubDeliveryAdapter();
+    telegramDelivery = new telegram_1.TelegramDeliveryAdapter();
     homeDir;
     remoteModuleRegistry;
     constructor(store, appendSourceEvent, options) {
@@ -51,6 +53,7 @@ class AdapterRegistry {
             homeDir: this.homeDir,
             client: options?.remoteSourceClient,
             moduleRegistry: this.remoteModuleRegistry,
+            telegramClient: options?.telegramClient,
         });
     }
     sourceAdapterFor(type) {
@@ -69,6 +72,9 @@ class AdapterRegistry {
         if (type === "feishu_bot") {
             return this.remoteSource;
         }
+        if (type === "telegram_bot") {
+            return this.remoteSource;
+        }
         return this.localEventSource;
     }
     deliveryAdapterFor(provider) {
@@ -78,6 +84,9 @@ class AdapterRegistry {
         if (provider === "github") {
             return this.githubDelivery;
         }
+        if (provider === "telegram") {
+            return this.telegramDelivery;
+        }
         return this.defaultDelivery;
     }
     async start() {
@@ -238,6 +247,9 @@ class AdapterRegistry {
         if (handle.provider === "feishu") {
             return this.remoteModuleRegistry.resolve(syntheticBuiltinSource("feishu_bot"), this.homeDir);
         }
+        if (handle.provider === "telegram") {
+            return this.remoteModuleRegistry.resolve(syntheticBuiltinSource("telegram_bot"), this.homeDir);
+        }
         return null;
     }
 }
@@ -248,6 +260,7 @@ function isExplicitFollowPreviewRef(value) {
         value === "github_repo" ||
         value === "github_repo_ci" ||
         value === "feishu_bot" ||
+        value === "telegram_bot" ||
         value.startsWith("remote:"));
 }
 function hasRemoteSourceModulePath(config) {

package/dist/src/cli.js

@@ -794,12 +794,12 @@ async function main() {
     }
     if (command === "inbox" && normalized[1] === "ack") {
         const args = normalized.slice(2);
-        const itemId = takeFlagValue(normalized, "--entry");
+        const itemId = takeFlagValue(normalized, "--entry-id") ?? takeFlagValue(normalized, "--entry");
         const throughEntryId = takeFlagValue(normalized, "--through");
         const ackAll = hasFlag(normalized, "--all");
         const modeCount = Number(Boolean(itemId)) + Number(Boolean(throughEntryId)) + Number(ackAll);
-        if (positionalArgs(args, ["--agent-id", "--entry", "--through"]).length > 0 || modeCount !== 1) {
-            throw new Error("usage: agentinbox inbox ack [--agent-id ID] (--through <entryId> | --entry <entryId> | --all)");
+        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)");
         }
         const selection = await selectAgentForCommand(client, {
             explicitAgentId: takeFlagValue(normalized, "--agent-id"),
@@ -1571,7 +1571,7 @@ Usage:
   agentinbox inbox read [--agent-id ID] [--after-entry ID] [--include-acked] [--limit N]
   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> | --all)
+  agentinbox inbox ack [--agent-id ID] (--through <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>

package/dist/src/service.js

@@ -1697,6 +1697,15 @@ class AgentInboxService {
     }
     async status() {
         const sources = await this.listSourceViews();
+        const agents = this.store.listAgents();
+        const subscriptions = this.store.listSubscriptions();
+        const inboxes = this.store.listInboxes();
+        const activationTargets = this.store.listActivationTargets();
+        const activationDispatchStates = this.store.listActivationDispatchStates();
+        const streams = this.store.listStreams();
+        const consumers = this.store.listConsumers();
+        const recentActivations = this.store.listActivations().slice(0, 10);
+        const recentDeliveries = this.store.listDeliveries().slice(0, 10);
         return {
             retention: {
                 ackedInboxItemsMs: this.ackedRetentionMs,
@@ -1704,17 +1713,30 @@ class AgentInboxService {
                 lastAckedInboxGcAt: this.lastAckedInboxGcAt > 0 ? new Date(this.lastAckedInboxGcAt).toISOString() : null,
             },
             counts: this.store.getCounts(),
-            agents: this.store.listAgents(),
+            diagnostics: {
+                database: this.store.getDatabaseHealth(),
+                daemon: { status: "running" },
+                sources: summarizeByStatus(sources, ["active", "paused", "error"]),
+                agents: summarizeByStatus(agents, ["active", "offline"]),
+                activationTargets: summarizeByStatus(activationTargets, ["active", "offline"]),
+                activationDispatch: {
+                    ...summarizeByStatus(activationDispatchStates, ["dirty", "notified"]),
+                    pendingNewItems: activationDispatchStates.reduce((total, state) => total + state.pendingNewItemCount, 0),
+                    deferredAttempts: activationDispatchStates.reduce((total, state) => total + state.deferAttempts, 0),
+                },
+                deliveries: summarizeByStatus(recentDeliveries, ["accepted", "sent", "failed"]),
+            },
+            agents,
             sources,
-            subscriptions: this.store.listSubscriptions(),
-            inboxes: this.store.listInboxes(),
-            activationTargets: this.store.listActivationTargets(),
-            activationDispatchStates: this.store.listActivationDispatchStates(),
-            streams: this.store.listStreams(),
-            consumers: this.store.listConsumers(),
+            subscriptions,
+            inboxes,
+            activationTargets,
+            activationDispatchStates,
+            streams,
+            consumers,
             adapters: this.adapters.status(),
-            recentActivations: this.store.listActivations().slice(0, 10),
-            recentDeliveries: this.store.listDeliveries().slice(0, 10),
+            recentActivations,
+            recentDeliveries,
             lifecycle: {
                 offlineAgentTtlMs: DEFAULT_OFFLINE_AGENT_TTL_MS,
                 gcIntervalMs: DEFAULT_GC_INTERVAL_MS,
@@ -1993,6 +2015,7 @@ class AgentInboxService {
             buffer = {
                 agentId: target.agentId,
                 targetId: target.targetId,
+                targetKind: target.kind,
                 pending: [],
                 timer: null,
                 inFlight: false,
@@ -2081,21 +2104,24 @@ class AgentInboxService {
                 return;
             }
             const state = this.store.getActivationDispatchState(buffer.agentId, buffer.targetId);
-            const shouldAttemptDispatch = !state || (state.status === "dirty" && state.leaseExpiresAt == null);
+            const shouldAttemptDispatch = !state
+                || (state.status === "dirty" && state.leaseExpiresAt == null)
+                || (state.status === "notified" && buffer.targetKind === "webhook");
             if (shouldAttemptDispatch) {
+                const pendingState = state?.status === "dirty" ? state : null;
                 const inbox = this.ensureInboxForAgent(buffer.agentId);
                 const unackedItems = this.store.listInboxEntries(inbox.inboxId, { includeAcked: false });
                 const dispatched = await this.dispatchActivationTarget({
                     agentId: buffer.agentId,
                     targetId: buffer.targetId,
-                    newItemCount: state ? state.pendingNewItemCount + entries.length : entries.length,
+                    newItemCount: pendingState ? pendingState.pendingNewItemCount + entries.length : entries.length,
                     totalUnackedCount: unackedItems.length,
-                    summary: state ? latestSummary(entries) ?? state.pendingSummary : latestSummary(entries),
-                    subscriptionIds: state
-                        ? uniqueSortedNullable([...state.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)])
+                    summary: pendingState ? latestSummary(entries) ?? pendingState.pendingSummary : latestSummary(entries),
+                    subscriptionIds: pendingState
+                        ? uniqueSortedNullable([...pendingState.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)])
                         : uniqueSortedNullable(entries.map((entry) => entry.subscriptionId)),
-                    sourceIds: state
-                        ? uniqueSorted([...state.pendingSourceIds, ...entries.map((entry) => entry.sourceId)])
+                    sourceIds: pendingState
+                        ? uniqueSorted([...pendingState.pendingSourceIds, ...entries.map((entry) => entry.sourceId)])
                         : uniqueSorted(entries.map((entry) => entry.sourceId)),
                     entries: unackedItems,
                 });
@@ -2104,22 +2130,22 @@ class AgentInboxService {
                     this.store.deleteActivationDispatchState(buffer.agentId, buffer.targetId);
                 }
                 if (dispatched === "retryable_failure") {
-                    if (state && state.status === "dirty" && state.leaseExpiresAt == null) {
+                    if (pendingState && pendingState.leaseExpiresAt == null) {
                         this.store.upsertActivationDispatchState({
                             agentId: buffer.agentId,
                             targetId: buffer.targetId,
                             status: "dirty",
                             leaseExpiresAt: new Date(Date.now() + DEFAULT_NOTIFY_RETRY_MS).toISOString(),
-                            lastNotifiedFingerprint: state.lastNotifiedFingerprint,
+                            lastNotifiedFingerprint: pendingState.lastNotifiedFingerprint,
                             deferReason: null,
                             deferAttempts: 0,
                             firstDeferredAt: null,
                             lastDeferredAt: null,
                             pendingFingerprint: null,
-                            pendingNewItemCount: state.pendingNewItemCount + entries.length,
-                            pendingSummary: latestSummary(entries) ?? state.pendingSummary,
-                            pendingSubscriptionIds: uniqueSortedNullable([...state.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)]),
-                            pendingSourceIds: uniqueSorted([...state.pendingSourceIds, ...entries.map((entry) => entry.sourceId)]),
+                            pendingNewItemCount: pendingState.pendingNewItemCount + entries.length,
+                            pendingSummary: latestSummary(entries) ?? pendingState.pendingSummary,
+                            pendingSubscriptionIds: uniqueSortedNullable([...pendingState.pendingSubscriptionIds, ...entries.map((entry) => entry.subscriptionId)]),
+                            pendingSourceIds: uniqueSorted([...pendingState.pendingSourceIds, ...entries.map((entry) => entry.sourceId)]),
                             updatedAt: (0, util_1.nowIso)(),
                         });
                     }
@@ -3104,7 +3130,12 @@ function mergeFollowPreviewConfig(config, templateArgs) {
     };
 }
 function sourceTypeForPreviewRef(sourceRef) {
-    if (sourceRef === "local_event" || sourceRef === "remote_source" || sourceRef === "github_repo" || sourceRef === "github_repo_ci" || sourceRef === "feishu_bot") {
+    if (sourceRef === "local_event" ||
+        sourceRef === "remote_source" ||
+        sourceRef === "github_repo" ||
+        sourceRef === "github_repo_ci" ||
+        sourceRef === "feishu_bot" ||
+        sourceRef === "telegram_bot") {
         return sourceRef;
     }
     if (sourceRef.startsWith("remote:")) {
@@ -3403,6 +3434,9 @@ function providerForSourceType(sourceType) {
     if (sourceType === "feishu_bot") {
         return "feishu";
     }
+    if (sourceType === "telegram_bot") {
+        return "telegram";
+    }
     return null;
 }
 class ActivationDispatcher {
@@ -3972,6 +4006,8 @@ function listHostStreamKinds(hostType) {
             return ["repo_events", "ci_runs"];
         case "feishu":
             return ["message_events"];
+        case "telegram":
+            return ["message_updates"];
         case "local_event":
             return ["events"];
         case "remote_source":
@@ -4015,6 +4051,16 @@ function deliveryActionsHelp(handle) {
 function isKnownDeliverySurface(handle) {
     return KNOWN_DELIVERY_SURFACES[handle.provider]?.includes(handle.surface) === true;
 }
+function summarizeByStatus(records, expectedStatuses) {
+    const summary = { total: records.length };
+    for (const status of expectedStatuses) {
+        summary[status] = 0;
+    }
+    for (const record of records) {
+        summary[record.status] = (summary[record.status] ?? 0) + 1;
+    }
+    return summary;
+}
 function getHostConfigFields(hostType) {
     switch (hostType) {
         case "github":
@@ -4025,6 +4071,12 @@ function getHostConfigFields(hostType) {
             return [
                 { name: "uxcAuth", type: "string", description: "Optional shared Feishu/Lark UXC auth profile.", required: false },
             ];
+        case "telegram":
+            return [
+                { name: "botToken", type: "string", description: "Telegram Bot API token.", required: false },
+                { name: "tokenEnv", type: "string", description: "Environment variable containing the Telegram Bot API token.", required: false },
+                { name: "botUsername", type: "string", description: "Optional bot username used for shared host identity.", required: false },
+            ];
         case "local_event":
             return [];
         case "remote_source":
@@ -4041,6 +4093,9 @@ function sourceTypeForStreamRegistration(hostType, streamKind) {
     if (hostType === "feishu") {
         return "feishu_bot";
     }
+    if (hostType === "telegram") {
+        return "telegram_bot";
+    }
     if (hostType === "local_event") {
         return "local_event";
     }

package/dist/src/source_hosts.js

@@ -44,6 +44,22 @@ function resolveSourceRegistration(input) {
             sourceType: input.sourceType,
         };
     }
+    if (input.sourceType === "telegram_bot") {
+        return {
+            hostType: "telegram",
+            hostKey: `bot:${stringOrDefault(config.botUsername, input.configRef ?? input.sourceKey)}`,
+            hostConfig: {
+                ...(valueOrUndefined(config.botToken) ? { botToken: config.botToken } : {}),
+                ...(valueOrUndefined(config.tokenEnv) ? { tokenEnv: config.tokenEnv } : {}),
+                ...(valueOrUndefined(config.apiBaseUrl) ? { apiBaseUrl: config.apiBaseUrl } : {}),
+                ...(valueOrUndefined(config.botUsername) ? { botUsername: config.botUsername } : {}),
+            },
+            streamKind: "message_updates",
+            streamKey: input.sourceKey,
+            streamConfig: config,
+            sourceType: input.sourceType,
+        };
+    }
     if (input.sourceType === "local_event") {
         return {
             hostType: "local_event",

package/dist/src/source_schema.js

@@ -154,6 +154,41 @@ const SOURCE_SCHEMAS = {
             { name: "replyInThread", type: "boolean", required: false, description: "Reply in thread when sending outbound messages." },
         ],
     },
+    telegram_bot: {
+        sourceType: "telegram_bot",
+        metadataFields: [
+            { name: "updateId", type: "string", description: "Telegram update_id." },
+            { name: "chatId", type: "string", description: "Telegram chat ID." },
+            { name: "chatType", type: "string|null", description: "Telegram chat type such as private, group, or channel." },
+            { name: "messageId", type: "string", description: "Telegram message_id." },
+            { name: "messageType", type: "string", description: "Normalized Telegram message type such as text or photo." },
+            { name: "fromId", type: "string|null", description: "Telegram sender user ID when present." },
+            { name: "fromUsername", type: "string|null", description: "Telegram sender username when present." },
+            { name: "fromFirstName", type: "string|null", description: "Telegram sender first_name when present." },
+            { name: "content", type: "string|null", description: "Message text or caption when present." },
+        ],
+        payloadExamples: [
+            {
+                update_id: 123,
+                message: {
+                    message_id: 7,
+                    date: 1710000000,
+                    text: "hello",
+                    chat: { id: 456, type: "private" },
+                    from: { id: 111, username: "operator", first_name: "Op" },
+                },
+            },
+        ],
+        eventVariantExamples: ["message.text", "edited_message.text", "channel_post.photo"],
+        configFields: [
+            { name: "botToken", type: "string", required: false, description: "Telegram bot token. Prefer tokenEnv for shared/local configuration." },
+            { name: "tokenEnv", type: "string", required: false, description: "Environment variable name containing the Telegram bot token." },
+            { name: "botUsername", type: "string", required: false, description: "Optional bot username used for source host identity." },
+            { name: "chatIds", type: "string[]", required: false, description: "Optional Telegram chat ID allowlist." },
+            { name: "allowedUpdates", type: "string[]", required: false, description: "Optional Telegram Bot API allowed_updates value." },
+            { name: "endpoint", type: "string", required: false, description: "Optional Telegram Bot API endpoint override." },
+        ],
+    },
 };
 function getSourceSchema(sourceType) {
     const schema = SOURCE_SCHEMAS[sourceType];

package/dist/src/sources/remote.js

@@ -5,11 +5,13 @@ const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
 const paths_1 = require("../paths");
 const util_1 = require("../util");
 const remote_modules_1 = require("./remote_modules");
+const telegram_1 = require("./telegram");
 const REMOTE_SOURCE_TYPES = new Set([
     "remote_source",
     "github_repo",
     "github_repo_ci",
     "feishu_bot",
+    "telegram_bot",
 ]);
 const DEFAULT_SYNC_INTERVAL_MS = 2_000;
 const DEFAULT_BACKOFF_BASE_SECS = 2;
@@ -21,6 +23,7 @@ class RpcUxcRemoteSourceClient {
         this.client = client;
     }
     sourceEnsure(args) {
+        const transportHint = args.spec.transport_hint ?? null;
         return this.client.sourceEnsure({
             namespace: args.namespace,
             sourceKey: args.sourceKey,
@@ -29,7 +32,7 @@ class RpcUxcRemoteSourceClient {
                 operation_id: args.spec.operation_id ?? null,
                 resource_uri: args.spec.resource_uri ?? null,
                 read_resource: args.spec.read_resource ?? false,
-                transport_hint: args.spec.transport_hint ?? null,
+                transport_hint: transportHint,
                 subprotocols: args.spec.subprotocols ?? [],
                 initial_text_frames: args.spec.initial_text_frames ?? [],
                 poll_config: args.spec.poll_config ?? null,
@@ -68,12 +71,14 @@ class RemoteSourceRuntime {
     errorCounts = new Map();
     nextRetryAt = new Map();
     homeDir;
+    telegramClient;
     constructor(store, appendSourceEvent, options) {
         this.store = store;
         this.appendSourceEvent = appendSourceEvent;
         this.moduleRegistry = options?.moduleRegistry ?? new remote_modules_1.RemoteSourceModuleRegistry();
         this.client = options?.client ?? new RpcUxcRemoteSourceClient();
         this.homeDir = options?.homeDir ?? (0, paths_1.resolveAgentInboxHome)(process.env);
+        this.telegramClient = options?.telegramClient ?? new telegram_1.TelegramBotApiClient();
     }
     async ensureSource(source) {
         if (!REMOTE_SOURCE_TYPES.has(source.sourceType)) {
@@ -380,6 +385,9 @@ class RemoteSourceRuntime {
                     };
                 }
             }
+            if (source.sourceType === "telegram_bot") {
+                return await this.syncTelegramSource(source);
+            }
             const module = await this.moduleRegistry.resolve(source, this.homeDir);
             const moduleSource = moduleInputSource(source);
             module.validateConfig(moduleSource);
@@ -474,6 +482,70 @@ class RemoteSourceRuntime {
             this.inFlight.delete(sourceId);
         }
     }
+    async syncTelegramSource(source) {
+        const config = (0, telegram_1.parseTelegramSourceConfig)(source);
+        const botToken = config.botToken ?? tokenFromEnv(config.tokenEnv);
+        if (!botToken) {
+            throw new Error("Telegram source requires config.botToken or tokenEnv");
+        }
+        const checkpoint = parseRemoteCheckpoint(source.checkpoint);
+        const updates = await this.telegramClient.getUpdates({
+            endpoint: config.endpoint,
+            botToken,
+            offset: checkpoint.telegramCursor?.nextOffset,
+            timeout: 0,
+            allowedUpdates: config.allowedUpdates,
+        });
+        let appended = 0;
+        let deduped = 0;
+        let nextOffset = checkpoint.telegramCursor?.nextOffset ?? 0;
+        for (const update of updates) {
+            const normalized = (0, telegram_1.normalizeTelegramBotUpdate)(source, config, update);
+            const updateId = numberFromUnknown(update.update_id);
+            if (updateId !== undefined) {
+                nextOffset = Math.max(nextOffset, updateId + 1);
+            }
+            if (!normalized) {
+                continue;
+            }
+            const result = await this.appendSourceEvent(normalized);
+            appended += result.appended;
+            deduped += result.deduped;
+        }
+        const latestSource = this.store.getSource(source.sourceId);
+        if (!latestSource) {
+            throw new Error(`unknown source: ${source.sourceId}`);
+        }
+        const observedAt = (0, util_1.nowIso)();
+        this.store.updateSourceRuntime(source.sourceId, {
+            status: latestSource.status === "paused" ? "paused" : "active",
+            checkpoint: JSON.stringify({
+                ...checkpoint,
+                telegramCursor: { nextOffset },
+                managedRuntime: {
+                    status: "running",
+                    runId: null,
+                    streamId: null,
+                    lastError: null,
+                    updatedAt: observedAt,
+                    startedAt: checkpoint.managedRuntime?.startedAt ?? observedAt,
+                    stoppedAt: null,
+                },
+                lastEventAt: observedAt,
+                lastError: null,
+            }),
+        });
+        this.errorCounts.delete(source.sourceId);
+        this.nextRetryAt.delete(source.sourceId);
+        return {
+            sourceId: source.sourceId,
+            sourceType: source.sourceType,
+            appended,
+            deduped,
+            eventsRead: updates.length,
+            note: "telegram getUpdates poll completed",
+        };
+    }
 }
 exports.RemoteSourceRuntime = RemoteSourceRuntime;
 function normalizeExpandedSubscriptionPlan(value) {
@@ -529,6 +601,25 @@ function managedBindingForSource(source) {
 function managedSourceBindingKey(namespace, sourceKey) {
     return `${namespace}:${sourceKey}`;
 }
+function tokenFromEnv(name) {
+    if (!name) {
+        return null;
+    }
+    const value = process.env[name];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function numberFromUnknown(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
 function parseRemoteCheckpoint(checkpoint) {
     if (!checkpoint) {
         return {};

package/dist/src/sources/remote_modules.js

@@ -14,9 +14,10 @@ const node_url_1 = require("node:url");
 const github_1 = require("./github");
 const github_ci_1 = require("./github_ci");
 const feishu_1 = require("./feishu");
+const telegram_1 = require("./telegram");
 const REMOTE_USER_MODULE_ROOT_DIR = "source-modules";
-const BUILTIN_MODULE_IDS = new Set(["builtin.github_repo", "builtin.github_repo_ci", "builtin.feishu_bot"]);
-const BUILTIN_REMOTE_SOURCE_TYPES = ["github_repo", "github_repo_ci", "feishu_bot"];
+const BUILTIN_MODULE_IDS = new Set(["builtin.github_repo", "builtin.github_repo_ci", "builtin.feishu_bot", "builtin.telegram_bot"]);
+const BUILTIN_REMOTE_SOURCE_TYPES = ["github_repo", "github_repo_ci", "feishu_bot", "telegram_bot"];
 class RemoteSourceModuleRegistry {
     moduleCache = new Map();
     githubRepoModule;
@@ -33,6 +34,9 @@ class RemoteSourceModuleRegistry {
         if (source.sourceType === "feishu_bot") {
             return Promise.resolve(FEISHU_BOT_MODULE);
         }
+        if (source.sourceType === "telegram_bot") {
+            return Promise.resolve(TELEGRAM_BOT_MODULE);
+        }
         if (source.sourceType !== "remote_source") {
             throw new Error(`unsupported source type for remote module: ${source.sourceType}`);
         }
@@ -79,6 +83,9 @@ function builtInModuleIdForSourceType(sourceType) {
     if (sourceType === "feishu_bot") {
         return "builtin.feishu_bot";
     }
+    if (sourceType === "telegram_bot") {
+        return "builtin.telegram_bot";
+    }
     return null;
 }
 function builtinRemoteSourceTypes() {
@@ -543,6 +550,85 @@ const FEISHU_BOT_MODULE = {
         };
     },
 };
+const TELEGRAM_BOT_MODULE = {
+    id: "builtin.telegram_bot",
+    listDeliveryOperations(input) {
+        return (0, telegram_1.telegramDeliveryOperationsForHandle)(input.handle);
+    },
+    async invokeDeliveryOperation(input) {
+        return (0, telegram_1.invokeTelegramDeliveryOperation)(input.handle, input.operation, input.input);
+    },
+    describeCapabilities() {
+        return {
+            sourceKind: "telegram_bot",
+            aliases: ["telegram_bot"],
+            configSchema: [
+                { name: "botToken", type: "string", required: false, description: "Telegram bot token. Prefer tokenEnv for shared/local configuration." },
+                { name: "tokenEnv", type: "string", required: false, description: "Environment variable name containing the Telegram bot token." },
+                { name: "botUsername", type: "string", required: false, description: "Optional bot username used for source host identity." },
+                { name: "chatIds", type: "string[]", required: false, description: "Optional Telegram chat ID allowlist." },
+                { name: "allowedUpdates", type: "string[]", required: false, description: "Optional Telegram Bot API allowed_updates value." },
+                { name: "endpoint", type: "string", required: false, description: "Optional Telegram Bot API endpoint override." },
+            ],
+            metadataFields: [
+                { name: "updateId", type: "string", description: "Telegram update_id." },
+                { name: "chatId", type: "string", description: "Telegram chat ID." },
+                { name: "chatType", type: "string|null", description: "Telegram chat type such as private, group, or channel." },
+                { name: "messageId", type: "string", description: "Telegram message_id." },
+                { name: "messageType", type: "string", description: "Normalized Telegram message type such as text or photo." },
+                { name: "fromId", type: "string|null", description: "Telegram sender user ID when present." },
+                { name: "fromUsername", type: "string|null", description: "Telegram sender username when present." },
+                { name: "fromFirstName", type: "string|null", description: "Telegram sender first_name when present." },
+                { name: "content", type: "string|null", description: "Message text or caption when present." },
+            ],
+            eventVariantExamples: ["message.text", "edited_message.text", "channel_post.photo"],
+        };
+    },
+    validateConfig(source) {
+        (0, telegram_1.parseTelegramSourceConfig)(source);
+    },
+    buildManagedSourceSpec(source) {
+        const config = (0, telegram_1.parseTelegramSourceConfig)(source);
+        return {
+            endpoint: config.endpoint ?? telegram_1.TELEGRAM_BOT_API_ENDPOINT,
+            operation_id: "getUpdates",
+            mode: "poll",
+            args: {
+                timeout: 5,
+                ...(config.botToken ? { botToken: config.botToken } : {}),
+                ...(config.tokenEnv ? { tokenEnv: config.tokenEnv } : {}),
+                ...(config.chatIds && config.chatIds.length > 0 ? { chatIds: config.chatIds } : {}),
+                ...(config.allowedUpdates && config.allowedUpdates.length > 0 ? { allowed_updates: config.allowedUpdates } : {}),
+            },
+            poll_config: {
+                interval_secs: 2,
+                extract_items_pointer: "/result",
+                request_cursor_arg: "offset",
+                cursor_from_item_pointer: "/update_id",
+                cursor_transform: "increment",
+                checkpoint_strategy: {
+                    type: "item_key",
+                    item_key_pointer: "/update_id",
+                },
+            },
+        };
+    },
+    mapRawEvent(rawPayload, source) {
+        const config = (0, telegram_1.parseTelegramSourceConfig)(source);
+        const normalized = (0, telegram_1.normalizeTelegramBotUpdate)(source, config, rawPayload);
+        if (!normalized) {
+            return null;
+        }
+        return {
+            sourceNativeId: normalized.sourceNativeId,
+            eventVariant: normalized.eventVariant,
+            metadata: normalized.metadata ?? {},
+            rawPayload: normalized.rawPayload ?? rawPayload,
+            occurredAt: normalized.occurredAt,
+            deliveryHandle: normalized.deliveryHandle,
+        };
+    },
+};
 function moduleConfigForSource(source) {
     const config = asRecord(source.config);
     if (source.sourceType === "remote_source") {

package/dist/src/sources/telegram.js

@@ -0,0 +1,317 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelegramDeliveryAdapter = exports.TelegramBotApiClient = exports.TELEGRAM_BOT_API_ENDPOINT = void 0;
+exports.telegramDeliveryOperationsForHandle = telegramDeliveryOperationsForHandle;
+exports.invokeTelegramDeliveryOperation = invokeTelegramDeliveryOperation;
+exports.normalizeTelegramBotUpdate = normalizeTelegramBotUpdate;
+exports.parseTelegramSourceConfig = parseTelegramSourceConfig;
+exports.TELEGRAM_BOT_API_ENDPOINT = "https://api.telegram.org";
+class TelegramBotApiClient {
+    client;
+    constructor(client = { fetch: (url, init) => fetch(url, init) }) {
+        this.client = client;
+    }
+    async getUpdates(input) {
+        const endpoint = stripTrailingSlash(input.endpoint ?? exports.TELEGRAM_BOT_API_ENDPOINT);
+        const params = new URLSearchParams();
+        if (input.offset !== undefined) {
+            params.set("offset", String(input.offset));
+        }
+        if (input.timeout !== undefined) {
+            params.set("timeout", String(input.timeout));
+        }
+        if (input.allowedUpdates && input.allowedUpdates.length > 0) {
+            params.set("allowed_updates", JSON.stringify(input.allowedUpdates));
+        }
+        const query = params.toString();
+        const response = await this.client.fetch(`${endpoint}/bot${input.botToken}/getUpdates${query ? `?${query}` : ""}`);
+        const body = await response.text();
+        if (!response.ok) {
+            throw new Error(`Telegram getUpdates failed with status ${response.status}: ${body}`);
+        }
+        const parsed = JSON.parse(body);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("Telegram getUpdates returned a non-object response");
+        }
+        const envelope = parsed;
+        if (envelope.ok !== true) {
+            throw new Error(`Telegram getUpdates returned ok=false: ${body}`);
+        }
+        const result = envelope.result;
+        if (!Array.isArray(result)) {
+            throw new Error("Telegram getUpdates response missing result array");
+        }
+        return result
+            .map((item) => asRecord(item))
+            .filter((item) => Object.keys(item).length > 0);
+    }
+    async sendMessage(input) {
+        const endpoint = stripTrailingSlash(input.endpoint ?? exports.TELEGRAM_BOT_API_ENDPOINT);
+        const body = {
+            chat_id: input.chatId,
+            text: input.text,
+        };
+        if (input.replyToMessageId !== undefined) {
+            body.reply_to_message_id = input.replyToMessageId;
+        }
+        if (input.parseMode) {
+            body.parse_mode = input.parseMode;
+        }
+        const response = await this.client.fetch(`${endpoint}/bot${input.botToken}/sendMessage`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new Error(`Telegram sendMessage failed with status ${response.status}: ${await response.text()}`);
+        }
+    }
+}
+exports.TelegramBotApiClient = TelegramBotApiClient;
+class TelegramDeliveryAdapter {
+    client;
+    constructor(client) {
+        this.client = client ?? new TelegramBotApiClient();
+    }
+    async send(request, attempt) {
+        return invokeTelegramDeliveryOperation(attempt, "send_text", request.payload, this.client);
+    }
+}
+exports.TelegramDeliveryAdapter = TelegramDeliveryAdapter;
+function telegramDeliveryOperationsForHandle(handle) {
+    if (handle.provider !== "telegram") {
+        return [];
+    }
+    if (handle.surface !== "message_reply" && handle.surface !== "chat_message") {
+        return [];
+    }
+    return [{
+            name: "send_text",
+            title: handle.surface === "message_reply" ? "Reply With Text" : "Send Text Message",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["text"],
+                properties: {
+                    text: { type: "string", minLength: 1 },
+                    endpoint: { type: "string", minLength: 1 },
+                    botToken: { type: "string", minLength: 1 },
+                    token: { type: "string", minLength: 1 },
+                    tokenEnv: { type: "string", minLength: 1 },
+                    chatId: { type: "string", minLength: 1 },
+                    chat_id: { type: "string", minLength: 1 },
+                    replyToMessageId: { type: "number" },
+                    reply_to_message_id: { type: "number" },
+                    parseMode: { type: "string", minLength: 1 },
+                    parse_mode: { type: "string", minLength: 1 },
+                },
+            },
+            canonicalTextAlias: true,
+        }];
+}
+async function invokeTelegramDeliveryOperation(handle, operation, input, client = new TelegramBotApiClient()) {
+    if (operation !== "send_text") {
+        throw new Error(`unknown Telegram delivery operation: ${operation}`);
+    }
+    if (handle.provider !== "telegram") {
+        throw new Error(`Telegram delivery operation requires a telegram handle, got ${handle.provider}`);
+    }
+    if (handle.surface !== "message_reply" && handle.surface !== "chat_message") {
+        throw new Error(`deliver send only supports canonical Telegram text surfaces; use deliver invoke for ${handle.surface}`);
+    }
+    const text = asString(input.text);
+    if (!text || text.trim().length === 0) {
+        throw new Error("send_text requires input.text");
+    }
+    const botToken = asString(input.botToken)
+        ?? asString(input.token)
+        ?? tokenFromEnv(asString(input.tokenEnv));
+    if (!botToken) {
+        throw new Error("send_text requires input.botToken, input.token, or input.tokenEnv");
+    }
+    const chatId = stringFromUnknown(input.chatId) ?? stringFromUnknown(input.chat_id) ?? handle.targetRef;
+    const replyToMessageId = numberFromUnknown(input.replyToMessageId)
+        ?? numberFromUnknown(input.reply_to_message_id)
+        ?? (handle.surface === "message_reply" ? numberFromUnknown(handle.threadRef) : undefined);
+    await client.sendMessage({
+        endpoint: asString(input.endpoint) ?? undefined,
+        botToken,
+        chatId,
+        text,
+        replyToMessageId,
+        parseMode: asString(input.parseMode) ?? asString(input.parse_mode) ?? undefined,
+    });
+    return {
+        status: "sent",
+        note: handle.surface === "message_reply" ? "sent Telegram message reply" : "sent Telegram chat message",
+    };
+}
+function normalizeTelegramBotUpdate(source, config, raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return null;
+    }
+    const payload = raw;
+    const updateId = stringFromUnknown(payload.update_id);
+    if (!updateId) {
+        return null;
+    }
+    const selected = selectTelegramMessage(payload);
+    if (!selected) {
+        return null;
+    }
+    const message = selected.message;
+    const messageId = stringFromUnknown(message.message_id);
+    const chat = asRecord(message.chat);
+    const chatId = stringFromUnknown(chat.id);
+    if (!messageId || !chatId) {
+        return null;
+    }
+    if (config.chatIds && config.chatIds.length > 0 && !config.chatIds.includes(chatId)) {
+        return null;
+    }
+    const from = asRecord(message.from);
+    const content = asString(message.text) ?? asString(message.caption);
+    const messageType = telegramMessageType(message);
+    return {
+        sourceId: source.sourceId,
+        sourceNativeId: `telegram:${source.sourceId}:${updateId}`,
+        eventVariant: `${selected.kind}.${messageType}`,
+        occurredAt: fromUnixSeconds(message.date) ?? new Date().toISOString(),
+        metadata: {
+            provider: "telegram",
+            updateId,
+            chatId,
+            chatType: asString(chat.type),
+            messageId,
+            messageType,
+            fromId: stringFromUnknown(from.id),
+            fromUsername: asString(from.username),
+            fromFirstName: asString(from.first_name),
+            content,
+        },
+        rawPayload: payload,
+        deliveryHandle: {
+            provider: "telegram",
+            surface: "message_reply",
+            targetRef: chatId,
+            threadRef: messageId,
+            replyMode: "reply",
+        },
+    };
+}
+function parseTelegramSourceConfig(source) {
+    const config = source.config ?? {};
+    return {
+        endpoint: asString(config.endpoint) ?? asString(config.apiBaseUrl) ?? exports.TELEGRAM_BOT_API_ENDPOINT,
+        botToken: asString(config.botToken) ?? undefined,
+        tokenEnv: asString(config.tokenEnv) ?? undefined,
+        botUsername: asString(config.botUsername) ?? undefined,
+        chatIds: asStringArray(config.chatIds) ?? undefined,
+        allowedUpdates: asStringArray(config.allowedUpdates) ?? undefined,
+    };
+}
+function selectTelegramMessage(payload) {
+    const candidates = [
+        ["message", payload.message],
+        ["edited_message", payload.edited_message],
+        ["channel_post", payload.channel_post],
+        ["edited_channel_post", payload.edited_channel_post],
+    ];
+    for (const [kind, value] of candidates) {
+        const message = asRecord(value);
+        if (Object.keys(message).length > 0) {
+            return { kind, message };
+        }
+    }
+    return null;
+}
+function telegramMessageType(message) {
+    if (typeof message.text === "string") {
+        return "text";
+    }
+    if (typeof message.caption === "string") {
+        return "caption";
+    }
+    if (Array.isArray(message.photo)) {
+        return "photo";
+    }
+    if (message.document && typeof message.document === "object") {
+        return "document";
+    }
+    if (message.audio && typeof message.audio === "object") {
+        return "audio";
+    }
+    if (message.video && typeof message.video === "object") {
+        return "video";
+    }
+    if (message.voice && typeof message.voice === "object") {
+        return "voice";
+    }
+    if (message.sticker && typeof message.sticker === "object") {
+        return "sticker";
+    }
+    return "unknown";
+}
+function fromUnixSeconds(value) {
+    const seconds = numberFromUnknown(value);
+    if (seconds === undefined) {
+        return null;
+    }
+    return new Date(seconds * 1000).toISOString();
+}
+function tokenFromEnv(name) {
+    if (!name) {
+        return null;
+    }
+    return asString(process.env[name]);
+}
+function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+function asStringArray(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => stringFromUnknown(item))
+            .filter((item) => Boolean(item));
+    }
+    if (typeof value === "string") {
+        return value
+            .split(",")
+            .map((item) => item.trim())
+            .filter((item) => item.length > 0);
+    }
+    return null;
+}
+function stringFromUnknown(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return String(value);
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    return null;
+}
+function numberFromUnknown(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return undefined;
+}

package/dist/src/store.js

@@ -7,6 +7,7 @@ exports.AgentInboxStore = void 0;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const store_queries_1 = require("./store_queries");
 const util_1 = require("./util");
 const DRIZZLE_MIGRATIONS_TABLE = "__drizzle_migrations";
 const V1_BASELINE_TAG = "0000_v1_initial";
@@ -130,6 +131,13 @@ class AgentInboxStore {
     save() {
         this.persist();
     }
+    getDatabaseHealth() {
+        return {
+            integrityCheck: String(this.db.pragma("integrity_check", { simple: true })),
+            journalMode: String(this.db.pragma("journal_mode", { simple: true })),
+            foreignKeys: Number(this.db.pragma("foreign_keys", { simple: true })) === 1,
+        };
+    }
     async backupHealthyDatabase() {
         const backupPath = `${this.dbPath}.bak`;
         const tmpPath = `${backupPath}.${process.pid}.tmp`;
@@ -667,40 +675,23 @@ class AgentInboxStore {
         this.persist();
     }
     listSubscriptions(limit) {
-        const rows = typeof limit === "number"
-            ? this.getAll("select * from subscriptions order by created_at asc, subscription_id asc limit ?", [limit])
-            : this.getAll("select * from subscriptions order by created_at asc, subscription_id asc");
+        const query = (0, store_queries_1.buildSubscriptionListQuery)({ limit });
+        const rows = this.getAll(query.sql, query.params);
         return rows.map((row) => this.mapSubscription(row));
     }
     listSubscriptionsFiltered(filters) {
-        const clauses = [];
-        const params = [];
-        if (filters?.sourceId) {
-            clauses.push("source_id = ?");
-            params.push(filters.sourceId);
-        }
-        if (filters?.agentId) {
-            clauses.push("agent_id = ?");
-            params.push(filters.agentId);
-        }
-        const where = clauses.length > 0 ? ` where ${clauses.join(" and ")}` : "";
-        const limitClause = typeof filters?.limit === "number" ? " limit ?" : "";
-        if (typeof filters?.limit === "number") {
-            params.push(filters.limit);
-        }
-        const rows = this.getAll(`select * from subscriptions${where} order by created_at asc, subscription_id asc${limitClause}`, params);
+        const query = (0, store_queries_1.buildSubscriptionListQuery)(filters);
+        const rows = this.getAll(query.sql, query.params);
         return rows.map((row) => this.mapSubscription(row));
     }
     listSubscriptionsForSource(sourceId, limit) {
-        const rows = typeof limit === "number"
-            ? this.getAll("select * from subscriptions where source_id = ? order by created_at asc, subscription_id asc limit ?", [sourceId, limit])
-            : this.getAll("select * from subscriptions where source_id = ? order by created_at asc, subscription_id asc", [sourceId]);
+        const query = (0, store_queries_1.buildSubscriptionListQuery)({ sourceId, limit });
+        const rows = this.getAll(query.sql, query.params);
         return rows.map((row) => this.mapSubscription(row));
     }
     listSubscriptionsForAgent(agentId, limit) {
-        const rows = typeof limit === "number"
-            ? this.getAll("select * from subscriptions where agent_id = ? order by created_at asc, subscription_id asc limit ?", [agentId, limit])
-            : this.getAll("select * from subscriptions where agent_id = ? order by created_at asc, subscription_id asc", [agentId]);
+        const query = (0, store_queries_1.buildSubscriptionListQuery)({ agentId, limit });
+        const rows = this.getAll(query.sql, query.params);
         return rows.map((row) => this.mapSubscription(row));
     }
     listSubscriptionsForHostTrackedResourceRef(hostId, trackedResourceRef) {

package/dist/src/store_queries.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSubscriptionListQuery = buildSubscriptionListQuery;
+function buildSubscriptionListQuery(filters) {
+    const clauses = [];
+    const params = [];
+    if (filters?.sourceId) {
+        clauses.push("source_id = ?");
+        params.push(filters.sourceId);
+    }
+    if (filters?.agentId) {
+        clauses.push("agent_id = ?");
+        params.push(filters.agentId);
+    }
+    const where = clauses.length > 0 ? ` where ${clauses.join(" and ")}` : "";
+    const limitClause = typeof filters?.limit === "number" ? " limit ?" : "";
+    if (typeof filters?.limit === "number") {
+        params.push(filters.limit);
+    }
+    return {
+        sql: `select * from subscriptions${where} order by created_at asc, subscription_id asc${limitClause}`,
+        params,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "@fastify/swagger": "^9.5.2",
-    "@holon-run/uxc-daemon-client": "^0.15.4",
+    "@holon-run/uxc-daemon-client": "^0.15.8",
     "better-sqlite3": "^12.10.0",
     "commander": "^14.0.3",
     "fastify": "^5.6.1",