typeclaw 0.48.13 → 0.50.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 (572) hide show
  1. package/dist/types/agent/attention-escalation.d.ts +18 -0
  2. package/dist/types/agent/auth.d.ts +7 -0
  3. package/dist/types/agent/compaction.d.ts +8 -0
  4. package/dist/types/agent/git-nudge.d.ts +6 -0
  5. package/dist/types/agent/guard-types.d.ts +25 -0
  6. package/dist/types/agent/guards.d.ts +7 -0
  7. package/dist/types/agent/idle-compaction.d.ts +7 -0
  8. package/dist/types/agent/index.d.ts +163 -0
  9. package/dist/types/agent/live-subagents.d.ts +113 -0
  10. package/dist/types/agent/llm-replay-sanitizer.d.ts +11 -0
  11. package/dist/types/agent/loop-guard.d.ts +67 -0
  12. package/dist/types/agent/model-fallback.d.ts +29 -0
  13. package/dist/types/agent/model-overrides.d.ts +8 -0
  14. package/dist/types/agent/multimodal/index.d.ts +2 -0
  15. package/dist/types/agent/multimodal/look-at.d.ts +60 -0
  16. package/dist/types/agent/multimodal/looker.d.ts +61 -0
  17. package/dist/types/agent/multimodal/read-redirect.d.ts +6 -0
  18. package/dist/types/agent/network/response-body.d.ts +1 -0
  19. package/dist/types/agent/network/safe-http.d.ts +46 -0
  20. package/dist/types/agent/plugin-tools.d.ts +129 -0
  21. package/dist/types/agent/proactive-next-step-nudge.d.ts +2 -0
  22. package/dist/types/agent/prompt-cache-key.d.ts +3 -0
  23. package/dist/types/agent/provider-error.d.ts +23 -0
  24. package/dist/types/agent/reload-tool.d.ts +10 -0
  25. package/dist/types/agent/restart/index.d.ts +31 -0
  26. package/dist/types/agent/restart-handoff/index.d.ts +32 -0
  27. package/dist/types/agent/restart-handoff/paths.d.ts +1 -0
  28. package/dist/types/agent/retry-same-ref.d.ts +41 -0
  29. package/dist/types/agent/reviewer-activity.d.ts +3 -0
  30. package/dist/types/agent/reviewer-bash-policy.d.ts +8 -0
  31. package/dist/types/agent/self.d.ts +1 -0
  32. package/dist/types/agent/session-meta.d.ts +28 -0
  33. package/dist/types/agent/session-origin.d.ts +65 -0
  34. package/dist/types/agent/subagent-cache-keepalive.d.ts +38 -0
  35. package/dist/types/agent/subagent-completion-reminder.d.ts +29 -0
  36. package/dist/types/agent/subagent-drain.d.ts +25 -0
  37. package/dist/types/agent/subagent-session.d.ts +3 -0
  38. package/dist/types/agent/subagents.d.ts +153 -0
  39. package/dist/types/agent/system-prompt.d.ts +7 -0
  40. package/dist/types/agent/throttle-circuit.d.ts +25 -0
  41. package/dist/types/agent/todo/continuation-policy.d.ts +54 -0
  42. package/dist/types/agent/todo/continuation-state.d.ts +11 -0
  43. package/dist/types/agent/todo/continuation-wiring.d.ts +32 -0
  44. package/dist/types/agent/todo/continuation.d.ts +21 -0
  45. package/dist/types/agent/todo/scope.d.ts +6 -0
  46. package/dist/types/agent/todo/store.d.ts +16 -0
  47. package/dist/types/agent/tool-error-remediation.d.ts +1 -0
  48. package/dist/types/agent/tool-file-safety.d.ts +78 -0
  49. package/dist/types/agent/tool-not-found-nudge.d.ts +9 -0
  50. package/dist/types/agent/tool-result-budget.d.ts +15 -0
  51. package/dist/types/agent/tools/channel-disengage.d.ts +18 -0
  52. package/dist/types/agent/tools/channel-edit.d.ts +19 -0
  53. package/dist/types/agent/tools/channel-fetch-attachment.d.ts +36 -0
  54. package/dist/types/agent/tools/channel-handoff.d.ts +13 -0
  55. package/dist/types/agent/tools/channel-history-render.d.ts +3 -0
  56. package/dist/types/agent/tools/channel-history.d.ts +25 -0
  57. package/dist/types/agent/tools/channel-log.d.ts +5 -0
  58. package/dist/types/agent/tools/channel-react.d.ts +23 -0
  59. package/dist/types/agent/tools/channel-read.d.ts +27 -0
  60. package/dist/types/agent/tools/channel-reply.d.ts +47 -0
  61. package/dist/types/agent/tools/channel-send.d.ts +42 -0
  62. package/dist/types/agent/tools/channel-session-search.d.ts +10 -0
  63. package/dist/types/agent/tools/curl-impersonate.d.ts +37 -0
  64. package/dist/types/agent/tools/ddg.d.ts +18 -0
  65. package/dist/types/agent/tools/grant-role.d.ts +25 -0
  66. package/dist/types/agent/tools/keyed-semaphore.d.ts +10 -0
  67. package/dist/types/agent/tools/post-github-review.d.ts +38 -0
  68. package/dist/types/agent/tools/restart.d.ts +25 -0
  69. package/dist/types/agent/tools/runtime-notice.d.ts +3 -0
  70. package/dist/types/agent/tools/search-retry.d.ts +16 -0
  71. package/dist/types/agent/tools/skip-response.d.ts +17 -0
  72. package/dist/types/agent/tools/spawn-subagent.d.ts +77 -0
  73. package/dist/types/agent/tools/stream-snapshot.d.ts +23 -0
  74. package/dist/types/agent/tools/subagent-access.d.ts +20 -0
  75. package/dist/types/agent/tools/subagent-cancel.d.ts +23 -0
  76. package/dist/types/agent/tools/subagent-output.d.ts +50 -0
  77. package/dist/types/agent/tools/todo/index.d.ts +14 -0
  78. package/dist/types/agent/tools/webfetch/adaptive-html.d.ts +29 -0
  79. package/dist/types/agent/tools/webfetch/fetch.d.ts +26 -0
  80. package/dist/types/agent/tools/webfetch/html-lexical.d.ts +27 -0
  81. package/dist/types/agent/tools/webfetch/index.d.ts +1 -0
  82. package/dist/types/agent/tools/webfetch/inline-style-visibility.d.ts +3 -0
  83. package/dist/types/agent/tools/webfetch/strategies/grep.d.ts +11 -0
  84. package/dist/types/agent/tools/webfetch/strategies/jq.d.ts +4 -0
  85. package/dist/types/agent/tools/webfetch/strategies/raw.d.ts +1 -0
  86. package/dist/types/agent/tools/webfetch/strategies/readability.d.ts +16 -0
  87. package/dist/types/agent/tools/webfetch/strategies/selector.d.ts +4 -0
  88. package/dist/types/agent/tools/webfetch/strategies/snapshot.d.ts +1 -0
  89. package/dist/types/agent/tools/webfetch/tool.d.ts +15 -0
  90. package/dist/types/agent/tools/webfetch/types.d.ts +32 -0
  91. package/dist/types/agent/tools/websearch.d.ts +17 -0
  92. package/dist/types/agent/tools/wikipedia.d.ts +7 -0
  93. package/dist/types/agent/tools-without-local-file-operands.d.ts +1 -0
  94. package/dist/types/agent/turn-runner.d.ts +36 -0
  95. package/dist/types/agent-messenger/config-dir.d.ts +19 -0
  96. package/dist/types/browser/dockerfile.d.ts +2 -0
  97. package/dist/types/browser/registry.d.ts +49 -0
  98. package/dist/types/bundled-plugins/bun-hygiene/policy.d.ts +18 -0
  99. package/dist/types/bundled-plugins/github-cli-auth/git-askpass.d.ts +5 -0
  100. package/dist/types/bundled-plugins/guard/keys.d.ts +6 -0
  101. package/dist/types/bundled-plugins/guard/policies/managed-config.d.ts +7 -0
  102. package/dist/types/bundled-plugins/guard/policies/memory-topics-delete.d.ts +11 -0
  103. package/dist/types/bundled-plugins/guard/policies/memory-topics-write.d.ts +7 -0
  104. package/dist/types/bundled-plugins/guard/policies/non-workspace-write.d.ts +9 -0
  105. package/dist/types/bundled-plugins/guard/policies/skill-authoring.d.ts +20 -0
  106. package/dist/types/bundled-plugins/guard/policies/uncommitted-changes.d.ts +12 -0
  107. package/dist/types/bundled-plugins/guard/policy.d.ts +11 -0
  108. package/dist/types/bundled-plugins/memory/secret-detector.d.ts +11 -0
  109. package/dist/types/bundled-plugins/memory/slug.d.ts +4 -0
  110. package/dist/types/bundled-plugins/security/permissions.d.ts +20 -0
  111. package/dist/types/bundled-plugins/security/policies/private-surface-read.d.ts +34 -0
  112. package/dist/types/bundled-plugins/security/policies/ssrf.d.ts +18 -0
  113. package/dist/types/bundled-plugins/security/policy.d.ts +4 -0
  114. package/dist/types/channels/adapter-namespace.d.ts +2 -0
  115. package/dist/types/channels/adapters/mention-hints.d.ts +12 -0
  116. package/dist/types/channels/adapters/webex-id-ref.d.ts +5 -0
  117. package/dist/types/channels/background-handoff.d.ts +56 -0
  118. package/dist/types/channels/background-obligations.d.ts +135 -0
  119. package/dist/types/channels/catch-up.d.ts +26 -0
  120. package/dist/types/channels/commands.d.ts +2 -0
  121. package/dist/types/channels/completion-claim.d.ts +20 -0
  122. package/dist/types/channels/continuation-willingness.d.ts +1 -0
  123. package/dist/types/channels/continuity-types.d.ts +75 -0
  124. package/dist/types/channels/describe-error.d.ts +1 -0
  125. package/dist/types/channels/engagement.d.ts +34 -0
  126. package/dist/types/channels/github-false-receipt.d.ts +20 -0
  127. package/dist/types/channels/github-repo.d.ts +2 -0
  128. package/dist/types/channels/github-rereview-guard.d.ts +24 -0
  129. package/dist/types/channels/github-review-check.d.ts +135 -0
  130. package/dist/types/channels/github-review-claim.d.ts +3 -0
  131. package/dist/types/channels/github-review-turn-ledger.d.ts +71 -0
  132. package/dist/types/channels/github-review-verdict-coordinator.d.ts +117 -0
  133. package/dist/types/channels/github-token-bridge.d.ts +20 -0
  134. package/dist/types/channels/github-verdict-activity.d.ts +12 -0
  135. package/dist/types/channels/inbound-journal.d.ts +272 -0
  136. package/dist/types/channels/last-alive.d.ts +3 -0
  137. package/dist/types/channels/membership-cache.d.ts +27 -0
  138. package/dist/types/channels/membership.d.ts +21 -0
  139. package/dist/types/channels/outbound-flood-filter.d.ts +7 -0
  140. package/dist/types/channels/participants.d.ts +4 -0
  141. package/dist/types/channels/persistence.d.ts +32 -0
  142. package/dist/types/channels/recovery-notice.d.ts +26 -0
  143. package/dist/types/channels/recovery-outbox.d.ts +58 -0
  144. package/dist/types/channels/router.d.ts +798 -0
  145. package/dist/types/channels/schema.d.ts +501 -0
  146. package/dist/types/channels/session-handoff.d.ts +58 -0
  147. package/dist/types/channels/session-search.d.ts +29 -0
  148. package/dist/types/channels/types.d.ts +414 -0
  149. package/dist/types/channels/waiting-reactions.d.ts +25 -0
  150. package/dist/types/cli/builtins.d.ts +2 -0
  151. package/dist/types/cli/command-meta.d.ts +9 -0
  152. package/dist/types/coding-agent/broker-body.d.ts +7 -0
  153. package/dist/types/coding-agent/broker.d.ts +22 -0
  154. package/dist/types/coding-agent/claude.d.ts +22 -0
  155. package/dist/types/coding-agent/codex.d.ts +19 -0
  156. package/dist/types/coding-agent/index.d.ts +71 -0
  157. package/dist/types/coding-agent/omo-state.d.ts +2 -0
  158. package/dist/types/coding-agent/omo-stream.d.ts +22 -0
  159. package/dist/types/coding-agent/omo.d.ts +133 -0
  160. package/dist/types/coding-agent/runner.d.ts +35 -0
  161. package/dist/types/coding-agent/tool.d.ts +27 -0
  162. package/dist/types/coding-agent/worktree.d.ts +22 -0
  163. package/dist/types/commands/index.d.ts +45 -0
  164. package/dist/types/config/config.d.ts +814 -0
  165. package/dist/types/config/index.d.ts +3 -0
  166. package/dist/types/config/model-overrides.d.ts +3 -0
  167. package/dist/types/config/providers.d.ts +1456 -0
  168. package/dist/types/config/reloadable.d.ts +9 -0
  169. package/dist/types/container/agent-operation-lock.d.ts +31 -0
  170. package/dist/types/container/build-cache.d.ts +39 -0
  171. package/dist/types/container/compose-project.d.ts +1 -0
  172. package/dist/types/container/controller.d.ts +25 -0
  173. package/dist/types/container/docker-app.d.ts +23 -0
  174. package/dist/types/container/exit-reason.d.ts +10 -0
  175. package/dist/types/container/index.d.ts +14 -0
  176. package/dist/types/container/log-archive.d.ts +68 -0
  177. package/dist/types/container/log-colors.d.ts +3 -0
  178. package/dist/types/container/log-timestamps.d.ts +9 -0
  179. package/dist/types/container/logs.d.ts +37 -0
  180. package/dist/types/container/memory-limit.d.ts +13 -0
  181. package/dist/types/container/memory-oversubscription.d.ts +20 -0
  182. package/dist/types/container/oom-events.d.ts +18 -0
  183. package/dist/types/container/port.d.ts +18 -0
  184. package/dist/types/container/require-running.d.ts +16 -0
  185. package/dist/types/container/restart.d.ts +32 -0
  186. package/dist/types/container/shared.d.ts +93 -0
  187. package/dist/types/container/shell.d.ts +35 -0
  188. package/dist/types/container/start.d.ts +144 -0
  189. package/dist/types/container/stats.d.ts +31 -0
  190. package/dist/types/container/status.d.ts +25 -0
  191. package/dist/types/container/stop.d.ts +24 -0
  192. package/dist/types/container/tool-oom-priority.d.ts +4 -0
  193. package/dist/types/container/verify-running.d.ts +49 -0
  194. package/dist/types/cron/consumer.d.ts +42 -0
  195. package/dist/types/cron/count-state.d.ts +24 -0
  196. package/dist/types/cron/index.d.ts +21 -0
  197. package/dist/types/cron/list.d.ts +33 -0
  198. package/dist/types/cron/reloadable.d.ts +11 -0
  199. package/dist/types/cron/scheduler.d.ts +51 -0
  200. package/dist/types/cron/schema.d.ts +108 -0
  201. package/dist/types/dependencies/bin-resolver.d.ts +28 -0
  202. package/dist/types/dependencies/bins.d.ts +22 -0
  203. package/dist/types/dependencies/index.d.ts +2 -0
  204. package/dist/types/git/bound-gc-config.d.ts +4 -0
  205. package/dist/types/git/hookless.d.ts +1 -0
  206. package/dist/types/git/reconcile-ignored.d.ts +13 -0
  207. package/dist/types/git/resolve-agent-git.d.ts +8 -0
  208. package/dist/types/git/resolve-identity.d.ts +10 -0
  209. package/dist/types/git/run.d.ts +24 -0
  210. package/dist/types/git/system-commit.d.ts +2 -0
  211. package/dist/types/hostd/client.d.ts +13 -0
  212. package/dist/types/hostd/models.d.ts +1 -0
  213. package/dist/types/hostd/paths.d.ts +17 -0
  214. package/dist/types/hostd/protocol.d.ts +93 -0
  215. package/dist/types/hostd/spawn.d.ts +17 -0
  216. package/dist/types/hostd/version.d.ts +18 -0
  217. package/dist/types/init/auto-upgrade.d.ts +41 -0
  218. package/dist/types/init/cli-version.d.ts +7 -0
  219. package/dist/types/init/dockerfile.d.ts +34 -0
  220. package/dist/types/init/ensure-deps.d.ts +17 -0
  221. package/dist/types/init/env-file.d.ts +3 -0
  222. package/dist/types/init/gitignore.d.ts +5 -0
  223. package/dist/types/init/local-source-stamp.d.ts +3 -0
  224. package/dist/types/init/packagejson.d.ts +7 -0
  225. package/dist/types/init/paths.d.ts +3 -0
  226. package/dist/types/init/reconcile-plugin-deps.d.ts +13 -0
  227. package/dist/types/init/run-bun-install.d.ts +16 -0
  228. package/dist/types/init/windows-dev-link.d.ts +8 -0
  229. package/dist/types/mcp/catalog.d.ts +7 -0
  230. package/dist/types/mcp/client.d.ts +58 -0
  231. package/dist/types/mcp/manager.d.ts +56 -0
  232. package/dist/types/mcp/tools.d.ts +23 -0
  233. package/dist/types/models/embedding-model.d.ts +20 -0
  234. package/dist/types/models/transformers-version.d.ts +1 -0
  235. package/dist/types/network/internal-destinations.d.ts +29 -0
  236. package/dist/types/operations/classify-tool-outcome.d.ts +35 -0
  237. package/dist/types/operations/incidents.d.ts +47 -0
  238. package/dist/types/operations/index.d.ts +3 -0
  239. package/dist/types/operations/remediations.d.ts +25 -0
  240. package/dist/types/path-safety/real-intended-path.d.ts +9 -0
  241. package/dist/types/permissions/builtins.d.ts +25 -0
  242. package/dist/types/permissions/grant.d.ts +19 -0
  243. package/dist/types/permissions/index.d.ts +6 -0
  244. package/dist/types/permissions/match-rule.d.ts +28 -0
  245. package/dist/types/permissions/permissions.d.ts +42 -0
  246. package/dist/types/permissions/resolve.d.ts +25 -0
  247. package/dist/types/permissions/schema.d.ts +14 -0
  248. package/dist/types/plugin/context.d.ts +20 -0
  249. package/dist/types/plugin/core-tool-names.d.ts +4 -0
  250. package/dist/types/plugin/define.d.ts +46 -0
  251. package/dist/types/plugin/hooks.d.ts +52 -0
  252. package/dist/types/plugin/index.d.ts +11 -0
  253. package/dist/types/plugin/load-skill.d.ts +14 -0
  254. package/dist/types/plugin/loader.d.ts +25 -0
  255. package/dist/types/plugin/manager.d.ts +42 -0
  256. package/dist/types/plugin/registry.d.ts +73 -0
  257. package/dist/types/plugin/skills.d.ts +11 -0
  258. package/dist/types/plugin/types.d.ts +336 -0
  259. package/dist/types/plugin/zod-introspect.d.ts +11 -0
  260. package/dist/types/reload/client.d.ts +11 -0
  261. package/dist/types/reload/docker-exec-client.d.ts +11 -0
  262. package/dist/types/reload/format.d.ts +2 -0
  263. package/dist/types/reload/index.d.ts +6 -0
  264. package/dist/types/reload/recover.d.ts +22 -0
  265. package/dist/types/reload/registry.d.ts +10 -0
  266. package/dist/types/reload/types.d.ts +25 -0
  267. package/dist/types/role-claim/client.d.ts +20 -0
  268. package/dist/types/role-claim/code.d.ts +4 -0
  269. package/dist/types/role-claim/controller.d.ts +59 -0
  270. package/dist/types/role-claim/index.d.ts +6 -0
  271. package/dist/types/role-claim/match-rule.d.ts +9 -0
  272. package/dist/types/role-claim/pending.d.ts +35 -0
  273. package/dist/types/role-claim/reload-after-claim.d.ts +16 -0
  274. package/dist/types/run/llm-fetch-observer.d.ts +50 -0
  275. package/dist/types/sandbox/availability.d.ts +21 -0
  276. package/dist/types/sandbox/build.d.ts +7 -0
  277. package/dist/types/sandbox/canonical-secrets.d.ts +8 -0
  278. package/dist/types/sandbox/coding-agent.d.ts +20 -0
  279. package/dist/types/sandbox/dependency-bins.d.ts +19 -0
  280. package/dist/types/sandbox/dev-source.d.ts +4 -0
  281. package/dist/types/sandbox/env-exposure.d.ts +1 -0
  282. package/dist/types/sandbox/errors.d.ts +20 -0
  283. package/dist/types/sandbox/hidden-paths.d.ts +11 -0
  284. package/dist/types/sandbox/index.d.ts +14 -0
  285. package/dist/types/sandbox/package-install.d.ts +1 -0
  286. package/dist/types/sandbox/policy.d.ts +71 -0
  287. package/dist/types/sandbox/privileged-runtime.d.ts +13 -0
  288. package/dist/types/sandbox/quote.d.ts +2 -0
  289. package/dist/types/sandbox/runtime-private.d.ts +1 -0
  290. package/dist/types/sandbox/session-tmp.d.ts +6 -0
  291. package/dist/types/sandbox/symlinks.d.ts +6 -0
  292. package/dist/types/sandbox/writable-zones.d.ts +15 -0
  293. package/dist/types/secrets/coding-agent-auth.d.ts +25 -0
  294. package/dist/types/secrets/defaults.d.ts +21 -0
  295. package/dist/types/secrets/export-github-cli-store.d.ts +22 -0
  296. package/dist/types/secrets/hydrate.d.ts +7 -0
  297. package/dist/types/secrets/index.d.ts +7 -0
  298. package/dist/types/secrets/provision-github-cli-store.d.ts +45 -0
  299. package/dist/types/secrets/refresh-provider-oauth.d.ts +22 -0
  300. package/dist/types/secrets/resolve.d.ts +14 -0
  301. package/dist/types/secrets/schema.d.ts +840 -0
  302. package/dist/types/secrets/storage.d.ts +56 -0
  303. package/dist/types/shared/host-locale.d.ts +1 -0
  304. package/dist/types/shared/index.d.ts +5 -0
  305. package/dist/types/shared/local-time.d.ts +4 -0
  306. package/dist/types/shared/platform.d.ts +2 -0
  307. package/dist/types/shared/protocol.d.ts +424 -0
  308. package/dist/types/shared/style-text.d.ts +3 -0
  309. package/dist/types/shared/wsl.d.ts +17 -0
  310. package/dist/types/stream/broker.d.ts +2 -0
  311. package/dist/types/stream/index.d.ts +2 -0
  312. package/dist/types/stream/types.d.ts +71 -0
  313. package/package.json +13 -6
  314. package/scripts/build-plugin-types.ts +105 -0
  315. package/scripts/check-plugin-sdk.ts +111 -0
  316. package/scripts/dump-system-prompt.ts +52 -110
  317. package/scripts/require-parallel.ts +5 -32
  318. package/src/agent/guard-types.ts +3 -0
  319. package/src/agent/guards.ts +4 -0
  320. package/src/agent/idle-compaction.ts +174 -0
  321. package/src/agent/index.ts +210 -80
  322. package/src/agent/live-sessions.ts +2 -2
  323. package/src/agent/live-subagents.ts +20 -0
  324. package/src/agent/multimodal/look-at.ts +22 -9
  325. package/src/agent/plugin-tools.ts +66 -12
  326. package/src/agent/prompt-cache-key.ts +42 -0
  327. package/src/agent/provider-error.ts +179 -10
  328. package/src/agent/restart-handoff/index.ts +7 -14
  329. package/src/agent/reviewer-activity.ts +68 -0
  330. package/src/agent/reviewer-bash-policy.ts +41 -1
  331. package/src/agent/session-origin.ts +58 -9
  332. package/src/agent/subagent-cache-keepalive.ts +198 -0
  333. package/src/agent/subagent-session.ts +6 -0
  334. package/src/agent/subagents.ts +59 -9
  335. package/src/agent/system-prompt.ts +68 -202
  336. package/src/agent/todo/continuation-policy.ts +12 -4
  337. package/src/agent/tool-file-safety.ts +119 -15
  338. package/src/agent/tool-not-found-nudge.ts +1 -1
  339. package/src/agent/tools/channel-edit.ts +20 -10
  340. package/src/agent/tools/channel-fetch-attachment.ts +12 -5
  341. package/src/agent/tools/channel-handoff.ts +72 -0
  342. package/src/agent/tools/channel-history-render.ts +2 -1
  343. package/src/agent/tools/channel-read.ts +57 -10
  344. package/src/agent/tools/channel-reply.ts +55 -30
  345. package/src/agent/tools/channel-send.ts +69 -19
  346. package/src/agent/tools/channel-session-search.ts +35 -0
  347. package/src/agent/tools/curl-impersonate.ts +22 -6
  348. package/src/agent/tools/ddg.ts +13 -5
  349. package/src/agent/tools/post-github-review.ts +77 -15
  350. package/src/agent/tools/skip-response.ts +2 -2
  351. package/src/agent/tools/spawn-subagent.ts +190 -23
  352. package/src/agent/tools/stream-snapshot.ts +15 -2
  353. package/src/agent/tools/subagent-access.ts +11 -4
  354. package/src/agent/tools/subagent-output.ts +8 -0
  355. package/src/browser/bsk-shim.mjs +74 -0
  356. package/src/browser/dockerfile.ts +84 -0
  357. package/src/browser/egress.ts +104 -0
  358. package/src/browser/managed-browser.ts +205 -0
  359. package/src/browser/registry.ts +110 -0
  360. package/src/browser/relay.ts +231 -0
  361. package/src/browser/sandbox-entry.ts +167 -0
  362. package/src/bundled-plugins/agent-browser/index.ts +2 -0
  363. package/src/bundled-plugins/backup/README.md +10 -9
  364. package/src/bundled-plugins/backup/runner.ts +140 -58
  365. package/src/bundled-plugins/backup/subagents.ts +58 -26
  366. package/src/bundled-plugins/browser-agent/browser-agent.ts +89 -0
  367. package/src/bundled-plugins/browser-agent/index.ts +12 -0
  368. package/src/bundled-plugins/doc-render/index.ts +0 -10
  369. package/src/bundled-plugins/doc-render/render.ts +83 -111
  370. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +152 -257
  371. package/src/bundled-plugins/github-cli-auth/gh-command.ts +38 -2
  372. package/src/bundled-plugins/github-cli-auth/git-auth-diagnostic.ts +95 -0
  373. package/src/bundled-plugins/github-cli-auth/granted-push.ts +135 -0
  374. package/src/bundled-plugins/github-cli-auth/index.ts +158 -70
  375. package/src/bundled-plugins/github-cli-auth/review-account.ts +23 -0
  376. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +9 -2
  377. package/src/bundled-plugins/github-cli-auth/review-recorder.ts +45 -7
  378. package/src/bundled-plugins/managed-browser/index.ts +74 -0
  379. package/src/bundled-plugins/managed-browser/skills/browser-use/browser-use/SKILL.md +27 -0
  380. package/src/bundled-plugins/managed-browser/skills/browserskill/browserskill/SKILL.md +28 -0
  381. package/src/bundled-plugins/managed-browser/skills/omowright/omowright/SKILL.md +40 -0
  382. package/src/bundled-plugins/operator/operator.ts +15 -4
  383. package/src/bundled-plugins/qa/index.ts +11 -0
  384. package/src/bundled-plugins/qa/qa.ts +160 -0
  385. package/src/bundled-plugins/qa/skills/qa-cli.ts +50 -0
  386. package/src/bundled-plugins/qa/skills/qa-general.ts +30 -0
  387. package/src/bundled-plugins/qa/skills/qa-http.ts +39 -0
  388. package/src/bundled-plugins/qa/skills/qa-pr.ts +51 -0
  389. package/src/bundled-plugins/qa/skills/qa-web.ts +49 -0
  390. package/src/bundled-plugins/reviewer/skills/code-review.ts +1 -1
  391. package/src/bundled-plugins/security/index.ts +103 -36
  392. package/src/bundled-plugins/security/policies/git-exfil.ts +24 -12
  393. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  394. package/src/channels/adapter-namespace.ts +13 -0
  395. package/src/channels/adapters/discord-bot-reactions.ts +18 -0
  396. package/src/channels/adapters/discord-bot.ts +219 -72
  397. package/src/channels/adapters/discord-reactions.ts +18 -0
  398. package/src/channels/adapters/discord.ts +114 -8
  399. package/src/channels/adapters/github/inbound.ts +103 -8
  400. package/src/channels/adapters/github/index.ts +267 -19
  401. package/src/channels/adapters/github/last-alive.ts +15 -0
  402. package/src/channels/adapters/github/outbound.ts +54 -18
  403. package/src/channels/adapters/github/pending-review-store.ts +141 -0
  404. package/src/channels/adapters/github/permission-guidance.ts +1 -0
  405. package/src/channels/adapters/github/reactions.ts +100 -0
  406. package/src/channels/adapters/github/reconcile-cooldown-store.ts +197 -67
  407. package/src/channels/adapters/github/reconcile-open-prs.ts +418 -33
  408. package/src/channels/adapters/github/recovery.ts +106 -0
  409. package/src/channels/adapters/github/review-check.ts +510 -0
  410. package/src/channels/adapters/github/review-submitter.ts +34 -2
  411. package/src/channels/adapters/instagram.ts +32 -14
  412. package/src/channels/adapters/kakaotalk.ts +22 -7
  413. package/src/channels/adapters/line.ts +18 -3
  414. package/src/channels/adapters/outbound-account.ts +20 -0
  415. package/src/channels/adapters/own-reactions.ts +66 -0
  416. package/src/channels/adapters/recovery-correlation.ts +214 -0
  417. package/src/channels/adapters/slack-attachment-download.ts +14 -3
  418. package/src/channels/adapters/slack-bot-author-resolver.ts +4 -3
  419. package/src/channels/adapters/slack-bot-channel-resolver.ts +9 -6
  420. package/src/channels/adapters/slack-bot-classify.ts +19 -11
  421. package/src/channels/adapters/slack-bot-dedupe.ts +111 -28
  422. package/src/channels/adapters/slack-bot-reactions.ts +18 -0
  423. package/src/channels/adapters/slack-bot-slash-commands.ts +3 -1
  424. package/src/channels/adapters/slack-bot.ts +424 -124
  425. package/src/channels/adapters/slack-classify.ts +26 -4
  426. package/src/channels/adapters/slack-inbound-revision.ts +96 -0
  427. package/src/channels/adapters/slack-reactions.ts +18 -0
  428. package/src/channels/adapters/slack-thread-ts.ts +6 -0
  429. package/src/channels/adapters/slack.ts +48 -3
  430. package/src/channels/adapters/teams.ts +14 -4
  431. package/src/channels/adapters/telegram-bot.ts +56 -10
  432. package/src/channels/adapters/webex-bot.ts +12 -2
  433. package/src/channels/adapters/webex.ts +12 -2
  434. package/src/channels/background-handoff.ts +434 -0
  435. package/src/channels/background-obligations.ts +893 -0
  436. package/src/channels/catch-up.ts +137 -0
  437. package/src/channels/continuation-willingness.ts +2 -2
  438. package/src/channels/continuity-types.ts +272 -0
  439. package/src/channels/engagement.ts +17 -1
  440. package/src/channels/github-false-receipt.ts +3 -3
  441. package/src/channels/github-rereview-guard.ts +9 -5
  442. package/src/channels/github-review-check.ts +598 -0
  443. package/src/channels/github-review-turn-ledger.ts +102 -28
  444. package/src/channels/github-review-verdict-coordinator.ts +72 -12
  445. package/src/channels/github-token-bridge.ts +35 -5
  446. package/src/channels/inbound-journal.ts +1738 -0
  447. package/src/channels/index.ts +6 -1
  448. package/src/channels/last-alive.ts +34 -0
  449. package/src/channels/manager.ts +25 -8
  450. package/src/channels/recovery-dispatcher.ts +264 -0
  451. package/src/channels/recovery-notice.ts +94 -0
  452. package/src/channels/recovery-outbox.ts +459 -0
  453. package/src/channels/router.ts +2951 -736
  454. package/src/channels/schema.ts +8 -1
  455. package/src/channels/session-handoff.fixture.ts +144 -0
  456. package/src/channels/session-handoff.ts +175 -0
  457. package/src/channels/session-search.ts +71 -0
  458. package/src/channels/subagent-completion-bridge.ts +17 -14
  459. package/src/channels/types.ts +133 -18
  460. package/src/channels/waiting-reactions.ts +664 -0
  461. package/src/cli/channel.ts +2 -3
  462. package/src/cli/compose.ts +7 -4
  463. package/src/cli/hostd.ts +49 -3
  464. package/src/cli/init.ts +2 -3
  465. package/src/cli/inspect.ts +11 -14
  466. package/src/cli/model.ts +132 -3
  467. package/src/coding-agent/broker-body.ts +38 -0
  468. package/src/coding-agent/broker.ts +290 -0
  469. package/src/coding-agent/claude.ts +95 -0
  470. package/src/coding-agent/codex.ts +104 -0
  471. package/src/coding-agent/index.ts +512 -0
  472. package/src/coding-agent/omo-state.ts +69 -0
  473. package/src/coding-agent/omo-stream.ts +138 -0
  474. package/src/coding-agent/omo.ts +192 -0
  475. package/src/coding-agent/runner.ts +285 -0
  476. package/src/coding-agent/tool.ts +62 -0
  477. package/src/coding-agent/worktree.ts +355 -0
  478. package/src/compose/restart.ts +10 -3
  479. package/src/compose/start.ts +20 -3
  480. package/src/config/config.ts +121 -25
  481. package/src/config/model-overrides.ts +59 -0
  482. package/src/config/models-mutation.ts +185 -2
  483. package/src/config/providers-mutation.ts +12 -4
  484. package/src/config/providers.ts +71 -9
  485. package/src/container/exit-reason.ts +44 -0
  486. package/src/container/index.ts +5 -0
  487. package/src/container/log-archive.ts +51 -13
  488. package/src/container/memory-limit.ts +1 -1
  489. package/src/container/memory-oversubscription.ts +36 -6
  490. package/src/container/oom-events.ts +86 -0
  491. package/src/container/restart.ts +2 -0
  492. package/src/container/shared.ts +8 -1
  493. package/src/container/start.ts +120 -17
  494. package/src/container/stop.ts +6 -2
  495. package/src/container/tool-oom-priority.ts +32 -0
  496. package/src/cron/consumer.ts +10 -4
  497. package/src/cron/reloadable.ts +23 -2
  498. package/src/doctor/checks.ts +22 -8
  499. package/src/hostd/daemon.ts +33 -11
  500. package/src/hostd/spawn.ts +106 -5
  501. package/src/hostd/version.ts +20 -0
  502. package/src/hostd/watchdog.ts +241 -0
  503. package/src/init/auto-upgrade.ts +7 -1
  504. package/src/init/dockerfile.ts +112 -602
  505. package/src/init/index.ts +6 -6
  506. package/src/init/local-source-stamp.ts +68 -0
  507. package/src/init/models-dev.ts +4 -0
  508. package/src/init/validate-api-key.ts +3 -0
  509. package/src/mcp/client.ts +3 -1
  510. package/src/operations/classify-tool-outcome.ts +45 -1
  511. package/src/operations/incidents.ts +10 -5
  512. package/src/permissions/builtins.ts +7 -0
  513. package/src/permissions/permissions.ts +18 -9
  514. package/src/permissions/resolve.ts +7 -1
  515. package/src/plugin/context.ts +2 -0
  516. package/src/plugin/core-tool-names.ts +1 -1
  517. package/src/plugin/define.ts +1 -0
  518. package/src/plugin/hooks.ts +137 -0
  519. package/src/plugin/index.ts +7 -0
  520. package/src/plugin/manager.ts +4 -0
  521. package/src/plugin/types.ts +66 -1
  522. package/src/run/background-handoff-boot.ts +86 -0
  523. package/src/run/bundled-plugins.ts +6 -0
  524. package/src/run/index.ts +107 -97
  525. package/src/run/llm-fetch-observer.ts +12 -15
  526. package/src/run/resource-sample.ts +19 -0
  527. package/src/sandbox/build.ts +4 -0
  528. package/src/sandbox/canonical-secrets.ts +4 -0
  529. package/src/sandbox/coding-agent.ts +214 -0
  530. package/src/sandbox/dev-source.ts +26 -0
  531. package/src/sandbox/hidden-paths.ts +16 -2
  532. package/src/sandbox/policy.ts +1 -0
  533. package/src/sandbox/runtime-private.ts +4 -1
  534. package/src/secrets/coding-agent-auth.ts +97 -0
  535. package/src/secrets/index.ts +0 -16
  536. package/src/secrets/storage.ts +13 -0
  537. package/src/server/command-runner.ts +6 -2
  538. package/src/server/index.ts +101 -40
  539. package/src/skills/typeclaw-channel-github/SKILL.md +15 -13
  540. package/src/skills/typeclaw-claude-code/SKILL.md +25 -260
  541. package/src/skills/typeclaw-claude-code/references/auth-flow.md +7 -23
  542. package/src/skills/typeclaw-claude-code/references/headless-sessions.md +11 -0
  543. package/src/skills/typeclaw-claude-code/references/results-and-worktrees.md +13 -0
  544. package/src/skills/typeclaw-codex-cli/SKILL.md +35 -270
  545. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +13 -20
  546. package/src/skills/typeclaw-codex-cli/references/headless-sessions.md +26 -0
  547. package/src/skills/typeclaw-codex-cli/references/results-and-worktrees.md +28 -0
  548. package/src/skills/typeclaw-config/SKILL.md +60 -26
  549. package/src/skills/typeclaw-config/references/dockerfile.md +14 -13
  550. package/src/skills/typeclaw-cron/SKILL.md +1 -1
  551. package/src/skills/typeclaw-github-contributing/SKILL.md +3 -3
  552. package/src/skills/typeclaw-memory/SKILL.md +3 -3
  553. package/src/skills/typeclaw-monorepo/SKILL.md +1 -1
  554. package/src/skills/typeclaw-omo-cli/SKILL.md +52 -0
  555. package/src/skills/typeclaw-omo-cli/references/auth-flow.md +11 -0
  556. package/src/skills/typeclaw-omo-cli/references/headless-sessions.md +11 -0
  557. package/src/skills/typeclaw-omo-cli/references/results-and-worktrees.md +23 -0
  558. package/src/skills/typeclaw-permissions/SKILL.md +7 -7
  559. package/src/skills/typeclaw-plugins/SKILL.md +15 -15
  560. package/src/skills/typeclaw-skills/SKILL.md +19 -2
  561. package/src/skills/typeclaw-troubleshooting/SKILL.md +26 -2
  562. package/typeclaw.schema.json +448 -6
  563. package/src/bundled-plugins/doc-render/templates/lib.typ +0 -339
  564. package/src/bundled-plugins/github-cli-auth/gh-store.ts +0 -733
  565. package/src/secrets/claude-credentials-json.ts +0 -129
  566. package/src/secrets/codex-auth-json.ts +0 -102
  567. package/src/secrets/export-claude-credentials-file.ts +0 -270
  568. package/src/secrets/export-codex-auth-file.ts +0 -250
  569. package/src/skills/typeclaw-claude-code/references/stop-hook.md +0 -101
  570. package/src/skills/typeclaw-claude-code/references/tmux-driving.md +0 -243
  571. package/src/skills/typeclaw-codex-cli/references/stop-hook.md +0 -92
  572. package/src/skills/typeclaw-codex-cli/references/tmux-driving.md +0 -239
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: typeclaw-config
3
- description: "Read or edit typeclaw.json — the host-stage runtime config: model, port, mounts, plugins, alias, channels, portForward, docker.file (container package toggles + append), git.ignore.append, plus provider credentials (secrets.json/.env) and the allowed-models registry. Strict schema with a mix of live-reloadable and restart-required fields — load before touching the file or you risk corrupting it or promising a behavior the runtime won't deliver. Also the authority on what a field defaults to and whether a behavior is already on out of the box (port forwarding, container packages, model choice) — load before saying you don't know what X defaults to, or before proposing to add a field whose default the user is asking about; most fields already default to the expected behavior, so the answer is usually 'no edit needed'. Owns the GitHub channel config — which repos it watches (channels.github.repos), the code-review trigger (channels.github.review.on/approve), webhook auto-registration via a tunnel — load on 'github channel', 'github webhook', 'review these repos', 'watch repo X', 'set up code review', 'stop reviewing repo Y'; GitHub events are an inbound channel the agent engages directly, there is NO 'forward webhooks to a Slack channel' flow, do not invent destinations. Covers recommended host paths to mount for common use cases (references/recommended-mounts.md). For messenger-channel engagement BEHAVIOR (when the agent replies vs. observes, triggers, stickiness, alias matching, suppressors) load typeclaw-channels; for who is admitted to a channel load typeclaw-permissions."
3
+ description: "Read or edit typeclaw.json — the host-stage runtime config: model, modelOverrides (per-channel models), port, mounts, plugins, alias, channels, portForward, docker.file (container package toggles + append), git.ignore.append, plus provider credentials (secrets.json/.env) and the allowed-models registry. Strict schema with a mix of live-reloadable and restart-required fields — load before touching the file or you risk corrupting it or promising a behavior the runtime won't deliver. Also the authority on what a field defaults to and whether a behavior is already on out of the box (port forwarding, container packages, model choice) — load before saying you don't know what X defaults to, or before proposing to add a field whose default the user is asking about; most fields already default to the expected behavior, so the answer is usually 'no edit needed'. Owns the GitHub channel config — which repos it watches (channels.github.repos), the code-review trigger (channels.github.review.on/approve), webhook auto-registration via a tunnel — load on 'github channel', 'github webhook', 'review these repos', 'watch repo X', 'set up code review', 'stop reviewing repo Y'; GitHub events are an inbound channel the agent engages directly, there is NO 'forward webhooks to a Slack channel' flow, do not invent destinations. Covers recommended host paths to mount for common use cases (references/recommended-mounts.md). For messenger-channel engagement BEHAVIOR (when the agent replies vs. observes, triggers, stickiness, alias matching, suppressors) load typeclaw-channels; for who is admitted to a channel load typeclaw-permissions."
4
4
  ---
5
5
 
6
6
  # typeclaw-config
@@ -17,12 +17,13 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
17
17
  - `model` — a fully-qualified `<provider>/<model-id>` string. The runtime resolves this against the built-in provider registry to decide which API to call for every turn. **Live-reloadable.**
18
18
  - `models.<profile>` fallback chain — a profile may be an array of refs. The chain advances on failure: cron/batch turns advance on **any** error; interactive turns (TUI, channels, subagents) advance only when the active ref is **throttled/overloaded** (`server_is_overloaded`/`429`/`503`/rate-limit), never mid-turn after output or a tool call, and a repeatedly-throttled ref is skipped for a short cooldown. A single-ref profile fails fast with a provider notice instead of stalling. To make an agent resilient to per-account provider throttling, declare a fallback ref (ideally a different provider/account). **Live-reloadable** (rides `models`).
19
19
  - `thinkingLevel` (per-profile) — reasoning effort lives **inside `models`**, not as a top-level field. A profile value may be an object like `{ "model": "<ref>", "thinkingLevel": "high" }` (or `{ "models": ["<ref>", …], "thinkingLevel": … }` for a chain). A session resolves its effort as **the profile's own level → the `default` profile's level → the SDK default (`medium`)** — so the `default` profile's `thinkingLevel` is the de-facto global default, mirroring how `models.default` is the default model. Levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Clamped to each model's capabilities (`max` exists only on models that offer it, such as GPT-6 and Claude Opus 5.5; elsewhere it clamps down). An attention-escalation cue in a turn bumps that single turn to `xhigh`, and a profile already at `max` stays at `max`. Bare string/array profile values keep working; a profile becomes an object only when a level is attached. **Live-reloadable** (rides `models`).
20
+ - `modelOverrides` — per-channel models. Named entries `{ "match": [<rules>], "models": { <profile>: … } }` (the `roles` shape) layer a partial `models` block over the global one for the chats their rules cover. See **Per-channel models** below. **Live-reloadable.**
20
21
  - `mounts` — additional host directories the user has chosen to expose to you. Each entry produces a `docker run -v <hostPath>:/agent/mounts/<name>` flag at `typeclaw start` time, so the directory shows up at `mounts/<name>` inside your agent folder. **The launcher reads this; the running container does not.** Editing `mounts` only takes effect on the next `typeclaw start`. **Restart-required.**
21
22
  - `plugins` — array of plugin module specifiers loaded at server boot: npm package names for published plugins, or relative paths for local plugins you are authoring. **Restart-required.**
22
23
  - `alias` — additional names the agent answers to when a channel message contains its name in plain text (no `<@id>` mention). The agent folder's directory name (`basename(agentDir)`) is always implicit; `alias` adds further forms (Latin transliteration, nicknames, Korean particles, etc.). Used by the channel engagement layer alongside the structural mention/reply/dm triggers. **Live-reloadable.**
23
24
  - `channels` — per-adapter engagement triggers and history-prefetch knobs for external messengers (Discord, Slack, Telegram, LINE, KakaoTalk), plus the GitHub channel (a webhook-driven adapter that watches repos and reviews PRs — see **GitHub channel** below). Access control lives in `roles`, not here. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
24
25
  - `branding` — whether your system prompt discloses that you run on TypeClaw. Default `true`: the prompt says you run "inside TypeClaw" and stamps a `## Runtime` TypeClaw-version block. Set `false` and both are stripped — the prompt opens generically and the runtime-version block is omitted (also on the subagent prompt path). Read fresh per session, so it applies on the next `reload`. The `typeclaw.json` filename and the `typeclaw-render-pdf` / `typeclaw-troubleshooting` skill names stay regardless — they are tokens you need to operate, not disclosure. **Live-reloadable.**
25
- - `docker.file` — controls what ships in the autogenerated container image. Two layers: (1) **toggles** for opinionated package installs — `tmux`, `gh`, `python`, `xvfb` default on (`true`); `cjkFonts` defaults to `"auto"` (resolved from host locale at start); `ffmpeg`, `cloudflared`, `claudeCode`, `codexCli` default off (`false`) — set a toggle to `false` to omit, or to a version string like `"2.40.0"` to apt-pin (`python`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, and `codexCli` are boolean-only). Most toggles install apt packages with BuildKit cache mounts; `cloudflared`, `claudeCode`, and `codexCli` are exceptions — `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's official `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package. (2) **`append`** — extra Dockerfile lines spliced in right before `ENTRYPOINT` for anything the toggles don't cover. The whole Dockerfile is rewritten on every `start` from the typeclaw template. Lives under the `docker` namespace alongside future Docker-related blocks (e.g. `docker.compose`). **Restart-required** (next `typeclaw start` rebuilds the image).
26
+ - `docker.file` — controls what ships in the autogenerated container image. Two layers: (1) **toggles** for opinionated package installs — `tmux`, `gh`, `python`, `xvfb` default on (`true`); `cjkFonts` defaults to `"auto"` (resolved from host locale at start); `ffmpeg`, `cloudflared`, `claudeCode`, `codexCli`, `omoCli` default off (`false`) — set a toggle to `false` to omit, or to a version string like `"2.40.0"` to apt-pin (`python`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`, and `omoCli` are boolean-only). Most toggles install apt packages with BuildKit cache mounts; `cloudflared`, `claudeCode`, `codexCli`, and `omoCli` are exceptions — `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's official `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package, and `omoCli` downloads digest-verified OmO Native 5.1.19 assets. (2) **`append`** — extra Dockerfile lines spliced in right before `ENTRYPOINT` for anything the toggles don't cover. The whole Dockerfile is rewritten on every `start` from the typeclaw template. Lives under the `docker` namespace alongside future Docker-related blocks (e.g. `docker.compose`). **Restart-required** (next `typeclaw start` rebuilds the image).
26
27
  - `git.ignore.append` — extra `.gitignore` patterns `typeclaw start` splices into the TypeClaw-owned `.gitignore` before the protected TypeClaw rules. The whole `.gitignore` is rewritten and auto-committed on every `start` when it changes; `append` is the supported escape hatch for local ignore patterns without editing the managed file by hand. Lives under the `git` namespace. **Restart-required** (next `typeclaw start` refreshes and commits `.gitignore`).
27
28
  - `portForward` — allow/deny policy for the auto port-forwarder (the host-stage `_hostd` daemon's portbroker). When the agent runs a server inside the container that LISTENs on a TCP port, the broker proxies it to the same port number on `127.0.0.1` of the host so the user can hit it directly. `portForward` decides which ports are allowed through. **Restart-required** — the broker captures the policy at register time on `typeclaw start`.
28
29
  - `network` — the separate container-stage egress firewall. `blockInternal` defaults on; `allow` accepts explicit IPv4 addresses/CIDRs for all-protocol firewall exceptions. It does not bypass `web_fetch` or URL-backed `look_at` SSRF validation. **Restart-required.**
@@ -31,7 +32,7 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
31
32
 
32
33
  There is no file watcher, but there is a `reload` mechanism. When `typeclaw.json` changes:
33
34
 
34
- - **Live-reloadable fields** (`models` — including per-profile `thinkingLevel`, `alias`, `channels`, `branding`) take effect on the next `reload` — no container restart.
35
+ - **Live-reloadable fields** (`models` — including per-profile `thinkingLevel`, `modelOverrides`, `alias`, `channels`, `branding`) take effect on the next `reload` — no container restart.
35
36
  - **Restart-required fields** (`port`, `mounts`, `plugins`, `portForward`, `network`, `docker.file`, `git.ignore`) are reported as "reload landed but change won't apply until restart". The diff returns success; the runtime still has the old value in memory. Tell the user explicitly which one they're hitting. `docker.file` additionally requires an image rebuild — that happens automatically on the next `typeclaw start`, no extra flag needed. `git.ignore` refreshes the managed `.gitignore` and auto-commits it on the next `typeclaw start` if content changed.
36
37
  - **`$schema`** changes are ignored.
37
38
 
@@ -43,25 +44,27 @@ You yourself cannot run `typeclaw restart` — that is a host-stage command and
43
44
 
44
45
  `typeclaw.json` is a single JSON object with these fields:
45
46
 
46
- | Field | Required | Type | Notes |
47
- | -------------------------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
48
- | `$schema` | no | string | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it. |
49
- | `port` | no | integer | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.** |
50
- | `model` | no | string | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.** |
51
- | `models.<profile>.thinkingLevel` | no | string | Per-profile reasoning effort (NOT a top-level field): `off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max`. Lives in a profile object `{ "model": "<ref>", "thinkingLevel": … }`. Resolves as profile's own → `default` profile's → SDK default (`medium`). Set with `typeclaw model set <profile> <ref> --thinking <level>` or `typeclaw model thinking <level>` (for `default`). **Live-reloadable.** |
52
- | `mounts` | no | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.** |
53
- | `plugins` | no | array of strings | Plugin module specifiers loaded at server boot: use npm package names for published plugins (for example, `typeclaw-gws-multi-account`) and relative paths only for local plugins you are authoring (for example, `./packages/my-plugin`). Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**. |
54
- | `alias` | no | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Channels and Alias** below for schema/edit mechanics; the matching behavior lives in the `typeclaw-channels` skill. **Live-reloadable.** |
55
- | `channels` | no | object | Per-adapter engagement triggers and history-prefetch knobs for external messengers (plus the `github` webhook channel — see **GitHub channel** below). Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill; engagement behavior lives in `typeclaw-channels`. **Live-reloadable.** See **Channels and Alias** below. |
56
- | `portForward` | no | object | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below. |
57
- | `network` | no | object | Container-stage egress firewall: `{ blockInternal, autoAllowResolvers, allow }`. Defaults to internal blocking on, resolver carve-outs on, and no IPv4 exceptions. `allow` is independent from safe-HTTP SSRF exceptions. **Restart-required.** See **Network and model HTTP internal destinations** below. |
58
- | `docker` | no | object | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: 'auto', cloudflared: false, xvfb: true, claudeCode: false, codexCli: false, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
59
- | `git` | no | object | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below. |
60
- | `branding` | no | boolean | Whether the system prompt discloses that you run on TypeClaw. Defaults to `true`. Set `false` to strip every TypeClaw clue from the prompt: the base prompt opens generically (no "inside TypeClaw") and the `## Runtime` version block is omitted, on both the main and subagent prompt paths. Read fresh per session. Functional identifiers (`typeclaw.json`, the `typeclaw-render-pdf` / `typeclaw-troubleshooting` skill names) are unaffected. **Live-reloadable.** |
47
+ | Field | Required | Type | Notes |
48
+ | -------------------------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
49
+ | `$schema` | no | string | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it. |
50
+ | `port` | no | integer | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.** |
51
+ | `model` | no | string | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.** |
52
+ | `models.<profile>.thinkingLevel` | no | string | Per-profile reasoning effort (NOT a top-level field): `off` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max`. Lives in a profile object `{ "model": "<ref>", "thinkingLevel": … }`. Resolves as profile's own → `default` profile's → SDK default (`medium`). Set with `typeclaw model set <profile> <ref> --thinking <level>` or `typeclaw model thinking <level>` (for `default`). **Live-reloadable.** |
53
+ | `modelOverrides` | no | object | Per-channel models: `{ "<name>": { "match": ["<rule>", …], "models": { "<profile>": <ref \| chain \| { model(s), thinkingLevel }> } } }`. Channel match rules only; most specific rule wins per profile. Defaults to `{}`. See **Per-channel models**. **Live-reloadable.** |
54
+ | `mounts` | no | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.** |
55
+ | `plugins` | no | array of strings | Plugin module specifiers loaded at server boot: use npm package names for published plugins (for example, `typeclaw-gws-multi-account`) and relative paths only for local plugins you are authoring (for example, `./packages/my-plugin`). Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**. |
56
+ | `alias` | no | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Channels and Alias** below for schema/edit mechanics; the matching behavior lives in the `typeclaw-channels` skill. **Live-reloadable.** |
57
+ | `channels` | no | object | Per-adapter engagement triggers and history-prefetch knobs for external messengers (plus the `github` webhook channel — see **GitHub channel** below). Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill; engagement behavior lives in `typeclaw-channels`. **Live-reloadable.** See **Channels and Alias** below. |
58
+ | `portForward` | no | object | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below. |
59
+ | `network` | no | object | Container-stage egress firewall: `{ blockInternal, autoAllowResolvers, allow }`. Defaults to internal blocking on, resolver carve-outs on, and no IPv4 exceptions. `allow` is independent from safe-HTTP SSRF exceptions. **Restart-required.** See **Network and model HTTP internal destinations** below. |
60
+ | `browser` | no | object | `{ engines, extensions }`. `engines` from `agent-browser` (default), `omowright`, `browser-use`; `extensions` from `browserskill` (default `[]`). Anything beyond the default starts a TypeClaw-managed shared Chrome; bash gets its token-gated CDP URL only with `browser.shared`. **Restart-required** (rebuilds the image). |
61
+ | `docker` | no | object | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`, `omoCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: 'auto', cloudflared: false, xvfb: true, claudeCode: false, codexCli: false, omoCli: false, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
62
+ | `git` | no | object | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below. |
63
+ | `branding` | no | boolean | Whether the system prompt discloses that you run on TypeClaw. Defaults to `true`. Set `false` to strip every TypeClaw clue from the prompt: the base prompt opens generically (no "inside TypeClaw") and the `## Runtime` version block is omitted, on both the main and subagent prompt paths. Read fresh per session. Functional identifiers (`typeclaw.json`, the `typeclaw-render-pdf` / `typeclaw-troubleshooting` skill names) are unaffected. **Live-reloadable.** |
61
64
 
62
65
  > **Top-level keys not in this table are not "ignored unknowns" anymore** — they are reserved for **plugin config blocks**. The schema's `catchall(z.unknown())` preserves them, and the plugin loader hands each block to its owning plugin's `configSchema` for validation. The bundled memory plugin owns `memory` at the top level — see the `typeclaw-memory` skill for that block's semantics. Do not write a top-level key unless you know which plugin owns it.
63
66
 
64
- Within the well-known core fields (`$schema`, `port`, `models`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `network`, `docker`, `git`), **fields the schema doesn't predeclare are silently dropped**. Legacy top-level `dockerfile` and `gitignore` keys are no longer migrated — use `docker.file` and `git.ignore` directly (the legacy keys are silently ignored). Do not invent runtime fields like `provider`, `apiKey`, `temperature`, `maxTokens`, `systemPrompt`, `tools`, `timeout`, etc. — those are not plugin blocks, they are imaginary. If the user asks for one, say it is not yet supported and (if it makes sense) suggest they file a request.
67
+ Within the well-known core fields (`$schema`, `port`, `models`, `modelOverrides`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `network`, `docker`, `git`), **fields the schema doesn't predeclare are silently dropped**. Legacy top-level `dockerfile` and `gitignore` keys are no longer migrated — use `docker.file` and `git.ignore` directly (the legacy keys are silently ignored). Do not invent runtime fields like `provider`, `apiKey`, `temperature`, `maxTokens`, `systemPrompt`, `tools`, `timeout`, etc. — those are not plugin blocks, they are imaginary. If the user asks for one, say it is not yet supported and (if it makes sense) suggest they file a request.
65
68
 
66
69
  A scaffolded `typeclaw.json` looks like:
67
70
 
@@ -72,7 +75,7 @@ A scaffolded `typeclaw.json` looks like:
72
75
  }
73
76
  ```
74
77
 
75
- The runtime fills in defaults for any omitted field: `port` → `8973`, `mounts` → `[]` (no host paths exposed), `plugins` → `[]`, `channels` → `{}` (no adapters configured), `portForward` → `{ "allow": "*" }` (forward every container LISTEN port), `network` → `{ "blockInternal": true, "autoAllowResolvers": true, "allow": [] }`, `docker` → `{ "file": { "ffmpeg": false, "gh": true, "python": true, "tmux": true, "cjkFonts": "auto", "cloudflared": false, "xvfb": true, "claudeCode": false, "codexCli": false, "append": [] } }` (tmux/gh/python/xvfb pre-installed; cjkFonts auto-detected from host locale; ffmpeg, cloudflared, claudeCode, and codexCli off; no custom build steps), `git` → `{ "ignore": { "append": [] } }` (no custom ignore patterns). `typeclaw init` deliberately omits any field whose default is owned elsewhere — `mounts`, `portForward`, `network`, `docker`, and `git` default via `configSchema`, and the bundled memory plugin owns its own `memory` defaults — so the scaffolded file stays minimal and the user sees only fields they actually need to think about. Add a `memory` block (a **plugin config block** owned by the bundled memory plugin) only when overriding its defaults; see the `typeclaw-memory` skill for the schema.
78
+ The runtime fills in defaults for any omitted field: `port` → `8973`, `mounts` → `[]` (no host paths exposed), `plugins` → `[]`, `channels` → `{}` (no adapters configured), `portForward` → `{ "allow": "*" }` (forward every container LISTEN port), `network` → `{ "blockInternal": true, "autoAllowResolvers": true, "allow": [] }`, `docker` → `{ "file": { "ffmpeg": false, "gh": true, "python": true, "tmux": true, "cjkFonts": "auto", "cloudflared": false, "xvfb": true, "claudeCode": false, "codexCli": false, "omoCli": false, "append": [] } }` (tmux/gh/python/xvfb pre-installed; cjkFonts auto-detected from host locale; ffmpeg, cloudflared, claudeCode, codexCli, and omoCli off; no custom build steps), `git` → `{ "ignore": { "append": [] } }` (no custom ignore patterns). `typeclaw init` deliberately omits any field whose default is owned elsewhere — `mounts`, `portForward`, `network`, `docker`, and `git` default via `configSchema`, and the bundled memory plugin owns its own `memory` defaults — so the scaffolded file stays minimal and the user sees only fields they actually need to think about. Add a `memory` block (a **plugin config block** owned by the bundled memory plugin) only when overriding its defaults; see the `typeclaw-memory` skill for the schema.
76
79
 
77
80
  If the user said yes to "Wire a Discord bot?" during `typeclaw init`, the scaffold also includes:
78
81
 
@@ -86,6 +89,8 @@ The empty block declares the adapter to the runtime — the schema fills in `ena
86
89
 
87
90
  ## Mounts
88
91
 
92
+ To let rendered pages and PDFs use the host's installed fonts, set top-level `"hostFonts": true` instead of adding a font mount by hand: it mounts the host font folders read-only where fontconfig finds them (restart-required).
93
+
89
94
  Each entry in `mounts` is an object with:
90
95
 
91
96
  | Field | Required | Type | Notes |
@@ -128,7 +133,7 @@ The `mounts/` directory itself is **gitignored** in your agent folder. The mount
128
133
  7. **Commit** with a message explaining which mount was added and why (`typeclaw-git` skill).
129
134
  8. **Tell the user to restart**: "Added mount `<name>` → `<path>`. Run `typeclaw restart` (host stage). The mount will appear at `mounts/<name>/` after the next start."
130
135
 
131
- GitHub push credentials are independent of mounts. For store-backed pushes, the operator selects the host account with `gh auth login --hostname github.com`; the next real `typeclaw start` or `typeclaw restart` refreshes the masked trusted store automatically. Configured GitHub remotes can then push from any accessible repository path. Runtime credential precedence is GitHub App, then an authorized PAT declared in `.env`, then the trusted store. The store fallback supports one configured destination, not explicit-URL or `--set-upstream` pushes.
136
+ GitHub push credentials are independent of mounts. Runtime credential precedence is GitHub App, then an authorized PAT declared in `.env`; with neither, a brokered push is blocked. Imported host auth (`githubCli.importHostAuth`) is **not** a push credential — it only authenticates brokered `gh` commands, because the host `gh` login is the operator's own GitHub account.
132
137
 
133
138
  ### When the user asks "what can you see / what's mounted"
134
139
 
@@ -141,6 +146,35 @@ When the user describes a use case rather than naming a path — "transcribe my
141
146
 
142
147
  The reference is **a lookup table, not a wishlist** — recommending a path there is not a license to add the mount silently. The user still has to ask, you still follow the standard procedure (read file, check collisions, pick name, append, write, commit, restart-required), and you still surface the TCC/FDA requirement before promising the agent can read FDA-gated data.
143
148
 
149
+ ## Per-channel models
150
+
151
+ `modelOverrides` picks different models for specific channels, workspaces, or chats. Global `models` stays the default; each named entry overrides some profiles for the chats its `match` rules cover.
152
+
153
+ ```json
154
+ {
155
+ "models": { "default": "openai/gpt-5.4", "fast": "openai/gpt-5.4-nano" },
156
+ "modelOverrides": {
157
+ "slack": { "match": ["slack:*"], "models": { "default": "openai/gpt-5.4-mini" } },
158
+ "support": {
159
+ "match": ["slack:T0123/C0ABCDE", "discord:G1/C2"],
160
+ "models": { "default": "openai/gpt-5.5", "fast": { "model": "openai/gpt-5.4-mini", "thinkingLevel": "off" } }
161
+ }
162
+ }
163
+ }
164
+ ```
165
+
166
+ - **`match`** uses the roles match-rule syntax (see the `typeclaw-permissions` skill), limited to channel rules: `*`, `<platform>:*`, `<platform>:<workspace>`, `<platform>:<workspace>/<chat>`, `<platform>:dm/*`. `author:`, `tui`, `cron`, and `subagent` rules are rejected, as is an empty list. Platform names are `slack`, `discord`, `telegram`, … — `slack:` covers both the `slack` and `slack-bot` adapters.
167
+ - **`models`** takes the same values as the top-level `models` (ref, fallback chain, or `{ model(s), thinkingLevel }`), needs at least one profile, and does not need `default`. Every ref must be in **Allowed models** and its provider must have credentials.
168
+ - **Resolution is per profile:** the most specific matching rule across all entries wins (chat > workspace or DM bucket > platform > `*`); a tie goes to the later-declared entry; a profile no matching entry defines uses the global `models`. Subagents you spawn from a chat inherit that chat's overrides. TUI and cron sessions use the global `models`.
169
+ - **After `reload`, the next turn uses it.** Channel sessions, including ones already running, re-resolve their model before each turn, so the new model applies from the next message; a request already in flight is not switched mid-request. A changed `thinkingLevel` applies to newly created sessions only. The `look_at` tool's `vision` profile always uses the global `models`.
170
+
171
+ ### When the user asks "use model X in this channel" / "use a cheaper model on Slack"
172
+
173
+ 1. Build the rule from your **session origin** (adapter, workspace id, chat id in your system prompt), not from display names: this chat → `<platform>:<workspace>/<chat>`; this workspace → `<platform>:<workspace>`; the whole platform → `<platform>:*`. Confirm the scope with the user when it is ambiguous ("this channel" vs. "all of Slack").
174
+ 2. Check the model is in **Allowed models** and its provider is configured (`typeclaw provider list`).
175
+ 3. Add or edit the entry. Reuse an existing entry whose `match` already covers the same chats instead of creating a duplicate; otherwise pick a short descriptive name (`slack`, `support`). Equivalent host CLI: `typeclaw model set <profile> <ref> --override <name> --match '<rule>'`, `typeclaw model override match|unmatch|remove …`, `typeclaw model remove <profile> --override <name>`.
176
+ 4. Say: "Edited `modelOverrides` — live-reloadable; after `reload`, that chat uses the new model from its next message."
177
+
144
178
  ## Channels and Alias
145
179
 
146
180
  `channels` configures which external adapters (`discord-bot`, `slack-bot`, `telegram-bot`, `line`, `kakaotalk`, and `github`) are enabled and how the engagement layer behaves on each; `alias` lists plain-text names the agent answers to. Both are **live-reloadable** — edits take effect on the next `reload`, no container restart.
@@ -291,7 +325,7 @@ The transport still performs DNS answer validation, socket pinning, mixed-answer
291
325
 
292
326
  The `docker.file` block has two layers of customization:
293
327
 
294
- 1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`). Most are apt packages — boolean for on/off, version string for an apt pin — and benefit from BuildKit cache mounts. Use a toggle whenever it covers what the user wants over a hand-rolled `append` entry.
328
+ 1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`, `omoCli`). Most are apt packages — boolean for on/off, version string for an apt pin — and benefit from BuildKit cache mounts. Use a toggle whenever it covers what the user wants over a hand-rolled `append` entry.
295
329
  2. **`append`** is the escape hatch for everything the toggles don't cover. An array of single-line Dockerfile instructions spliced in right before `ENTRYPOINT`, prefixed with a `# Custom lines from typeclaw.json#docker.file.append.` comment.
296
330
 
297
331
  For the full toggle catalog (per-toggle defaults, types, version-pin rules, what each installs and why), the `append` single-line constraint, where things land in the build, and the restart/rebuild semantics, consult `references/dockerfile.md`. The playbooks below are the entry point; open the reference when you need the specifics of a toggle or the build-layer details. **`docker.file` is restart-required** — the next `typeclaw start` rewrites the Dockerfile and rebuilds the image automatically (no `--build` flag needed).
@@ -299,7 +333,7 @@ For the full toggle catalog (per-toggle defaults, types, version-pin rules, what
299
333
  ### When the user asks "install <package> in the container" / "add a Dockerfile line"
300
334
 
301
335
  1. **Read `typeclaw.json`.**
302
- 2. **Check if a toggle covers it.** If the package is `tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts` (CJK glyph rendering for `agent-browser` screenshots), `cloudflared` (Cloudflare Quick tunnels), Anthropic's Claude Code CLI (`claudeCode`), or OpenAI's Codex CLI (`codexCli`), prefer the toggle: `"docker": { "file": { "ffmpeg": true } }`. For a pinned version of an apt toggle, pass the version string: `"gh": "2.40.0"`. This is faster (BuildKit cache mount) and clearer than `append`. `cjkFonts`, `cloudflared`, `claudeCode`, and `codexCli` are boolean-only — no version-pin variant.
336
+ 2. **Check if a toggle covers it.** If the package is `tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts` (CJK glyph rendering for `agent-browser` screenshots), `cloudflared` (Cloudflare Quick tunnels), Anthropic's Claude Code CLI (`claudeCode`), OpenAI's Codex CLI (`codexCli`), or OmO Native (`omoCli`), prefer the toggle: `"docker": { "file": { "ffmpeg": true } }`. For a pinned version of an apt toggle, pass the version string: `"gh": "2.40.0"`. This is faster (BuildKit cache mount) and clearer than `append`. `cjkFonts`, `cloudflared`, `claudeCode`, `codexCli`, and `omoCli` are boolean-only — no version-pin variant.
303
337
  3. **Otherwise, use `append`.** Decide on a single-line entry — for apt installs, prefer one `RUN apt-get update && apt-get install -y --no-install-recommends <pkg> && rm -rf /var/lib/apt/lists/*` line. For env vars, one `ENV` line per variable.
304
338
  4. **Validate no embedded newlines** (`append` only). Multi-step logic must be `&&`-chained on one line, not split across array entries unless those entries are independent Dockerfile instructions.
305
339
  5. **Append to `docker.file.append`** (creating the field if it doesn't exist). Preserve existing entries.
@@ -393,7 +427,7 @@ What this means for you:
393
427
 
394
428
  ## Plugin config blocks
395
429
 
396
- Top-level keys in `typeclaw.json` that are **not** in the well-known ten (`$schema`, `port`, `models`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `docker`, `git`) are treated as plugin config blocks. The schema preserves them via `catchall(z.unknown())`, and `extractPluginConfigs` hands each block to the owning plugin's `configSchema` for validation at boot.
430
+ Top-level keys in `typeclaw.json` that are **not** in the well-known core fields (`$schema`, `port`, `models`, `modelOverrides`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `docker`, `git`) are treated as plugin config blocks. The schema preserves them via `catchall(z.unknown())`, and `extractPluginConfigs` hands each block to the owning plugin's `configSchema` for validation at boot.
397
431
 
398
432
  This skill does **not** document individual plugin blocks. For schema, defaults, and reload semantics of a specific plugin's config, defer to that plugin's own skill:
399
433
 
@@ -524,7 +558,7 @@ Never request, echo, log, or commit values from `secrets.json` or `.env`. Gitign
524
558
  - If `portForward` is set: `allow` is either `"*"` or an array of integers (1–65535); `deny`, if present, is an array of integers and **only valid when `allow` is `"*"`** (the schema rejects `deny` paired with a number-array `allow`)
525
559
  - If `network` is set: `blockInternal` and `autoAllowResolvers` are booleans; `allow` is an array of bare IPv4 addresses or IPv4 CIDRs only
526
560
  - If `docker.file.append` is set: array of strings, each with no embedded `\n` or `\r` (multi-step shell logic goes in a single `&&`-chained `RUN` entry)
527
- - If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `cjkFonts` is boolean or `"auto"`; `python`, `cloudflared`, `claudeCode`, and `codexCli` are boolean only
561
+ - If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `cjkFonts` is boolean or `"auto"`; `python`, `cloudflared`, `claudeCode`, `codexCli`, and `omoCli` are boolean only
528
562
  - No unknown top-level keys you invented — keys outside the documented core fields are interpreted as **plugin config blocks** and only do something if a plugin owns them. Inventing one means the user thinks it took effect and it did not.
529
563
 
530
564
  ## Things you must not do
@@ -543,7 +577,7 @@ Never request, echo, log, or commit values from `secrets.json` or `.env`. Gitign
543
577
  - **Do not promise to post to a channel the speaker's role does not cover.** The router drops every inbound where the speaking author resolves to a role without `channel.respond`. If the user wants you to post somewhere new, the prerequisite is a `roles` edit + restart, not a retry.
544
578
  - **Do not conflate "stop replying" with "remove the role's match-rule".** Removing the match-rule cuts off both inbound visibility and outbound posting. If the user just wants quieter behavior, edit `engagement` instead.
545
579
  - **Do not edit the `Dockerfile` directly.** It is autogenerated and rewritten on every `typeclaw start` from `src/init/dockerfile.ts` in the typeclaw repo. Manual edits will be silently overwritten (and auto-committed away if the working tree is dirty). Customizations belong in the `docker.file` block (toggles or `append`).
546
- - **Do not reach for `docker.file.append` when a toggle covers it.** If the user wants tmux, gh, python, ffmpeg, fonts-noto-cjk (cjkFonts), cloudflared, Anthropic's Claude Code CLI (claudeCode), or OpenAI's Codex CLI (codexCli) installed (or removed, or pinned), use the toggle. The apt toggles are the cache-mounted path; `cloudflared`, `claudeCode`, and `codexCli` are non-apt boolean toggles, and the `claudeCode`/`codexCli` toggles pair with the `typeclaw-claude-code`/`typeclaw-codex-cli` skills that document auth + usage. `append` for any of these is slower and harder to read.
580
+ - **Do not reach for `docker.file.append` when a toggle covers it.** If the user wants tmux, gh, python, ffmpeg, fonts-noto-cjk (cjkFonts), cloudflared, Anthropic's Claude Code CLI (claudeCode), OpenAI's Codex CLI (codexCli), or OmO Native (omoCli) installed (or removed, or pinned), use the toggle. The apt toggles are the cache-mounted path; `cloudflared`, `claudeCode`, `codexCli`, and `omoCli` are non-apt boolean toggles, and the `claudeCode`/`codexCli` toggles pair with the `typeclaw-claude-code`/`typeclaw-codex-cli` skills that document auth + usage. `append` for any of these is slower and harder to read.
547
581
  - **Do not use `docker.file.append` for things that belong in the template.** If the user wants a system package _every_ typeclaw user should have, that's a typeclaw release, not a per-agent `append`. Suggest filing an issue.
548
582
  - **Do not put multiline strings in `docker.file.append`.** The schema rejects entries with embedded `\n`/`\r`. Use one entry per Dockerfile instruction; chain shell logic with `&&` on one line.
549
583
  - **Do not pass `pkg=ver` as a toggle version string.** The schema rejects `=` in version strings. Pass just the version (`"gh": "2.40.0"`); the renderer prepends `pkg=` itself. Same for whitespace — version strings cannot contain spaces.
@@ -6,21 +6,22 @@ Companion to the **Dockerfile** section of the `typeclaw-config` SKILL.md. The S
6
6
 
7
7
  `docker.file` has two layers of customization:
8
8
 
9
- 1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`). Most are apt packages — boolean for on/off, version string for an apt pin (e.g. `"gh": "2.40.0"` → `gh=2.40.0`) — and benefit from BuildKit cache mounts. `cloudflared`, `claudeCode`, and `codexCli` are the exceptions: `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package; all three are boolean-only. Use a toggle whenever it covers what the user wants over a hand-rolled `append` entry.
9
+ 1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`, `omoCli`). Most are apt packages — boolean for on/off, version string for an apt pin (e.g. `"gh": "2.40.0"` → `gh=2.40.0`) — and benefit from BuildKit cache mounts. `cloudflared`, `claudeCode`, `codexCli`, and `omoCli` are the exceptions: `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package, and `omoCli` downloads digest-verified OmO Native 5.1.19 assets; all four are boolean-only. Use a toggle whenever it covers what the user wants over a hand-rolled `append` entry.
10
10
  2. **`append`** is the escape hatch for everything the toggles don't cover. An array of single-line Dockerfile instructions spliced in right before `ENTRYPOINT`, prefixed with a `# Custom lines from typeclaw.json#docker.file.append.` comment.
11
11
 
12
- | Field | Required | Type | Notes |
13
- | ------------- | -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14
- | `tmux` | no | boolean \| string | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`). |
15
- | `gh` | no | boolean \| string | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version. |
16
- | `python` | no | boolean | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin. |
17
- | `ffmpeg` | no | boolean \| string | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version. |
18
- | `cjkFonts` | no | boolean or `"auto"` | Default `"auto"`. Installs `fonts-noto-cjk` (~89 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `"auto"` resolves at `typeclaw start` from the host locale (`LANG`/`LC_ALL`/`Intl`): a CJK host (ja/ko/zh) installs the fonts, any other host skips them. An explicit `true`/`false` forces the decision. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes). |
19
- | `cloudflared` | no | boolean | Default `false`. Downloads the pinned `cloudflared` GitHub release (~38 MB) into the image so `cloudflare-quick` tunnels work. Default `false` skips the layer on agents that don't use tunnels; `typeclaw tunnel add` / `channel add github` with a Cloudflare provider flip it to `true` automatically and prompt for a restart, so the happy path needs no manual edit. If the binary is absent when a tunnel starts, the tunnel goes `permanently-failed` with a "set docker.file.cloudflared: true and run typeclaw restart" message. Boolean-only — pinning is owned by the typeclaw release. |
20
- | `xvfb` | no | boolean | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin. |
21
- | `claudeCode` | no | boolean | Default `false`. `true` runs Anthropic's official `curl -fsSL https://claude.ai/install.sh \| bash` in a dedicated layer (between agent-browser and the entrypoint shim) and pre-seeds `~/.claude.json` to skip the TTY-only theme picker on first launch (without it the agent's `tmux send-keys` would be eaten by the picker). Not apt: no version-pin variant; the upstream installer manages channels via env vars. Pairs with the `typeclaw-claude-code` skill, which documents the auth + tmux-driven usage flow including how to clear the post-seed API-key/trust dialogs. |
22
- | `codexCli` | no | boolean | Default `false`. `true` runs `bun install -g @openai/codex` in a dedicated layer (after `claudeCode`, before the entrypoint shim) and pre-writes `~/.codex/hooks.json` registering `SessionStart` + `Stop` hooks so the operator can detect turn boundaries the same way as Claude Code (sentinel files, `.session-id` discovery). Not apt: no version-pin variant. Codex CLI has NO theme picker so no onboarding seed is needed, but auth (`codex login` or `OPENAI_API_KEY`) and the per-project trust dialog are still required at runtime — handled by the `typeclaw-codex-cli` skill. |
23
- | `append` | no | array of strings | Each entry is a single Dockerfile line — schema **rejects** entries containing `\n` or `\r`. Defaults to `[]`. Splice happens just before `ENTRYPOINT`, after `ENV NODE_ENV=production`. |
12
+ | Field | Required | Type | Notes |
13
+ | ------------- | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
14
+ | `tmux` | no | boolean \| string | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`). |
15
+ | `gh` | no | boolean \| string | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version. |
16
+ | `python` | no | boolean | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin. |
17
+ | `ffmpeg` | no | boolean \| string | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version. |
18
+ | `cjkFonts` | no | boolean or `"auto"` | Default `"auto"`. Installs `fonts-noto-cjk` (~89 MB) so Chromium (used by every browser engine) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `"auto"` resolves at `typeclaw start` from the host locale (`LANG`/`LC_ALL`/`Intl`): a CJK host (ja/ko/zh) installs the fonts, any other host skips them. An explicit `true`/`false` forces the decision. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes). |
19
+ | `cloudflared` | no | boolean | Default `false`. Downloads the pinned `cloudflared` GitHub release (~38 MB) into the image so `cloudflare-quick` tunnels work. Default `false` skips the layer on agents that don't use tunnels; `typeclaw tunnel add` / `channel add github` with a Cloudflare provider flip it to `true` automatically and prompt for a restart, so the happy path needs no manual edit. If the binary is absent when a tunnel starts, the tunnel goes `permanently-failed` with a "set docker.file.cloudflared: true and run typeclaw restart" message. Boolean-only — pinning is owned by the typeclaw release. |
20
+ | `xvfb` | no | boolean | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, the managed shared browser, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin. |
21
+ | `claudeCode` | no | boolean | Default `false`. `true` runs Anthropic's official installer with version argument `2.1.299`, copies the resolved executable into root-owned `/usr/local/lib/typeclaw-coding-agents/claude/2.1.299/claude`, and links `/usr/local/bin/claude` there so model bash's bwrap sandbox can execute it without binding `/root`. The layer retains the existing hooks and `~/.claude.json` onboarding seed. Boolean-only; the version pin is owned by the TypeClaw release. Protected authentication profiles remain masked. |
22
+ | `codexCli` | no | boolean | Default `false`. `true` runs `bun install -g @openai/codex@0.162.1` with `BUN_INSTALL=/usr/local/lib/typeclaw-coding-agents/codex` and `BUN_INSTALL_BIN=/usr/local/lib/typeclaw-coding-agents/codex/bin`. The root-owned global package tree (including the vendored native binary) stays under `/usr/local`; `/usr/local/bin/codex` invokes its JS launcher with Bun because the image's `node` fallback is outside the sandbox PATH. The layer retains the existing hook scripts and `~/.codex/hooks.json`. Boolean-only; the version pin is owned by the TypeClaw release. Protected authentication profiles remain masked. |
23
+ | `omoCli` | no | boolean | Default `false`. Installs digest-verified OmO Native 5.1.19 (arm64 or amd64-baseline) under `/usr/local/lib/typeclaw-coding-agents/omo/5.1.19/`, linked from `/usr/local/bin/omo`. Both Dockerfile branches use the same pin. Task-local HOME/config and broker authority come from `coding_agent`; no provider profile is installed. See `typeclaw-omo-cli`. |
24
+ | `append` | no | array of strings | Each entry is a single Dockerfile line — schema **rejects** entries containing `\n` or `\r`. Defaults to `[]`. Splice happens just before `ENTRYPOINT`, after `ENV NODE_ENV=production`. |
24
25
 
25
26
  Toggle version strings reject whitespace and `=` (apt-injection guard) — pass just the version, not `pkg=ver`.
26
27
 
@@ -170,7 +170,7 @@ The handler receives a `ctx` with the LLM-call surface of a container plugin com
170
170
  | `ctx.signal` | `AbortSignal` | Reserved for future cancellation; currently never aborted by the runtime (matches existing prompt/exec cron behavior — in-flight work runs to completion on container shutdown). Already threaded into `ctx.prompt` and `ctx.exec`, so future aborts propagate without handler-author changes. |
171
171
  | `ctx.permissions` | `PermissionService` | Same service the rest of the runtime uses. Most handlers don't need it; the LLM session resolves permissions through `ctx.origin` automatically. |
172
172
  | `ctx.origin` | `SessionOrigin` (cron-shaped) | `{ kind: 'cron', jobId, jobKind: 'handler', scheduledByRole, scheduledByOrigin }`. Plugin-contributed jobs default to `scheduledByRole: 'owner'`. |
173
- | `ctx.prompt` | `(text: string) => Promise<string>` | Opens a brand-new agent session with the full toolset, sends `text`, returns the final assistant message. Uses **slim system prompt mode** (saves ~2000 tokens per LLM call vs a TUI session). |
173
+ | `ctx.prompt` | `(text: string) => Promise<string>` | Opens a brand-new agent session with the full toolset, sends `text`, returns the final assistant message. Gets the same shared system policy as every session, without the interactive orchestration context, roster, git nudge, or MCP catalog a TUI session adds. |
174
174
  | `ctx.subagent` | `(name: string, payload?) => Promise<void>` | Invokes a registered subagent. Same dispatch path as `PluginContext.spawnSubagent`. |
175
175
  | `ctx.exec` | `` ctx.exec`shell pipeline` `` → `Promise<CommandExecResult>` | Tagged template; runs in the agent folder with `ctx.signal` threaded through. Abort kills the entire process group (SIGTERM → 5s grace → SIGKILL). |
176
176
 
@@ -98,15 +98,15 @@ The same applies to PRs: a quick `gh pr list --search` avoids opening a PR for s
98
98
  ```sh
99
99
  gh issue create --repo OWNER/REPO --title '<conventional title>' --body '<filled body>'
100
100
  ```
101
- For a **pull request**, push the head branch yourself first when an eligible broker credential exists. Credential precedence is GitHub App, then an authorized PAT declared in `.env`, then the trusted GitHub CLI store. The store can fund a configured GitHub remote from any accessible repository path, including `workspace`, mounts, nested repositories, and `/tmp`. It accepts one configured destination and does not accept explicit-URL or `--set-upstream` pushes. Name the remote and branch explicitly:
101
+ For a **pull request**, push the head branch yourself first when an eligible broker credential exists. Credential precedence is GitHub App, then an authorized PAT declared in `.env`. The trusted GitHub CLI store is never a push credential: it funds `gh` work only. Name the remote and branch explicitly:
102
102
  ```sh
103
103
  git -C <checkout> push <remote> <branch>
104
104
  ```
105
- Then prepare the exact title, body, head branch and base branch and ask the operator to run this at the host stage from that same checkout:
105
+ Then open the PR yourself, with every field explicit and inline:
106
106
  ```sh
107
107
  gh pr create --repo OWNER/REPO --title '<conventional title>' --body '<filled body>' --head <branch> --base <branch>
108
108
  ```
109
- `gh pr create` is host-stage only: TypeClaw blocks it because it may invoke local Git hooks with reusable credentials. Fix ordinary Git errors yourself and retry; only hand the operator a push command when the broker or your permissions refuse it. If the trusted store is unavailable, ask the operator to run `gh auth login --hostname github.com` on the host; the next real `typeclaw start` or `typeclaw restart` refreshes it automatically, while a start against an already-running container does not. When handing off, name a host-accessible checkout; never direct the operator to a per-session `/tmp` path.
109
+ All five flags are required (`--draft` is optional). `--fill`, `--body-file`, `--template`, `--editor`, `--web` and `--attach` are refused because they read local files or open an editor/browser while the credential is live; omitting `--head` would make gh interrogate the checkout and offer to push. Fix ordinary Git errors yourself and retry. Without the `gitExfil` bypass, a plain one-branch push still works to repos listed in `channels.github.repos` under GitHub App auth; if `gitExfil` refuses it anyway, your role can't publish to that repository — surface the denial and only hand the operator a push command when the broker or your permissions refuse it. If the trusted store is unavailable, ask the operator to run `gh auth login --hostname github.com` on the host; the next real `typeclaw start` or `typeclaw restart` refreshes it automatically, while a start against an already-running container does not. When handing off, name a host-accessible checkout; never direct the operator to a per-session `/tmp` path.
110
110
  5. **Verify it landed** as intended (`gh issue view` / `gh pr view`) — confirm the template rendered and nothing got truncated.
111
111
 
112
112
  ## Things you must not do
@@ -5,7 +5,7 @@ description: Use this skill whenever the user asks what you remember, what you f
5
5
 
6
6
  # typeclaw-memory
7
7
 
8
- The agent's long-term memory is sharded across files in `memory/topics/<slug>.md`. Each shard is one topic with YAML frontmatter (`heading`, `cites`, `days`, `lastReinforced`, optional `tags`) + body markdown. Runtime owns the frontmatter — don't try to author it; write the body and let the runtime compute the metadata.
8
+ The agent's long-term memory is sharded across files in `memory/topics/<slug>.md`. Each shard is one topic with YAML frontmatter (`heading`, `cites`, `days`, `lastReinforced`, optional `tags`) + body markdown. The dreaming subagent writes shard bodies and the runtime computes the frontmatter; neither is yours to author.
9
9
 
10
10
  ## Reading
11
11
 
@@ -15,9 +15,9 @@ Under budget you get shard bodies de-duplicated across turns; over budget you ge
15
15
 
16
16
  ## Writing
17
17
 
18
- You don't author shards directly. The dreaming subagent (runs on a cron schedule, default every 30 minutes) reads undreamed fragments from `memory/streams/<date>.jsonl` and rebalances the shards.
18
+ You don't author shards directly. The dreaming subagent (runs on a cron schedule, default every 30 minutes) reads undreamed fragments from `memory/streams/<date>.jsonl` and rebalances the shards. Do not edit `memory/topics/`, `memory/skills/`, or the stream files yourself — the dreaming subagent and runtime own them. To capture something memorable, surface it in your reply and let the memory-logger append it to `memory/streams/`.
19
19
 
20
- If you have a procedure you've now done twice and want to externalize as muscle memory, write a skill at `memory/skills/<name>/SKILL.md`. The runtime auto-loads these as first-class skills on next boot. Skill name must be a single-segment kebab-case slug. Frontmatter requires `name` + `description`.
20
+ `memory/skills/<name>/SKILL.md` is muscle memory the dreaming subagent distills from recurring procedures; the runtime auto-loads those as first-class skills on next boot. A durable task procedure you want to keep goes to its existing editable owner skill (or a support file that skill links) first — see `typeclaw-skills` for who owns which skill — not into `memory/skills/` or `AGENTS.md`.
21
21
 
22
22
  ## Citations
23
23
 
@@ -89,7 +89,7 @@ To depend on a workspace package from the **agent root** (e.g. so cron `exec` jo
89
89
  {
90
90
  "dependencies": {
91
91
  "typeclaw": "file:../typeclaw",
92
- "agent-browser": "^0.33.0",
92
+ "agent-browser": "^0.39.1",
93
93
  "my-utility": "workspace:*"
94
94
  }
95
95
  }
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: typeclaw-omo-cli
3
+ description: Use for explicit OmO Native delegation, substantial coding or analysis suited to OmO, a second opinion, or an attempt to invoke omo. Runs the brokered coding_agent tool in a persistent isolated worktree through a background operator, with brokered internal subagents and no credential transfer.
4
+ ---
5
+
6
+ # Delegate to OmO Native
7
+
8
+ Brief the repository, task, constraints, and acceptance checks. Use the existing background `operator` for substantial work; its `coding_agent` invocation stays foreground while the main conversation remains responsive.
9
+
10
+ ## Prerequisites
11
+
12
+ The host operator enables `docker.file.omoCli:true`, configures `anthropic` or `openai-codex` through `typeclaw provider add <provider>`, and runs `typeclaw start` to rebuild the image. OmO Native 5.1.19 requires the supported Linux/bwrap profile. Use the tool's safe readiness diagnostic, never credential-file or environment inspection. See [auth-flow.md](references/auth-flow.md).
13
+
14
+ ## Run and continue
15
+
16
+ ```json
17
+ {
18
+ "action": "run",
19
+ "engine": "omo",
20
+ "repo": "/agent/mounts/project",
21
+ "modelRef": "anthropic/claude-sonnet-4-6",
22
+ "mode": "code",
23
+ "prompt": "Implement the requested change and run its tests.",
24
+ "timeoutSeconds": 1800
25
+ }
26
+ ```
27
+
28
+ Select a configured/curated `anthropic/...` or `openai-codex/...` model. One provider/model serves the parent, internal categories, named agents, and compaction. Other providers and model fallback are unavailable. `openai-codex` uses ChatGPT subscription OAuth, not an OpenAI API key.
29
+
30
+ Record `taskId`, `baseSha`, and `worktreePath`. The baseline is committed HEAD; dirty source changes are excluded. Never create a WIP commit to satisfy delegation. Use `mode:"plan"` for a read-only worktree and Git database. Implementation requires an explicit authorized transition:
31
+
32
+ ```json
33
+ {
34
+ "action": "run",
35
+ "engine": "omo",
36
+ "taskId": "<returned UUID>",
37
+ "mode": "code",
38
+ "prompt": "Implement the agreed plan and run the checks."
39
+ }
40
+ ```
41
+
42
+ The runtime retains the exact session UUID and checks that its saved session exists before resume. Do not select recent sessions, invent IDs, or rewrite OmO configuration. Engine, provider, model, and version remain fixed. See [headless-sessions.md](references/headless-sessions.md).
43
+
44
+ ## Review and recovery
45
+
46
+ Inspect `state`, `finalMessage`, `exitCode`, and the complete patch, including untracked and binary files. A JSON-mode provider failure can exit zero; the runner checks structured stop reasons. A question in any language needs a follow-up prompt, not keyword detection or polling. A claim that tests passed is not independent evidence.
47
+
48
+ Run acceptance checks and apply reviewed changes through ordinary tools. The tool never merges, pushes, or creates a PR in the source repository. Timeout, cancellation, and failure preserve partial work. Retrieve it with `{"action":"result","taskId":"<returned UUID>"}`. Discard a stopped task only when its work is no longer needed: `{"action":"dispose","taskId":"<returned UUID>","discard":true}`. See [results-and-worktrees.md](references/results-and-worktrees.md).
49
+
50
+ ## Credential boundary
51
+
52
+ OmO receives only a fresh local inference capability. Task-local HOME, sessions, and generated provider config contain no real provider credential. Do not run login flows, copy profiles, pass tokens, or disable TypeClaw sandboxing. OmO's native approvals are disabled only inside the outer sandbox; a bare `omo` shell invocation has no broker authority.
@@ -0,0 +1,11 @@
1
+ # OmO authentication through the broker
2
+
3
+ Host setup is `docker.file.omoCli:true`, `typeclaw provider add anthropic` or `typeclaw provider add openai-codex`, then `typeclaw start`. Anthropic supports API-key or subscription OAuth credentials; `openai-codex` supports ChatGPT subscription OAuth only. Do not silently switch billing surfaces.
4
+
5
+ The trusted runtime resolves and refreshes credentials. A per-invocation broker authenticates a fresh local capability, permits only the selected model and exact inference routes, rebuilds headers, and uses fixed upstreams. OmO's Anthropic OAuth capability has a transport compatibility prefix but is not a real OAuth token. The child never receives an access, refresh, or ID token, account identifier, or exported auth profile.
6
+
7
+ The generated provider config routes main, category, named-agent, and compaction calls through this broker. Categories use one explicit model chain; named agents clear inherited fallback chains. Memory side models, telemetry, update checks, ambient OAuth extensions, and MCP startup are disabled. Ordinary dependency downloads and tool networking remain governed by the outer sandbox, not by an offline marketing claim.
8
+
9
+ Missing credentials affect only the requested task. Ask the host operator to repair the chosen provider using its setup command, then retry. Missing binary or sandbox support requires an image rebuild or host namespace repair, never an unconfined fallback. Missing exact session data requires restoration or review of retained changes, not a fresh conversation disguised as a resume.
10
+
11
+ The guarantee covers private canonical credentials. Keys already exposed in `.env`, prompts, source objects, or model-readable files are outside it. Live subscription tools, resume, refresh, compaction, and Linux amd64/arm64 bwrap execution remain release gates; mock traffic does not establish upstream acceptance.
@@ -0,0 +1,11 @@
1
+ # Headless OmO sessions
2
+
3
+ The runtime invokes pinned OmO with `-p --mode json`, a concrete brokered model, an exact `--session-id`, and a task-local `--session-dir`. Prompt text travels over stdin. No terminal, tmux process, picker, or Stop-hook polling is involved.
4
+
5
+ The session header must match the recorded UUID and worktree. The runner extracts text from the last assistant in the final settled `agent_end.messages`, excluding custom messages, tools, and thinking. It resets completion on a new main `agent_start` and ignores retrying boundaries. It drains both pipes and waits for process exit.
6
+
7
+ Success requires clean JSONL, exit zero, a matching session header, a settled final run, and assistant `stopReason:"stop"`. `length` and `toolUse` are incomplete. `error` and `aborted` cannot become success even when OmO exits zero. Individual recoverable tool errors remain visible in the saved structured events.
8
+
9
+ A new tool call with the same TypeClaw `taskId` resumes the exact session. Runtime ownership checks, invocation locking, provider/model/version pinning, and fresh capabilities apply on every turn. Missing or unsafe session files do not trigger OmO's implicit fresh-session behavior.
10
+
11
+ Plan mode makes worktree and Git storage read-only, regardless of native approval policy. Task-local conversation state remains writable. Internal OmO children run in-process under the same outer sandbox; its task IDs are not TypeClaw authority. Processes do not survive invocation teardown. After interruption, preserve the diff and resume explicitly.
@@ -0,0 +1,23 @@
1
+ # OmO results and worktrees
2
+
3
+ Container-stage task state persists under `/agent/workspace/coding-agents/<task-id>/`:
4
+
5
+ ```text
6
+ git/ private Git object database
7
+ worktree/ detached checkout of recorded committed HEAD
8
+ omo/home/.omo/ generated orchestration config and provisioned native runtime
9
+ omo/agent/ generated models/settings and engine state
10
+ omo/sessions/ exact-session conversation files
11
+ omo/task-state/ internal OmO child-task records
12
+ omo/tmp/ task scratch
13
+ omo/config/ cache/ data/ state/ redirected XDG state
14
+ output/ JSONL, stderr, receipt, complete patch and change inventory
15
+ ```
16
+
17
+ The live source worktree and credential write directory are not mounted into the child. Snapshot bootstrap reads only source Git metadata; execution and artifact collection use task-private files. Ordinary project instructions remain available, while existing project/ancestor OmO config operands are masked so they cannot replace the generated model chains at launch.
18
+
19
+ The complete patch includes staged, unstaged, untracked, deleted, binary, executable-mode, and symlink changes against the recorded base. Capture does not mutate the CLI's index. Oversized artifacts are marked incomplete rather than presented as complete truncated patches.
20
+
21
+ Review the diff and run checks before applying it through normal tools. Timeout/failure preserves state; `result` retrieves it after restart. The private runtime registry, not editable CLI output, owns task authority and session identity.
22
+
23
+ Use explicit `dispose` with `discard:true` only for a stopped task whose work is no longer needed. Never prune sibling tasks or force-delete useful partial work. Task files stay outside system-managed memory/session backups. Shared workspace readers may inspect these non-secret artifacts; task IDs are not a separate tenant boundary.
@@ -25,12 +25,12 @@ You always have these four, even if `typeclaw.json` declares zero `roles`. User-
25
25
 
26
26
  Roles form a strict tower for **bypassable plugin guards**: each role bypasses guards at its tier and below. The canonical-secret invariant sits outside this tower.
27
27
 
28
- | Role | Built-in `match[]` | Tier bypass cap | Default `permissions[]` |
29
- | --------- | ----------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
- | `owner` | `["tui"]` (always prepended) | `high` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`, `security.bypass.low`, `security.bypass.medium`, `security.bypass.high`, plus every plugin-contributed `security.bypass.<guard>` (wildcard expansion) |
31
- | `trusted` | none | `medium` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`, `security.bypass.low`, `security.bypass.medium` |
32
- | `member` | none | `low` | `channel.respond`, `session.control`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `fs.see.private`, `security.bypass.low` |
33
- | `guest` | none (fallback when nothing else matches, or stamped role is bad) | (none) | none |
28
+ | Role | Built-in `match[]` | Tier bypass cap | Default `permissions[]` |
29
+ | --------- | ----------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
+ | `owner` | `["tui"]` (always prepended) | `high` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `browser.shared`, `fs.see.secrets`, `security.bypass.low`, `security.bypass.medium`, `security.bypass.high`, plus every plugin-contributed `security.bypass.<guard>` (wildcard expansion) |
31
+ | `trusted` | none | `medium` | `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `browser.shared`, `fs.see.secrets`, `security.bypass.low`, `security.bypass.medium` |
32
+ | `member` | none | `low` | `channel.respond`, `session.control`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `fs.see.private`, `browser.shared`, `security.bypass.low` |
33
+ | `guest` | none (fallback when nothing else matches, or stamped role is bad) | (none) | none |
34
34
 
35
35
  A session that doesn't match anything resolves to `guest`. `guest` has no `channel.respond`, so the router silently drops inbound messages whose author resolves to `guest`. **This is the most common cause of "the agent stopped responding"**: the user added a channel but did not add a match rule, so every speaker in that channel is `guest` and every inbound is dropped before you ever see it. There is no message in your session log when this happens — only a host-side line `[channels] <key>: denied by permissions (channel.respond) author=<id>`.
36
36
 
@@ -92,7 +92,7 @@ Things the DSL rejects (the parser emits actionable errors at boot, but you shou
92
92
 
93
93
  Three sources contribute permission strings:
94
94
 
95
- 1. **Core** (always present): `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`.
95
+ 1. **Core** (always present): `channel.respond`, `session.control`, `session.admin`, `cron.schedule`, `cron.modify`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `subagent.spawn.operator`, `fs.see.private`, `fs.see.secrets`, `browser.shared`.
96
96
  2. **Bundled security plugin** (always loaded): the eight per-guard strings (`security.bypass.secretExfilBash`, `security.bypass.gitExfil`, `security.bypass.gitRemoteTainted`, `security.bypass.secretExfilRead`, `security.bypass.ssrf`, `security.bypass.sessionSearchSecrets`, `security.bypass.systemPromptLeak`, `security.bypass.outboundSecret`) AND three severity-tier strings (`security.bypass.low`, `security.bypass.medium`, `security.bypass.high`).
97
97
  3. **User-declared plugins** (variable): each plugin can contribute its own strings via `definePlugin({ permissions: [...] })`.
98
98