typeclaw 0.39.7 → 0.40.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 (58) hide show
  1. package/package.json +1 -1
  2. package/scripts/dump-system-prompt.ts +4 -50
  3. package/src/agent/auth-reloadable.ts +24 -0
  4. package/src/agent/auth.ts +12 -0
  5. package/src/agent/index.ts +18 -58
  6. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +0 -2
  7. package/src/bundled-plugins/guard/policy.ts +0 -5
  8. package/src/bundled-plugins/memory/README.md +26 -37
  9. package/src/bundled-plugins/memory/index.ts +30 -144
  10. package/src/bundled-plugins/memory/load-memory.ts +7 -121
  11. package/src/bundled-plugins/memory/memory-logger.ts +8 -2
  12. package/src/bundled-plugins/memory/search-command.ts +2 -11
  13. package/src/bundled-plugins/memory/vector/doctor.ts +1 -1
  14. package/src/bundled-plugins/memory/vector/embedder.ts +4 -5
  15. package/src/bundled-plugins/memory/vector/hybrid.ts +47 -5
  16. package/src/bundled-plugins/memory/vector/relevance-gate.ts +11 -7
  17. package/src/bundled-plugins/memory/vector/script.ts +87 -0
  18. package/src/channels/adapters/describe-error.ts +40 -0
  19. package/src/channels/adapters/discord.ts +9 -12
  20. package/src/channels/adapters/kakaotalk.ts +14 -17
  21. package/src/channels/adapters/line.ts +11 -14
  22. package/src/channels/adapters/slack-bot.ts +15 -18
  23. package/src/channels/adapters/slack.ts +45 -21
  24. package/src/channels/adapters/telegram-bot.ts +15 -18
  25. package/src/channels/adapters/webex-bot.ts +13 -14
  26. package/src/channels/adapters/webex.ts +14 -15
  27. package/src/cli/compose.ts +20 -0
  28. package/src/cli/docker-preflight.ts +42 -0
  29. package/src/cli/hostd.ts +12 -3
  30. package/src/cli/init.ts +24 -22
  31. package/src/cli/logs.ts +7 -0
  32. package/src/cli/provider.ts +8 -1
  33. package/src/cli/reload.ts +6 -0
  34. package/src/cli/restart.ts +7 -0
  35. package/src/cli/shell.ts +7 -0
  36. package/src/cli/start.ts +7 -0
  37. package/src/cli/status.ts +9 -0
  38. package/src/cli/stop.ts +7 -0
  39. package/src/cli/tui.ts +6 -0
  40. package/src/config/config.ts +31 -8
  41. package/src/container/docker-app.ts +253 -0
  42. package/src/container/index.ts +11 -0
  43. package/src/container/start.ts +85 -41
  44. package/src/hostd/current-host-daemon.ts +21 -0
  45. package/src/hostd/daemon.ts +27 -3
  46. package/src/hostd/supervisor.ts +18 -3
  47. package/src/plugin/hooks.ts +3 -4
  48. package/src/plugin/types.ts +1 -1
  49. package/src/run/channel-session-factory.ts +3 -5
  50. package/src/run/index.ts +17 -16
  51. package/src/server/command-runner.ts +2 -11
  52. package/src/skills/typeclaw-memory/SKILL.md +2 -2
  53. package/src/skills/typeclaw-plugins/SKILL.md +1 -1
  54. package/typeclaw.schema.json +1 -23
  55. package/src/bundled-plugins/guard/policies/memory-retrieval-cache-write.ts +0 -43
  56. package/src/bundled-plugins/memory/memory-retrieval.ts +0 -111
  57. package/src/bundled-plugins/memory/vector/cache-write.ts +0 -19
  58. package/src/bundled-plugins/memory/vector/config.ts +0 -28
@@ -4,7 +4,7 @@ import { createServer, type Server, type Socket as NetSocket } from 'node:net'
4
4
  import { join } from 'node:path'
5
5
 
6
6
  import type { PortForward } from '@/config'
7
- import { defaultDockerExec, type DockerExec } from '@/container'
7
+ import { defaultDockerExec, type DockerExec, type HostDaemonRegisterPayload } from '@/container'
8
8
  import type { PortForwardEvent } from '@/portbroker'
9
9
  import {
10
10
  discordChannelBlockSchema,
@@ -17,6 +17,7 @@ import { SecretsBackend } from '@/secrets/storage'
17
17
  import { isWindows } from '@/shared'
18
18
 
19
19
  import { isDaemonReachable } from './client'
20
+ import type { CurrentHostDaemonHolder } from './current-host-daemon'
20
21
  import type { KakaoRenewalCallbacks, KakaoRenewalLogEvent } from './kakao-renewal-manager'
21
22
  import { ensureDirs, registrationFilePath, registrationsDir, socketPath } from './paths'
22
23
  import type {
@@ -71,6 +72,10 @@ export type DaemonOptions = {
71
72
  // ticks hourly because Webex password tokens live ~27h (see
72
73
  // webex-renewal-manager.ts). Omit when the agent has no webex channel.
73
74
  webexRenewal?: WebexRenewalCallbacks
75
+ // Populated once the daemon is booted so direct callers of the restart
76
+ // (the renewal callbacks in cli/hostd.ts) get the in-process registration
77
+ // path instead of the socket self-RPC. Omit in tests that don't exercise it.
78
+ currentHostDaemonHolder?: CurrentHostDaemonHolder
74
79
  }
75
80
 
76
81
  export type RestartPreflight = (input: {
@@ -400,7 +405,7 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
400
405
  }
401
406
  }
402
407
 
403
- const handleRegister = async (req: RegisterPayload): Promise<RpcResponse> => {
408
+ const registerContainer = async (req: RegisterPayload): Promise<RpcResponse> => {
404
409
  if (stopped) return { ok: false, reason: 'daemon stopping' }
405
410
  return runSerially(req.containerName, async () => {
406
411
  if (stopped) return { ok: false, reason: 'daemon stopping' }
@@ -417,6 +422,8 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
417
422
  })
418
423
  }
419
424
 
425
+ const handleRegister = async (req: RegisterPayload): Promise<RpcResponse> => registerContainer(req)
426
+
420
427
  const handleDeregister = async (req: { containerName: string }): Promise<RpcResponse> =>
421
428
  runSerially(req.containerName, async () => {
422
429
  const hadCwd = cwds.delete(req.containerName)
@@ -449,6 +456,17 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
449
456
  return { ok: true, result }
450
457
  }
451
458
 
459
+ // Lets the supervisor's restart re-register the child in-process instead of
460
+ // over the socket. Awaits restore for the same no-mutation-before-restore
461
+ // invariant the socket dispatcher enforces before handleRegister.
462
+ const registerCurrentChild = async (
463
+ payload: HostDaemonRegisterPayload,
464
+ ): Promise<{ ok: true } | { ok: false; reason: string }> => {
465
+ await awaitRestored()
466
+ const reply = await registerContainer(payload)
467
+ return reply.ok ? { ok: true } : { ok: false, reason: reply.reason }
468
+ }
469
+
452
470
  // Auth: only restart containers that registered with this daemon. The
453
471
  // socket is 0o600 + UID-bound, but inside a container any process that
454
472
  // reaches the mounted socket could otherwise restart any peer container on
@@ -465,7 +483,12 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
465
483
  ? await opts.restartPreflight({ containerName: req.containerName, cwd, build: req.build })
466
484
  : null
467
485
  if (preflight) return preflight
468
- const ack = supervisor.scheduleRestart({ containerName: req.containerName, cwd, build: req.build })
486
+ const ack = supervisor.scheduleRestart({
487
+ containerName: req.containerName,
488
+ cwd,
489
+ build: req.build,
490
+ currentHostDaemon: { httpPort, register: registerCurrentChild },
491
+ })
469
492
  if (!ack.ok) return ack
470
493
  const result: RestartResult = { containerName: req.containerName, scheduled: true }
471
494
  return { ok: true, result }
@@ -699,6 +722,7 @@ export async function startDaemon(opts: DaemonOptions = {}): Promise<Daemon> {
699
722
  }
700
723
  httpPort = httpServer.port ?? 0
701
724
  log({ kind: 'daemon-http-listening', host: httpHostname, port: httpPort })
725
+ opts.currentHostDaemonHolder?.set({ httpPort, register: registerCurrentChild })
702
726
 
703
727
  const sockets = new Set<NetSocket>()
704
728
  const listener = createServer((socket) => {
@@ -1,3 +1,5 @@
1
+ import type { CurrentHostDaemon } from '@/container'
2
+
1
3
  import type { Response } from './protocol'
2
4
 
3
5
  export type SupervisorRestart = (input: {
@@ -8,6 +10,9 @@ export type SupervisorRestart = (input: {
8
10
  // image even if it already exists. Default false matches the host-side
9
11
  // `typeclaw restart` (no `--build` flag) behavior.
10
12
  build?: boolean
13
+ // Injected by the daemon so the restart registers the container in-process
14
+ // instead of over the socket — see CurrentHostDaemon docs in src/container.
15
+ currentHostDaemon?: CurrentHostDaemon
11
16
  }) => Promise<{ ok: true } | { ok: false; reason: string }>
12
17
 
13
18
  export type SupervisorOptions = {
@@ -20,7 +25,12 @@ export type SupervisorLogEvent =
20
25
  | { kind: 'restart-failed'; containerName: string; reason: string }
21
26
 
22
27
  export type Supervisor = {
23
- scheduleRestart: (input: { containerName: string; cwd: string; build?: boolean }) => Response
28
+ scheduleRestart: (input: {
29
+ containerName: string
30
+ cwd: string
31
+ build?: boolean
32
+ currentHostDaemon?: CurrentHostDaemon
33
+ }) => Response
24
34
  }
25
35
 
26
36
  export type SupervisorBuildOptions = {
@@ -36,7 +46,7 @@ export type SupervisorBuildOptions = {
36
46
  // surfaced via the log channel; there is no connected client to receive them.
37
47
  export function buildSupervisor({ restart, onLog, isStopped }: SupervisorBuildOptions): Supervisor {
38
48
  return {
39
- scheduleRestart: ({ containerName, cwd, build = false }): Response => {
49
+ scheduleRestart: ({ containerName, cwd, build = false, currentHostDaemon }): Response => {
40
50
  if (isStopped()) return { ok: false, reason: 'daemon stopping' }
41
51
  onLog({ kind: 'restart-scheduled', containerName, build })
42
52
  void runRestart()
@@ -44,7 +54,12 @@ export function buildSupervisor({ restart, onLog, isStopped }: SupervisorBuildOp
44
54
 
45
55
  async function runRestart(): Promise<void> {
46
56
  try {
47
- const result = await restart({ containerName, cwd, build })
57
+ const result = await restart({
58
+ containerName,
59
+ cwd,
60
+ build,
61
+ ...(currentHostDaemon ? { currentHostDaemon } : {}),
62
+ })
48
63
  if (result.ok) onLog({ kind: 'restart-completed', containerName })
49
64
  else onLog({ kind: 'restart-failed', containerName, reason: result.reason })
50
65
  } catch (error) {
@@ -40,10 +40,9 @@ export const END_HANDLER_TIMEOUT_MS = 60_000
40
40
  // (loadSelf, loadMemory shard reads, prefetchChannelContext) before
41
41
  // ensureLive fires.
42
42
  //
43
- // The bundled memory plugin's session.prompt fires memory-retrieval
44
- // detached, so it returns in <1ms in steady state; this ceiling guards
45
- // third-party hooks that legitimately need to do work inline, AND a
46
- // regression in the memory plugin that re-introduces an inline await.
43
+ // The bundled memory plugin does per-turn retrieval from session.turn.start;
44
+ // this ceiling guards third-party hooks that legitimately need to do work
45
+ // inline, AND regressions that re-introduce expensive inline prompt work.
47
46
  export const PROMPT_HANDLER_TIMEOUT_MS = 20_000
48
47
 
49
48
  export type RegisteredHook<K extends keyof Hooks> = {
@@ -183,7 +183,7 @@ export type SessionTurnStartEvent = {
183
183
  userPrompt: string
184
184
  origin?: SessionOrigin
185
185
  // Mutable ref: plugin writes retrieval results here; server/router reads after hook returns.
186
- // Only populated when vector.enabled and injection plan is index mode.
186
+ // Populated when a turn driver supplies a retrieval context bag.
187
187
  retrievalContext?: { results: string }
188
188
  }
189
189
 
@@ -1,3 +1,5 @@
1
+ import { join } from 'node:path'
2
+
1
3
  import { SessionManager } from '@mariozechner/pi-coding-agent'
2
4
 
3
5
  import { createSession as defaultCreateSession } from '@/agent'
@@ -71,9 +73,6 @@ export type BuildChannelSessionFactoryDeps = {
71
73
  subagentRegistry?: SubagentRegistry
72
74
  getCreateSessionForSubagent?: () => CreateSessionForSubagent
73
75
  liveSessionRegistry?: LiveSessionRegistry
74
- // Forwarded to createSession: when true the `# Memory` section is omitted
75
- // from the system prompt (vector agents inject memory per-turn instead).
76
- suppressSystemMemory?: boolean
77
76
  }
78
77
 
79
78
  // Tight basename validation so a tampered or corrupt channels/sessions.json
@@ -141,7 +140,6 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
141
140
  ...(deps.getCreateSessionForSubagent !== undefined
142
141
  ? { createSessionForSubagent: deps.getCreateSessionForSubagent() }
143
142
  : {}),
144
- ...(deps.suppressSystemMemory !== undefined ? { suppressSystemMemory: deps.suppressSystemMemory } : {}),
145
143
  })
146
144
 
147
145
  const sessionId = sessionManager.getSessionId()
@@ -192,7 +190,7 @@ function tryReopenOrCreate(
192
190
  )
193
191
  return SessionManager.create(cwd, sessionDir)
194
192
  }
195
- const path = `${sessionDir}/${existingSessionFile}`
193
+ const path = join(sessionDir, existingSessionFile)
196
194
  if (capOptions !== null) {
197
195
  try {
198
196
  const stats = capJsonlFileInPlace(path, capOptions)
package/src/run/index.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { SessionManager } from '@mariozechner/pi-coding-agent'
2
2
 
3
3
  import { createSession, createSessionWithDispose } from '@/agent'
4
+ import { createProviderAuthReloadable } from '@/agent/auth-reloadable'
4
5
  import { LiveSessionRegistry } from '@/agent/live-sessions'
5
6
  import { LiveSubagentRegistry } from '@/agent/live-subagents'
6
7
  import { requestContainerRestart } from '@/agent/restart'
@@ -20,7 +21,6 @@ import {
20
21
  type SubagentShared,
21
22
  } from '@/agent/subagents'
22
23
  import { clearTodosForOrigin, markRestartAbortPendingForOrigin } from '@/agent/todo/continuation-wiring'
23
- import { vectorEnabledFromMemoryConfig } from '@/bundled-plugins/memory/vector/config'
24
24
  import { embed, warmEmbedder } from '@/bundled-plugins/memory/vector/embedder'
25
25
  import { buildStartupVectorIndex } from '@/bundled-plugins/memory/vector/startup'
26
26
  import { resolveCapOptionsFromConfig } from '@/bundled-plugins/tool-result-cap'
@@ -219,10 +219,6 @@ async function startAgentRuntime(
219
219
  onProcessGlobalsInstalled(disposeProcessGlobals)
220
220
 
221
221
  const { config: cwdConfig, pluginConfigs: pluginConfigsByName } = loadConfigBundleSync(cwd)
222
- // Vector agents omit the system-prompt `# Memory` section and inject memory
223
- // per-turn instead. Derived once here: `memory.vector.enabled` is
224
- // restart-required, so a single boot read is coherent for the process.
225
- const suppressSystemMemory = vectorEnabledFromMemoryConfig(pluginConfigsByName.memory)
226
222
  const githubTokenBridge = createGithubTokenBridge()
227
223
  const mcpManager =
228
224
  cwdConfig.mcpServers.length > 0 ? createMcpManager(cwdConfig.mcpServers, { env: process.env }) : null
@@ -256,7 +252,7 @@ async function startAgentRuntime(
256
252
  hasGithubAppTokenResolver: githubTokenBridge.hasAppTokenResolver,
257
253
  ...(cwdConfig.roles !== undefined ? { roles: cwdConfig.roles } : {}),
258
254
  })
259
- const vectorStartupPromise = suppressSystemMemory ? runVectorStartup(cwd) : Promise.resolve()
255
+ const vectorStartupPromise = runVectorStartup(cwd)
260
256
  let pluginsLoaded: LoadPluginsResult
261
257
  try {
262
258
  const [loaded] = await Promise.all([pluginsLoadedPromise, vectorStartupPromise])
@@ -368,7 +364,6 @@ async function startAgentRuntime(
368
364
  stream,
369
365
  reloadRegistry,
370
366
  pluginRuntime,
371
- suppressSystemMemory,
372
367
  getChannelRouter: () => channelManager.router,
373
368
  rehydrateCapOptions: resolveCapOptionsFromConfig(pluginConfigsByName['tool-result-cap']),
374
369
  permissions: pluginsLoaded.permissions,
@@ -612,7 +607,6 @@ async function startAgentRuntime(
612
607
  containerName: containerNameOpt.containerName,
613
608
  sessionFactory,
614
609
  channelRouter: channelManager.router,
615
- suppressSystemMemory,
616
610
  ...mcpManagerOpt,
617
611
  }),
618
612
  subagent: (subName: string, payload?: unknown) =>
@@ -653,7 +647,6 @@ async function startAgentRuntime(
653
647
  channelRouter: channelManager.router,
654
648
  origin: cronOrigin,
655
649
  permissions: pluginsLoaded.permissions,
656
- suppressSystemMemory,
657
650
  ...(refOverride !== undefined ? { refOverride } : {}),
658
651
  ...(snap.hasAnyPluginContent
659
652
  ? {
@@ -747,6 +740,17 @@ async function startAgentRuntime(
747
740
  })
748
741
  })
749
742
 
743
+ // Registered before channels so its cache clear lands before any channel
744
+ // session teardown observes it. secrets.json provider credentials are not
745
+ // part of the typeclaw.json config diff, so a rotated key takes effect on
746
+ // `typeclaw reload` only via this dedicated scope. Live sessions captured
747
+ // their AuthStorage at creation, so teardown recreates them with fresh auth.
748
+ reloadRegistry.register(
749
+ createProviderAuthReloadable({
750
+ onProviderAuthChanged: () => channelManager.router.tearDownAllLive(),
751
+ }),
752
+ )
753
+
750
754
  reloadRegistry.register(createChannelsReloadable({ manager: channelManager }))
751
755
 
752
756
  // Two-phase channel restart-resume around adapter startup, to close the race
@@ -786,12 +790,10 @@ async function startAgentRuntime(
786
790
  // In-flight coalescing for direct ctx.spawnSubagent calls mirrors the
787
791
  // SubagentConsumer's stream-path gate (subagents.ts:441). Two queued
788
792
  // `new-session` messages for the same (name, inFlightKey) drop the second
789
- // on the consumer side; without the same gate here, two consecutive
790
- // session.prompt fires (cold-start prompt N immediately followed by prompt
791
- // N+1 on the same channel session) could both fire memory-retrieval spawns
792
- // racing to write `memory/.retrieval-cache/<sessionId>.md`. Awaiting the
793
- // spawn in the hook used to mask this; now that the hook is fire-and-forget,
794
- // the race is exposed and the gate is mandatory.
793
+ // on the consumer side; without the same gate here, two consecutive direct
794
+ // plugin spawns with the same in-flight key could race. Awaiting the spawn in
795
+ // the hook used to mask this; detached hook paths expose the race and make the
796
+ // gate mandatory.
795
797
  //
796
798
  // Same key shape as the consumer: `${name}:${inFlightKey(payload)}` when the
797
799
  // subagent declares one, else just `${name}`. Collisions resolve cleanly
@@ -898,7 +900,6 @@ async function startAgentRuntime(
898
900
  outbound,
899
901
  sessionFactory,
900
902
  channelRouter: channelManager.router,
901
- suppressSystemMemory,
902
903
  ...mcpManagerOpt,
903
904
  })
904
905
 
@@ -58,10 +58,6 @@ export type CommandRunnerOptions = {
58
58
  // wire for the handler/command path.
59
59
  channelRouter: ChannelRouter | undefined
60
60
  mcpManager?: McpManager
61
- // When true, prompt sessions spawned here omit the system-prompt `# Memory`
62
- // section (vector agents inject memory per-turn). Forwarded to createSession
63
- // so command/handler sessions stay coherent with the rest of the runtime.
64
- suppressSystemMemory?: boolean
65
61
  }
66
62
 
67
63
  type CommandHandle = {
@@ -201,7 +197,6 @@ export function createCommandRunner(opts: CommandRunnerOptions): CommandRunner {
201
197
  signal: abortController.signal,
202
198
  sessionFactory: opts.sessionFactory,
203
199
  channelRouter: opts.channelRouter,
204
- ...(opts.suppressSystemMemory !== undefined ? { suppressSystemMemory: opts.suppressSystemMemory } : {}),
205
200
  ...(opts.mcpManager !== undefined ? { mcpManager: opts.mcpManager } : {}),
206
201
  }),
207
202
  subagent: (subName, payload) =>
@@ -388,7 +383,6 @@ export async function runPromptForCommand(args: {
388
383
  // so the spawned session exposes `channel_send`.
389
384
  channelRouter?: ChannelRouter
390
385
  mcpManager?: McpManager
391
- suppressSystemMemory?: boolean
392
386
  // Test seam for the agent-session boundary. Production passes the real
393
387
  // `createSessionWithDispose`; tests inject a fake to verify wiring
394
388
  // (specifically: the sessionManager handed off must be persisted, not
@@ -418,14 +412,11 @@ export async function runPromptForCommand(args: {
418
412
  ...(args.mcpManager !== undefined ? { mcpManager: args.mcpManager } : {}),
419
413
  ...(args.runtimeVersion !== undefined ? { runtimeVersion: args.runtimeVersion } : {}),
420
414
  ...(args.containerName !== undefined ? { containerName: args.containerName } : {}),
421
- ...(args.suppressSystemMemory !== undefined ? { suppressSystemMemory: args.suppressSystemMemory } : {}),
422
415
  })
423
416
  const detachAbort = bindSignalToSession(args.signal, session)
424
417
  // Mirror the other turn drivers (TUI/channel/cron/subagent): fire
425
- // session.turn.start with a retrievalContext so a vector agent — whose
426
- // system-prompt `# Memory` section is suppressed — gets its long-term memory
427
- // injected per-turn into the user prompt here too. Without this, command and
428
- // handler prompt sessions would have no memory at all under vector mode.
418
+ // session.turn.start with a retrievalContext so vector memory is injected
419
+ // per-turn into command and handler prompts too.
429
420
  const turnEvent = { sessionId, agentDir: args.agentDir, origin: args.origin }
430
421
  const retrievalContext = { results: '' }
431
422
  try {
@@ -9,9 +9,9 @@ The agent's long-term memory is sharded across files in `memory/topics/<slug>.md
9
9
 
10
10
  ## Reading
11
11
 
12
- The `# Memory` section comes from topic shards only. Undreamed daily-stream events are **not** injected — call `memory_search` when you need them. When total shard bytes are above the 16 KB injection budget (or when speaking in a channel), shard bodies are dropped — only the heading + `cites=N, days=N, lastReinforced=YYYY-MM-DD` shows; call `memory_search` to fetch the bodies you need. The same `memory_search` covers both surfaces (topic shards and undreamed stream events), so one tool call reaches everything.
12
+ The `# Memory` block is injected per turn into the user prompt; the system prompt never contains long-term memory; vector memory is always on. Undreamed daily-stream events are **not** dumped wholesale into prompts — use `memory_search` when you need them. When speaking in a channel, shard bodies are dropped and only headings/slugs show; call `memory_search` to fetch the bodies you need. The same `memory_search` covers both surfaces (topic shards and undreamed stream events), so one tool call reaches everything.
13
13
 
14
- **Where the `# Memory` section lives depends on `memory.vector.enabled`.** With vector **off** (default), it's part of the system prompt, snapshotted once at session creation. With vector **on**, it is removed from the system prompt and injected fresh into each **user turn** instead: under budget you get all shard bodies, over budget you get the top-K shards/fragments most relevant to the current message (hybrid vector + keyword search). This keeps the system-prompt cache prefix stable across a session and lets retrieval track the current topic instead of a stale session-start snapshot. Either way `memory_search` remains available on demand.
14
+ Under budget you get shard bodies de-duplicated across turns; over budget you get the top-K shards/fragments/references most relevant to the current message (hybrid vector + keyword search). This keeps the system-prompt cache prefix stable across a session and lets retrieval track the current topic instead of a stale session-start snapshot. `memory_search` remains available on demand.
15
15
 
16
16
  ## Writing
17
17
 
@@ -380,7 +380,7 @@ hooks: {
380
380
 
381
381
  The `prompt` field on `SessionPromptEvent` is the system prompt as it's being composed by `createResourceLoader` (`basePrompt + IDENTITY.md + SOUL.md`), NOT the user's most recent message. Reading it as if it were the user's prompt — and feeding it to a retrieval system, classifier, or LLM — will keyword-mine TypeClaw's framing prose (`TypeClaw`, `subagent`, `AGENTS.md`) on every session.
382
382
 
383
- If you want the **user's actual prompt** (their message text), subscribe to `session.turn.start` and read `event.userPrompt`. The bundled memory plugin's `memory-retrieval` subagent learned this the hard way; see `src/bundled-plugins/memory/index.ts`'s `session.turn.start` handler.
383
+ If you want the **user's actual prompt** (their message text), subscribe to `session.turn.start` and read `event.userPrompt`. The bundled memory plugin's per-turn retrieval uses this hook so it embeds the user's text instead of the assembling system prompt; see `src/bundled-plugins/memory/index.ts`'s `session.turn.start` handler.
384
384
 
385
385
  #### CRITICAL: `session.prompt` and provider prompt caching
386
386
 
@@ -2528,11 +2528,7 @@
2528
2528
  "bufferBytes": 500000,
2529
2529
  "injectionBudgetBytes": 16384,
2530
2530
  "minIdleDeltaLines": 3,
2531
- "spawnTimeoutMs": 50000,
2532
- "retrievalSpawnTimeoutMs": 30000,
2533
- "vector": {
2534
- "enabled": false
2535
- }
2531
+ "spawnTimeoutMs": 50000
2536
2532
  },
2537
2533
  "type": "object",
2538
2534
  "properties": {
@@ -2566,12 +2562,6 @@
2566
2562
  "minimum": 1,
2567
2563
  "maximum": 9007199254740991
2568
2564
  },
2569
- "retrievalSpawnTimeoutMs": {
2570
- "default": 30000,
2571
- "type": "integer",
2572
- "minimum": 1,
2573
- "maximum": 9007199254740991
2574
- },
2575
2565
  "dreaming": {
2576
2566
  "type": "object",
2577
2567
  "properties": {
@@ -2580,18 +2570,6 @@
2580
2570
  "minLength": 1
2581
2571
  }
2582
2572
  }
2583
- },
2584
- "vector": {
2585
- "default": {
2586
- "enabled": false
2587
- },
2588
- "type": "object",
2589
- "properties": {
2590
- "enabled": {
2591
- "default": false,
2592
- "type": "boolean"
2593
- }
2594
- }
2595
2573
  }
2596
2574
  }
2597
2575
  },
@@ -1,43 +0,0 @@
1
- import path from 'node:path'
2
-
3
- import type { SessionOrigin } from '@/agent/session-origin'
4
- import type { SecuritySeverity } from '@/bundled-plugins/security/permissions'
5
-
6
- export const GUARD_MEMORY_RETRIEVAL_CACHE_WRITE = 'memoryRetrievalCacheWrite'
7
- export const GUARD_MEMORY_RETRIEVAL_CACHE_WRITE_SEVERITY: SecuritySeverity = 'low'
8
-
9
- const SESSION_ID_REGEX = /^[A-Za-z0-9._-]{1,128}$/
10
-
11
- export async function isMemoryRetrievalCacheWriteAllowed(options: {
12
- tool: string
13
- args: Record<string, unknown>
14
- agentDir: string
15
- origin?: SessionOrigin
16
- }): Promise<boolean> {
17
- const { tool, args, agentDir, origin } = options
18
- if (tool !== 'write') return false
19
- // Allow the memory-retrieval subagent (existing path) OR the in-process
20
- // vector retrieval writer (system origin with component='memory-retrieval').
21
- // The in-process path runs under the session origin, not a subagent, so we
22
- // check for the system component name as the trusted internal actor.
23
- const isMemoryRetrievalSubagent = origin?.kind === 'subagent' && origin.subagent === 'memory-retrieval'
24
- const isInProcessWriter = origin?.kind === 'system' && origin.component === 'memory-retrieval'
25
- if (!isMemoryRetrievalSubagent && !isInProcessWriter) return false
26
-
27
- const rawPath = args.path
28
- if (typeof rawPath !== 'string') return false
29
-
30
- const targetPath = path.resolve(agentDir, rawPath)
31
- const expectedDir = path.resolve(agentDir, 'memory', '.retrieval-cache')
32
- const relative = path.relative(expectedDir, targetPath)
33
- if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) return false
34
-
35
- const parts = relative.split(path.sep).filter(Boolean)
36
- if (parts.length !== 1) return false
37
-
38
- const fileName = parts[0]!
39
- if (!fileName.endsWith('.md')) return false
40
-
41
- const sessionId = fileName.slice(0, -3)
42
- return SESSION_ID_REGEX.test(sessionId)
43
- }
@@ -1,111 +0,0 @@
1
- import { z } from 'zod'
2
-
3
- import { lsTool, readTool, type Subagent, writeTool } from '@/plugin'
4
-
5
- import { createMemorySearchTool } from './search-tool'
6
-
7
- export const memoryRetrievalPayloadSchema = z.object({
8
- parentSessionId: z.string().min(1),
9
- agentDir: z.string().min(1),
10
- recentPrompt: z.string(),
11
- cacheFilePath: z.string().min(1),
12
- origin: z.unknown().optional(),
13
- })
14
-
15
- export type MemoryRetrievalPayload = z.infer<typeof memoryRetrievalPayloadSchema>
16
-
17
- export function isMemoryRetrievalPayload(value: unknown): value is MemoryRetrievalPayload {
18
- return memoryRetrievalPayloadSchema.safeParse(value).success
19
- }
20
-
21
- export type MemoryRetrievalLogger = {
22
- info: (msg: string) => void
23
- warn: (msg: string) => void
24
- error: (msg: string) => void
25
- }
26
-
27
- export type CreateMemoryRetrievalSubagentOptions = {
28
- logger?: MemoryRetrievalLogger
29
- timeoutMs?: number
30
- }
31
-
32
- export const MEMORY_RETRIEVAL_SYSTEM_PROMPT = `You are the memory-retrieval subagent. Read the user's most recent prompt and decide what's relevant across topic shards in \`memory/topics/\` (consolidated long-term memory), references in \`memory/references/\` (verbatim artifacts), AND undreamed daily-stream events under \`memory/streams/\` (recent fragments not yet folded into shards). Use \`memory_search\` to query all three surfaces; use \`read\`/\`ls\` to pull full shard bodies when needed. Synthesize a focused ≤8 KB summary of the relevant memory. Save by \`write\`ing it to the exact path provided in your payload as \`cacheFilePath\`. Be ruthlessly concise. Do NOT write anywhere else. Do NOT delete files.
33
-
34
- Search discipline: issue ALL your \`memory_search\` queries in a SINGLE response as parallel tool calls (up to 3 at once), then wait for every result before deciding what to do next. Different angles in parallel, NEVER one search per turn — sequential searches waste a full LLM round-trip per query (~3s each) on file I/O that takes milliseconds. Pick queries that match the user's literal phrasing — not framing vocabulary, not metadata (session ids, dates), not words from your own system prompt. If the parallel batch turns up nothing relevant, write the empty-context note and stop.`
35
-
36
- export function memoryRetrievalExhaustedMessage(used: number, max: number): string {
37
- const usedKb = Math.round(used / 1024)
38
- const maxKb = Math.round(max / 1024)
39
- return [
40
- `[memory-retrieval budget exhausted: used ${usedKb}KB of ${maxKb}KB across memory_search and read]`,
41
- '',
42
- 'Stop searching. Stop reading. Every subsequent memory_search or read call will return this same notice.',
43
- 'Write the cache file at the provided cacheFilePath with whatever relevant memory you have already gathered.',
44
- 'If nothing was relevant, write a short empty-context note to the cache file and stop.',
45
- ].join('\n')
46
- }
47
-
48
- const consoleLogger: MemoryRetrievalLogger = {
49
- info: (m) => console.warn(m),
50
- warn: (m) => console.warn(m),
51
- error: (m) => console.error(m),
52
- }
53
-
54
- export function createMemoryRetrievalSubagent(
55
- options: CreateMemoryRetrievalSubagentOptions = {},
56
- ): Subagent<MemoryRetrievalPayload> {
57
- const logger = options.logger ?? consoleLogger
58
- return {
59
- systemPrompt: MEMORY_RETRIEVAL_SYSTEM_PROMPT,
60
- // Retrieval is "4 keyword searches + 1 write" — no reasoning required.
61
- // `fast` falls back to `default` (with a one-time warning) when the
62
- // operator hasn't configured it, so this is safe by construction.
63
- profile: 'fast',
64
- tools: [readTool, writeTool, lsTool],
65
- customTools: [createMemorySearchTool()],
66
- payloadSchema: memoryRetrievalPayloadSchema,
67
- inFlightKey: (payload) => payload.parentSessionId,
68
- ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
69
- // 256 KB read + memory_search budget. Sized for one retrieval pass:
70
- // ~16 KB of memory_search hits (3 queries × ~5 KB excerpts) plus a few
71
- // shard reads (~5 KB each). A smaller budget would systematically
72
- // exhaust on any agent with rich memory; a larger budget invites the
73
- // pre-fix failure mode where the LLM kept iterating searches until it
74
- // gave up. The exhausted-message tells the subagent to write the
75
- // cache file with what it has rather than retrying forever.
76
- toolResultBudget: {
77
- maxTotalBytes: 256 * 1024,
78
- toolNames: ['read', 'memory_search'],
79
- exhaustedMessage: memoryRetrievalExhaustedMessage,
80
- },
81
- handler: async (ctx, runSession) => {
82
- const start = Date.now()
83
- logger.info(`[memory-retrieval] ${ctx.payload.parentSessionId} start cache=${ctx.payload.cacheFilePath}`)
84
- try {
85
- await runSession({ userPrompt: buildInitialPrompt(ctx.payload) })
86
- logger.info(`[memory-retrieval] ${ctx.payload.parentSessionId} done elapsed_ms=${Date.now() - start}`)
87
- } catch (err) {
88
- const message = err instanceof Error ? err.message : String(err)
89
- logger.warn(
90
- `[memory-retrieval] ${ctx.payload.parentSessionId}: run threw: ${message} elapsed_ms=${Date.now() - start}`,
91
- )
92
- throw err
93
- }
94
- },
95
- }
96
- }
97
-
98
- function buildInitialPrompt(payload: MemoryRetrievalPayload): string {
99
- return [
100
- `Parent session: ${payload.parentSessionId}`,
101
- `Agent folder: ${payload.agentDir}`,
102
- `Recent user prompt: ${payload.recentPrompt}`,
103
- `Topic shard directory: memory/topics/`,
104
- `Daily-stream directory: memory/streams/`,
105
- `Cache output path: ${payload.cacheFilePath}`,
106
- '',
107
- 'Use `memory_search` to find relevant material across BOTH topic shards and undreamed stream events (results are discriminated by `source: "topic" | "stream"`). Read any shard whose body you need in full via `read`. Write one concise retrieval summary to the cache output path exactly as provided. Keep the file ≤8 KB. If nothing is relevant, write a short empty-context note to the cache output path. Do not write any other path.',
108
- ].join('\n')
109
- }
110
-
111
- export const memoryRetrievalSubagent: Subagent<MemoryRetrievalPayload> = createMemoryRetrievalSubagent()
@@ -1,19 +0,0 @@
1
- import { mkdir, writeFile, rename } from 'node:fs/promises'
2
- import { join } from 'node:path'
3
-
4
- /**
5
- * Atomically write retrieval cache to memory/.retrieval-cache/<sessionId>.md
6
- * using tmp+rename pattern for crash safety.
7
- */
8
- export async function writeRetrievalCache(agentDir: string, sessionId: string, content: string): Promise<void> {
9
- const cacheDir = join(agentDir, 'memory', '.retrieval-cache')
10
- const cachePath = join(cacheDir, `${sessionId}.md`)
11
- const tmpPath = `${cachePath}.tmp`
12
-
13
- // Create directory if it doesn't exist
14
- await mkdir(cacheDir, { recursive: true })
15
-
16
- // Write to tmp file, then atomically rename
17
- await writeFile(tmpPath, content, 'utf8')
18
- await rename(tmpPath, cachePath)
19
- }
@@ -1,28 +0,0 @@
1
- import { z } from 'zod'
2
-
3
- import { loadPluginConfigsSync } from '@/config'
4
-
5
- export const vectorConfigSchema = z
6
- .object({
7
- enabled: z.boolean().default(false),
8
- })
9
- .default({ enabled: false })
10
-
11
- export type VectorConfig = z.infer<typeof vectorConfigSchema>
12
-
13
- // Fails closed to `false`: a memory block we can't parse is treated as opted
14
- // out. Shared by the host-side download gate and the runtime's per-turn vs
15
- // system-prompt memory-injection decision, so both read the flag identically.
16
- export function vectorEnabledFromMemoryConfig(memory: unknown): boolean {
17
- if (typeof memory !== 'object' || memory === null) return false
18
- const parsed = vectorConfigSchema.safeParse((memory as Record<string, unknown>).vector)
19
- return parsed.success && parsed.data.enabled
20
- }
21
-
22
- export function agentUsesVector(cwd: string): boolean {
23
- try {
24
- return vectorEnabledFromMemoryConfig(loadPluginConfigsSync(cwd).memory)
25
- } catch {
26
- return false
27
- }
28
- }