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,211 @@
1
+ import { CHANNEL_FIELD_ENV } from '@/secrets/defaults'
2
+
3
+ type ActionAllowlist = Readonly<Record<string, readonly string[] | null>>
4
+
5
+ const AUTH_READ_ONLY = ['status', 'list'] as const
6
+
7
+ // Bot-token agent-messenger CLIs whose credential TypeClaw already holds as a
8
+ // channel adapter token in secrets.json. User-account platforms carry refresh
9
+ // and session state the CLI would write back, so they are not minted here.
10
+ //
11
+ // `actions` lists, per command group, the verified actions that never read a
12
+ // local path (null = the group itself is the action). Everything else is
13
+ // absent on purpose: the `file` groups and Telegram's `message upload` read
14
+ // the path they are given, so they could upload the minted profile; config
15
+ // mutators (`auth set`, `server switch`) cannot write the read-only mount.
16
+ export const BOT_PLATFORMS = {
17
+ slackbot: {
18
+ tokenEnv: CHANNEL_FIELD_ENV['slack-bot'].botToken,
19
+ globalValueOptions: ['--bot'],
20
+ actions: {
21
+ auth: AUTH_READ_ONLY,
22
+ channel: ['list', 'info'],
23
+ message: ['send', 'list', 'get', 'edit', 'delete', 'typing', 'replies'],
24
+ reaction: ['add', 'remove'],
25
+ user: ['list', 'info'],
26
+ whoami: null,
27
+ },
28
+ },
29
+ discordbot: {
30
+ tokenEnv: CHANNEL_FIELD_ENV['discord-bot'].token,
31
+ globalValueOptions: ['--bot', '--server'],
32
+ actions: {
33
+ auth: AUTH_READ_ONLY,
34
+ channel: ['list', 'info'],
35
+ message: ['send', 'list', 'get', 'edit', 'delete', 'replies'],
36
+ reaction: ['list', 'add', 'remove'],
37
+ server: ['list', 'current', 'info'],
38
+ snapshot: null,
39
+ thread: ['list', 'create', 'archive'],
40
+ user: ['list', 'info'],
41
+ whoami: null,
42
+ },
43
+ },
44
+ telegrambot: {
45
+ tokenEnv: CHANNEL_FIELD_ENV['telegram-bot'].token,
46
+ globalValueOptions: ['--bot'],
47
+ actions: {
48
+ auth: AUTH_READ_ONLY,
49
+ chat: ['info', 'member'],
50
+ message: ['send', 'edit', 'delete', 'forward'],
51
+ reaction: ['set', 'clear'],
52
+ whoami: null,
53
+ },
54
+ },
55
+ webexbot: {
56
+ tokenEnv: CHANNEL_FIELD_ENV['webex-bot'].token,
57
+ globalValueOptions: ['--bot'],
58
+ actions: {
59
+ auth: AUTH_READ_ONLY,
60
+ listen: null,
61
+ member: ['list'],
62
+ message: ['send', 'reply', 'replies', 'dm', 'list', 'get', 'delete', 'edit'],
63
+ snapshot: null,
64
+ space: ['list', 'info'],
65
+ user: ['list', 'info'],
66
+ whoami: null,
67
+ },
68
+ },
69
+ } as const satisfies Record<
70
+ string,
71
+ { tokenEnv: string; globalValueOptions: readonly string[]; actions: ActionAllowlist }
72
+ >
73
+
74
+ export type BotPlatform = keyof typeof BOT_PLATFORMS
75
+
76
+ export type AgentMessengerCommandDecision =
77
+ | { kind: 'mint'; platform: BotPlatform; args: string[] }
78
+ | { kind: 'refuse'; platform: BotPlatform; reason: string }
79
+ | { kind: 'ignore'; platform?: BotPlatform }
80
+
81
+ const GLOBAL_FLAGS = new Set(['--pretty'])
82
+ const CREDENTIAL_MUTATING_AUTH = new Set(['set', 'clear', 'use', 'remove'])
83
+
84
+ // The minted profile is readable by every process in the sandbox, so it may only
85
+ // reach ONE CLI process (which the broker launches itself) whose argv cannot name
86
+ // a local file to read. Anything else is refused or left alone.
87
+ export function analyzeAgentMessengerCommand(command: string): AgentMessengerCommandDecision {
88
+ const scanned = scanWords(command)
89
+ const invocation = resolveInvocation(scanned.words)
90
+ if (invocation === undefined) return { kind: 'ignore' }
91
+ const { platform, args } = invocation
92
+ if (!scanned.safe) {
93
+ return {
94
+ kind: 'refuse',
95
+ platform,
96
+ reason:
97
+ `TypeClaw can lend this agent's ${platform} channel token to agent-${platform} only as a single bare command. ` +
98
+ 'Pipes, `&&`, `;`, redirections, `$(...)`, and backslash escapes are not allowed because another process in the same command could read the lent credential. ' +
99
+ `Run \`agent-${platform} ...\` on its own, then process its output in a separate command.`,
100
+ }
101
+ }
102
+
103
+ const spec = BOT_PLATFORMS[platform]
104
+ const valueOptions = new Set<string>(spec.globalValueOptions)
105
+ let index = 0
106
+ while (index < args.length && (args[index] as string).startsWith('-')) {
107
+ const arg = args[index] as string
108
+ const name = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg
109
+ if (GLOBAL_FLAGS.has(arg)) index += 1
110
+ else if (valueOptions.has(name) && name !== arg) index += 1
111
+ else if (valueOptions.has(arg) && index + 1 < args.length) index += 2
112
+ else if (arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V')
113
+ return { kind: 'ignore', platform }
114
+ else return refuseShape(platform, `the leading option \`${arg}\` is not one TypeClaw can verify`)
115
+ }
116
+
117
+ const group = args[index]
118
+ if (group === undefined || group === 'help') return { kind: 'ignore', platform }
119
+ const actions = (spec.actions as ActionAllowlist)[group]
120
+ if (group === 'auth' && CREDENTIAL_MUTATING_AUTH.has(args[index + 1] ?? '')) return { kind: 'ignore', platform }
121
+ if (actions === undefined) return refuseShape(platform, `\`${group}\` is not an allowed command group`)
122
+ if (actions === null) return { kind: 'mint', platform, args }
123
+ const action = args[index + 1]
124
+ if (action === undefined || action.startsWith('-')) return { kind: 'ignore', platform }
125
+ if (!actions.includes(action)) return refuseShape(platform, `\`${group} ${action}\` can read a local file`)
126
+ return { kind: 'mint', platform, args }
127
+ }
128
+
129
+ function refuseShape(platform: BotPlatform, detail: string): AgentMessengerCommandDecision {
130
+ const allowed = Object.entries(BOT_PLATFORMS[platform].actions as ActionAllowlist)
131
+ .map(([group, actions]) => (actions === null ? group : `${group} ${actions.join('|')}`))
132
+ .join(', ')
133
+ return {
134
+ kind: 'refuse',
135
+ platform,
136
+ reason:
137
+ `TypeClaw lends this agent's ${platform} channel token only to agent-${platform} commands that cannot read local files, ` +
138
+ `and ${detail}. Allowed: ${allowed}. Leading options may only be ${['--pretty', ...BOT_PLATFORMS[platform].globalValueOptions].join(', ')}.`,
139
+ }
140
+ }
141
+
142
+ function resolveInvocation(words: readonly string[]): { platform: BotPlatform; args: string[] } | undefined {
143
+ let index = 0
144
+ if (words[0] === 'bunx') index = 1
145
+ else if (words[0] === 'bun' && words[1] === 'x') index = 2
146
+ const bin = words[index]
147
+ if (bin === undefined) return undefined
148
+ // `bunx agent-<platform>` resolves an npm package of that name, not the
149
+ // agent-messenger package, so only the umbrella package is accepted there.
150
+ if (index === 0 && bin.startsWith('agent-')) {
151
+ const platform = bin.slice('agent-'.length)
152
+ if (isBotPlatform(platform)) return { platform, args: words.slice(1) }
153
+ }
154
+ if (bin === 'agent-messenger' || (index === 0 && bin === 'amsg')) {
155
+ const platform = words[index + 1]
156
+ if (isBotPlatform(platform)) return { platform, args: words.slice(index + 2) }
157
+ }
158
+ return undefined
159
+ }
160
+
161
+ function isBotPlatform(value: string | undefined): value is BotPlatform {
162
+ return value !== undefined && Object.hasOwn(BOT_PLATFORMS, value)
163
+ }
164
+
165
+ const UNQUOTED_UNSAFE = new Set([';', '&', '|', '<', '>', '(', ')', '$', '`', '\\', '\n', '\r'])
166
+ const DOUBLE_QUOTED_UNSAFE = new Set(['$', '`', '\\'])
167
+
168
+ // A conservative word splitter: it does not emulate bash, it only proves the
169
+ // command has no shell construct that could start a second process or feed the
170
+ // CLI a file. Any doubt marks the command unsafe. Unquoted globs are rejected
171
+ // too, because the broker re-quotes argv and bash would otherwise expand them.
172
+ function scanWords(command: string): { words: string[]; safe: boolean } {
173
+ const words: string[] = []
174
+ let current = ''
175
+ let inWord = false
176
+ let quote: "'" | '"' | undefined
177
+ let safe = true
178
+ for (const char of command.trim()) {
179
+ if (quote === "'") {
180
+ if (char === "'") quote = undefined
181
+ else current += char
182
+ continue
183
+ }
184
+ if (quote === '"') {
185
+ if (char === '"') quote = undefined
186
+ else {
187
+ if (DOUBLE_QUOTED_UNSAFE.has(char)) safe = false
188
+ current += char
189
+ }
190
+ continue
191
+ }
192
+ if (char === "'" || char === '"') {
193
+ quote = char
194
+ inWord = true
195
+ continue
196
+ }
197
+ if (char === ' ' || char === '\t') {
198
+ if (inWord) words.push(current)
199
+ current = ''
200
+ inWord = false
201
+ continue
202
+ }
203
+ if (UNQUOTED_UNSAFE.has(char) || char === '*' || char === '?' || char === '[') safe = false
204
+ if (char === '#' && !inWord) break
205
+ current += char
206
+ inWord = true
207
+ }
208
+ if (quote !== undefined) safe = false
209
+ if (inWord) words.push(current)
210
+ return { words, safe }
211
+ }
@@ -0,0 +1,186 @@
1
+ import { existsSync } from 'node:fs'
2
+ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
3
+ import { tmpdir } from 'node:os'
4
+ import { dirname, join, posix, sep } from 'node:path'
5
+
6
+ import {
7
+ type DeferredBashPreparation,
8
+ type DeferredBashPreparationResult,
9
+ TYPECLAW_INTERNAL_BASH_ENV,
10
+ TYPECLAW_INTERNAL_BASH_PREPARE,
11
+ } from '@/agent/plugin-tools'
12
+ import type { SessionOrigin } from '@/agent/session-origin'
13
+ import { CORE_PERMISSIONS } from '@/permissions/builtins'
14
+ import type { PermissionService } from '@/permissions/permissions'
15
+ import { definePlugin, type Hooks } from '@/plugin'
16
+ import { resolveHiddenPaths } from '@/sandbox/hidden-paths'
17
+
18
+ import { analyzeAgentMessengerCommand, BOT_PLATFORMS, type BotPlatform } from './command'
19
+
20
+ // Fixed and outside every agent/tmp bind: each bwrap call gets its own mount
21
+ // namespace, so a command without a minted profile never sees this path.
22
+ export const MINTED_PROFILE_SANDBOX_DIR = '/run/typeclaw/agent-messenger'
23
+
24
+ const PROFILE_ID = 'typeclaw'
25
+ const PROFILE_NAME = 'TypeClaw channel bot'
26
+
27
+ export default definePlugin({
28
+ plugin: async (ctx) => ({
29
+ hooks: {
30
+ 'tool.before': agentMessengerMintHook({
31
+ agentDir: ctx.agentDir,
32
+ permissions: ctx.permissions,
33
+ env: process.env,
34
+ }),
35
+ },
36
+ }),
37
+ })
38
+
39
+ export function agentMessengerMintHook(options: {
40
+ agentDir: string
41
+ permissions: PermissionService
42
+ env: NodeJS.ProcessEnv
43
+ cliEntrypoint?: (platform: BotPlatform) => string
44
+ }): NonNullable<Hooks['tool.before']> {
45
+ return async (event) => {
46
+ if (event.tool !== 'bash') return
47
+ const command = event.args.command
48
+ if (typeof command !== 'string') return
49
+ const decision = analyzeAgentMessengerCommand(command)
50
+ if (decision.platform === undefined) return
51
+ const token = options.env[BOT_PLATFORMS[decision.platform].tokenEnv]
52
+ if (token === undefined || token === '') return
53
+ if (!canUseChannelToken(options.permissions, event.origin)) return
54
+ const operatorProfileDir = visibleOperatorProfileDir(options, event.origin, decision.platform)
55
+ if (operatorProfileDir !== undefined) {
56
+ // The container-level AGENT_MESSENGER_CONFIG_DIR is not inherited by
57
+ // sandboxed bash, so point the CLI at the profile this role can see.
58
+ const existing = event.args[TYPECLAW_INTERNAL_BASH_ENV]
59
+ event.args[TYPECLAW_INTERNAL_BASH_ENV] = {
60
+ ...(existing !== null && typeof existing === 'object' ? (existing as Record<string, string>) : {}),
61
+ AGENT_MESSENGER_CONFIG_DIR: operatorProfileDir,
62
+ }
63
+ return
64
+ }
65
+ if (decision.kind === 'refuse') return { block: true, reason: decision.reason }
66
+ if (decision.kind !== 'mint') return
67
+ // One deferred preparation per call; never clobber another broker's.
68
+ if (event.args[TYPECLAW_INTERNAL_BASH_PREPARE] !== undefined) return
69
+ const entrypoint = (options.cliEntrypoint ?? resolveCliEntrypoint)(decision.platform)
70
+ event.args[TYPECLAW_INTERNAL_BASH_PREPARE] = mintProfilePreparation(
71
+ decision.platform,
72
+ decision.args,
73
+ token,
74
+ entrypoint,
75
+ )
76
+ }
77
+ }
78
+
79
+ // Two gates, both required. The credential gate is the one github-cli-auth uses
80
+ // to lend a long-lived PAT, since a channel bot token is equally broad. The
81
+ // private-surface gate is channel_read's gate for reading another conversation,
82
+ // since the token reads any chat the bot is in.
83
+ function canUseChannelToken(permissions: PermissionService, origin: SessionOrigin | undefined): boolean {
84
+ const has = (permission: string): boolean => permissions.has(origin, permission)
85
+ const canUseCredential = has(CORE_PERMISSIONS.fsSeeSecrets) || has('security.bypass.medium')
86
+ const canReadOtherConversations =
87
+ has(CORE_PERMISSIONS.fsSeePrivate) || has('security.bypass.low') || has('security.bypass.medium')
88
+ return canUseCredential && canReadOtherConversations
89
+ }
90
+
91
+ // An operator who authenticated the CLI themselves keeps their profile (and any
92
+ // extra bots in it); minting would hide it behind a single-bot profile.
93
+ function visibleOperatorProfileDir(
94
+ options: { agentDir: string; permissions: PermissionService; env: NodeJS.ProcessEnv },
95
+ origin: SessionOrigin | undefined,
96
+ platform: BotPlatform,
97
+ ): string | undefined {
98
+ const configDir = options.env.AGENT_MESSENGER_CONFIG_DIR
99
+ if (configDir === undefined || configDir === '') return undefined
100
+ if (configDir !== options.agentDir && !configDir.startsWith(`${options.agentDir}${sep}`)) return undefined
101
+ const hidden = resolveHiddenPaths(options.permissions, origin, options.agentDir).dirs
102
+ if (hidden.some((dir) => configDir === dir || configDir.startsWith(`${dir}${sep}`))) return undefined
103
+ return existsSync(join(configDir, `${platform}-credentials.json`)) ? configDir : undefined
104
+ }
105
+
106
+ export function resolveCliEntrypoint(platform: BotPlatform): string {
107
+ const packageJson = Bun.resolveSync('agent-messenger/package.json', import.meta.dir)
108
+ return join(dirname(packageJson), 'dist', 'src', 'platforms', platform, 'cli.js')
109
+ }
110
+
111
+ // The CLI is launched by the broker, not through PATH or a dependency-bin
112
+ // wrapper: the runtime's own bun runs the resolved agent-messenger entrypoint
113
+ // (under the read-only node_modules) from an empty read-only cwd and HOME, so a
114
+ // model-written bunfig.toml preload, .env, or PATH shim cannot run inside the
115
+ // process that holds the minted profile.
116
+ export function buildCliLaunch(
117
+ root: string,
118
+ entrypoint: string,
119
+ args: readonly string[],
120
+ ): { command: string; env: Record<string, string> } {
121
+ // posix: the sandbox is always Linux, even when the host stage is Windows.
122
+ const home = posix.join(root, 'home')
123
+ return {
124
+ command: `cd ${shellQuote(home)} && exec ${[process.execPath, entrypoint, ...args].map(shellQuote).join(' ')}`,
125
+ env: {
126
+ AGENT_MESSENGER_CONFIG_DIR: posix.join(root, 'config'),
127
+ HOME: home,
128
+ XDG_CONFIG_HOME: home,
129
+ BUN_OPTIONS: '',
130
+ NODE_OPTIONS: '',
131
+ },
132
+ }
133
+ }
134
+
135
+ function mintProfilePreparation(
136
+ platform: BotPlatform,
137
+ args: readonly string[],
138
+ token: string,
139
+ entrypoint: string,
140
+ ): DeferredBashPreparation {
141
+ return async (): Promise<DeferredBashPreparationResult> => {
142
+ if (!existsSync(entrypoint)) {
143
+ throw new Error(`agent-messenger ${platform} CLI entrypoint not found at ${entrypoint}`)
144
+ }
145
+ const dir = await mkdtemp(join(tmpdir(), 'typeclaw-agent-messenger-'))
146
+ try {
147
+ await mkdir(join(dir, 'home'), { mode: 0o700 })
148
+ await mkdir(join(dir, 'config'), { mode: 0o700 })
149
+ await writeFile(
150
+ join(dir, 'config', `${platform}-credentials.json`),
151
+ JSON.stringify(buildProfile(platform, token)),
152
+ { mode: 0o600, flag: 'wx' },
153
+ )
154
+ } catch (error) {
155
+ await rm(dir, { recursive: true, force: true })
156
+ throw error
157
+ }
158
+ return {
159
+ ...buildCliLaunch(MINTED_PROFILE_SANDBOX_DIR, entrypoint, args),
160
+ mount: { type: 'ro-bind', source: dir, dest: MINTED_PROFILE_SANDBOX_DIR },
161
+ cleanup: () => rm(dir, { recursive: true, force: true }),
162
+ }
163
+ }
164
+ }
165
+
166
+ export function buildProfile(platform: BotPlatform, token: string): Record<string, unknown> {
167
+ const bot = { bot_id: PROFILE_ID, bot_name: PROFILE_NAME, token }
168
+ switch (platform) {
169
+ case 'slackbot':
170
+ return {
171
+ current: { workspace_id: PROFILE_ID, bot_id: PROFILE_ID },
172
+ workspaces: {
173
+ [PROFILE_ID]: { workspace_id: PROFILE_ID, workspace_name: PROFILE_NAME, bots: { [PROFILE_ID]: bot } },
174
+ },
175
+ }
176
+ case 'discordbot':
177
+ return { current: { bot_id: PROFILE_ID }, bots: { [PROFILE_ID]: bot }, current_server: null, servers: {} }
178
+ case 'telegrambot':
179
+ case 'webexbot':
180
+ return { current: { bot_id: PROFILE_ID }, bots: { [PROFILE_ID]: bot } }
181
+ }
182
+ }
183
+
184
+ function shellQuote(value: string): string {
185
+ return `'${value.replaceAll("'", `'"'"'`)}'`
186
+ }
@@ -73,6 +73,7 @@ export default definePlugin({
73
73
  const maintenance = ctx.config.maintenance
74
74
 
75
75
  const activeTurns = new Set<string>()
76
+ const commitMessages: CommitMessageMemo = {}
76
77
  let idleTimer: ReturnType<typeof setTimeout> | null = null
77
78
  let pendingFire = false
78
79
  let inFlight = false
@@ -133,7 +134,7 @@ export default definePlugin({
133
134
  payloadSchema: runnerPayloadSchema,
134
135
  inFlightKey: (payload) => payload.agentDir,
135
136
  handler: async (sctx) => {
136
- const result = await runBackupOnce(sctx.payload, ctx)
137
+ const result = await runBackupOnce(sctx.payload, ctx, commitMessages)
137
138
  const summary = describeResult(result)
138
139
  ctx.logger.info(`[backup] ${summary}`)
139
140
  },
@@ -180,6 +181,7 @@ async function runBackupOnce(
180
181
  spawnSubagent: PluginContext['spawnSubagent']
181
182
  github: PluginContext['github']
182
183
  },
184
+ commitMessages: CommitMessageMemo,
183
185
  ): Promise<BackupResult> {
184
186
  const messagePath = messageFilePath(payload.agentDir)
185
187
  await ensureMessageDir(messagePath)
@@ -205,6 +207,8 @@ async function runBackupOnce(
205
207
  gitSpawn,
206
208
  pushEnv,
207
209
  pickCommitMessage: async ({ status, diffstat }: { status: string; diffstat: string }): Promise<string> => {
210
+ const key = `${status}\0${diffstat}`
211
+ if (commitMessages.last?.key === key) return commitMessages.last.message
208
212
  await cleanupMessageFile(messagePath)
209
213
  const messagePayload: CommitMessagePayload = {
210
214
  agentDir: payload.agentDir,
@@ -221,7 +225,11 @@ async function runBackupOnce(
221
225
  }
222
226
  const written = await readMessageFile(messagePath)
223
227
  await cleanupMessageFile(messagePath)
224
- return written ?? 'chore: backup'
228
+ if (written === null) return FALLBACK_COMMIT_MESSAGE
229
+ // The message subagent writes this same fallback when its own session
230
+ // fails, so it is never remembered: the next run retries generation.
231
+ if (written.trim() !== FALLBACK_COMMIT_MESSAGE) commitMessages.last = { key, message: written }
232
+ return written
225
233
  },
226
234
  diagnoseFailure: async (input: {
227
235
  cwd: string
@@ -265,6 +273,13 @@ async function runBackupOnce(
265
273
  return result
266
274
  }
267
275
 
276
+ // A commit that keeps failing (e.g. no git identity) leaves the same dirty set
277
+ // behind, and every idle window would otherwise pay another uncacheable LLM call
278
+ // for the same message. Reused only for byte-identical status + diffstat.
279
+ type CommitMessageMemo = { last?: { key: string; message: string } }
280
+
281
+ const FALLBACK_COMMIT_MESSAGE = 'chore: backup'
282
+
268
283
  // True when a local commit was created this run, regardless of the push outcome.
269
284
  // The commit is made before push recovery, so `push-failed`/`rebase-failed` still
270
285
  // grew local history and must trigger reclamation; only `clean`/`no-repo` (no
@@ -35,7 +35,8 @@ const BOUNDED_PACK_FLAGS = [
35
35
  ] as const
36
36
 
37
37
  const RUNTIME_OWNED_PREFIXES = ['memory/'] as const
38
- const FORCE_ADD_PREFIXES = ['sessions/', 'todo/'] as const
38
+ const TYPEVAULT_ROOT = '.typevault'
39
+ const FORCE_ADD_PREFIXES = ['sessions/', 'todo/', `${TYPEVAULT_ROOT}/`] as const
39
40
 
40
41
  const NONINTERACTIVE_ENV = {
41
42
  GIT_TERMINAL_PROMPT: '0',
@@ -102,7 +103,10 @@ export async function runBackup(options: BackupRunnerOptions, deps: BackupRunner
102
103
  timeoutMs: COMMIT_TIMEOUT_MS,
103
104
  })
104
105
  if (status.exitCode !== 0) return { ok: false, kind: 'aborted', reason: `git status failed: ${shortErr(status)}` }
105
- const entries = parsePorcelain(status.stdout)
106
+ const vaultFiles = await listUntrackedVaultFiles(cwd, deps, repo.gitArgs)
107
+ if (!vaultFiles.ok)
108
+ return { ok: false, kind: 'aborted', reason: `git ls-files failed: ${shortErr(vaultFiles.result)}` }
109
+ const entries = [...parsePorcelain(status.stdout), ...vaultFiles.entries]
106
110
  // Only index-known, absent worktree paths that were NEVER in HEAD are
107
111
  // stale additions (including removed intent-to-add entries). A tracked
108
112
  // deletion still in HEAD is backup work; memory/ belongs to another writer.
@@ -182,6 +186,18 @@ export async function runBackup(options: BackupRunnerOptions, deps: BackupRunner
182
186
  if (stagedCheck.exitCode !== 1)
183
187
  return { ok: false, kind: 'commit-failed', reason: `git diff failed: ${shortErr(stagedCheck)}` }
184
188
 
189
+ // `git var` applies commit's strict ident rules, so a commit that would fail
190
+ // for a missing identity stops here instead of paying for a message first.
191
+ for (const ident of ['GIT_AUTHOR_IDENT', 'GIT_COMMITTER_IDENT']) {
192
+ const check = await privateGit(['var', ident])
193
+ if (check.exitCode !== 0)
194
+ return {
195
+ ok: false,
196
+ kind: 'commit-failed',
197
+ reason: `git identity unavailable; set user.name and user.email in the agent repo or run typeclaw start: ${shortErr(check)}`,
198
+ }
199
+ }
200
+
185
201
  const diffstat = await privateGit(['diff', '--cached', '--stat'])
186
202
  const message = await deps.pickCommitMessage({
187
203
  status: status.stdout.replaceAll('\0', '\n').slice(0, 4096),
@@ -479,6 +495,25 @@ export function parsePorcelain(stdout: string): PorcelainEntry[] {
479
495
  return entries
480
496
  }
481
497
 
498
+ // `.typevault/` is gitignored, so porcelain never reports a vault file until it
499
+ // is tracked, and new entries get new file names. List the untracked ignored
500
+ // files under that root explicitly; `.typeclaw/typevault/` (the key) is never
501
+ // matched by this pathspec.
502
+ async function listUntrackedVaultFiles(
503
+ cwd: string,
504
+ deps: BackupRunnerDeps,
505
+ gitArgs: readonly string[],
506
+ ): Promise<{ ok: true; entries: PorcelainEntry[] } | { ok: false; result: GitSpawnResult }> {
507
+ if (!hasDirectoryEntry(join(cwd, TYPEVAULT_ROOT))) return { ok: true, entries: [] }
508
+ const result = await deps.gitSpawn(
509
+ [...gitArgs, 'ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--', `${TYPEVAULT_ROOT}/`],
510
+ { cwd, timeoutMs: COMMIT_TIMEOUT_MS },
511
+ )
512
+ if (result.exitCode !== 0) return { ok: false, result }
513
+ const paths = result.stdout.split('\0').filter((path) => path.startsWith(`${TYPEVAULT_ROOT}/`))
514
+ return { ok: true, entries: paths.map((path) => ({ status: '??', kind: 'untracked', paths: [path] })) }
515
+ }
516
+
482
517
  type StagingSnapshot = {
483
518
  paths: string[]
484
519
  untrackedPaths: Set<string>
@@ -3,6 +3,7 @@ import { join } from 'node:path'
3
3
  import { z } from 'zod'
4
4
 
5
5
  import type { BrowserEngineId, BrowserExtensionId } from '@/browser/registry'
6
+ import { FILL_SECRET_TOOL } from '@/bundled-plugins/managed-browser'
6
7
  import { bashTool, findTool, grepTool, lsTool, readTool, type Subagent, writeTool } from '@/plugin'
7
8
 
8
9
  const BUNDLED_PLUGINS_DIR = join(import.meta.dir, '..')
@@ -21,7 +22,18 @@ export function driverSkillPath(id: BrowserDriverId): string {
21
22
  : join(BUNDLED_PLUGINS_DIR, 'managed-browser', 'skills', id, id, 'SKILL.md')
22
23
  }
23
24
 
24
- export function buildBrowserSystemPrompt({ engines, extensions }: BrowserDrivers): string {
25
+ export const TYPEVAULT_SKILL_PATH = join(BUNDLED_PLUGINS_DIR, 'typevault', 'skills', 'typevault', 'SKILL.md')
26
+
27
+ export type BrowserPromptOptions = {
28
+ // True only when the vault is live (enabled and secrets.json migrated), the
29
+ // same boot gate the typevault plugin uses before it registers anything.
30
+ typevault?: boolean
31
+ }
32
+
33
+ export function buildBrowserSystemPrompt(
34
+ { engines, extensions }: BrowserDrivers,
35
+ { typevault = false }: BrowserPromptOptions = {},
36
+ ): string {
25
37
  const skills = [...engines, ...extensions].map((id) => `- \`${id}\` — ${driverSkillPath(id)}`).join('\n')
26
38
  return `You are a web-browsing subagent running inside TypeClaw. Your job: drive a real browser to complete one browsing task for the main agent and report what happened.
27
39
 
@@ -30,6 +42,7 @@ export function buildBrowserSystemPrompt({ engines, extensions }: BrowserDrivers
30
42
  - The main agent delegates ALL web browsing to you so the page snapshots and screenshots stay out of its context.
31
43
  - You do not talk to the user; the main agent does. Your final message is the whole report.
32
44
  - You cannot spawn subagents.
45
+ - Nobody can see your browser. It runs inside TypeClaw's container, not on the user's screen, and the only path to the user is the main agent's messages. A page you opened, a form you filled, or a dialog on screen is invisible to them until it is described in words or sent as an image.
33
46
 
34
47
  ## How to browse
35
48
 
@@ -37,10 +50,14 @@ Before your first browser command, read the skill for the driver you will use. E
37
50
 
38
51
  ${skills}
39
52
 
40
- Drive the browser with \`bash\`. Use \`write\` only to save requested artifacts (screenshots, extracted data) under \`workspace/\`. Close every browser session you opened before you finish, except one waiting on a human.
53
+ Drive the browser with \`bash\`. Use \`write\` only to save requested artifacts (screenshots, extracted data) under \`workspace/\`.
54
+
55
+ When the user wants to see a page, when the outcome is visual (a layout, a chart, a rendered result, an error dialog), or when you hand a step to a human, save a screenshot of that state under \`workspace/\` and list it under Artifacts so the main agent can send it. Never report "the page is open", "you can see it in the browser", or a step the user should check on screen as if they could look. Close every browser session you opened before you finish, except one waiting on a human.
41
56
 
42
- If a step needs a human (login, 2FA, CAPTCHA, payment confirmation), follow the skill's human-handoff instructions (e.g. start the dashboard), leave that session open, and stop. Report the session name, the dashboard URL or how the user reaches the page, and exactly what the human must do, so the main agent can hand it over and spawn you again to continue in the same session once they are done.
57
+ To enter a password or other secret, click the field with your driver, then call \`${FILL_SECRET_TOOL}\` with the \`.env\` variable name or \`typevault://\` vault reference you were given and the tab's \`url\`; pass \`submit: true\` on the last field. The value never reaches you. Never type, read back, or screenshot a secret yourself.
43
58
 
59
+ If a step needs a human (login, 2FA, CAPTCHA, payment confirmation), follow the skill's human-handoff instructions (e.g. start the dashboard), leave that session open, and stop. Report the session name, the dashboard URL or how the user reaches the page (they cannot reach your local browser window), a screenshot of what they will face, and exactly what the human must do, so the main agent can hand it over and spawn you again to continue in the same session once they are done.
60
+ ${typevault ? TYPEVAULT_SECTION : ''}
44
61
  ## Final report
45
62
 
46
63
  1. **Outcome** — succeeded / partially succeeded / failed, in one sentence.
@@ -49,8 +66,21 @@ If a step needs a human (login, 2FA, CAPTCHA, payment confirmation), follow the
49
66
  4. **Blockers** — anything that stopped you and what would unblock it, including any session left open for a human.`
50
67
  }
51
68
 
52
- // `profile` is dropped, not passed through: the browsing tier is fixed (see
53
- // createBrowserSubagent), so a parent must not move it via a per-spawn `profile`.
69
+ const TYPEVAULT_SECTION = `
70
+ ## Credentials
71
+
72
+ TypeVault is enabled: this agent keeps logins and other credentials in its vault. Read ${TYPEVAULT_SKILL_PATH} before you handle your first credential.
73
+
74
+ - **Filling.** Fill the username from the vault too, not just the password: focus each field and call \`${FILL_SECRET_TOOL}\` with a field reference, e.g. \`typevault://github/bot#username\`, then \`typevault://github/bot#password\` with \`submit: true\`. When the task names no entry, run \`typevault ls\` to find the one for the site.
75
+ - **Missing credential.** When the vault has no entry for the site, do not ask for the value and do not hand the login to a human to type. Stop and report under Blockers the entry name to request (e.g. \`typevault://example.com/alice\`) and its preset (\`password\`), so the main agent can have the user store it with \`vault_request\` and spawn you again.
76
+ - **New login.** On a sign-up, generate the password in bash and store it without printing it, e.g. \`head -c 18 /dev/urandom | base64 | typevault set typevault://example.com/alice --preset password --field username=alice --stdin\`, then fill it from the vault.
77
+ - **Password change.** Never write a new password into the working entry before the site accepts it: \`set\` overwrites it at once, and a rejected or interrupted change would leave the vault without the password the site still wants. Store the candidate in a separate entry (e.g. \`typevault://example.com/alice-next\`, same command as above), fill the current password from the working entry and the new one from the candidate, and only after the site confirms the change run \`typevault rm typevault://example.com/alice\` then \`typevault mv typevault://example.com/alice-next typevault://example.com/alice\`. If it fails or the outcome is unclear, keep the working entry, leave the candidate, and report both entry names.
78
+ - If \`typevault\` says you have no grant, your role cannot use the vault; report that under Blockers.
79
+ - Report entry names, never values. Never put a credential in a file, a command line, or a screenshot.
80
+ `
81
+
82
+ // A per-spawn `profile` passes through so the parent can rerun a task the
83
+ // browsing model declined on another model profile (see the roster line).
54
84
  export const browserPayloadSchema = z
55
85
  .object({
56
86
  requestId: z.string().optional(),
@@ -58,7 +88,6 @@ export const browserPayloadSchema = z
58
88
  description: z.string().optional(),
59
89
  })
60
90
  .passthrough()
61
- .transform(({ profile: _profile, ...rest }) => rest)
62
91
 
63
92
  export type BrowserPayload = z.infer<typeof browserPayloadSchema>
64
93
 
@@ -66,20 +95,28 @@ export type BrowserPayload = z.infer<typeof browserPayloadSchema>
66
95
  // bound a wedged run so it never blocks the parent forever.
67
96
  export const BROWSER_TIMEOUT_MS = 900_000
68
97
 
69
- export function createBrowserSubagent(drivers: BrowserDrivers): Subagent<BrowserPayload> {
98
+ export function createBrowserSubagent(
99
+ drivers: BrowserDrivers,
100
+ options: BrowserPromptOptions = {},
101
+ ): Subagent<BrowserPayload> {
70
102
  return {
71
- systemPrompt: buildBrowserSystemPrompt(drivers),
72
- // The deep model at low effort, like omo's deep-low browser lane: strong
73
- // agentic UI handling without deliberating before every click. Without a
74
- // configured `deep` profile this resolves to plain `default` (its own level).
75
- profile: 'deep',
76
- thinkingLevel: 'low',
103
+ systemPrompt: buildBrowserSystemPrompt(drivers, options),
104
+ // The fast model at medium effort, the tier dedicated browser agents ship
105
+ // by default: a browsing step is mostly reading a snapshot and picking an
106
+ // action, so per-step speed and cost matter more than depth. Medium, not
107
+ // `fast`'s own low, leaves room to recover from misclicks. Without a
108
+ // configured `fast` profile this resolves to plain `default` (its own level).
109
+ profile: 'fast',
110
+ thinkingLevel: 'medium',
77
111
  timeoutMs: BROWSER_TIMEOUT_MS,
78
112
  tools: [readTool, grepTool, findTool, lsTool, bashTool, writeTool],
113
+ // Lets a login finish inside this subagent instead of bouncing the
114
+ // focused tab back to the parent for every secret field.
115
+ pluginTools: [FILL_SECRET_TOOL],
79
116
  payloadSchema: browserPayloadSchema,
80
117
  visibility: 'public',
81
118
  rosterDescription:
82
- 'ALL web browsing — navigate, click, fill forms, log in, screenshot, scrape JS-rendered pages; deep model at low thinking (default profile if no deep); never drive a browser yourself',
119
+ 'ALL web browsing — navigate, click, fill forms, log in, screenshot, scrape JS-rendered pages; fast model at medium thinking (default profile if no fast); never drive a browser yourself',
83
120
  inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
84
121
  toolResultBudget: {
85
122
  maxTotalBytes: 1_000_000,