typeclaw 0.45.0 → 0.46.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 (147) 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 +67 -25
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/loop-guard.ts +208 -10
  7. package/src/agent/multimodal/index.ts +1 -1
  8. package/src/agent/multimodal/look-at.ts +78 -44
  9. package/src/agent/multimodal/looker.ts +151 -39
  10. package/src/agent/network/response-body.ts +26 -0
  11. package/src/agent/network/safe-http.ts +198 -0
  12. package/src/agent/plugin-tools.ts +438 -162
  13. package/src/agent/provider-error.ts +62 -4
  14. package/src/agent/restart/index.ts +61 -40
  15. package/src/agent/restart-handoff/index.ts +73 -4
  16. package/src/agent/retry-same-ref.ts +66 -0
  17. package/src/agent/reviewer-bash-policy.ts +42 -1
  18. package/src/agent/session-origin.ts +2 -0
  19. package/src/agent/subagent-drain.ts +117 -7
  20. package/src/agent/subagents.ts +77 -18
  21. package/src/agent/throttle-circuit.ts +25 -5
  22. package/src/agent/tool-error-remediation.ts +72 -0
  23. package/src/agent/tool-file-safety.ts +1050 -0
  24. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  25. package/src/agent/tools/channel-reply.ts +15 -1
  26. package/src/agent/tools/channel-send.ts +17 -1
  27. package/src/agent/tools/ddg.ts +16 -2
  28. package/src/agent/tools/post-github-review.ts +199 -0
  29. package/src/agent/tools/spawn-subagent.ts +21 -18
  30. package/src/agent/tools/webfetch/fetch.ts +143 -183
  31. package/src/agent/tools/webfetch/tool.ts +2 -3
  32. package/src/agent/tools/websearch.ts +23 -2
  33. package/src/agent/tools-without-local-file-operands.ts +27 -0
  34. package/src/agent/turn-runner.ts +109 -15
  35. package/src/bundled-plugins/backup/index.ts +2 -1
  36. package/src/bundled-plugins/backup/runner.ts +2 -1
  37. package/src/bundled-plugins/doc-render/render.ts +93 -12
  38. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  39. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  40. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  41. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  42. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  43. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  44. package/src/bundled-plugins/memory/README.md +23 -11
  45. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  46. package/src/bundled-plugins/memory/citations.ts +22 -9
  47. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  48. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  49. package/src/bundled-plugins/memory/index.ts +0 -4
  50. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  51. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  52. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  53. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  54. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  55. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  56. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  57. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  58. package/src/bundled-plugins/reviewer/index.ts +2 -2
  59. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  60. package/src/bundled-plugins/reviewer/skills/code-review.ts +24 -9
  61. package/src/bundled-plugins/scout/scout.ts +8 -0
  62. package/src/bundled-plugins/security/index.ts +4 -4
  63. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  64. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  65. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  66. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  67. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  68. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  69. package/src/channels/adapters/discord-bot.ts +91 -10
  70. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  71. package/src/channels/adapters/discord-id.ts +4 -0
  72. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  73. package/src/channels/adapters/discord.ts +57 -7
  74. package/src/channels/adapters/github/auth-app.ts +41 -12
  75. package/src/channels/adapters/github/index.ts +23 -11
  76. package/src/channels/adapters/github/review-submitter.ts +302 -0
  77. package/src/channels/adapters/kakaotalk-channel-resolver.ts +12 -1
  78. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  79. package/src/channels/adapters/kakaotalk-typing.ts +127 -0
  80. package/src/channels/adapters/kakaotalk.ts +19 -0
  81. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  82. package/src/channels/adapters/slack-bot.ts +19 -8
  83. package/src/channels/adapters/slack-classify.ts +21 -2
  84. package/src/channels/adapters/slack.ts +59 -7
  85. package/src/channels/adapters/telegram-bot.ts +18 -5
  86. package/src/channels/adapters/webex-bot.ts +8 -3
  87. package/src/channels/adapters/webex.ts +8 -3
  88. package/src/channels/fetch-attachment.ts +43 -0
  89. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  90. package/src/channels/github-token-bridge.ts +10 -3
  91. package/src/channels/manager.ts +9 -0
  92. package/src/channels/router.ts +568 -12
  93. package/src/channels/types.ts +28 -1
  94. package/src/cli/channel.ts +1 -1
  95. package/src/cli/init.ts +1 -1
  96. package/src/cli/model.ts +57 -7
  97. package/src/compose/stop.ts +17 -5
  98. package/src/config/config.ts +6 -6
  99. package/src/config/models-mutation.ts +13 -1
  100. package/src/config/providers.ts +176 -0
  101. package/src/container/start.ts +49 -10
  102. package/src/doctor/checks.ts +3 -1
  103. package/src/doctor/commit.ts +2 -1
  104. package/src/doctor/file-ownership.ts +52 -0
  105. package/src/dreams/git.ts +2 -1
  106. package/src/git/hookless.ts +5 -0
  107. package/src/git/reconcile-ignored.ts +18 -5
  108. package/src/git/secret-history.ts +371 -0
  109. package/src/git/system-commit.ts +12 -6
  110. package/src/init/dockerfile.ts +86 -5
  111. package/src/init/index.ts +17 -5
  112. package/src/init/models-dev.ts +4 -0
  113. package/src/init/validate-api-key.ts +2 -0
  114. package/src/mcp/tools.ts +16 -3
  115. package/src/permissions/builtins.ts +3 -1
  116. package/src/plugin/context.ts +2 -0
  117. package/src/plugin/index.ts +1 -0
  118. package/src/plugin/manager.ts +4 -0
  119. package/src/plugin/types.ts +21 -0
  120. package/src/run/index.ts +40 -0
  121. package/src/run/llm-fetch-observer.ts +188 -13
  122. package/src/sandbox/build.ts +37 -15
  123. package/src/sandbox/canonical-secrets.ts +18 -0
  124. package/src/sandbox/env-exposure.ts +80 -0
  125. package/src/sandbox/errors.ts +13 -6
  126. package/src/sandbox/hidden-paths.ts +102 -44
  127. package/src/sandbox/index.ts +22 -4
  128. package/src/sandbox/package-install.ts +3 -27
  129. package/src/sandbox/policy.ts +11 -25
  130. package/src/sandbox/privileged-runtime.ts +255 -0
  131. package/src/sandbox/session-tmp.ts +8 -2
  132. package/src/sandbox/writable-zones.ts +204 -140
  133. package/src/secrets/index.ts +8 -0
  134. package/src/secrets/refresh-provider-oauth.ts +128 -0
  135. package/src/server/command-runner.ts +48 -4
  136. package/src/server/index.ts +4 -0
  137. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  138. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  139. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  140. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  141. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  142. package/src/skills/typeclaw-config/SKILL.md +5 -5
  143. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  144. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  145. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  146. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  147. package/typeclaw.schema.json +20 -0
@@ -0,0 +1,717 @@
1
+ import type { AdapterId } from '@/channels/schema'
2
+
3
+ import { formatCitation, splitCitationRefsBySection } from './citations'
4
+ import { loadAllShards, type TopicShard } from './load-shards'
5
+ import { isSafeProvenanceCoordinate, sanitizeProvenanceName } from './provenance-sanitize'
6
+ import type { FragmentEvent, FragmentProvenance } from './stream-events'
7
+ import { readAllStreamDays, type StreamDay } from './stream-io'
8
+
9
+ const MAX_COORDINATES = 20_000
10
+ const MAX_ALIASES = 12
11
+ const DEFAULT_BUILD_TIMEOUT_MS = 250
12
+
13
+ export type ProvenanceChild = {
14
+ citation: string
15
+ resolved: boolean
16
+ dreamed?: boolean
17
+ who?: string
18
+ when?: string
19
+ where?: FragmentProvenance
20
+ }
21
+
22
+ export type MemoryScope = {
23
+ workspace?: string
24
+ chat?: string
25
+ thread?: string
26
+ }
27
+
28
+ type AliasSource = 'historical' | 'resolver'
29
+ type AliasSources = { workspaceName: AliasSource; chatName: AliasSource; parentChatName: AliasSource }
30
+ const HISTORICAL_ALIAS_SOURCES: AliasSources = {
31
+ workspaceName: 'historical',
32
+ chatName: 'historical',
33
+ parentChatName: 'historical',
34
+ }
35
+ type AliasRecord = { names: string[]; parentChat?: string; parentChatNames: string[]; parentChecked?: boolean }
36
+ type RegistryEntry = { kind: 'workspace' | 'chat'; key: string }
37
+ type ProvenanceRegistry = {
38
+ workspaces: Record<string, string[]>
39
+ chats: Record<string, AliasRecord>
40
+ entryCount: number
41
+ recency: Map<string, RegistryEntry>
42
+ resolverAliases: Map<string, string[]>
43
+ }
44
+ type RegistryRecency = { recencyKey: string; entry: RegistryEntry }
45
+ type NewestFirstLearningBatch = {
46
+ protectedEntries: Set<string>
47
+ recencyGroups: RegistryRecency[][]
48
+ aliases: Map<string, { values: string[]; original: string[]; seen: Set<string>; observed: string[] }>
49
+ }
50
+
51
+ export type ProvenanceIndexOptions = {
52
+ timeoutMs?: number
53
+ now?: () => number
54
+ }
55
+
56
+ export type HistoricalProvenanceResolution = { where: FragmentProvenance; parentChecked: boolean }
57
+ export type HistoricalProvenanceResolver = (where: FragmentProvenance) => Promise<HistoricalProvenanceResolution>
58
+
59
+ export type HistoricalProvenanceEnrichmentResult = {
60
+ scanned: number
61
+ attempted: number
62
+ resolved: number
63
+ failed: number
64
+ timedOut: number
65
+ changed: boolean
66
+ }
67
+
68
+ export type HistoricalProvenanceEnrichmentOptions = {
69
+ adapter: Extract<AdapterId, 'discord' | 'discord-bot'>
70
+ maxOrigins?: number
71
+ timeoutMs?: number
72
+ perOriginTimeoutMs?: number
73
+ }
74
+
75
+ const runtimeRegistries = new Map<string, ProvenanceRegistry>()
76
+
77
+ export class ProvenanceIndex {
78
+ readonly #childrenByTopic: Map<string, ProvenanceChild[]>
79
+ readonly #undreamed: ProvenanceChild[]
80
+ readonly #undreamedByCitation: Map<string, ProvenanceChild>
81
+ readonly #registry: ProvenanceRegistry
82
+ readonly #activeCitations: Set<string>
83
+ readonly #supersededCitations: Set<string>
84
+
85
+ constructor(
86
+ childrenByTopic: Map<string, ProvenanceChild[]>,
87
+ undreamed: ProvenanceChild[],
88
+ registry: ProvenanceRegistry,
89
+ activeCitations: Set<string>,
90
+ supersededCitations: Set<string>,
91
+ ) {
92
+ this.#childrenByTopic = childrenByTopic
93
+ this.#undreamed = undreamed
94
+ this.#undreamedByCitation = new Map(undreamed.map((child) => [child.citation, child]))
95
+ this.#registry = registry
96
+ this.#activeCitations = activeCitations
97
+ this.#supersededCitations = supersededCitations
98
+ }
99
+
100
+ childrenForTopic(slug: string, scope: MemoryScope = {}): ProvenanceChild[] {
101
+ return (this.#childrenByTopic.get(slug) ?? []).filter((child) => childMatchesScope(child, scope, this.#registry))
102
+ }
103
+
104
+ undreamedChildren(scope: MemoryScope = {}): ProvenanceChild[] {
105
+ return this.#undreamed.filter((child) => childMatchesScope(child, scope, this.#registry))
106
+ }
107
+
108
+ topicEligible(slug: string, scope: MemoryScope): boolean {
109
+ if (!hasScope(scope)) return true
110
+ return this.childrenForTopic(slug, scope).some((child) => child.resolved)
111
+ }
112
+
113
+ lexicalTextForTopic(slug: string, scope: MemoryScope = {}): string {
114
+ return this.childrenForTopic(slug, scope)
115
+ .flatMap((child) => lexicalParts(child, this.#registry))
116
+ .join('\n')
117
+ }
118
+
119
+ lexicalTextForUndreamed(citation: string, scope: MemoryScope = {}): string {
120
+ const child = this.undreamedChild(citation, scope)
121
+ return child === undefined ? '' : lexicalParts(child, this.#registry).join('\n')
122
+ }
123
+
124
+ undreamedChild(citation: string, scope: MemoryScope = {}): ProvenanceChild | undefined {
125
+ const child = this.#undreamedByCitation.get(citation)
126
+ return child !== undefined && childMatchesScope(child, scope, this.#registry) ? child : undefined
127
+ }
128
+
129
+ isActivelyCited(citation: string): boolean {
130
+ return this.#activeCitations.has(citation)
131
+ }
132
+
133
+ isSuperseded(citation: string): boolean {
134
+ return this.#supersededCitations.has(citation) && !this.#activeCitations.has(citation)
135
+ }
136
+ }
137
+
138
+ export async function buildProvenanceIndex(
139
+ agentDir: string,
140
+ options: ProvenanceIndexOptions = {},
141
+ ): Promise<ProvenanceIndex> {
142
+ const [shards, days] = await Promise.all([loadAllShards(agentDir), readAllStreamDays(agentDir)])
143
+ return await buildProvenanceIndexFrom(agentDir, shards, days, options)
144
+ }
145
+
146
+ export async function buildProvenanceIndexFrom(
147
+ agentDir: string,
148
+ shards: TopicShard[],
149
+ days: StreamDay[],
150
+ options: ProvenanceIndexOptions = {},
151
+ ): Promise<ProvenanceIndex> {
152
+ const now = options.now ?? Date.now
153
+ const deadline = now() + (options.timeoutMs ?? DEFAULT_BUILD_TIMEOUT_MS)
154
+ const fragments = new Map<string, { event: FragmentEvent; date: string; dreamed: boolean }>()
155
+ const coordinates: FragmentProvenance[] = []
156
+
157
+ for (const day of days) {
158
+ for (const event of day.events) {
159
+ if (event.type !== 'fragment') continue
160
+ const citation = formatCitation(day.date, event.id)
161
+ fragments.set(citation, { event, date: day.date, dreamed: day.dreamedIds.has(event.id) })
162
+ }
163
+ }
164
+
165
+ for (let dayIndex = days.length - 1; dayIndex >= 0 && coordinates.length < MAX_COORDINATES; dayIndex--) {
166
+ const events = days[dayIndex]!.events
167
+ for (let eventIndex = events.length - 1; eventIndex >= 0 && coordinates.length < MAX_COORDINATES; eventIndex--) {
168
+ const event = events[eventIndex]!
169
+ if (event.type === 'fragment' && event.where !== undefined) coordinates.push(event.where)
170
+ }
171
+ }
172
+
173
+ const registry = registryFor(agentDir)
174
+ const learningBatch = createNewestFirstLearningBatch()
175
+ for (let index = 0; index < coordinates.length; index++) {
176
+ if (now() > deadline) break
177
+ learnWhere(registry, coordinates[index]!, learningBatch)
178
+ }
179
+ finalizeNewestFirstLearningBatch(registry, learningBatch)
180
+
181
+ const childrenByTopic = new Map<string, ProvenanceChild[]>()
182
+ const activelyCited = new Set<string>()
183
+ const supersededCitations = new Set<string>()
184
+ for (const shard of shards) {
185
+ const { active, superseded } = splitCitationRefsBySection(shard.body)
186
+ for (const citation of superseded) supersededCitations.add(formatCitation(citation.date, citation.fragmentId))
187
+ const children = active
188
+ .map((citation): ProvenanceChild => {
189
+ const canonical = formatCitation(citation.date, citation.fragmentId)
190
+ activelyCited.add(canonical)
191
+ const source = fragments.get(canonical)
192
+ if (source === undefined) return { citation: canonical, resolved: false }
193
+ return childFromFragment(canonical, source.event, source.dreamed, registry)
194
+ })
195
+ .sort(compareChildren)
196
+ childrenByTopic.set(shard.slug, children)
197
+ }
198
+
199
+ const undreamed = [...fragments]
200
+ .filter(([, source]) => !source.dreamed)
201
+ .map(([citation, source]) => childFromFragment(citation, source.event, false, registry))
202
+ .sort(compareChildren)
203
+
204
+ return new ProvenanceIndex(childrenByTopic, undreamed, registry, activelyCited, supersededCitations)
205
+ }
206
+
207
+ export async function enrichHistoricalProvenance(
208
+ agentDir: string,
209
+ resolve: HistoricalProvenanceResolver,
210
+ options: HistoricalProvenanceEnrichmentOptions,
211
+ ): Promise<HistoricalProvenanceEnrichmentResult> {
212
+ const maxOrigins = options.maxOrigins ?? 100
213
+ const deadline = Date.now() + (options.timeoutMs ?? 10_000)
214
+ const perOriginTimeoutMs = options.perOriginTimeoutMs ?? 1_500
215
+ const days = await readAllStreamDays(agentDir)
216
+ const registry = registryFor(agentDir)
217
+ const candidates = new Map<string, FragmentProvenance>()
218
+
219
+ for (let dayIndex = days.length - 1; dayIndex >= 0; dayIndex--) {
220
+ const events = days[dayIndex]!.events
221
+ for (let eventIndex = events.length - 1; eventIndex >= 0; eventIndex--) {
222
+ const event = events[eventIndex]!
223
+ if (event.type !== 'fragment' || event.where?.adapter !== options.adapter) continue
224
+ const where = event.where
225
+ if (where.workspace === '@dm') continue
226
+ if (!needsResolverEnrichment(where, registry)) continue
227
+ if (candidates.size >= maxOrigins) break
228
+ candidates.set(chatKey(where), where)
229
+ }
230
+ if (candidates.size >= maxOrigins) break
231
+ }
232
+
233
+ let attempted = 0
234
+ let resolved = 0
235
+ let failed = 0
236
+ let timedOut = 0
237
+ const resolutions: { original: FragmentProvenance; resolution: HistoricalProvenanceResolution }[] = []
238
+ for (const where of candidates.values()) {
239
+ const remainingMs = deadline - Date.now()
240
+ if (remainingMs <= 0) {
241
+ timedOut += 1
242
+ break
243
+ }
244
+ attempted += 1
245
+ const outcome = await settleWithin(resolve(where), Math.min(perOriginTimeoutMs, remainingMs))
246
+ if (outcome.kind === 'timeout') {
247
+ timedOut += 1
248
+ continue
249
+ }
250
+ if (outcome.kind === 'error' || !sameCoordinates(where, outcome.value.where)) {
251
+ failed += 1
252
+ continue
253
+ }
254
+ const resolution = sanitizeResolution(outcome.value)
255
+ if (!resolutionAddsData(where, resolution, registry)) {
256
+ failed += 1
257
+ continue
258
+ }
259
+ resolutions.push({ original: where, resolution })
260
+ resolved += 1
261
+ }
262
+
263
+ const before = JSON.stringify(registry)
264
+ for (const { original, resolution } of resolutions) applyResolution(registry, original, resolution)
265
+ const changed = JSON.stringify(registry) !== before
266
+ return { scanned: candidates.size, attempted, resolved, failed, timedOut, changed }
267
+ }
268
+
269
+ function childFromFragment(
270
+ citation: string,
271
+ event: FragmentEvent,
272
+ dreamed: boolean,
273
+ sidecar: ProvenanceRegistry,
274
+ ): ProvenanceChild {
275
+ const child: ProvenanceChild = { citation, resolved: true, ...(dreamed ? { dreamed: true } : {}), when: event.ts }
276
+ const who = sanitizeProvenanceName(event.who)
277
+ if (who !== undefined) child.who = who
278
+ if (event.where !== undefined) child.where = enrichWhere(event.where, sidecar)
279
+ return child
280
+ }
281
+
282
+ function compareChildren(a: ProvenanceChild, b: ProvenanceChild): number {
283
+ return a.citation.localeCompare(b.citation)
284
+ }
285
+
286
+ function hasScope(scope: MemoryScope): boolean {
287
+ return scope.workspace !== undefined || scope.chat !== undefined || scope.thread !== undefined
288
+ }
289
+
290
+ function childMatchesScope(child: ProvenanceChild, scope: MemoryScope, sidecar: ProvenanceRegistry): boolean {
291
+ if (!hasScope(scope)) return true
292
+ if (!child.resolved || child.where === undefined) return false
293
+ const where = child.where
294
+ if (scope.workspace !== undefined && !matches(scope.workspace, workspaceValues(where, sidecar))) return false
295
+ if (scope.chat !== undefined && !matches(scope.chat, chatValues(where, sidecar))) return false
296
+ if (scope.thread !== undefined && !matches(scope.thread, threadValues(where, sidecar))) return false
297
+ return true
298
+ }
299
+
300
+ function matches(needle: string, values: string[]): boolean {
301
+ const normalized = normalize(needle)
302
+ return values.some((value) => normalize(value) === normalized)
303
+ }
304
+
305
+ function normalize(value: string): string {
306
+ return value.replace(/^#/, '').toLocaleLowerCase()
307
+ }
308
+
309
+ function workspaceValues(where: FragmentProvenance, sidecar: ProvenanceRegistry): string[] {
310
+ return [
311
+ where.workspace,
312
+ ...(where.workspaceName === undefined ? [] : [where.workspaceName]),
313
+ ...workspaceAliases(where, sidecar),
314
+ ]
315
+ }
316
+
317
+ function chatValues(where: FragmentProvenance, sidecar: ProvenanceRegistry): string[] {
318
+ const record = sidecar.chats[chatKey(where)]
319
+ return [
320
+ where.chat,
321
+ ...(where.chatName === undefined ? [] : [where.chatName]),
322
+ ...(where.parentChat === undefined ? [] : [where.parentChat]),
323
+ ...(where.parentChatName === undefined ? [] : [where.parentChatName]),
324
+ ...(record?.names ?? []),
325
+ ...(record?.parentChatNames ?? []),
326
+ ]
327
+ }
328
+
329
+ function threadValues(where: FragmentProvenance, sidecar: ProvenanceRegistry): string[] {
330
+ const isThreadRoom = where.parentChat !== undefined || sidecar.chats[chatKey(where)]?.parentChat !== undefined
331
+ return [
332
+ ...(where.thread === null || where.thread === undefined ? [] : [where.thread]),
333
+ ...(isThreadRoom ? [where.chat] : []),
334
+ ]
335
+ }
336
+
337
+ function lexicalParts(child: ProvenanceChild, sidecar: ProvenanceRegistry): string[] {
338
+ if (!child.resolved) return [child.citation, 'unresolved citation']
339
+ const where = child.where
340
+ return [
341
+ child.citation,
342
+ ...(child.who === undefined ? [] : [child.who]),
343
+ ...(child.when === undefined ? [] : [child.when]),
344
+ ...(where === undefined
345
+ ? []
346
+ : [...workspaceValues(where, sidecar), ...chatValues(where, sidecar), ...threadValues(where, sidecar)]),
347
+ ]
348
+ }
349
+
350
+ function enrichWhere(where: FragmentProvenance, sidecar: ProvenanceRegistry): FragmentProvenance {
351
+ const safeWhere = safeProvenanceNames(where)
352
+ const workspaceNames = workspaceAliases(safeWhere, sidecar)
353
+ const chat = sidecar.chats[chatKey(safeWhere)]
354
+ return {
355
+ ...safeWhere,
356
+ ...(safeWhere.workspaceName === undefined && workspaceNames[0] !== undefined
357
+ ? { workspaceName: workspaceNames[0] }
358
+ : {}),
359
+ ...(safeWhere.chatName === undefined && chat?.names[0] !== undefined ? { chatName: chat.names[0] } : {}),
360
+ ...(safeWhere.parentChat === undefined && chat?.parentChat !== undefined ? { parentChat: chat.parentChat } : {}),
361
+ ...(safeWhere.parentChatName === undefined && chat?.parentChatNames[0] !== undefined
362
+ ? { parentChatName: chat.parentChatNames[0] }
363
+ : {}),
364
+ }
365
+ }
366
+
367
+ function safeProvenanceNames(where: FragmentProvenance): FragmentProvenance {
368
+ const workspaceName = sanitizeProvenanceName(where.workspaceName)
369
+ const chatName = sanitizeProvenanceName(where.chatName)
370
+ const parentChatName = sanitizeProvenanceName(where.parentChatName)
371
+ return {
372
+ adapter: where.adapter,
373
+ workspace: where.workspace,
374
+ chat: where.chat,
375
+ thread: where.thread,
376
+ ...(workspaceName === undefined ? {} : { workspaceName }),
377
+ ...(chatName === undefined ? {} : { chatName }),
378
+ ...(where.parentChat === undefined ? {} : { parentChat: where.parentChat }),
379
+ ...(parentChatName === undefined ? {} : { parentChatName }),
380
+ }
381
+ }
382
+
383
+ function learnWhere(
384
+ sidecar: ProvenanceRegistry,
385
+ where: FragmentProvenance,
386
+ batch?: NewestFirstLearningBatch,
387
+ aliasSources: AliasSources = HISTORICAL_ALIAS_SOURCES,
388
+ ): boolean {
389
+ if (![where.adapter, where.workspace, where.chat].every(isSafeProvenanceCoordinate)) return false
390
+ const workspaceKey = `${where.adapter}\u0000${where.workspace}`
391
+ const chatCoordinateKey = chatKey(where)
392
+ const workspaceRecencyKey = registryRecencyKey('workspace', workspaceKey)
393
+ const chatRecencyKey = registryRecencyKey('chat', chatCoordinateKey)
394
+ const workspaceName = sanitizeProvenanceName(where.workspaceName)
395
+ const protectedEntries = batch?.protectedEntries ?? new Set<string>()
396
+ const recencyGroup: RegistryRecency[] = []
397
+ if (sidecar.workspaces[workspaceKey] !== undefined) {
398
+ touchLearnedRegistryEntry(
399
+ sidecar,
400
+ workspaceRecencyKey,
401
+ { kind: 'workspace', key: workspaceKey },
402
+ protectedEntries,
403
+ recencyGroup,
404
+ batch !== undefined,
405
+ )
406
+ }
407
+ if (sidecar.chats[chatCoordinateKey] !== undefined) {
408
+ touchLearnedRegistryEntry(
409
+ sidecar,
410
+ chatRecencyKey,
411
+ { kind: 'chat', key: chatCoordinateKey },
412
+ protectedEntries,
413
+ recencyGroup,
414
+ batch !== undefined,
415
+ )
416
+ }
417
+ const newCoordinates =
418
+ Number(workspaceName !== undefined && sidecar.workspaces[workspaceKey] === undefined) +
419
+ Number(sidecar.chats[chatCoordinateKey] === undefined)
420
+ if (!makeRegistryRoom(sidecar, newCoordinates, protectedEntries)) return false
421
+ if (workspaceName !== undefined) {
422
+ if (sidecar.workspaces[workspaceKey] === undefined) {
423
+ sidecar.entryCount += 1
424
+ touchLearnedRegistryEntry(
425
+ sidecar,
426
+ workspaceRecencyKey,
427
+ { kind: 'workspace', key: workspaceKey },
428
+ protectedEntries,
429
+ recencyGroup,
430
+ batch !== undefined,
431
+ )
432
+ }
433
+ addAlias(sidecar, sidecar.workspaces, workspaceKey, workspaceName, batch, aliasSources.workspaceName)
434
+ }
435
+ const record = sidecar.chats[chatCoordinateKey] ?? { names: [], parentChatNames: [] }
436
+ if (sidecar.chats[chatCoordinateKey] === undefined) {
437
+ sidecar.entryCount += 1
438
+ touchLearnedRegistryEntry(
439
+ sidecar,
440
+ chatRecencyKey,
441
+ { kind: 'chat', key: chatCoordinateKey },
442
+ protectedEntries,
443
+ recencyGroup,
444
+ batch !== undefined,
445
+ )
446
+ }
447
+ const chatName = sanitizeProvenanceName(where.chatName)
448
+ const parentChatName = sanitizeProvenanceName(where.parentChatName)
449
+ if (chatName !== undefined)
450
+ observeAlias(sidecar, record.names, chatName, batch, `chat\u0000${chatCoordinateKey}`, aliasSources.chatName)
451
+ if (where.parentChat !== undefined && isSafeProvenanceCoordinate(where.parentChat)) {
452
+ record.parentChat = where.parentChat
453
+ record.parentChecked = true
454
+ }
455
+ if (parentChatName !== undefined)
456
+ observeAlias(
457
+ sidecar,
458
+ record.parentChatNames,
459
+ parentChatName,
460
+ batch,
461
+ `parent-chat\u0000${chatCoordinateKey}`,
462
+ aliasSources.parentChatName,
463
+ )
464
+ sidecar.chats[chatCoordinateKey] = record
465
+ if (batch !== undefined && recencyGroup.length > 0) batch.recencyGroups.push(recencyGroup)
466
+ return true
467
+ }
468
+
469
+ function createNewestFirstLearningBatch(): NewestFirstLearningBatch {
470
+ return { protectedEntries: new Set(), recencyGroups: [], aliases: new Map() }
471
+ }
472
+
473
+ function finalizeNewestFirstLearningBatch(sidecar: ProvenanceRegistry, batch: NewestFirstLearningBatch): void {
474
+ for (const [aliasKey, { values, original, seen, observed }] of batch.aliases) {
475
+ const resolverAliases = sidecar.resolverAliases.get(aliasKey) ?? []
476
+ const resolverAliasSet = new Set(resolverAliases)
477
+ const observedHistorical = observed.filter((value) => !resolverAliasSet.has(value))
478
+ const retainedHistorical = original.filter((value) => !resolverAliasSet.has(value) && !seen.has(value))
479
+ values.splice(0, values.length, ...resolverAliases, ...observedHistorical, ...retainedHistorical)
480
+ if (values.length > MAX_ALIASES) values.length = MAX_ALIASES
481
+ retainResolverAliases(sidecar, aliasKey, values)
482
+ }
483
+ for (let groupIndex = batch.recencyGroups.length - 1; groupIndex >= 0; groupIndex--) {
484
+ for (const { recencyKey, entry } of batch.recencyGroups[groupIndex]!) {
485
+ touchRegistryEntry(sidecar, recencyKey, entry)
486
+ }
487
+ }
488
+ }
489
+
490
+ function touchLearnedRegistryEntry(
491
+ sidecar: ProvenanceRegistry,
492
+ recencyKey: string,
493
+ entry: RegistryEntry,
494
+ protectedEntries: Set<string>,
495
+ recencyGroup: RegistryRecency[],
496
+ newestFirst: boolean,
497
+ ): void {
498
+ if (newestFirst && protectedEntries.has(recencyKey)) return
499
+ touchRegistryEntry(sidecar, recencyKey, entry)
500
+ protectedEntries.add(recencyKey)
501
+ if (newestFirst) recencyGroup.push({ recencyKey, entry })
502
+ }
503
+
504
+ function makeRegistryRoom(sidecar: ProvenanceRegistry, newCoordinates: number, protectedEntries: Set<string>): boolean {
505
+ while (sidecar.entryCount + newCoordinates > MAX_COORDINATES) {
506
+ let oldest: [string, RegistryEntry] | undefined
507
+ for (const candidate of sidecar.recency) {
508
+ if (!protectedEntries.has(candidate[0])) {
509
+ oldest = candidate
510
+ break
511
+ }
512
+ }
513
+ if (oldest === undefined) return false
514
+ const [recencyKey, entry] = oldest
515
+ sidecar.recency.delete(recencyKey)
516
+ if (entry.kind === 'workspace') {
517
+ delete sidecar.workspaces[entry.key]
518
+ sidecar.resolverAliases.delete(`workspace\u0000${entry.key}`)
519
+ } else {
520
+ delete sidecar.chats[entry.key]
521
+ sidecar.resolverAliases.delete(`chat\u0000${entry.key}`)
522
+ sidecar.resolverAliases.delete(`parent-chat\u0000${entry.key}`)
523
+ }
524
+ sidecar.entryCount -= 1
525
+ }
526
+ return true
527
+ }
528
+
529
+ function touchRegistryEntry(sidecar: ProvenanceRegistry, recencyKey: string, entry: RegistryEntry): void {
530
+ sidecar.recency.delete(recencyKey)
531
+ sidecar.recency.set(recencyKey, entry)
532
+ }
533
+
534
+ function registryRecencyKey(kind: RegistryEntry['kind'], key: string): string {
535
+ return `${kind}\u0000${key}`
536
+ }
537
+
538
+ function needsResolverEnrichment(where: FragmentProvenance, sidecar: ProvenanceRegistry): boolean {
539
+ const workspaceNames = workspaceAliases(where, sidecar)
540
+ const chat = sidecar.chats[chatKey(where)]
541
+ return (
542
+ (where.workspaceName === undefined && workspaceNames.length === 0) ||
543
+ (where.chatName === undefined && (chat?.names.length ?? 0) === 0) ||
544
+ (where.parentChat === undefined && chat?.parentChecked !== true)
545
+ )
546
+ }
547
+
548
+ function sameCoordinates(original: FragmentProvenance, resolved: FragmentProvenance): boolean {
549
+ return (
550
+ original.adapter === resolved.adapter &&
551
+ original.workspace === resolved.workspace &&
552
+ original.chat === resolved.chat &&
553
+ (original.thread ?? null) === (resolved.thread ?? null)
554
+ )
555
+ }
556
+
557
+ function resolutionAddsData(
558
+ original: FragmentProvenance,
559
+ resolution: HistoricalProvenanceResolution,
560
+ sidecar: ProvenanceRegistry,
561
+ ): boolean {
562
+ const resolved = resolution.where
563
+ const workspaceNames = workspaceAliases(original, sidecar)
564
+ const chat = sidecar.chats[chatKey(original)]
565
+ return (
566
+ (resolved.workspaceName !== undefined && !workspaceNames.includes(resolved.workspaceName)) ||
567
+ (resolved.chatName !== undefined && !(chat?.names.includes(resolved.chatName) ?? false)) ||
568
+ (resolved.parentChat !== undefined && resolved.parentChat !== chat?.parentChat) ||
569
+ (resolved.parentChatName !== undefined && !(chat?.parentChatNames.includes(resolved.parentChatName) ?? false)) ||
570
+ (resolution.parentChecked && chat?.parentChecked !== true)
571
+ )
572
+ }
573
+
574
+ function sanitizeResolution(resolution: HistoricalProvenanceResolution): HistoricalProvenanceResolution {
575
+ const where = resolution.where
576
+ const workspaceName = sanitizeProvenanceName(where.workspaceName)
577
+ const chatName = sanitizeProvenanceName(where.chatName)
578
+ const parentChatName = sanitizeProvenanceName(where.parentChatName)
579
+ return {
580
+ where: {
581
+ adapter: where.adapter,
582
+ workspace: where.workspace,
583
+ chat: where.chat,
584
+ thread: where.thread,
585
+ ...(workspaceName === undefined ? {} : { workspaceName }),
586
+ ...(chatName === undefined ? {} : { chatName }),
587
+ ...(where.parentChat !== undefined && isSafeProvenanceCoordinate(where.parentChat)
588
+ ? { parentChat: where.parentChat }
589
+ : {}),
590
+ ...(parentChatName === undefined ? {} : { parentChatName }),
591
+ },
592
+ parentChecked: resolution.parentChecked,
593
+ }
594
+ }
595
+
596
+ function applyResolution(
597
+ sidecar: ProvenanceRegistry,
598
+ original: FragmentProvenance,
599
+ resolution: HistoricalProvenanceResolution,
600
+ ): void {
601
+ if (!learnWhere(sidecar, resolution.where, undefined, aliasSourcesForResolution(original, resolution.where))) return
602
+ if (!resolution.parentChecked) return
603
+ const record = sidecar.chats[chatKey(resolution.where)] ?? { names: [], parentChatNames: [] }
604
+ record.parentChecked = true
605
+ sidecar.chats[chatKey(resolution.where)] = record
606
+ }
607
+
608
+ function aliasSourcesForResolution(original: FragmentProvenance, resolved: FragmentProvenance): AliasSources {
609
+ return {
610
+ workspaceName:
611
+ resolved.workspaceName !== undefined && resolved.workspaceName !== original.workspaceName
612
+ ? 'resolver'
613
+ : 'historical',
614
+ chatName: resolved.chatName !== undefined && resolved.chatName !== original.chatName ? 'resolver' : 'historical',
615
+ parentChatName:
616
+ resolved.parentChatName !== undefined && resolved.parentChatName !== original.parentChatName
617
+ ? 'resolver'
618
+ : 'historical',
619
+ }
620
+ }
621
+
622
+ async function settleWithin<T>(
623
+ promise: Promise<T>,
624
+ timeoutMs: number,
625
+ ): Promise<{ kind: 'value'; value: T } | { kind: 'error'; error: unknown } | { kind: 'timeout' }> {
626
+ let timer: ReturnType<typeof setTimeout> | undefined
627
+ try {
628
+ return await Promise.race([
629
+ promise.then(
630
+ (value) => ({ kind: 'value' as const, value }),
631
+ (error: unknown) => ({ kind: 'error' as const, error }),
632
+ ),
633
+ new Promise<{ kind: 'timeout' }>((resolveTimeout) => {
634
+ timer = setTimeout(() => resolveTimeout({ kind: 'timeout' }), Math.max(0, timeoutMs))
635
+ }),
636
+ ])
637
+ } finally {
638
+ if (timer !== undefined) clearTimeout(timer)
639
+ }
640
+ }
641
+
642
+ function workspaceAliases(where: FragmentProvenance, sidecar: ProvenanceRegistry): string[] {
643
+ return sidecar.workspaces[`${where.adapter}\u0000${where.workspace}`] ?? []
644
+ }
645
+
646
+ function chatKey(where: FragmentProvenance): string {
647
+ return `${where.adapter}\u0000${where.workspace}\u0000${where.chat}`
648
+ }
649
+
650
+ function addAlias(
651
+ sidecar: ProvenanceRegistry,
652
+ target: Record<string, string[]>,
653
+ key: string,
654
+ value: string,
655
+ batch: NewestFirstLearningBatch | undefined,
656
+ source: AliasSource,
657
+ ): void {
658
+ const values = target[key] ?? []
659
+ observeAlias(sidecar, values, value, batch, `workspace\u0000${key}`, source)
660
+ target[key] = values
661
+ }
662
+
663
+ function observeAlias(
664
+ sidecar: ProvenanceRegistry,
665
+ values: string[],
666
+ value: string,
667
+ batch: NewestFirstLearningBatch | undefined,
668
+ aliasKey: string,
669
+ source: AliasSource,
670
+ ): void {
671
+ if (source === 'resolver') {
672
+ const resolverAliases = sidecar.resolverAliases.get(aliasKey) ?? []
673
+ const existingResolverIndex = resolverAliases.indexOf(value)
674
+ if (existingResolverIndex >= 0) resolverAliases.splice(existingResolverIndex, 1)
675
+ resolverAliases.unshift(value)
676
+ sidecar.resolverAliases.set(aliasKey, resolverAliases)
677
+ }
678
+
679
+ if (batch === undefined) {
680
+ const resolverAliases = sidecar.resolverAliases.get(aliasKey) ?? []
681
+ const resolverAliasSet = new Set(resolverAliases)
682
+ const observedHistorical = source === 'historical' && !resolverAliasSet.has(value) ? [value] : []
683
+ const retainedHistorical = values.filter((candidate) => !resolverAliasSet.has(candidate) && candidate !== value)
684
+ values.splice(0, values.length, ...resolverAliases, ...observedHistorical, ...retainedHistorical)
685
+ if (values.length > MAX_ALIASES) values.length = MAX_ALIASES
686
+ retainResolverAliases(sidecar, aliasKey, values)
687
+ return
688
+ }
689
+
690
+ const state = batch.aliases.get(aliasKey) ?? {
691
+ values,
692
+ original: [...values],
693
+ seen: new Set<string>(),
694
+ observed: [],
695
+ }
696
+ if (state.seen.has(value)) return
697
+ state.seen.add(value)
698
+ state.observed.push(value)
699
+ batch.aliases.set(aliasKey, state)
700
+ }
701
+
702
+ function retainResolverAliases(sidecar: ProvenanceRegistry, aliasKey: string, values: string[]): void {
703
+ const resolverAliases = sidecar.resolverAliases.get(aliasKey)
704
+ if (resolverAliases === undefined) return
705
+ const retained = resolverAliases.filter((value) => values.includes(value))
706
+ if (retained.length === 0) sidecar.resolverAliases.delete(aliasKey)
707
+ else sidecar.resolverAliases.set(aliasKey, retained)
708
+ }
709
+
710
+ function registryFor(agentDir: string): ProvenanceRegistry {
711
+ let registry = runtimeRegistries.get(agentDir)
712
+ if (registry === undefined) {
713
+ registry = { workspaces: {}, chats: {}, entryCount: 0, recency: new Map(), resolverAliases: new Map() }
714
+ runtimeRegistries.set(agentDir, registry)
715
+ }
716
+ return registry
717
+ }