typeclaw 0.50.0 → 0.52.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 (258) hide show
  1. package/dist/types/agent/bash-sandbox-env.d.ts +17 -0
  2. package/dist/types/agent/bash-sandbox-proc.d.ts +8 -0
  3. package/dist/types/agent/bash-sandbox.d.ts +98 -0
  4. package/dist/types/agent/compaction.d.ts +4 -4
  5. package/dist/types/agent/idle-compaction.d.ts +1 -0
  6. package/dist/types/agent/index.d.ts +10 -17
  7. package/dist/types/agent/multimodal/look-at.d.ts +1 -1
  8. package/dist/types/agent/output-allowance.d.ts +4 -0
  9. package/dist/types/agent/plugin-tools.d.ts +8 -75
  10. package/dist/types/agent/prompt-cache-key.d.ts +1 -0
  11. package/dist/types/agent/session-tail.d.ts +12 -0
  12. package/dist/types/agent/subagents.d.ts +5 -0
  13. package/dist/types/agent/system-prompt-composition.d.ts +18 -0
  14. package/dist/types/agent/system-prompt.d.ts +2 -0
  15. package/dist/types/agent/tools/channel-disengage.d.ts +1 -1
  16. package/dist/types/agent/tools/channel-edit.d.ts +1 -1
  17. package/dist/types/agent/tools/channel-fetch-attachment.d.ts +1 -1
  18. package/dist/types/agent/tools/channel-handoff.d.ts +1 -1
  19. package/dist/types/agent/tools/channel-history.d.ts +1 -1
  20. package/dist/types/agent/tools/channel-react.d.ts +1 -1
  21. package/dist/types/agent/tools/channel-read.d.ts +10 -2
  22. package/dist/types/agent/tools/channel-reply.d.ts +1 -1
  23. package/dist/types/agent/tools/channel-send.d.ts +1 -1
  24. package/dist/types/agent/tools/channel-session-search.d.ts +1 -1
  25. package/dist/types/agent/tools/ddg.d.ts +9 -0
  26. package/dist/types/agent/tools/grant-role.d.ts +1 -1
  27. package/dist/types/agent/tools/post-github-review.d.ts +1 -1
  28. package/dist/types/agent/tools/restart.d.ts +1 -1
  29. package/dist/types/agent/tools/skip-response.d.ts +1 -1
  30. package/dist/types/agent/tools/spawn-subagent.d.ts +2 -1
  31. package/dist/types/agent/tools/stream-snapshot.d.ts +2 -2
  32. package/dist/types/agent/tools/subagent-cancel.d.ts +1 -1
  33. package/dist/types/agent/tools/subagent-output.d.ts +1 -1
  34. package/dist/types/agent/tools/todo/index.d.ts +1 -1
  35. package/dist/types/agent/tools/webfetch/adaptive-html.d.ts +3 -3
  36. package/dist/types/agent/tools/webfetch/strategies/readability-process.d.ts +48 -0
  37. package/dist/types/agent/tools/webfetch/tool.d.ts +2 -2
  38. package/dist/types/agent/tools/websearch.d.ts +1 -1
  39. package/dist/types/channels/adapters/github/auth-app.d.ts +25 -0
  40. package/dist/types/channels/adapters/github/auth-pat.d.ts +17 -0
  41. package/dist/types/channels/adapters/github/auth.d.ts +24 -0
  42. package/dist/types/channels/github-review-check.d.ts +1 -1
  43. package/dist/types/channels/github-token-bridge.d.ts +4 -0
  44. package/dist/types/channels/lost-background-context.d.ts +2 -0
  45. package/dist/types/channels/persistence.d.ts +1 -0
  46. package/dist/types/channels/router.d.ts +16 -50
  47. package/dist/types/channels/types.d.ts +1 -0
  48. package/dist/types/coding-agent/tool.d.ts +1 -1
  49. package/dist/types/config/config.d.ts +22 -0
  50. package/dist/types/config/providers.d.ts +50 -1
  51. package/dist/types/container/start.d.ts +1 -0
  52. package/dist/types/eval/cell.d.ts +26 -0
  53. package/dist/types/eval/config.d.ts +19 -0
  54. package/dist/types/eval/dispatch.d.ts +7 -0
  55. package/dist/types/eval/kernel.d.ts +28 -0
  56. package/dist/types/eval/process.d.ts +23 -0
  57. package/dist/types/eval/protocol.d.ts +34 -0
  58. package/dist/types/eval/sandbox.d.ts +12 -0
  59. package/dist/types/eval/tool.d.ts +17 -0
  60. package/dist/types/eval/wire.d.ts +33 -0
  61. package/dist/types/git/resolve-identity.d.ts +2 -0
  62. package/dist/types/init/dockerfile.d.ts +1 -0
  63. package/dist/types/init/gitignore.d.ts +1 -1
  64. package/dist/types/permissions/builtins.d.ts +1 -0
  65. package/dist/types/plugin/types.d.ts +3 -0
  66. package/dist/types/sandbox/canonical-secrets.d.ts +2 -2
  67. package/dist/types/sandbox/coding-agent.d.ts +1 -1
  68. package/dist/types/sandbox/dependency-bins.d.ts +1 -0
  69. package/dist/types/sandbox/dev-source.d.ts +2 -2
  70. package/dist/types/sandbox/env-exposure.d.ts +2 -0
  71. package/dist/types/sandbox/hidden-paths.d.ts +1 -0
  72. package/dist/types/sandbox/index.d.ts +1 -1
  73. package/dist/types/sandbox/policy.d.ts +3 -0
  74. package/dist/types/typevault/cli-path.d.ts +2 -0
  75. package/dist/types/typevault/envelope-store.d.ts +11 -0
  76. package/dist/types/typevault/lifecycle.d.ts +13 -0
  77. package/dist/types/typevault/vault.d.ts +27 -0
  78. package/package.json +8 -7
  79. package/scripts/test.ts +252 -0
  80. package/src/agent/bash-sandbox-env.ts +136 -0
  81. package/src/agent/bash-sandbox-proc.ts +70 -0
  82. package/src/agent/bash-sandbox.ts +239 -0
  83. package/src/agent/compaction.ts +22 -10
  84. package/src/agent/idle-compaction.ts +7 -3
  85. package/src/agent/index.ts +185 -187
  86. package/src/agent/multimodal/look-at.ts +1 -1
  87. package/src/agent/output-allowance.ts +7 -0
  88. package/src/agent/plugin-tools.ts +64 -380
  89. package/src/agent/prompt-cache-key.ts +26 -3
  90. package/src/agent/session-origin.ts +41 -19
  91. package/src/agent/session-tail.ts +28 -0
  92. package/src/agent/subagent-completion-reminder.ts +2 -2
  93. package/src/agent/subagents.ts +21 -2
  94. package/src/agent/system-prompt-composition.ts +159 -0
  95. package/src/agent/system-prompt.ts +43 -5
  96. package/src/agent/todo/scope.ts +1 -1
  97. package/src/agent/tool-error-remediation.ts +18 -3
  98. package/src/agent/tools/channel-disengage.ts +1 -1
  99. package/src/agent/tools/channel-edit.ts +1 -1
  100. package/src/agent/tools/channel-fetch-attachment.ts +1 -1
  101. package/src/agent/tools/channel-handoff.ts +3 -2
  102. package/src/agent/tools/channel-history.ts +2 -1
  103. package/src/agent/tools/channel-react.ts +1 -1
  104. package/src/agent/tools/channel-read.ts +36 -3
  105. package/src/agent/tools/channel-reply.ts +1 -1
  106. package/src/agent/tools/channel-send.ts +4 -3
  107. package/src/agent/tools/channel-session-search.ts +13 -4
  108. package/src/agent/tools/ddg.ts +71 -11
  109. package/src/agent/tools/grant-role.ts +1 -1
  110. package/src/agent/tools/post-github-review.ts +1 -1
  111. package/src/agent/tools/restart.ts +1 -1
  112. package/src/agent/tools/skip-response.ts +1 -1
  113. package/src/agent/tools/spawn-subagent.ts +15 -1
  114. package/src/agent/tools/stream-snapshot.ts +1 -1
  115. package/src/agent/tools/subagent-cancel.ts +1 -1
  116. package/src/agent/tools/subagent-output.ts +1 -1
  117. package/src/agent/tools/todo/index.ts +1 -1
  118. package/src/agent/tools/webfetch/adaptive-html.ts +6 -4
  119. package/src/agent/tools/webfetch/strategies/readability-child.ts +25 -0
  120. package/src/agent/tools/webfetch/strategies/readability-process.ts +185 -0
  121. package/src/agent/tools/webfetch/tool.ts +6 -5
  122. package/src/agent/tools/websearch.ts +1 -1
  123. package/src/agent/tools-without-local-file-operands.ts +4 -0
  124. package/src/browser/dockerfile.ts +1 -1
  125. package/src/browser/fill-secret.ts +364 -0
  126. package/src/browser/registry.ts +6 -6
  127. package/src/bundled-plugins/agent-messenger-cli-auth/command.ts +211 -0
  128. package/src/bundled-plugins/agent-messenger-cli-auth/index.ts +186 -0
  129. package/src/bundled-plugins/backup/index.ts +17 -2
  130. package/src/bundled-plugins/backup/runner.ts +37 -2
  131. package/src/bundled-plugins/browser-agent/browser-agent.ts +51 -14
  132. package/src/bundled-plugins/browser-agent/index.ts +12 -5
  133. package/src/bundled-plugins/explorer/explorer.ts +1 -1
  134. package/src/bundled-plugins/github-cli-auth/gh-review-detect.ts +40 -16
  135. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +12 -7
  136. package/src/bundled-plugins/github-cli-auth/index.ts +10 -1
  137. package/src/bundled-plugins/managed-browser/index.ts +130 -2
  138. package/src/bundled-plugins/managed-browser/skills/browserskill/browserskill/SKILL.md +13 -5
  139. package/src/bundled-plugins/managed-browser/skills/omowright/omowright/SKILL.md +56 -5
  140. package/src/bundled-plugins/memory/README.md +23 -2
  141. package/src/bundled-plugins/memory/append-fragment.ts +133 -0
  142. package/src/bundled-plugins/memory/append-tool.ts +80 -149
  143. package/src/bundled-plugins/memory/dreaming.ts +6 -1
  144. package/src/bundled-plugins/memory/index.ts +33 -6
  145. package/src/bundled-plugins/memory/load-memory.ts +2 -4
  146. package/src/bundled-plugins/memory/memory-logger.ts +200 -6
  147. package/src/bundled-plugins/memory/references/store-reference-tool.ts +56 -32
  148. package/src/bundled-plugins/memory/remember-tool.ts +81 -0
  149. package/src/bundled-plugins/memory/search-tool-hybrid.ts +91 -0
  150. package/src/bundled-plugins/memory/search-tool.ts +58 -12
  151. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  152. package/src/bundled-plugins/memory/transcript-cursor.ts +30 -0
  153. package/src/bundled-plugins/memory/transcript-preload.ts +208 -0
  154. package/src/bundled-plugins/memory/transcript-view.ts +36 -0
  155. package/src/bundled-plugins/memory/vector/hybrid.ts +25 -14
  156. package/src/bundled-plugins/memory/watermark.ts +19 -10
  157. package/src/bundled-plugins/reviewer/reviewer.ts +20 -0
  158. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +3 -6
  159. package/src/bundled-plugins/security/policies/outbound-text.ts +20 -0
  160. package/src/bundled-plugins/security/policies/private-surface-read.ts +166 -201
  161. package/src/bundled-plugins/security/policies/system-prompt-leak.ts +2 -7
  162. package/src/bundled-plugins/typevault/grants.ts +119 -0
  163. package/src/bundled-plugins/typevault/index.ts +152 -0
  164. package/src/bundled-plugins/typevault/request.ts +87 -0
  165. package/src/bundled-plugins/typevault/runtime.ts +45 -0
  166. package/src/bundled-plugins/typevault/skills/typevault/SKILL.md +65 -0
  167. package/src/channels/adapter-halt.ts +17 -0
  168. package/src/channels/adapters/discord-bot-reference.ts +5 -4
  169. package/src/channels/adapters/discord-bot.ts +1 -0
  170. package/src/channels/adapters/discord-classify.ts +8 -3
  171. package/src/channels/adapters/discord.ts +29 -0
  172. package/src/channels/adapters/github/history.ts +23 -2
  173. package/src/channels/adapters/github/inbound.ts +60 -1
  174. package/src/channels/adapters/github/index.ts +27 -5
  175. package/src/channels/adapters/github/reconcile-open-prs.ts +7 -1
  176. package/src/channels/adapters/kakaotalk-author-resolver.ts +7 -5
  177. package/src/channels/adapters/kakaotalk-channel-resolver.ts +45 -15
  178. package/src/channels/adapters/kakaotalk-classify.ts +7 -9
  179. package/src/channels/adapters/kakaotalk-list.ts +62 -0
  180. package/src/channels/adapters/kakaotalk-member-cache.ts +67 -0
  181. package/src/channels/adapters/kakaotalk-membership.ts +27 -10
  182. package/src/channels/adapters/kakaotalk-mention.ts +61 -0
  183. package/src/channels/adapters/kakaotalk.ts +159 -125
  184. package/src/channels/adapters/teams-classify.ts +18 -8
  185. package/src/channels/github-review-check.ts +5 -1
  186. package/src/channels/github-review-verdict-coordinator.ts +68 -2
  187. package/src/channels/github-token-bridge.ts +13 -0
  188. package/src/channels/lost-background-context.ts +46 -0
  189. package/src/channels/manager.ts +52 -3
  190. package/src/channels/persistence.ts +5 -0
  191. package/src/channels/router.ts +208 -128
  192. package/src/channels/schema.ts +1 -1
  193. package/src/channels/subagent-completion-bridge.ts +3 -2
  194. package/src/channels/types.ts +3 -0
  195. package/src/cli/hostd.ts +3 -0
  196. package/src/coding-agent/tool.ts +1 -1
  197. package/src/config/config.ts +35 -1
  198. package/src/config/providers.ts +75 -4
  199. package/src/container/start.ts +52 -3
  200. package/src/doctor/channel-checks.ts +33 -0
  201. package/src/doctor/checks.ts +37 -18
  202. package/src/doctor/index.ts +48 -12
  203. package/src/doctor/operational-incidents.ts +16 -1
  204. package/src/doctor/plugin-bridge.ts +14 -1
  205. package/src/doctor/stage.ts +14 -0
  206. package/src/doctor/types.ts +6 -0
  207. package/src/eval/cell.ts +93 -0
  208. package/src/eval/config.ts +32 -0
  209. package/src/eval/dispatch.ts +67 -0
  210. package/src/eval/entry.ts +261 -0
  211. package/src/eval/kernel.ts +154 -0
  212. package/src/eval/process.ts +113 -0
  213. package/src/eval/protocol.ts +26 -0
  214. package/src/eval/redeclare.ts +174 -0
  215. package/src/eval/sandbox.ts +117 -0
  216. package/src/eval/tool.ts +99 -0
  217. package/src/eval/wire.ts +93 -0
  218. package/src/git/resolve-identity.ts +67 -2
  219. package/src/git/system-commit.ts +7 -0
  220. package/src/init/dockerfile.ts +5 -1
  221. package/src/init/gitignore.ts +3 -3
  222. package/src/init/index.ts +1 -0
  223. package/src/init/models-dev.ts +2 -0
  224. package/src/init/validate-api-key.ts +5 -0
  225. package/src/migrations/secrets-v1-to-v2.ts +2 -0
  226. package/src/operations/classify-tool-outcome.ts +1 -1
  227. package/src/permissions/builtins.ts +8 -0
  228. package/src/plugin/core-tool-names.ts +6 -1
  229. package/src/plugin/types.ts +6 -0
  230. package/src/run/bundled-plugins.ts +12 -0
  231. package/src/run/channel-session-factory.ts +3 -0
  232. package/src/run/index.ts +13 -2
  233. package/src/sandbox/build.ts +1 -0
  234. package/src/sandbox/canonical-secrets.ts +6 -0
  235. package/src/sandbox/dependency-bins.ts +13 -1
  236. package/src/sandbox/dev-source.ts +21 -12
  237. package/src/sandbox/env-exposure.ts +20 -0
  238. package/src/sandbox/hidden-paths.ts +1 -1
  239. package/src/sandbox/index.ts +1 -0
  240. package/src/sandbox/policy.ts +5 -0
  241. package/src/secrets/hydrate.ts +4 -1
  242. package/src/secrets/storage.ts +10 -1
  243. package/src/server/command-runner.ts +4 -0
  244. package/src/server/index.ts +54 -12
  245. package/src/skills/typeclaw-config/SKILL.md +36 -2
  246. package/src/skills/typeclaw-memory/SKILL.md +3 -1
  247. package/src/skills/typeclaw-permissions/SKILL.md +8 -8
  248. package/src/skills/typeclaw-troubleshooting/SKILL.md +18 -1
  249. package/src/tunnels/active.ts +14 -0
  250. package/src/typevault/bash-cli.ts +18 -0
  251. package/src/typevault/cli-path.ts +11 -0
  252. package/src/typevault/envelope-helper.ts +17 -0
  253. package/src/typevault/envelope-store.ts +98 -0
  254. package/src/typevault/lifecycle.ts +132 -0
  255. package/src/typevault/prompt-tunnel.ts +33 -0
  256. package/src/typevault/redaction.ts +37 -0
  257. package/src/typevault/vault.ts +283 -0
  258. package/typeclaw.schema.json +92 -10
@@ -1,6 +1,6 @@
1
1
  import { AsyncLocalStorage } from 'node:async_hooks'
2
2
  import { mkdir } from 'node:fs/promises'
3
- import { join, relative, sep } from 'node:path'
3
+ import { relative, sep } from 'node:path'
4
4
 
5
5
  import {
6
6
  createBashToolDefinition as piCreateBashToolDefinition,
@@ -19,10 +19,9 @@ import { Type } from 'typebox'
19
19
  import { z } from 'zod'
20
20
 
21
21
  import { ACKNOWLEDGE_GUARDS } from '@/bundled-plugins/guard/keys'
22
- import { config, getSandboxWritablePathSpecs } from '@/config/config'
22
+ import type { GetGithubSelf } from '@/channels/github-token-bridge'
23
23
  import { readOomEvents, toolOomNote } from '@/container/oom-events'
24
24
  import { withToolOomPriorityCommand } from '@/container/tool-oom-priority'
25
- import { readEnvFile } from '@/init/env-file'
26
25
  import {
27
26
  classifyToolOutcome,
28
27
  deriveMechanicallyVerifiedIncidentFingerprints,
@@ -47,39 +46,29 @@ import type {
47
46
  } from '@/plugin'
48
47
  import { PI_BUILTIN_TOOL_NAMES, type PiBuiltinToolName } from '@/plugin/core-tool-names'
49
48
  import {
50
- buildSandboxedCommand,
51
- canWriteAgentRootInSandbox,
52
- canMountRealProc,
53
- cleanupPrivilegedSandboxRuntime,
54
49
  commandNeedsRealProc,
55
- DEFAULT_SANDBOX_ENV,
56
- DEPENDENCY_BIN_SANDBOX_DIR,
57
50
  dependencyBinUnavailableHint,
58
- ensureBwrapAvailable,
59
- ensureHiddenMaskTargets,
60
51
  ensureSessionTmpDir,
61
- getProcBindSafetyVerdict,
62
52
  isGitControlPath,
63
53
  mapVirtualTmpPath,
64
- reconcileDependencyBinWrappers,
65
54
  resolveHiddenPaths,
66
- resolvePrivilegedSandboxRuntime,
67
- resolveProcBindSafetyWithRetry,
68
- resolveProcSelfExe,
69
- resolveProtectedZones,
70
- resolveSandboxSymlinks,
71
- resolveWritableZones,
72
55
  SandboxPolicyError,
73
- SandboxDegradedProcError,
74
- SandboxProcProbeUnverifiedError,
75
- type SandboxMount,
76
- type DependencyBinReconciliation,
77
- subtractMasked,
78
- verifyHiddenMaskTargets,
79
- verifyPrivilegedSandboxRuntime,
80
56
  } from '@/sandbox'
81
- import { resolveDevSourceMount } from '@/sandbox/dev-source'
82
- import { resolveExposableEnvNames } from '@/sandbox/env-exposure'
57
+
58
+ import {
59
+ prepareBashSandbox,
60
+ type BashSandboxBoundary,
61
+ type BashSandboxReveal,
62
+ type DeferredBashPreparation,
63
+ type PreparedBashSandbox,
64
+ } from './bash-sandbox'
65
+ export {
66
+ buildBashFilesystemPolicy,
67
+ type BashSandboxBoundary,
68
+ type DeferredBashPreparation,
69
+ type DeferredBashPreparationResult,
70
+ } from './bash-sandbox'
71
+ export { buildSandboxEnvPolicy } from './bash-sandbox-env'
83
72
 
84
73
  import type { InternalGuard } from './guard-types'
85
74
  import { createLoopGuard, type LoopGuard, type LoopGuardDecision } from './loop-guard'
@@ -110,28 +99,12 @@ let sharedLoopGuard: LoopGuard = createLoopGuard()
110
99
  export const TYPECLAW_INTERNAL_BASH_ENV = '__typeclawBashEnv'
111
100
  export const TYPECLAW_INTERNAL_BASH_WITHHOLD_ENV = '__typeclawBashWithholdEnv'
112
101
  export const TYPECLAW_INTERNAL_BASH_PREPARE = '__typeclawBashPrepare'
102
+ export const TYPECLAW_INTERNAL_BASH_REVEAL = '__typeclawBashReveal'
113
103
 
114
104
  type BashEnvOverlay = Record<string, string>
115
105
  type BashEnvWithhold = string[]
116
- export type DeferredBashPreparationResult = {
117
- command: string
118
- env?: Record<string, string>
119
- mount: Extract<SandboxMount, { type: 'ro-bind' }>
120
- cleanup: () => Promise<void>
121
- }
122
- export type DeferredBashPreparation = () => Promise<DeferredBashPreparationResult>
123
106
  const SECRET_BASH_ENV_NAMES = new Set(['GH_TOKEN', 'GITHUB_TOKEN'])
124
107
 
125
- // Transport classifier for the TRUSTED hook-injected overlay only (e.g.
126
- // github-cli-auth's per-repo GH_TOKEN). Token/secret-shaped names use `inherit`
127
- // so their value never renders into the bwrap argv; plain names (GH_REPO) go
128
- // via `set`. This is NOT a .env exposure filter — the overlay is populated by
129
- // trusted runtime hooks, not operator .env.
130
- const OVERLAY_SECRET_NAME_PATTERN = /(?:^|_)(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY|AUTH)$/i
131
- function isOverlaySecretName(name: string): boolean {
132
- return SECRET_BASH_ENV_NAMES.has(name) || OVERLAY_SECRET_NAME_PATTERN.test(name)
133
- }
134
-
135
108
  type BashSpawnEnvContext = {
136
109
  overlay?: BashEnvOverlay
137
110
  withhold?: BashEnvWithhold
@@ -162,6 +135,20 @@ function readBashEnvWithhold(args: Record<string, unknown>): BashEnvWithhold | u
162
135
  return names.length > 0 ? names : undefined
163
136
  }
164
137
 
138
+ function readBashReveal(args: Record<string, unknown>): BashSandboxReveal | undefined {
139
+ const raw = args[TYPECLAW_INTERNAL_BASH_REVEAL]
140
+ if (!Array.isArray(raw)) return undefined
141
+ const reveal: BashSandboxReveal = []
142
+ for (const entry of raw) {
143
+ if (entry === null || typeof entry !== 'object') continue
144
+ const { type, source, dest } = entry as Record<string, unknown>
145
+ if (typeof dest !== 'string') continue
146
+ if (type === 'tmpfs') reveal.push({ type, dest })
147
+ else if (type === 'ro-bind' && typeof source === 'string') reveal.push({ type, source, dest })
148
+ }
149
+ return reveal.length > 0 ? reveal : undefined
150
+ }
151
+
165
152
  function readBashPreparation(args: Record<string, unknown>): DeferredBashPreparation | undefined {
166
153
  const raw = args[TYPECLAW_INTERNAL_BASH_PREPARE]
167
154
  return typeof raw === 'function' ? (raw as DeferredBashPreparation) : undefined
@@ -309,21 +296,8 @@ export type WrapToolOptions = {
309
296
  getLoopGuardTurn?: () => number | undefined
310
297
  }
311
298
 
312
- export type BashSandboxBoundary = {
313
- ensureAvailable: () => Promise<void>
314
- buildCommand: typeof buildSandboxedCommand
315
- resolveProcStrategy?: () => Promise<ProcStrategyResolution>
316
- resolveRuntime?: typeof resolvePrivilegedSandboxRuntime
317
- verifyRuntime?: typeof verifyPrivilegedSandboxRuntime
318
- cleanupRuntime?: typeof cleanupPrivilegedSandboxRuntime
319
- }
320
-
321
- const DEFAULT_BASH_SANDBOX_BOUNDARY: BashSandboxBoundary = {
322
- ensureAvailable: ensureBwrapAvailable,
323
- buildCommand: buildSandboxedCommand,
324
- }
325
-
326
299
  export type WrapSystemToolOptions = {
300
+ readonly getGithubSelf?: GetGithubSelf
327
301
  agentDir: string
328
302
  sessionId: string
329
303
  hooks: HookBus
@@ -380,7 +354,7 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
380
354
  label: opts.toolName,
381
355
  description: tool.description,
382
356
  parameters,
383
- async execute(toolCallId, params, signal) {
357
+ async execute(toolCallId, params, signal, _onUpdate, ctx) {
384
358
  const envelope = extractGuardAcknowledgements(params, opts.toolName, opts.guards ?? [])
385
359
  if (!envelope.ok) return errorResult(`invalid arguments: ${envelope.error}`)
386
360
 
@@ -391,6 +365,8 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
391
365
 
392
366
  const mutableArgs = validated.data as Record<string, unknown>
393
367
  const liveOrigin = opts.getOrigin?.()
368
+ // Plain Agent/direct invocations may have no extension context.
369
+ const entryId = ctx?.sessionManager?.getLeafId() ?? undefined
394
370
  const before: ToolBeforeEvent = {
395
371
  tool: opts.toolName,
396
372
  sessionId: opts.sessionId,
@@ -423,6 +399,8 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
423
399
  sessionId: opts.sessionId,
424
400
  agentDir: opts.agentDir,
425
401
  logger: opts.logger,
402
+ ...(liveOrigin === undefined ? {} : { origin: liveOrigin }),
403
+ ...(entryId === undefined ? {} : { entryId }),
426
404
  }
427
405
 
428
406
  let result: ToolResult | undefined
@@ -606,6 +584,7 @@ export function wrapBuiltinToolDefinition<TParams extends TSchema, TDetails = un
606
584
  delete mutableArgs[TYPECLAW_INTERNAL_BASH_ENV]
607
585
  delete mutableArgs[TYPECLAW_INTERNAL_BASH_WITHHOLD_ENV]
608
586
  delete mutableArgs[TYPECLAW_INTERNAL_BASH_PREPARE]
587
+ delete mutableArgs[TYPECLAW_INTERNAL_BASH_REVEAL]
609
588
  const blockResult = await opts.hooks.runToolBefore(
610
589
  {
611
590
  tool: tool.name,
@@ -633,9 +612,11 @@ export function wrapBuiltinToolDefinition<TParams extends TSchema, TDetails = un
633
612
  const bashEnvOverlay = readBashEnvOverlay(mutableArgs)
634
613
  const bashEnvWithhold = readBashEnvWithhold(mutableArgs)
635
614
  const bashPreparation = readBashPreparation(mutableArgs)
615
+ const bashReveal = readBashReveal(mutableArgs)
636
616
  delete mutableArgs[TYPECLAW_INTERNAL_BASH_ENV]
637
617
  delete mutableArgs[TYPECLAW_INTERNAL_BASH_WITHHOLD_ENV]
638
618
  delete mutableArgs[TYPECLAW_INTERNAL_BASH_PREPARE]
619
+ delete mutableArgs[TYPECLAW_INTERNAL_BASH_REVEAL]
639
620
  const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs, opts.getLoopGuardTurn?.(), opts.agentDir)
640
621
  if (loopGate.blockNow) {
641
622
  fireLoopAbort(opts.getAbort, 'loop_guard:block', opts.sessionId)
@@ -658,7 +639,7 @@ export function wrapBuiltinToolDefinition<TParams extends TSchema, TDetails = un
658
639
  let executionError: unknown
659
640
  let cleanupError: unknown
660
641
  let sandboxedRealProcSucceeded = false
661
- const sandboxBoundary = opts.bashSandboxBoundary ?? DEFAULT_BASH_SANDBOX_BOUNDARY
642
+ const sandboxBoundary = opts.bashSandboxBoundary
662
643
  const incidentLedger = opts.incidentLedger ?? new IncidentLedger(opts.agentDir)
663
644
  const originalArgs = { ...mutableArgs }
664
645
  const executeAttempt = async (): Promise<void> => {
@@ -678,17 +659,21 @@ export function wrapBuiltinToolDefinition<TParams extends TSchema, TDetails = un
678
659
  'model-driven bash has no permission service; refusing unsandboxed execution',
679
660
  )
680
661
  }
681
- preparedSandboxRuntime = await applyBashSandbox(
682
- attemptArgs,
683
- opts.permissions,
684
- liveOrigin,
685
- opts.agentDir,
686
- opts.sessionId,
687
- bashEnvOverlay,
688
- bashEnvWithhold,
689
- bashPreparation,
690
- sandboxBoundary,
691
- )
662
+ if (typeof attemptArgs.command !== 'string') throw new SandboxPolicyError('bash command must be a string')
663
+ preparedSandboxRuntime = await prepareBashSandbox({
664
+ getGithubSelf: opts.getGithubSelf,
665
+ command: attemptArgs.command,
666
+ permissions: opts.permissions,
667
+ origin: liveOrigin,
668
+ agentDir: opts.agentDir,
669
+ sessionId: opts.sessionId,
670
+ envOverlay: bashEnvOverlay,
671
+ envWithhold: bashEnvWithhold,
672
+ deferredPreparation: bashPreparation,
673
+ reveal: bashReveal,
674
+ boundary: sandboxBoundary,
675
+ })
676
+ attemptArgs.command = preparedSandboxRuntime.commandString
692
677
  }
693
678
 
694
679
  tmpRedirect =
@@ -902,156 +887,6 @@ export function buildBuiltinPiToolOverrides(opts: WrapSystemToolOptions): ToolDe
902
887
  return defaultBuiltinPiToolDefinitions(opts.agentDir).map((tool) => wrapBuiltinToolDefinition(tool, opts))
903
888
  }
904
889
 
905
- type BashFilesystemPolicyOptions = {
906
- agentDir: string
907
- canWriteAgentRoot: boolean
908
- masks: { dirs: string[]; files: string[] }
909
- writable: { dirs: string[]; files: string[] }
910
- protected: { dirs: string[]; files: string[] }
911
- }
912
-
913
- type PreparedBashSandbox = {
914
- verify: () => Promise<void>
915
- cleanup: () => Promise<void>
916
- spawnEnv?: Record<string, string>
917
- dependencyBins?: DependencyBinReconciliation
918
- withheld: {
919
- paths: { dirs: string[]; files: string[] }
920
- envNames: string[]
921
- }
922
- }
923
-
924
- export function buildBashFilesystemPolicy(options: BashFilesystemPolicyOptions) {
925
- const { agentDir, canWriteAgentRoot, masks, writable, protected: protectedZones } = options
926
- if (canWriteAgentRoot) {
927
- return { writableRoot: { dir: agentDir }, masks, protected: protectedZones }
928
- }
929
- return { masks, writable, protected: protectedZones }
930
- }
931
-
932
- // Rewrites mutableArgs.command in place so the bash builtin runs inside bwrap
933
- // with role-derived private-directory masks and unconditional canonical-secret
934
- // file masks. When masks are needed but bwrap is unavailable
935
- // we throw rather than run unsandboxed — fail closed, never leak the masked
936
- // surface. Runs after the tool.before guards have inspected the raw command.
937
- async function applyBashSandbox(
938
- mutableArgs: Record<string, unknown>,
939
- permissions: PermissionService,
940
- origin: SessionOrigin | undefined,
941
- agentDir: string,
942
- sessionId: string,
943
- envOverlay: BashEnvOverlay | undefined,
944
- envWithhold: BashEnvWithhold | undefined,
945
- deferredPreparation: DeferredBashPreparation | undefined,
946
- boundary: BashSandboxBoundary,
947
- ): Promise<PreparedBashSandbox> {
948
- const originalCommand = mutableArgs.command
949
- if (typeof originalCommand !== 'string') {
950
- return {
951
- verify: async () => {},
952
- cleanup: async () => {},
953
- withheld: { paths: { dirs: [], files: [] }, envNames: [] },
954
- }
955
- }
956
-
957
- let preparation: DeferredBashPreparationResult | undefined
958
- let privilegedRuntime: Awaited<ReturnType<typeof resolvePrivilegedSandboxRuntime>> | undefined
959
- const cleanup = async (): Promise<void> => {
960
- const tasks: Promise<void>[] = []
961
- if (privilegedRuntime !== undefined) {
962
- tasks.push((boundary.cleanupRuntime ?? cleanupPrivilegedSandboxRuntime)(privilegedRuntime))
963
- }
964
- if (preparation !== undefined) tasks.push(preparation.cleanup())
965
- const outcomes = await Promise.allSettled(tasks)
966
- const failure = outcomes.find((outcome) => outcome.status === 'rejected')
967
- if (failure?.status === 'rejected') throw failure.reason
968
- }
969
- try {
970
- preparation = await deferredPreparation?.()
971
- const command = preparation?.command ?? originalCommand
972
- const preparedEnvOverlay = preparation?.env === undefined ? envOverlay : { ...envOverlay, ...preparation.env }
973
- const { dirs, files } = resolveHiddenPaths(permissions, origin, agentDir)
974
- const envNames = resolveExposableBashEnvNames(agentDir)
975
- const sandboxEnvOverlay = buildRoleScopedConfigEnv(agentDir, dirs, preparedEnvOverlay)
976
- const effectiveEnvWithhold = (envWithhold ?? []).filter((name) => !Object.hasOwn(sandboxEnvOverlay ?? {}, name))
977
- const maskTargets = await ensureHiddenMaskTargets({ dirs, files })
978
- await boundary.ensureAvailable()
979
- const sessionTmp = await ensureSessionTmpDir(sessionId)
980
- const dependencyBins = await reconcileDependencyBinWrappers({ agentDir, sessionTmp })
981
- const writable = subtractMasked(await resolveWritableZones(agentDir, getSandboxWritablePathSpecs(config)), {
982
- dirs,
983
- files,
984
- })
985
- const writableRoot = canWriteAgentRootInSandbox(permissions, origin)
986
- const baseProtectedZones =
987
- writableRoot || writable.dirs.includes(join(agentDir, '.git'))
988
- ? subtractMasked(await resolveProtectedZones(agentDir), { dirs, files })
989
- : { dirs: [], files: [] }
990
- const protectedZones = {
991
- dirs: baseProtectedZones.dirs,
992
- files: [...new Set([...baseProtectedZones.files, ...dependencyBins.protectedFiles])],
993
- }
994
- const writableDirSet = new Set(writable.dirs)
995
- const sandboxHome = DEFAULT_SANDBOX_ENV.HOME ?? '/tmp'
996
- const symlinks = resolveSandboxSymlinks(agentDir, config.sandbox.symlinks, sandboxHome).filter((op) =>
997
- writableDirSet.has(op.target),
998
- )
999
- const { strategy: proc, degradeReason } = await (boundary.resolveProcStrategy ?? resolveProcStrategy)()
1000
- if (proc === 'tmpfs' && commandNeedsRealProc(command)) {
1001
- throw degradeReason === 'unverified' ? new SandboxProcProbeUnverifiedError() : new SandboxDegradedProcError()
1002
- }
1003
- privilegedRuntime = await (boundary.resolveRuntime ?? resolvePrivilegedSandboxRuntime)({
1004
- agentDir,
1005
- command,
1006
- env: sandboxEnvOverlay,
1007
- })
1008
- await verifyHiddenMaskTargets(maskTargets)
1009
- const devSourceMount = await resolveDevSourceMount(agentDir)
1010
- const { commandString, spawnEnv } = boundary.buildCommand(command, {
1011
- mounts: [
1012
- { type: 'ro-bind', source: agentDir, dest: agentDir },
1013
- { type: 'bind', source: sessionTmp, dest: '/tmp' },
1014
- // `/tmp` is writable, but PATH entries must remain runtime-owned for
1015
- // the lifetime of this command. Last-op-wins makes this narrow re-bind
1016
- // read-only without adding any broader filesystem exposure.
1017
- { type: 'ro-bind', source: dependencyBins.wrapperDir, dest: DEPENDENCY_BIN_SANDBOX_DIR },
1018
- ...(devSourceMount === undefined ? [] : [devSourceMount]),
1019
- ...(privilegedRuntime?.mounts ?? []),
1020
- ...(preparation === undefined ? [] : [preparation.mount]),
1021
- ],
1022
- ...(writableRoot
1023
- ? { writableRoot: { dir: agentDir }, masks: maskTargets, protected: protectedZones }
1024
- : { masks: maskTargets, writable, protected: protectedZones }),
1025
- symlinks,
1026
- network: 'inherit',
1027
- cwd: agentDir,
1028
- proc,
1029
- procSelfExe: resolveProcSelfExe(),
1030
- ...spreadSandboxEnv(
1031
- buildSandboxEnvPolicy(sandboxEnvOverlay, privilegedRuntime?.env, envNames.exposable, envWithhold),
1032
- ),
1033
- })
1034
- mutableArgs.command = commandString
1035
- // The overlay carries command-scoped secret VALUES (e.g. a per-repo GH_TOKEN)
1036
- // that live in neither process.env nor argv; resolveSpawnEnv snapshots
1037
- // inherited names from process.env only, so merge the overlay values in here
1038
- // to complete the exact bwrap-parent env.
1039
- const mergedSpawnEnv =
1040
- spawnEnv !== undefined && sandboxEnvOverlay !== undefined ? { ...spawnEnv, ...sandboxEnvOverlay } : spawnEnv
1041
- const runtimeForResult = privilegedRuntime
1042
- return {
1043
- verify: async () => (boundary.verifyRuntime ?? verifyPrivilegedSandboxRuntime)(runtimeForResult),
1044
- cleanup,
1045
- spawnEnv: mergedSpawnEnv,
1046
- dependencyBins,
1047
- withheld: { paths: maskTargets, envNames: [...new Set([...envNames.withheld, ...effectiveEnvWithhold])] },
1048
- }
1049
- } catch (error) {
1050
- await cleanup()
1051
- throw error
1052
- }
1053
- }
1054
-
1055
890
  function bashResultIsCommandNotFound(result: ToolResult): boolean {
1056
891
  if (isRecord(result.details) && result.details.exitCode === 127) return true
1057
892
  return (result.content as ContentPart[]).some(
@@ -1089,164 +924,6 @@ function appendTextResult(result: ToolResult, text: string): ToolResult {
1089
924
  return { ...result, content: [...(result.content as ContentPart[]), { type: 'text', text }] }
1090
925
  }
1091
926
 
1092
- export function buildSandboxEnvPolicy(
1093
- overlay: BashEnvOverlay | undefined,
1094
- runtimeEnv: Record<string, string> | undefined,
1095
- exposableEnvNames: readonly string[] = [],
1096
- withhold: readonly string[] = [],
1097
- ): { inherit?: string[]; set?: Record<string, string>; withhold?: string[] } {
1098
- const requestedWithhold = new Set(withhold)
1099
- const overlayNames = new Set(Object.keys(overlay ?? {}))
1100
- // The overlay is a deliberate command-scoped replacement, while withholding
1101
- // only removes ambient values; an overlay therefore wins for the same name.
1102
- const effectiveWithhold = [...requestedWithhold].filter((name) => !overlayNames.has(name))
1103
- const effectiveWithholdSet = new Set(effectiveWithhold)
1104
- const set = Object.fromEntries(Object.entries(runtimeEnv ?? {}).filter(([key]) => !requestedWithhold.has(key)))
1105
- const inherit: string[] = []
1106
- const inheritSeen = new Set<string>()
1107
- const pushInherit = (key: string): void => {
1108
- if (effectiveWithholdSet.has(key) || Object.hasOwn(set, key) || inheritSeen.has(key)) return
1109
- inheritSeen.add(key)
1110
- inherit.push(key)
1111
- }
1112
- for (const [key, value] of Object.entries(overlay ?? {})) {
1113
- if (Object.hasOwn(set, key)) continue
1114
- if (isOverlaySecretName(key)) pushInherit(key)
1115
- else set[key] = value
1116
- }
1117
- // Operator-declared .env vars pass through by NAME (inherit), keeping values
1118
- // out of the rendered bwrap argv. Sandbox-integrity names were already dropped
1119
- // in resolveExposableEnvNames — these are the survivors.
1120
- for (const key of exposableEnvNames) pushInherit(key)
1121
- // Pass the entrypoint-exported Xvfb display (start_xvfb: `export DISPLAY=:99`)
1122
- // through --clearenv, else sandboxed `agent-browser --headed` dies with
1123
- // "Missing X server or $DISPLAY". Passing the runtime's OWN value (not a fixed
1124
- // ":99") keeps `docker.file.xvfb=false` advertising no display. Rendered via
1125
- // `set` (a display number is neither a credential nor shell-injectable), and no
1126
- // /tmp/.X11-unix bind is needed: Chrome reaches Xvfb over the netns-scoped
1127
- // abstract X11 socket while bash keeps network:'inherit'.
1128
- const display = process.env['DISPLAY']
1129
- if (
1130
- display !== undefined &&
1131
- display !== '' &&
1132
- !effectiveWithholdSet.has('DISPLAY') &&
1133
- !Object.hasOwn(set, 'DISPLAY') &&
1134
- !inheritSeen.has('DISPLAY')
1135
- ) {
1136
- set['DISPLAY'] = display
1137
- }
1138
- return {
1139
- ...(inherit.length > 0 ? { inherit } : {}),
1140
- ...(Object.keys(set).length > 0 ? { set } : {}),
1141
- ...(effectiveWithhold.length > 0 ? { withhold: effectiveWithhold } : {}),
1142
- }
1143
- }
1144
-
1145
- function spreadSandboxEnv(policy: ReturnType<typeof buildSandboxEnvPolicy>): {
1146
- env?: ReturnType<typeof buildSandboxEnvPolicy>
1147
- } {
1148
- return Object.keys(policy).length > 0 ? { env: policy } : {}
1149
- }
1150
-
1151
- function resolveExposableBashEnvNames(agentDir: string): { exposable: string[]; withheld: string[] } {
1152
- const declaredEnv = readEnvFile(agentDir)
1153
- const exposable = resolveExposableEnvNames(declaredEnv, process.env)
1154
- const exposableSet = new Set(exposable)
1155
- const withheld = [...declaredEnv]
1156
- .filter(([name, value]) => value.length > 0 && !exposableSet.has(name))
1157
- .map(([name]) => name)
1158
- return { exposable, withheld }
1159
- }
1160
-
1161
- function buildRoleScopedConfigEnv(
1162
- agentDir: string,
1163
- hiddenDirs: string[],
1164
- envOverlay: BashEnvOverlay | undefined,
1165
- ): BashEnvOverlay | undefined {
1166
- // Low-trust roles have workspace/ masked. Do not let container-global config
1167
- // env vars point CLIs back at that private surface: apps that honor XDG should
1168
- // still run, but their config must land in the sandbox's per-session /tmp.
1169
- // Trusted/owner have only the unconditional credential-dir masks, not the
1170
- // workspace root mask, so their command broker decides whether to set GWS.
1171
- const workspaceHidden = hiddenDirs.includes(join(agentDir, 'workspace'))
1172
- if (!workspaceHidden) return envOverlay
1173
-
1174
- return {
1175
- ...envOverlay,
1176
- XDG_CONFIG_HOME: '/tmp/.config',
1177
- GWS_CONFIG_HOME: '/tmp/.config/gws',
1178
- }
1179
- }
1180
-
1181
- // Picks the /proc strategy for a sandboxed bash call. The branch order is:
1182
- // 'real-proc' ONLY when the operator explicitly opted in (sandbox.realProc) AND
1183
- // the kernel permits the mount (canMountRealProc) — it adds PID isolation but
1184
- // needs CAP_SYS_ADMIN (unshare --mount-proc), so it is a deliberate, narrow
1185
- // opt-in; else 'proc-bind' (--ro-bind /proc, NO CAP_SYS_ADMIN) when its userns
1186
- // leak-block is verified safe; else 'tmpfs'. Because sandbox.realProc DEFAULTS
1187
- // FALSE, the first branch is normally skipped and proc-bind is the de-facto
1188
- // default — which is the point: the common path needs no broad outer capability.
1189
- // 'tmpfs' is the last-resort degraded mode where external packages can't run;
1190
- // reached only when proc-bind is DEFINITIVELY unavailable (a real cross-userns
1191
- // environ leak → fail closed) or its safety stays unverifiable after retries.
1192
- //
1193
- // Read from the boot-time `config` snapshot, NOT live getConfig(): sandbox is
1194
- // restart-required, and the strategy MUST track the boot-time CAP_SYS_ADMIN
1195
- // grant. A `typeclaw reload` flipping realProc would otherwise emit `unshare
1196
- // --mount-proc` in a container booted WITHOUT the cap (or vice versa). Both
1197
- // probes are cached process-globally, so this resolves to one spawn per
1198
- // container lifetime regardless of how many bash calls hit it.
1199
- // A tmpfs degrade carries WHY it happened so the caller can pick a permanent vs
1200
- // retryable error. 'definitive': the probe returned a real cross-userns leak
1201
- // ('unsafe') — the ONLY verdict proven permanent, so it fails closed for good.
1202
- // 'unverified': the safety probe never reached a definitive verdict within its
1203
- // retry budget. That covers BOTH a transient load spike AND a durable
1204
- // incapability (no usable namespaces, a bwrap that starts but cannot set up its
1205
- // sandbox): the probe cannot prove a NEGATIVE capability — only a leak is
1206
- // definitive — so a genuinely incapable host also lands here and simply keeps
1207
- // re-degrading on each call. Since 'inconclusive' is never cached, that costs a
1208
- // re-probe but is correct: the only false case is "capable but briefly
1209
- // saturated", which recovers; an incapable host stays degraded either way.
1210
- // Absent when the strategy is not tmpfs.
1211
- type ProcStrategyResolution =
1212
- | { strategy: 'real-proc' | 'proc-bind'; degradeReason?: undefined }
1213
- | { strategy: 'tmpfs'; degradeReason: 'definitive' | 'unverified' }
1214
-
1215
- async function resolveProcStrategy(): Promise<ProcStrategyResolution> {
1216
- if (config.sandbox.realProc && (await canMountRealProc())) return { strategy: 'real-proc' }
1217
- // Retry an 'inconclusive' proc-bind probe (transient under load) before
1218
- // degrading — a single such hiccup must not break external-package runs on a
1219
- // capable host. 'unsafe' still fails closed with no retry.
1220
- const verdict = await resolveProcBindSafetyWithRetry(
1221
- () => getProcBindSafetyVerdict(),
1222
- (ms) => Bun.sleep(ms),
1223
- )
1224
- if (verdict === 'safe') return { strategy: 'proc-bind' }
1225
- // Degraded last resort: no working /proc strategy. External package runners
1226
- // (bunx/bun run <pkg-bin>) will fail with Bun's opaque "NotDir" because
1227
- // /proc/self/{fd,maps} are absent. Only a proven 'unsafe' (a real cross-userns
1228
- // leak) is DEFINITIVE — warn once (a real operator-facing limit). An
1229
- // 'inconclusive' is reported as retryable upstream and NOT warned (it would cry
1230
- // wolf every boot storm); a durably-incapable host re-degrades quietly here,
1231
- // since the probe cannot distinguish it from transient load.
1232
- if (verdict === 'unsafe') {
1233
- warnTmpfsProcFallbackOnce()
1234
- return { strategy: 'tmpfs', degradeReason: 'definitive' }
1235
- }
1236
- return { strategy: 'tmpfs', degradeReason: 'unverified' }
1237
- }
1238
-
1239
- let tmpfsProcFallbackWarned = false
1240
- function warnTmpfsProcFallbackOnce(): void {
1241
- if (tmpfsProcFallbackWarned) return
1242
- tmpfsProcFallbackWarned = true
1243
- console.warn(
1244
- '[sandbox] degraded /proc mode: neither real-proc nor proc-bind is available on this host, ' +
1245
- 'so sandboxed external package runners (bunx / bun run <pkg-bin>) will fail. ' +
1246
- 'This needs a runtime with working user namespaces.',
1247
- )
1248
- }
1249
-
1250
927
  // The builtin file tools that take a single filesystem `path` arg. They run in
1251
928
  // the main process rather than bwrap, so each must apply the same
1252
929
  // /tmp -> session-dir mapping that
@@ -1438,6 +1115,13 @@ export function forgetSharedLoopGuardTool(sessionId: string, tool: string): void
1438
1115
  sharedLoopGuard.forgetTool(sessionId, tool)
1439
1116
  }
1440
1117
 
1118
+ // Drops a session's whole loop-guard history when a new user request starts
1119
+ // (see `attachLoopGuardUserRunTracking`), so per-request repetition is not
1120
+ // mistaken for a cycle that spans requests.
1121
+ export function resetSharedLoopGuardSession(sessionId: string): void {
1122
+ sharedLoopGuard.reset(sessionId)
1123
+ }
1124
+
1441
1125
  // Test-only seam: swaps the shared loop guard for a fresh instance so tests
1442
1126
  // that reuse sessionIds across cases don't see cross-test streak counts.
1443
1127
  // Production code never calls this; the guard's LRU bound handles
@@ -10,9 +10,7 @@ const PROMPT_CACHE_KEY_MAX_LENGTH = 64
10
10
  // session therefore landed on a cold machine and re-paid its whole ~10K-token
11
11
  // system+tools prefix even though sibling sessions of the same kind had just
12
12
  // sent the identical prefix. Keying by origin kind (and subagent/component
13
- // name, whose prompts differ) lets those sessions share the warm prefix. Only
14
- // the body key changes: pi still uses the session id for the Codex websocket
15
- // session cache and request headers.
13
+ // name, whose prompts differ) lets those sessions share the warm prefix.
16
14
  export function promptCacheKeyForOrigin(origin: SessionOrigin | undefined): string | undefined {
17
15
  const key = unboundedPromptCacheKey(origin)
18
16
  return key === undefined ? undefined : Array.from(key).slice(0, PROMPT_CACHE_KEY_MAX_LENGTH).join('')
@@ -32,6 +30,31 @@ function unboundedPromptCacheKey(origin: SessionOrigin | undefined): string | un
32
30
  }
33
31
  }
34
32
 
33
+ // Providers route cache affinity by the stream `sessionId` pi turns into
34
+ // session-affinity headers (`session-id`, `x-session-affinity`, `x-affinity`, …)
35
+ // and default cache keys, so rewriting the body key alone does not reach a warm
36
+ // machine. On the ChatGPT Codex backend, a live probe of identical prefixes on
37
+ // fresh connections got 0% reuse with per-session ids and the same body key,
38
+ // and ~96% once the session id was shared. Short-lived subagent and system
39
+ // sessions therefore send their origin key as the session id on every
40
+ // provider, and each cron fire (a fresh session that repeats its job's prompt)
41
+ // shares one id per job. Long-lived tui/channel sessions keep their own id so
42
+ // one hot shared key cannot spill their long histories onto overflow machines.
43
+ // The id travels in HTTP headers, whose values must be Latin-1, so characters
44
+ // outside printable ASCII are percent-encoded. ASCII names stay identical to
45
+ // their body cache key.
46
+ export function sharedSessionIdForOrigin(origin: SessionOrigin | undefined): string | undefined {
47
+ const shared =
48
+ origin?.kind === 'subagent' || origin?.kind === 'system'
49
+ ? unboundedPromptCacheKey(origin)!
50
+ : origin?.kind === 'cron'
51
+ ? `typeclaw:cron:${origin.jobId}`
52
+ : undefined
53
+ if (shared === undefined) return undefined
54
+ const key = shared.replace(/[^\x20-\x7e]/gu, (char) => encodeURIComponent(char))
55
+ return key.slice(0, PROMPT_CACHE_KEY_MAX_LENGTH)
56
+ }
57
+
35
58
  // Rewrites only payloads that already carry a string `prompt_cache_key`, so
36
59
  // providers without the field and `cacheRetention: 'none'` (which omits it)
37
60
  // are left untouched.