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
@@ -0,0 +1,136 @@
1
+ import { join } from 'node:path'
2
+
3
+ import type { GithubSelfUser } from '@/channels/adapters/github/auth'
4
+ import { isFallbackGitIdentity, resolveGitIdentity } from '@/git/resolve-identity'
5
+ import { readEnvFile } from '@/init/env-file'
6
+ import { resolveExposableEnvNames } from '@/sandbox/env-exposure'
7
+ type BashEnvOverlay = Record<string, string>
8
+ // TYPECLAW_VAULT_GRANT is a bearer credential whose name the pattern below
9
+ // misses; in argv another sandboxed session could read it from proc cmdline.
10
+ const SECRET_BASH_ENV_NAMES = new Set(['GH_TOKEN', 'GITHUB_TOKEN', 'TYPECLAW_VAULT_GRANT'])
11
+ // Transport classifier for the TRUSTED hook-injected overlay only (e.g.
12
+ // github-cli-auth's per-repo GH_TOKEN). Token/secret-shaped names use `inherit`
13
+ // so their value never renders into the bwrap argv; plain names (GH_REPO) go
14
+ // via `set`. This is NOT a .env exposure filter — the overlay is populated by
15
+ // trusted runtime hooks, not operator .env.
16
+ const OVERLAY_SECRET_NAME_PATTERN = /(?:^|_)(?:TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE_KEY|AUTH)$/i
17
+ function isOverlaySecretName(name: string): boolean {
18
+ return SECRET_BASH_ENV_NAMES.has(name) || OVERLAY_SECRET_NAME_PATTERN.test(name)
19
+ }
20
+
21
+ export function buildSandboxEnvPolicy(
22
+ overlay: BashEnvOverlay | undefined,
23
+ runtimeEnv: Record<string, string> | undefined,
24
+ exposableEnvNames: readonly string[] = [],
25
+ withhold: readonly string[] = [],
26
+ ): { inherit?: string[]; set?: Record<string, string>; withhold?: string[] } {
27
+ const requestedWithhold = new Set(withhold)
28
+ const overlayNames = new Set(Object.keys(overlay ?? {}))
29
+ // The overlay is a deliberate command-scoped replacement, while withholding
30
+ // only removes ambient values; an overlay therefore wins for the same name.
31
+ const effectiveWithhold = [...requestedWithhold].filter((name) => !overlayNames.has(name))
32
+ const effectiveWithholdSet = new Set(effectiveWithhold)
33
+ const set = Object.fromEntries(Object.entries(runtimeEnv ?? {}).filter(([key]) => !requestedWithhold.has(key)))
34
+ const inherit: string[] = []
35
+ const inheritSeen = new Set<string>()
36
+ const pushInherit = (key: string): void => {
37
+ if (effectiveWithholdSet.has(key) || Object.hasOwn(set, key) || inheritSeen.has(key)) return
38
+ inheritSeen.add(key)
39
+ inherit.push(key)
40
+ }
41
+ for (const [key, value] of Object.entries(overlay ?? {})) {
42
+ if (Object.hasOwn(set, key)) continue
43
+ if (isOverlaySecretName(key)) pushInherit(key)
44
+ else set[key] = value
45
+ }
46
+ // Operator-declared .env vars pass through by NAME (inherit), keeping values
47
+ // out of the rendered bwrap argv. Sandbox-integrity names were already dropped
48
+ // in resolveExposableEnvNames — these are the survivors.
49
+ for (const key of exposableEnvNames) pushInherit(key)
50
+ // Pass the entrypoint-exported Xvfb display (start_xvfb: `export DISPLAY=:99`)
51
+ // through --clearenv, else sandboxed `agent-browser --headed` dies with
52
+ // "Missing X server or $DISPLAY". Passing the runtime's OWN value (not a fixed
53
+ // ":99") keeps `docker.file.xvfb=false` advertising no display. Rendered via
54
+ // `set` (a display number is neither a credential nor shell-injectable), and no
55
+ // /tmp/.X11-unix bind is needed: Chrome reaches Xvfb over the netns-scoped
56
+ // abstract X11 socket while bash keeps network:'inherit'.
57
+ const display = process.env['DISPLAY']
58
+ if (
59
+ display !== undefined &&
60
+ display !== '' &&
61
+ !effectiveWithholdSet.has('DISPLAY') &&
62
+ !Object.hasOwn(set, 'DISPLAY') &&
63
+ !inheritSeen.has('DISPLAY')
64
+ ) {
65
+ set['DISPLAY'] = display
66
+ }
67
+ return {
68
+ ...(inherit.length > 0 ? { inherit } : {}),
69
+ ...(Object.keys(set).length > 0 ? { set } : {}),
70
+ ...(effectiveWithhold.length > 0 ? { withhold: effectiveWithhold } : {}),
71
+ }
72
+ }
73
+
74
+ export function spreadSandboxEnv(policy: ReturnType<typeof buildSandboxEnvPolicy>): {
75
+ env?: ReturnType<typeof buildSandboxEnvPolicy>
76
+ } {
77
+ return Object.keys(policy).length > 0 ? { env: policy } : {}
78
+ }
79
+
80
+ export function resolveExposableBashEnvNames(agentDir: string): { exposable: string[]; withheld: string[] } {
81
+ const declaredEnv = readEnvFile(agentDir)
82
+ const exposable = resolveExposableEnvNames(declaredEnv, process.env)
83
+ const exposableSet = new Set(exposable)
84
+ const withheld = [...declaredEnv]
85
+ .filter(([name, value]) => value.length > 0 && !exposableSet.has(name))
86
+ .map(([name]) => name)
87
+ return { exposable, withheld }
88
+ }
89
+
90
+ // `typeclaw start` withholds a synthesized fallback identity from the container
91
+ // env so a later `git config` in the agent repo still takes effect. Without this,
92
+ // commits in any other repository (workspace clones, /tmp worktrees) fail with
93
+ // "Author identity unknown" and the model invents an identity, which can credit a
94
+ // stranger's GitHub account. Reading the agent repo per command keeps it live.
95
+ export async function resolveAgentGitIdentityEnv(
96
+ agentDir: string,
97
+ exposableEnvNames: readonly string[],
98
+ githubSelf: GithubSelfUser | null = null,
99
+ ): Promise<BashEnvOverlay> {
100
+ const exposable = new Set(exposableEnvNames)
101
+ const names = {
102
+ GIT_AUTHOR_NAME: 'name',
103
+ GIT_AUTHOR_EMAIL: 'email',
104
+ GIT_COMMITTER_NAME: 'name',
105
+ GIT_COMMITTER_EMAIL: 'email',
106
+ } as const
107
+ const missing = Object.entries(names).filter(([name]) => !exposable.has(name))
108
+ if (missing.length === 0) return {}
109
+ const repoIdentity = await resolveGitIdentity(agentDir)
110
+ const identity =
111
+ githubSelf !== null && (repoIdentity === null || (await isFallbackGitIdentity(agentDir, repoIdentity)))
112
+ ? { name: githubSelf.login, email: `${githubSelf.id}+${githubSelf.login}@users.noreply.github.com` }
113
+ : repoIdentity
114
+ if (identity === null) return {}
115
+ return Object.fromEntries(missing.map(([name, field]) => [name, identity[field]]))
116
+ }
117
+
118
+ export function buildRoleScopedConfigEnv(
119
+ agentDir: string,
120
+ hiddenDirs: string[],
121
+ envOverlay: BashEnvOverlay | undefined,
122
+ ): BashEnvOverlay | undefined {
123
+ // Low-trust roles have workspace/ masked. Do not let container-global config
124
+ // env vars point CLIs back at that private surface: apps that honor XDG should
125
+ // still run, but their config must land in the sandbox's per-session /tmp.
126
+ // Trusted/owner have only the unconditional credential-dir masks, not the
127
+ // workspace root mask, so their command broker decides whether to set GWS.
128
+ const workspaceHidden = hiddenDirs.includes(join(agentDir, 'workspace'))
129
+ if (!workspaceHidden) return envOverlay
130
+
131
+ return {
132
+ ...envOverlay,
133
+ XDG_CONFIG_HOME: '/tmp/.config',
134
+ GWS_CONFIG_HOME: '/tmp/.config/gws',
135
+ }
136
+ }
@@ -0,0 +1,70 @@
1
+ import { config } from '@/config/config'
2
+ import { canMountRealProc, getProcBindSafetyVerdict, resolveProcBindSafetyWithRetry } from '@/sandbox'
3
+ // Picks the /proc strategy for a sandboxed bash call. The branch order is:
4
+ // 'real-proc' ONLY when the operator explicitly opted in (sandbox.realProc) AND
5
+ // the kernel permits the mount (canMountRealProc) — it adds PID isolation but
6
+ // needs CAP_SYS_ADMIN (unshare --mount-proc), so it is a deliberate, narrow
7
+ // opt-in; else 'proc-bind' (--ro-bind /proc, NO CAP_SYS_ADMIN) when its userns
8
+ // leak-block is verified safe; else 'tmpfs'. Because sandbox.realProc DEFAULTS
9
+ // FALSE, the first branch is normally skipped and proc-bind is the de-facto
10
+ // default — which is the point: the common path needs no broad outer capability.
11
+ // 'tmpfs' is the last-resort degraded mode where external packages can't run;
12
+ // reached only when proc-bind is DEFINITIVELY unavailable (a real cross-userns
13
+ // environ leak → fail closed) or its safety stays unverifiable after retries.
14
+ //
15
+ // Read from the boot-time `config` snapshot, NOT live getConfig(): sandbox is
16
+ // restart-required, and the strategy MUST track the boot-time CAP_SYS_ADMIN
17
+ // grant. A `typeclaw reload` flipping realProc would otherwise emit `unshare
18
+ // --mount-proc` in a container booted WITHOUT the cap (or vice versa). Both
19
+ // probes are cached process-globally, so this resolves to one spawn per
20
+ // container lifetime regardless of how many bash calls hit it.
21
+ // A tmpfs degrade carries WHY it happened so the caller can pick a permanent vs
22
+ // retryable error. 'definitive': the probe returned a real cross-userns leak
23
+ // ('unsafe') — the ONLY verdict proven permanent, so it fails closed for good.
24
+ // 'unverified': the safety probe never reached a definitive verdict within its
25
+ // retry budget. That covers BOTH a transient load spike AND a durable
26
+ // incapability (no usable namespaces, a bwrap that starts but cannot set up its
27
+ // sandbox): the probe cannot prove a NEGATIVE capability — only a leak is
28
+ // definitive — so a genuinely incapable host also lands here and simply keeps
29
+ // re-degrading on each call. Since 'inconclusive' is never cached, that costs a
30
+ // re-probe but is correct: the only false case is "capable but briefly
31
+ // saturated", which recovers; an incapable host stays degraded either way.
32
+ // Absent when the strategy is not tmpfs.
33
+ export type ProcStrategyResolution =
34
+ | { strategy: 'real-proc' | 'proc-bind'; degradeReason?: undefined }
35
+ | { strategy: 'tmpfs'; degradeReason: 'definitive' | 'unverified' }
36
+
37
+ export async function resolveProcStrategy(): Promise<ProcStrategyResolution> {
38
+ if (config.sandbox.realProc && (await canMountRealProc())) return { strategy: 'real-proc' }
39
+ // Retry an 'inconclusive' proc-bind probe (transient under load) before
40
+ // degrading — a single such hiccup must not break external-package runs on a
41
+ // capable host. 'unsafe' still fails closed with no retry.
42
+ const verdict = await resolveProcBindSafetyWithRetry(
43
+ () => getProcBindSafetyVerdict(),
44
+ (ms) => Bun.sleep(ms),
45
+ )
46
+ if (verdict === 'safe') return { strategy: 'proc-bind' }
47
+ // Degraded last resort: no working /proc strategy. External package runners
48
+ // (bunx/bun run <pkg-bin>) will fail with Bun's opaque "NotDir" because
49
+ // /proc/self/{fd,maps} are absent. Only a proven 'unsafe' (a real cross-userns
50
+ // leak) is DEFINITIVE — warn once (a real operator-facing limit). An
51
+ // 'inconclusive' is reported as retryable upstream and NOT warned (it would cry
52
+ // wolf every boot storm); a durably-incapable host re-degrades quietly here,
53
+ // since the probe cannot distinguish it from transient load.
54
+ if (verdict === 'unsafe') {
55
+ warnTmpfsProcFallbackOnce()
56
+ return { strategy: 'tmpfs', degradeReason: 'definitive' }
57
+ }
58
+ return { strategy: 'tmpfs', degradeReason: 'unverified' }
59
+ }
60
+
61
+ let tmpfsProcFallbackWarned = false
62
+ function warnTmpfsProcFallbackOnce(): void {
63
+ if (tmpfsProcFallbackWarned) return
64
+ tmpfsProcFallbackWarned = true
65
+ console.warn(
66
+ '[sandbox] degraded /proc mode: neither real-proc nor proc-bind is available on this host, ' +
67
+ 'so sandboxed external package runners (bunx / bun run <pkg-bin>) will fail. ' +
68
+ 'This needs a runtime with working user namespaces.',
69
+ )
70
+ }
@@ -0,0 +1,239 @@
1
+ import { join } from 'node:path'
2
+
3
+ import type { GetGithubSelf } from '@/channels/github-token-bridge'
4
+ import { config, getSandboxWritablePathSpecs } from '@/config/config'
5
+ import type { PermissionService } from '@/permissions/permissions'
6
+ import {
7
+ buildSandboxedCommand,
8
+ canWriteAgentRootInSandbox,
9
+ cleanupPrivilegedSandboxRuntime,
10
+ commandNeedsRealProc,
11
+ DEFAULT_SANDBOX_ENV,
12
+ DEPENDENCY_BIN_SANDBOX_DIR,
13
+ ensureBwrapAvailable,
14
+ ensureHiddenMaskTargets,
15
+ ensureSessionTmpDir,
16
+ reconcileDependencyBinWrappers,
17
+ resolveHiddenPaths,
18
+ resolvePrivilegedSandboxRuntime,
19
+ resolveProcSelfExe,
20
+ resolveProtectedZones,
21
+ resolveSandboxSymlinks,
22
+ resolveWritableZones,
23
+ SandboxDegradedProcError,
24
+ SandboxProcProbeUnverifiedError,
25
+ subtractMasked,
26
+ verifyHiddenMaskTargets,
27
+ verifyPrivilegedSandboxRuntime,
28
+ type SandboxMount,
29
+ type SandboxNetwork,
30
+ type SandboxPolicy,
31
+ type DependencyBinReconciliation,
32
+ } from '@/sandbox'
33
+ import { resolveDevSourceMounts } from '@/sandbox/dev-source'
34
+ import { typevaultBashCliPath } from '@/typevault/cli-path'
35
+
36
+ import {
37
+ buildRoleScopedConfigEnv,
38
+ buildSandboxEnvPolicy,
39
+ resolveAgentGitIdentityEnv,
40
+ resolveExposableBashEnvNames,
41
+ spreadSandboxEnv,
42
+ } from './bash-sandbox-env'
43
+ import { resolveProcStrategy, type ProcStrategyResolution } from './bash-sandbox-proc'
44
+ import type { SessionOrigin } from './session-origin'
45
+ export type DeferredBashPreparationResult = {
46
+ command: string
47
+ env?: Record<string, string>
48
+ mount: Extract<SandboxMount, { type: 'ro-bind' }>
49
+ cleanup: () => Promise<void>
50
+ }
51
+ export type DeferredBashPreparation = () => Promise<DeferredBashPreparationResult>
52
+ export type BashSandboxBoundary = {
53
+ ensureAvailable: () => Promise<void>
54
+ buildCommand: typeof buildSandboxedCommand
55
+ resolveProcStrategy?: () => Promise<ProcStrategyResolution>
56
+ resolveRuntime?: typeof resolvePrivilegedSandboxRuntime
57
+ verifyRuntime?: typeof verifyPrivilegedSandboxRuntime
58
+ cleanupRuntime?: typeof cleanupPrivilegedSandboxRuntime
59
+ }
60
+
61
+ const DEFAULT_BASH_SANDBOX_BOUNDARY: BashSandboxBoundary = {
62
+ ensureAvailable: ensureBwrapAvailable,
63
+ buildCommand: buildSandboxedCommand,
64
+ }
65
+
66
+ type BashFilesystemPolicyOptions = {
67
+ agentDir: string
68
+ canWriteAgentRoot: boolean
69
+ masks: { dirs: string[]; files: string[] }
70
+ writable: { dirs: string[]; files: string[] }
71
+ protected: { dirs: string[]; files: string[] }
72
+ }
73
+
74
+ export type PreparedBashSandbox = {
75
+ commandString: string
76
+ policy: SandboxPolicy
77
+ verify: () => Promise<void>
78
+ cleanup: () => Promise<void>
79
+ spawnEnv: Record<string, string>
80
+ dependencyBins?: DependencyBinReconciliation
81
+ withheld: {
82
+ paths: { dirs: string[]; files: string[] }
83
+ envNames: string[]
84
+ }
85
+ }
86
+
87
+ export function buildBashFilesystemPolicy(options: BashFilesystemPolicyOptions) {
88
+ const { agentDir, canWriteAgentRoot, masks, writable, protected: protectedZones } = options
89
+ if (canWriteAgentRoot) {
90
+ return { writableRoot: { dir: agentDir }, masks, protected: protectedZones }
91
+ }
92
+ return { masks, writable, protected: protectedZones }
93
+ }
94
+
95
+ export type BashSandboxReveal = NonNullable<SandboxPolicy['reveal']>
96
+
97
+ export type BashSandboxRequest = {
98
+ readonly getGithubSelf?: GetGithubSelf
99
+ readonly command: string
100
+ readonly permissions: PermissionService
101
+ readonly origin: SessionOrigin | undefined
102
+ readonly agentDir: string
103
+ readonly sessionId: string
104
+ readonly envOverlay?: Record<string, string>
105
+ readonly envWithhold?: string[]
106
+ readonly deferredPreparation?: DeferredBashPreparation
107
+ readonly reveal?: BashSandboxReveal
108
+ readonly boundary?: BashSandboxBoundary
109
+ readonly network?: SandboxNetwork
110
+ }
111
+
112
+ // Shared preparation for model bash and eval. The caller owns verification
113
+ // immediately before spawn and cleanup after the process has exited.
114
+ export async function prepareBashSandbox(options: BashSandboxRequest): Promise<PreparedBashSandbox> {
115
+ const {
116
+ command: originalCommand,
117
+ permissions,
118
+ origin,
119
+ agentDir,
120
+ sessionId,
121
+ envOverlay,
122
+ envWithhold,
123
+ deferredPreparation,
124
+ } = options
125
+ const boundary = options.boundary ?? DEFAULT_BASH_SANDBOX_BOUNDARY
126
+ let preparation: DeferredBashPreparationResult | undefined
127
+ let privilegedRuntime: Awaited<ReturnType<typeof resolvePrivilegedSandboxRuntime>> | undefined
128
+ const cleanup = async (): Promise<void> => {
129
+ const tasks: Promise<void>[] = []
130
+ if (privilegedRuntime !== undefined) {
131
+ tasks.push((boundary.cleanupRuntime ?? cleanupPrivilegedSandboxRuntime)(privilegedRuntime))
132
+ }
133
+ if (preparation !== undefined) tasks.push(preparation.cleanup())
134
+ const outcomes = await Promise.allSettled(tasks)
135
+ const failure = outcomes.find((outcome) => outcome.status === 'rejected')
136
+ if (failure?.status === 'rejected') throw failure.reason
137
+ }
138
+ try {
139
+ preparation = await deferredPreparation?.()
140
+ const command = preparation?.command ?? originalCommand
141
+ const envNames = resolveExposableBashEnvNames(agentDir)
142
+ const gitIdentityEnv = await resolveAgentGitIdentityEnv(agentDir, envNames.exposable, options.getGithubSelf?.())
143
+ const mergedEnvOverlay = { ...gitIdentityEnv, ...envOverlay, ...preparation?.env }
144
+ const preparedEnvOverlay = Object.keys(mergedEnvOverlay).length > 0 ? mergedEnvOverlay : undefined
145
+ const { dirs, files } = resolveHiddenPaths(permissions, origin, agentDir)
146
+ const sandboxEnvOverlay = buildRoleScopedConfigEnv(agentDir, dirs, preparedEnvOverlay)
147
+ const effectiveEnvWithhold = (envWithhold ?? []).filter((name) => !Object.hasOwn(sandboxEnvOverlay ?? {}, name))
148
+ const maskTargets = await ensureHiddenMaskTargets({ dirs, files })
149
+ await boundary.ensureAvailable()
150
+ const sessionTmp = await ensureSessionTmpDir(sessionId)
151
+ const dependencyBins = await reconcileDependencyBinWrappers({
152
+ agentDir,
153
+ sessionTmp,
154
+ ...(config.typevault.enabled ? { runtimeBins: { typevault: typevaultBashCliPath() } } : {}),
155
+ })
156
+ const writable = subtractMasked(await resolveWritableZones(agentDir, getSandboxWritablePathSpecs(config)), {
157
+ dirs,
158
+ files,
159
+ })
160
+ const writableRoot = canWriteAgentRootInSandbox(permissions, origin)
161
+ const baseProtectedZones =
162
+ writableRoot || writable.dirs.includes(join(agentDir, '.git'))
163
+ ? subtractMasked(await resolveProtectedZones(agentDir), { dirs, files })
164
+ : { dirs: [], files: [] }
165
+ const protectedZones = {
166
+ dirs: baseProtectedZones.dirs,
167
+ files: [...new Set([...baseProtectedZones.files, ...dependencyBins.protectedFiles])],
168
+ }
169
+ const writableDirSet = new Set(writable.dirs)
170
+ const sandboxHome = DEFAULT_SANDBOX_ENV.HOME ?? '/tmp'
171
+ const symlinks = resolveSandboxSymlinks(agentDir, config.sandbox.symlinks, sandboxHome).filter((op) =>
172
+ writableDirSet.has(op.target),
173
+ )
174
+ const { strategy: proc, degradeReason } = await (boundary.resolveProcStrategy ?? resolveProcStrategy)()
175
+ if (proc === 'tmpfs' && commandNeedsRealProc(command)) {
176
+ throw degradeReason === 'unverified' ? new SandboxProcProbeUnverifiedError() : new SandboxDegradedProcError()
177
+ }
178
+ privilegedRuntime = await (boundary.resolveRuntime ?? resolvePrivilegedSandboxRuntime)({
179
+ agentDir,
180
+ command,
181
+ env: sandboxEnvOverlay,
182
+ })
183
+ await verifyHiddenMaskTargets(maskTargets)
184
+ const devSourceMounts = await resolveDevSourceMounts(agentDir)
185
+ const policy: SandboxPolicy = {
186
+ mounts: [
187
+ { type: 'ro-bind', source: agentDir, dest: agentDir },
188
+ { type: 'bind', source: sessionTmp, dest: '/tmp' },
189
+ // `/tmp` is writable, but PATH entries must remain runtime-owned for
190
+ // the lifetime of this command. Last-op-wins makes this narrow re-bind
191
+ // read-only without adding any broader filesystem exposure.
192
+ { type: 'ro-bind', source: dependencyBins.wrapperDir, dest: DEPENDENCY_BIN_SANDBOX_DIR },
193
+ // The running Bun ELF is runtime-owned, not a model-selected path.
194
+ // Dev/CI installations may place it outside /usr; expose only the
195
+ // executable, never its parent directory, under every proc strategy.
196
+ { type: 'ro-bind', source: process.execPath, dest: process.execPath },
197
+ ...devSourceMounts,
198
+ ...(privilegedRuntime?.mounts ?? []),
199
+ ...(preparation === undefined ? [] : [preparation.mount]),
200
+ ],
201
+ ...buildBashFilesystemPolicy({
202
+ agentDir,
203
+ canWriteAgentRoot: writableRoot,
204
+ masks: maskTargets,
205
+ writable,
206
+ protected: protectedZones,
207
+ }),
208
+ ...(options.reveal === undefined ? {} : { reveal: options.reveal }),
209
+ symlinks,
210
+ network: options.network ?? 'inherit',
211
+ cwd: agentDir,
212
+ proc,
213
+ procSelfExe: resolveProcSelfExe(),
214
+ ...spreadSandboxEnv(
215
+ buildSandboxEnvPolicy(sandboxEnvOverlay, privilegedRuntime?.env, envNames.exposable, envWithhold),
216
+ ),
217
+ }
218
+ const { commandString, spawnEnv } = boundary.buildCommand(command, policy)
219
+ // The overlay carries command-scoped secret VALUES (e.g. a per-repo GH_TOKEN)
220
+ // that live in neither process.env nor argv; resolveSpawnEnv snapshots
221
+ // inherited names from process.env only, so merge the overlay values in here
222
+ // to complete the exact bwrap-parent env.
223
+ const mergedSpawnEnv =
224
+ spawnEnv !== undefined && sandboxEnvOverlay !== undefined ? { ...spawnEnv, ...sandboxEnvOverlay } : spawnEnv
225
+ const runtimeForResult = privilegedRuntime
226
+ return {
227
+ commandString,
228
+ policy,
229
+ verify: async () => (boundary.verifyRuntime ?? verifyPrivilegedSandboxRuntime)(runtimeForResult),
230
+ cleanup,
231
+ spawnEnv: mergedSpawnEnv,
232
+ dependencyBins,
233
+ withheld: { paths: maskTargets, envNames: [...new Set([...envNames.withheld, ...effectiveEnvWithhold])] },
234
+ }
235
+ } catch (error) {
236
+ await cleanup()
237
+ throw error
238
+ }
239
+ }
@@ -9,35 +9,47 @@ import { SettingsManager } from '@earendil-works/pi-coding-agent'
9
9
  // drifts to ~94% on a 256K window and ~98% on 1M.
10
10
  export const COMPACTION_TRIGGER_PERCENT = 0.8
11
11
 
12
- // Absolute ceiling on the compaction trigger, independent of window size. The
12
+ // Default ceiling on the compaction trigger, independent of window size. The
13
13
  // window-relative trigger alone optimizes for overflow avoidance, not token
14
14
  // cost: at 80% of a large window a session accumulates ~160K (200K window) to
15
15
  // ~800K (1M window) tokens of history that get re-shipped as `cacheRead` every
16
16
  // turn before compaction ever fires. Capping the trigger bounds that
17
17
  // steady-state re-read on big-window models; `min()` keeps the 80% behavior on
18
- // small ones. 64K is 3x keepRecent (invariant asserted in the test), leaving
19
- // growth room after a compaction so it does not retrigger immediately.
20
- export const COMPACTION_ABSOLUTE_TRIGGER_TOKENS = 64_000
18
+ // small ones. The ceiling was 64K and is now 200K: at 64K a long investigation
19
+ // compacted every few turns (six times in forty minutes in one production
20
+ // channel session), and each summary dropped the raw evidence later turns had
21
+ // to reason over. Cached re-reads are cheap; losing the working set costs
22
+ // correctness. 200K stays 10x keepRecent (the >=3x invariant is asserted in
23
+ // the test), so a compaction never retriggers immediately. Each agent can set
24
+ // its own ceiling for its workload with `compaction.maxTriggerTokens` in
25
+ // typeclaw.json; this value is the default.
26
+ export const COMPACTION_ABSOLUTE_TRIGGER_TOKENS = 200_000
21
27
 
22
28
  // Tokens to keep in the recent window after compaction. Fixed (not a
23
29
  // percentage) because "recent context" is a property of conversation shape, not
24
30
  // model capacity. Mirrors pi's DEFAULT_COMPACTION_SETTINGS.keepRecentTokens.
25
31
  export const COMPACTION_KEEP_RECENT_TOKENS = 20_000
26
32
 
27
- export function compactionTriggerTokens<TApi extends KnownApi>(model: Model<TApi>): number {
33
+ export function compactionTriggerTokens<TApi extends KnownApi>(
34
+ model: Model<TApi>,
35
+ maxTriggerTokens: number = COMPACTION_ABSOLUTE_TRIGGER_TOKENS,
36
+ ): number {
28
37
  const windowRelative = Math.round(model.contextWindow * COMPACTION_TRIGGER_PERCENT)
29
- return Math.min(windowRelative, COMPACTION_ABSOLUTE_TRIGGER_TOKENS)
38
+ return Math.min(windowRelative, maxTriggerTokens)
30
39
  }
31
40
 
32
- export function reserveTokensForModel<TApi extends KnownApi>(model: Model<TApi>): number {
33
- return Math.max(1, model.contextWindow - compactionTriggerTokens(model))
41
+ export function reserveTokensForModel<TApi extends KnownApi>(model: Model<TApi>, maxTriggerTokens?: number): number {
42
+ return Math.max(1, model.contextWindow - compactionTriggerTokens(model, maxTriggerTokens))
34
43
  }
35
44
 
36
- export function createCompactionSettingsManager<TApi extends KnownApi>(model: Model<TApi>): SettingsManager {
45
+ export function createCompactionSettingsManager<TApi extends KnownApi>(
46
+ model: Model<TApi>,
47
+ maxTriggerTokens?: number,
48
+ ): SettingsManager {
37
49
  return SettingsManager.inMemory({
38
50
  compaction: {
39
51
  enabled: true,
40
- reserveTokens: reserveTokensForModel(model),
52
+ reserveTokens: reserveTokensForModel(model, maxTriggerTokens),
41
53
  keepRecentTokens: COMPACTION_KEEP_RECENT_TOKENS,
42
54
  },
43
55
  })
@@ -10,7 +10,7 @@ const IDLE_COMPACTION_TRIGGER_RATIO = 0.9
10
10
 
11
11
  export function attachIdleCompaction(
12
12
  session: AgentSession,
13
- options: { schedule?: IdleSchedule; onApplied?: () => void } = {},
13
+ options: { schedule?: IdleSchedule; onApplied?: () => void; maxTriggerTokens?: number } = {},
14
14
  ): () => void {
15
15
  const schedule = options.schedule ?? scheduleIdle
16
16
  // Capture before turn drivers install output caps that apply only to replies.
@@ -42,7 +42,7 @@ export function attachIdleCompaction(
42
42
  !model ||
43
43
  leaf === attemptedLeaf ||
44
44
  tokens == null ||
45
- tokens < compactionTriggerTokens(model) * IDLE_COMPACTION_TRIGGER_RATIO
45
+ tokens < compactionTriggerTokens(model, options.maxTriggerTokens) * IDLE_COMPACTION_TRIGGER_RATIO
46
46
  )
47
47
  return
48
48
 
@@ -95,7 +95,11 @@ export function attachIdleCompaction(
95
95
  // can be disposed without starting a summary they will never use.
96
96
  const tokens = session.getContextUsage()?.tokens
97
97
  const model = session.model
98
- if (model && tokens != null && tokens >= compactionTriggerTokens(model) * IDLE_COMPACTION_TRIGGER_RATIO) {
98
+ if (
99
+ model &&
100
+ tokens != null &&
101
+ tokens >= compactionTriggerTokens(model, options.maxTriggerTokens) * IDLE_COMPACTION_TRIGGER_RATIO
102
+ ) {
99
103
  cancelScheduled = schedule(run)
100
104
  }
101
105
  } else if (event.type === 'agent_start' || event.type === 'compaction_start' || event.type === 'entry_appended') {