typeclaw 0.45.1 → 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 (142) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -1
  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 +151 -39
  9. package/src/agent/network/response-body.ts +26 -0
  10. package/src/agent/network/safe-http.ts +198 -0
  11. package/src/agent/plugin-tools.ts +379 -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 +1050 -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 +143 -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 +27 -0
  30. package/src/agent/turn-runner.ts +86 -6
  31. package/src/bundled-plugins/backup/index.ts +2 -1
  32. package/src/bundled-plugins/backup/runner.ts +2 -1
  33. package/src/bundled-plugins/doc-render/render.ts +93 -12
  34. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  35. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  36. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  37. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  38. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  39. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  40. package/src/bundled-plugins/memory/README.md +23 -11
  41. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  42. package/src/bundled-plugins/memory/citations.ts +22 -9
  43. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  44. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  45. package/src/bundled-plugins/memory/index.ts +0 -4
  46. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  47. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  48. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  49. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  50. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  51. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  52. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  53. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  54. package/src/bundled-plugins/reviewer/index.ts +2 -2
  55. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  56. package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
  57. package/src/bundled-plugins/scout/scout.ts +8 -0
  58. package/src/bundled-plugins/security/index.ts +4 -4
  59. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  60. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  61. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  62. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  63. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  64. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  65. package/src/channels/adapters/discord-bot.ts +66 -6
  66. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  67. package/src/channels/adapters/discord-id.ts +4 -0
  68. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  69. package/src/channels/adapters/discord.ts +57 -7
  70. package/src/channels/adapters/github/auth-app.ts +41 -12
  71. package/src/channels/adapters/github/index.ts +23 -11
  72. package/src/channels/adapters/github/review-submitter.ts +302 -0
  73. package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
  74. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  75. package/src/channels/adapters/kakaotalk-typing.ts +17 -15
  76. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  77. package/src/channels/adapters/slack-bot.ts +19 -8
  78. package/src/channels/adapters/slack-classify.ts +21 -2
  79. package/src/channels/adapters/slack.ts +59 -7
  80. package/src/channels/adapters/telegram-bot.ts +18 -5
  81. package/src/channels/adapters/webex-bot.ts +8 -3
  82. package/src/channels/adapters/webex.ts +8 -3
  83. package/src/channels/fetch-attachment.ts +43 -0
  84. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  85. package/src/channels/github-token-bridge.ts +10 -3
  86. package/src/channels/manager.ts +9 -0
  87. package/src/channels/router.ts +248 -6
  88. package/src/channels/types.ts +28 -1
  89. package/src/cli/channel.ts +1 -1
  90. package/src/cli/init.ts +1 -1
  91. package/src/cli/model.ts +57 -7
  92. package/src/compose/stop.ts +17 -5
  93. package/src/config/config.ts +6 -6
  94. package/src/config/models-mutation.ts +13 -1
  95. package/src/config/providers.ts +176 -0
  96. package/src/container/start.ts +49 -10
  97. package/src/doctor/checks.ts +3 -1
  98. package/src/doctor/commit.ts +2 -1
  99. package/src/doctor/file-ownership.ts +52 -0
  100. package/src/dreams/git.ts +2 -1
  101. package/src/git/hookless.ts +5 -0
  102. package/src/git/reconcile-ignored.ts +18 -5
  103. package/src/git/secret-history.ts +371 -0
  104. package/src/git/system-commit.ts +12 -6
  105. package/src/init/dockerfile.ts +86 -5
  106. package/src/init/index.ts +17 -5
  107. package/src/init/models-dev.ts +4 -0
  108. package/src/init/validate-api-key.ts +2 -0
  109. package/src/mcp/tools.ts +16 -3
  110. package/src/permissions/builtins.ts +3 -1
  111. package/src/plugin/context.ts +2 -0
  112. package/src/plugin/index.ts +1 -0
  113. package/src/plugin/manager.ts +4 -0
  114. package/src/plugin/types.ts +21 -0
  115. package/src/run/index.ts +40 -0
  116. package/src/run/llm-fetch-observer.ts +41 -4
  117. package/src/sandbox/build.ts +37 -15
  118. package/src/sandbox/canonical-secrets.ts +18 -0
  119. package/src/sandbox/env-exposure.ts +80 -0
  120. package/src/sandbox/errors.ts +13 -6
  121. package/src/sandbox/hidden-paths.ts +102 -44
  122. package/src/sandbox/index.ts +22 -4
  123. package/src/sandbox/package-install.ts +3 -27
  124. package/src/sandbox/policy.ts +11 -25
  125. package/src/sandbox/privileged-runtime.ts +255 -0
  126. package/src/sandbox/session-tmp.ts +8 -2
  127. package/src/sandbox/writable-zones.ts +204 -140
  128. package/src/secrets/index.ts +8 -0
  129. package/src/secrets/refresh-provider-oauth.ts +128 -0
  130. package/src/server/command-runner.ts +48 -4
  131. package/src/server/index.ts +4 -0
  132. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  133. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  134. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  135. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  136. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  137. package/src/skills/typeclaw-config/SKILL.md +5 -5
  138. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  139. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  140. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  141. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  142. package/typeclaw.schema.json +20 -0
@@ -1,12 +1,19 @@
1
1
  import { TYPECLAW_INTERNAL_BASH_ENV } from '@/agent/plugin-tools'
2
2
  import type { SessionOrigin } from '@/agent/session-origin'
3
+ import {
4
+ configureReviewVerdictCoordinator,
5
+ createSharedReviewVerdictGuard,
6
+ } from '@/channels/github-review-verdict-coordinator'
7
+ import { CORE_PERMISSIONS } from '@/permissions/builtins'
3
8
  import { definePlugin } from '@/plugin'
4
- import { resolveHiddenPaths } from '@/sandbox'
5
9
 
6
- import { createApproveIdempotencyGuard } from './approve-idempotency'
7
10
  import { createGithubEffectiveApprovalResolver, createGithubHeadShaResolver } from './effective-approval'
8
- import { analyzeGhCommand, effectiveGhTokensForAuthenticatedUserEndpoint } from './gh-command'
9
- import { ensureGitAskPassHelper } from './git-askpass'
11
+ import {
12
+ analyzeGhCommand,
13
+ canInjectPatIntoPassThroughGh,
14
+ effectiveGhTokensForAuthenticatedUserEndpoint,
15
+ usesGhApiGraphqlEndpoint,
16
+ } from './gh-command'
10
17
  import { analyzeGitCommand, defaultGitResolvers, resolveGhDefaultRepoFromCwd } from './git-command'
11
18
  import { checkGraphqlAuthNudge } from './graphql-auth-nudge'
12
19
  import { commitReviewIfSucceeded, noteReviewCommand } from './review-recorder'
@@ -17,15 +24,32 @@ export default definePlugin({
17
24
  const resolveTokenForRepo = ctx.github.resolveTokenForRepo
18
25
  const hasAppTokenResolver = ctx.github.hasAppTokenResolver
19
26
 
20
- // A .env PAT is broad and long-lived, so it may only reach bash that runs
21
- // WITHOUT bwrap's --clearenv — otherwise a low-trust, stranger-drivable
22
- // sandbox could exfiltrate it. We gate on the SAME signal applyBashSandbox
23
- // uses (resolveHiddenPaths empty => unsandboxed) rather than a role name, so
24
- // the credential policy can never diverge from the actual sandbox decision
25
- // and custom roles follow their real fs.see.secrets / security.bypass grant.
26
- const runsUnsandboxed = (origin: SessionOrigin | undefined): boolean => {
27
- const { dirs, files } = resolveHiddenPaths(ctx.permissions, origin, ctx.agentDir)
28
- return dirs.length === 0 && files.length === 0
27
+ // Every model-driven bash masks the canonical credential files. A role may
28
+ // still USE a PAT through this runtime-owned overlay, which injects one
29
+ // value without exposing .env/secrets.json to the model. Gate that on the
30
+ // existing credential capability rather than sandbox presence: privileged
31
+ // roles are sandboxed for file masking too.
32
+ const canUsePat = (origin: SessionOrigin | undefined): boolean =>
33
+ ctx.permissions.has(origin, CORE_PERMISSIONS.fsSeeSecrets) ||
34
+ ctx.permissions.has(origin, 'security.bypass.medium')
35
+
36
+ const effectiveProcessToken = (): { envName: 'GH_TOKEN' | 'GITHUB_TOKEN'; value: string } | undefined => {
37
+ if (process.env.GH_TOKEN !== undefined && process.env.GH_TOKEN !== '') {
38
+ return { envName: 'GH_TOKEN', value: process.env.GH_TOKEN }
39
+ }
40
+ if (process.env.GITHUB_TOKEN !== undefined && process.env.GITHUB_TOKEN !== '') {
41
+ return { envName: 'GITHUB_TOKEN', value: process.env.GITHUB_TOKEN }
42
+ }
43
+ return undefined
44
+ }
45
+
46
+ const processPatOverlay = (): Record<string, string> | undefined => {
47
+ const token = effectiveProcessToken()
48
+ if (token === undefined) return undefined
49
+ const tokenClass = classifyGhToken(token.value)
50
+ return tokenClass === 'cross-owner' || tokenClass === 'fine-grained-pat'
51
+ ? { [token.envName]: token.value }
52
+ : undefined
29
53
  }
30
54
 
31
55
  // The PAT is in the container env but stripped by --clearenv for this role,
@@ -61,14 +85,24 @@ export default definePlugin({
61
85
  'scoped calls still work). It is not a valid auth/login check. For repo data use ' +
62
86
  '`gh <cmd> -R owner/repo` or `gh api /repos/owner/repo/...`; for the actor, read the ' +
63
87
  'PR/issue/comment context you were given instead of `gh api /user`.'
88
+ const patGraphqlReason =
89
+ 'Model-driven `gh api graphql` cannot receive a classic or fine-grained GitHub PAT because the query can ' +
90
+ 'target repositories that are not visible in argv; `-R owner/repo` is only a CLI hint, not an authorization ' +
91
+ 'boundary. Configure GitHub App auth so TypeClaw can mint a server-enforced single-repository installation ' +
92
+ 'token, use a statically repo-confined REST endpoint, or run the PAT-backed GraphQL command host-side.'
64
93
  const resolveToken = async (workspace: string) => {
65
94
  const result = await resolveTokenForRepo(workspace)
66
95
  return result.kind === 'token' ? result.token : null
67
96
  }
68
- const verdictGuard = createApproveIdempotencyGuard({
69
- resolveEffectiveApproval: createGithubEffectiveApprovalResolver({ resolveToken }),
97
+ configureReviewVerdictCoordinator({
98
+ resolveEffectiveApproval: createGithubEffectiveApprovalResolver({
99
+ resolveToken,
100
+ selfLogin: ctx.github.getAppSelfLogin ?? (() => null),
101
+ isAppAuth: hasAppTokenResolver,
102
+ }),
70
103
  resolveHeadSha: createGithubHeadShaResolver({ resolveToken }),
71
104
  })
105
+ const verdictGuard = createSharedReviewVerdictGuard()
72
106
 
73
107
  type HookResult = void | { block: true; reason: string }
74
108
 
@@ -108,31 +142,6 @@ export default definePlugin({
108
142
  command: string
109
143
  }): Promise<HookResult | 'fall-through'> => {
110
144
  const { event, command } = params
111
- const review = await noteReviewCommand({ callId: event.callId, command })
112
- // guard() holds the lease expecting tool.after to release it, but a
113
- // tool.before block (from ANY guard below) means the command never runs, so
114
- // tool.after never fires and the lease strands for its full TTL — telling
115
- // every other session "the in-flight one will post" when it never will (the
116
- // lost-verdict strand: a review trips the shape guard, the lease strands, the
117
- // PR ends unreviewed). blockAfterLease() releases on such a block. guard()'s
118
- // OWN terminal block self-releases and returns directly, bypassing this path.
119
- let leaseClaimed = false
120
- const blockAfterLease = async (block: HookResult & { block: true }): Promise<HookResult> => {
121
- if (leaseClaimed) await verdictGuard.release({ callId: event.callId, succeeded: false })
122
- return block
123
- }
124
- if (review.detected !== null) {
125
- const block = await verdictGuard.guard({
126
- callId: event.callId,
127
- workspace: review.detected.workspace,
128
- prNumber: review.detected.prNumber,
129
- verdict: review.detected.verdict,
130
- })
131
- if (block !== null) return block
132
- leaseClaimed = true
133
- }
134
- if (review.dump !== null) return blockAfterLease(review.dump)
135
-
136
145
  // Analyze first WITHOUT the fallback: an explicit `-R`/path repo must win,
137
146
  // and we only pay for fallback resolution (a git subprocess) when the
138
147
  // command is otherwise repo-less. A trusted fallback is then applied ONLY to
@@ -154,6 +163,42 @@ export default definePlugin({
154
163
  }
155
164
  }
156
165
 
166
+ // Reject every statically unsafe/conflicting shape before review detection.
167
+ // noteReviewCommand may open an --input file, and verdictGuard.guard performs
168
+ // authenticated GitHub reads through the token resolver; neither may run for
169
+ // a command the argv/repository authorization layer already rejects.
170
+ if (decision.kind === 'block') {
171
+ return {
172
+ block: true,
173
+ reason:
174
+ decision.code === 'credential-display'
175
+ ? decision.reason
176
+ : decision.reason + buildGhBlockGuidance(decision.code, fallbackRepo),
177
+ }
178
+ }
179
+
180
+ const review = await noteReviewCommand({ callId: event.callId, command })
181
+ // guard() holds the lease expecting tool.after to release it. A later
182
+ // tool.before block means tool.after never fires, so blockAfterLease()
183
+ // releases the lease with succeeded:false. The static command analyzer runs
184
+ // above and never claims a lease for a command it will reject.
185
+ let leaseClaimed = false
186
+ const blockAfterLease = async (block: HookResult & { block: true }): Promise<HookResult> => {
187
+ if (leaseClaimed) await verdictGuard.release({ callId: event.callId, succeeded: false })
188
+ return block
189
+ }
190
+ if (review.detected !== null) {
191
+ const block = await verdictGuard.guard({
192
+ callId: event.callId,
193
+ workspace: review.detected.workspace,
194
+ prNumber: review.detected.prNumber,
195
+ verdict: review.detected.verdict,
196
+ })
197
+ if (block !== null) return block
198
+ leaseClaimed = true
199
+ }
200
+ if (review.dump !== null) return blockAfterLease(review.dump)
201
+
157
202
  // `/user` classifies as pass-through (no repo to mint for), so this block
158
203
  // must run BEFORE the pass-through return. Resolve the EFFECTIVE token per
159
204
  // `/user` invocation (a command-local `GH_TOKEN=…`/`GITHUB_TOKEN=…` overrides
@@ -168,7 +213,33 @@ export default definePlugin({
168
213
  return blockAfterLease({ block: true, reason: appUserEndpointReason })
169
214
  }
170
215
 
171
- if (decision.kind === 'pass-through') return 'fall-through'
216
+ const processToken = effectiveProcessToken()
217
+ const tokenClass = classifyGhToken(processToken?.value)
218
+ if (
219
+ (tokenClass === 'cross-owner' || tokenClass === 'fine-grained-pat') &&
220
+ canUsePat(event.origin) &&
221
+ usesGhApiGraphqlEndpoint(command)
222
+ ) {
223
+ return blockAfterLease({ block: true, reason: patGraphqlReason })
224
+ }
225
+
226
+ if (decision.kind === 'pass-through') {
227
+ const patOverlay = canUsePat(event.origin) ? processPatOverlay() : undefined
228
+ if (patOverlay !== undefined) {
229
+ if (!canInjectPatIntoPassThroughGh(command)) {
230
+ return blockAfterLease({
231
+ block: true,
232
+ reason:
233
+ 'A GitHub PAT can only be brokered to a single standalone known-safe `gh` command. ' +
234
+ 'Chaining, substitution, aliases, extensions, and config/auth management are blocked because a sibling or plugin could read the command-scoped token.',
235
+ })
236
+ }
237
+ const existing = event.args[TYPECLAW_INTERNAL_BASH_ENV]
238
+ const overlay = existing !== null && typeof existing === 'object' ? (existing as Record<string, string>) : {}
239
+ event.args[TYPECLAW_INTERNAL_BASH_ENV] = { ...overlay, ...patOverlay }
240
+ }
241
+ return 'fall-through'
242
+ }
172
243
 
173
244
  // The `-R` strip is a pure syntax fix (`gh api` rejects `-R`), independent
174
245
  // of token minting, so apply it for EVERY token class — including the PAT
@@ -179,30 +250,25 @@ export default definePlugin({
179
250
  event.args.command = decision.rewrittenCommand
180
251
  }
181
252
 
182
- const tokenClass = classifyGhToken(process.env.GH_TOKEN)
183
-
184
253
  // PAT classes (classic = cross-owner, fine-grained) are not re-minted per
185
254
  // repo; the seeded GH_TOKEN is the only token we have. App minting, when
186
- // available, is still preferred for SANDBOXED roles (the PAT can't reach
187
- // them), so a PAT must NOT suppress minting there — only for unsandboxed
188
- // execution does the PAT win. Unsandboxed: the PAT already rides inherited
189
- // process.env, but re-asserting it in the overlay keeps the command-local
190
- // GH_TOKEN explicit and consistent with the git path. Sandboxed PAT-only:
255
+ // available, is preferred for roles without credential-use permission,
256
+ // so a PAT must not suppress minting there. An entitled role receives the
257
+ // PAT through the narrow overlay; raw process.env and credential files
258
+ // remain unavailable inside bash. Sandboxed PAT-only:
191
259
  // block with guidance instead of failing silently.
192
260
  // Set when a sandboxed PAT falls through to App minting: the tail's
193
261
  // shouldMintAppToken(process.env.GH_TOKEN) re-check would see the PAT and
194
262
  // bail, so this flag forces the mint that the PAT must not suppress.
195
263
  let mintForSandboxedPat = false
196
264
  if (tokenClass === 'cross-owner' || tokenClass === 'fine-grained-pat') {
197
- // Unsandboxed: the PAT authenticates directly (it already rides inherited
198
- // process.env). For a repo-targeting command we re-assert it in the
199
- // overlay so behavior is explicit and matches the git path; otherwise we
200
- // pass through. The App-oriented missing-repo / multi-owner BLOCK does
201
- // NOT apply — a PAT needs no per-repo mint — so we never surface it here.
202
- if (runsUnsandboxed(event.origin)) {
265
+ // Credential-entitled role: for a repo-targeting command, inject the PAT
266
+ // through the runtime-owned overlay. The same literal-repo and
267
+ // credential-safe argv gates apply to PATs and App tokens.
268
+ if (canUsePat(event.origin)) {
203
269
  if (decision.kind === 'inject') {
204
270
  event.args[TYPECLAW_INTERNAL_BASH_ENV] = {
205
- GH_TOKEN: process.env.GH_TOKEN as string,
271
+ [processToken?.envName ?? 'GH_TOKEN']: processToken?.value ?? '',
206
272
  ...(fallbackRepoUsed && fallbackRepo !== undefined ? { GH_REPO: fallbackRepo } : {}),
207
273
  }
208
274
  }
@@ -212,29 +278,16 @@ export default definePlugin({
212
278
  // available (a PAT must NOT suppress it, or the original silent-failure
213
279
  // bug returns); otherwise block with guidance rather than failing mute.
214
280
  if (!shouldMintAppToken(undefined, hasAppTokenResolver())) {
215
- if (decision.kind === 'block') {
216
- return blockAfterLease({
217
- block: true,
218
- reason: decision.reason + buildGhBlockGuidance(decision.code, fallbackRepo),
219
- })
220
- }
221
281
  warnSandboxedPatWithheldOnce()
222
282
  return blockAfterLease({ block: true, reason: sandboxedPatWithheldReason })
223
283
  }
224
284
  mintForSandboxedPat = true
225
285
  }
226
286
 
227
- if (decision.kind === 'block') {
228
- return blockAfterLease({
229
- block: true,
230
- reason: decision.reason + buildGhBlockGuidance(decision.code, fallbackRepo),
231
- })
232
- }
233
-
234
287
  // No App auth (no App-class GH_TOKEN and no live minter): leave whatever
235
288
  // is seeded so `gh` fails honestly rather than us guessing a token. The
236
289
  // sandboxed-PAT mint path bypasses this PAT-class re-check via the flag.
237
- if (!mintForSandboxedPat && !shouldMintAppToken(process.env.GH_TOKEN, hasAppTokenResolver())) return
290
+ if (!mintForSandboxedPat && !shouldMintAppToken(processToken?.value, hasAppTokenResolver())) return
238
291
 
239
292
  const result = await resolveTokenForRepo(decision.repoSlug)
240
293
  if (result.kind === 'unavailable') return blockAfterLease({ block: true, reason: result.reason })
@@ -251,75 +304,18 @@ export default definePlugin({
251
304
  return
252
305
  }
253
306
 
254
- const handleGitCommand = async (params: {
255
- event: { args: Record<string, unknown>; origin?: SessionOrigin }
256
- command: string
257
- agentDir: string
258
- }): Promise<HookResult> => {
259
- const { event, command, agentDir } = params
260
- const tokenClass = classifyGhToken(process.env.GH_TOKEN)
261
- const isPat = tokenClass === 'cross-owner' || tokenClass === 'fine-grained-pat'
262
-
263
- // A PAT is not re-mintable per repo. For unsandboxed roles it rides the
264
- // git-askpass path so SSH/scp remotes get rewritten to https and clone
265
- // works uniformly (matching the gh path). For sandboxed roles the PAT is
266
- // withheld (env cleared): mint an App token instead if available, else
267
- // block with guidance rather than letting git fail silently. App auth must
268
- // still mint for sandboxed roles even when a PAT is present.
269
- const useEnvPat = isPat && runsUnsandboxed(event.origin)
270
- // Sandboxed PAT: the env is cleared, so the PAT can't reach git. Mint an
271
- // App token instead when a minter is live (a PAT must NOT suppress it);
272
- // otherwise block with guidance below rather than fail silently.
273
- const mintForSandboxedPat = isPat && !useEnvPat && shouldMintAppToken(undefined, hasAppTokenResolver())
274
- if (isPat && !useEnvPat && !mintForSandboxedPat) {
275
- const decision = await analyzeGitCommand(command, { cwd: agentDir, resolvers: defaultGitResolvers })
276
- if (decision.kind === 'pass-through') return
277
- if (decision.kind === 'block') return { block: true, reason: decision.reason }
278
- warnSandboxedPatWithheldOnce()
279
- return { block: true, reason: sandboxedPatWithheldReason }
280
- }
281
-
282
- // Neither a usable PAT nor App auth: leave the command untouched so git
283
- // fails honestly rather than us guessing a token. App auth is detected by
284
- // the live minter too, not just an App-class GH_TOKEN: multi-owner /
285
- // no-repos App configs never seed GH_TOKEN yet can mint. The mintForSandboxedPat
286
- // flag forces minting past this PAT-class re-check.
287
- if (!useEnvPat && !mintForSandboxedPat && !shouldMintAppToken(process.env.GH_TOKEN, hasAppTokenResolver())) return
288
-
307
+ const handleGitCommand = async (params: { command: string; agentDir: string }): Promise<HookResult> => {
308
+ const { command, agentDir } = params
289
309
  const decision = await analyzeGitCommand(command, { cwd: agentDir, resolvers: defaultGitResolvers })
290
310
  if (decision.kind === 'pass-through') return
291
311
  if (decision.kind === 'block') return { block: true, reason: decision.reason }
292
-
293
- // The unsandboxed-PAT path uses the PAT directly; otherwise mint a per-repo
294
- // App token. Both ride TYPECLAW_GIT_TOKEN (read by the askpass helper),
295
- // never argv/config.
296
- let gitToken: string
297
- if (useEnvPat) {
298
- gitToken = process.env.GH_TOKEN as string
299
- } else {
300
- const result = await resolveTokenForRepo(decision.repoSlug)
301
- if (result.kind === 'unavailable') return { block: true, reason: result.reason }
302
- gitToken = result.token
312
+ const token = effectiveProcessToken()
313
+ if (token === undefined && !hasAppTokenResolver()) return
314
+ return {
315
+ block: true,
316
+ reason:
317
+ 'Authenticated git is unavailable to model-driven bash because git can invoke repository hooks and credential helpers that inherit reusable credentials. Local git commands still work; use a first-class GitHub action or run network git host-side.',
303
318
  }
304
-
305
- const askpass = await ensureGitAskPassHelper()
306
- const existing = event.args[TYPECLAW_INTERNAL_BASH_ENV]
307
- const overlay = existing !== null && typeof existing === 'object' ? (existing as Record<string, string>) : {}
308
- // insteadOf rewrites SSH/scp remotes to https so the helper's credential
309
- // applies; GIT_TERMINAL_PROMPT=0 fails fast instead of hanging.
310
- event.args[TYPECLAW_INTERNAL_BASH_ENV] = {
311
- ...overlay,
312
- GIT_ASKPASS: askpass,
313
- TYPECLAW_GIT_TOKEN: gitToken,
314
- GIT_TERMINAL_PROMPT: '0',
315
- GIT_CONFIG_COUNT: '2',
316
- GIT_CONFIG_KEY_0: 'url.https://github.com/.insteadOf',
317
- GIT_CONFIG_VALUE_0: 'git@github.com:',
318
- GIT_CONFIG_KEY_1: 'url.https://github.com/.insteadOf',
319
- GIT_CONFIG_VALUE_1: 'ssh://git@github.com/',
320
- }
321
- if (decision.rewrittenCommand !== undefined) event.args.command = decision.rewrittenCommand
322
- return
323
319
  }
324
320
 
325
321
  return {
@@ -335,7 +331,7 @@ export default definePlugin({
335
331
  }
336
332
 
337
333
  if (command.includes('git')) {
338
- return await handleGitCommand({ event, command, agentDir: ctx.agentDir })
334
+ return await handleGitCommand({ command, agentDir: ctx.agentDir })
339
335
  }
340
336
  return
341
337
  },
@@ -0,0 +1,138 @@
1
+ import { execFile } from 'node:child_process'
2
+ import { mkdtemp, rm } from 'node:fs/promises'
3
+ import path from 'node:path'
4
+ import { promisify } from 'node:util'
5
+
6
+ import { z } from 'zod'
7
+
8
+ import { GITHUB_API_BASE, githubJsonHeaders } from '@/channels/adapters/github/auth-pat'
9
+ import type { ResolveGithubTokenForRepo } from '@/channels/github-token-bridge'
10
+ import { defineTool } from '@/plugin'
11
+ import { ensureSessionTmpDir } from '@/sandbox'
12
+
13
+ import { ensureGitAskPassHelper } from './git-askpass'
14
+
15
+ const execFileAsync = promisify(execFile)
16
+ const FULL_SHA = /^[0-9a-f]{40}$/i
17
+ const REPO_SLUG = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/
18
+
19
+ type RunProcess = (file: string, args: string[], options: { env: NodeJS.ProcessEnv }) => Promise<void>
20
+ type GithubFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
21
+
22
+ export async function prepareReviewerCheckout(options: {
23
+ repoSlug: string
24
+ headSha: string
25
+ sessionId: string
26
+ resolveTokenForRepo: ResolveGithubTokenForRepo
27
+ fetchImpl?: GithubFetch
28
+ runProcess?: RunProcess
29
+ ensureAskPass?: () => Promise<string>
30
+ }): Promise<{ path: string; repoSlug: string; headSha: string }> {
31
+ if (!REPO_SLUG.test(options.repoSlug)) throw new Error('repository must be one owner/repo slug')
32
+ if (!FULL_SHA.test(options.headSha)) throw new Error('headSha must be a full 40-character commit SHA')
33
+ const tokenResult = await options.resolveTokenForRepo(options.repoSlug)
34
+ if (tokenResult.kind !== 'token') throw new Error(tokenResult.reason)
35
+ const token = tokenResult.token
36
+ await verifyCommit(options.fetchImpl ?? fetch, options.repoSlug, options.headSha, token)
37
+
38
+ const sessionRoot = await ensureSessionTmpDir(options.sessionId)
39
+ const checkout = await mkdtemp(path.join(sessionRoot, 'review-checkout-'))
40
+ const run = options.runProcess ?? defaultRunProcess
41
+ try {
42
+ const baseEnv: NodeJS.ProcessEnv = {
43
+ PATH: process.env.PATH ?? '/usr/bin:/bin',
44
+ HOME: sessionRoot,
45
+ GIT_CONFIG_GLOBAL: '/dev/null',
46
+ GIT_CONFIG_NOSYSTEM: '1',
47
+ GIT_TERMINAL_PROMPT: '0',
48
+ }
49
+ await run('git', ['init', '--quiet', checkout], { env: baseEnv })
50
+ const askPass = await (options.ensureAskPass ?? ensureGitAskPassHelper)()
51
+ await run(
52
+ 'git',
53
+ [
54
+ '-C',
55
+ checkout,
56
+ '-c',
57
+ 'credential.helper=',
58
+ '-c',
59
+ 'core.hooksPath=/dev/null',
60
+ 'fetch',
61
+ '--depth=1',
62
+ `https://github.com/${options.repoSlug}.git`,
63
+ options.headSha,
64
+ ],
65
+ { env: { ...baseEnv, GIT_ASKPASS: askPass, TYPECLAW_GIT_TOKEN: token } },
66
+ )
67
+ await run(
68
+ 'git',
69
+ [
70
+ '-C',
71
+ checkout,
72
+ '-c',
73
+ 'credential.helper=',
74
+ '-c',
75
+ 'core.hooksPath=/dev/null',
76
+ 'checkout',
77
+ '--quiet',
78
+ '--detach',
79
+ options.headSha,
80
+ ],
81
+ { env: baseEnv },
82
+ )
83
+ return { path: checkout, repoSlug: options.repoSlug, headSha: options.headSha.toLocaleLowerCase() }
84
+ } catch (error) {
85
+ await rm(checkout, { recursive: true, force: true }).catch(() => {})
86
+ throw error
87
+ }
88
+ }
89
+
90
+ export function createReviewerCheckoutTool(resolveTokenForRepo: ResolveGithubTokenForRepo) {
91
+ return defineTool({
92
+ description:
93
+ 'Prepare a runtime-owned token-safe scratch checkout of one allowlisted GitHub repository at an exact full commit SHA.',
94
+ parameters: z.object({ repoSlug: z.string(), headSha: z.string() }),
95
+ // `repoSlug` ("owner/repo") and `headSha` (40-hex) are remote GitHub
96
+ // coordinates, never local paths — repoSlug is only ever interpolated into
97
+ // `https://github.com/<slug>.git` and prepareReviewerCheckout rejects
98
+ // anything not matching /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/. Declared so the
99
+ // required "/" in a slug isn't misread as a path separator. Scoped to THIS
100
+ // tool: an undeclared reader passing a slug-shaped value still fails closed.
101
+ fileOperands: { nonFile: ['repoSlug', 'headSha'] },
102
+ async execute(args, ctx) {
103
+ try {
104
+ const receipt = await prepareReviewerCheckout({
105
+ repoSlug: args.repoSlug,
106
+ headSha: args.headSha,
107
+ sessionId: ctx.sessionId,
108
+ resolveTokenForRepo,
109
+ })
110
+ return {
111
+ content: [{ type: 'text' as const, text: `Reviewer checkout ready: ${receipt.path} @ ${receipt.headSha}` }],
112
+ details: { ok: true, ...receipt },
113
+ }
114
+ } catch (error) {
115
+ const message = error instanceof Error ? error.message : String(error)
116
+ return {
117
+ content: [{ type: 'text' as const, text: `Reviewer checkout failed: ${message}` }],
118
+ details: { ok: false, error: message },
119
+ }
120
+ }
121
+ },
122
+ })
123
+ }
124
+
125
+ async function verifyCommit(fetchImpl: GithubFetch, repoSlug: string, sha: string, token: string): Promise<void> {
126
+ const response = await fetchImpl(`${GITHUB_API_BASE}/repos/${repoSlug}/commits/${sha}`, {
127
+ headers: githubJsonHeaders(token),
128
+ redirect: 'error',
129
+ })
130
+ if (!response.ok) throw new Error(`GitHub could not verify ${repoSlug}@${sha} (${response.status})`)
131
+ const body = (await response.json().catch(() => null)) as { sha?: unknown } | null
132
+ if (typeof body?.sha !== 'string' || body.sha.toLocaleLowerCase() !== sha.toLocaleLowerCase())
133
+ throw new Error('GitHub commit verification returned a different SHA')
134
+ }
135
+
136
+ async function defaultRunProcess(file: string, args: string[], options: { env: NodeJS.ProcessEnv }): Promise<void> {
137
+ await execFileAsync(file, args, { ...options, maxBuffer: 1024 * 1024 })
138
+ }
@@ -1,3 +1,4 @@
1
+ import { hooklessGitArgs } from '@/git/hookless'
1
2
  import { resolveAgentGit } from '@/git/resolve-agent-git'
2
3
  import type { ContentPart, ToolResult } from '@/plugin'
3
4
 
@@ -63,7 +64,7 @@ const defaultDeps: UncommittedChangesDeps = {
63
64
  if (!bun) return null
64
65
  try {
65
66
  const proc = bun.spawn({
66
- cmd: ['git', ...gitArgs, 'status', '--porcelain=v1'],
67
+ cmd: ['git', ...hooklessGitArgs([...gitArgs, 'status', '--porcelain=v1'])],
67
68
  cwd: agentDir,
68
69
  stdout: 'pipe',
69
70
  stderr: 'pipe',
@@ -30,16 +30,28 @@ All fields are **restart-required** — the plugin reads them once at boot. The
30
30
 
31
31
  ## What it contributes
32
32
 
33
- | Kind | Name | Notes |
34
- | -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35
- | Subagent | `memory-logger` | Reads a parent transcript past a watermark and appends fragments to `memory/streams/<today>.jsonl`. Coalesced per `agentDir`. |
36
- | Subagent | `dreaming` | Reads shards under `memory/topics/` plus undreamed daily-stream events and rebalances the topic shards. Coalesced per `agentDir`. Citation-superset invariant enforced on every run. |
37
- | Tool | `memory_search` | Main-agent tool. Pass `query` to search, or `topic` to look up one shard by exact slug (not both). Search is substring/regex across BOTH topic shards (slugs, frontmatter, bodies) and undreamed daily-stream events (fragment topic/body, legacy prose). Plain queries are phrase-first: the whole query is tried as one substring, and if that finds nothing the query is split on whitespace and the distinct words are OR-matched, ranked by how many words each hit contains (regex queries never fall back). Results are discriminated by `source: "topic" \| "stream"`; exact-phrase (and regex) results list topics first, then streams newest-first, while word-fallback results are ranked by matched-word count with that order as the tiebreak (so a higher-scoring stream can precede a lower-scoring topic). The `topic` mode reads `memory/topics/<slug>.md` directly via `loadShard` and returns that one shard with its full body — no fuzzy search — so a channel agent can open a topic whose slug the per-turn injection already showed it, instead of re-searching for a body the retrieval layer already located. When no topic shard matches the slug it falls back to a reference of the same slug (`memory/references/<slug>.md`), because the per-turn injection renders topic and reference entries with the same `slug:` line and the same `memory_search({ topic: "<slug>" })` recovery hint — so a reference slug surfaced in channel memory must resolve here, not dead-end. Bad slugs (path traversal) come back as a structured error; a slug matching neither a topic nor a reference is an empty match set. The optional `where` param scopes a query to one room (`"#incidents"` or its raw chat id): it keeps only stream fragments whose captured `where` matches the room by raw `chat` id or `chatName` (case-insensitive, leading `#` optional) and — because room is fragment-only provenance — returns ONLY stream matches, excluding topic shards and references. |
38
- | Tool | `delete_topic_shard` | Subagent-only (dreaming). Deletes a topic shard at `memory/topics/<slug>.md`. Path-guarded. |
39
- | Cron | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`. |
40
- | Hook | `session.idle` | Per-session debouncer with size-based ceiling. Spawns `memory-logger` on idle or buffer-trip. |
41
- | Hook | `session.end` | Spawns `memory-logger` immediately and clears per-session retrieval de-dup state. |
42
- | Hook | `session.turn.start` | Renders the per-turn user-prompt memory block into `event.retrievalContext.results` (direct-mode shards under budget, de-duplicated across turns per session; top-K `hybridSearch` over budget; channel origins always index/headings-only); runs for every origin that supplies a `retrievalContext`, including user-delegated subagents (researcher, reviewer) — but NOT TypeClaw-owned infrastructure turns (`system` origins and `system`-spawned subagents memory-logger/backup, plus the dreaming cron job matched by its `__plugin_memory_dreaming` job id), whose `userPrompt` is a fixed instruction block, not a user message (see [Internal-infrastructure turns skip retrieval](#internal-infrastructure-turns-skip-retrieval)). |
33
+ | Kind | Name | Notes |
34
+ | -------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
35
+ | Subagent | `memory-logger` | Reads a parent transcript past a watermark and appends fragments to `memory/streams/<today>.jsonl`. Coalesced per `agentDir`. |
36
+ | Subagent | `dreaming` | Reads shards under `memory/topics/` plus undreamed daily-stream events and rebalances the topic shards. Coalesced per `agentDir`. Citation-superset invariant enforced on every run. |
37
+ | Tool | `memory_search` | Main-agent tool. Pass `query` for phrase-first/token-fallback lexical search, or `topic` for exact slug lookup (not both). Searches topic shards, active cited-child provenance, undreamed streams, and references. Optional `workspace`, `chat`, and `thread` scopes apply to both query and exact-topic mode; legacy `where` aliases `chat`. Results include eligible active-child provenance. See [Provenance-aware recall](#provenance-aware-recall). |
38
+ | Tool | `delete_topic_shard` | Subagent-only (dreaming). Deletes a topic shard at `memory/topics/<slug>.md`. Path-guarded. |
39
+ | Cron | `__plugin_memory_dreaming` | `kind: 'prompt'`, `subagent: 'dreaming'`, scheduled per `memory.dreaming.schedule`. |
40
+ | Hook | `session.idle` | Per-session debouncer with size-based ceiling. Spawns `memory-logger` on idle or buffer-trip. |
41
+ | Hook | `session.end` | Spawns `memory-logger` immediately and clears per-session retrieval de-dup state. |
42
+ | Hook | `session.turn.start` | Renders the per-turn user-prompt memory block into `event.retrievalContext.results` (direct-mode shards under budget, de-duplicated across turns per session; top-K `hybridSearch` over budget; channel origins always index/headings-only); runs for every origin that supplies a `retrievalContext`, including user-delegated subagents (researcher, reviewer) — but NOT TypeClaw-owned infrastructure turns (`system` origins and `system`-spawned subagents memory-logger/backup, plus the dreaming cron job matched by its `__plugin_memory_dreaming` job id), whose `userPrompt` is a fixed instruction block, not a user message (see [Internal-infrastructure turns skip retrieval](#internal-infrastructure-turns-skip-retrieval)). |
43
+
44
+ ## Provenance-aware recall
45
+
46
+ Fragments can carry runtime-stamped `where` coordinates (`adapter`, workspace/chat/thread IDs, captured names, and Discord parent-room metadata) plus an attributed `who`. A topic derives searchable provenance only from its **active** `fragments:` children. `superseded:` evidence is excluded, and unresolved citations remain explicit rather than receiving invented metadata. The same eligible children determine scope eligibility, lexical matching, and returned `provenance`, so a multi-workspace topic cannot return another workspace's child details through a scoped result.
47
+
48
+ `memory_search` accepts optional `workspace`, `chat`, and `thread` filters in query and exact-topic modes (`where` remains a `chat` alias). Matching is case-insensitive and accepts an optional leading `#` for names. Recall is globally visible by default across roles and origins. Provenance coordinates and captured names are additive lexical metadata rather than authorization inputs, and automatic hybrid retrieval or channel heading injection never derives a hidden scope from session ancestry.
49
+
50
+ When explicit filters are supplied, a topic remains eligible when any resolved active child matches every requested coordinate, and returned provenance contains only matching children. Undreamed streams use the same filters. References are excluded from scoped results because they have no workspace provenance; unscoped recall continues to include them.
51
+
52
+ Provenance participates only in lexical documents. It is never appended to `fragmentEmbeddableText` or topic vector passages, so origin changes cannot alter vector scores or consume the embedding budget. `hybridSearch` loads shards and streams once per call, derives the undreamed view from that corpus, and builds provenance from the same loaded data.
53
+
54
+ Historical stream JSONL stays append-only. Both Discord adapters run bounded, timeout-safe startup maintenance that resolves old ID-only guild/channel/thread coordinates into a process-local, bounded enrichment registry. The registry is rebuilt on every startup and never written to disk, eliminating sidecar path races entirely. Confirmed non-thread checks remain negatively cached for the process lifetime so they do not retry or starve the candidate batch. Names containing secrets, controls, bidi overrides, zero-width characters, Markdown prompt-shaping syntax, or excessive length are rejected. Resolver failures and timeouts degrade to raw-ID search. Search itself only reads local memory plus the in-memory registry and never performs network resolution.
43
55
 
44
56
  ## Memory injection (two-tier, topic shards only)
45
57
 
@@ -125,7 +137,7 @@ A `[dreaming] citation-superset violation: …` warning logs the dropped ids and
125
137
  ## Files on disk
126
138
 
127
139
  - **`memory/topics/<slug>.md`** — per-topic shards with YAML frontmatter (`heading`, `cites`, `days`, `lastReinforced`, `tags?`) + body markdown. Runtime owns the frontmatter (recomputed after every dreaming run from the body's citations); dreaming subagent writes body only. The body is a **compact belief record**: one belief sentence stating the current truth (subject + predicate + essential scope qualifier; the strength wording — "mentioned" / "consistently" / "always" — is calibrated from `days`), followed by the `fragments:` list (active evidence behind the belief) and an optional `superseded:` list (evidence overturned by a later contradiction — kept cited for GC/history but excluded from vector retrieval). One sentence (not a paragraph) keeps bodies small so more topics stay under the direct-injection budget; the citation lists are the only load-bearing part of the body, so the prose shape is free to be terse. Existing verbose shards are rewritten into this form by the next dreaming run (no migration).
128
- - **`memory/streams/yyyy-MM-dd.jsonl`** — daily fragment streams. One event per line, discriminated union of `fragment | watermark | legacy_prose`. Force-committed alongside the shards. A `fragment` event carries optional **situational provenance** for "who said what, where, and when": `who` (display name/handle of the attributed speaker, LLM-supplied per-fragment by `memory-logger` only when one transcript speaker clearly owns the evidence), `where` (`{ adapter, workspace, workspaceName?, chat, chatName?, thread }` — runtime-stamped from the session origin in the append tool, channel origins only), and `when` (reuses the existing `ts`). Both are optional, so legacy fragments and non-channel (TUI) origins parse with them absent. `who`/`where` are deliberately NOT in `fragmentContentHash` (dedup stays content-identity) and NOT in `fragmentEmbeddableText` (provenance is retrieval metadata, not embedded — it must not burn the 512-token budget or let same-room/same-person dominate recall). **Secret-scanning covers provenance too**: `who` (LLM-supplied) clears the same `detectSecrets` guard as `topic`/`body` and a credential-shaped value is refused with the retryable error; the origin-derived `where` names (`workspaceName`/`chatName`) are external channel data the agent can't rewrite, so a credential-shaped name is silently dropped (raw id kept) rather than wedging the logger. Raw ids are platform-issued identifiers, not free text, so they are not scanned. `where` is runtime-stamped rather than LLM-supplied because the channel is stable for a whole logger run; `who` is per-fragment because a single run spans many speakers and `origin.lastInboundAuthorId` is only the spawn-time one — auto-stamping it would misattribute fragments about earlier speakers. Surfaced to the agent (not embedded) via `memory_search` (`StreamMatch.who/when/where`), `hybridSearch` (`HybridSearchResult.who/when/where` on self-resolved undreamed fragments), and the per-turn retrieval render (`renderProvenanceLine` → `_Jisoo in #incidents on 2026-06-24_`).
140
+ - **`memory/streams/yyyy-MM-dd.jsonl`** — daily fragment streams. One event per line, discriminated union of `fragment | watermark | legacy_prose`. Force-committed alongside the shards. A `fragment` event carries optional **situational provenance** for "who said what, where, and when": `who` (display name/handle of the attributed speaker, LLM-supplied per-fragment by `memory-logger` only when one transcript speaker clearly owns the evidence), `where` (`{ adapter, workspace, workspaceName?, chat, chatName?, thread, parentChat?, parentChatName? }` — runtime-stamped from the session origin in the append tool, channel origins only), and `when` (reuses the existing `ts`). Both are optional, so legacy fragments and non-channel (TUI) origins parse with them absent. `who`/`where` are deliberately NOT in `fragmentContentHash` (dedup stays content-identity) and NOT in `fragmentEmbeddableText` (provenance is retrieval metadata, not embedded — it must not burn the 512-token budget or let same-room/same-person dominate recall). **Secret-scanning covers provenance too**: `who` (LLM-supplied) clears the same `detectSecrets` guard as `topic`/`body` and a credential-shaped value is refused with the retryable error; the origin-derived `where` names (`workspaceName`/`chatName`/`parentChatName`) are external channel data the agent can't rewrite, so a credential-shaped, overlong, or control-character-bearing name is silently dropped (raw id kept) rather than wedging the logger. Raw ids are platform-issued identifiers, not free text, so they are not scanned. `where` is runtime-stamped rather than LLM-supplied because the channel is stable for a whole logger run; `who` is per-fragment because a single run spans many speakers and `origin.lastInboundAuthorId` is only the spawn-time one — auto-stamping it would misattribute fragments about earlier speakers. Surfaced to the agent (not embedded) via `memory_search` (`StreamMatch.who/when/where`), `hybridSearch` (`HybridSearchResult.who/when/where` on self-resolved undreamed fragments), and the per-turn retrieval render (`renderProvenanceLine` → `_Jisoo in #incidents on 2026-06-24_`).
129
141
  - **`memory/MEMORY.md.pre-shard.bak`** — legacy pre-shard backup left by older TypeClaw versions. Safe to delete after verifying.
130
142
  - **`memory/skills/<name>/SKILL.md`** — muscle memory (Form A). Skills the dreaming subagent distills from repeated procedures. Auto-loaded as first-class skills. CLI/plugin suggestions (Forms B and C) are recorded as topic shards instead — see [Muscle memory](#muscle-memory-three-forms).
131
143
  - **`memory/references/<slug>.md`** — verbatim reference artifacts. Written by `store_reference`, a `memory-logger` custom tool that is always registered (there is no `references.enabled` config gate — references are unconditionally available; they simply stay empty until the `memory-logger` chooses to store one). A fragment may cite a stored reference via `append`'s `references: ['<slug>']`, but the append tool validates each slug against the references that actually exist on disk and silently drops the rest (`resolveValidReferences`), so a hallucinated slug never lands a dangling citation in the stream. A freshly stored reference is embedded into the vector index immediately via the `store_reference` on-write hook (`vector/reference-index-on-write.ts`), mirroring the stream-fragment on-write hook — so it is vector-retrievable within the same container uptime instead of only after the next startup index build. Chunks are derived by the same `referencePassagesForOne` the startup build uses, and re-storing a shorter body prunes the stale higher-index chunk rows.