typeclaw 0.39.2 → 0.39.4

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 (102) hide show
  1. package/auth.schema.json +110 -0
  2. package/package.json +2 -2
  3. package/secrets.schema.json +110 -0
  4. package/src/agent/index.ts +39 -18
  5. package/src/agent/model-fallback.ts +13 -4
  6. package/src/agent/plugin-tools.ts +12 -12
  7. package/src/agent/provider-error.ts +36 -1
  8. package/src/agent/session-origin.ts +2 -0
  9. package/src/agent/subagents.ts +29 -2
  10. package/src/agent/throttle-circuit.ts +50 -0
  11. package/src/agent/todo/store.ts +21 -1
  12. package/src/agent/tools/channel-reply.ts +18 -5
  13. package/src/agent/tools/channel-send.ts +13 -2
  14. package/src/agent/turn-runner.ts +162 -0
  15. package/src/bundled-plugins/doc-render/render.ts +2 -2
  16. package/src/bundled-plugins/github-cli-auth/approve-idempotency.ts +40 -18
  17. package/src/bundled-plugins/memory/README.md +12 -12
  18. package/src/bundled-plugins/memory/append-tool.ts +58 -6
  19. package/src/bundled-plugins/memory/dreaming.ts +1 -1
  20. package/src/bundled-plugins/memory/fragment-parser.ts +10 -3
  21. package/src/bundled-plugins/memory/load-memory.ts +28 -2
  22. package/src/bundled-plugins/memory/memory-logger.ts +14 -2
  23. package/src/bundled-plugins/memory/search-tool.ts +50 -7
  24. package/src/bundled-plugins/memory/stream-events.ts +23 -0
  25. package/src/bundled-plugins/memory/vector/hybrid.ts +9 -2
  26. package/src/bundled-plugins/security/index.ts +24 -1
  27. package/src/bundled-plugins/security/policies/cron-promotion.ts +94 -62
  28. package/src/bundled-plugins/security/policies/plugin-addition.ts +2 -4
  29. package/src/bundled-plugins/security/policies/role-promotion.ts +2 -4
  30. package/src/channels/adapters/discord-author-resolver.ts +52 -0
  31. package/src/channels/adapters/discord-bot.ts +1 -1
  32. package/src/channels/adapters/discord-channel-resolver.ts +44 -0
  33. package/src/channels/adapters/discord-classify.ts +121 -0
  34. package/src/channels/adapters/discord-reactions.ts +138 -0
  35. package/src/channels/adapters/discord.ts +416 -0
  36. package/src/channels/adapters/github/outbound.ts +23 -4
  37. package/src/channels/adapters/kakaotalk.ts +8 -1
  38. package/src/channels/adapters/line.ts +1 -1
  39. package/src/channels/adapters/slack-author-resolver.ts +54 -0
  40. package/src/channels/adapters/slack-bot.ts +3 -1
  41. package/src/channels/adapters/slack-channel-resolver.ts +49 -0
  42. package/src/channels/adapters/slack-classify.ts +83 -0
  43. package/src/channels/adapters/slack-reactions.ts +126 -0
  44. package/src/channels/adapters/slack.ts +416 -0
  45. package/src/channels/adapters/telegram-bot.ts +2 -1
  46. package/src/channels/adapters/webex-bot.ts +31 -27
  47. package/src/channels/adapters/webex-prefetch-limiter.ts +120 -0
  48. package/src/channels/adapters/webex.ts +81 -31
  49. package/src/channels/github-review-turn-ledger.ts +32 -0
  50. package/src/channels/github-verdict-activity.ts +60 -0
  51. package/src/channels/index.ts +6 -0
  52. package/src/channels/manager.ts +168 -37
  53. package/src/channels/pr-verdict-activity-bridge.ts +43 -0
  54. package/src/channels/router.ts +295 -13
  55. package/src/channels/schema.ts +4 -0
  56. package/src/channels/types.ts +25 -2
  57. package/src/cli/builtins.ts +6 -31
  58. package/src/cli/channel.ts +170 -18
  59. package/src/cli/command-meta.ts +93 -0
  60. package/src/cli/help.ts +24 -0
  61. package/src/cli/index.ts +45 -10
  62. package/src/cli/init.ts +2 -0
  63. package/src/cli/update-check.ts +14 -0
  64. package/src/cli/update-notify.ts +91 -0
  65. package/src/cli/update-suppression.ts +19 -0
  66. package/src/config/channels-mutation.ts +3 -1
  67. package/src/config/config.ts +78 -1
  68. package/src/config/index.ts +1 -0
  69. package/src/container/start.ts +52 -8
  70. package/src/doctor/channel-checks.ts +57 -3
  71. package/src/hostd/daemon.ts +77 -31
  72. package/src/hostd/index.ts +11 -1
  73. package/src/hostd/paths.ts +4 -0
  74. package/src/hostd/protocol.ts +15 -2
  75. package/src/hostd/spawn.ts +53 -19
  76. package/src/init/cli-version.ts +1 -1
  77. package/src/init/discord-auth.ts +50 -0
  78. package/src/init/index.ts +94 -4
  79. package/src/init/reconcile-plugin-deps.ts +30 -5
  80. package/src/init/run-owner-claim.ts +2 -0
  81. package/src/init/slack-auth.ts +51 -0
  82. package/src/mcp/manager.ts +94 -7
  83. package/src/mcp/tools.ts +7 -4
  84. package/src/permissions/permissions.ts +12 -0
  85. package/src/permissions/resolve.ts +2 -0
  86. package/src/role-claim/match-rule.ts +2 -0
  87. package/src/run/codex-fetch-observer.ts +11 -6
  88. package/src/run/index.ts +74 -29
  89. package/src/secrets/discord-store.ts +96 -0
  90. package/src/secrets/oauth-xai.ts +2 -2
  91. package/src/secrets/schema.ts +34 -0
  92. package/src/secrets/slack-store.ts +96 -0
  93. package/src/server/command-runner.ts +21 -0
  94. package/src/server/index.ts +27 -2
  95. package/src/skills/typeclaw-channels/SKILL.md +1 -1
  96. package/src/skills/typeclaw-config/SKILL.md +1 -0
  97. package/src/skills/typeclaw-cron/SKILL.md +20 -4
  98. package/src/skills/typeclaw-permissions/SKILL.md +18 -6
  99. package/src/tui/format.ts +0 -19
  100. package/src/tui/index.ts +2 -8
  101. package/src/update/check.ts +192 -0
  102. package/typeclaw.schema.json +332 -0
@@ -0,0 +1,416 @@
1
+ import { basename } from 'node:path'
2
+
3
+ import {
4
+ SlackClient,
5
+ SlackListener,
6
+ type SlackMessage,
7
+ type SlackRTMMessageEvent,
8
+ type SlackRTMReactionEvent,
9
+ } from 'agent-messenger/slack'
10
+
11
+ import {
12
+ MEMBERSHIP_ENUMERATION_CAP,
13
+ type MembershipResolver,
14
+ type MembershipResolverFailure,
15
+ type MembershipResolverResult,
16
+ } from '@/channels/membership'
17
+ import { deriveMembershipFromHistory } from '@/channels/membership-from-history'
18
+ import type { ChannelRouter } from '@/channels/router'
19
+ import type { ChannelAdapterConfig } from '@/channels/schema'
20
+ import type {
21
+ ChannelHistoryMessage,
22
+ ChannelSelfIdentityResolver,
23
+ FetchAttachmentCallback,
24
+ FetchHistoryArgs,
25
+ FetchHistoryResult,
26
+ HistoryCallback,
27
+ OutboundCallback,
28
+ OutboundMessage,
29
+ ResolvedChannelNames,
30
+ SendResult,
31
+ } from '@/channels/types'
32
+ import { chunkMarkdown } from '@/markdown'
33
+ import type { SlackAccountRecord } from '@/secrets/schema'
34
+
35
+ import { createSlackAuthorResolver } from './slack-author-resolver'
36
+ import { slackTsToMillis } from './slack-bot-time'
37
+ import { createSlackChannelResolver } from './slack-channel-resolver'
38
+ import { classifyInbound, type InboundDropReason } from './slack-classify'
39
+ import { createSlackReactionCallback, createSlackRemoveReactionCallback } from './slack-reactions'
40
+
41
+ export type SlackAdapterLogger = {
42
+ info: (msg: string) => void
43
+ warn: (msg: string) => void
44
+ error: (msg: string) => void
45
+ }
46
+
47
+ const consoleLogger: SlackAdapterLogger = {
48
+ info: (m) => console.log(m),
49
+ warn: (m) => console.warn(m),
50
+ error: (m) => console.error(m),
51
+ }
52
+
53
+ export type SlackCredentialStore = {
54
+ getAccount(id?: string): Promise<SlackAccountRecord | null>
55
+ }
56
+
57
+ export type SlackAdapterOptions = {
58
+ router: ChannelRouter
59
+ configRef: () => ChannelAdapterConfig
60
+ logger?: SlackAdapterLogger
61
+ selfAliasesRef?: () => readonly string[]
62
+ credentialsStore?: SlackCredentialStore
63
+ createClient?: () => SlackClient
64
+ createListener?: (client: SlackClient) => SlackListener
65
+ }
66
+
67
+ export type SlackAdapter = {
68
+ start: () => Promise<void>
69
+ stop: () => Promise<void>
70
+ isConnected: () => boolean
71
+ }
72
+
73
+ export type SlackFileReader = (path: string) => Promise<Buffer>
74
+
75
+ export function createSlackOutboundCallback(deps: {
76
+ client: Pick<SlackClient, 'sendMessage' | 'uploadFile'>
77
+ logger: SlackAdapterLogger
78
+ formatChannelTag: (chat: string) => Promise<string>
79
+ readFile?: SlackFileReader
80
+ resolvePath?: (path: string) => string
81
+ }): OutboundCallback {
82
+ const readFile = deps.readFile ?? defaultReadFile
83
+ return async (msg: OutboundMessage): Promise<SendResult> => {
84
+ if (msg.adapter !== 'slack') return { ok: false, error: `unknown adapter: ${msg.adapter}` }
85
+ const text = msg.text ?? ''
86
+ const attachments = msg.attachments ?? []
87
+ if (text === '' && attachments.length === 0) return { ok: false, error: 'message has neither text nor attachments' }
88
+ const tag = await deps.formatChannelTag(msg.chat)
89
+ const threadTs = msg.replyTo?.externalMessageId ?? msg.thread ?? undefined
90
+ deps.logger.info(
91
+ `[slack] outbound ${tag} text_len=${text.length} attachments=${attachments.length}${threadTs !== undefined ? ` thread=${threadTs}` : ''}`,
92
+ )
93
+ try {
94
+ if (text !== '') {
95
+ for (const chunk of chunkMarkdown(text, 11_500)) await deps.client.sendMessage(msg.chat, chunk, threadTs)
96
+ }
97
+ for (const attachment of attachments) {
98
+ const path = deps.resolvePath ? deps.resolvePath(attachment.path) : attachment.path
99
+ const buffer = await readFile(path)
100
+ const filename = attachment.filename ?? basename(path)
101
+ await deps.client.uploadFile([msg.chat], buffer, filename)
102
+ }
103
+ return { ok: true }
104
+ } catch (err) {
105
+ const message = describe(err)
106
+ deps.logger.error(`[slack] outbound failed: ${message}`)
107
+ return { ok: false, error: message }
108
+ }
109
+ }
110
+ }
111
+
112
+ export function createSlackHistoryCallback(deps: {
113
+ client: Pick<SlackClient, 'getMessages'>
114
+ logger: SlackAdapterLogger
115
+ }): HistoryCallback {
116
+ return async (args: FetchHistoryArgs): Promise<FetchHistoryResult> => {
117
+ try {
118
+ const messages = await deps.client.getMessages(args.chat, { limit: clampLimit(args.limit, 100) })
119
+ return { ok: true, messages: messages.map(mapSlackHistoryMessage).reverse() }
120
+ } catch (err) {
121
+ const message = describe(err)
122
+ deps.logger.warn(`[slack] history fetch failed: ${message}`)
123
+ return { ok: false, error: message }
124
+ }
125
+ }
126
+ }
127
+
128
+ export function createSlackMembershipResolver(deps: {
129
+ client: Pick<SlackClient, 'listChannelMembers'>
130
+ logger: SlackAdapterLogger
131
+ historyCallback: HistoryCallback
132
+ selfUserIdRef: () => string | null
133
+ now?: () => number
134
+ }): MembershipResolver {
135
+ const now = deps.now ?? Date.now
136
+ return async (key): Promise<MembershipResolverResult> => {
137
+ if (key.adapter !== 'slack') return { kind: 'permanent' } satisfies MembershipResolverFailure
138
+ if (key.workspace === '@dm') return { humans: 1, bots: 1, fetchedAt: now(), truncated: false }
139
+ try {
140
+ const members = await deps.client.listChannelMembers(key.chat)
141
+ const capped = members.slice(0, MEMBERSHIP_ENUMERATION_CAP)
142
+ const selfUserId = deps.selfUserIdRef()
143
+ let bots = 0
144
+ const humanMemberIds: string[] = []
145
+ for (const member of capped) {
146
+ if (selfUserId !== null && member === selfUserId) bots++
147
+ else humanMemberIds.push(member)
148
+ }
149
+ const truncated = members.length >= MEMBERSHIP_ENUMERATION_CAP
150
+ if (truncated) return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated }
151
+ return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated, humanMemberIds }
152
+ } catch (err) {
153
+ deps.logger.warn(`[slack] membership channel=${key.chat} failed: ${describe(err)}; deriving from recent history`)
154
+ return await deriveMembershipFromHistory({
155
+ fetchHistory: (limit) => deps.historyCallback({ chat: key.chat, thread: key.thread, limit }),
156
+ now,
157
+ })
158
+ }
159
+ }
160
+ }
161
+
162
+ export function createSlackFetchAttachmentCallback(deps: {
163
+ client: Pick<SlackClient, 'downloadFile'>
164
+ logger: SlackAdapterLogger
165
+ }): FetchAttachmentCallback {
166
+ return async ({ ref, filename }) => {
167
+ try {
168
+ const { buffer, file } = await deps.client.downloadFile(ref)
169
+ return {
170
+ ok: true,
171
+ buffer,
172
+ filename: filename ?? file.name ?? 'attachment',
173
+ mimetype: file.mimetype,
174
+ size: buffer.length,
175
+ }
176
+ } catch (err) {
177
+ const message = describe(err)
178
+ deps.logger.error(`[slack] fetchAttachment failed for ${ref}: ${message}`)
179
+ return { ok: false, error: message }
180
+ }
181
+ }
182
+ }
183
+
184
+ export function createSlackAdapter(options: SlackAdapterOptions): SlackAdapter {
185
+ const logger = options.logger ?? consoleLogger
186
+ const createClient = options.createClient ?? (() => new SlackClient())
187
+ const createListener = options.createListener ?? ((client) => new SlackListener(client))
188
+ const client = createClient()
189
+ let listener: SlackListener | null = null
190
+ let selfUserId: string | null = null
191
+ let selfName: string | null = null
192
+ let teamId = ''
193
+ let teamName: string | null = null
194
+ let connected = false
195
+ let started = false
196
+ let inflightInbounds = 0
197
+ let stopWaiters: Array<() => void> = []
198
+
199
+ const channelResolver = createSlackChannelResolver({ client, teamNameRef: () => teamName })
200
+ const authorResolver = createSlackAuthorResolver({ client })
201
+ const selfIdentityResolver: ChannelSelfIdentityResolver = () =>
202
+ selfUserId !== null ? { id: selfUserId, username: selfName ?? selfUserId } : null
203
+ const formatChannelTag = async (chat: string): Promise<string> => {
204
+ const names = await channelResolver({ adapter: 'slack', workspace: teamId, chat, thread: null }).catch(
205
+ (): ResolvedChannelNames => ({}),
206
+ )
207
+ const label = names.chatName ?? null
208
+ return label === null || label === chat ? `channel=${chat}` : `channel=${label}(${chat})`
209
+ }
210
+ const historyCallback = createSlackHistoryCallback({ client, logger })
211
+ const membershipResolver = createSlackMembershipResolver({
212
+ client,
213
+ logger,
214
+ historyCallback,
215
+ selfUserIdRef: () => selfUserId,
216
+ })
217
+ const outboundCallback = createSlackOutboundCallback({ client, logger, formatChannelTag })
218
+ const fetchAttachmentCallback = createSlackFetchAttachmentCallback({ client, logger })
219
+ const reactionCallback = createSlackReactionCallback({ client })
220
+ const removeReactionCallback = createSlackRemoveReactionCallback({ client })
221
+
222
+ const handleMessage = async (event: SlackRTMMessageEvent): Promise<void> => {
223
+ inflightInbounds++
224
+ try {
225
+ const tag = await formatChannelTag(event.channel)
226
+ logger.info(
227
+ `[slack] inbound id=${event.ts} author=${event.user ?? '(none)'} ${tag} text_len=${(event.text ?? '').length}`,
228
+ )
229
+ const verdict = classifyInbound(event, options.configRef(), {
230
+ teamId,
231
+ selfUserId,
232
+ selfAliases: options.selfAliasesRef?.() ?? [],
233
+ })
234
+ if (verdict.kind === 'drop') {
235
+ logger.info(`[slack] dropped id=${event.ts} reason=${verdict.reason}${dropHint(verdict.reason)}`)
236
+ return
237
+ }
238
+ const payload = { ...verdict.payload, authorName: await authorResolver.resolve(verdict.payload.authorId) }
239
+ logger.info(`[slack] routed id=${event.ts} ${tag} mention=${payload.isBotMention}`)
240
+ await options.router.route(payload)
241
+ } catch (err) {
242
+ logger.error(`[slack] handleInbound failed: ${describe(err)}`)
243
+ } finally {
244
+ inflightInbounds--
245
+ if (inflightInbounds === 0 && stopWaiters.length > 0) {
246
+ const waiters = stopWaiters
247
+ stopWaiters = []
248
+ for (const w of waiters) w()
249
+ }
250
+ }
251
+ }
252
+
253
+ const handleReaction = (kind: 'added' | 'removed', event: SlackRTMReactionEvent): void => {
254
+ logger.info(`[slack] reaction_${kind} channel=${event.item.channel} ts=${event.item.ts} emoji=${event.reaction}`)
255
+ }
256
+
257
+ return {
258
+ async start(): Promise<void> {
259
+ if (started) return
260
+ started = true
261
+ try {
262
+ const account = await (options.credentialsStore ?? null)?.getAccount()
263
+ if (account === null || account === undefined) {
264
+ throw new Error('no Slack account in secrets.json#channels.slack (run typeclaw init to authenticate)')
265
+ }
266
+ await client.login({ token: account.token, cookie: account.cookie })
267
+ const auth = await client.testAuth()
268
+ selfUserId = auth.user_id
269
+ selfName = auth.user ?? auth.user_id
270
+ teamId = auth.team_id
271
+ teamName = auth.team ?? account.workspace_name ?? null
272
+ logger.info(`[slack] authenticated as ${selfName} (${selfUserId}) team=${teamName ?? teamId}`)
273
+ } catch (err) {
274
+ started = false
275
+ selfUserId = null
276
+ teamId = ''
277
+ logger.error(`[slack] login failed: ${describe(err)}`)
278
+ throw err
279
+ }
280
+
281
+ listener = createListener(client)
282
+ let listenerConnected = false
283
+ let listenerStartupError: Error | null = null
284
+ listener.on('connected', (info) => {
285
+ listenerConnected = true
286
+ connected = true
287
+ selfUserId = info.self.id
288
+ teamId = info.team.id
289
+ })
290
+ listener.on('disconnected', () => {
291
+ connected = false
292
+ logger.warn('[slack] disconnected')
293
+ })
294
+ listener.on('error', (err) => {
295
+ if (!listenerConnected && listenerStartupError === null) listenerStartupError = err
296
+ logger.error(`[slack] listener error: ${describe(err)}`)
297
+ })
298
+ listener.on('message', (event) => void handleMessage(event))
299
+ listener.on('reaction_added', (event) => handleReaction('added', event))
300
+ listener.on('reaction_removed', (event) => handleReaction('removed', event))
301
+
302
+ options.router.registerOutbound('slack', outboundCallback)
303
+ options.router.setTypingCapability('slack', false)
304
+ options.router.registerChannelNameResolver('slack', channelResolver)
305
+ options.router.registerSelfIdentity('slack', selfIdentityResolver)
306
+ options.router.registerHistory('slack', historyCallback)
307
+ options.router.registerFetchAttachment('slack', fetchAttachmentCallback)
308
+ options.router.registerMembership('slack', membershipResolver)
309
+ options.router.registerReaction('slack', reactionCallback)
310
+ options.router.registerRemoveReaction('slack', removeReactionCallback)
311
+
312
+ const rollbackStart = (reason: string, cause: Error): never => {
313
+ options.router.unregisterOutbound('slack', outboundCallback)
314
+ options.router.setTypingCapability('slack', false)
315
+ options.router.unregisterChannelNameResolver('slack', channelResolver)
316
+ options.router.unregisterSelfIdentity('slack', selfIdentityResolver)
317
+ options.router.unregisterHistory('slack', historyCallback)
318
+ options.router.unregisterFetchAttachment('slack', fetchAttachmentCallback)
319
+ options.router.unregisterMembership('slack', membershipResolver)
320
+ options.router.unregisterReaction('slack', reactionCallback)
321
+ options.router.unregisterRemoveReaction('slack', removeReactionCallback)
322
+ listener?.stop()
323
+ listener = null
324
+ selfUserId = null
325
+ connected = false
326
+ started = false
327
+ logger.error(`[slack] ${reason}: ${describe(cause)}`)
328
+ throw cause
329
+ }
330
+
331
+ try {
332
+ await listener.start()
333
+ } catch (err) {
334
+ rollbackStart('listener start threw', err instanceof Error ? err : new Error(String(err)))
335
+ }
336
+ if (!listenerConnected) {
337
+ rollbackStart(
338
+ 'listener start failed silently',
339
+ listenerStartupError ?? new Error('listener.start() returned without emitting connected'),
340
+ )
341
+ }
342
+ },
343
+
344
+ async stop(): Promise<void> {
345
+ if (!started) return
346
+ started = false
347
+ options.router.unregisterOutbound('slack', outboundCallback)
348
+ options.router.setTypingCapability('slack', false)
349
+ options.router.unregisterChannelNameResolver('slack', channelResolver)
350
+ options.router.unregisterSelfIdentity('slack', selfIdentityResolver)
351
+ options.router.unregisterHistory('slack', historyCallback)
352
+ options.router.unregisterFetchAttachment('slack', fetchAttachmentCallback)
353
+ options.router.unregisterMembership('slack', membershipResolver)
354
+ options.router.unregisterReaction('slack', reactionCallback)
355
+ options.router.unregisterRemoveReaction('slack', removeReactionCallback)
356
+ listener?.stop()
357
+ listener = null
358
+ connected = false
359
+ if (inflightInbounds > 0) {
360
+ await new Promise<void>((resolve) => {
361
+ stopWaiters.push(resolve)
362
+ })
363
+ }
364
+ selfUserId = null
365
+ },
366
+
367
+ isConnected(): boolean {
368
+ return started && selfUserId !== null && connected
369
+ },
370
+ }
371
+ }
372
+
373
+ async function defaultReadFile(path: string): Promise<Buffer> {
374
+ return Buffer.from(await Bun.file(path).arrayBuffer())
375
+ }
376
+
377
+ function mapSlackHistoryMessage(msg: SlackMessage): ChannelHistoryMessage {
378
+ const attachments = (msg.files ?? []).map((file, index) => ({
379
+ id: index + 1,
380
+ kind: 'file' as const,
381
+ ref: file.id,
382
+ filename: file.name,
383
+ mimetype: file.mimetype,
384
+ }))
385
+ return {
386
+ externalMessageId: msg.ts,
387
+ authorId: msg.user ?? msg.username ?? 'unknown',
388
+ authorName: msg.username ?? msg.user ?? 'unknown',
389
+ text: msg.text,
390
+ ts: slackTsToMillis(msg.ts),
391
+ isBot: false,
392
+ replyToBotMessageId: null,
393
+ ...(attachments.length > 0 ? { attachments } : {}),
394
+ }
395
+ }
396
+
397
+ function clampLimit(requested: number, max: number): number {
398
+ if (!Number.isFinite(requested) || requested <= 0) return max
399
+ return Math.min(Math.floor(requested), max)
400
+ }
401
+
402
+ function describe(err: unknown): string {
403
+ return err instanceof Error ? err.message : String(err)
404
+ }
405
+
406
+ function dropHint(reason: InboundDropReason): string {
407
+ switch (reason) {
408
+ case 'empty_text':
409
+ return ' (message had no text)'
410
+ case 'pre_connect':
411
+ case 'self_author':
412
+ case 'no_user':
413
+ case 'slack_system_message':
414
+ return ''
415
+ }
416
+ }
@@ -260,7 +260,8 @@ export function createOutboundCallback(deps: {
260
260
  if (replyToId !== undefined) sendOptions.reply_to_message_id = replyToId
261
261
  const sent = await client.sendMessage(msg.chat, rendered, sendOptions)
262
262
  logger.info(`[telegram-bot] sent message_id=${sent.message_id} ${tag}`)
263
- return { ok: true }
263
+ const id = String(sent.message_id)
264
+ return { ok: true, messageId: id, messageIds: [id] }
264
265
  } catch (err) {
265
266
  const message = describe(err)
266
267
  logger.error(`[telegram-bot] sendMessage failed: ${message}`)
@@ -33,6 +33,7 @@ import { createWebexChannelNameResolver } from './webex-bot-channel-resolver'
33
33
  import { classifyInbound, type InboundDropReason, type WebexInboundMessage } from './webex-bot-classify'
34
34
  import { enrichWebexMessageReference } from './webex-bot-reference'
35
35
  import { resolveWebexBodyText } from './webex-format'
36
+ import { createWebexPrefetchLimiter, isWebexRateLimitError, type WebexPrefetchLimiter } from './webex-prefetch-limiter'
36
37
 
37
38
  export type WebexBotAdapterLogger = {
38
39
  info: (msg: string) => void
@@ -107,6 +108,7 @@ export function createOutboundCallback(deps: {
107
108
 
108
109
  try {
109
110
  if (attachments.length > 0) {
111
+ const uploadedRefs: string[] = []
110
112
  for (const [index, attachment] of attachments.entries()) {
111
113
  const path = resolvePath ? resolvePath(attachment.path) : attachment.path
112
114
  const file = await readFile(path)
@@ -116,14 +118,16 @@ export function createOutboundCallback(deps: {
116
118
  ...(carriesText ? { text } : {}),
117
119
  ...(parentId !== undefined ? { parentId } : {}),
118
120
  })
121
+ uploadedRefs.push(sent.ref)
119
122
  logger.info(`[webex-bot] uploaded id=${sent.ref} filename=${file.filename} ${tag}`)
120
123
  }
121
- return { ok: true }
124
+ // First upload carries the text and is the thread parent, so it is the reply anchor.
125
+ return { ok: true, messageId: uploadedRefs[0], messageIds: uploadedRefs }
122
126
  }
123
127
 
124
128
  const sent = await client.sendMessage(msg.chat, text, parentId !== undefined ? { parentId } : undefined)
125
129
  logger.info(`[webex-bot] sent id=${sent.ref} ${tag}`)
126
- return { ok: true }
130
+ return { ok: true, messageId: sent.ref, messageIds: [sent.ref] }
127
131
  } catch (err) {
128
132
  const message = describe(err)
129
133
  logger.error(`[webex-bot] outbound failed: ${message}`)
@@ -136,27 +140,39 @@ async function defaultReadFile(path: string): Promise<WebexOutboundFile> {
136
140
  return { content: Bun.file(path), filename: path.split('/').pop() ?? 'attachment' }
137
141
  }
138
142
 
139
- // See webex.ts: the bot client has no AbortSignal either, so a hung listMessages
140
- // is bounded by a tighter internal deadline than the router's 5s history ceiling.
141
- const WEBEX_HISTORY_COLD_FETCH_TIMEOUT_MS = 2500
142
-
143
143
  export function createWebexHistoryCallback(deps: {
144
144
  client: Pick<WebexBotClient, 'listMessages'>
145
145
  logger: WebexBotAdapterLogger
146
146
  botPersonIdRef: () => string | null
147
- timeoutMs?: number
147
+ limiter?: WebexPrefetchLimiter
148
148
  }): HistoryCallback {
149
- const timeoutMs = deps.timeoutMs ?? WEBEX_HISTORY_COLD_FETCH_TIMEOUT_MS
149
+ const limiter = deps.limiter ?? createWebexPrefetchLimiter()
150
+ const listMessages = (args: FetchHistoryArgs) =>
151
+ deps.client.listMessages(args.chat, { max: clampLimit(args.limit, 100) })
152
+ const toHistory = (messages: WebexMessage[]): FetchHistoryResult => ({
153
+ ok: true,
154
+ messages: messages.map((m) => mapWebexHistoryMessage(m, deps.botPersonIdRef())).reverse(),
155
+ })
150
156
  return async (args: FetchHistoryArgs): Promise<FetchHistoryResult> => {
151
157
  try {
152
- const messages = await raceWithTimeout(
153
- deps.client.listMessages(args.chat, { max: clampLimit(args.limit, 100) }),
154
- timeoutMs,
155
- '[webex-bot] history fetch',
156
- )
157
- return { ok: true, messages: messages.map((m) => mapWebexHistoryMessage(m, deps.botPersonIdRef())).reverse() }
158
+ // Only best-effort reads (cold-start prefetch, membership fallback) submit
159
+ // to the per-room limiter. Explicit channel_history reads bypass it so a
160
+ // user-initiated look-back is never declined by prefetch backpressure.
161
+ if (args.prefetch !== true) {
162
+ return toHistory(await listMessages(args))
163
+ }
164
+ const outcome = await limiter.run(args.chat, () => listMessages(args))
165
+ if (!outcome.admitted) {
166
+ deps.logger.info('[webex-bot] history prefetch skipped: rate-limit backpressure')
167
+ return { ok: false, error: 'prefetch skipped: rate-limit backpressure', skipReason: 'rate-limited' }
168
+ }
169
+ return toHistory(outcome.value)
158
170
  } catch (err) {
159
171
  const message = describe(err)
172
+ if (args.prefetch === true && isWebexRateLimitError(err)) {
173
+ deps.logger.info(`[webex-bot] history prefetch skipped: rate limited (${message})`)
174
+ return { ok: false, error: message, skipReason: 'rate-limited' }
175
+ }
160
176
  deps.logger.warn(`[webex-bot] history fetch failed: ${message}`)
161
177
  return { ok: false, error: message }
162
178
  }
@@ -201,7 +217,7 @@ export function createWebexMembershipResolver(deps: {
201
217
  } catch (err) {
202
218
  deps.logger.warn(`[webex-bot] membership room=${key.chat} failed: ${describe(err)}; deriving from recent history`)
203
219
  return await deriveMembershipFromHistory({
204
- fetchHistory: (limit) => deps.historyCallback({ chat: key.chat, thread: key.thread, limit }),
220
+ fetchHistory: (limit) => deps.historyCallback({ chat: key.chat, thread: key.thread, limit, prefetch: true }),
205
221
  now,
206
222
  })
207
223
  }
@@ -462,18 +478,6 @@ function describe(err: unknown): string {
462
478
  return err instanceof Error ? err.message : String(err)
463
479
  }
464
480
 
465
- async function raceWithTimeout<T>(work: Promise<T>, ms: number, label: string): Promise<T> {
466
- let timer: ReturnType<typeof setTimeout> | null = null
467
- const timeout = new Promise<never>((_, reject) => {
468
- timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms)
469
- })
470
- try {
471
- return await Promise.race([work, timeout])
472
- } finally {
473
- if (timer !== null) clearTimeout(timer)
474
- }
475
- }
476
-
477
481
  function dropHint(reason: InboundDropReason): string {
478
482
  switch (reason) {
479
483
  case 'empty_content':
@@ -0,0 +1,120 @@
1
+ // Webex's internal conversation API rate-limits reads PER ROOM, not per account:
2
+ // hammering one room's history returns HTTP 429 (x-ratelimit-limit ~3, Retry-After
3
+ // up to ~25s) while a different room served by the same token stays unaffected
4
+ // (verified empirically — saturating room A produced zero 429s on room B). The
5
+ // upstream agent-messenger SDK retries 429s, but its bucket tracker is reactive
6
+ // (it learns the limit only after a 429 lands) and its 3-retry budget cannot
7
+ // outlast a 25s window, so same-room pile-up — cold-start prefetch plus the
8
+ // membership resolver's deriveMembershipFromHistory fallback, both reading the
9
+ // same room — overflows the bucket and fails the prefetch.
10
+ //
11
+ // History prefetch is a context improvement, not liveness — the router skips it
12
+ // and the agent can call channel_history on demand later. So the fix is keyed by
13
+ // room: bound concurrent reads PER ROOM (independent rooms never wait on each
14
+ // other) and keep cold-start non-blocking with bounded admission ("admit fast or
15
+ // skip"), because starting then abandoning a listMessages we cannot cancel (the
16
+ // SDK exposes no AbortSignal) would only burn more quota on an orphaned fetch.
17
+
18
+ export type WebexPrefetchLimiter = {
19
+ // Runs `work` under the permit pool for `key` (the room id). If no slot frees
20
+ // within `admitTimeoutMs`, resolves to `{ admitted: false }` WITHOUT starting
21
+ // `work` — the caller then skips the prefetch. On admission, runs `work` and
22
+ // returns its result. Distinct keys never contend.
23
+ run<T>(key: string, work: () => Promise<T>): Promise<{ admitted: true; value: T } | { admitted: false }>
24
+ }
25
+
26
+ export type WebexPrefetchLimiterOptions = {
27
+ // Max concurrent reads PER ROOM. Defaults to 2: Webex's per-room cap is ~3, so
28
+ // 2 leaves headroom for the SDK's own retry traffic while still letting a
29
+ // prefetch and a membership-fallback read of the same room overlap.
30
+ concurrency?: number
31
+ // How long a queued caller waits for a slot before giving up and skipping.
32
+ // Defaults to 2500ms, matching the prior cold-fetch fail-fast posture so a
33
+ // backlog never stalls cold-start past the router's history ceiling.
34
+ admitTimeoutMs?: number
35
+ }
36
+
37
+ const DEFAULT_CONCURRENCY = 2
38
+ const DEFAULT_ADMIT_TIMEOUT_MS = 2500
39
+
40
+ export function createWebexPrefetchLimiter(options: WebexPrefetchLimiterOptions = {}): WebexPrefetchLimiter {
41
+ const concurrency = Math.max(1, Math.floor(options.concurrency ?? DEFAULT_CONCURRENCY))
42
+ const admitTimeoutMs = options.admitTimeoutMs ?? DEFAULT_ADMIT_TIMEOUT_MS
43
+
44
+ type Pool = { active: number; waiters: Array<() => void> }
45
+ const pools = new Map<string, Pool>()
46
+
47
+ const poolFor = (key: string): Pool => {
48
+ let pool = pools.get(key)
49
+ if (pool === undefined) {
50
+ pool = { active: 0, waiters: [] }
51
+ pools.set(key, pool)
52
+ }
53
+ return pool
54
+ }
55
+
56
+ const release = (key: string): void => {
57
+ const pool = pools.get(key)
58
+ if (pool === undefined) return
59
+ pool.active--
60
+ const next = pool.waiters.shift()
61
+ if (next) next()
62
+ // Drop idle pools so a long-lived limiter does not accumulate one entry per
63
+ // room ever seen.
64
+ else if (pool.active === 0 && pool.waiters.length === 0) pools.delete(key)
65
+ }
66
+
67
+ const acquire = (key: string): Promise<boolean> => {
68
+ const pool = poolFor(key)
69
+ if (pool.active < concurrency) {
70
+ pool.active++
71
+ return Promise.resolve(true)
72
+ }
73
+ return new Promise<boolean>((resolve) => {
74
+ let settled = false
75
+ const timer = setTimeout(() => {
76
+ if (settled) return
77
+ settled = true
78
+ const idx = pool.waiters.indexOf(grant)
79
+ if (idx >= 0) pool.waiters.splice(idx, 1)
80
+ resolve(false)
81
+ }, admitTimeoutMs)
82
+ const grant = (): void => {
83
+ if (settled) {
84
+ // Admitted after we already gave up: hand the freed slot to the next
85
+ // waiter so a timed-out grant never leaks a permanently-held slot.
86
+ release(key)
87
+ return
88
+ }
89
+ settled = true
90
+ clearTimeout(timer)
91
+ pool.active++
92
+ resolve(true)
93
+ }
94
+ pool.waiters.push(grant)
95
+ })
96
+ }
97
+
98
+ return {
99
+ async run<T>(key: string, work: () => Promise<T>): Promise<{ admitted: true; value: T } | { admitted: false }> {
100
+ const admitted = await acquire(key)
101
+ if (!admitted) return { admitted: false }
102
+ try {
103
+ return { admitted: true, value: await work() }
104
+ } finally {
105
+ release(key)
106
+ }
107
+ },
108
+ }
109
+ }
110
+
111
+ // The SDK throws WebexError with code 'rate_limited' once 429 retries are
112
+ // exhausted, and 'http_429' for a raw 429 that bypassed the retry path. Both mean
113
+ // the same thing to us: an expected, transient, non-fatal rate-limit skip — not an
114
+ // auth/network failure worth a warn. Matching on the SDK's code field (rather than
115
+ // the human message) keeps this stable across SDK message-wording changes.
116
+ export function isWebexRateLimitError(err: unknown): boolean {
117
+ if (typeof err !== 'object' || err === null) return false
118
+ const code = (err as { code?: unknown }).code
119
+ return code === 'rate_limited' || code === 'http_429'
120
+ }