@aiwg/cli 2026.10.15 → 2026.10.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (286) hide show
  1. package/agentic/code/providers/pi/aiwg-bridge.ts +45 -7
  2. package/dist/src/artifacts/citation-parser.js +7 -6
  3. package/dist/src/artifacts/corpus-tools/citation-densify.js +4 -2
  4. package/dist/src/artifacts/corpus-tools/cli.js +8 -3
  5. package/dist/src/artifacts/corpus-tools/discovery-log.js +26 -24
  6. package/dist/src/artifacts/corpus-tools/expand-cli.js +3 -2
  7. package/dist/src/artifacts/corpus-tools/expand-dates.js +107 -0
  8. package/dist/src/artifacts/corpus-tools/expand-queue.js +4 -1
  9. package/dist/src/artifacts/corpus-tools/expand-review.js +104 -0
  10. package/dist/src/artifacts/corpus-tools/expand-state.js +17 -1
  11. package/dist/src/artifacts/corpus-tools/expand.js +16 -17
  12. package/dist/src/artifacts/corpus-tools/induction-audit.js +7 -6
  13. package/dist/src/artifacts/corpus-tools/integrity-scan.js +3 -3
  14. package/dist/src/artifacts/corpus-tools/radar-shared.js +7 -9
  15. package/dist/src/artifacts/corpus-tools/ref-files.js +11 -0
  16. package/dist/src/artifacts/corpus-tools/resolve-cli.js +11 -3
  17. package/dist/src/artifacts/corpus-tools/resolve.js +42 -11
  18. package/dist/src/artifacts/corpus-tools/retrieval-lab.js +2 -1
  19. package/dist/src/artifacts/corpus-tools/sidecar-lint.js +4 -4
  20. package/dist/src/artifacts/corpus-tools/sidecar-repair.js +2 -1
  21. package/dist/src/artifacts/corpus-views/ref-parser.js +3 -17
  22. package/dist/src/artifacts/graph-query.js +5 -3
  23. package/dist/src/artifacts/hybrid-query.js +11 -2
  24. package/dist/src/artifacts/index-refresh.js +2 -0
  25. package/dist/src/artifacts/query-engine-corpus.js +217 -0
  26. package/dist/src/artifacts/query-engine-discover-output.js +229 -0
  27. package/dist/src/artifacts/query-engine-discover.js +285 -0
  28. package/dist/src/artifacts/query-engine-entries.js +188 -0
  29. package/dist/src/artifacts/query-engine-index.js +249 -0
  30. package/dist/src/artifacts/query-engine-matching.js +143 -0
  31. package/dist/src/artifacts/query-engine-options.js +2 -0
  32. package/dist/src/artifacts/query-engine-rules.js +202 -0
  33. package/dist/src/artifacts/query-engine-scoring.js +436 -0
  34. package/dist/src/artifacts/query-engine-show-card.js +194 -0
  35. package/dist/src/artifacts/query-engine-show-load.js +211 -0
  36. package/dist/src/artifacts/query-engine-show.js +300 -0
  37. package/dist/src/artifacts/query-engine.js +7 -2576
  38. package/dist/src/cli/handlers/daemon.js +17 -1
  39. package/dist/src/cli/handlers/doctor-args.js +10 -5
  40. package/dist/src/cli/handlers/doctor-help.js +4 -1
  41. package/dist/src/cli/handlers/index.js +2 -2
  42. package/dist/src/cli/handlers/mc-agents.js +111 -0
  43. package/dist/src/cli/handlers/mc-args.js +54 -0
  44. package/dist/src/cli/handlers/mc-control.js +227 -0
  45. package/dist/src/cli/handlers/mc-dispatch.js +203 -0
  46. package/dist/src/cli/handlers/mc-help.js +171 -0
  47. package/dist/src/cli/handlers/mc-run.js +343 -0
  48. package/dist/src/cli/handlers/mc-session.js +138 -0
  49. package/dist/src/cli/handlers/mc-status.js +258 -0
  50. package/dist/src/cli/handlers/mc-summary.js +43 -0
  51. package/dist/src/cli/handlers/mc-types.js +3 -0
  52. package/dist/src/cli/handlers/mc-worker.js +205 -0
  53. package/dist/src/cli/handlers/mc.js +12 -1665
  54. package/dist/src/cli/handlers/models-refusal.js +13 -0
  55. package/dist/src/cli/handlers/models-resource-sample.js +10 -0
  56. package/dist/src/cli/handlers/models.js +5 -3
  57. package/dist/src/cli/handlers/regenerate.js +8 -16
  58. package/dist/src/cli/handlers/remove-bundled.js +133 -0
  59. package/dist/src/cli/handlers/remove-options.js +31 -0
  60. package/dist/src/cli/handlers/remove-user.js +174 -0
  61. package/dist/src/cli/handlers/remove.js +201 -0
  62. package/dist/src/cli/handlers/sessions.js +7 -7
  63. package/dist/src/cli/handlers/subcommands-bundles.js +257 -0
  64. package/dist/src/cli/handlers/subcommands-discovery.js +165 -0
  65. package/dist/src/cli/handlers/subcommands-list-format.js +129 -0
  66. package/dist/src/cli/handlers/subcommands-list.js +250 -0
  67. package/dist/src/cli/handlers/subcommands-plugins.js +213 -0
  68. package/dist/src/cli/handlers/subcommands-quickref.js +58 -0
  69. package/dist/src/cli/handlers/subcommands-rlm.js +113 -0
  70. package/dist/src/cli/handlers/subcommands-services.js +66 -0
  71. package/dist/src/cli/handlers/subcommands-storage.js +259 -0
  72. package/dist/src/cli/handlers/subcommands.js +18 -1976
  73. package/dist/src/cli/handlers/update.js +157 -0
  74. package/dist/src/cli/handlers/use.js +14 -4
  75. package/dist/src/cli/handlers/utilities.js +3 -560
  76. package/dist/src/cli/handlers/utility-doctor.js +412 -0
  77. package/dist/src/cli/scope-resolver.js +1 -142
  78. package/dist/src/cli/services/deployment-verification.js +0 -1
  79. package/dist/src/cli/user-scope-mirror.js +173 -0
  80. package/dist/src/config/aiwg-config.js +2 -1
  81. package/dist/src/config/authorization-cli.js +7 -3
  82. package/dist/src/config/dispatch-host-thresholds.js +2 -0
  83. package/dist/src/config/dispatch-thresholds-runtime.d.mts +3 -2
  84. package/dist/src/config/dispatch-thresholds-runtime.mjs +21 -7
  85. package/dist/src/config/framework-aliases.js +12 -0
  86. package/dist/src/config/host-resource-report.d.mts +24 -0
  87. package/dist/src/config/host-resource-report.mjs +110 -0
  88. package/dist/src/config/host-resource-runtime.d.mts +37 -0
  89. package/dist/src/config/host-resource-runtime.mjs +296 -0
  90. package/dist/src/config/installed-selection.js +22 -0
  91. package/dist/src/config/worker-invocation-marker.d.mts +1 -0
  92. package/dist/src/config/worker-invocation-marker.mjs +2 -0
  93. package/dist/src/decision/ensemble-study/artifacts.js +7 -0
  94. package/dist/src/decision/ensemble-study/gate-policy.js +58 -0
  95. package/dist/src/decision/ensemble-study/gates.js +78 -0
  96. package/dist/src/decision/ensemble-study/protocol.js +18 -21
  97. package/dist/src/decision/ensemble-study/score.js +3 -2
  98. package/dist/src/decision/ensemble-study/statistics.js +7 -26
  99. package/dist/src/decision/heldout/access.js +74 -0
  100. package/dist/src/decision/heldout/calibration.js +1 -0
  101. package/dist/src/decision/heldout/collector.js +8 -1
  102. package/dist/src/decision/sensitivity/comparative-gates.js +135 -0
  103. package/dist/src/decision/sensitivity/comparative.js +18 -41
  104. package/dist/src/effects/verifiers/file.js +22 -5
  105. package/dist/src/extensions/claude-attribution.js +82 -0
  106. package/dist/src/extensions/claude-hooks-installer.js +133 -69
  107. package/dist/src/extensions/commands/daemon.js +109 -0
  108. package/dist/src/extensions/commands/definitions.js +5 -89
  109. package/dist/src/gates/evaluate.js +2 -358
  110. package/dist/src/gates/heldout.js +17 -7
  111. package/dist/src/gates/observations.js +363 -0
  112. package/dist/src/gates/pack-composition.js +270 -0
  113. package/dist/src/gates/pack-tightening.js +197 -0
  114. package/dist/src/gates/pack-validation.js +262 -0
  115. package/dist/src/gates/registry-error.js +5 -0
  116. package/dist/src/gates/registry.js +13 -685
  117. package/dist/src/lint/check-patterns.js +163 -0
  118. package/dist/src/lint/checks.js +268 -0
  119. package/dist/src/lint/reference-resolution.js +54 -0
  120. package/dist/src/lint/runner.js +3 -465
  121. package/dist/src/mcp/helpers.mjs +11 -1
  122. package/dist/src/mcp/json-document.mjs +29 -0
  123. package/dist/src/mcp/muse-native-config.mjs +1 -28
  124. package/dist/src/memory/project-registry.js +44 -4
  125. package/dist/src/mission-protocol/worker-review-gate.js +7 -0
  126. package/dist/src/models/worker-plan.js +36 -5
  127. package/dist/src/models/wrapper-deployment.js +25 -12
  128. package/dist/src/models/wrapper-enforcement.js +47 -7
  129. package/dist/src/network-analysis/research.js +2 -1
  130. package/dist/src/plugin/command-ownership.js +34 -0
  131. package/dist/src/plugin/skill-command-frontmatter.js +197 -0
  132. package/dist/src/plugin/skill-command-translator.js +6 -232
  133. package/dist/src/policy/hitl-check.js +14 -4
  134. package/dist/src/policy/hitl-consume.js +54 -0
  135. package/dist/src/policy/hitl-receipt.js +2 -0
  136. package/dist/src/policy/hitl.js +11 -3
  137. package/dist/src/providers/context-output-ownership.js +26 -0
  138. package/dist/src/providers/deployment-ownership.d.mts +19 -0
  139. package/dist/src/providers/deployment-ownership.mjs +226 -0
  140. package/dist/src/providers/deployment-removal.js +200 -0
  141. package/dist/src/providers/provider-context-contracts.js +162 -0
  142. package/dist/src/providers/provider-definition-schema.js +136 -0
  143. package/dist/src/providers/provider-definitions.js +8 -1298
  144. package/dist/src/providers/provider-seeds-1.js +360 -0
  145. package/dist/src/providers/provider-seeds-2.js +387 -0
  146. package/dist/src/providers/provider-seeds-3.js +262 -0
  147. package/dist/src/providers/removal-transaction.js +86 -0
  148. package/dist/src/providers/settings-document.d.mts +3 -0
  149. package/dist/src/providers/settings-document.mjs +47 -0
  150. package/dist/src/providers/settings-removal.js +190 -0
  151. package/dist/src/providers/skill-ownership.d.mts +19 -2
  152. package/dist/src/providers/skill-ownership.mjs +12 -4
  153. package/dist/src/providers/transformation-receipt-integration.js +15 -271
  154. package/dist/src/providers/transformation-receipt-outputs.js +99 -0
  155. package/dist/src/providers/transformation-receipt-source.js +194 -0
  156. package/dist/src/research/clients/arxiv.js +4 -30
  157. package/dist/src/research/clients/base.js +48 -22
  158. package/dist/src/research/identity.js +42 -4
  159. package/dist/src/research/query-cli.js +3 -87
  160. package/dist/src/research/query-options.js +87 -0
  161. package/dist/src/research/reference-match.js +105 -24
  162. package/dist/src/research/services/acquisition.js +9 -7
  163. package/dist/src/research/services/citation.js +5 -2
  164. package/dist/src/research/types.js +2 -0
  165. package/dist/src/rules/activation.mjs +15 -6
  166. package/dist/src/rules/core-startup.mjs +2 -2
  167. package/dist/src/serve/mission-conductor.js +52 -4
  168. package/dist/src/serve/mission-summary.js +56 -0
  169. package/dist/src/sessions/adapters/grok-build-native.js +23 -0
  170. package/dist/src/sessions/adapters/grok-build.js +14 -7
  171. package/dist/src/sessions/workspace-discovery.js +5 -5
  172. package/dist/src/smiths/context-pipeline/aiwg-md.js +39 -46
  173. package/dist/src/smiths/context-pipeline/claude-hook.js +1 -1
  174. package/dist/src/smiths/context-pipeline/code-regions.js +28 -0
  175. package/dist/src/smiths/context-pipeline/context-file-safety.js +3 -0
  176. package/dist/src/smiths/context-pipeline/finalization.js +81 -51
  177. package/dist/src/smiths/context-pipeline/generator.js +10 -11
  178. package/dist/src/smiths/context-pipeline/managed-hook.js +1 -1
  179. package/dist/src/smiths/context-pipeline/muse-bridge.js +2 -2
  180. package/dist/src/smiths/context-pipeline/provider-policy.js +6 -12
  181. package/dist/src/smiths/context-pipeline/workspace-audit.js +299 -0
  182. package/dist/src/smiths/context-pipeline/workspace-bootstrap.js +148 -0
  183. package/dist/src/smiths/context-pipeline/workspace-context-shared.js +111 -0
  184. package/dist/src/smiths/context-pipeline/workspace-context.js +8 -1373
  185. package/dist/src/smiths/context-pipeline/workspace-doctor.js +192 -0
  186. package/dist/src/smiths/context-pipeline/workspace-document.js +201 -0
  187. package/dist/src/smiths/context-pipeline/workspace-extraction.js +205 -0
  188. package/dist/src/smiths/context-pipeline/workspace-migration.js +250 -0
  189. package/dist/src/smiths/hook-bridge/index.js +9 -0
  190. package/package.json +13 -1
  191. package/schemas/decision/D17StudyProtocol.v1.schema.json +39 -67
  192. package/schemas/decision/D29Study.v10.schema.json +65 -0
  193. package/tools/agents/deploy-agents.mjs +24 -675
  194. package/tools/agents/deploy-command-mirrors.mjs +229 -0
  195. package/tools/agents/deploy-options.mjs +258 -0
  196. package/tools/agents/deploy-support.mjs +165 -0
  197. package/tools/agents/providers/base-addon-discovery.mjs +139 -0
  198. package/tools/agents/providers/base-behaviors.mjs +168 -0
  199. package/tools/agents/providers/base-context.mjs +205 -0
  200. package/tools/agents/providers/base-contract.mjs +116 -0
  201. package/tools/agents/providers/base-files.mjs +252 -0
  202. package/tools/agents/providers/base-flat-artifacts.mjs +233 -0
  203. package/tools/agents/providers/base-framework-discovery.mjs +309 -0
  204. package/tools/agents/providers/base-frontmatter.mjs +196 -0
  205. package/tools/agents/providers/base-inventory.mjs +269 -0
  206. package/tools/agents/providers/base-kernel-skills.mjs +354 -0
  207. package/tools/agents/providers/base-migrations.mjs +258 -0
  208. package/tools/agents/providers/base-models-platforms.mjs +273 -0
  209. package/tools/agents/providers/base-rule-index.mjs +450 -0
  210. package/tools/agents/providers/base-runtime.mjs +60 -0
  211. package/tools/agents/providers/base-skill-copy.mjs +273 -0
  212. package/tools/agents/providers/base.mjs +16 -3364
  213. package/tools/agents/providers/claude-post-deploy.mjs +20 -1
  214. package/tools/agents/providers/context-write.mjs +4 -0
  215. package/tools/agents/providers/hermes-startup.mjs +0 -5
  216. package/tools/agents/providers/muse.mjs +7 -2
  217. package/tools/agents/providers/pi.mjs +3 -1
  218. package/tools/agents/providers/rule-delivery-surface.mjs +359 -0
  219. package/tools/agents/providers/rule-delivery.mjs +20 -1144
  220. package/tools/agents/providers/rule-deployment-commit.mjs +148 -0
  221. package/tools/agents/providers/rule-deployment-prepare.mjs +461 -0
  222. package/tools/agents/providers/rule-deployment-state.mjs +300 -0
  223. package/tools/agents/providers/rule-projection.mjs +3 -0
  224. package/tools/daemon/README.md +511 -0
  225. package/tools/daemon/adapters/base-adapter.mjs +84 -0
  226. package/tools/daemon/adapters/webhook-adapter.mjs +107 -0
  227. package/tools/daemon/agent-supervisor.mjs +299 -0
  228. package/tools/daemon/automation-engine.mjs +310 -0
  229. package/tools/daemon/autonomous-engine.mjs +346 -0
  230. package/tools/daemon/behavior-loader.mjs +316 -0
  231. package/tools/daemon/behavior.mjs +174 -0
  232. package/tools/daemon/concierge/intent-router.mjs +401 -0
  233. package/tools/daemon/concierge/orchestrator.mjs +272 -0
  234. package/tools/daemon/concierge/response-translator.mjs +462 -0
  235. package/tools/daemon/config.mjs +377 -0
  236. package/tools/daemon/cron-scheduler.mjs +178 -0
  237. package/tools/daemon/daemon-main.mjs +1169 -0
  238. package/tools/daemon/event-router.mjs +84 -0
  239. package/tools/daemon/file-watcher.mjs +383 -0
  240. package/tools/daemon/index.mjs +1181 -0
  241. package/tools/daemon/init-profile.mjs +124 -0
  242. package/tools/daemon/ipc-client.mjs +197 -0
  243. package/tools/daemon/ipc-ops-handlers.mjs +236 -0
  244. package/tools/daemon/ipc-server.mjs +275 -0
  245. package/tools/daemon/maintenance-owner.mjs +79 -0
  246. package/tools/daemon/memory-manager.mjs +386 -0
  247. package/tools/daemon/message-router.mjs +194 -0
  248. package/tools/daemon/provider-watcher.mjs +585 -0
  249. package/tools/daemon/pty-adapter.mjs +420 -0
  250. package/tools/daemon/repl-chat.mjs +359 -0
  251. package/tools/daemon/resource-bounds.mjs +88 -0
  252. package/tools/daemon/sandbox-transport.mjs +295 -0
  253. package/tools/daemon/scheduled-task-runner.mjs +535 -0
  254. package/tools/daemon/task-store.mjs +450 -0
  255. package/tools/daemon/tmux-manager.mjs +324 -0
  256. package/tools/daemon/update-policy.mjs +517 -0
  257. package/tools/daemon/web-server.mjs +399 -0
  258. package/tools/daemon/web-ui/index.html +585 -0
  259. package/tools/daemon/web-ui/styles.css +156 -0
  260. package/tools/docker/Dockerfile.daemon +35 -0
  261. package/tools/docker/container-manager.mjs +291 -0
  262. package/tools/messaging/adapter-registry.mjs +230 -0
  263. package/tools/messaging/adapters/base.mjs +326 -0
  264. package/tools/messaging/adapters/discord.mjs +462 -0
  265. package/tools/messaging/adapters/slack.mjs +402 -0
  266. package/tools/messaging/adapters/telegram.mjs +552 -0
  267. package/tools/messaging/chat-handler.mjs +297 -0
  268. package/tools/messaging/command-router.mjs +269 -0
  269. package/tools/messaging/event-bus.mjs +199 -0
  270. package/tools/messaging/index.mjs +456 -0
  271. package/tools/messaging/message-formatter.mjs +320 -0
  272. package/tools/messaging/room-manager.mjs +277 -0
  273. package/tools/messaging/types.mjs +94 -0
  274. package/tools/providers/pi-bridge-policy.mjs +4 -0
  275. package/tools/ralph-external/daemon-supervisor.mjs +394 -0
  276. package/tools/ralph-external/lib/behavior-registry.mjs +270 -0
  277. package/tools/ralph-external/lib/worker-invocation-processes.mjs +7 -4
  278. package/tools/ralph-external/lib/worker-isolation-args.mjs +217 -0
  279. package/tools/ralph-external/lib/worker-isolation-status.mjs +19 -0
  280. package/tools/ralph-external/lib/worker-isolation.mjs +11 -237
  281. package/tools/ralph-external/lib/worker-overflow.mjs +10 -2
  282. package/tools/ralph-external/lib/worker-termination.mjs +15 -8
  283. package/tools/ralph-external/lib/worker-unit-cleanup.mjs +72 -0
  284. package/tools/ralph-external/session-launcher.mjs +7 -7
  285. package/tools/scripts/resource-preflight.mjs +3 -242
  286. package/vscode-extension/schemas/aiwg.config.v1.json +2 -4
@@ -0,0 +1,552 @@
1
+ /**
2
+ * Telegram Bot API adapter for AIWG messaging.
3
+ *
4
+ * Implements the MessagingAdapter interface using raw fetch() to interact
5
+ * with the Telegram Bot API. Supports sending formatted messages with HTML,
6
+ * inline keyboard buttons, long-polling for inbound commands, and message updates.
7
+ *
8
+ * @implements @.aiwg/architecture/adrs/ADR-messaging-bot-mode.md
9
+ */
10
+
11
+ import { BaseAdapter } from './base.mjs';
12
+ import { getSeverityEmoji } from '../message-formatter.mjs';
13
+
14
+ /**
15
+ * @typedef {Object} TelegramConfig
16
+ * @property {string} botToken - Telegram bot token
17
+ * @property {string} defaultChatId - Default chat ID for messages
18
+ * @property {boolean} [pollingEnabled] - Enable long-polling for commands
19
+ * @property {number} [pollingTimeout] - Polling timeout in seconds (default: 30)
20
+ */
21
+
22
+ /**
23
+ * Telegram Bot API adapter.
24
+ */
25
+ export class TelegramAdapter extends BaseAdapter {
26
+ /** @type {string} */
27
+ #botToken;
28
+
29
+ /** @type {string} */
30
+ #defaultChatId;
31
+
32
+ /** @type {boolean} */
33
+ #pollingEnabled;
34
+
35
+ /** @type {number} */
36
+ #pollingTimeout;
37
+
38
+ /** @type {string} */
39
+ #apiBase;
40
+
41
+ /** @type {AbortController|null} */
42
+ #pollingController = null;
43
+
44
+ /** @type {number} */
45
+ #updateOffset = 0;
46
+
47
+ /** @type {Map<string, {chat_id: string, message_id: number}>} */
48
+ #messageIdMap = new Map();
49
+
50
+ /**
51
+ * Create a Telegram adapter.
52
+ *
53
+ * @param {TelegramConfig} config
54
+ */
55
+ constructor(config = {}) {
56
+ super('telegram');
57
+
58
+ // Load from config or environment variables
59
+ this.#botToken = config.botToken || config.token || process.env.AIWG_TELEGRAM_TOKEN;
60
+ this._setSensitiveValues(this.#botToken);
61
+ this.#defaultChatId = config.defaultChatId || process.env.AIWG_TELEGRAM_CHAT_ID;
62
+ this.#pollingEnabled = config.pollingEnabled ?? config.polling_enabled ?? false;
63
+ this.#pollingTimeout = config.pollingTimeout ?? 30;
64
+
65
+ if (!this.#botToken) {
66
+ throw new Error('Telegram bot token is required (config.botToken or AIWG_TELEGRAM_TOKEN)');
67
+ }
68
+
69
+ // Multi-room: register rooms from config, or use defaultChatId as single room
70
+ if (Array.isArray(config.rooms) && config.rooms.length > 0) {
71
+ for (const room of config.rooms) {
72
+ const chatId = room.chat_id || room.chatId;
73
+ if (chatId) {
74
+ this.addRoom(chatId, {
75
+ label: room.label || room.name || chatId,
76
+ isDefault: room.is_default ?? room.isDefault ?? false,
77
+ purpose: room.purpose || 'interactive',
78
+ });
79
+ }
80
+ }
81
+ // Use first default room or first room as the fallback defaultChatId
82
+ if (!this.#defaultChatId) {
83
+ const defaultRoom = config.rooms.find(r => r.is_default || r.isDefault) || config.rooms[0];
84
+ this._setSensitiveValues(this.#botToken);
85
+ this.#defaultChatId = defaultRoom.chat_id || defaultRoom.chatId;
86
+ }
87
+ }
88
+
89
+ if (!this.#defaultChatId && this.getRooms().size === 0) {
90
+ throw new Error('Telegram requires at least one chat ID (config.defaultChatId, config.rooms, or AIWG_TELEGRAM_CHAT_ID)');
91
+ }
92
+
93
+ // If we have a defaultChatId but no rooms registered, auto-create a single room
94
+ if (this.#defaultChatId && this.getRooms().size === 0) {
95
+ this.addRoom(this.#defaultChatId, {
96
+ label: 'default',
97
+ isDefault: true,
98
+ purpose: 'interactive',
99
+ });
100
+ }
101
+
102
+ this.#apiBase = `https://api.telegram.org/bot${this.#botToken}`;
103
+ }
104
+
105
+ /**
106
+ * Initialize the Telegram adapter.
107
+ *
108
+ * Validates the bot token by calling getMe and starts polling if enabled.
109
+ *
110
+ * @returns {Promise<void>}
111
+ */
112
+ async initialize() {
113
+ try {
114
+ // Validate token by calling getMe
115
+ const response = await fetch(`${this.#apiBase}/getMe`);
116
+ const data = await response.json();
117
+
118
+ if (!data.ok) {
119
+ throw new Error(`Telegram API error: ${data.description}`);
120
+ }
121
+
122
+ console.log(this._redactText(`[telegram] Connected as bot: ${data.result.username}`));
123
+ this._setConnected();
124
+
125
+ // Start polling if enabled
126
+ if (this.#pollingEnabled) {
127
+ this.#startPolling();
128
+ }
129
+ } catch (error) {
130
+ error = this._redactError(error);
131
+ this._recordError(error);
132
+ throw new Error(`Failed to initialize Telegram adapter: ${error.message}`);
133
+ }
134
+ }
135
+
136
+ /**
137
+ * Shutdown the Telegram adapter.
138
+ *
139
+ * Stops polling and marks adapter as disconnected.
140
+ *
141
+ * @returns {Promise<void>}
142
+ */
143
+ async shutdown() {
144
+ this.#stopPolling();
145
+ this._setDisconnected();
146
+ console.log('[telegram] Adapter shut down');
147
+ }
148
+
149
+ /**
150
+ * Send a formatted message to a Telegram chat.
151
+ *
152
+ * @param {import('../message-formatter.mjs').AiwgMessage} message
153
+ * @param {string} [channel] - Chat ID (defaults to configured defaultChatId)
154
+ * @returns {Promise<import('./base.mjs').MessageResult>}
155
+ */
156
+ async send(message, channel) {
157
+ const chatId = channel || this.#defaultChatId;
158
+
159
+ try {
160
+ const text = this.#formatMessageAsHtml(message);
161
+ const payload = {
162
+ chat_id: chatId,
163
+ text,
164
+ parse_mode: 'HTML',
165
+ };
166
+
167
+ // Add reply_to_message_id if threadId is provided
168
+ if (message.threadId) {
169
+ const threadRef = this.#messageIdMap.get(message.threadId);
170
+ if (threadRef && threadRef.chat_id === chatId) {
171
+ payload.reply_to_message_id = threadRef.message_id;
172
+ }
173
+ }
174
+
175
+ // Add inline keyboard if actions are provided
176
+ if (message.actions && message.actions.length > 0) {
177
+ payload.reply_markup = {
178
+ inline_keyboard: [
179
+ message.actions.map((action) => ({
180
+ text: action.label,
181
+ callback_data: action.command,
182
+ })),
183
+ ],
184
+ };
185
+ }
186
+
187
+ const response = await this.#apiCall('sendMessage', payload);
188
+
189
+ if (!response.ok) {
190
+ throw new Error(response.description || 'Unknown Telegram API error');
191
+ }
192
+
193
+ const messageId = `${response.result.chat.id}:${response.result.message_id}`;
194
+
195
+ // Store message ID for potential updates or threading
196
+ this.#messageIdMap.set(messageId, {
197
+ chat_id: response.result.chat.id,
198
+ message_id: response.result.message_id,
199
+ });
200
+
201
+ // If this message has a threadId, store it too for future threading
202
+ if (message.threadId) {
203
+ this.#messageIdMap.set(message.threadId, {
204
+ chat_id: response.result.chat.id,
205
+ message_id: response.result.message_id,
206
+ });
207
+ }
208
+
209
+ this._recordSend();
210
+
211
+ return {
212
+ messageId,
213
+ channelId: String(response.result.chat.id),
214
+ success: true,
215
+ };
216
+ } catch (error) {
217
+ error = this._redactError(error);
218
+ this._recordError(error);
219
+ return {
220
+ messageId: '',
221
+ channelId: chatId,
222
+ success: false,
223
+ error: error.message,
224
+ };
225
+ }
226
+ }
227
+
228
+ /**
229
+ * Update an existing message.
230
+ *
231
+ * @param {string} messageId - Format: "chat_id:message_id"
232
+ * @param {import('../message-formatter.mjs').AiwgMessage} message
233
+ * @returns {Promise<void>}
234
+ */
235
+ async update(messageId, message) {
236
+ try {
237
+ const ref = this.#messageIdMap.get(messageId);
238
+ if (!ref) {
239
+ throw new Error(`Message ID not found: ${messageId}`);
240
+ }
241
+
242
+ const text = this.#formatMessageAsHtml(message);
243
+ const payload = {
244
+ chat_id: ref.chat_id,
245
+ message_id: ref.message_id,
246
+ text,
247
+ parse_mode: 'HTML',
248
+ };
249
+
250
+ // Update inline keyboard if actions are provided
251
+ if (message.actions && message.actions.length > 0) {
252
+ payload.reply_markup = {
253
+ inline_keyboard: [
254
+ message.actions.map((action) => ({
255
+ text: action.label,
256
+ callback_data: action.command,
257
+ })),
258
+ ],
259
+ };
260
+ }
261
+
262
+ const response = await this.#apiCall('editMessageText', payload);
263
+
264
+ if (!response.ok) {
265
+ throw new Error(response.description || 'Unknown Telegram API error');
266
+ }
267
+ } catch (error) {
268
+ error = this._redactError(error);
269
+ this._recordError(error);
270
+ throw new Error(`Failed to update Telegram message: ${error.message}`);
271
+ }
272
+ }
273
+
274
+ // ========================================================================
275
+ // Private methods
276
+ // ========================================================================
277
+
278
+ /**
279
+ * Make a Telegram Bot API call.
280
+ *
281
+ * @param {string} method - API method name
282
+ * @param {Object} payload - Request payload
283
+ * @returns {Promise<any>}
284
+ */
285
+ async #apiCall(method, payload) {
286
+ const url = `${this.#apiBase}/${method}`;
287
+
288
+ const response = await fetch(url, {
289
+ method: 'POST',
290
+ headers: {
291
+ 'Content-Type': 'application/json',
292
+ },
293
+ body: JSON.stringify(payload),
294
+ });
295
+
296
+ const data = await response.json();
297
+
298
+ // Handle rate limiting
299
+ if (response.status === 429) {
300
+ const retryAfter = data.parameters?.retry_after || 1;
301
+ console.warn(`[telegram] Rate limited. Retrying after ${retryAfter}s`);
302
+ await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
303
+ return this.#apiCall(method, payload);
304
+ }
305
+
306
+ return data;
307
+ }
308
+
309
+ /**
310
+ * Format an AiwgMessage as HTML text for Telegram.
311
+ *
312
+ * @param {import('../message-formatter.mjs').AiwgMessage} message
313
+ * @returns {string}
314
+ */
315
+ #formatMessageAsHtml(message) {
316
+ const emoji = getSeverityEmoji(message.severity);
317
+ const parts = [];
318
+
319
+ // Title with emoji
320
+ parts.push(`${emoji} <b>${this.#escapeHtml(message.title)}</b>\n`);
321
+
322
+ // Body
323
+ if (message.body) {
324
+ parts.push(`${this.#escapeHtml(message.body)}\n`);
325
+ }
326
+
327
+ // Fields
328
+ if (message.fields && message.fields.length > 0) {
329
+ parts.push('');
330
+ for (const field of message.fields) {
331
+ parts.push(
332
+ `<b>${this.#escapeHtml(field.label)}:</b> ${this.#escapeHtml(field.value)}`
333
+ );
334
+ }
335
+ }
336
+
337
+ // Code block
338
+ if (message.codeBlock) {
339
+ parts.push('');
340
+ parts.push(`<pre>${this.#escapeHtml(message.codeBlock)}</pre>`);
341
+ }
342
+
343
+ // Link
344
+ if (message.linkUrl && message.linkText) {
345
+ parts.push('');
346
+ parts.push(`<a href="${this.#escapeHtml(message.linkUrl)}">${this.#escapeHtml(message.linkText)}</a>`);
347
+ }
348
+
349
+ // Footer
350
+ parts.push('');
351
+ parts.push(`<i>${this.#escapeHtml(message.project)} • ${this.#escapeHtml(message.timestamp)}</i>`);
352
+
353
+ return parts.join('\n');
354
+ }
355
+
356
+ /**
357
+ * Escape HTML special characters for Telegram HTML mode.
358
+ *
359
+ * @param {string} text
360
+ * @returns {string}
361
+ */
362
+ #escapeHtml(text) {
363
+ return String(text)
364
+ .replace(/&/g, '&amp;')
365
+ .replace(/</g, '&lt;')
366
+ .replace(/>/g, '&gt;');
367
+ }
368
+
369
+ /**
370
+ * Start long-polling for updates.
371
+ */
372
+ #startPolling() {
373
+ if (this.#pollingController) {
374
+ return; // Already polling
375
+ }
376
+
377
+ this.#pollingController = new AbortController();
378
+ console.log('[telegram] Starting long-polling for commands');
379
+
380
+ this.#pollLoop();
381
+ }
382
+
383
+ /**
384
+ * Stop long-polling.
385
+ */
386
+ #stopPolling() {
387
+ if (this.#pollingController) {
388
+ this.#pollingController.abort();
389
+ this.#pollingController = null;
390
+ console.log('[telegram] Stopped long-polling');
391
+ }
392
+ }
393
+
394
+ /**
395
+ * Long-polling loop.
396
+ */
397
+ async #pollLoop() {
398
+ while (this.#pollingController && !this.#pollingController.signal.aborted) {
399
+ try {
400
+ await this.#pollOnce();
401
+ } catch (error) {
402
+ error = this._redactError(error);
403
+ if (error.name === 'AbortError') {
404
+ break;
405
+ }
406
+ console.error('[telegram] Polling error:', error);
407
+ this._recordError(error);
408
+ // Wait before retrying
409
+ await new Promise((resolve) => setTimeout(resolve, 5000));
410
+ }
411
+ }
412
+ }
413
+
414
+ /**
415
+ * Poll for updates once.
416
+ */
417
+ async #pollOnce() {
418
+ const payload = {
419
+ offset: this.#updateOffset,
420
+ timeout: this.#pollingTimeout,
421
+ allowed_updates: ['message', 'callback_query'],
422
+ };
423
+
424
+ const controller = new AbortController();
425
+ const timeoutId = setTimeout(() => controller.abort(), (this.#pollingTimeout + 10) * 1000);
426
+
427
+ try {
428
+ const response = await fetch(`${this.#apiBase}/getUpdates`, {
429
+ method: 'POST',
430
+ headers: {
431
+ 'Content-Type': 'application/json',
432
+ },
433
+ body: JSON.stringify(payload),
434
+ signal: controller.signal,
435
+ });
436
+
437
+ clearTimeout(timeoutId);
438
+
439
+ const data = await response.json();
440
+
441
+ if (!data.ok) {
442
+ throw new Error(`Telegram API error: ${data.description}`);
443
+ }
444
+
445
+ const updates = data.result || [];
446
+
447
+ for (const update of updates) {
448
+ this.#updateOffset = Math.max(this.#updateOffset, update.update_id + 1);
449
+ await this.#handleUpdate(update);
450
+ }
451
+ } catch (error) {
452
+ error = this._redactError(error);
453
+ clearTimeout(timeoutId);
454
+ if (error.name !== 'AbortError') {
455
+ throw error;
456
+ }
457
+ }
458
+ }
459
+
460
+ /**
461
+ * Handle a Telegram update.
462
+ *
463
+ * @param {Object} update
464
+ */
465
+ async #handleUpdate(update) {
466
+ try {
467
+ // Handle text messages (commands)
468
+ if (update.message?.text) {
469
+ await this.#handleMessage(update.message);
470
+ }
471
+
472
+ // Handle callback queries (button presses)
473
+ if (update.callback_query) {
474
+ await this.#handleCallbackQuery(update.callback_query);
475
+ }
476
+ } catch (error) {
477
+ error = this._redactError(error);
478
+ console.error('[telegram] Error handling update:', error);
479
+ this._recordError(error);
480
+ }
481
+ }
482
+
483
+ /**
484
+ * Handle a text message (parse commands or dispatch free-text).
485
+ *
486
+ * @param {Object} message
487
+ */
488
+ async #handleMessage(message) {
489
+ const text = message.text.trim();
490
+
491
+ const context = {
492
+ chatId: String(message.chat.id),
493
+ messageId: message.message_id,
494
+ from: {
495
+ id: message.from.id,
496
+ username: message.from.username,
497
+ firstName: message.from.first_name,
498
+ },
499
+ };
500
+
501
+ // Parse bot commands (format: /command or /command@botname)
502
+ const commandMatch = text.match(/^\/([a-z_]+)(?:@\w+)?\s*(.*)/i);
503
+ if (commandMatch) {
504
+ const command = commandMatch[1];
505
+ const argsText = commandMatch[2];
506
+ const args = argsText ? argsText.split(/\s+/) : [];
507
+
508
+ await this._dispatchCommand(command, args, context);
509
+ return;
510
+ }
511
+
512
+ // Non-command free-text message → dispatch to message handlers
513
+ if (this.hasMessageHandlers()) {
514
+ await this._dispatchMessage(text, context);
515
+ }
516
+ }
517
+
518
+ /**
519
+ * Handle a callback query (button press).
520
+ *
521
+ * @param {Object} callbackQuery
522
+ */
523
+ async #handleCallbackQuery(callbackQuery) {
524
+ const data = callbackQuery.data;
525
+
526
+ // Parse as command
527
+ const parts = data.trim().split(/\s+/);
528
+ const command = parts[0];
529
+ const args = parts.slice(1);
530
+
531
+ const context = {
532
+ chatId: String(callbackQuery.message.chat.id),
533
+ messageId: callbackQuery.message.message_id,
534
+ callbackQueryId: callbackQuery.id,
535
+ from: {
536
+ id: callbackQuery.from.id,
537
+ username: callbackQuery.from.username,
538
+ firstName: callbackQuery.from.first_name,
539
+ },
540
+ };
541
+
542
+ await this._dispatchCommand(command, args, context);
543
+
544
+ // Acknowledge callback query
545
+ await this.#apiCall('answerCallbackQuery', {
546
+ callback_query_id: callbackQuery.id,
547
+ });
548
+ }
549
+ }
550
+
551
+ // Export as both default and named
552
+ export default TelegramAdapter;