typeclaw 0.45.1 → 0.46.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 (163) hide show
  1. package/README.md +1 -1
  2. package/package.json +3 -2
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +44 -30
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/multimodal/index.ts +1 -1
  7. package/src/agent/multimodal/look-at.ts +78 -44
  8. package/src/agent/multimodal/looker.ts +161 -39
  9. package/src/agent/network/response-body.ts +26 -0
  10. package/src/agent/network/safe-http.ts +207 -0
  11. package/src/agent/plugin-tools.ts +377 -157
  12. package/src/agent/provider-error.ts +52 -1
  13. package/src/agent/restart/index.ts +61 -40
  14. package/src/agent/restart-handoff/index.ts +73 -4
  15. package/src/agent/reviewer-bash-policy.ts +42 -1
  16. package/src/agent/session-origin.ts +2 -0
  17. package/src/agent/subagent-drain.ts +117 -7
  18. package/src/agent/subagents.ts +49 -16
  19. package/src/agent/throttle-circuit.ts +25 -5
  20. package/src/agent/tool-error-remediation.ts +72 -0
  21. package/src/agent/tool-file-safety.ts +1310 -0
  22. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  23. package/src/agent/tools/ddg.ts +16 -2
  24. package/src/agent/tools/post-github-review.ts +199 -0
  25. package/src/agent/tools/spawn-subagent.ts +21 -18
  26. package/src/agent/tools/webfetch/fetch.ts +163 -183
  27. package/src/agent/tools/webfetch/tool.ts +2 -3
  28. package/src/agent/tools/websearch.ts +23 -2
  29. package/src/agent/tools-without-local-file-operands.ts +30 -0
  30. package/src/agent/turn-runner.ts +86 -6
  31. package/src/bundled-plugins/backup/README.md +23 -10
  32. package/src/bundled-plugins/backup/git-auth.ts +6 -4
  33. package/src/bundled-plugins/backup/index.ts +85 -44
  34. package/src/bundled-plugins/backup/runner.ts +85 -1
  35. package/src/bundled-plugins/doc-render/render.ts +93 -12
  36. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  37. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  38. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  39. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +74 -26
  40. package/src/bundled-plugins/github-cli-auth/git-command.ts +224 -36
  41. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +9 -9
  42. package/src/bundled-plugins/github-cli-auth/index.ts +207 -132
  43. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  44. package/src/bundled-plugins/github-cli-auth/token-class.ts +4 -6
  45. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  46. package/src/bundled-plugins/memory/README.md +32 -11
  47. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  48. package/src/bundled-plugins/memory/citations.ts +22 -9
  49. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  50. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  51. package/src/bundled-plugins/memory/index.ts +0 -4
  52. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  53. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  54. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  55. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  56. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  57. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  58. package/src/bundled-plugins/memory/vector/embed-threads.ts +36 -0
  59. package/src/bundled-plugins/memory/vector/embedder.ts +19 -1
  60. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  61. package/src/bundled-plugins/researcher/write-report.ts +8 -5
  62. package/src/bundled-plugins/reviewer/index.ts +2 -2
  63. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  64. package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
  65. package/src/bundled-plugins/scout/scout.ts +8 -0
  66. package/src/bundled-plugins/security/index.ts +4 -4
  67. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  68. package/src/bundled-plugins/security/policies/private-surface-read.ts +787 -36
  69. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  70. package/src/bundled-plugins/security/policies/ssrf.ts +147 -42
  71. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  72. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  73. package/src/channels/adapters/discord-bot.ts +66 -6
  74. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  75. package/src/channels/adapters/discord-id.ts +4 -0
  76. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  77. package/src/channels/adapters/discord.ts +57 -7
  78. package/src/channels/adapters/github/auth-app.ts +41 -12
  79. package/src/channels/adapters/github/inbound.ts +11 -0
  80. package/src/channels/adapters/github/index.ts +71 -65
  81. package/src/channels/adapters/github/reconcile-cooldown-store.ts +178 -0
  82. package/src/channels/adapters/github/reconcile-open-prs.ts +31 -0
  83. package/src/channels/adapters/github/review-submitter.ts +302 -0
  84. package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
  85. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  86. package/src/channels/adapters/kakaotalk-typing.ts +17 -15
  87. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  88. package/src/channels/adapters/slack-bot-edit.ts +85 -20
  89. package/src/channels/adapters/slack-bot.ts +26 -10
  90. package/src/channels/adapters/slack-classify.ts +21 -2
  91. package/src/channels/adapters/slack-format.ts +245 -0
  92. package/src/channels/adapters/slack.ts +59 -7
  93. package/src/channels/adapters/telegram-bot.ts +18 -5
  94. package/src/channels/adapters/webex-bot.ts +8 -3
  95. package/src/channels/adapters/webex.ts +8 -3
  96. package/src/channels/fetch-attachment.ts +43 -0
  97. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  98. package/src/channels/github-token-bridge.ts +12 -6
  99. package/src/channels/manager.ts +9 -0
  100. package/src/channels/router.ts +248 -6
  101. package/src/channels/types.ts +28 -1
  102. package/src/cli/channel.ts +1 -1
  103. package/src/cli/init.ts +1 -1
  104. package/src/cli/model.ts +57 -7
  105. package/src/compose/stop.ts +17 -5
  106. package/src/config/config.ts +6 -6
  107. package/src/config/models-mutation.ts +13 -1
  108. package/src/config/providers.ts +176 -0
  109. package/src/container/docker-app.ts +42 -13
  110. package/src/container/start.ts +62 -10
  111. package/src/cron/bridge.ts +9 -2
  112. package/src/doctor/checks.ts +8 -3
  113. package/src/doctor/commit.ts +2 -1
  114. package/src/doctor/file-ownership.ts +52 -0
  115. package/src/dreams/git.ts +2 -1
  116. package/src/git/bound-gc-config.ts +82 -0
  117. package/src/git/hookless.ts +5 -0
  118. package/src/git/reconcile-ignored.ts +18 -5
  119. package/src/git/system-commit.ts +12 -6
  120. package/src/hostd/spawn.ts +133 -47
  121. package/src/init/dockerfile.ts +99 -5
  122. package/src/init/index.ts +17 -5
  123. package/src/init/models-dev.ts +4 -0
  124. package/src/init/validate-api-key.ts +2 -0
  125. package/src/inspect/replay.ts +21 -9
  126. package/src/inspect/session-list.ts +71 -33
  127. package/src/mcp/tools.ts +17 -3
  128. package/src/network/internal-destinations.ts +267 -0
  129. package/src/permissions/builtins.ts +3 -1
  130. package/src/plugin/context.ts +2 -0
  131. package/src/plugin/index.ts +1 -0
  132. package/src/plugin/manager.ts +4 -0
  133. package/src/plugin/types.ts +22 -0
  134. package/src/run/index.ts +40 -0
  135. package/src/run/llm-fetch-observer.ts +41 -4
  136. package/src/sandbox/build.ts +37 -15
  137. package/src/sandbox/canonical-secrets.ts +18 -0
  138. package/src/sandbox/env-exposure.ts +83 -0
  139. package/src/sandbox/errors.ts +13 -6
  140. package/src/sandbox/hidden-paths.ts +102 -44
  141. package/src/sandbox/index.ts +22 -4
  142. package/src/sandbox/package-install.ts +3 -27
  143. package/src/sandbox/policy.ts +16 -28
  144. package/src/sandbox/privileged-runtime.ts +256 -0
  145. package/src/sandbox/session-tmp.ts +8 -2
  146. package/src/sandbox/writable-zones.ts +204 -140
  147. package/src/secrets/index.ts +8 -0
  148. package/src/secrets/refresh-provider-oauth.ts +128 -0
  149. package/src/server/command-runner.ts +48 -4
  150. package/src/server/index.ts +4 -0
  151. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  152. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  153. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  154. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  155. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  156. package/src/skills/typeclaw-config/SKILL.md +27 -11
  157. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  158. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  159. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  160. package/src/skills/typeclaw-permissions/SKILL.md +36 -19
  161. package/src/skills/typeclaw-plugins/SKILL.md +37 -0
  162. package/src/usage/scan.ts +11 -2
  163. package/typeclaw.schema.json +25 -0
@@ -22,6 +22,7 @@ const SENSITIVE_BASENAMES = new Set([
22
22
  'service-account.json',
23
23
  'gha-creds.json',
24
24
  'token.json',
25
+ 'secrets.json',
25
26
  ])
26
27
 
27
28
  const SENSITIVE_BASENAME_PATTERNS: ReadonlyArray<RegExp> = [
@@ -1,5 +1,16 @@
1
+ import { isIP } from 'node:net'
2
+
3
+ import {
4
+ addressMatchesPolicy,
5
+ extractEmbeddedIpv4Address,
6
+ extractRfc6052Ipv4Addresses,
7
+ getBootInternalDestinationPolicy,
8
+ hostnameMatchesPolicy,
9
+ type InternalDestinationPolicy,
10
+ } from '@/network/internal-destinations'
11
+
1
12
  import type { SecuritySeverity } from '../permissions'
2
- import { ACKNOWLEDGE_GUARDS, type SecurityBlock, isGuardAcknowledged } from '../policy'
13
+ import type { SecurityBlock } from '../policy'
3
14
 
4
15
  export const GUARD_SSRF = 'ssrf'
5
16
  // Classified `medium` (silent-attack axis): bypass lets `curl
@@ -8,14 +19,13 @@ export const GUARD_SSRF = 'ssrf'
8
19
  // Catastrophic on follow-up because the model now has live cloud creds.
9
20
  export const GUARD_SSRF_SEVERITY: SecuritySeverity = 'medium'
10
21
 
11
- const ALWAYS_BLOCKED_HOSTS = new Set([
12
- 'localhost',
13
- 'localhost.localdomain',
14
- 'ip6-localhost',
15
- 'ip6-loopback',
22
+ const ALWAYS_BLOCKED_HOSTS = new Set(['localhost', 'localhost.localdomain', 'ip6-localhost', 'ip6-loopback'])
23
+
24
+ const CLOUD_METADATA_HOSTS = new Set([
16
25
  'metadata.google.internal',
17
26
  'metadata',
18
27
  'metadata.aws.internal',
28
+ 'metadata.azure.internal',
19
29
  'instance-data',
20
30
  'instance-data.ec2.internal',
21
31
  ])
@@ -37,7 +47,7 @@ export type SsrfClassification = {
37
47
  reason?: string
38
48
  }
39
49
 
40
- export function classifyUrl(rawUrl: string): SsrfClassification {
50
+ export function classifyUrl(rawUrl: string, internalDestinationPolicy?: InternalDestinationPolicy): SsrfClassification {
41
51
  let parsed: URL
42
52
  try {
43
53
  parsed = new URL(rawUrl)
@@ -65,47 +75,102 @@ export function classifyUrl(rawUrl: string): SsrfClassification {
65
75
  }
66
76
 
67
77
  const host = parsed.hostname.toLowerCase()
68
- const decoded = decodeBracketedIpv6(host)
78
+ const decoded = decodeBracketedIpv6(host).replace(/\.$/, '')
69
79
 
70
- if (ALWAYS_BLOCKED_HOSTS.has(decoded)) {
80
+ if (isCloudMetadataHostname(decoded)) {
71
81
  return {
82
+ blocked: true,
83
+ category: 'cloud_metadata',
84
+ reason: `cloud metadata hostname "${decoded}" is never allowed`,
85
+ }
86
+ }
87
+
88
+ if (ALWAYS_BLOCKED_HOSTS.has(decoded)) {
89
+ const classification: SsrfClassification = {
72
90
  blocked: true,
73
91
  category: 'reserved_internal_host',
74
92
  reason: `host "${decoded}" resolves to internal/loopback infrastructure`,
75
93
  }
94
+ return internalDestinationPolicy !== undefined &&
95
+ allowsInternalDestination(decoded, undefined, internalDestinationPolicy)
96
+ ? { blocked: false }
97
+ : classification
76
98
  }
77
99
  for (const suffix of ALWAYS_BLOCKED_HOST_SUFFIXES) {
78
100
  if (decoded.endsWith(suffix)) {
79
- return {
101
+ const classification: SsrfClassification = {
80
102
  blocked: true,
81
103
  category: 'reserved_internal_host',
82
104
  reason: `host suffix "${suffix}" is reserved for internal networks`,
83
105
  }
106
+ return internalDestinationPolicy !== undefined &&
107
+ allowsInternalDestination(decoded, undefined, internalDestinationPolicy)
108
+ ? { blocked: false }
109
+ : classification
84
110
  }
85
111
  }
86
112
 
113
+ const addressClassification = classifyIpAddress(decoded)
114
+ if (addressClassification.blocked) {
115
+ return internalDestinationPolicy !== undefined &&
116
+ allowsInternalDestination(decoded, decoded, internalDestinationPolicy)
117
+ ? { blocked: false }
118
+ : addressClassification
119
+ }
120
+
121
+ return { blocked: false }
122
+ }
123
+
124
+ export function classifyIpAddress(address: string): SsrfClassification {
125
+ const decoded = decodeBracketedIpv6(address.toLowerCase().split('%')[0] ?? '')
87
126
  const ipv4 = parseIpv4Loose(decoded)
88
127
  if (ipv4) {
89
128
  const cls = classifyIpv4(ipv4)
90
129
  if (cls) return { blocked: true, category: cls.category, reason: cls.reason }
130
+ return { blocked: false }
91
131
  }
92
-
93
- if (looksLikeIpv6(decoded)) {
94
- const cls = classifyIpv6(decoded)
132
+ const normalizedIpv6 = normalizeIpv6(decoded)
133
+ if (normalizedIpv6 !== undefined) {
134
+ const cls = classifyIpv6(normalizedIpv6)
95
135
  if (cls) return { blocked: true, category: cls.category, reason: cls.reason }
96
136
  }
97
-
98
137
  return { blocked: false }
99
138
  }
100
139
 
101
- export function checkSsrfGuard(options: { tool: string; args: Record<string, unknown> }): SecurityBlock | undefined {
140
+ export function allowsInternalDestination(
141
+ hostname: string,
142
+ address: string | undefined,
143
+ policy: InternalDestinationPolicy,
144
+ ): boolean {
145
+ const normalizedHostname = decodeBracketedIpv6(hostname.toLowerCase()).replace(/\.$/, '')
146
+ if (isCloudMetadataHostname(normalizedHostname)) return false
147
+ if (address !== undefined && isCloudMetadataAddress(address)) return false
148
+ return (
149
+ hostnameMatchesPolicy(normalizedHostname, policy) ||
150
+ (address !== undefined && addressMatchesPolicy(address, policy))
151
+ )
152
+ }
153
+
154
+ function normalizeIpv6(address: string): string | undefined {
155
+ if (isIP(address) !== 6) return undefined
156
+ try {
157
+ return decodeBracketedIpv6(new URL(`http://[${address}]/`).hostname).toLowerCase()
158
+ } catch {
159
+ return undefined
160
+ }
161
+ }
162
+
163
+ export function checkSsrfGuard(options: {
164
+ tool: string
165
+ args: Record<string, unknown>
166
+ internalDestinationPolicy?: InternalDestinationPolicy
167
+ }): SecurityBlock | undefined {
102
168
  const { tool, args } = options
103
169
  if (tool !== 'web_fetch') return undefined
104
170
  const url = args.url
105
171
  if (typeof url !== 'string') return undefined
106
- if (isGuardAcknowledged(args, GUARD_SSRF)) return undefined
107
172
 
108
- const result = classifyUrl(url)
173
+ const result = classifyUrl(url, options.internalDestinationPolicy ?? getBootInternalDestinationPolicy())
109
174
  if (!result.blocked) return undefined
110
175
 
111
176
  return {
@@ -113,7 +178,7 @@ export function checkSsrfGuard(options: { tool: string; args: Record<string, unk
113
178
  reason: [
114
179
  `Guard \`${GUARD_SSRF}\` blocked web_fetch to a non-public destination (${result.category ?? 'unknown'}): ${result.reason ?? 'classified as internal'}.`,
115
180
  'This protects against SSRF, cloud metadata exfiltration, and accidental fetches against internal services.',
116
- `If this is genuinely intentional and you trust the URL, retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_SSRF}: true\` in the web_fetch arguments.`,
181
+ 'Intentional internal destinations must be configured by the operator through the boot-only model HTTP environment policy; model-authored acknowledgements cannot bypass this guard.',
117
182
  ].join(' '),
118
183
  }
119
184
  }
@@ -152,6 +217,8 @@ function classifyIpv4(
152
217
  ip: [number, number, number, number],
153
218
  ): { category: SsrfClassification['category']; reason: string } | undefined {
154
219
  const [a, b] = ip
220
+ if (isCloudMetadataIpv4(ip))
221
+ return { category: 'cloud_metadata', reason: `cloud metadata endpoint (${ip.join('.')})` }
155
222
  if (a === 127) return { category: 'loopback', reason: `IPv4 loopback (${ip.join('.')})` }
156
223
  if (a === 10) return { category: 'private_ipv4', reason: `private RFC1918 10.0.0.0/8 (${ip.join('.')})` }
157
224
  if (a === 172 && b >= 16 && b <= 31)
@@ -159,44 +226,82 @@ function classifyIpv4(
159
226
  if (a === 192 && b === 168)
160
227
  return { category: 'private_ipv4', reason: `private RFC1918 192.168.0.0/16 (${ip.join('.')})` }
161
228
  if (a === 169 && b === 254)
162
- return { category: 'cloud_metadata', reason: `link-local / cloud metadata 169.254.0.0/16 (${ip.join('.')})` }
229
+ return { category: 'link_local', reason: `IPv4 link-local 169.254.0.0/16 (${ip.join('.')})` }
163
230
  if (a === 100 && b >= 64 && b <= 127)
164
231
  return { category: 'shared_cgnat', reason: `CGNAT 100.64.0.0/10 (${ip.join('.')})` }
232
+ if (a === 198 && (b === 18 || b === 19))
233
+ return { category: 'private_ipv4', reason: `benchmarking-only 198.18.0.0/15 (${ip.join('.')})` }
165
234
  if (a === 0) return { category: 'unspecified', reason: `unspecified 0.0.0.0/8 (${ip.join('.')})` }
166
235
  if (a >= 224) return { category: 'private_ipv4', reason: `multicast/reserved (${ip.join('.')})` }
167
236
  return undefined
168
237
  }
169
238
 
170
- function looksLikeIpv6(host: string): boolean {
171
- return host.includes(':') && /^[0-9a-f:]+$/i.test(host)
172
- }
173
-
174
239
  function classifyIpv6(host: string): { category: SsrfClassification['category']; reason: string } | undefined {
175
240
  const lower = host.toLowerCase()
241
+ if (lower === 'fd00:ec2::254' || lower === 'fd20:ce::254') {
242
+ return { category: 'cloud_metadata', reason: `cloud IPv6 metadata endpoint (${lower})` }
243
+ }
244
+ if (lower.startsWith('64:ff9b:1:')) {
245
+ return {
246
+ category: 'cloud_metadata',
247
+ reason: `RFC8215 local-use translation prefix has no safely inferable IPv4 field (${lower})`,
248
+ }
249
+ }
250
+ const internalClassification = classifyInternalIpv6(lower)
251
+ if (internalClassification !== undefined) {
252
+ const translatedMetadata = extractRfc6052Ipv4Addresses(lower).find((candidate) => {
253
+ const ipv4 = parseIpv4Loose(candidate)
254
+ return ipv4 !== undefined && isCloudMetadataIpv4(ipv4)
255
+ })
256
+ if (translatedMetadata !== undefined) {
257
+ return {
258
+ category: 'cloud_metadata',
259
+ reason: `RFC6052 network-specific translation of cloud metadata endpoint (${translatedMetadata})`,
260
+ }
261
+ }
262
+ return internalClassification
263
+ }
264
+ const embeddedIpv4 = extractEmbeddedIpv4Address(lower)
265
+ if (embeddedIpv4 !== undefined) {
266
+ const parsed = parseIpv4Loose(embeddedIpv4)
267
+ const cls = parsed === undefined ? undefined : classifyIpv4(parsed)
268
+ if (cls) return { category: cls.category, reason: `IPv4-embedded IPv6: ${cls.reason}` }
269
+ }
270
+ return undefined
271
+ }
272
+
273
+ function classifyInternalIpv6(lower: string): { category: SsrfClassification['category']; reason: string } | undefined {
176
274
  if (lower === '::1' || lower === '0:0:0:0:0:0:0:1') return { category: 'loopback', reason: 'IPv6 loopback ::1' }
177
275
  if (lower === '::' || lower === '0:0:0:0:0:0:0:0') return { category: 'unspecified', reason: 'IPv6 unspecified ::' }
178
- if (lower.startsWith('fe80:') || lower.startsWith('fe80::'))
276
+ const firstHextet = Number.parseInt(lower.split(':')[0] ?? '', 16)
277
+ if (Number.isFinite(firstHextet) && firstHextet >= 0xfe80 && firstHextet <= 0xfebf)
179
278
  return { category: 'link_local', reason: 'IPv6 link-local fe80::/10' }
279
+ if (Number.isFinite(firstHextet) && firstHextet >= 0xfec0 && firstHextet <= 0xfeff)
280
+ return { category: 'ipv6_internal', reason: 'IPv6 site-local fec0::/10' }
180
281
  if (lower.startsWith('fc') || lower.startsWith('fd'))
181
282
  return { category: 'ipv6_internal', reason: 'IPv6 unique-local fc00::/7' }
182
283
  if (lower.startsWith('ff')) return { category: 'ipv6_internal', reason: 'IPv6 multicast ff00::/8' }
183
- if (lower.startsWith('::ffff:')) {
184
- const tail = lower.slice('::ffff:'.length)
185
- const dotted = parseIpv4Loose(tail)
186
- if (dotted) {
187
- const cls = classifyIpv4(dotted)
188
- if (cls) return { category: cls.category, reason: `IPv4-mapped IPv6: ${cls.reason}` }
189
- }
190
- const hexPair = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
191
- if (hexPair && hexPair[1] && hexPair[2]) {
192
- const hi = parseInt(hexPair[1], 16)
193
- const lo = parseInt(hexPair[2], 16)
194
- if (Number.isFinite(hi) && Number.isFinite(lo)) {
195
- const ip: [number, number, number, number] = [(hi >>> 8) & 0xff, hi & 0xff, (lo >>> 8) & 0xff, lo & 0xff]
196
- const cls = classifyIpv4(ip)
197
- if (cls) return { category: cls.category, reason: `IPv4-mapped IPv6: ${cls.reason}` }
198
- }
199
- }
200
- }
201
284
  return undefined
202
285
  }
286
+
287
+ function isCloudMetadataHostname(hostname: string): boolean {
288
+ return CLOUD_METADATA_HOSTS.has(hostname) || hostname.endsWith('.metadata.google.internal')
289
+ }
290
+
291
+ function isCloudMetadataAddress(address: string): boolean {
292
+ return classifyIpAddress(address).category === 'cloud_metadata'
293
+ }
294
+
295
+ function isCloudMetadataIpv4(ip: [number, number, number, number]): boolean {
296
+ const value = ip.join('.')
297
+ return (
298
+ value === '169.254.169.254' ||
299
+ value === '169.254.170.2' ||
300
+ value === '169.254.170.23' ||
301
+ value === '169.254.0.23' ||
302
+ value === '169.254.0.24' ||
303
+ value === '100.100.100.200' ||
304
+ value === '192.0.0.192' ||
305
+ value === '168.63.129.16'
306
+ )
307
+ }
@@ -1,5 +1,8 @@
1
1
  import type { ChannelKey, ChannelNameResolver, ResolvedChannelNames } from '@/channels/types'
2
2
 
3
+ import { isDiscordSnowflake } from './discord-id'
4
+ import { DiscordResolverCache } from './discord-resolver-cache'
5
+
3
6
  const DISCORD_API_BASE = 'https://discord.com/api/v10'
4
7
  const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
5
8
 
@@ -7,29 +10,34 @@ export type DiscordChannelResolverOptions = {
7
10
  token: string
8
11
  now?: () => number
9
12
  ttlMs?: number
13
+ maxCacheEntries?: number
14
+ fetchImpl?: typeof fetch
10
15
  }
11
16
 
12
- type CacheEntry<T> = { value: T; expiresAt: number }
13
-
14
17
  type DiscordChannel = { id?: string; name?: string }
15
18
  type DiscordGuild = { id?: string; name?: string }
16
19
 
17
20
  export function createDiscordChannelResolver(options: DiscordChannelResolverOptions): ChannelNameResolver {
18
21
  const now = options.now ?? Date.now
19
22
  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS
23
+ const fetchImpl = options.fetchImpl ?? fetch
20
24
 
21
- const channelCache = new Map<string, CacheEntry<string>>()
22
- const guildCache = new Map<string, CacheEntry<string>>()
25
+ const channelCache = new DiscordResolverCache<string>(options.maxCacheEntries)
26
+ const guildCache = new DiscordResolverCache<string>(options.maxCacheEntries)
23
27
 
24
28
  const fetchCached = async <T>(
25
- cache: Map<string, CacheEntry<T>>,
29
+ cache: DiscordResolverCache<T>,
26
30
  key: string,
27
31
  fetcher: () => Promise<T | null>,
28
32
  ): Promise<T | null> => {
29
- const cached = cache.get(key)
30
- if (cached && cached.expiresAt > now()) return cached.value
33
+ const currentTime = now()
34
+ const cached = cache.get(key, currentTime)
35
+ if (cached !== undefined) return cached
31
36
  const value = await fetcher()
32
- if (value !== null) cache.set(key, { value, expiresAt: now() + ttlMs })
37
+ if (value !== null) {
38
+ const fetchedAt = now()
39
+ cache.set(key, value, fetchedAt + ttlMs, fetchedAt)
40
+ }
33
41
  return value
34
42
  }
35
43
 
@@ -37,8 +45,12 @@ export function createDiscordChannelResolver(options: DiscordChannelResolverOpti
37
45
  if (key.workspace === '@dm') return {}
38
46
 
39
47
  const [chatName, workspaceName] = await Promise.all([
40
- fetchCached(channelCache, key.chat, () => fetchChannelName(key.chat, options.token)),
41
- fetchCached(guildCache, key.workspace, () => fetchGuildName(key.workspace, options.token)),
48
+ isDiscordSnowflake(key.chat)
49
+ ? fetchCached(channelCache, key.chat, () => fetchChannelName(key.chat, options.token, fetchImpl))
50
+ : Promise.resolve(null),
51
+ isDiscordSnowflake(key.workspace)
52
+ ? fetchCached(guildCache, key.workspace, () => fetchGuildName(key.workspace, options.token, fetchImpl))
53
+ : Promise.resolve(null),
42
54
  ])
43
55
 
44
56
  const result: ResolvedChannelNames = {}
@@ -48,9 +60,9 @@ export function createDiscordChannelResolver(options: DiscordChannelResolverOpti
48
60
  }
49
61
  }
50
62
 
51
- async function fetchChannelName(channelId: string, token: string): Promise<string | null> {
63
+ async function fetchChannelName(channelId: string, token: string, fetchImpl: typeof fetch): Promise<string | null> {
52
64
  try {
53
- const response = await fetch(`${DISCORD_API_BASE}/channels/${encodeURIComponent(channelId)}`, {
65
+ const response = await fetchImpl(`${DISCORD_API_BASE}/channels/${encodeURIComponent(channelId)}`, {
54
66
  headers: { Authorization: `Bot ${token}` },
55
67
  })
56
68
  if (!response.ok) return null
@@ -62,9 +74,9 @@ async function fetchChannelName(channelId: string, token: string): Promise<strin
62
74
  }
63
75
  }
64
76
 
65
- async function fetchGuildName(guildId: string, token: string): Promise<string | null> {
77
+ async function fetchGuildName(guildId: string, token: string, fetchImpl: typeof fetch): Promise<string | null> {
66
78
  try {
67
- const response = await fetch(`${DISCORD_API_BASE}/guilds/${encodeURIComponent(guildId)}`, {
79
+ const response = await fetchImpl(`${DISCORD_API_BASE}/guilds/${encodeURIComponent(guildId)}`, {
68
80
  headers: { Authorization: `Bot ${token}` },
69
81
  })
70
82
  if (!response.ok) return null
@@ -1,5 +1,8 @@
1
1
  import type { InboundMessage } from '@/channels/types'
2
2
 
3
+ import { isDiscordSnowflake } from './discord-id'
4
+ import { DiscordResolverCache } from './discord-resolver-cache'
5
+
3
6
  const DISCORD_API_BASE = 'https://discord.com/api/v10'
4
7
  const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
5
8
 
@@ -11,7 +14,7 @@ const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000
11
14
  // carries no thread/parent signal.
12
15
  const DISCORD_THREAD_CHANNEL_TYPES: ReadonlySet<number> = new Set([10, 11, 12])
13
16
 
14
- export type DiscordChannelMeta = { type?: number; parent_id?: string }
17
+ export type DiscordChannelMeta = { type?: number; parent_id?: string | null }
15
18
 
16
19
  // The lookup has THREE outcomes, and the failure case must not be conflated
17
20
  // with a confirmed non-thread channel:
@@ -25,6 +28,12 @@ export type DiscordThreadRoomResolverOptions = {
25
28
  fetchImpl?: typeof fetch
26
29
  now?: () => number
27
30
  ttlMs?: number
31
+ maxCacheEntries?: number
32
+ }
33
+
34
+ export type DiscordThreadRoomStatus = { room: InboundMessage['room']; parentChecked: boolean }
35
+ export type DiscordThreadRoomResolver = ((channelId: string) => Promise<InboundMessage['room']>) & {
36
+ resolveStatus(channelId: string): Promise<DiscordThreadRoomStatus>
28
37
  }
29
38
 
30
39
  // Maps a lookup outcome to the room signal. A confirmed thread carries its
@@ -37,37 +46,60 @@ export type DiscordThreadRoomResolverOptions = {
37
46
  export function discordThreadRoom(meta: ChannelMetaLookup): InboundMessage['room'] {
38
47
  if (meta === 'unknown') return { kind: 'thread' }
39
48
  if (meta.type === undefined || !DISCORD_THREAD_CHANNEL_TYPES.has(meta.type)) return undefined
40
- return meta.parent_id !== undefined ? { kind: 'thread', parentChat: meta.parent_id } : { kind: 'thread' }
49
+ return meta.parent_id != null ? { kind: 'thread', parentChat: meta.parent_id } : { kind: 'thread' }
41
50
  }
42
51
 
43
- export function createDiscordThreadRoomResolver(
44
- options: DiscordThreadRoomResolverOptions,
45
- ): (channelId: string) => Promise<InboundMessage['room']> {
52
+ export function createDiscordThreadRoomResolver(options: DiscordThreadRoomResolverOptions): DiscordThreadRoomResolver {
46
53
  const fetchImpl = options.fetchImpl ?? fetch
47
54
  const now = options.now ?? Date.now
48
55
  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS
49
- const cache = new Map<string, { value: DiscordChannelMeta; expiresAt: number }>()
56
+ const cache = new DiscordResolverCache<DiscordChannelMeta>(options.maxCacheEntries)
50
57
 
51
- return async (channelId: string): Promise<InboundMessage['room']> => {
52
- const cached = cache.get(channelId)
53
- if (cached !== undefined && cached.expiresAt > now()) return discordThreadRoom(cached.value)
58
+ const resolve = (async (channelId: string): Promise<InboundMessage['room']> =>
59
+ (await resolve.resolveStatus(channelId)).room) as DiscordThreadRoomResolver
60
+
61
+ resolve.resolveStatus = async (channelId: string): Promise<DiscordThreadRoomStatus> => {
62
+ if (!isDiscordSnowflake(channelId)) return { room: { kind: 'thread' }, parentChecked: false }
63
+ const currentTime = now()
64
+ const cached = cache.get(channelId, currentTime)
65
+ if (cached !== undefined) {
66
+ return { room: discordThreadRoom(cached), parentChecked: true }
67
+ }
54
68
  // Only CONFIRMED metadata is cached. A failed lookup ('unknown') is not
55
69
  // cached, so the next message on this channel retries rather than pinning
56
70
  // the fail-closed state for the whole TTL.
57
71
  const meta = await fetchChannelMeta(channelId)
58
- if (meta !== 'unknown') cache.set(channelId, { value: meta, expiresAt: now() + ttlMs })
59
- return discordThreadRoom(meta)
72
+ const room = discordThreadRoom(meta)
73
+ const parentChecked = meta !== 'unknown' && (room?.kind !== 'thread' || room.parentChat != null)
74
+ if (meta !== 'unknown' && parentChecked) {
75
+ const fetchedAt = now()
76
+ cache.set(channelId, meta, fetchedAt + ttlMs, fetchedAt)
77
+ }
78
+ return { room, parentChecked }
60
79
  }
61
80
 
81
+ return resolve
82
+
62
83
  async function fetchChannelMeta(channelId: string): Promise<ChannelMetaLookup> {
63
84
  try {
64
85
  const response = await fetchImpl(`${DISCORD_API_BASE}/channels/${encodeURIComponent(channelId)}`, {
65
86
  headers: { Authorization: `Bot ${options.token}` },
66
87
  })
67
88
  if (!response.ok) return 'unknown'
68
- return (await response.json()) as DiscordChannelMeta
89
+ const body: unknown = await response.json()
90
+ if (!validChannelMetadata(body)) return 'unknown'
91
+ return body
69
92
  } catch {
70
93
  return 'unknown'
71
94
  }
72
95
  }
73
96
  }
97
+
98
+ function validChannelMetadata(value: unknown): value is DiscordChannelMeta & { type: number } {
99
+ if (typeof value !== 'object' || value === null || !('type' in value)) return false
100
+ if (typeof value.type !== 'number' || !Number.isInteger(value.type) || value.type < 0) return false
101
+ if ('parent_id' in value && value.parent_id != null) {
102
+ if (typeof value.parent_id !== 'string' || !isDiscordSnowflake(value.parent_id)) return false
103
+ }
104
+ return true
105
+ }
@@ -10,6 +10,15 @@ import {
10
10
  type DiscordGatewayStickerItem,
11
11
  } from 'agent-messenger/discordbot'
12
12
 
13
+ import {
14
+ enrichHistoricalProvenance,
15
+ type HistoricalProvenanceResolver,
16
+ } from '@/bundled-plugins/memory/provenance-index'
17
+ import {
18
+ DEFAULT_ATTACHMENT_MAX_BYTES,
19
+ readAttachmentErrorSnippet,
20
+ readAttachmentResponse,
21
+ } from '@/channels/fetch-attachment'
13
22
  import {
14
23
  MEMBERSHIP_ENUMERATION_CAP,
15
24
  type MembershipResolver,
@@ -113,6 +122,7 @@ const consoleLogger: DiscordBotAdapterLogger = {
113
122
  }
114
123
 
115
124
  export type DiscordBotAdapterOptions = {
125
+ agentDir?: string
116
126
  router: ChannelRouter
117
127
  configRef: () => ChannelAdapterConfig
118
128
  token: string
@@ -123,6 +133,7 @@ export type DiscordBotAdapterOptions = {
123
133
  fetchImpl?: typeof fetch
124
134
  createClient?: () => DiscordBotClient
125
135
  createListener?: (client: DiscordBotClient, options: DiscordBotListenerOptions) => DiscordBotListener
136
+ enrichHistoricalProvenance?: typeof enrichHistoricalProvenance
126
137
  }
127
138
 
128
139
  export type DiscordBotAdapter = {
@@ -895,7 +906,7 @@ export function createFetchAttachmentCallback(deps: {
895
906
  }): FetchAttachmentCallback {
896
907
  const { token, logger } = deps
897
908
  const fetchImpl = deps.fetchImpl ?? fetch
898
- return async ({ ref, filename }) => {
909
+ return async ({ ref, filename, maxBytes = DEFAULT_ATTACHMENT_MAX_BYTES }) => {
899
910
  let url: URL
900
911
  try {
901
912
  url = new URL(ref)
@@ -908,13 +919,12 @@ export function createFetchAttachmentCallback(deps: {
908
919
  try {
909
920
  const res = await fetchImpl(url.toString(), { headers: { Authorization: `Bot ${token}` } })
910
921
  if (!res.ok) {
911
- const body = await res.text().catch(() => '')
922
+ const body = await readAttachmentErrorSnippet(res)
912
923
  const message = `discord cdn fetch ${res.status} ${res.statusText}${body ? `: ${body.slice(0, 200)}` : ''}`
913
924
  logger.error(`[discord-bot] fetchAttachment failed for ${url.toString()}: ${message}`)
914
925
  return { ok: false, error: message }
915
926
  }
916
- const arrayBuffer = await res.arrayBuffer()
917
- const buffer = Buffer.from(arrayBuffer)
927
+ const buffer = await readAttachmentResponse(res, maxBytes)
918
928
  const inferredFilename = filename ?? url.pathname.split('/').pop() ?? 'attachment'
919
929
  const contentType = res.headers.get('content-type') ?? undefined
920
930
  logger.info(
@@ -1032,7 +1042,7 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
1032
1042
  let inflightInbounds = 0
1033
1043
  let stopWaiters: Array<() => void> = []
1034
1044
 
1035
- const channelResolver = createDiscordChannelResolver({ token: options.token })
1045
+ const channelResolver = createDiscordChannelResolver({ token: options.token, fetchImpl })
1036
1046
  const threadRoomResolver = createDiscordThreadRoomResolver({ token: options.token, fetchImpl })
1037
1047
 
1038
1048
  // Discord mentions by snowflake id (`<@id>`/`<@!id>`), so no username form.
@@ -1148,7 +1158,16 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
1148
1158
  // stays null), so the engagement gate cannot see "this is a thread" from
1149
1159
  // the payload alone. Resolve the channel's type/parent and stamp the
1150
1160
  // structural `room` signal for guild inbounds; DMs are never thread rooms.
1151
- const room = event.guild_id !== undefined ? await threadRoomResolver(event.channel_id) : undefined
1161
+ let room = event.guild_id !== undefined ? await threadRoomResolver(event.channel_id) : undefined
1162
+ if (room?.parentChat !== undefined && event.guild_id !== undefined) {
1163
+ const parentNames = await channelResolver({
1164
+ adapter: 'discord-bot',
1165
+ workspace: event.guild_id,
1166
+ chat: room.parentChat,
1167
+ thread: null,
1168
+ })
1169
+ if (parentNames.chatName !== undefined) room = { ...room, parentChatName: parentNames.chatName }
1170
+ }
1152
1171
  const basePayload =
1153
1172
  referenceResult.referenceContext === undefined
1154
1173
  ? { ...verdict.payload, text: hintedText }
@@ -1277,6 +1296,47 @@ export function createDiscordBotAdapter(options: DiscordBotAdapterOptions): Disc
1277
1296
  logger.error(`[discord-bot] listener start failed: ${describe(err)}`)
1278
1297
  throw err
1279
1298
  }
1299
+
1300
+ if (options.agentDir !== undefined) {
1301
+ const runEnrichment = options.enrichHistoricalProvenance ?? enrichHistoricalProvenance
1302
+ const resolveHistorical: HistoricalProvenanceResolver = async (where) => {
1303
+ const key = {
1304
+ adapter: 'discord-bot' as const,
1305
+ workspace: where.workspace,
1306
+ chat: where.chat,
1307
+ thread: where.thread ?? null,
1308
+ }
1309
+ const [names, roomStatus] = await Promise.all([
1310
+ channelResolver(key),
1311
+ threadRoomResolver.resolveStatus(where.chat),
1312
+ ])
1313
+ const room = roomStatus.room
1314
+ let parentChatName = room?.parentChatName
1315
+ if (parentChatName === undefined && room?.parentChat !== undefined) {
1316
+ const parentNames = await channelResolver({ ...key, chat: room.parentChat })
1317
+ parentChatName = parentNames.chatName
1318
+ }
1319
+ return {
1320
+ where: {
1321
+ ...where,
1322
+ ...names,
1323
+ ...(room?.parentChat !== undefined ? { parentChat: room.parentChat } : {}),
1324
+ ...(parentChatName !== undefined ? { parentChatName } : {}),
1325
+ },
1326
+ parentChecked: roomStatus.parentChecked,
1327
+ }
1328
+ }
1329
+ void runEnrichment(options.agentDir, resolveHistorical, { adapter: 'discord-bot' }).then(
1330
+ (result) => {
1331
+ logger.info(
1332
+ `[discord-bot] historical provenance enrichment scanned=${result.scanned} attempted=${result.attempted} resolved=${result.resolved} failed=${result.failed} timed_out=${result.timedOut} changed=${String(result.changed)}`,
1333
+ )
1334
+ },
1335
+ (error: unknown) => {
1336
+ logger.warn(`[discord-bot] historical provenance enrichment failed: ${describe(error)}`)
1337
+ },
1338
+ )
1339
+ }
1280
1340
  },
1281
1341
 
1282
1342
  async stop(): Promise<void> {