typeclaw 0.47.2 → 0.48.1

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 (129) hide show
  1. package/package.json +1 -1
  2. package/src/agent/index.ts +1 -2
  3. package/src/agent/loop-guard.ts +71 -41
  4. package/src/agent/plugin-tools.ts +234 -58
  5. package/src/agent/system-prompt.ts +1 -1
  6. package/src/agent/turn-runner.ts +12 -2
  7. package/src/agent-messenger/config-dir.ts +131 -0
  8. package/src/agent-messenger/host-config-dir.ts +121 -0
  9. package/src/bundled-plugins/agent-browser/index.ts +0 -38
  10. package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md +1 -1
  11. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +16 -1
  12. package/src/bundled-plugins/memory/append-tool.ts +75 -2
  13. package/src/bundled-plugins/memory/frontmatter.ts +13 -2
  14. package/src/bundled-plugins/memory/load-memory.ts +1 -1
  15. package/src/bundled-plugins/memory/memory-logger.ts +5 -1
  16. package/src/bundled-plugins/memory/secret-detector.ts +7 -0
  17. package/src/bundled-plugins/memory/vector/hybrid.ts +3 -1
  18. package/src/bundled-plugins/memory/vector/passages.ts +5 -1
  19. package/src/bundled-plugins/security/index.ts +148 -98
  20. package/src/bundled-plugins/security/policies/private-surface-read.ts +43 -28
  21. package/src/channels/adapters/discord-bot-edit.ts +3 -5
  22. package/src/channels/adapters/discord-bot-reactions.ts +4 -6
  23. package/src/channels/adapters/discord-bot-slash-commands.ts +3 -1
  24. package/src/channels/adapters/discord-bot.ts +20 -23
  25. package/src/channels/adapters/discord-edit.ts +3 -5
  26. package/src/channels/adapters/discord-reactions.ts +4 -6
  27. package/src/channels/adapters/discord.ts +1 -1
  28. package/src/channels/adapters/github/decoy-reviewer.ts +2 -1
  29. package/src/channels/adapters/github/history.ts +2 -1
  30. package/src/channels/adapters/github/inbound.ts +4 -11
  31. package/src/channels/adapters/github/index.ts +6 -9
  32. package/src/channels/adapters/github/outbound.ts +3 -6
  33. package/src/channels/adapters/github/reactions.ts +3 -2
  34. package/src/channels/adapters/github/reconcile-cooldown-store.ts +4 -6
  35. package/src/channels/adapters/github/reconcile-open-prs.ts +5 -4
  36. package/src/channels/adapters/github/recover-failed-deliveries.ts +2 -5
  37. package/src/channels/adapters/github/review-state.ts +3 -2
  38. package/src/channels/adapters/github/review-thread-resolver.ts +3 -2
  39. package/src/channels/adapters/github/webhook-register.ts +5 -8
  40. package/src/channels/adapters/instagram-channel-resolver.ts +3 -5
  41. package/src/channels/adapters/instagram.ts +1 -1
  42. package/src/channels/adapters/kakaotalk-author-resolver.ts +2 -5
  43. package/src/channels/adapters/kakaotalk-channel-resolver.ts +3 -5
  44. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +2 -1
  45. package/src/channels/adapters/kakaotalk-membership.ts +2 -5
  46. package/src/channels/adapters/kakaotalk-typing.ts +1 -1
  47. package/src/channels/adapters/kakaotalk.ts +1 -1
  48. package/src/channels/adapters/line-channel-resolver.ts +3 -5
  49. package/src/channels/adapters/line.ts +1 -1
  50. package/src/channels/adapters/slack-bot-edit.ts +1 -1
  51. package/src/channels/adapters/slack-bot-reactions.ts +4 -6
  52. package/src/channels/adapters/slack-bot.ts +8 -8
  53. package/src/channels/adapters/slack-edit.ts +3 -5
  54. package/src/channels/adapters/slack-reactions.ts +4 -6
  55. package/src/channels/adapters/slack.ts +1 -1
  56. package/src/channels/adapters/teams-edit.ts +2 -5
  57. package/src/channels/adapters/teams.ts +1 -1
  58. package/src/channels/adapters/telegram-bot-edit.ts +4 -7
  59. package/src/channels/adapters/telegram-bot.ts +1 -1
  60. package/src/channels/adapters/webex-bot.ts +1 -1
  61. package/src/channels/adapters/webex-edit.ts +3 -5
  62. package/src/channels/adapters/webex.ts +1 -1
  63. package/src/channels/github-review-claim.ts +89 -4
  64. package/src/channels/github-token-bridge.ts +2 -1
  65. package/src/channels/manager.ts +478 -64
  66. package/src/channels/membership-cache.ts +2 -5
  67. package/src/channels/persistence.ts +3 -6
  68. package/src/channels/reloadable.ts +23 -6
  69. package/src/channels/router.ts +134 -56
  70. package/src/channels/tunnel-bridge.ts +2 -1
  71. package/src/channels/types.ts +6 -3
  72. package/src/cli/channel.ts +15 -16
  73. package/src/cli/hostd.ts +61 -38
  74. package/src/cli/init.ts +21 -7
  75. package/src/cli/model.ts +6 -3
  76. package/src/cli/restart.ts +13 -15
  77. package/src/compose/restart.ts +14 -6
  78. package/src/config/config.ts +10 -0
  79. package/src/config/providers.ts +68 -0
  80. package/src/container/agent-operation-lock.ts +85 -0
  81. package/src/container/controller.ts +6 -0
  82. package/src/container/index.ts +8 -0
  83. package/src/container/restart.ts +55 -0
  84. package/src/container/shared.ts +5 -0
  85. package/src/container/start.ts +70 -4
  86. package/src/container/stop.ts +17 -1
  87. package/src/dependencies/bin-resolver.ts +88 -0
  88. package/src/dependencies/bins.ts +227 -0
  89. package/src/dependencies/index.ts +17 -0
  90. package/src/doctor/checks.ts +2 -0
  91. package/src/doctor/operational-incidents.ts +32 -0
  92. package/src/hostd/credential-rotation-apply.ts +94 -0
  93. package/src/hostd/daemon.ts +1 -1
  94. package/src/hostd/paths.ts +17 -0
  95. package/src/hostd/supervisor.ts +27 -10
  96. package/src/init/dockerfile.ts +6 -5
  97. package/src/init/env-file.ts +42 -18
  98. package/src/init/instagram-auth.ts +55 -31
  99. package/src/init/kakaotalk-auth.ts +1 -5
  100. package/src/init/line-auth.ts +45 -29
  101. package/src/init/models-dev.ts +131 -10
  102. package/src/init/opengateway-catalog.ts +120 -0
  103. package/src/init/validate-api-key.ts +26 -4
  104. package/src/operations/classify-tool-outcome.ts +151 -0
  105. package/src/operations/incidents.ts +274 -0
  106. package/src/operations/index.ts +3 -0
  107. package/src/operations/remediations.ts +41 -0
  108. package/src/reload/client.ts +8 -2
  109. package/src/reload/docker-exec-client.ts +10 -2
  110. package/src/reload/index.ts +1 -1
  111. package/src/reload/recover.ts +5 -3
  112. package/src/reload/registry.ts +5 -5
  113. package/src/reload/types.ts +9 -1
  114. package/src/run/index.ts +5 -0
  115. package/src/sandbox/canonical-secrets.ts +10 -1
  116. package/src/sandbox/dependency-bins.ts +125 -0
  117. package/src/sandbox/hidden-paths.ts +4 -1
  118. package/src/sandbox/index.ts +8 -0
  119. package/src/sandbox/policy.ts +1 -1
  120. package/src/sandbox/privileged-runtime.ts +7 -12
  121. package/src/sandbox/runtime-private.ts +4 -0
  122. package/src/sandbox/writable-zones.ts +4 -4
  123. package/src/server/index.ts +7 -5
  124. package/src/shared/protocol.ts +6 -1
  125. package/src/test-helpers/fake-agent-operation-lock.ts +66 -0
  126. package/typeclaw.schema.json +10 -5
  127. package/src/bundled-plugins/agent-browser/shim-install.ts +0 -179
  128. package/src/bundled-plugins/agent-browser/shim.ts +0 -108
  129. /package/src/channels/{adapters/describe-error.ts → describe-error.ts} +0 -0
@@ -50,6 +50,7 @@ import type {
50
50
  TypingTarget,
51
51
  } from '@/channels/types'
52
52
 
53
+ import { describeError } from '../describe-error'
53
54
  import { createDiscordChannelResolver } from './discord-bot-channel-resolver'
54
55
  import {
55
56
  classifyInbound,
@@ -174,7 +175,7 @@ export function createTypingCallback(deps: {
174
175
  logger.warn(`[discord-bot] typing ${tag} status=${response.status}`)
175
176
  }
176
177
  } catch (err) {
177
- logger.warn(`[discord-bot] typing ${tag} failed: ${describe(err)}`)
178
+ logger.warn(`[discord-bot] typing ${tag} failed: ${describeError(err)}`)
178
179
  }
179
180
  }
180
181
  }
@@ -503,7 +504,7 @@ async function fetchDiscordJson<T>(fetchFn: typeof fetch, url: string, token: st
503
504
  try {
504
505
  response = await fetchFn(url, { method: 'GET', headers: { Authorization: `Bot ${token}` } })
505
506
  } catch (err) {
506
- return { ok: false, status: null, reason: describe(err), failure: { kind: 'transient' } }
507
+ return { ok: false, status: null, reason: describeError(err), failure: { kind: 'transient' } }
507
508
  }
508
509
  if (!response.ok) {
509
510
  return {
@@ -516,7 +517,7 @@ async function fetchDiscordJson<T>(fetchFn: typeof fetch, url: string, token: st
516
517
  try {
517
518
  return { ok: true, value: (await response.json()) as T }
518
519
  } catch (err) {
519
- return { ok: false, status: null, reason: `parse failed: ${describe(err)}`, failure: { kind: 'transient' } }
520
+ return { ok: false, status: null, reason: `parse failed: ${describeError(err)}`, failure: { kind: 'transient' } }
520
521
  }
521
522
  }
522
523
 
@@ -578,7 +579,7 @@ export function createDiscordHistoryCallback(deps: {
578
579
  headers: { Authorization: `Bot ${token}` },
579
580
  })
580
581
  } catch (err) {
581
- const message = err instanceof Error ? err.message : String(err)
582
+ const message = describeError(err)
582
583
  logger.warn(`[discord-bot] history fetch failed: ${message}`)
583
584
  return { ok: false, error: message }
584
585
  }
@@ -588,7 +589,7 @@ export function createDiscordHistoryCallback(deps: {
588
589
  try {
589
590
  raw = (await response.json()) as DiscordRawHistoryMessage[]
590
591
  } catch (err) {
591
- const message = err instanceof Error ? err.message : String(err)
592
+ const message = describeError(err)
592
593
  return { ok: false, error: `parse failed: ${message}` }
593
594
  }
594
595
 
@@ -628,7 +629,7 @@ export function createDiscordMessageGetCallback(deps: {
628
629
  headers: { Authorization: `Bot ${token}` },
629
630
  })
630
631
  } catch (err) {
631
- const message = err instanceof Error ? err.message : String(err)
632
+ const message = describeError(err)
632
633
  logger.warn(`[discord-bot] message get failed: ${message}`)
633
634
  return { ok: false, error: message }
634
635
  }
@@ -638,7 +639,7 @@ export function createDiscordMessageGetCallback(deps: {
638
639
  try {
639
640
  raw = (await response.json()) as DiscordRawHistoryMessage
640
641
  } catch (err) {
641
- const message = err instanceof Error ? err.message : String(err)
642
+ const message = describeError(err)
642
643
  return { ok: false, error: `parse failed: ${message}` }
643
644
  }
644
645
  return { ok: true, message: mapDiscordMessage(raw, botUserIdRef()) }
@@ -665,7 +666,7 @@ export function createDiscordListCallback(deps: {
665
666
  headers: { Authorization: `Bot ${token}` },
666
667
  })
667
668
  } catch (err) {
668
- const message = err instanceof Error ? err.message : String(err)
669
+ const message = describeError(err)
669
670
  logger.warn(`[discord-bot] channel list failed: ${message}`)
670
671
  return { ok: false, error: message }
671
672
  }
@@ -674,7 +675,7 @@ export function createDiscordListCallback(deps: {
674
675
  try {
675
676
  raw = (await response.json()) as DiscordListChannel[]
676
677
  } catch (err) {
677
- const message = err instanceof Error ? err.message : String(err)
678
+ const message = describeError(err)
678
679
  return { ok: false, error: `parse failed: ${message}` }
679
680
  }
680
681
  const entries = raw
@@ -819,7 +820,7 @@ export function createOutboundCallback(deps: {
819
820
  )
820
821
  }
821
822
  } catch (err) {
822
- const message = err instanceof Error ? err.message : String(err)
823
+ const message = describeError(err)
823
824
  logger.error(`[discord-bot] uploadFile failed for ${path}: ${message}`)
824
825
  return { ok: false, error: `uploadFile failed: ${message}` }
825
826
  }
@@ -841,7 +842,7 @@ export function createOutboundCallback(deps: {
841
842
  logger.info(`[discord-bot] sent id=${sent.id} ${tag}`)
842
843
  return { ok: true, messageId: sent.id, messageIds: [sent.id] }
843
844
  } catch (err) {
844
- const message = err instanceof Error ? err.message : String(err)
845
+ const message = describeError(err)
845
846
  logger.error(`[discord-bot] sendMessage failed: ${message}`)
846
847
  return { ok: false, error: message }
847
848
  }
@@ -938,7 +939,7 @@ export function createFetchAttachmentCallback(deps: {
938
939
  size: buffer.length,
939
940
  }
940
941
  } catch (err) {
941
- const message = err instanceof Error ? err.message : String(err)
942
+ const message = describeError(err)
942
943
  logger.error(`[discord-bot] fetchAttachment failed for ${url.toString()}: ${message}`)
943
944
  return { ok: false, error: message }
944
945
  }
@@ -1016,11 +1017,11 @@ export function createInteractionHandler(
1016
1017
  deps.logger.info(`[discord-bot] interaction /${command.name} result=${result.kind} ${inboundTag}`)
1017
1018
  } catch (err) {
1018
1019
  deps.logger.info(
1019
- `[discord-bot] interaction /${command.name} result=${result.kind} (channel-tag resolution failed: ${describe(err)})`,
1020
+ `[discord-bot] interaction /${command.name} result=${result.kind} (channel-tag resolution failed: ${describeError(err)})`,
1020
1021
  )
1021
1022
  }
1022
1023
  } catch (err) {
1023
- deps.logger.error(`[discord-bot] handleInteraction failed: ${describe(err)}`)
1024
+ deps.logger.error(`[discord-bot] handleInteraction failed: ${describeError(err)}`)
1024
1025
  }
1025
1026
  }
1026
1027
  }
@@ -1180,7 +1181,7 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
1180
1181
  )
1181
1182
  await options.router.route(payload)
1182
1183
  } catch (err) {
1183
- logger.error(`[discord-bot] handleInbound failed: ${describe(err)}`)
1184
+ logger.error(`[discord-bot] handleInbound failed: ${describeError(err)}`)
1184
1185
  } finally {
1185
1186
  inflightInbounds--
1186
1187
  if (inflightInbounds === 0 && stopWaiters.length > 0) {
@@ -1199,7 +1200,7 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
1199
1200
  await client.login({ token: options.token })
1200
1201
  } catch (err) {
1201
1202
  started = false
1202
- logger.error(`[discord-bot] login failed: ${describe(err)}`)
1203
+ logger.error(`[discord-bot] login failed: ${describeError(err)}`)
1203
1204
  throw err
1204
1205
  }
1205
1206
 
@@ -1246,7 +1247,7 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
1246
1247
  // distinct SDK error contract without treating transient transport
1247
1248
  // errors as disconnects.
1248
1249
  if (isTerminalGatewayClose(err)) connected = false
1249
- logger.error(`[discord-bot] gateway error: ${describe(err)}`)
1250
+ logger.error(`[discord-bot] gateway error: ${describeError(err)}`)
1250
1251
  })
1251
1252
  listener.on('message_create', (event) => {
1252
1253
  void handleMessageCreate(event)
@@ -1293,7 +1294,7 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
1293
1294
  botUserId = null
1294
1295
  connected = false
1295
1296
  started = false
1296
- logger.error(`[discord-bot] listener start failed: ${describe(err)}`)
1297
+ logger.error(`[discord-bot] listener start failed: ${describeError(err)}`)
1297
1298
  throw err
1298
1299
  }
1299
1300
 
@@ -1333,7 +1334,7 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
1333
1334
  )
1334
1335
  },
1335
1336
  (error: unknown) => {
1336
- logger.warn(`[discord-bot] historical provenance enrichment failed: ${describe(error)}`)
1337
+ logger.warn(`[discord-bot] historical provenance enrichment failed: ${describeError(error)}`)
1337
1338
  },
1338
1339
  )
1339
1340
  }
@@ -1377,10 +1378,6 @@ function isTerminalGatewayClose(err: unknown): boolean {
1377
1378
  return err instanceof Error && TERMINAL_GATEWAY_CLOSE_PATTERN.test(err.message)
1378
1379
  }
1379
1380
 
1380
- function describe(err: unknown): string {
1381
- return err instanceof Error ? err.message : String(err)
1382
- }
1383
-
1384
1381
  // Operator hints appended to drop logs. Kept short — full guidance lives in
1385
1382
  // docs. The empty_content hint is the highest-leverage one because that
1386
1383
  // failure mode is invisible from Discord's side (bot stays green).
@@ -2,6 +2,8 @@ import type { DiscordClient } from 'agent-messenger/discord'
2
2
 
3
3
  import type { EditMessageCallback, EditMessageResult } from '@/channels/types'
4
4
 
5
+ import { describeError } from '../describe-error'
6
+
5
7
  export function createDiscordUserEditMessageCallback(deps: {
6
8
  client: Pick<DiscordClient, 'editMessage'>
7
9
  }): EditMessageCallback {
@@ -17,7 +19,7 @@ export function createDiscordUserEditMessageCallback(deps: {
17
19
  try {
18
20
  await deps.client.editMessage(channelId, req.messageId, req.text)
19
21
  } catch (err) {
20
- return { ok: false, error: describe(err), code: classifyEditError(err) }
22
+ return { ok: false, error: describeError(err), code: classifyEditError(err) }
21
23
  }
22
24
  return { ok: true }
23
25
  }
@@ -45,7 +47,3 @@ function classifyEditError(err: unknown): NonNullable<(EditMessageResult & { ok:
45
47
  return 'not-found'
46
48
  }
47
49
  }
48
-
49
- function describe(err: unknown): string {
50
- return err instanceof Error ? err.message : String(err)
51
- }
@@ -8,6 +8,8 @@ import type {
8
8
  RemoveReactionCallback,
9
9
  } from '@/channels/types'
10
10
 
11
+ import { describeError } from '../describe-error'
12
+
11
13
  export type DiscordReactionTarget = { channel: string; message: string }
12
14
  export type DiscordReactionRemovalTarget = { channel: string; message: string; emoji: string }
13
15
 
@@ -78,7 +80,7 @@ export function createDiscordReactionCallback(deps: { client: Pick<DiscordClient
78
80
  try {
79
81
  await deps.client.addReaction(target.channel, target.message, unicode)
80
82
  } catch (err) {
81
- return { ok: false, error: describe(err), code: classifyDiscordError(err) }
83
+ return { ok: false, error: describeError(err), code: classifyDiscordError(err) }
82
84
  }
83
85
  return { ok: true, reactionRef: encodeDiscordRemovalRef({ ...target, emoji: unicode }) }
84
86
  }
@@ -94,7 +96,7 @@ export function createDiscordRemoveReactionCallback(deps: {
94
96
  try {
95
97
  await deps.client.removeReaction(target.channel, target.message, target.emoji)
96
98
  } catch (err) {
97
- return { ok: false, error: describe(err), code: classifyDiscordError(err) }
99
+ return { ok: false, error: describeError(err), code: classifyDiscordError(err) }
98
100
  }
99
101
  return { ok: true }
100
102
  }
@@ -132,7 +134,3 @@ function parseRecord(value: string): Record<string, unknown> | null {
132
134
  ? (parsed as Record<string, unknown>)
133
135
  : null
134
136
  }
135
-
136
- function describe(err: unknown): string {
137
- return err instanceof Error ? err.message : String(err)
138
- }
@@ -33,7 +33,7 @@ import type {
33
33
  import { chunkMarkdown } from '@/markdown'
34
34
  import type { DiscordAccountRecord } from '@/secrets/schema'
35
35
 
36
- import { describeError } from './describe-error'
36
+ import { describeError } from '../describe-error'
37
37
  import { createDiscordAuthorResolver } from './discord-author-resolver'
38
38
  import { createDiscordChannelResolver } from './discord-channel-resolver'
39
39
  import { classifyInbound, type InboundDropReason } from './discord-classify'
@@ -1,3 +1,4 @@
1
+ import { describeError } from '../../describe-error'
1
2
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
2
3
 
3
4
  // `absent` separates "GitHub says the reviewer is already not requested"
@@ -38,6 +39,6 @@ export async function removeRequestedReviewer(params: {
38
39
  reason: `GitHub API ${response.status}${message !== '' ? `: ${message}` : ''}`,
39
40
  }
40
41
  } catch (err) {
41
- return { kind: 'failed', reason: err instanceof Error ? err.message : String(err) }
42
+ return { kind: 'failed', reason: describeError(err) }
42
43
  }
43
44
  }
@@ -1,5 +1,6 @@
1
1
  import type { ChannelHistoryMessage, FetchHistoryArgs, FetchHistoryResult, HistoryCallback } from '@/channels/types'
2
2
 
3
+ import { describeError } from '../../describe-error'
3
4
  import type { GithubAuthContext } from './auth'
4
5
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
5
6
  import { parseChat, parseRepo } from './outbound'
@@ -38,7 +39,7 @@ export function createGithubHistoryCallback(options: {
38
39
  ? { ok: true, messages: raw.map(mapComment), nextCursor }
39
40
  : { ok: true, messages: raw.map(mapComment) }
40
41
  } catch (err) {
41
- return { ok: false, error: err instanceof Error ? err.message : String(err) }
42
+ return { ok: false, error: describeError(err) }
42
43
  }
43
44
  }
44
45
  }
@@ -3,6 +3,7 @@ import { createHmac, timingSafeEqual } from 'node:crypto'
3
3
  import type { GithubReviewOn } from '@/channels/schema'
4
4
  import type { InboundMessage } from '@/channels/types'
5
5
 
6
+ import { describeError } from '../../describe-error'
6
7
  import type { GithubAuthContext } from './auth'
7
8
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
8
9
  import { removeRequestedReviewer } from './decoy-reviewer'
@@ -204,9 +205,7 @@ function maybeScheduleDecoyReviewerDrop(input: {
204
205
  options.logger.warn(`[github] failed to drop decoy reviewer @${decoyLogin} from ${target}: ${result.reason}`)
205
206
  }
206
207
  } catch (err) {
207
- options.logger.warn(
208
- `[github] failed to drop decoy reviewer @${decoyLogin} from ${target}: ${err instanceof Error ? err.message : String(err)}`,
209
- )
208
+ options.logger.warn(`[github] failed to drop decoy reviewer @${decoyLogin} from ${target}: ${describeError(err)}`)
210
209
  }
211
210
  })
212
211
  }
@@ -295,9 +294,7 @@ function scheduleReviewFollowup(input: {
295
294
  ),
296
295
  )
297
296
  } catch (err) {
298
- options.logger.warn(
299
- `[github] review followup failed for ${target}: ${err instanceof Error ? err.message : String(err)}`,
300
- )
297
+ options.logger.warn(`[github] review followup failed for ${target}: ${describeError(err)}`)
301
298
  }
302
299
  })
303
300
  }
@@ -944,7 +941,7 @@ async function resolveTeamMembership(
944
941
  try {
945
942
  return await options.isBotInTeam({ org, slug: team.slug, login: selfLogin })
946
943
  } catch (err) {
947
- options.logger.warn(`[github] team membership lookup failed: ${describe(err)}`)
944
+ options.logger.warn(`[github] team membership lookup failed: ${describeError(err)}`)
948
945
  return false
949
946
  }
950
947
  }
@@ -1105,7 +1102,3 @@ function readBoolean(obj: Record<string, unknown> | null, key: string): boolean
1105
1102
  function ok(): Response {
1106
1103
  return new Response('ok', { status: 200 })
1107
1104
  }
1108
-
1109
- function describe(err: unknown): string {
1110
- return err instanceof Error ? err.message : String(err)
1111
- }
@@ -5,6 +5,7 @@ import type { ChannelSelfIdentityResolver, InboundMessage } from '@/channels/typ
5
5
  import { resolveSecret } from '@/secrets/resolve'
6
6
  import type { GithubSecretsBlock } from '@/secrets/schema'
7
7
 
8
+ import { describeError } from '../../describe-error'
8
9
  import { buildAuthStrategy, type GithubAuthContext } from './auth'
9
10
  import { createGithubChannelNameResolver } from './channel-resolver'
10
11
  import { createDeliveryDedup } from './dedup'
@@ -206,7 +207,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
206
207
  void Promise.resolve()
207
208
  .then(() => options.router.route(message))
208
209
  .catch((err: unknown) => {
209
- logger.error(`[github] route failed: ${err instanceof Error ? err.message : String(err)}`)
210
+ logger.error(`[github] route failed: ${describeError(err)}`)
210
211
  })
211
212
  }
212
213
  const handlerOptions: GithubWebhookHandlerOptions = {
@@ -281,9 +282,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
281
282
  if (tokenRefreshIntervalMs > 0) {
282
283
  const refresh = () => {
283
284
  seedGhToken().catch((err) => {
284
- logger.error(
285
- `[github] periodic token refresh failed: ${err instanceof Error ? err.message : String(err)}`,
286
- )
285
+ logger.error(`[github] periodic token refresh failed: ${describeError(err)}`)
287
286
  })
288
287
  }
289
288
  tokenRefreshTimer = setIntervalFn(refresh, tokenRefreshIntervalMs)
@@ -389,7 +388,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
389
388
  fetchImpl,
390
389
  cooldownStore: store,
391
390
  }).catch((err: unknown) => {
392
- logger.warn(`[github] reconcile pass failed: ${err instanceof Error ? err.message : String(err)}`)
391
+ logger.warn(`[github] reconcile pass failed: ${describeError(err)}`)
393
392
  })
394
393
  if (reconcileCooldownStore !== null) {
395
394
  await runReconcile(reconcileCooldownStore)
@@ -421,7 +420,7 @@ export function createGithubAdapter(options: GithubAdapterOptions): GithubAdapte
421
420
  logger,
422
421
  fetchImpl,
423
422
  }).catch((err: unknown) => {
424
- logger.warn(`[github] delivery recovery sweep failed: ${err instanceof Error ? err.message : String(err)}`)
423
+ logger.warn(`[github] delivery recovery sweep failed: ${describeError(err)}`)
425
424
  })
426
425
  }
427
426
  deliveryRecoveryTimer = setIntervalFn(sweep, deliveryRecoveryIntervalMs)
@@ -589,9 +588,7 @@ async function runAppPermissionPreflight(
589
588
  try {
590
589
  grants = await getGrants(context)
591
590
  } catch (err) {
592
- logger.warn(
593
- `[github] permission preflight skipped for ${label}: ${err instanceof Error ? err.message : String(err)}`,
594
- )
591
+ logger.warn(`[github] permission preflight skipped for ${label}: ${describeError(err)}`)
595
592
  continue
596
593
  }
597
594
  if (grants === undefined) continue
@@ -1,5 +1,6 @@
1
1
  import type { OutboundCallback, OutboundMessage, SendResult } from '@/channels/types'
2
2
 
3
+ import { describeError } from '../../describe-error'
3
4
  import type { GithubAuthContext } from './auth'
4
5
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
5
6
  import {
@@ -160,7 +161,7 @@ async function graphql<T>(
160
161
  if (raw.data === undefined) return { ok: false, error: 'GraphQL response missing data' }
161
162
  return { ok: true, data: raw.data }
162
163
  } catch (err) {
163
- return { ok: false, error: describe(err) }
164
+ return { ok: false, error: describeError(err) }
164
165
  }
165
166
  }
166
167
 
@@ -189,7 +190,7 @@ async function postJson(
189
190
  : baseError
190
191
  return { ok: false, error: decorated }
191
192
  } catch (err) {
192
- return { ok: false, error: describe(err) }
193
+ return { ok: false, error: describeError(err) }
193
194
  }
194
195
  }
195
196
 
@@ -210,7 +211,3 @@ export function parseChat(chat: string): ChatRef | null {
210
211
  }
211
212
  return { kind, number }
212
213
  }
213
-
214
- function describe(err: unknown): string {
215
- return err instanceof Error ? err.message : String(err)
216
- }
@@ -6,6 +6,7 @@ import type {
6
6
  ReactionResult,
7
7
  } from '@/channels/types'
8
8
 
9
+ import { describeError } from '../../describe-error'
9
10
  import type { GithubAuthContext } from './auth'
10
11
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
11
12
  import {
@@ -194,7 +195,7 @@ async function postReaction(
194
195
  body: JSON.stringify({ content: options.content }),
195
196
  })
196
197
  } catch (err) {
197
- return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
198
+ return { ok: false, error: describeError(err), code: 'transient' }
198
199
  }
199
200
  // 201 = reaction created, 200 = the actor already left this same reaction.
200
201
  // Both are success: an :eyes: that's already there is the desired end state,
@@ -229,7 +230,7 @@ async function deleteReaction(
229
230
  headers: githubJsonHeaders(token),
230
231
  })
231
232
  } catch (err) {
232
- return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
233
+ return { ok: false, error: describeError(err), code: 'transient' }
233
234
  }
234
235
  if (response.status === 204) return { ok: true }
235
236
  const text = await response.text().catch(() => '')
@@ -1,6 +1,8 @@
1
1
  import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
2
2
  import { dirname, join } from 'node:path'
3
3
 
4
+ import { describeError } from '../../describe-error'
5
+
4
6
  // Durable per-PR replay cooldown for the open-PR reconcile pass.
5
7
  //
6
8
  // The reconcile pass (reconcile-open-prs.ts) runs on every adapter start() and
@@ -128,7 +130,7 @@ export async function loadReconcileCooldownStore(
128
130
  try {
129
131
  await flush()
130
132
  } catch (err) {
131
- logger.error(`[github] failed to persist reconcile cooldown: ${describe(err)}`)
133
+ logger.error(`[github] failed to persist reconcile cooldown: ${describeError(err)}`)
132
134
  }
133
135
  }
134
136
  },
@@ -146,7 +148,7 @@ async function readMarkers(path: string, logger: ReconcileCooldownLogger): Promi
146
148
  try {
147
149
  parsed = JSON.parse(raw)
148
150
  } catch (err) {
149
- logger.error(`[github] ${path} corrupted: ${describe(err)}; starting fresh`)
151
+ logger.error(`[github] ${path} corrupted: ${describeError(err)}; starting fresh`)
150
152
  return []
151
153
  }
152
154
  if (!isObject(parsed)) {
@@ -172,7 +174,3 @@ function isValidMarker(v: unknown): v is ReconcileMarker {
172
174
  const r = v as Record<string, unknown>
173
175
  return typeof r.repo === 'string' && typeof r.prId === 'number' && typeof r.lastReplayAt === 'number'
174
176
  }
175
-
176
- function describe(err: unknown): string {
177
- return err instanceof Error ? err.message : String(err)
178
- }
@@ -1,6 +1,7 @@
1
1
  import type { GithubReviewOn } from '@/channels/schema'
2
2
  import type { InboundMessage } from '@/channels/types'
3
3
 
4
+ import { describeError } from '../../describe-error'
4
5
  import type { GithubAuthContext } from './auth'
5
6
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
6
7
  import { DEFAULT_RECONCILE_COOLDOWN_MS, type ReconcileCooldownStore } from './reconcile-cooldown-store'
@@ -67,7 +68,7 @@ export async function reconcileOpenPrs(options: ReconcileOpenPrsOptions): Promis
67
68
  options.logger.info(`[github] reconcile ${repo}: replayed ${outcome.replayed}/${outcome.scanned} open PR(s)`)
68
69
  }
69
70
  } catch (err) {
70
- const message = err instanceof Error ? err.message : String(err)
71
+ const message = describeError(err)
71
72
  options.logger.warn(`[github] reconcile ${repo} failed: ${message}`)
72
73
  outcomes.push({ repo, error: message })
73
74
  }
@@ -103,9 +104,9 @@ async function reconcileRepo(
103
104
  await cooldownStore.markReplayed(repo, pr.id, now())
104
105
  } catch (err) {
105
106
  options.logger.warn(
106
- `[github] reconcile ${repo}: skipping PR #${pr.number} replay, cooldown persist failed: ${
107
- err instanceof Error ? err.message : String(err)
108
- }`,
107
+ `[github] reconcile ${repo}: skipping PR #${pr.number} replay, cooldown persist failed: ${describeError(
108
+ err,
109
+ )}`,
109
110
  )
110
111
  continue
111
112
  }
@@ -1,3 +1,4 @@
1
+ import { describeError } from '../../describe-error'
1
2
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
2
3
 
3
4
  // Recovers webhook events whose delivery to our ingress FAILED and that GitHub
@@ -99,7 +100,7 @@ export async function recoverFailedGithubDeliveries(options: RecoverFailedDelive
99
100
  } catch (err) {
100
101
  // Per-hook isolation: one repo's token/list/detail failure must not abort
101
102
  // the others. The next interval retries this hook.
102
- options.logger.warn(`[github] delivery recovery failed for ${hook.repo}: ${describe(err)}`)
103
+ options.logger.warn(`[github] delivery recovery failed for ${hook.repo}: ${describeError(err)}`)
103
104
  }
104
105
  }
105
106
  return { recovered, scanned }
@@ -264,7 +265,3 @@ function nextLink(linkHeader: string | null): string | null {
264
265
  function isRecord(value: unknown): value is Record<string, unknown> {
265
266
  return typeof value === 'object' && value !== null && !Array.isArray(value)
266
267
  }
267
-
268
- function describe(err: unknown): string {
269
- return err instanceof Error ? err.message : String(err)
270
- }
@@ -1,5 +1,6 @@
1
1
  import type { ReviewStateResolver, ReviewStateResult } from '@/channels/types'
2
2
 
3
+ import { describeError } from '../../describe-error'
3
4
  import type { GithubAuthContext } from './auth'
4
5
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
5
6
 
@@ -111,7 +112,7 @@ async function fetchSelfReviews(
111
112
  try {
112
113
  response = await fetchImpl(url, { headers: githubJsonHeaders(token) })
113
114
  } catch (err) {
114
- return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
115
+ return { ok: false, error: describeError(err), code: 'transient' }
115
116
  }
116
117
  if (!response.ok) {
117
118
  const text = await response.text().catch(() => '')
@@ -153,7 +154,7 @@ async function fetchReviewDecision(
153
154
  }),
154
155
  })
155
156
  } catch (err) {
156
- return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
157
+ return { ok: false, error: describeError(err), code: 'transient' }
157
158
  }
158
159
  if (!response.ok) {
159
160
  const text = await response.text().catch(() => '')
@@ -1,5 +1,6 @@
1
1
  import type { ReviewThreadResolveRequest, ReviewThreadResolveResult, ReviewThreadResolver } from '@/channels/types'
2
2
 
3
+ import { describeError } from '../../describe-error'
3
4
  import type { GithubAuthContext } from './auth'
4
5
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
5
6
 
@@ -233,7 +234,7 @@ async function walkThreadPages(
233
234
  } catch (err) {
234
235
  return {
235
236
  kind: 'error',
236
- result: { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' },
237
+ result: { ok: false, error: describeError(err), code: 'transient' },
237
238
  }
238
239
  }
239
240
  const parsed = await parseThreadsPage(response)
@@ -308,7 +309,7 @@ async function runResolveMutation(
308
309
  body: JSON.stringify({ query: RESOLVE_MUTATION, variables: { threadId } }),
309
310
  })
310
311
  } catch (err) {
311
- return { ok: false, error: err instanceof Error ? err.message : String(err), code: 'transient' }
312
+ return { ok: false, error: describeError(err), code: 'transient' }
312
313
  }
313
314
  if (!response.ok) {
314
315
  const text = await response.text().catch(() => '')
@@ -1,3 +1,4 @@
1
+ import { describeError } from '../../describe-error'
1
2
  import { GITHUB_API_BASE, githubJsonHeaders } from './auth-pat'
2
3
 
3
4
  export type RegisterGithubWebhooksOptions = {
@@ -68,7 +69,7 @@ export async function registerGithubWebhooks(
68
69
  try {
69
70
  token = await options.token(repo)
70
71
  } catch (err) {
71
- return { repo, action: 'failed', error: describe(err) }
72
+ return { repo, action: 'failed', error: describeError(err) }
72
73
  }
73
74
  return registerOne(fetchImpl, token, repo, options)
74
75
  }),
@@ -96,7 +97,7 @@ export async function deregisterGithubWebhooks(
96
97
  try {
97
98
  token = await options.token(hook.repo)
98
99
  } catch (err) {
99
- return { ...hook, action: 'failed', error: describe(err) }
100
+ return { ...hook, action: 'failed', error: describeError(err) }
100
101
  }
101
102
  return deleteOne(fetchImpl, token, hook)
102
103
  }),
@@ -137,7 +138,7 @@ async function registerOne(
137
138
  const stalePruned = pruned.filter(Boolean).length
138
139
  return { repo, action: 'updated', hookId: keep!, stalePruned }
139
140
  } catch (err) {
140
- return { repo, action: 'failed', error: describe(err) }
141
+ return { repo, action: 'failed', error: describeError(err) }
141
142
  }
142
143
  }
143
144
 
@@ -166,7 +167,7 @@ async function deleteOne(
166
167
  }
167
168
  return { ...hook, action: 'deleted' }
168
169
  } catch (err) {
169
- return { ...hook, action: 'failed', error: describe(err) }
170
+ return { ...hook, action: 'failed', error: describeError(err) }
170
171
  }
171
172
  }
172
173
 
@@ -351,7 +352,3 @@ function toCoarseEvents(events: readonly string[]): string[] {
351
352
  }
352
353
  return [...seen]
353
354
  }
354
-
355
- function describe(err: unknown): string {
356
- return err instanceof Error ? err.message : String(err)
357
- }
@@ -2,6 +2,8 @@ import type { InstagramChatSummary } from 'agent-messenger/instagram'
2
2
 
3
3
  import type { ChannelKey, ChannelNameResolver, ResolvedChannelNames } from '@/channels/types'
4
4
 
5
+ import { describeError } from '../describe-error'
6
+
5
7
  const DEFAULT_TTL_MS = 5 * 60 * 1000
6
8
  const CHAT_FETCH_LIMIT = 500
7
9
 
@@ -64,7 +66,7 @@ export function createInstagramChannelResolver(options: InstagramChannelResolver
64
66
  const expiresAt = now() + ttlMs
65
67
  for (const chat of chats) ingest(chat, expiresAt)
66
68
  } catch (err) {
67
- options.logger?.warn(`[instagram] channel resolver refresh failed: ${describe(err)}`)
69
+ options.logger?.warn(`[instagram] channel resolver refresh failed: ${describeError(err)}`)
68
70
  }
69
71
  }
70
72
 
@@ -107,7 +109,3 @@ export function createInstagramChannelResolver(options: InstagramChannelResolver
107
109
 
108
110
  return { resolve, lookupChat, refresh, ingestProvisional }
109
111
  }
110
-
111
- function describe(err: unknown): string {
112
- return err instanceof Error ? err.message : String(err)
113
- }
@@ -19,7 +19,7 @@ import type {
19
19
  SendResult,
20
20
  } from '@/channels/types'
21
21
 
22
- import { describeError } from './describe-error'
22
+ import { describeError } from '../describe-error'
23
23
  import { createInstagramChannelResolver } from './instagram-channel-resolver'
24
24
  import { classifyInbound } from './instagram-classify'
25
25
  import { toInstagramPlainText } from './instagram-format'