typeclaw 0.49.0 → 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 (442) 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 +9 -2
  314. package/scripts/build-plugin-types.ts +105 -0
  315. package/scripts/check-plugin-sdk.ts +111 -0
  316. package/scripts/require-parallel.ts +5 -32
  317. package/src/agent/guard-types.ts +3 -0
  318. package/src/agent/guards.ts +4 -0
  319. package/src/agent/idle-compaction.ts +174 -0
  320. package/src/agent/index.ts +74 -16
  321. package/src/agent/live-subagents.ts +19 -0
  322. package/src/agent/multimodal/look-at.ts +22 -9
  323. package/src/agent/plugin-tools.ts +13 -1
  324. package/src/agent/reviewer-bash-policy.ts +41 -1
  325. package/src/agent/session-origin.ts +26 -10
  326. package/src/agent/subagent-cache-keepalive.ts +198 -0
  327. package/src/agent/subagent-session.ts +6 -0
  328. package/src/agent/subagents.ts +46 -8
  329. package/src/agent/system-prompt.ts +1 -1
  330. package/src/agent/tool-file-safety.ts +6 -1
  331. package/src/agent/tools/channel-edit.ts +20 -10
  332. package/src/agent/tools/channel-fetch-attachment.ts +12 -5
  333. package/src/agent/tools/channel-handoff.ts +72 -0
  334. package/src/agent/tools/channel-read.ts +57 -10
  335. package/src/agent/tools/channel-reply.ts +33 -26
  336. package/src/agent/tools/channel-send.ts +21 -13
  337. package/src/agent/tools/channel-session-search.ts +35 -0
  338. package/src/agent/tools/curl-impersonate.ts +11 -4
  339. package/src/agent/tools/ddg.ts +13 -5
  340. package/src/agent/tools/spawn-subagent.ts +27 -11
  341. package/src/agent/tools/stream-snapshot.ts +15 -2
  342. package/src/agent/tools/subagent-access.ts +11 -4
  343. package/src/browser/bsk-shim.mjs +74 -0
  344. package/src/browser/dockerfile.ts +84 -0
  345. package/src/browser/egress.ts +104 -0
  346. package/src/browser/managed-browser.ts +205 -0
  347. package/src/browser/registry.ts +110 -0
  348. package/src/browser/relay.ts +231 -0
  349. package/src/browser/sandbox-entry.ts +167 -0
  350. package/src/bundled-plugins/agent-browser/index.ts +2 -0
  351. package/src/bundled-plugins/browser-agent/browser-agent.ts +89 -0
  352. package/src/bundled-plugins/browser-agent/index.ts +12 -0
  353. package/src/bundled-plugins/doc-render/index.ts +0 -10
  354. package/src/bundled-plugins/doc-render/render.ts +83 -111
  355. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +152 -257
  356. package/src/bundled-plugins/github-cli-auth/gh-command.ts +4 -0
  357. package/src/bundled-plugins/github-cli-auth/git-auth-diagnostic.ts +95 -0
  358. package/src/bundled-plugins/github-cli-auth/index.ts +75 -59
  359. package/src/bundled-plugins/managed-browser/index.ts +74 -0
  360. package/src/bundled-plugins/managed-browser/skills/browser-use/browser-use/SKILL.md +27 -0
  361. package/src/bundled-plugins/managed-browser/skills/browserskill/browserskill/SKILL.md +28 -0
  362. package/src/bundled-plugins/managed-browser/skills/omowright/omowright/SKILL.md +40 -0
  363. package/src/bundled-plugins/operator/operator.ts +1 -1
  364. package/src/bundled-plugins/qa/index.ts +11 -0
  365. package/src/bundled-plugins/qa/qa.ts +160 -0
  366. package/src/bundled-plugins/qa/skills/qa-cli.ts +50 -0
  367. package/src/bundled-plugins/qa/skills/qa-general.ts +30 -0
  368. package/src/bundled-plugins/qa/skills/qa-http.ts +39 -0
  369. package/src/bundled-plugins/qa/skills/qa-pr.ts +51 -0
  370. package/src/bundled-plugins/qa/skills/qa-web.ts +49 -0
  371. package/src/bundled-plugins/security/index.ts +53 -34
  372. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  373. package/src/channels/adapter-namespace.ts +13 -0
  374. package/src/channels/adapters/discord-bot.ts +97 -5
  375. package/src/channels/adapters/github/index.ts +16 -0
  376. package/src/channels/adapters/github/last-alive.ts +4 -16
  377. package/src/channels/adapters/slack-attachment-download.ts +14 -3
  378. package/src/channels/adapters/slack-bot-author-resolver.ts +4 -3
  379. package/src/channels/adapters/slack-bot-channel-resolver.ts +9 -6
  380. package/src/channels/adapters/slack-bot-classify.ts +1 -0
  381. package/src/channels/adapters/slack-bot-slash-commands.ts +3 -1
  382. package/src/channels/adapters/slack-bot.ts +299 -67
  383. package/src/channels/adapters/slack-classify.ts +1 -0
  384. package/src/channels/catch-up.ts +137 -0
  385. package/src/channels/continuation-willingness.ts +2 -2
  386. package/src/channels/continuity-types.ts +1 -0
  387. package/src/channels/engagement.ts +17 -1
  388. package/src/channels/github-false-receipt.ts +3 -3
  389. package/src/channels/github-rereview-guard.ts +9 -5
  390. package/src/channels/github-token-bridge.ts +24 -0
  391. package/src/channels/last-alive.ts +34 -0
  392. package/src/channels/manager.ts +8 -1
  393. package/src/channels/router.ts +427 -136
  394. package/src/channels/session-handoff.fixture.ts +144 -0
  395. package/src/channels/session-handoff.ts +175 -0
  396. package/src/channels/session-search.ts +71 -0
  397. package/src/channels/types.ts +12 -2
  398. package/src/cli/channel.ts +2 -3
  399. package/src/cli/init.ts +2 -3
  400. package/src/cli/model.ts +132 -3
  401. package/src/coding-agent/index.ts +7 -1
  402. package/src/coding-agent/omo-stream.ts +40 -0
  403. package/src/coding-agent/runner.ts +30 -8
  404. package/src/config/config.ts +111 -22
  405. package/src/config/model-overrides.ts +59 -0
  406. package/src/config/models-mutation.ts +185 -2
  407. package/src/config/providers-mutation.ts +12 -4
  408. package/src/config/providers.ts +59 -0
  409. package/src/container/start.ts +95 -4
  410. package/src/doctor/checks.ts +8 -6
  411. package/src/hostd/daemon.ts +13 -1
  412. package/src/init/auto-upgrade.ts +7 -1
  413. package/src/init/dockerfile.ts +57 -12
  414. package/src/init/index.ts +4 -3
  415. package/src/init/local-source-stamp.ts +68 -0
  416. package/src/init/models-dev.ts +4 -0
  417. package/src/init/validate-api-key.ts +3 -0
  418. package/src/permissions/builtins.ts +7 -0
  419. package/src/permissions/permissions.ts +18 -9
  420. package/src/permissions/resolve.ts +7 -1
  421. package/src/plugin/context.ts +2 -0
  422. package/src/plugin/hooks.ts +137 -0
  423. package/src/plugin/index.ts +6 -0
  424. package/src/plugin/manager.ts +4 -0
  425. package/src/plugin/types.ts +60 -0
  426. package/src/run/bundled-plugins.ts +6 -0
  427. package/src/run/index.ts +24 -14
  428. package/src/run/llm-fetch-observer.ts +12 -15
  429. package/src/sandbox/canonical-secrets.ts +4 -0
  430. package/src/sandbox/dev-source.ts +26 -0
  431. package/src/sandbox/hidden-paths.ts +16 -2
  432. package/src/secrets/storage.ts +13 -0
  433. package/src/skills/typeclaw-channel-github/SKILL.md +8 -8
  434. package/src/skills/typeclaw-config/SKILL.md +39 -5
  435. package/src/skills/typeclaw-config/references/dockerfile.md +2 -2
  436. package/src/skills/typeclaw-github-contributing/SKILL.md +1 -1
  437. package/src/skills/typeclaw-monorepo/SKILL.md +1 -1
  438. package/src/skills/typeclaw-permissions/SKILL.md +7 -7
  439. package/src/skills/typeclaw-troubleshooting/SKILL.md +12 -1
  440. package/typeclaw.schema.json +436 -5
  441. package/src/bundled-plugins/doc-render/templates/lib.typ +0 -339
  442. package/src/bundled-plugins/github-cli-auth/gh-store.ts +0 -733
@@ -22,17 +22,12 @@ import {
22
22
  canInjectPatIntoPassThroughGh,
23
23
  effectiveGhTokensForAuthenticatedUserEndpoint,
24
24
  effectiveGhTokensForCommand,
25
+ hasGhInvocation,
25
26
  usesGhApiGraphqlEndpoint,
26
27
  } from './gh-command'
27
28
  import { detectReviewDismissal } from './gh-review-detect'
28
- import {
29
- cleanupPreparedGithubStorePush,
30
- GH_STORE_AMBIENT_AUTH_KEYS,
31
- planGithubStorePush,
32
- prepareGithubStorePush,
33
- resolveGithubCliStoreToken,
34
- } from './gh-store'
35
29
  import { ensureGitAskPassHelper, resolveSandboxGitAskPassPath } from './git-askpass'
30
+ import { appendGitAuthDiagnostic, createGitAuthLoginResolver, type GitAuthCredential } from './git-auth-diagnostic'
36
31
  import {
37
32
  analyzeGitCommand,
38
33
  createSessionTmpGitResolvers,
@@ -88,6 +83,15 @@ export default definePlugin({
88
83
  const hasAppTokenResolver = ctx.github.hasAppTokenResolver
89
84
  const trustedGitTransportEnv: NodeJS.ProcessEnv = { ...process.env }
90
85
  const reviewCredentials = new Map<string, GithubTokenCredential>()
86
+ const resolveGitAuthLogin = createGitAuthLoginResolver()
87
+ const gitAuthDiagnostics = new Map<
88
+ string,
89
+ {
90
+ credentials: GitAuthCredential[]
91
+ ghCredential?: GitAuthCredential
92
+ push: boolean
93
+ }
94
+ >()
91
95
 
92
96
  // Every model-driven bash masks the canonical credential files. A role may
93
97
  // still USE a PAT through this runtime-owned overlay, which injects one
@@ -193,18 +197,14 @@ export default definePlugin({
193
197
  const missingAppAuthForPushReason =
194
198
  'Pushing to github.com needs an eligible credential and validated destination, and TypeClaw has nothing it can give this git command. ' +
195
199
  'Operator remedy: declare `GH_TOKEN` in the agent `.env` and restart, configure GitHub App auth under ' +
196
- '`channels.github` for per-repo short-lived tokens, or authenticate host `gh` with ' +
197
- '`gh auth login --hostname github.com`; the next real `typeclaw start` or `typeclaw restart` automatically captures ' +
198
- 'that active account into the trusted-runtime store (a start against an already-running container is a no-op). ' +
200
+ '`channels.github` for per-repo short-lived tokens, or (PAT channel auth) list the repo in ' +
201
+ '`channels.github.repos[]` so its PAT can fund the push. ' +
202
+ 'The host `gh` login never funds a push, even when ' +
203
+ '`githubCli.importHostAuth` is enabled. ' +
199
204
  'If App auth is already configured, the adapter failed to start — check ' +
200
205
  '`typeclaw logs`. Do not retry with ' +
201
206
  '`gh auth setup-git`, a credential helper, or a tokenized remote URL: those are blocked and the ' +
202
207
  'credential files are masked in this sandbox.'
203
- const multiPushStoreReason =
204
- 'The trusted GitHub CLI credential store can fund exactly one configured push repository. ' +
205
- 'This remote has multiple GitHub push destinations; use an authoritative declared PAT or GitHub App auth, ' +
206
- 'or configure exactly one push URL.'
207
-
208
208
  let warnedSandboxedPatWithheld = false
209
209
  const warnSandboxedPatWithheldOnce = (): void => {
210
210
  if (warnedSandboxedPatWithheld) return
@@ -416,7 +416,10 @@ export default definePlugin({
416
416
  }
417
417
 
418
418
  if (decision.kind === 'pass-through') {
419
- const patOverlay = canUsePat(event.origin) ? processPatOverlay() : undefined
419
+ // The caller routes on a raw `gh` substring, so `git commit -m "...wright..."`
420
+ // lands here. With no real `gh` invocation there is nothing to broker the
421
+ // PAT to: fall through without the overlay instead of blocking.
422
+ const patOverlay = canUsePat(event.origin) && hasGhInvocation(command) ? processPatOverlay() : undefined
420
423
  if (patOverlay !== undefined) {
421
424
  if (!canInjectPatIntoPassThroughGh(command)) {
422
425
  return blockAfterLease({
@@ -551,6 +554,20 @@ export default definePlugin({
551
554
  decision.pushProvenance?.kind === 'configured-remote'
552
555
  ? decision.pushProvenance.repoSlugs
553
556
  : [decision.repoSlug.toLocaleLowerCase()]
557
+ const noteGitCredential = (credentials: GitAuthCredential[]): void => {
558
+ // Match handleGhCommand's no-minter precedence. With a minter, gh uses
559
+ // the same per-repo credential as git, so no comparison is needed.
560
+ const ghToken = !hasAppTokenResolver()
561
+ ? (sandboxInheritedGhToken() ?? (canUsePat(event.origin) ? effectiveProcessToken() : undefined))
562
+ : undefined
563
+ gitAuthDiagnostics.set(event.callId, {
564
+ credentials,
565
+ ...(ghToken !== undefined
566
+ ? { ghCredential: { source: `github repo token via ${ghToken.envName}`, token: ghToken.value } }
567
+ : {}),
568
+ push: decision.access === 'write',
569
+ })
570
+ }
554
571
 
555
572
  if (!hasAppTokenResolver()) {
556
573
  const declared = declaredGitCredentialState()
@@ -574,54 +591,42 @@ export default definePlugin({
574
591
  // Withhold wins only when the same ambient names are absent from the overlay.
575
592
  event.args[TYPECLAW_INTERNAL_BASH_WITHHOLD_ENV] = ['GH_TOKEN', 'GITHUB_TOKEN']
576
593
  if (decision.rewrittenCommand !== undefined) event.args.command = decision.rewrittenCommand
594
+ noteGitCredential([{ source: `declared .env ${declared.envName}`, token: declared.value }])
577
595
  return
578
596
  }
579
597
  if (decision.access !== 'write') return
580
- if (declared.kind !== 'absent') return { block: true, reason: missingAppAuthForPushReason }
581
- if (destinationRepos.length !== 1) return { block: true, reason: multiPushStoreReason }
582
-
583
- const askpass = await ensureGitAskPassHelper(resolveSandboxGitAskPassPath())
584
- const plan = await planGithubStorePush(decision, { agentDir, sessionId, askpassPath: askpass })
585
- if (plan === null) return { block: true, reason: missingAppAuthForPushReason }
586
- const storeToken = await resolveGithubCliStoreToken()
587
- if (storeToken === null) return { block: true, reason: missingAppAuthForPushReason }
588
- const credentialEnv = await buildGitCredentialOverlay(
589
- [{ repoSlug: plan.repo, token: storeToken }],
590
- event.args[TYPECLAW_INTERNAL_BASH_ENV],
591
- { expectedRemote: plan.remote, trustedEnv: {} },
592
- )
593
- event.args[TYPECLAW_INTERNAL_BASH_ENV] = credentialEnv
594
- const inheritedNames = [
595
- ...Object.keys(process.env),
596
- ...Object.keys(credentialEnv),
597
- 'SSH_ASKPASS',
598
- 'SSH_AUTH_SOCK',
599
- 'HTTP_PROXY',
600
- 'HTTPS_PROXY',
601
- 'ALL_PROXY',
602
- 'http_proxy',
603
- 'https_proxy',
604
- 'all_proxy',
605
- ]
606
- event.args[TYPECLAW_INTERNAL_BASH_WITHHOLD_ENV] = [
607
- ...new Set([
608
- ...GH_STORE_AMBIENT_AUTH_KEYS,
609
- ...inheritedNames.filter(
610
- (name) => name.startsWith('GIT_') || name.startsWith('SSH_') || /proxy/i.test(name),
611
- ),
612
- ]),
613
- ]
614
- event.args[TYPECLAW_INTERNAL_BASH_PREPARE] = async () => {
615
- const prepared = await prepareGithubStorePush(plan)
616
- if (prepared === null) throw new Error(missingAppAuthForPushReason)
617
- return {
618
- command: prepared.command,
619
- env: prepared.env,
620
- mount: prepared.mount,
621
- cleanup: async () => await cleanupPreparedGithubStorePush(prepared.backingGitDir),
598
+ // PAT-mode channel auth lends its PAT for configured repos (the adapter enforces
599
+ // repos[]). Only an absent `.env` declaration falls through here: an invalid one
600
+ // stays blocked rather than being silently replaced by a different credential.
601
+ if (declared.kind === 'absent' && canUsePat(event.origin) && ctx.github.resolvePatForRepo !== undefined) {
602
+ const credentials: GitRepoCredential[] = []
603
+ for (const repoSlug of destinationRepos) {
604
+ const result = await ctx.github.resolvePatForRepo(repoSlug)
605
+ if (result.kind === 'unavailable') {
606
+ return { block: true, reason: `${missingAppAuthForPushReason} Channel PAT: ${result.reason}` }
607
+ }
608
+ credentials.push({ repoSlug, token: result.token })
622
609
  }
610
+ event.args[TYPECLAW_INTERNAL_BASH_ENV] = await buildGitCredentialOverlay(
611
+ credentials,
612
+ event.args[TYPECLAW_INTERNAL_BASH_ENV],
613
+ {
614
+ expectedRemote:
615
+ decision.pushProvenance?.kind === 'configured-remote' ? decision.pushProvenance.remote : undefined,
616
+ pushUrls:
617
+ decision.pushProvenance?.kind === 'configured-remote' ? decision.pushProvenance.pushUrls : undefined,
618
+ trustedEnv: trustedGitTransportEnv,
619
+ },
620
+ )
621
+ event.args[TYPECLAW_INTERNAL_BASH_WITHHOLD_ENV] = ['GH_TOKEN', 'GITHUB_TOKEN']
622
+ if (decision.rewrittenCommand !== undefined) event.args.command = decision.rewrittenCommand
623
+ noteGitCredential(credentials.map(({ token }) => ({ source: 'GitHub channel PAT', token })))
624
+ return
623
625
  }
624
- return
626
+ // The host `gh` login is the operator's identity, not the agent's, so it never funds
627
+ // a push: anything it signed would land on GitHub as the operator. App auth and an
628
+ // authoritative declared PAT stay the authorized push credentials.
629
+ return { block: true, reason: missingAppAuthForPushReason }
625
630
  }
626
631
  const credentials: GitRepoCredential[] = []
627
632
  for (const repoSlug of destinationRepos) {
@@ -652,6 +657,12 @@ export default definePlugin({
652
657
  )
653
658
  if (grantedPush !== undefined) event.args.command = grantedPush.command
654
659
  else if (decision.rewrittenCommand !== undefined) event.args.command = decision.rewrittenCommand
660
+ noteGitCredential(
661
+ credentials.map(({ repoSlug, token }) => ({
662
+ source: `per-repo GitHub App token for ${repoSlug}`,
663
+ token,
664
+ })),
665
+ )
655
666
  return
656
667
  }
657
668
 
@@ -705,6 +716,11 @@ export default definePlugin({
705
716
  return
706
717
  },
707
718
  'tool.after': async (event) => {
719
+ const gitAuth = gitAuthDiagnostics.get(event.callId)
720
+ gitAuthDiagnostics.delete(event.callId)
721
+ if (event.tool === 'bash' && gitAuth !== undefined) {
722
+ await appendGitAuthDiagnostic({ result: event.result, ...gitAuth, resolveLogin: resolveGitAuthLogin })
723
+ }
708
724
  checkGraphqlAuthNudge({ tool: event.tool, result: event.result })
709
725
  const dismissal = pendingDismissals.get(event.callId)
710
726
  pendingDismissals.delete(event.callId)
@@ -0,0 +1,74 @@
1
+ import { join } from 'node:path'
2
+
3
+ import { TYPECLAW_INTERNAL_BASH_ENV } from '@/agent/plugin-tools'
4
+ import { type ManagedBrowser, startManagedBrowser } from '@/browser/managed-browser'
5
+ import { BROWSER_ENGINES, type BrowserConfig, needsManagedBrowser } from '@/browser/registry'
6
+ import { getConfig } from '@/config'
7
+ import type { PermissionService } from '@/permissions'
8
+ import { CORE_PERMISSIONS } from '@/permissions/builtins'
9
+ import { definePlugin, type Hooks } from '@/plugin'
10
+
11
+ const SKILLS_ROOT = join(import.meta.dir, 'skills')
12
+
13
+ export default definePlugin({
14
+ plugin: async (ctx) => {
15
+ // Boot snapshot: `browser` is restart-required, matching the image layers
16
+ // and the browser process started below.
17
+ const browser = getConfig().browser
18
+ const skillsDirs = browserSkillDirs(browser)
19
+ if (!needsManagedBrowser(browser)) return { skillsDirs }
20
+
21
+ let managed: ManagedBrowser
22
+ try {
23
+ managed = await startManagedBrowser({ agentDir: ctx.agentDir, browser, logger: ctx.logger })
24
+ } catch (error) {
25
+ ctx.logger.error(`managed browser failed to start; browser engines are unavailable: ${String(error)}`)
26
+ return { skillsDirs }
27
+ }
28
+ const overlay = browserEnvOverlay(browser, managed)
29
+
30
+ return {
31
+ skillsDirs,
32
+ hooks: { 'tool.before': sharedBrowserBashHook(ctx.permissions, overlay) },
33
+ onDispose: () => managed.stop(),
34
+ }
35
+ },
36
+ })
37
+
38
+ export function sharedBrowserBashHook(
39
+ permissions: PermissionService,
40
+ overlay: Record<string, string>,
41
+ ): NonNullable<Hooks['tool.before']> {
42
+ return (event) => {
43
+ if (event.tool !== 'bash') return
44
+ if (!permissions.has(event.origin, CORE_PERMISSIONS.browserShared)) return
45
+ const existing = event.args[TYPECLAW_INTERNAL_BASH_ENV]
46
+ const current = existing !== null && typeof existing === 'object' ? (existing as Record<string, string>) : {}
47
+ event.args[TYPECLAW_INTERNAL_BASH_ENV] = { ...current, ...overlay }
48
+ }
49
+ }
50
+
51
+ export function browserSkillDirs(browser: BrowserConfig): string[] {
52
+ const ids = [...browser.engines.filter((id) => id !== 'agent-browser'), ...browser.extensions]
53
+ // One root per id (skills/<id>/<skill>/SKILL.md) so disabled engines stay out of the catalog.
54
+ return ids.map((id) => join(SKILLS_ROOT, id))
55
+ }
56
+
57
+ export function browserEnvOverlay(
58
+ browser: BrowserConfig,
59
+ managed: Pick<ManagedBrowser, 'cdpUrl' | 'filesDir' | 'bskRelay' | 'token'>,
60
+ ) {
61
+ const env: Record<string, string> = {
62
+ TYPECLAW_BROWSER_CDP_URL: managed.cdpUrl,
63
+ TYPECLAW_BROWSER_FILES: managed.filesDir,
64
+ }
65
+ // agent-browser is in every image and bundled skills (qa, PDF) call it
66
+ // directly, so it always joins the shared browser while one is running.
67
+ for (const id of new Set(['agent-browser' as const, ...browser.engines])) {
68
+ Object.assign(env, BROWSER_ENGINES[id].env(managed.cdpUrl))
69
+ }
70
+ if (managed.bskRelay !== undefined) {
71
+ Object.assign(env, { TYPECLAW_BSK_RELAY: managed.bskRelay, TYPECLAW_BSK_TOKEN: managed.token })
72
+ }
73
+ return env
74
+ }
@@ -0,0 +1,27 @@
1
+ ---
2
+ name: browser-use
3
+ description: Browser Use CLI for driving the shared TypeClaw browser from Python snippets over CDP. Use for browsing, clicking, scraping and screenshots when you prefer Python helpers.
4
+ ---
5
+
6
+ # browser-use
7
+
8
+ The `browser-use` CLI runs a Python snippet with browser helpers pre-imported. `$BU_CDP_WS` points it at the shared browser. If the variable is unset, this session's role cannot use the shared browser (it needs the `browser.shared` permission) or the browser failed to start; the operator log (`typeclaw logs`) names which. Do not try to start Chrome yourself.
9
+
10
+ ```bash
11
+ browser-use <<'PY'
12
+ new_tab("https://example.com")
13
+ wait_for_load()
14
+ print(page_info())
15
+ PY
16
+ ```
17
+
18
+ Run `browser-use skill` once to read the full helper reference (`ensure_real_tab`, `click_at_xy`, `cdp(...)`, screenshots). Its tabs are marked with a horse emoji in the title; keep to those.
19
+
20
+ Never run `browser-use --update`, `browser-use auth login`, or remote/cloud daemons (`start_remote_daemon`): the version is pinned by TypeClaw and cloud browsers are not part of this setup.
21
+
22
+ ## Shared browser rules
23
+
24
+ - One TypeClaw-managed Chrome serves every engine and every session that has `browser.shared`. Logins and tabs persist across bash calls and sessions.
25
+ - Work only in tabs you opened. Never navigate or close a tab another engine or session is using.
26
+ - Files: downloads land in `$TYPECLAW_BROWSER_FILES`; to upload a file, copy it there first and pass that path. Chrome cannot see other paths.
27
+ - The browser runs in its own sandbox with no view of the agent folder, so `file://` URLs outside `$TYPECLAW_BROWSER_FILES` fail by design.
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: browserskill
3
+ description: BrowserSkill (bsk) CLI driving the shared TypeClaw browser through its extension. Use for semantic page observation, table/list extraction, recording traces, and website debugging evidence.
4
+ ---
5
+
6
+ # browserskill
7
+
8
+ The `bsk` CLI talks to a daemon TypeClaw runs next to the shared browser; the BrowserSkill extension is preloaded and connected. `bsk` reaches that daemon through `$TYPECLAW_BSK_RELAY`; do not set `BSK_HOME` yourself. If the variable is unset, this session's role cannot use the shared browser (it needs the `browser.shared` permission) or the browser failed to start; the operator log (`typeclaw logs`) names which. Do not try to start Chrome yourself.
9
+
10
+ ```bash
11
+ bsk status --json # a connected browser must be listed
12
+ SID=$(bsk session start --json | jq -r .session_id)
13
+ bsk navigate https://example.com --session "$SID"
14
+ bsk snapshot --session "$SID" # @eN refs
15
+ bsk click @e3 --session "$SID"
16
+ bsk session stop "$SID" # always stop, success or failure
17
+ ```
18
+
19
+ - Sessions open their own Agent Window. Never borrow an existing tab: borrowing asks a human to confirm, and nobody can click it here.
20
+ - `bsk --help` and `bsk <command> --help` list everything (`extract`, `observe`, `record`, `debug`).
21
+ - Never run `bsk update`, `bsk daemon stop`, or `bsk daemon restart`; TypeClaw owns the daemon and its version.
22
+
23
+ ## Shared browser rules
24
+
25
+ - One TypeClaw-managed Chrome serves every engine and every session that has `browser.shared`. Logins and tabs persist across bash calls and sessions.
26
+ - Work only in tabs you opened. Never navigate or close a tab another engine or session is using.
27
+ - Files: downloads land in `$TYPECLAW_BROWSER_FILES`; to upload a file, copy it there first and pass that path. Chrome cannot see other paths.
28
+ - The browser runs in its own sandbox with no view of the agent folder, so `file://` URLs outside `$TYPECLAW_BROWSER_FILES` fail by design.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: omowright
3
+ description: Playwright-shaped browser automation library (OmOWright) for the shared TypeClaw browser. Use for browsing, clicking, form filling, accessibility snapshots, scrolling feeds and collecting JSON from network responses while scrolling.
4
+ ---
5
+
6
+ # omowright
7
+
8
+ OmOWright is a JavaScript library with the Playwright API shape (`page.goto`, `page.locator(ref).click()`, `page.mouse.wheel`, `page.keyboard.type`, `page.screenshot`). Write a short Bun script and run it with `bun`. Each script connects to the shared browser, so state survives between scripts.
9
+
10
+ `$OMOWRIGHT_CDP_URL` holds the connection URL. If the variable is unset, this session's role cannot use the shared browser (it needs the `browser.shared` permission) or the browser failed to start; the operator log (`typeclaw logs`) names which. Do not try to start Chrome yourself.
11
+
12
+ ```js
13
+ // save as /tmp/browse.mjs, run: bun /tmp/browse.mjs
14
+ import { compactSnapshot, connect, createAgentTabs } from '/usr/local/lib/typeclaw-browser/omowright/index.js'
15
+
16
+ const url = process.env.OMOWRIGHT_CDP_URL
17
+ // The relay requires the token on every request; omowright drops the URL query
18
+ // for HTTP discovery (listTargets), so pass it as an Authorization header too.
19
+ const token = new URL(url).searchParams.get('token')
20
+ const browser = await connect(url, {
21
+ client: { authorizer: { resolveAuthorization: async () => `Bearer ${token}` } },
22
+ })
23
+ const tabs = createAgentTabs(browser) // background tabs that never steal focus
24
+ const page = await tabs.open('https://example.com')
25
+ console.log(compactSnapshot(await page.snapshot())) // refs like [ref=e1]
26
+ await page.locator('e1').click()
27
+ process.exit(0) // leaves the tab and browser running
28
+ ```
29
+
30
+ - Prefer `compactSnapshot(await page.snapshot())` over screenshots; re-snapshots come back as a diff.
31
+ - Long lists: `createNetworkSnoop` + `collectWhileScrolling` read the page's JSON instead of scraping rows.
32
+ - Canvas or custom widgets: `createCua(page)` gives coordinate-level clicks and scrolls.
33
+ - `connectPipe()` and `connectBrowserSkill()` launch or find other browsers; do not use them here.
34
+
35
+ ## Shared browser rules
36
+
37
+ - One TypeClaw-managed Chrome serves every engine and every session that has `browser.shared`. Logins and tabs persist across bash calls and sessions.
38
+ - Work only in tabs you opened. Never navigate or close a tab another engine or session is using.
39
+ - Files: downloads land in `$TYPECLAW_BROWSER_FILES`; to upload a file, copy it there first and pass that path. Chrome cannot see other paths.
40
+ - The browser runs in its own sandbox with no view of the agent folder, so `file://` URLs outside `$TYPECLAW_BROWSER_FILES` fail by design.
@@ -82,7 +82,7 @@ export function createOperatorSubagent(): Subagent<OperatorPayload> {
82
82
  payloadSchema: operatorPayloadSchema,
83
83
  visibility: 'public',
84
84
  rosterDescription:
85
- 'write-capable: bash-with-side-effects, write, edit, coding_agent — for browser sessions, refactors, deploys, batch ops, and brokered Claude Code/Codex delegation; runs at YOUR role',
85
+ 'write-capable: bash-with-side-effects, write, edit, coding_agent — for refactors, deploys, batch ops, and brokered Claude Code/Codex delegation; runs at YOUR role',
86
86
  // No `requiresSpecificPermission`: a subagent inherits `spawnedByRole`, and
87
87
  // main sessions are never narrowed to a subset of the builtin tools, so a
88
88
  // caller already holds every tool listed above. Gating the spawn bought no
@@ -0,0 +1,11 @@
1
+ import { definePlugin } from '@/plugin'
2
+
3
+ import { createQaSubagent } from './qa'
4
+
5
+ export default definePlugin({
6
+ plugin: async (ctx) => ({
7
+ subagents: {
8
+ qa: createQaSubagent({ resolveTokenForRepo: ctx.github.resolveTokenForRepo }),
9
+ },
10
+ }),
11
+ })
@@ -0,0 +1,160 @@
1
+ import { z } from 'zod'
2
+
3
+ import { createReviewerCheckoutTool } from '@/bundled-plugins/github-cli-auth/review-checkout'
4
+ import type { ResolveGithubTokenForRepo } from '@/channels/github-token-bridge'
5
+ import {
6
+ bashTool,
7
+ createLoadSkillTool,
8
+ findTool,
9
+ grepTool,
10
+ type LoadableSkill,
11
+ lsTool,
12
+ readTool,
13
+ type Subagent,
14
+ webFetchTool,
15
+ webSearchTool,
16
+ writeTool,
17
+ } from '@/plugin'
18
+
19
+ import { CLI_QA_SKILL } from './skills/qa-cli'
20
+ import { GENERAL_QA_SKILL } from './skills/qa-general'
21
+ import { HTTP_QA_SKILL } from './skills/qa-http'
22
+ import { PR_QA_SKILL } from './skills/qa-pr'
23
+ import { WEB_QA_SKILL } from './skills/qa-web'
24
+
25
+ // Ordered by expected frequency; `qa-general` stays last as the fallback, the same
26
+ // convention as REVIEWER_SKILLS.
27
+ export const QA_SKILLS: readonly LoadableSkill[] = [
28
+ PR_QA_SKILL,
29
+ WEB_QA_SKILL,
30
+ CLI_QA_SKILL,
31
+ HTTP_QA_SKILL,
32
+ GENERAL_QA_SKILL,
33
+ ]
34
+
35
+ // QA builds, installs dependencies, boots servers, and drives browsers, so it
36
+ // routinely outlasts a review. Same 30m ceiling as the other deep-profile
37
+ // subagents (reviewer, researcher): liveness for the parent, not cancellation.
38
+ export const QA_SPAWN_TIMEOUT_MS = 1_800_000
39
+
40
+ export const QA_SYSTEM_PROMPT = `You are a QA tester running inside TypeClaw. Your job: exercise a product, a repository, or a code change through its REAL user-facing surface and return an evidence-backed verdict on whether it works.
41
+
42
+ The \`reviewer\` reads code and judges it. You do the other half: you RUN it. A claim you did not observe through an executed command, a rendered page, or a captured response is not a QA result.
43
+
44
+ === WHAT YOU MAY CHANGE ===
45
+ You run builds, installs, servers, browsers, and test suites, so your bash is not read-only. Your side effects are bounded to a private scratch area:
46
+
47
+ - Work only inside a scratch directory under \`/tmp/qa/<run-id>/\` (pick a short unique run id). Clone, install, build, write helper scripts, and store evidence there.
48
+ - NEVER edit, commit, push, or "fix" the product under test. If you find a bug, you report it; the parent decides what happens next. A QA run that patches the code until it passes has destroyed its own evidence.
49
+ - NEVER weaken an assertion, skip a failing check, or mark a recovered step as a pass.
50
+ - NEVER post to GitHub, Slack, Discord, or any channel. The parent owns posting.
51
+ - Do not touch the agent's own workspace files, secrets, or config. Do not run destructive commands against shared or production systems; QA targets staging, local builds, or what the caller explicitly named.
52
+ - Stop every server, browser, and background process you started before you finish.
53
+
54
+ Each \`bash\` call runs in its own sandbox, and a process it backgrounds can die when that call returns. Files under \`/tmp\` persist between calls; processes do not. So start a server, wait for it, exercise it, and stop it inside ONE \`bash\` invocation, usually a script you \`write\` to your scratch directory and then run.
55
+
56
+ ## Tools
57
+
58
+ - \`read\`, \`grep\`, \`find\`, \`ls\` — inspect files and the target's source/docs
59
+ - \`bash\` — clone, install, build, run, drive CLIs, curl endpoints, drive a browser (the \`agent-browser\` CLI is always installed; other enabled engines ship their own skill)
60
+ - \`write\` — helper scripts and evidence notes inside your scratch directory only
61
+ - \`web_search\`, \`web_fetch\` — public docs or a deployed URL's static content
62
+ - \`load_skill\` — load a QA playbook for the surface under test (see below)
63
+ - \`github_prepare_review_checkout\` — when available, acquire a private GitHub repo at an exact SHA
64
+
65
+ ## Loading a QA skill
66
+
67
+ Surface-specific craft lives in skills you load on demand. First read the payload and decide what is being tested: a pull request or repository, a web app or URL, a CLI or TUI, an HTTP API, or something else. Then call \`load_skill\` with the matching name before you plan. Load a second skill when the target spans surfaces (a PR that changes a web page loads \`qa-pr\` and \`qa-web\`). If nothing fits, load \`qa-general\`. Keep the selection internal — do not narrate it in \`<summary>\`.
68
+
69
+ ## The QA loop
70
+
71
+ 1. **Plan.** Turn the request into explicit acceptance criteria: what must work, the riskiest edge (empty, boundary, malformed, unauthorized, concurrent), and one adjacent behavior that could regress. Every stated success criterion gets a scenario.
72
+ 2. **Prepare.** Isolate state in your scratch directory. Record the target identity (URL, binary version, commit SHA), the environment, and the exact commands used to install and start it. Wait for readiness on an observable signal (a port answering, a log line), never a fixed sleep.
73
+ 3. **Execute.** Exercise the behavior the way a user would: the real CLI, the real page, the real endpoint. Include at least one negative path.
74
+ 4. **Capture.** Save evidence while you run, for passes as well as failures: command transcripts with exit codes, HTTP status/headers/body, screenshots, console errors. Every scenario names its artifact path AND quotes the decisive evidence inline: your scratch directory is private to this run, so the parent usually cannot open the path. For a screenshot, describe exactly what it shows.
75
+ 5. **Judge.** Compare observed against expected that you wrote BEFORE running. Classify each failure: product defect, harness/setup failure, or environment limitation. A failure you caused (wrong command, missing env) is a harness issue to fix and retry, not a product bug.
76
+ 6. **Reproduce.** Re-run a failing scenario once to confirm it is not flaky; keep both attempts in the record.
77
+
78
+ ## Verdict rules
79
+
80
+ - \`pass\` — every required scenario was executed and passed with an artifact. "The agent finished" is not a pass.
81
+ - \`fail\` — at least one required scenario failed on a confirmed product defect.
82
+ - \`inconclusive\` — required scenarios could not run (blocked setup, missing credentials, unreachable target) and nothing failed. Name exactly what blocked you and what the caller must provide.
83
+
84
+ Per-scenario verdicts are \`pass\`, \`fail\`, \`blocked\`, or \`not-run\`. A scenario without an artifact cannot be \`pass\`.
85
+
86
+ ## Output discipline
87
+
88
+ End every response with exactly one \`<qa>\` block in this structure:
89
+
90
+ <qa>
91
+ <summary>
92
+ [Two or three sentences: the verdict and the one or two facts that justify it. No process narration.]
93
+ </summary>
94
+ <target>
95
+ [What was tested: repo + SHA, URL, or binary + version; environment; install/start commands.]
96
+ </target>
97
+ <scenarios>
98
+ <scenario id="S1" verdict="pass|fail|blocked|not-run">
99
+ <action>Exact command or UI steps.</action>
100
+ <expected>What should happen, written before running.</expected>
101
+ <observed>What actually happened.</observed>
102
+ <artifact>The decisive excerpt inline (exit code, status line, error text, or what the screenshot shows), plus its /tmp/qa/<run-id>/... path.</artifact>
103
+ </scenario>
104
+ </scenarios>
105
+ <findings>
106
+ <finding severity="blocker|concern|nit" scenario="S1">
107
+ <issue>One-sentence statement of the defect.</issue>
108
+ <repro>Minimal steps to reproduce.</repro>
109
+ <evidence>Expected vs actual, with the artifact path or excerpt.</evidence>
110
+ </finding>
111
+ </findings>
112
+ <coverage_gaps>
113
+ [What was NOT tested and why. Empty only when everything requested was covered.]
114
+ </coverage_gaps>
115
+ <verdict>pass | fail | inconclusive</verdict>
116
+ </qa>
117
+
118
+ You have one shot. The parent receives your final message verbatim — make it complete and self-contained.`
119
+
120
+ export const qaPayloadSchema = z
121
+ .object({
122
+ requestId: z.string().optional(),
123
+ prompt: z.string().optional(),
124
+ description: z.string().optional(),
125
+ })
126
+ .passthrough()
127
+
128
+ export type QaPayload = z.infer<typeof qaPayloadSchema>
129
+
130
+ export function createQaSubagent(options?: { resolveTokenForRepo: ResolveGithubTokenForRepo }): Subagent<QaPayload> {
131
+ const loadSkillTool = createLoadSkillTool({
132
+ skills: QA_SKILLS,
133
+ description: `Load a QA playbook by name. Each skill explains how to set up, exercise, and capture evidence for one kind of surface. Call this BEFORE planning scenarios.
134
+
135
+ Available skills:
136
+ ${QA_SKILLS.map((s) => `- \`${s.name}\` — ${s.description}`).join('\n')}
137
+
138
+ If none fit, load \`qa-general\`.`,
139
+ })
140
+
141
+ return {
142
+ systemPrompt: QA_SYSTEM_PROMPT,
143
+ profile: 'deep',
144
+ tools: [readTool, grepTool, findTool, lsTool, bashTool, writeTool, webSearchTool, webFetchTool],
145
+ customTools: [
146
+ loadSkillTool,
147
+ ...(options === undefined ? [] : [createReviewerCheckoutTool(options.resolveTokenForRepo)]),
148
+ ],
149
+ payloadSchema: qaPayloadSchema,
150
+ visibility: 'public',
151
+ rosterDescription:
152
+ 'hands-on QA tester: builds and runs a PR, repo, web app, CLI, or API through its real surface and returns an evidence-backed pass/fail/inconclusive verdict; never edits the product or posts — you act on its findings',
153
+ timeoutMs: QA_SPAWN_TIMEOUT_MS,
154
+ inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
155
+ toolResultBudget: {
156
+ maxTotalBytes: 1_000_000,
157
+ toolNames: ['read', 'grep', 'find', 'ls', 'bash', 'write', 'web_search', 'web_fetch', 'load_skill'],
158
+ },
159
+ }
160
+ }
@@ -0,0 +1,50 @@
1
+ import type { LoadableSkill } from '@/plugin'
2
+
3
+ export const CLI_QA_SKILL: LoadableSkill = {
4
+ name: 'qa-cli',
5
+ description:
6
+ 'QA a command-line tool or terminal UI: run the real binary with representative, edge, and invalid arguments, capture stdout/stderr and exit codes, and drive interactive prompts or TUIs through tmux with captured panes.',
7
+ content: `# qa-cli
8
+
9
+ You are QAing a command-line tool or terminal UI. Apply this on top of the QA loop and the \`<qa>\` output contract.
10
+
11
+ ## Run the real binary
12
+
13
+ - Build it from the project's documented command, then invoke the built artifact (or the documented \`bun run\`/\`npx\`-style entry) exactly as a user would.
14
+ - Record the version (\`--version\`) in \`<target>\`.
15
+ - Run each scenario from a clean scratch working directory so leftover state cannot mask a bug. Use a scratch \`HOME\` (\`HOME=/tmp/qa/<run-id>/home\`) when the tool writes config there.
16
+
17
+ ## Capture
18
+
19
+ For every invocation keep the exact command, stdout, stderr, and exit code. Save long output to \`/tmp/qa/<run-id>/<scenario>.log\` and quote the decisive lines in \`<observed>\`.
20
+
21
+ ## What to cover
22
+
23
+ 1. **Happy path** of each command the request names, with the resulting files or state checked (\`ls\`, \`cat\`, a second command that reads it back).
24
+ 2. **Help and discovery**: \`--help\` lists the new or changed flag; the description matches behavior.
25
+ 3. **Invalid input**: unknown flag, missing required argument, bad value. Expect a non-zero exit and a message that names the problem. A stack trace or exit 0 on failure is a finding.
26
+ 4. **Edge input**: empty file, very long argument, paths with spaces, non-ASCII (Korean or Japanese) text.
27
+ 5. **Idempotency and re-runs** where it matters: running the same command twice does not corrupt state.
28
+ 6. **Non-TTY behavior**: output piped to a file has no broken escape codes when the tool claims to support that.
29
+
30
+ ## Interactive prompts and TUIs
31
+
32
+ Drive them in a real pseudo-terminal with tmux, scripted so the whole session (start, every step, capture, kill) runs inside ONE \`bash\` call; a tmux server started in one call does not survive to the next:
33
+
34
+ - \`tmux new-session -d -s qa -x 120 -y 40 '<command>'\`
35
+ - \`tmux send-keys -t qa 'input' Enter\` (and \`Down\`, \`C-c\`, etc.)
36
+ - \`tmux capture-pane -t qa -p > /tmp/qa/<run-id>/<scenario>-<step>.txt\` after each step
37
+ - Wait for a prompt by polling \`capture-pane\` for the expected text with a bounded loop, never a fixed sleep.
38
+ - \`tmux kill-session -t qa\` when done.
39
+
40
+ Check that lines fit the terminal width, borders align, and wide (CJK) characters do not shift columns. If tmux is not installed, fall back to non-interactive flags when the tool has them and record the TUI as a coverage gap.
41
+
42
+ ## Severity
43
+
44
+ - **blocker** — a named command fails or produces wrong output, data is destroyed, a crash on common input.
45
+ - **concern** — bad error message or exit code on invalid input, a broken edge case, help text that lies.
46
+ - **nit** — formatting.
47
+
48
+ Return everything inside the \`<qa>\` block.
49
+ `,
50
+ }
@@ -0,0 +1,30 @@
1
+ import type { LoadableSkill } from '@/plugin'
2
+
3
+ export const GENERAL_QA_SKILL: LoadableSkill = {
4
+ name: 'qa-general',
5
+ description:
6
+ 'Fallback for QA targets that fit no specific surface: a library or SDK, a data pipeline, a config or migration, a generated artifact, or a mixed system. Pick the channel that faithfully exercises the behavior and capture its output as evidence.',
7
+ content: `# general
8
+
9
+ You are QAing something that is not clearly a PR, a web app, a CLI, or an API, or that mixes them. Apply this on top of the QA loop and the \`<qa>\` output contract.
10
+
11
+ ## Pick the channel that exercises the real behavior
12
+
13
+ - **Library or SDK** — write a small script in \`/tmp/qa/<run-id>/\` that imports the public API exactly as a consumer would and exercises the behavior; keep its transcript.
14
+ - **Data pipeline, migration, or generator** — run it on a representative input in scratch space and inspect the produced artifact itself: diff it, dump it, count rows, validate it against its schema.
15
+ - **Config change** — start the system with the config and observe the behavior it is supposed to change, then with the previous value to show the difference.
16
+ - **Document or report output** (PDF, HTML, spreadsheet) — render it and inspect the result; extracted text alone does not prove layout.
17
+
18
+ If the target spans surfaces, load the matching surface skill as well.
19
+
20
+ ## What to cover
21
+
22
+ The happy path the request names, the riskiest edge (empty, boundary, malformed input), and one adjacent behavior that could regress. Every stated success criterion gets its own scenario with an artifact.
23
+
24
+ ## When you cannot exercise it
25
+
26
+ If the behavior needs something you do not have (credentials, hardware, a paid service, a specific OS), do not substitute reading code for running it. Mark those scenarios \`blocked\`, say exactly what is missing, and return \`inconclusive\` unless something else failed.
27
+
28
+ Return everything inside the \`<qa>\` block.
29
+ `,
30
+ }