typeclaw 0.47.2 → 0.48.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 (105) 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 +167 -50
  5. package/src/agent/system-prompt.ts +1 -1
  6. package/src/agent/turn-runner.ts +12 -2
  7. package/src/bundled-plugins/agent-browser/index.ts +0 -38
  8. package/src/bundled-plugins/agent-browser/skills/agent-browser/SKILL.md +1 -1
  9. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +16 -1
  10. package/src/bundled-plugins/memory/append-tool.ts +75 -2
  11. package/src/bundled-plugins/memory/frontmatter.ts +13 -2
  12. package/src/bundled-plugins/memory/load-memory.ts +1 -1
  13. package/src/bundled-plugins/memory/memory-logger.ts +5 -1
  14. package/src/bundled-plugins/memory/secret-detector.ts +7 -0
  15. package/src/bundled-plugins/memory/vector/hybrid.ts +3 -1
  16. package/src/bundled-plugins/memory/vector/passages.ts +5 -1
  17. package/src/bundled-plugins/security/index.ts +148 -98
  18. package/src/bundled-plugins/security/policies/private-surface-read.ts +43 -28
  19. package/src/channels/adapters/discord-bot-edit.ts +3 -5
  20. package/src/channels/adapters/discord-bot-reactions.ts +4 -6
  21. package/src/channels/adapters/discord-bot-slash-commands.ts +3 -1
  22. package/src/channels/adapters/discord-bot.ts +20 -23
  23. package/src/channels/adapters/discord-edit.ts +3 -5
  24. package/src/channels/adapters/discord-reactions.ts +4 -6
  25. package/src/channels/adapters/discord.ts +1 -1
  26. package/src/channels/adapters/github/decoy-reviewer.ts +2 -1
  27. package/src/channels/adapters/github/history.ts +2 -1
  28. package/src/channels/adapters/github/inbound.ts +4 -11
  29. package/src/channels/adapters/github/index.ts +6 -9
  30. package/src/channels/adapters/github/outbound.ts +3 -6
  31. package/src/channels/adapters/github/reactions.ts +3 -2
  32. package/src/channels/adapters/github/reconcile-cooldown-store.ts +4 -6
  33. package/src/channels/adapters/github/reconcile-open-prs.ts +5 -4
  34. package/src/channels/adapters/github/recover-failed-deliveries.ts +2 -5
  35. package/src/channels/adapters/github/review-state.ts +3 -2
  36. package/src/channels/adapters/github/review-thread-resolver.ts +3 -2
  37. package/src/channels/adapters/github/webhook-register.ts +5 -8
  38. package/src/channels/adapters/instagram-channel-resolver.ts +3 -5
  39. package/src/channels/adapters/instagram.ts +1 -1
  40. package/src/channels/adapters/kakaotalk-author-resolver.ts +2 -5
  41. package/src/channels/adapters/kakaotalk-channel-resolver.ts +3 -5
  42. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +2 -1
  43. package/src/channels/adapters/kakaotalk-membership.ts +2 -5
  44. package/src/channels/adapters/kakaotalk-typing.ts +1 -1
  45. package/src/channels/adapters/kakaotalk.ts +1 -1
  46. package/src/channels/adapters/line-channel-resolver.ts +3 -5
  47. package/src/channels/adapters/line.ts +1 -1
  48. package/src/channels/adapters/slack-bot-edit.ts +1 -1
  49. package/src/channels/adapters/slack-bot-reactions.ts +4 -6
  50. package/src/channels/adapters/slack-bot.ts +8 -8
  51. package/src/channels/adapters/slack-edit.ts +3 -5
  52. package/src/channels/adapters/slack-reactions.ts +4 -6
  53. package/src/channels/adapters/slack.ts +1 -1
  54. package/src/channels/adapters/teams-edit.ts +2 -5
  55. package/src/channels/adapters/teams.ts +1 -1
  56. package/src/channels/adapters/telegram-bot-edit.ts +4 -7
  57. package/src/channels/adapters/telegram-bot.ts +1 -1
  58. package/src/channels/adapters/webex-bot.ts +1 -1
  59. package/src/channels/adapters/webex-edit.ts +3 -5
  60. package/src/channels/adapters/webex.ts +1 -1
  61. package/src/channels/github-review-claim.ts +89 -4
  62. package/src/channels/github-token-bridge.ts +2 -1
  63. package/src/channels/manager.ts +478 -64
  64. package/src/channels/membership-cache.ts +2 -5
  65. package/src/channels/persistence.ts +3 -6
  66. package/src/channels/reloadable.ts +23 -6
  67. package/src/channels/router.ts +134 -56
  68. package/src/channels/tunnel-bridge.ts +2 -1
  69. package/src/channels/types.ts +6 -3
  70. package/src/cli/hostd.ts +56 -28
  71. package/src/config/config.ts +10 -0
  72. package/src/config/providers.ts +179 -0
  73. package/src/dependencies/bin-resolver.ts +88 -0
  74. package/src/dependencies/bins.ts +227 -0
  75. package/src/dependencies/index.ts +17 -0
  76. package/src/doctor/checks.ts +2 -0
  77. package/src/doctor/operational-incidents.ts +32 -0
  78. package/src/hostd/credential-rotation-apply.ts +94 -0
  79. package/src/init/models-dev.ts +17 -3
  80. package/src/init/validate-api-key.ts +26 -4
  81. package/src/operations/classify-tool-outcome.ts +151 -0
  82. package/src/operations/incidents.ts +274 -0
  83. package/src/operations/index.ts +3 -0
  84. package/src/operations/remediations.ts +41 -0
  85. package/src/reload/client.ts +8 -2
  86. package/src/reload/docker-exec-client.ts +10 -2
  87. package/src/reload/index.ts +1 -1
  88. package/src/reload/recover.ts +5 -3
  89. package/src/reload/registry.ts +5 -5
  90. package/src/reload/types.ts +9 -1
  91. package/src/run/index.ts +5 -0
  92. package/src/sandbox/dependency-bins.ts +125 -0
  93. package/src/sandbox/errors.ts +32 -0
  94. package/src/sandbox/hidden-paths.ts +4 -1
  95. package/src/sandbox/index.ts +8 -0
  96. package/src/sandbox/policy.ts +1 -1
  97. package/src/sandbox/privileged-runtime.ts +88 -7
  98. package/src/sandbox/runtime-private.ts +4 -0
  99. package/src/sandbox/writable-zones.ts +4 -4
  100. package/src/server/index.ts +7 -5
  101. package/src/shared/protocol.ts +6 -1
  102. package/typeclaw.schema.json +35 -5
  103. package/src/bundled-plugins/agent-browser/shim-install.ts +0 -179
  104. package/src/bundled-plugins/agent-browser/shim.ts +0 -108
  105. /package/src/channels/{adapters/describe-error.ts → describe-error.ts} +0 -0
@@ -81,24 +81,33 @@ export function checkPrivateSurfaceReadGuard(
81
81
  ): SecurityBlock | undefined {
82
82
  const { tool, args, agentDir, hidden, fileOperands } = options
83
83
  if (UNSCANNED_TOOLS.has(tool)) return undefined
84
- const { deniedDirs, deniedFiles } = deniedSurface(agentDir, hidden)
85
- if (deniedDirs.length === 0 && deniedFiles.length === 0) return undefined
86
- const identityScanner = createHardlinkIdentityScanner(agentDir, deniedDirs, deniedFiles, hooks)
87
-
88
- const nonFile = fileOperands?.nonFile === undefined ? undefined : new Set(fileOperands.nonFile)
89
- for (const candidate of collectPathCandidates(args, tool, nonFile)) {
90
- const hit = matchHidden(candidate, agentDir, deniedDirs, deniedFiles, identityScanner)
91
- if (hit !== undefined) {
92
- return {
93
- block: true,
94
- reason: [
95
- `Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: argument \`${candidate}\` resolves to ${hit}, which is not available to LLM tools.`,
96
- 'The bash sandbox masks the same path. Privileged roles cannot bypass canonical agent credential files; use host-side redacted diagnostics such as `typeclaw doctor`, `typeclaw provider list`, or `typeclaw channel list` instead.',
97
- ].join(' '),
84
+ try {
85
+ const { deniedDirs, deniedFiles } = deniedSurface(agentDir, hidden)
86
+ if (deniedDirs.length === 0 && deniedFiles.length === 0) return undefined
87
+ const identityScanner = createHardlinkIdentityScanner(agentDir, deniedDirs, deniedFiles, hooks)
88
+ const realpath = hooks.realpathNative ?? realpathSync.native
89
+
90
+ const nonFile = fileOperands?.nonFile === undefined ? undefined : new Set(fileOperands.nonFile)
91
+ for (const candidate of collectPathCandidates(args, tool, nonFile)) {
92
+ const hit = matchHidden(candidate, agentDir, deniedDirs, deniedFiles, identityScanner, realpath)
93
+ if (hit !== undefined) {
94
+ return {
95
+ block: true,
96
+ reason: [
97
+ `Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: argument \`${candidate}\` resolves to ${hit}, which is not available to LLM tools.`,
98
+ 'The bash sandbox masks the same path. Privileged roles cannot bypass canonical agent credential files; use host-side redacted diagnostics such as `typeclaw doctor`, `typeclaw provider list`, or `typeclaw channel list` instead.',
99
+ ].join(' '),
100
+ }
98
101
  }
99
102
  }
103
+ return undefined
104
+ } catch (error) {
105
+ hooks.onInternalError?.(error)
106
+ return {
107
+ block: true,
108
+ reason: `Guard \`${GUARD_PRIVATE_SURFACE_READ}\` blocked ${tool}: an internal guard error prevented safe path validation.`,
109
+ }
100
110
  }
101
- return undefined
102
111
  }
103
112
 
104
113
  type PrivateSurfaceIdentityOptions = {
@@ -111,6 +120,8 @@ export type PrivateSurfaceIdentityScanHooks = {
111
120
  maxEntries?: number
112
121
  openDirectory?(directory: string): Pick<Dir, 'readSync' | 'closeSync'>
113
122
  lstat?(candidate: string): Stats
123
+ realpathNative?(candidate: string): string
124
+ onInternalError?(error: unknown): void
114
125
  afterEntryLstat?(candidate: string, stats: Stats): void
115
126
  }
116
127
 
@@ -157,6 +168,7 @@ function createHardlinkIdentityScanner(
157
168
  ? openDescriptorAnchoredDirectory
158
169
  : createPathDirectoryOpener(hooks.openDirectory, lstat),
159
170
  lstat,
171
+ realpath: hooks.realpathNative ?? realpathSync.native,
160
172
  afterEntryLstat: hooks.afterEntryLstat,
161
173
  })
162
174
  }
@@ -341,18 +353,19 @@ function matchHidden(
341
353
  deniedDirs: string[],
342
354
  deniedFiles: string[],
343
355
  identityScanner: HardlinkIdentityScanner,
356
+ realpath: (candidate: string) => string,
344
357
  ): string | undefined {
345
358
  const lexicalHit = matchLexicallyDenied(candidate, agentDir, deniedDirs, deniedFiles)
346
359
  if (lexicalHit !== undefined) return lexicalHit
347
360
  const lexical = path.resolve(agentDir, candidate)
348
- const resolved = realpathRealIntendedPath(lexical)
361
+ const resolved = realpathRealIntendedPath(lexical, realpath)
349
362
  const virtualRoot = virtualFilesystemRoot(lexical) ?? virtualFilesystemRoot(resolved)
350
363
  if (virtualRoot !== undefined) return `${virtualRoot}, a virtual or process-backed filesystem`
351
364
  for (const file of deniedFiles) {
352
- if (resolved === realpathRealIntendedPath(file) || hasSameFileIdentity(resolved, file)) return file
365
+ if (resolved === realpathRealIntendedPath(file, realpath) || hasSameFileIdentity(resolved, file)) return file
353
366
  }
354
367
  for (const dir of deniedDirs) {
355
- const realDir = realpathRealIntendedPath(dir)
368
+ const realDir = realpathRealIntendedPath(dir, realpath)
356
369
  // realpathRealIntendedPath joins with the platform separator, so the
357
370
  // under-dir test must use path.sep too — a hardcoded "/" never matches the
358
371
  // "\"-joined paths a win32 test runner produces.
@@ -510,6 +523,7 @@ type HardlinkIdentityScannerOptions = {
510
523
  maxEntries: number
511
524
  openDirectory(directory: string): HardlinkDirectory
512
525
  lstat(candidate: string): Stats
526
+ realpath(candidate: string): string
513
527
  afterEntryLstat?(candidate: string, stats: Stats): void
514
528
  }
515
529
 
@@ -565,9 +579,11 @@ class HardlinkIdentityScanner {
565
579
  private scanVisibleTree(): void {
566
580
  if (this.visibleScanned) return
567
581
  this.visibleScanned = true
568
- const root = realpathRealIntendedPath(this.options.agentDir)
569
- const deniedRoots = this.options.deniedDirs.map(realpathRealIntendedPath)
570
- const deniedFiles = new Set(this.options.deniedFiles.map(realpathRealIntendedPath))
582
+ const root = realpathRealIntendedPath(this.options.agentDir, this.options.realpath)
583
+ const deniedRoots = this.options.deniedDirs.map((dir) => realpathRealIntendedPath(dir, this.options.realpath))
584
+ const deniedFiles = new Set(
585
+ this.options.deniedFiles.map((file) => realpathRealIntendedPath(file, this.options.realpath)),
586
+ )
571
587
  const rootStats = this.readRootStats(root, 'visible')
572
588
  if (rootStats === undefined) return
573
589
  const rootDirectory = this.openVerifiedDirectory(root, rootStats, 'visible')
@@ -619,7 +635,7 @@ class HardlinkIdentityScanner {
619
635
  let rootStats: Stats
620
636
  let root: string
621
637
  try {
622
- root = realpathRealIntendedPath(deniedDir)
638
+ root = realpathRealIntendedPath(deniedDir, this.options.realpath)
623
639
  rootStats = this.options.lstat(root)
624
640
  } catch (error) {
625
641
  if (isNotFoundError(error)) continue
@@ -950,16 +966,15 @@ function hasSameFileIdentity(candidate: string, deniedFile: string): boolean {
950
966
  // symlinked component including a planted symlink), and rejoin the remainder.
951
967
  // This catches `public/leak/x` where `public/leak` is a symlink into a hidden
952
968
  // dir even though `public/leak/x` itself does not exist. Sync (realpathSync)
953
- // keeps the guard synchronous so the security tool.before check array stays
954
- // non-async; the cost is one syscall per existing component, negligible at the
955
- // tool-call boundary. Sync mirror of resolveRealIntendedPath in the guard
956
- // plugin's non-workspace-write policy.
957
- function realpathRealIntendedPath(absolutePath: string): string {
969
+ // keeps the guard synchronous; the cost is one syscall per existing component,
970
+ // negligible at the tool-call boundary. Sync mirror of resolveRealIntendedPath
971
+ // in the guard plugin's non-workspace-write policy.
972
+ function realpathRealIntendedPath(absolutePath: string, realpath: (candidate: string) => string): string {
958
973
  const pending: string[] = []
959
974
  let current = absolutePath
960
975
  while (true) {
961
976
  try {
962
- return path.join(realpathSync.native(current), ...pending.reverse())
977
+ return path.join(realpath(current), ...pending.reverse())
963
978
  } catch (err) {
964
979
  if (!isNotFoundError(err)) throw err
965
980
  }
@@ -2,6 +2,8 @@ import type { DiscordBotClient } from 'agent-messenger/discordbot'
2
2
 
3
3
  import type { EditMessageCallback, EditMessageResult } from '@/channels/types'
4
4
 
5
+ import { describeError } from '../describe-error'
6
+
5
7
  export function createDiscordEditMessageCallback(deps: {
6
8
  client: Pick<DiscordBotClient, 'editMessage'>
7
9
  }): EditMessageCallback {
@@ -17,7 +19,7 @@ export function createDiscordEditMessageCallback(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
  }
@@ -43,7 +45,3 @@ function classifyEditError(err: unknown): NonNullable<(EditMessageResult & { ok:
43
45
  return 'not-found'
44
46
  }
45
47
  }
46
-
47
- function describe(err: unknown): string {
48
- return err instanceof Error ? err.message : String(err)
49
- }
@@ -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
  // The reactable target on Discord: a message is addressed by its channel id
12
14
  // plus the message id. The classifier stamps this because both values are on
13
15
  // the gateway event but `chat`/`externalMessageId` are the only ones that
@@ -99,7 +101,7 @@ export function createDiscordReactionCallback(deps: {
99
101
  try {
100
102
  await deps.client.addReaction(target.channel, target.message, unicode)
101
103
  } catch (err) {
102
- return { ok: false, error: describe(err), code: classifyDiscordError(err) }
104
+ return { ok: false, error: describeError(err), code: classifyDiscordError(err) }
103
105
  }
104
106
  return { ok: true, reactionRef: encodeDiscordRemovalRef({ ...target, emoji: unicode }) }
105
107
  }
@@ -117,7 +119,7 @@ export function createDiscordRemoveReactionCallback(deps: {
117
119
  try {
118
120
  await deps.client.removeReaction(target.channel, target.message, target.emoji)
119
121
  } catch (err) {
120
- return { ok: false, error: describe(err), code: classifyDiscordError(err) }
122
+ return { ok: false, error: describeError(err), code: classifyDiscordError(err) }
121
123
  }
122
124
  return { ok: true }
123
125
  }
@@ -159,7 +161,3 @@ function parseRecord(value: string): Record<string, unknown> | null {
159
161
  ? (parsed as Record<string, unknown>)
160
162
  : null
161
163
  }
162
-
163
- function describe(err: unknown): string {
164
- return err instanceof Error ? err.message : String(err)
165
- }
@@ -2,6 +2,8 @@ import type { DiscordGatewayInteractionEvent } from 'agent-messenger/discordbot'
2
2
 
3
3
  import type { ChannelKey } from '@/channels/types'
4
4
 
5
+ import { describeError } from '../describe-error'
6
+
5
7
  const DISCORD_API_BASE = 'https://discord.com/api/v10'
6
8
 
7
9
  // CHAT_INPUT is the only Discord application-command type that maps to the
@@ -63,7 +65,7 @@ export async function registerCommands(args: RegisterCommandsArgs): Promise<Regi
63
65
  }
64
66
  return { ok: true }
65
67
  } catch (err) {
66
- return { ok: false, error: err instanceof Error ? err.message : String(err) }
68
+ return { ok: false, error: describeError(err) }
67
69
  }
68
70
  }
69
71
 
@@ -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(() => '')