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.
- package/README.md +1 -1
- package/package.json +2 -1
- package/src/agent/git-nudge.ts +2 -1
- package/src/agent/index.ts +44 -30
- package/src/agent/live-subagents.ts +18 -0
- package/src/agent/multimodal/index.ts +1 -1
- package/src/agent/multimodal/look-at.ts +78 -44
- package/src/agent/multimodal/looker.ts +151 -39
- package/src/agent/network/response-body.ts +26 -0
- package/src/agent/network/safe-http.ts +198 -0
- package/src/agent/plugin-tools.ts +379 -157
- package/src/agent/provider-error.ts +52 -1
- package/src/agent/restart/index.ts +61 -40
- package/src/agent/restart-handoff/index.ts +73 -4
- package/src/agent/reviewer-bash-policy.ts +42 -1
- package/src/agent/session-origin.ts +2 -0
- package/src/agent/subagent-drain.ts +117 -7
- package/src/agent/subagents.ts +49 -16
- package/src/agent/throttle-circuit.ts +25 -5
- package/src/agent/tool-error-remediation.ts +72 -0
- package/src/agent/tool-file-safety.ts +1050 -0
- package/src/agent/tools/channel-fetch-attachment.ts +10 -3
- package/src/agent/tools/ddg.ts +16 -2
- package/src/agent/tools/post-github-review.ts +199 -0
- package/src/agent/tools/spawn-subagent.ts +21 -18
- package/src/agent/tools/webfetch/fetch.ts +143 -183
- package/src/agent/tools/webfetch/tool.ts +2 -3
- package/src/agent/tools/websearch.ts +23 -2
- package/src/agent/tools-without-local-file-operands.ts +27 -0
- package/src/agent/turn-runner.ts +86 -6
- package/src/bundled-plugins/backup/index.ts +2 -1
- package/src/bundled-plugins/backup/runner.ts +2 -1
- package/src/bundled-plugins/doc-render/render.ts +93 -12
- package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
- package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
- package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
- package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
- package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
- package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
- package/src/bundled-plugins/memory/README.md +23 -11
- package/src/bundled-plugins/memory/append-tool.ts +15 -8
- package/src/bundled-plugins/memory/citations.ts +22 -9
- package/src/bundled-plugins/memory/dreaming.ts +13 -8
- package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
- package/src/bundled-plugins/memory/index.ts +0 -4
- package/src/bundled-plugins/memory/load-memory.ts +8 -3
- package/src/bundled-plugins/memory/provenance-index.ts +717 -0
- package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
- package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
- package/src/bundled-plugins/memory/search-tool.ts +163 -60
- package/src/bundled-plugins/memory/stream-events.ts +2 -0
- package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
- package/src/bundled-plugins/researcher/write-report.ts +6 -3
- package/src/bundled-plugins/reviewer/index.ts +2 -2
- package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
- package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
- package/src/bundled-plugins/scout/scout.ts +8 -0
- package/src/bundled-plugins/security/index.ts +4 -4
- package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
- package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
- package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
- package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
- package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
- package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
- package/src/channels/adapters/discord-bot.ts +66 -6
- package/src/channels/adapters/discord-channel-resolver.ts +91 -23
- package/src/channels/adapters/discord-id.ts +4 -0
- package/src/channels/adapters/discord-resolver-cache.ts +41 -0
- package/src/channels/adapters/discord.ts +57 -7
- package/src/channels/adapters/github/auth-app.ts +41 -12
- package/src/channels/adapters/github/index.ts +23 -11
- package/src/channels/adapters/github/review-submitter.ts +302 -0
- package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
- package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
- package/src/channels/adapters/kakaotalk-typing.ts +17 -15
- package/src/channels/adapters/slack-attachment-download.ts +71 -0
- package/src/channels/adapters/slack-bot.ts +19 -8
- package/src/channels/adapters/slack-classify.ts +21 -2
- package/src/channels/adapters/slack.ts +59 -7
- package/src/channels/adapters/telegram-bot.ts +18 -5
- package/src/channels/adapters/webex-bot.ts +8 -3
- package/src/channels/adapters/webex.ts +8 -3
- package/src/channels/fetch-attachment.ts +43 -0
- package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
- package/src/channels/github-token-bridge.ts +10 -3
- package/src/channels/manager.ts +9 -0
- package/src/channels/router.ts +248 -6
- package/src/channels/types.ts +28 -1
- package/src/cli/channel.ts +1 -1
- package/src/cli/init.ts +1 -1
- package/src/cli/model.ts +57 -7
- package/src/compose/stop.ts +17 -5
- package/src/config/config.ts +6 -6
- package/src/config/models-mutation.ts +13 -1
- package/src/config/providers.ts +176 -0
- package/src/container/start.ts +49 -10
- package/src/doctor/checks.ts +3 -1
- package/src/doctor/commit.ts +2 -1
- package/src/doctor/file-ownership.ts +52 -0
- package/src/dreams/git.ts +2 -1
- package/src/git/hookless.ts +5 -0
- package/src/git/reconcile-ignored.ts +18 -5
- package/src/git/secret-history.ts +371 -0
- package/src/git/system-commit.ts +12 -6
- package/src/init/dockerfile.ts +86 -5
- package/src/init/index.ts +17 -5
- package/src/init/models-dev.ts +4 -0
- package/src/init/validate-api-key.ts +2 -0
- package/src/mcp/tools.ts +16 -3
- package/src/permissions/builtins.ts +3 -1
- package/src/plugin/context.ts +2 -0
- package/src/plugin/index.ts +1 -0
- package/src/plugin/manager.ts +4 -0
- package/src/plugin/types.ts +21 -0
- package/src/run/index.ts +40 -0
- package/src/run/llm-fetch-observer.ts +41 -4
- package/src/sandbox/build.ts +37 -15
- package/src/sandbox/canonical-secrets.ts +18 -0
- package/src/sandbox/env-exposure.ts +80 -0
- package/src/sandbox/errors.ts +13 -6
- package/src/sandbox/hidden-paths.ts +102 -44
- package/src/sandbox/index.ts +22 -4
- package/src/sandbox/package-install.ts +3 -27
- package/src/sandbox/policy.ts +11 -25
- package/src/sandbox/privileged-runtime.ts +255 -0
- package/src/sandbox/session-tmp.ts +8 -2
- package/src/sandbox/writable-zones.ts +204 -140
- package/src/secrets/index.ts +8 -0
- package/src/secrets/refresh-provider-oauth.ts +128 -0
- package/src/server/command-runner.ts +48 -4
- package/src/server/index.ts +4 -0
- package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
- package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
- package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
- package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
- package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
- package/src/skills/typeclaw-config/SKILL.md +5 -5
- package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
- package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
- package/src/skills/typeclaw-memory/SKILL.md +9 -3
- package/src/skills/typeclaw-permissions/SKILL.md +19 -15
- 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 {
|
|
9
|
-
|
|
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
|
-
//
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
//
|
|
24
|
-
//
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
-
|
|
69
|
-
resolveEffectiveApproval: createGithubEffectiveApprovalResolver({
|
|
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
|
-
|
|
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
|
|
187
|
-
//
|
|
188
|
-
//
|
|
189
|
-
//
|
|
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
|
-
//
|
|
198
|
-
//
|
|
199
|
-
//
|
|
200
|
-
|
|
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:
|
|
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(
|
|
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
|
-
|
|
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
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
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({
|
|
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`
|
|
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.
|