typeclaw 0.39.7 → 0.40.0

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 (58) hide show
  1. package/package.json +1 -1
  2. package/scripts/dump-system-prompt.ts +4 -50
  3. package/src/agent/auth-reloadable.ts +24 -0
  4. package/src/agent/auth.ts +12 -0
  5. package/src/agent/index.ts +18 -58
  6. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +0 -2
  7. package/src/bundled-plugins/guard/policy.ts +0 -5
  8. package/src/bundled-plugins/memory/README.md +26 -37
  9. package/src/bundled-plugins/memory/index.ts +30 -144
  10. package/src/bundled-plugins/memory/load-memory.ts +7 -121
  11. package/src/bundled-plugins/memory/memory-logger.ts +8 -2
  12. package/src/bundled-plugins/memory/search-command.ts +2 -11
  13. package/src/bundled-plugins/memory/vector/doctor.ts +1 -1
  14. package/src/bundled-plugins/memory/vector/embedder.ts +4 -5
  15. package/src/bundled-plugins/memory/vector/hybrid.ts +47 -5
  16. package/src/bundled-plugins/memory/vector/relevance-gate.ts +11 -7
  17. package/src/bundled-plugins/memory/vector/script.ts +87 -0
  18. package/src/channels/adapters/describe-error.ts +40 -0
  19. package/src/channels/adapters/discord.ts +9 -12
  20. package/src/channels/adapters/kakaotalk.ts +14 -17
  21. package/src/channels/adapters/line.ts +11 -14
  22. package/src/channels/adapters/slack-bot.ts +15 -18
  23. package/src/channels/adapters/slack.ts +45 -21
  24. package/src/channels/adapters/telegram-bot.ts +15 -18
  25. package/src/channels/adapters/webex-bot.ts +13 -14
  26. package/src/channels/adapters/webex.ts +14 -15
  27. package/src/cli/compose.ts +20 -0
  28. package/src/cli/docker-preflight.ts +42 -0
  29. package/src/cli/hostd.ts +12 -3
  30. package/src/cli/init.ts +24 -22
  31. package/src/cli/logs.ts +7 -0
  32. package/src/cli/provider.ts +8 -1
  33. package/src/cli/reload.ts +6 -0
  34. package/src/cli/restart.ts +7 -0
  35. package/src/cli/shell.ts +7 -0
  36. package/src/cli/start.ts +7 -0
  37. package/src/cli/status.ts +9 -0
  38. package/src/cli/stop.ts +7 -0
  39. package/src/cli/tui.ts +6 -0
  40. package/src/config/config.ts +31 -8
  41. package/src/container/docker-app.ts +253 -0
  42. package/src/container/index.ts +11 -0
  43. package/src/container/start.ts +85 -41
  44. package/src/hostd/current-host-daemon.ts +21 -0
  45. package/src/hostd/daemon.ts +27 -3
  46. package/src/hostd/supervisor.ts +18 -3
  47. package/src/plugin/hooks.ts +3 -4
  48. package/src/plugin/types.ts +1 -1
  49. package/src/run/channel-session-factory.ts +3 -5
  50. package/src/run/index.ts +17 -16
  51. package/src/server/command-runner.ts +2 -11
  52. package/src/skills/typeclaw-memory/SKILL.md +2 -2
  53. package/src/skills/typeclaw-plugins/SKILL.md +1 -1
  54. package/typeclaw.schema.json +1 -23
  55. package/src/bundled-plugins/guard/policies/memory-retrieval-cache-write.ts +0 -43
  56. package/src/bundled-plugins/memory/memory-retrieval.ts +0 -111
  57. package/src/bundled-plugins/memory/vector/cache-write.ts +0 -19
  58. package/src/bundled-plugins/memory/vector/config.ts +0 -28
@@ -32,6 +32,7 @@ import type {
32
32
  InboundAttachment,
33
33
  } from '@/channels/types'
34
34
 
35
+ import { describeError } from './describe-error'
35
36
  import {
36
37
  emoticonEventToMessageEvent,
37
38
  splitEmoticonInbound,
@@ -215,7 +216,7 @@ export function createOutboundCallback(deps: {
215
216
  }),
216
217
  )
217
218
  } catch (err) {
218
- const message = describe(err)
219
+ const message = describeError(err)
219
220
  logger.error(`[kakaotalk] readFile failed: ${message}`)
220
221
  return { ok: false, error: `readFile failed: ${message}` }
221
222
  }
@@ -228,7 +229,7 @@ export function createOutboundCallback(deps: {
228
229
  logIds.push(result.log_id)
229
230
  logger.info(`[kakaotalk] uploaded log_id=${result.log_id} attachments=${items.length} ${tag}`)
230
231
  } catch (err) {
231
- const message = describe(err)
232
+ const message = describeError(err)
232
233
  logger.error(`[kakaotalk] sendAttachment failed: ${message}`)
233
234
  return { ok: false, error: message }
234
235
  }
@@ -262,7 +263,7 @@ export function createOutboundCallback(deps: {
262
263
  logIds.push(result.log_id)
263
264
  logger.info(`[kakaotalk] sent log_id=${result.log_id} ${tag}`)
264
265
  } catch (err) {
265
- const message = describe(err)
266
+ const message = describeError(err)
266
267
  logger.error(`[kakaotalk] sendMessage failed: ${message}`)
267
268
  return { ok: false, error: message }
268
269
  }
@@ -295,7 +296,7 @@ async function resolveKakaoReplyTarget(
295
296
  }
296
297
  return { log_id: target.log_id, author_id: target.author_id, message: target.message, type: target.type }
297
298
  } catch (err) {
298
- logger.warn(`[kakaotalk] reply target lookup failed: ${describe(err)}`)
299
+ logger.warn(`[kakaotalk] reply target lookup failed: ${describeError(err)}`)
299
300
  return undefined
300
301
  }
301
302
  }
@@ -334,7 +335,7 @@ export function createKakaoHistoryCallback(deps: {
334
335
  )
335
336
  return { ok: true, messages: mapped }
336
337
  } catch (err) {
337
- const message = describe(err)
338
+ const message = describeError(err)
338
339
  logger.warn(`[kakaotalk] history fetch failed: ${message}`)
339
340
  return { ok: false, error: message }
340
341
  }
@@ -483,7 +484,7 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
483
484
  )
484
485
  await options.router.route(enriched)
485
486
  } catch (err) {
486
- logger.error(`[kakaotalk] handleInbound failed: ${describe(err)}`)
487
+ logger.error(`[kakaotalk] handleInbound failed: ${describeError(err)}`)
487
488
  } finally {
488
489
  inflightInbounds--
489
490
  if (inflightInbounds === 0 && stopWaiters.length > 0) {
@@ -527,7 +528,7 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
527
528
  }
528
529
  } catch (err) {
529
530
  started = false
530
- logger.error(`[kakaotalk] login failed: ${describe(err)}`)
531
+ logger.error(`[kakaotalk] login failed: ${describeError(err)}`)
531
532
  throw err
532
533
  }
533
534
 
@@ -546,14 +547,14 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
546
547
  logger.error(`[kakaotalk] ${message}`)
547
548
  throw new Error(message)
548
549
  }
549
- logger.error(`[kakaotalk] getProfile failed: ${describe(err)}`)
550
+ logger.error(`[kakaotalk] getProfile failed: ${describeError(err)}`)
550
551
  throw err
551
552
  }
552
553
 
553
554
  try {
554
555
  await channelResolver.refresh()
555
556
  } catch (err) {
556
- logger.warn(`[kakaotalk] initial chat list fetch failed: ${describe(err)}`)
557
+ logger.warn(`[kakaotalk] initial chat list fetch failed: ${describeError(err)}`)
557
558
  }
558
559
 
559
560
  listener = options.listenerFactory ? options.listenerFactory(client) : new KakaoTalkListener(client)
@@ -585,7 +586,7 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
585
586
  logger.warn('[kakaotalk] disconnected; SDK will reconnect with backoff')
586
587
  })
587
588
  listener.on('error', (err) => {
588
- logger.error(`[kakaotalk] listener error: ${describe(err)}`)
589
+ logger.error(`[kakaotalk] listener error: ${describeError(err)}`)
589
590
  if (!isKickoutError(err)) return
590
591
  // KICKOUT closes the SDK session and skips scheduleReconnect, so
591
592
  // without intervention the adapter goes silent. We must either
@@ -624,7 +625,7 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
624
625
  if (recoveryEpisode !== episode) return
625
626
  activeListener.start().catch((retryErr) => {
626
627
  logger.error(
627
- `[kakaotalk] KICKOUT auto-recovery failed: ${describe(retryErr)}. Run \`typeclaw restart\` to retry.`,
628
+ `[kakaotalk] KICKOUT auto-recovery failed: ${describeError(retryErr)}. Run \`typeclaw restart\` to retry.`,
628
629
  )
629
630
  })
630
631
  }, delayMs)
@@ -658,7 +659,7 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
658
659
  }
659
660
  listener = null
660
661
  started = false
661
- logger.error(`[kakaotalk] listener start failed: ${describe(err)}`)
662
+ logger.error(`[kakaotalk] listener start failed: ${describeError(err)}`)
662
663
  throw err
663
664
  }
664
665
 
@@ -707,10 +708,6 @@ export function createKakaotalkAdapter(options: KakaotalkAdapterOptions): Kakaot
707
708
  }
708
709
  }
709
710
 
710
- function describe(err: unknown): string {
711
- return err instanceof Error ? err.message : String(err)
712
- }
713
-
714
711
  function markReadIfSupported(deps: {
715
712
  client: Pick<KakaoTalkClient, 'markRead'>
716
713
  event: KakaoTalkPushMessageEvent
@@ -738,7 +735,7 @@ function markReadIfSupported(deps: {
738
735
  }
739
736
  },
740
737
  (err) => {
741
- logger.warn(`[kakaotalk] mark-read failed: ${describe(err)} chat=${event.chat_id} log=${event.log_id}`)
738
+ logger.warn(`[kakaotalk] mark-read failed: ${describeError(err)} chat=${event.chat_id} log=${event.log_id}`)
742
739
  },
743
740
  )
744
741
  }
@@ -25,6 +25,7 @@ import type {
25
25
  SendResult,
26
26
  } from '@/channels/types'
27
27
 
28
+ import { describeError } from './describe-error'
28
29
  import { splitInboundLine } from './line-attachment'
29
30
  import { createLineChannelResolver } from './line-channel-resolver'
30
31
  import { classifyInbound } from './line-classify'
@@ -128,7 +129,7 @@ export function createOutboundCallback(deps: {
128
129
  logger.info(`[line] sent message_id=${result.message_id} ${tag}`)
129
130
  return { ok: true, messageId: result.message_id, messageIds: [result.message_id] }
130
131
  } catch (err) {
131
- const message = describe(err)
132
+ const message = describeError(err)
132
133
  logger.error(`[line] sendMessage failed: ${message}`)
133
134
  return { ok: false, error: message }
134
135
  }
@@ -160,7 +161,7 @@ export function createLineHistoryCallback(deps: {
160
161
  })
161
162
  return { ok: true, messages: mapped }
162
163
  } catch (err) {
163
- const message = describe(err)
164
+ const message = describeError(err)
164
165
  logger.warn(`[line] history fetch failed: ${message}`)
165
166
  return { ok: false, error: message }
166
167
  }
@@ -231,7 +232,7 @@ export function createLineAdapter(options: LineAdapterOptions): LineAdapter {
231
232
  lastPersistedToken = authToken
232
233
  logger.info('[line] persisted refreshed auth token to secrets')
233
234
  } catch (err) {
234
- logger.warn(`[line] failed to persist refreshed auth token: ${describe(err)}`)
235
+ logger.warn(`[line] failed to persist refreshed auth token: ${describeError(err)}`)
235
236
  }
236
237
  }
237
238
 
@@ -241,7 +242,7 @@ export function createLineAdapter(options: LineAdapterOptions): LineAdapter {
241
242
  const token = await client.ensureFreshAuthToken({ skewMs: LINE_TOKEN_REFRESH_SKEW_MS })
242
243
  if (token) await persistAuthToken(token)
243
244
  } catch (err) {
244
- logger.warn(`[line] token refresh failed: ${describe(err)}`)
245
+ logger.warn(`[line] token refresh failed: ${describeError(err)}`)
245
246
  }
246
247
  }
247
248
 
@@ -301,7 +302,7 @@ export function createLineAdapter(options: LineAdapterOptions): LineAdapter {
301
302
  )
302
303
  await options.router.route(verdict.payload)
303
304
  } catch (err) {
304
- logger.error(`[line] handleInbound failed: ${describe(err)}`)
305
+ logger.error(`[line] handleInbound failed: ${describeError(err)}`)
305
306
  } finally {
306
307
  inflightInbounds--
307
308
  if (inflightInbounds === 0 && stopWaiters.length > 0) {
@@ -335,7 +336,7 @@ export function createLineAdapter(options: LineAdapterOptions): LineAdapter {
335
336
  }
336
337
  } catch (err) {
337
338
  started = false
338
- logger.error(`[line] login failed: ${describe(err)}`)
339
+ logger.error(`[line] login failed: ${describeError(err)}`)
339
340
  throw err
340
341
  }
341
342
 
@@ -348,14 +349,14 @@ export function createLineAdapter(options: LineAdapterOptions): LineAdapter {
348
349
  logger.info(`[line] authenticated as ${profile.display_name || profile.mid} (${profile.mid})`)
349
350
  } catch (err) {
350
351
  started = false
351
- logger.error(`[line] getProfile failed: ${describe(err)}`)
352
+ logger.error(`[line] getProfile failed: ${describeError(err)}`)
352
353
  throw err
353
354
  }
354
355
 
355
356
  try {
356
357
  await channelResolver.refresh()
357
358
  } catch (err) {
358
- logger.warn(`[line] initial chat list fetch failed: ${describe(err)}`)
359
+ logger.warn(`[line] initial chat list fetch failed: ${describeError(err)}`)
359
360
  }
360
361
 
361
362
  listener = options.listenerFactory ? options.listenerFactory(client) : new LineListener(client)
@@ -368,7 +369,7 @@ export function createLineAdapter(options: LineAdapterOptions): LineAdapter {
368
369
  logger.warn('[line] disconnected; SDK will reconnect with backoff')
369
370
  })
370
371
  listener.on('error', (err) => {
371
- logger.error(`[line] listener error: ${describe(err)}`)
372
+ logger.error(`[line] listener error: ${describeError(err)}`)
372
373
  })
373
374
  listener.on('message', (event) => {
374
375
  void processInbound(event)
@@ -384,7 +385,7 @@ export function createLineAdapter(options: LineAdapterOptions): LineAdapter {
384
385
  }
385
386
  listener = null
386
387
  started = false
387
- logger.error(`[line] listener start failed: ${describe(err)}`)
388
+ logger.error(`[line] listener start failed: ${describeError(err)}`)
388
389
  throw err
389
390
  }
390
391
 
@@ -432,7 +433,3 @@ function formatLabel(name: string | undefined, id: string): string {
432
433
  if (name === undefined || name === '' || name === id) return id
433
434
  return `${name}(${id})`
434
435
  }
435
-
436
- function describe(err: unknown): string {
437
- return err instanceof Error ? err.message : String(err)
438
- }
@@ -32,6 +32,7 @@ import type {
32
32
  } from '@/channels/types'
33
33
  import { chunkMarkdown } from '@/markdown'
34
34
 
35
+ import { describeError } from './describe-error'
35
36
  import { addSlackMentionHints } from './mention-hints'
36
37
  import { createSlackAuthorResolver, type SlackAuthorResolver } from './slack-bot-author-resolver'
37
38
  import { createSlackChannelResolver } from './slack-bot-channel-resolver'
@@ -110,7 +111,7 @@ export function createSlashCommandHandler(
110
111
  try {
111
112
  ack(buildSlashAckPayload(SLACK_SLASH_REPLY_FAILED))
112
113
  } catch (err) {
113
- deps.logger.warn(`[slack-bot] slash command ack (drop path) failed: ${describe(err)}`)
114
+ deps.logger.warn(`[slack-bot] slash command ack (drop path) failed: ${describeError(err)}`)
114
115
  }
115
116
  return
116
117
  }
@@ -128,11 +129,11 @@ export function createSlashCommandHandler(
128
129
  invokerId: command.invokerId,
129
130
  })
130
131
  } catch (err) {
131
- deps.logger.error(`[slack-bot] slash command handler failed: ${describe(err)}`)
132
+ deps.logger.error(`[slack-bot] slash command handler failed: ${describeError(err)}`)
132
133
  try {
133
134
  ack(buildSlashAckPayload(SLACK_SLASH_REPLY_FAILED))
134
135
  } catch (ackErr) {
135
- deps.logger.warn(`[slack-bot] slash command error-ack failed: ${describe(ackErr)}`)
136
+ deps.logger.warn(`[slack-bot] slash command error-ack failed: ${describeError(ackErr)}`)
136
137
  }
137
138
  return
138
139
  }
@@ -146,7 +147,7 @@ export function createSlashCommandHandler(
146
147
  try {
147
148
  ack(buildSlashAckPayload(replyContent))
148
149
  } catch (err) {
149
- deps.logger.warn(`[slack-bot] slash command ack failed: ${describe(err)}`)
150
+ deps.logger.warn(`[slack-bot] slash command ack failed: ${describeError(err)}`)
150
151
  }
151
152
 
152
153
  // Decorative post-ack logging: resolve channel names now that the 3s
@@ -156,7 +157,7 @@ export function createSlashCommandHandler(
156
157
  deps.logger.info(`[slack-bot] slash /${command.name} result=${result.kind} ${inboundTag}`)
157
158
  } catch (err) {
158
159
  deps.logger.info(
159
- `[slack-bot] slash /${command.name} result=${result.kind} (channel-tag resolution failed: ${describe(err)})`,
160
+ `[slack-bot] slash /${command.name} result=${result.kind} (channel-tag resolution failed: ${describeError(err)})`,
160
161
  )
161
162
  }
162
163
  }
@@ -210,14 +211,14 @@ export function createThreadCommandHandler(
210
211
  reply = commandResultReply(result)
211
212
  deps.logger.info(`[slack-bot] thread-command !${command.name} result=${result.kind}`)
212
213
  } catch (err) {
213
- deps.logger.error(`[slack-bot] thread-command !${command.name} failed: ${describe(err)}`)
214
+ deps.logger.error(`[slack-bot] thread-command !${command.name} failed: ${describeError(err)}`)
214
215
  reply = SLACK_SLASH_REPLY_FAILED
215
216
  }
216
217
 
217
218
  try {
218
219
  await deps.postReply({ chat: input.channel, thread: input.threadTs, text: reply })
219
220
  } catch (err) {
220
- deps.logger.warn(`[slack-bot] thread-command reply post failed: ${describe(err)}`)
221
+ deps.logger.warn(`[slack-bot] thread-command reply post failed: ${describeError(err)}`)
221
222
  }
222
223
  return { kind: 'executed' }
223
224
  }
@@ -329,7 +330,7 @@ export function createSlackTypingTracker(deps: {
329
330
  })
330
331
  .catch((err: unknown) => {
331
332
  logger.warn(
332
- `[slack-bot] typing call=${callId} chat=${chat} thread=${threadTs} status="${status}" failed: ${describe(err)}`,
333
+ `[slack-bot] typing call=${callId} chat=${chat} thread=${threadTs} status="${status}" failed: ${describeError(err)}`,
333
334
  )
334
335
  })
335
336
  queues.set(key, next)
@@ -575,7 +576,7 @@ async function slackApi<T>(
575
576
  })
576
577
  raw = (await response.json()) as { ok?: boolean; error?: string }
577
578
  } catch (err) {
578
- return { ok: false, reason: describe(err), failure: { kind: 'transient' } }
579
+ return { ok: false, reason: describeError(err), failure: { kind: 'transient' } }
579
580
  }
580
581
  if (raw.ok !== true) {
581
582
  const reason = raw.error ?? 'unknown slack error'
@@ -1162,7 +1163,7 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
1162
1163
  )
1163
1164
  await options.router.route(enriched)
1164
1165
  } catch (err) {
1165
- logger.error(`[slack-bot] handleInbound failed: ${describe(err)}`)
1166
+ logger.error(`[slack-bot] handleInbound failed: ${describeError(err)}`)
1166
1167
  } finally {
1167
1168
  inflightInbounds--
1168
1169
  if (inflightInbounds === 0 && stopWaiters.length > 0) {
@@ -1181,7 +1182,7 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
1181
1182
  await client.login({ token: options.token })
1182
1183
  } catch (err) {
1183
1184
  started = false
1184
- logger.error(`[slack-bot] login failed: ${describe(err)}`)
1185
+ logger.error(`[slack-bot] login failed: ${describeError(err)}`)
1185
1186
  throw err
1186
1187
  }
1187
1188
 
@@ -1196,7 +1197,7 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
1196
1197
  logger.info(`[slack-bot] authenticated as ${auth.user ?? auth.user_id} in team ${auth.team ?? auth.team_id}`)
1197
1198
  } catch (err) {
1198
1199
  started = false
1199
- logger.error(`[slack-bot] auth.test failed: ${describe(err)}`)
1200
+ logger.error(`[slack-bot] auth.test failed: ${describeError(err)}`)
1200
1201
  throw err
1201
1202
  }
1202
1203
 
@@ -1208,7 +1209,7 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
1208
1209
  logger.warn('[slack-bot] disconnected; SDK will reconnect with backoff')
1209
1210
  })
1210
1211
  listener.on('error', (err) => {
1211
- logger.error(`[slack-bot] socket-mode error: ${describe(err)}`)
1212
+ logger.error(`[slack-bot] socket-mode error: ${describeError(err)}`)
1212
1213
  })
1213
1214
  listener.on('message', ({ ack, event }) => {
1214
1215
  // Ack first so Slack stops retrying; failure to ack causes duplicate
@@ -1280,7 +1281,7 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
1280
1281
  botUserId = null
1281
1282
  teamId = null
1282
1283
  started = false
1283
- logger.error(`[slack-bot] listener start failed: ${describe(err)}`)
1284
+ logger.error(`[slack-bot] listener start failed: ${describeError(err)}`)
1284
1285
  throw err
1285
1286
  }
1286
1287
  },
@@ -1315,10 +1316,6 @@ export function createSlackBotAdapter(options: SlackBotAdapterOptions): SlackBot
1315
1316
  }
1316
1317
  }
1317
1318
 
1318
- function describe(err: unknown): string {
1319
- return err instanceof Error ? err.message : String(err)
1320
- }
1321
-
1322
1319
  function dropHint(reason: InboundDropReason): string {
1323
1320
  switch (reason) {
1324
1321
  case 'empty_text':
@@ -32,6 +32,7 @@ import type {
32
32
  import { chunkMarkdown } from '@/markdown'
33
33
  import type { SlackAccountRecord } from '@/secrets/schema'
34
34
 
35
+ import { describeError } from './describe-error'
35
36
  import { createSlackAuthorResolver } from './slack-author-resolver'
36
37
  import { slackTsToMillis } from './slack-bot-time'
37
38
  import { createSlackChannelResolver } from './slack-channel-resolver'
@@ -50,6 +51,8 @@ const consoleLogger: SlackAdapterLogger = {
50
51
  error: (m) => console.error(m),
51
52
  }
52
53
 
54
+ const LISTENER_CONNECT_TIMEOUT_MS = 15_000
55
+
53
56
  export type SlackCredentialStore = {
54
57
  getAccount(id?: string): Promise<SlackAccountRecord | null>
55
58
  }
@@ -102,7 +105,7 @@ export function createSlackOutboundCallback(deps: {
102
105
  }
103
106
  return { ok: true }
104
107
  } catch (err) {
105
- const message = describe(err)
108
+ const message = describeError(err)
106
109
  deps.logger.error(`[slack] outbound failed: ${message}`)
107
110
  return { ok: false, error: message }
108
111
  }
@@ -118,7 +121,7 @@ export function createSlackHistoryCallback(deps: {
118
121
  const messages = await deps.client.getMessages(args.chat, { limit: clampLimit(args.limit, 100) })
119
122
  return { ok: true, messages: messages.map(mapSlackHistoryMessage).reverse() }
120
123
  } catch (err) {
121
- const message = describe(err)
124
+ const message = describeError(err)
122
125
  deps.logger.warn(`[slack] history fetch failed: ${message}`)
123
126
  return { ok: false, error: message }
124
127
  }
@@ -150,7 +153,9 @@ export function createSlackMembershipResolver(deps: {
150
153
  if (truncated) return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated }
151
154
  return { humans: humanMemberIds.length, bots, fetchedAt: now(), truncated, humanMemberIds }
152
155
  } catch (err) {
153
- deps.logger.warn(`[slack] membership channel=${key.chat} failed: ${describe(err)}; deriving from recent history`)
156
+ deps.logger.warn(
157
+ `[slack] membership channel=${key.chat} failed: ${describeError(err)}; deriving from recent history`,
158
+ )
154
159
  return await deriveMembershipFromHistory({
155
160
  fetchHistory: (limit) => deps.historyCallback({ chat: key.chat, thread: key.thread, limit }),
156
161
  now,
@@ -174,7 +179,7 @@ export function createSlackFetchAttachmentCallback(deps: {
174
179
  size: buffer.length,
175
180
  }
176
181
  } catch (err) {
177
- const message = describe(err)
182
+ const message = describeError(err)
178
183
  deps.logger.error(`[slack] fetchAttachment failed for ${ref}: ${message}`)
179
184
  return { ok: false, error: message }
180
185
  }
@@ -239,7 +244,7 @@ export function createSlackAdapter(options: SlackAdapterOptions): SlackAdapter {
239
244
  logger.info(`[slack] routed id=${event.ts} ${tag} mention=${payload.isBotMention}`)
240
245
  await options.router.route(payload)
241
246
  } catch (err) {
242
- logger.error(`[slack] handleInbound failed: ${describe(err)}`)
247
+ logger.error(`[slack] handleInbound failed: ${describeError(err)}`)
243
248
  } finally {
244
249
  inflightInbounds--
245
250
  if (inflightInbounds === 0 && stopWaiters.length > 0) {
@@ -274,26 +279,52 @@ export function createSlackAdapter(options: SlackAdapterOptions): SlackAdapter {
274
279
  started = false
275
280
  selfUserId = null
276
281
  teamId = ''
277
- logger.error(`[slack] login failed: ${describe(err)}`)
282
+ logger.error(`[slack] login failed: ${describeError(err)}`)
278
283
  throw err
279
284
  }
280
285
 
281
286
  listener = createListener(client)
282
287
  let listenerConnected = false
283
288
  let listenerStartupError: Error | null = null
289
+
290
+ // SlackListener.start() resolves as soon as the WebSocket is opened, but
291
+ // 'connected' is only emitted later when Slack sends the `hello` frame. A
292
+ // synchronous post-start check therefore always fails the race. Gate
293
+ // startup on a deferred settled by the 'connected'/'error' handlers below.
294
+ let settleStartup: (() => void) | null = null
295
+ let failStartup: ((err: Error) => void) | null = null
296
+ const startupTimer = setTimeout(() => {
297
+ failStartup?.(new Error(`listener did not connect within ${LISTENER_CONNECT_TIMEOUT_MS}ms`))
298
+ }, LISTENER_CONNECT_TIMEOUT_MS)
299
+ const connectedPromise = new Promise<void>((resolve, reject) => {
300
+ settleStartup = () => {
301
+ clearTimeout(startupTimer)
302
+ resolve()
303
+ }
304
+ failStartup = (err) => {
305
+ clearTimeout(startupTimer)
306
+ reject(err)
307
+ }
308
+ })
309
+
284
310
  listener.on('connected', (info) => {
285
311
  listenerConnected = true
286
312
  connected = true
287
313
  selfUserId = info.self.id
288
314
  teamId = info.team.id
315
+ settleStartup?.()
289
316
  })
290
317
  listener.on('disconnected', () => {
291
318
  connected = false
292
319
  logger.warn('[slack] disconnected')
293
320
  })
294
321
  listener.on('error', (err) => {
295
- if (!listenerConnected && listenerStartupError === null) listenerStartupError = err
296
- logger.error(`[slack] listener error: ${describe(err)}`)
322
+ const error = err instanceof Error ? err : new Error(describeError(err))
323
+ if (!listenerConnected && listenerStartupError === null) {
324
+ listenerStartupError = error
325
+ failStartup?.(error)
326
+ }
327
+ logger.error(`[slack] listener error: ${describeError(err)}`)
297
328
  })
298
329
  listener.on('message', (event) => void handleMessage(event))
299
330
  listener.on('reaction_added', (event) => handleReaction('added', event))
@@ -319,25 +350,22 @@ export function createSlackAdapter(options: SlackAdapterOptions): SlackAdapter {
319
350
  options.router.unregisterMembership('slack', membershipResolver)
320
351
  options.router.unregisterReaction('slack', reactionCallback)
321
352
  options.router.unregisterRemoveReaction('slack', removeReactionCallback)
353
+ clearTimeout(startupTimer)
322
354
  listener?.stop()
323
355
  listener = null
324
356
  selfUserId = null
325
357
  connected = false
326
358
  started = false
327
- logger.error(`[slack] ${reason}: ${describe(cause)}`)
359
+ logger.error(`[slack] ${reason}: ${describeError(cause)}`)
328
360
  throw cause
329
361
  }
330
362
 
331
363
  try {
332
- await listener.start()
364
+ await Promise.all([listener.start(), connectedPromise])
333
365
  } 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
- )
366
+ const cause = err instanceof Error ? err : new Error(describeError(err))
367
+ const reason = listenerStartupError !== null ? 'listener start failed' : 'listener start threw'
368
+ rollbackStart(reason, cause)
341
369
  }
342
370
  },
343
371
 
@@ -399,10 +427,6 @@ function clampLimit(requested: number, max: number): number {
399
427
  return Math.min(Math.floor(requested), max)
400
428
  }
401
429
 
402
- function describe(err: unknown): string {
403
- return err instanceof Error ? err.message : String(err)
404
- }
405
-
406
430
  function dropHint(reason: InboundDropReason): string {
407
431
  switch (reason) {
408
432
  case 'empty_text':
@@ -16,6 +16,7 @@ import type {
16
16
  TypingTarget,
17
17
  } from '@/channels/types'
18
18
 
19
+ import { describeError } from './describe-error'
19
20
  import { classifyInbound, type InboundDropReason, TELEGRAM_WORKSPACE } from './telegram-bot-classify'
20
21
  import { toTelegramMarkdownV2 } from './telegram-bot-format'
21
22
 
@@ -105,7 +106,7 @@ export function createTypingCallback(deps: {
105
106
  logger.warn(`[telegram-bot] typing ${tag} status=${response.status}`)
106
107
  }
107
108
  } catch (err) {
108
- logger.warn(`[telegram-bot] typing ${tag} failed: ${describe(err)}`)
109
+ logger.warn(`[telegram-bot] typing ${tag} failed: ${describeError(err)}`)
109
110
  }
110
111
  }
111
112
  }
@@ -187,7 +188,7 @@ export function createTelegramMembershipResolver(deps: {
187
188
  truncated: true,
188
189
  }
189
190
  } catch (err) {
190
- deps.logger.warn(`[telegram-bot] membership chat=${key.chat} failed: ${describe(err)}`)
191
+ deps.logger.warn(`[telegram-bot] membership chat=${key.chat} failed: ${describeError(err)}`)
191
192
  return { kind: 'transient' } satisfies MembershipResolverFailure
192
193
  }
193
194
  }
@@ -240,7 +241,7 @@ export function createOutboundCallback(deps: {
240
241
  )
241
242
  }
242
243
  } catch (err) {
243
- const message = describe(err)
244
+ const message = describeError(err)
244
245
  logger.error(`[telegram-bot] sendDocument failed for ${path}: ${message}`)
245
246
  return { ok: false, error: `sendDocument failed: ${message}` }
246
247
  }
@@ -263,7 +264,7 @@ export function createOutboundCallback(deps: {
263
264
  const id = String(sent.message_id)
264
265
  return { ok: true, messageId: id, messageIds: [id] }
265
266
  } catch (err) {
266
- const message = describe(err)
267
+ const message = describeError(err)
267
268
  logger.error(`[telegram-bot] sendMessage failed: ${message}`)
268
269
  return { ok: false, error: message }
269
270
  }
@@ -319,7 +320,7 @@ export function createFetchAttachmentCallback(deps: {
319
320
  try {
320
321
  metaResponse = await fetchImpl(`${TELEGRAM_API_BASE}/bot${token}/getFile?file_id=${encodeURIComponent(ref)}`)
321
322
  } catch (err) {
322
- const message = describe(err)
323
+ const message = describeError(err)
323
324
  logger.error(`[telegram-bot] getFile failed for ${ref}: ${message}`)
324
325
  return { ok: false, error: `getFile failed: ${message}` }
325
326
  }
@@ -333,7 +334,7 @@ export function createFetchAttachmentCallback(deps: {
333
334
  try {
334
335
  meta = (await metaResponse.json()) as TelegramFileResponse
335
336
  } catch (err) {
336
- return { ok: false, error: `getFile parse failed: ${describe(err)}` }
337
+ return { ok: false, error: `getFile parse failed: ${describeError(err)}` }
337
338
  }
338
339
  if (!meta.ok || meta.result === undefined || meta.result.file_path === undefined) {
339
340
  const message = meta.description ?? 'getFile returned no file_path'
@@ -345,7 +346,7 @@ export function createFetchAttachmentCallback(deps: {
345
346
  try {
346
347
  response = await fetchImpl(downloadUrl)
347
348
  } catch (err) {
348
- const message = describe(err)
349
+ const message = describeError(err)
349
350
  logger.error(`[telegram-bot] download failed for ${ref}: ${message}`)
350
351
  return { ok: false, error: message }
351
352
  }
@@ -449,7 +450,7 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
449
450
  )
450
451
  await options.router.route(verdict.payload)
451
452
  } catch (err) {
452
- logger.error(`[telegram-bot] handleInbound failed: ${describe(err)}`)
453
+ logger.error(`[telegram-bot] handleInbound failed: ${describeError(err)}`)
453
454
  } finally {
454
455
  inflightInbounds--
455
456
  if (inflightInbounds === 0 && stopWaiters.length > 0) {
@@ -468,7 +469,7 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
468
469
  await client.login({ token: options.token })
469
470
  } catch (err) {
470
471
  started = false
471
- logger.error(`[telegram-bot] login failed: ${describe(err)}`)
472
+ logger.error(`[telegram-bot] login failed: ${describeError(err)}`)
472
473
  throw err
473
474
  }
474
475
 
@@ -486,7 +487,7 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
486
487
  } catch (err) {
487
488
  started = false
488
489
  botUser = null
489
- logger.error(`[telegram-bot] getMe failed (likely invalid token): ${describe(err)}`)
490
+ logger.error(`[telegram-bot] getMe failed (likely invalid token): ${describeError(err)}`)
490
491
  throw err
491
492
  }
492
493
 
@@ -515,11 +516,11 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
515
516
  logger.warn('[telegram-bot] disconnected; SDK will reconnect with backoff')
516
517
  })
517
518
  listener.on('error', (err) => {
518
- const error = err instanceof Error ? err : new Error(String(err))
519
+ const error = err instanceof Error ? err : new Error(describeError(err))
519
520
  if (!listenerConnected && listenerStartupError === null) {
520
521
  listenerStartupError = error
521
522
  }
522
- logger.error(`[telegram-bot] listener error: ${describe(error)}`)
523
+ logger.error(`[telegram-bot] listener error: ${describeError(err)}`)
523
524
  })
524
525
  listener.on('message', (event) => {
525
526
  void handleMessage(event)
@@ -548,14 +549,14 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
548
549
  listener = null
549
550
  botUser = null
550
551
  started = false
551
- logger.error(`[telegram-bot] ${reason}: ${describe(cause)}`)
552
+ logger.error(`[telegram-bot] ${reason}: ${describeError(cause)}`)
552
553
  throw cause
553
554
  }
554
555
 
555
556
  try {
556
557
  await listener.start()
557
558
  } catch (err) {
558
- rollbackStart('listener start threw', err instanceof Error ? err : new Error(String(err)))
559
+ rollbackStart('listener start threw', err instanceof Error ? err : new Error(describeError(err)))
559
560
  }
560
561
  if (!listenerConnected) {
561
562
  const cause = listenerStartupError ?? new Error('listener.start() returned without emitting connected')
@@ -599,10 +600,6 @@ export function createTelegramBotAdapter(options: TelegramBotAdapterOptions): Te
599
600
  }
600
601
  }
601
602
 
602
- function describe(err: unknown): string {
603
- return err instanceof Error ? err.message : String(err)
604
- }
605
-
606
603
  function dropHint(reason: InboundDropReason): string {
607
604
  switch (reason) {
608
605
  case 'no_user':