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
@@ -0,0 +1,198 @@
1
+ import type { StreamFn } from '@earendil-works/pi-agent-core'
2
+
3
+ import type { LiveSubagentRegistry } from './live-subagents'
4
+
5
+ const TTL_MS = 5 * 60_000
6
+ const INTERVAL_MS = TTL_MS * 0.9
7
+ export const MAX_SUBAGENT_CACHE_PINGS = 6
8
+
9
+ type Request = {
10
+ readonly model: Parameters<StreamFn>[0]
11
+ readonly context: Parameters<StreamFn>[1]
12
+ readonly options: NonNullable<Parameters<StreamFn>[2]>
13
+ readonly payload: Record<string, unknown>
14
+ }
15
+
16
+ function isRecord(value: unknown): value is Record<string, unknown> {
17
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
18
+ }
19
+
20
+ // Inspect the actual cache markers, including hook overrides and env-derived
21
+ // retention. Never turn a no-cache or one-hour request into a five-minute one.
22
+ function hasShortCache(value: unknown): boolean {
23
+ if (Array.isArray(value)) return value.some(hasShortCache)
24
+ if (!isRecord(value)) return false
25
+ if (isRecord(value.cache_control) && value.cache_control.type === 'ephemeral') {
26
+ return value.cache_control.ttl === undefined || value.cache_control.ttl === '5m'
27
+ }
28
+ return Object.values(value).some(hasShortCache)
29
+ }
30
+
31
+ export class SubagentCacheKeepalive {
32
+ private request: Request | undefined
33
+ private refreshedAt = 0
34
+ private idle = false
35
+ private closed = false
36
+ private pings = 0
37
+ private cancelTimer: (() => void) | undefined
38
+ private controller: AbortController | undefined
39
+ private readonly unsubscribe: () => void
40
+
41
+ constructor(
42
+ private readonly sessionId: string,
43
+ private readonly registry: LiveSubagentRegistry,
44
+ private readonly stream: StreamFn,
45
+ private readonly clock = {
46
+ now: () => Date.now(),
47
+ schedule: (callback: () => void, delay: number): (() => void) => {
48
+ const timer = setTimeout(callback, delay)
49
+ timer.unref()
50
+ return () => clearTimeout(timer)
51
+ },
52
+ },
53
+ private readonly log: (line: string) => void = console.debug,
54
+ ) {
55
+ this.unsubscribe = registry.subscribe((parent) => {
56
+ if (parent === sessionId) this.reconcile()
57
+ })
58
+ }
59
+
60
+ capture(model: Request['model'], context: Request['context'], options: Request['options'], payload: unknown): void {
61
+ this.request = undefined
62
+ if (
63
+ this.closed ||
64
+ model.api !== 'anthropic-messages' ||
65
+ options.cacheRetention === 'none' ||
66
+ !isRecord(payload) ||
67
+ !hasShortCache(payload)
68
+ ) {
69
+ return
70
+ }
71
+ // Snapshot after all payload hooks and prompt-cache-key handling. Rebuilding
72
+ // from session state can reorder tools or include new messages/system text.
73
+ this.request = {
74
+ model: structuredClone(model),
75
+ context: structuredClone(context),
76
+ options: { ...options },
77
+ payload: structuredClone(payload),
78
+ }
79
+ this.refreshedAt = this.clock.now()
80
+ }
81
+
82
+ invalidate(): void {
83
+ this.request = undefined
84
+ this.stop()
85
+ }
86
+
87
+ startTurn(): void {
88
+ this.idle = false
89
+ this.pings = 0
90
+ this.stop()
91
+ }
92
+
93
+ settle(): void {
94
+ if (this.closed) return
95
+ this.idle = true
96
+ this.reconcile()
97
+ }
98
+
99
+ close(): void {
100
+ this.closed = true
101
+ this.request = undefined
102
+ this.stop()
103
+ this.unsubscribe()
104
+ }
105
+
106
+ private running(): boolean {
107
+ return this.registry
108
+ .list({ parentSessionId: this.sessionId })
109
+ .some((child) => child.background === true && child.status === 'running')
110
+ }
111
+
112
+ private stop(): void {
113
+ this.cancelTimer?.()
114
+ this.cancelTimer = undefined
115
+ this.controller?.abort()
116
+ this.controller = undefined
117
+ }
118
+
119
+ private reconcile(): void {
120
+ if (this.closed || !this.idle || !this.running()) {
121
+ this.stop()
122
+ return
123
+ }
124
+ if (!this.request || this.pings >= MAX_SUBAGENT_CACHE_PINGS || this.cancelTimer || this.controller) return
125
+ // A late callback or a long real turn must not buy a cold cache write.
126
+ const age = this.clock.now() - this.refreshedAt
127
+ if (age > INTERVAL_MS + (TTL_MS - INTERVAL_MS) / 2) return
128
+ this.cancelTimer = this.clock.schedule(
129
+ () => {
130
+ this.cancelTimer = undefined
131
+ void this.ping()
132
+ },
133
+ Math.max(0, INTERVAL_MS - age),
134
+ )
135
+ }
136
+
137
+ private async ping(): Promise<void> {
138
+ const request = this.request
139
+ if (
140
+ !request ||
141
+ !this.idle ||
142
+ this.closed ||
143
+ !this.running() ||
144
+ this.clock.now() - this.refreshedAt > INTERVAL_MS + (TTL_MS - INTERVAL_MS) / 2
145
+ ) {
146
+ return
147
+ }
148
+ const controller = new AbortController()
149
+ this.controller = controller
150
+ this.pings += 1
151
+ const startedAt = this.clock.now()
152
+ // Legacy thinking requires max_tokens > budget_tokens. Preserve that budget:
153
+ // changing thinking settings invalidates the very cache we want to refresh.
154
+ const thinking = request.payload.thinking
155
+ const maxTokens =
156
+ isRecord(thinking) && thinking.type === 'enabled' && typeof thinking.budget_tokens === 'number'
157
+ ? thinking.budget_tokens + 1
158
+ : 1
159
+ let prefilled = false
160
+ this.log(`[agent] subagent cache keepalive ${this.pings}/${MAX_SUBAGENT_CACHE_PINGS}`)
161
+ try {
162
+ const events = await this.stream(request.model, request.context, {
163
+ ...request.options,
164
+ signal: controller.signal,
165
+ maxTokens,
166
+ maxRetries: 0,
167
+ timeoutMs: 15_000,
168
+ onPayload: () => ({ ...structuredClone(request.payload), max_tokens: maxTokens }),
169
+ onResponse: undefined,
170
+ // message_start follows prefill, unlike the SDK's synthetic start event.
171
+ // Stop here even for legacy thinking, without generating its full budget.
172
+ onProviderStreamEvent: (event) => {
173
+ if (isRecord(event) && event.type === 'message_start') {
174
+ prefilled = true
175
+ controller.abort()
176
+ }
177
+ },
178
+ })
179
+ const result = await events.result()
180
+ if (result.stopReason === 'error') {
181
+ this.log(`[agent] subagent cache keepalive failed: ${result.errorMessage ?? 'provider error'}`)
182
+ }
183
+ } catch (error) {
184
+ this.log(`[agent] subagent cache keepalive failed: ${error instanceof Error ? error.message : String(error)}`)
185
+ } finally {
186
+ // A new turn/completion/close may already have cancelled this ping.
187
+ if (this.controller === controller) {
188
+ this.controller = undefined
189
+ if (prefilled) {
190
+ this.refreshedAt = startedAt
191
+ this.reconcile()
192
+ } else if (this.request === request) {
193
+ this.request = undefined
194
+ }
195
+ }
196
+ }
197
+ }
198
+ }
@@ -0,0 +1,6 @@
1
+ import { SessionManager } from '@earendil-works/pi-coding-agent'
2
+
3
+ /** Plugin-owned privacy choice; model payloads cannot enable or disable persistence. */
4
+ export function createSubagentSessionManager(cwd: string, sessionDir: string, ephemeral = false): SessionManager {
5
+ return ephemeral ? SessionManager.inMemory(cwd) : SessionManager.create(cwd, sessionDir)
6
+ }
@@ -1,7 +1,8 @@
1
1
  import type { ToolDefinition } from '@earendil-works/pi-coding-agent'
2
2
  import type { z } from 'zod'
3
3
 
4
- import { getConfig, resolveModel } from '@/config'
4
+ import { getConfig, resolveModel, type ThinkingLevel } from '@/config'
5
+ import { effectiveModels } from '@/config/model-overrides'
5
6
  import type { PermissionService } from '@/permissions'
6
7
  import type { HookBus } from '@/plugin'
7
8
  import type { Stream, Unsubscribe } from '@/stream'
@@ -64,6 +65,11 @@ export type SubagentShared<P = unknown> = {
64
65
  // session construction. Unknown profile names fall back to `default` with
65
66
  // a warning. See `Subagent` in `@/plugin/types` for the full contract.
66
67
  profile?: string
68
+ // Thinking level for this subagent's session, overriding the profile's own
69
+ // level. Applies only when `profile` is configured: when it falls back to
70
+ // `default`, the session keeps `default`'s level, so e.g. `deep` + `low` means
71
+ // "the deep model at low effort if one exists, else the plain default".
72
+ thinkingLevel?: ThinkingLevel
67
73
  payloadSchema?: z.ZodType<P>
68
74
  handler?: (ctx: SubagentContext<P>, runSession: RunSession) => Promise<void>
69
75
  toolResultBudget?: ToolResultBudget
@@ -222,6 +228,7 @@ export const defaultCreateSessionForSubagent: CreateSessionForSubagent = (subage
222
228
  ...(resolveSubagentProfile(subagent, options) !== undefined
223
229
  ? { profile: resolveSubagentProfile(subagent, options) }
224
230
  : {}),
231
+ ...(subagent.thinkingLevel !== undefined ? { thinkingLevel: subagent.thinkingLevel } : {}),
225
232
  ...(subagent.toolResultBudget !== undefined ? { toolResultBudget: subagent.toolResultBudget } : {}),
226
233
  ...(subagent.bashPolicy !== undefined ? { bashPolicy: subagent.bashPolicy } : {}),
227
234
  })
@@ -309,7 +316,10 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
309
316
  const { session, dispose, hooks, sessionId, agentDir, origin, getTranscriptPath, backgroundDrain } =
310
317
  normalizeSubagentSession(await createSessionForSubagent(subagent, sessionOptions))
311
318
  let aborted = false
312
- let activeModelRef = resolveFallbackChain(getConfig().models, resolveSubagentProfile(subagent, sessionOptions))[0]!
319
+ let activeModelRef = resolveFallbackChain(
320
+ effectiveModels(getConfig(), sessionOptions.spawnedByOrigin),
321
+ resolveSubagentProfile(subagent, sessionOptions),
322
+ )[0]!
313
323
  // Latency tolerance is decided ONCE here, from the REQUESTED profile — not the
314
324
  // one resolveProfile() landed on. A `deep` subagent whose operator never
315
325
  // configured `models.deep` still runs on a background path nobody is watching
@@ -380,7 +390,10 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
380
390
  allowEscalation: false,
381
391
  })
382
392
  const result = await promptPersistentTurnWithFallback({
383
- refs: resolveFallbackChain(getConfig().models, resolveSubagentProfile(subagent, sessionOptions)),
393
+ refs: resolveFallbackChain(
394
+ effectiveModels(getConfig(), sessionOptions.spawnedByOrigin),
395
+ resolveSubagentProfile(subagent, sessionOptions),
396
+ ),
384
397
  currentModelRef: activeModelRef,
385
398
  profile: resolveSubagentProfile(subagent, sessionOptions),
386
399
  retryPolicy,
@@ -681,7 +694,7 @@ function raceSubagentCompletion(
681
694
  // The tags a subagent can use to wrap its structured result: the reviewer's
682
695
  // `<review>`, the researcher's `<report>`. Fixed literals — never user input —
683
696
  // so the per-tag patterns below are injection-safe.
684
- type FinalBlockTag = 'review' | 'report'
697
+ type FinalBlockTag = 'review' | 'report' | 'qa'
685
698
 
686
699
  // A complete <TAG>...</TAG> block. The block IS the result: same-message
687
700
  // preamble/trailing chatter or a later summary turn must not become the captured
@@ -692,6 +705,7 @@ type FinalBlockTag = 'review' | 'report'
692
705
  const FINAL_BLOCK_RE: Readonly<Record<FinalBlockTag, RegExp>> = {
693
706
  review: /<review>[\s\S]*?<\/review>/g,
694
707
  report: /<report>[\s\S]*?<\/report>/g,
708
+ qa: /<qa>[\s\S]*?<\/qa>/g,
695
709
  }
696
710
 
697
711
  function lastTaggedBlock(text: string, tag: FinalBlockTag): string | null {
@@ -718,7 +732,11 @@ function lastTaggedBlock(text: string, tag: FinalBlockTag): string | null {
718
732
  // only catches children that declare none.
719
733
  const DRAIN_MAX_CHILD_WAIT_MS = 600_000
720
734
 
721
- const REQUIRED_FINAL_BLOCK: Readonly<Record<string, FinalBlockTag>> = { researcher: 'report', reviewer: 'review' }
735
+ const REQUIRED_FINAL_BLOCK: Readonly<Record<string, FinalBlockTag>> = {
736
+ researcher: 'report',
737
+ reviewer: 'review',
738
+ qa: 'qa',
739
+ }
722
740
 
723
741
  // Bounded re-prompt budget for the required-block guard, mirroring the channel
724
742
  // empty-response guard's MAX_EMPTY_TURN_RETRIES. A subagent that owes a result
@@ -732,9 +750,11 @@ const MAX_REQUIRED_BLOCK_RETRIES = 2
732
750
  // The tail is tag-specific: each block has different mandatory child fields.
733
751
  function renderRequiredBlockRetryNudge(tag: FinalBlockTag): string {
734
752
  const tail =
735
- tag === 'report'
736
- ? 'in particular do NOT call write_report. Do NOT continue researching or spawn more subagents.\n\nIf the report file was not successfully written, still emit the block: set <report_file>none</report_file>, <confidence>low</confidence> (explain the report artifact was not completed), and note in <open_questions> that the run should be retried.'
737
- : `Do NOT re-run gh, diff reads, or spawn more subagents.\n\nEmit the block from the analysis you have already done: include your <summary>, whatever <finding> items you can support with evidence, and a <verdict> (approve | request-changes | comment). Only use a real verdict if you actually reached one. If you could NOT analyze enough to decide, do NOT invent a verdict — set <verdict>${INCOMPLETE_REVIEW_VERDICT}</verdict> exactly (this signals an incomplete review; the parent will not treat it as approve/request-changes/comment, even on a re-review).`
753
+ tag === 'qa'
754
+ ? `Do NOT run more commands or start more processes.\n\nEmit the block from the scenarios you have already executed: <summary>, <target>, every <scenario> with the verdict you actually observed (mark unexecuted ones not-run), <findings>, <coverage_gaps>, and a <verdict>. If required scenarios never ran, the verdict is inconclusive, never pass.`
755
+ : tag === 'report'
756
+ ? 'in particular do NOT call write_report. Do NOT continue researching or spawn more subagents.\n\nIf the report file was not successfully written, still emit the block: set <report_file>none</report_file>, <confidence>low</confidence> (explain the report artifact was not completed), and note in <open_questions> that the run should be retried.'
757
+ : `Do NOT re-run gh, diff reads, or spawn more subagents.\n\nEmit the block from the analysis you have already done: include your <summary>, whatever <finding> items you can support with evidence, and a <verdict> (approve | request-changes | comment). Only use a real verdict if you actually reached one. If you could NOT analyze enough to decide, do NOT invent a verdict — set <verdict>${INCOMPLETE_REVIEW_VERDICT}</verdict> exactly (this signals an incomplete review; the parent will not treat it as approve/request-changes/comment, even on a re-review).`
738
758
  return `---
739
759
  **[SYSTEM MESSAGE — not from a human]**
740
760
 
@@ -800,6 +820,24 @@ ${headline}. The ${name} subagent could not complete a review in this run: ${cau
800
820
  </findings>
801
821
  <verdict>${INCOMPLETE_REVIEW_VERDICT}</verdict>
802
822
  </review>`
823
+ }
824
+ if (tag === 'qa') {
825
+ return `<qa>
826
+ <summary>
827
+ The ${name} subagent could not complete a QA run: ${cause}. No scenario results are reliable — do not treat any earlier text as a pass. Rerun QA${providerFailed ? ' once the provider recovers' : ''}.
828
+ </summary>
829
+ <target>
830
+ unknown
831
+ </target>
832
+ <scenarios>
833
+ </scenarios>
834
+ <findings>
835
+ </findings>
836
+ <coverage_gaps>
837
+ The entire QA request remains untested.
838
+ </coverage_gaps>
839
+ <verdict>inconclusive</verdict>
840
+ </qa>`
803
841
  }
804
842
  return `<${tag}>\nThe ${name} subagent could not produce the required <${tag}> block (${cause}) and could not recover; rerun it or inspect the transcript.\n</${tag}>`
805
843
  }
@@ -77,7 +77,7 @@ A green build, lint, or type check proves the artifact is well-formed, not that
77
77
  - For multi-step or long-running work, call \`todo_write\` when you start and mark items complete as you finish; incomplete items let the runtime resume after interruptions. Use \`todo_clear\` only to abandon remaining work. Single-step requests need no list.
78
78
  - For multi-step work, give one short progress update, not narration. Do not narrate routine low-risk tool calls; explain only for multi-step context, risky or irreversible actions, external sends, or when asked. Do not over-explain.
79
79
  - Match the user's register. If SOUL.md specifies a voice, use it; otherwise be concise and direct.
80
- - Produce a polished file only when someone asks for a standalone deliverable to download, print, forward, attach, export, or keep. The bare word "report" is not enough: routine updates, stats, and status reports stay inline. A summary then points to the file; it never replaces it. For Markdown-to-PDF, follow the \`typeclaw-render-pdf\` skill.
80
+ - Produce a polished file only when someone asks for a standalone deliverable to download, print, forward, attach, export, or keep. The bare word "report" is not enough: routine updates, stats, and status reports stay inline. A summary then points to the file; it never replaces it. For PDFs, follow the \`typeclaw-render-pdf\` skill.
81
81
  - Foreground \`bash\` blocks until exit. Run minutes-long or input-waiting programs (dev servers, REPLs, watchers, \`docker compose up\`, installers) detached in \`tmux\`; \`typeclaw-troubleshooting\` has the commands.
82
82
 
83
83
  ## Version control
@@ -177,8 +177,13 @@ export async function enforceAndPinToolFiles(
177
177
  let copiedBytes = 0
178
178
  for (let i = 0; i < verified.length; i++) {
179
179
  const input = verified[i] as VerifiedInput
180
- const pinned = path.join(dir, String(i))
180
+ const slot = path.join(dir, String(i))
181
+ // Files keep their original basename under a per-operand slot: tools that
182
+ // derive a name or type from the path (channel uploads, mime sniffing by
183
+ // extension) would otherwise see the bare index, e.g. a Discord file named `0`.
184
+ const pinned = input.kind === 'file' ? path.join(slot, path.basename(input.original)) : slot
181
185
  if (input.kind === 'file') {
186
+ await mkdir(slot, { mode: 0o700 })
182
187
  const source = await openInput(input.resolved, input.original)
183
188
  try {
184
189
  const opened = await source.stat()
@@ -10,6 +10,7 @@ import {
10
10
  } from '@/channels/router'
11
11
  import { ADAPTER_IDS, type AdapterId } from '@/channels/schema'
12
12
  import type { EditMessageResult } from '@/channels/types'
13
+ import type { ChannelOutboundOrigin } from '@/plugin'
13
14
 
14
15
  import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
15
16
  import { renderOutboundEcho, TOOL_RESULT_PREFIX } from './channel-reply'
@@ -17,10 +18,15 @@ import { fenceToolResult } from './runtime-notice'
17
18
 
18
19
  export type CreateChannelEditToolOptions = {
19
20
  router: ChannelRouter
21
+ getOutboundOrigin?: () => ChannelOutboundOrigin | undefined
20
22
  logger?: ChannelToolLogger
21
23
  }
22
24
 
23
- export function createChannelEditTool({ router, logger = consoleChannelLogger }: CreateChannelEditToolOptions) {
25
+ export function createChannelEditTool({
26
+ router,
27
+ getOutboundOrigin,
28
+ logger = consoleChannelLogger,
29
+ }: CreateChannelEditToolOptions) {
24
30
  return defineTool({
25
31
  name: 'channel_edit',
26
32
  label: 'Channel Edit',
@@ -96,20 +102,24 @@ export function createChannelEditTool({ router, logger = consoleChannelLogger }:
96
102
  const text = stripThinkBlocks(params.text)
97
103
  if (text === '') return deny('the replacement text is empty after removing reasoning blocks')
98
104
 
99
- const result = await router.editMessage({
100
- adapter,
101
- workspace: params.workspace,
102
- chat: params.chat,
103
- ...(params.thread !== undefined ? { thread: params.thread } : {}),
104
- messageId: params.message_id,
105
- text,
106
- })
105
+ const outboundOrigin = getOutboundOrigin?.()
106
+ const result = await router.editMessage(
107
+ {
108
+ adapter,
109
+ workspace: params.workspace,
110
+ chat: params.chat,
111
+ ...(params.thread !== undefined ? { thread: params.thread } : {}),
112
+ messageId: params.message_id,
113
+ text,
114
+ },
115
+ outboundOrigin ? { origin: outboundOrigin } : undefined,
116
+ )
107
117
 
108
118
  if (!result.ok) {
109
119
  return deny(`${adapter}:${params.workspace}/${params.chat}: ${result.error}`, result.code)
110
120
  }
111
121
 
112
- const echo = renderOutboundEcho(text, undefined)
122
+ const echo = renderOutboundEcho(result.deliveredText ?? text, undefined)
113
123
  const receipt = `edited ${adapter}:${params.workspace}/${params.chat} message ${params.message_id}: ${echo}`
114
124
  return {
115
125
  content: [{ type: 'text' as const, text: fenceToolResult(receipt) }],
@@ -61,14 +61,17 @@ export function createChannelFetchAttachmentTool({
61
61
  'messages with attachments show `[<Platform> attachment #N: <kind> <metadata>]` in the text. Pass `N` as ' +
62
62
  '`attachment_id`; do not invent ids that are not present in the message. The router resolves the private ' +
63
63
  'platform ref itself. Attachments on the CURRENT inbound message resolve directly; for one from an EARLIER ' +
64
- 'message, call channel_history first (it makes those attachments resolvable by the same id). On success ' +
65
- 'returns the absolute path of the saved file plus its detected mimetype and size.',
64
+ 'message, call channel_history first. On Slack, pass the exact file_id when the request names one or ' +
65
+ 'several messages reuse #1. Returns the selected file identity, saved path, mimetype and size.',
66
66
  parameters: Type.Object({
67
67
  attachment_id: Type.Integer({
68
68
  description:
69
69
  'The number N from the inbound `[<Platform> attachment #N: ...]` placeholder. Must be present in this turn.',
70
70
  minimum: 1,
71
71
  }),
72
+ file_id: Type.Optional(
73
+ Type.String({ pattern: '^F[A-Z0-9]+$', description: 'Exact Slack file ID from the request or history.' }),
74
+ ),
72
75
  filename: Type.Optional(
73
76
  Type.String({
74
77
  description:
@@ -79,12 +82,15 @@ export function createChannelFetchAttachmentTool({
79
82
  }),
80
83
 
81
84
  async execute(_toolCallId, params) {
85
+ if (params.file_id !== undefined && adapter !== 'slack' && adapter !== 'slack-bot')
86
+ return errorResult('file_id is only supported for Slack attachments')
82
87
  const found = router.lookupInboundAttachment({
83
88
  adapter,
84
89
  workspace: origin.workspace,
85
90
  chat: origin.chat,
86
91
  thread: origin.thread,
87
92
  id: params.attachment_id,
93
+ ...(params.file_id !== undefined ? { ref: params.file_id } : {}),
88
94
  })
89
95
  if (found === null) {
90
96
  const validIds = router.listInboundAttachmentIds({
@@ -107,6 +113,7 @@ export function createChannelFetchAttachmentTool({
107
113
  )
108
114
  }
109
115
  const ref = found.ref
116
+ const identityPart = adapter === 'slack' || adapter === 'slack-bot' ? ` file_id=${ref}` : ''
110
117
  const filename = params.filename ?? found.filename
111
118
  const result = await router.fetchAttachment(adapter, {
112
119
  ref,
@@ -115,7 +122,7 @@ export function createChannelFetchAttachmentTool({
115
122
  })
116
123
  if (!result.ok) {
117
124
  logger.warn(formatChannelToolFailure('channel_fetch_attachment', `${adapter}: ${result.error}`))
118
- const text = `channel_fetch_attachment error: ${result.error}`
125
+ const text = `channel_fetch_attachment error:${identityPart} ${result.error}`
119
126
  const details: FetchAttachmentDetails = { ok: false, error: result.error }
120
127
  return { content: [{ type: 'text' as const, text }], details }
121
128
  }
@@ -135,13 +142,13 @@ export function createChannelFetchAttachmentTool({
135
142
  } catch (err) {
136
143
  const message = err instanceof Error ? err.message : String(err)
137
144
  logger.warn(formatChannelToolFailure('channel_fetch_attachment', `${adapter}: write failed: ${message}`))
138
- const text = `channel_fetch_attachment error: write failed: ${message}`
145
+ const text = `channel_fetch_attachment error:${identityPart} write failed: ${message}`
139
146
  const details: FetchAttachmentDetails = { ok: false, error: `write failed: ${message}` }
140
147
  return { content: [{ type: 'text' as const, text }], details }
141
148
  }
142
149
 
143
150
  const mimetypePart = result.mimetype !== undefined ? ` (${result.mimetype})` : ''
144
- const text = `saved ${result.size} bytes to ${targetPath}${mimetypePart}`
151
+ const text = `saved ${result.size} bytes to ${targetPath}${mimetypePart}${identityPart}`
145
152
  const details: FetchAttachmentDetails = {
146
153
  ok: true,
147
154
  path: targetPath,
@@ -0,0 +1,72 @@
1
+ import { Type } from '@earendil-works/pi-ai'
2
+ import { defineTool } from '@earendil-works/pi-coding-agent'
3
+
4
+ import type { ChannelHandoffResult, ChannelRouter } from '@/channels/router'
5
+ import { ADAPTER_IDS } from '@/channels/schema'
6
+
7
+ export type CreateChannelHandoffToolOptions = {
8
+ router: Pick<ChannelRouter, 'handoff'>
9
+ sessionId: string
10
+ }
11
+
12
+ // `channel_handoff` hands work to the session that owns another conversation
13
+ // instead of posting there with channel_send. A channel_send from here is
14
+ // written from THIS session's view of that conversation, which goes stale the
15
+ // moment people keep talking there; the owning session sees its latest
16
+ // messages and decides what (if anything) to post.
17
+ export function createChannelHandoffTool({ router, sessionId }: CreateChannelHandoffToolOptions) {
18
+ return defineTool({
19
+ name: 'channel_handoff',
20
+ label: 'Channel Handoff',
21
+ description:
22
+ 'Hand a result or request to the session that owns ANOTHER conversation, on any adapter. First use ' +
23
+ '`channel_session_search` to find its target by conversation name, topic, or participant. When the work ' +
24
+ 'belongs there, hand it off instead of reading or posting there directly from this session. ' +
25
+ 'The session that owns that conversation receives your `text` as a private note from ' +
26
+ 'the user, reads its own latest messages, and then decides what to post, so newer requests there are not ' +
27
+ 'answered with a stale result. Your `text` is not posted verbatim: write what was done and what is left, ' +
28
+ 'not a finished channel message. It acts on behalf of the user who asked you this turn, with their permissions ' +
29
+ 'in the target conversation, without gaining authority over their source role. No recent participation is required. ' +
30
+ 'After a successful handoff, briefly tell the user here that it was passed on. ' +
31
+ 'Not available in a turn that was itself started by a handoff (reply with `channel_reply` there).',
32
+ parameters: Type.Object({
33
+ adapter: Type.Union(
34
+ ADAPTER_IDS.map((a) => Type.Literal(a)),
35
+ { description: 'Target adapter id from channel_session_search; it can differ from this session.' },
36
+ ),
37
+ workspace: Type.String({
38
+ description: 'Discord guild id or Slack team id; "@dm" for direct-message channels.',
39
+ minLength: 1,
40
+ }),
41
+ chat: Type.String({ description: 'Target channel id.', minLength: 1 }),
42
+ thread: Type.Optional(
43
+ Type.String({
44
+ description: 'Optional thread id (Discord thread channel id, Slack parent thread_ts).',
45
+ minLength: 1,
46
+ }),
47
+ ),
48
+ text: Type.String({
49
+ description:
50
+ 'What the owning session needs to know: the request, what you already did, and the result. Plain context, not a ready-to-post message.',
51
+ minLength: 1,
52
+ }),
53
+ }),
54
+
55
+ async execute(_toolCallId, params) {
56
+ const result: ChannelHandoffResult = await router.handoff({
57
+ fromSessionId: sessionId,
58
+ target: {
59
+ adapter: params.adapter,
60
+ workspace: params.workspace,
61
+ chat: params.chat,
62
+ thread: params.thread ?? null,
63
+ },
64
+ text: params.text,
65
+ })
66
+ const text = result.ok
67
+ ? `Handed off to ${result.target}. That conversation's session will answer there with its current context; do not also post it yourself.`
68
+ : `channel_handoff denied (${result.code}): ${result.error}`
69
+ return { content: [{ type: 'text' as const, text }], details: result }
70
+ },
71
+ })
72
+ }
@@ -3,7 +3,7 @@ import { defineTool } from '@earendil-works/pi-coding-agent'
3
3
 
4
4
  import type { ChannelRouter } from '@/channels/router'
5
5
  import { ADAPTER_IDS, type AdapterId } from '@/channels/schema'
6
- import type { ChannelListEntry } from '@/channels/types'
6
+ import type { ChannelKey, ChannelListEntry } from '@/channels/types'
7
7
 
8
8
  import { renderHistoryMessage, renderHistoryMessages } from './channel-history-render'
9
9
  import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
@@ -11,6 +11,7 @@ import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure
11
11
  export type CreateChannelReadToolOptions = {
12
12
  router: ChannelRouter
13
13
  logger?: ChannelToolLogger
14
+ sessionId?: string
14
15
  }
15
16
 
16
17
  const DEFAULT_LIMIT = 20
@@ -22,7 +23,11 @@ const DEFAULT_LIMIT = 20
22
23
  // modes share one tool to keep the per-turn tool-schema budget small, mirroring
23
24
  // web_fetch's strategy union; mode-specific required params are validated at
24
25
  // runtime since JSON-Schema can't express "required-if".
25
- export function createChannelReadTool({ router, logger = consoleChannelLogger }: CreateChannelReadToolOptions) {
26
+ export function createChannelReadTool({
27
+ router,
28
+ logger = consoleChannelLogger,
29
+ sessionId,
30
+ }: CreateChannelReadToolOptions) {
26
31
  return defineTool({
27
32
  name: 'channel_read',
28
33
  label: 'Channel Read',
@@ -34,7 +39,8 @@ export function createChannelReadTool({ router, logger = consoleChannelLogger }:
34
39
  '- "list": discover channels/chats in `workspace` (no `chat` needed). Use when you do not yet know a chat id.\n' +
35
40
  'For Discord guild channels, `workspace` is the guild id; for Slack team channels, `workspace` is the team id (e.g. "T0ACME"); for DMs, "@dm". ' +
36
41
  'On failure returns { ok: false, error }. Not every adapter supports every mode — an unsupported mode returns a not-supported error rather than throwing. ' +
37
- 'This is read-only; use channel_send to post.',
42
+ 'This is read-only. When work belongs to another conversation, use channel_session_search and channel_handoff ' +
43
+ 'instead of reading or posting there directly. An access error may include an authorized handoff target.',
38
44
  parameters: Type.Object({
39
45
  mode: Type.Union([Type.Literal('history'), Type.Literal('message'), Type.Literal('list')], {
40
46
  description:
@@ -79,21 +85,62 @@ export function createChannelReadTool({ router, logger = consoleChannelLogger }:
79
85
  }),
80
86
 
81
87
  async execute(_toolCallId, params) {
82
- const adapter = params.adapter as AdapterId
88
+ const adapter = params.adapter
83
89
  const limit = params.limit ?? DEFAULT_LIMIT
84
90
 
85
- if (params.mode === 'history') {
86
- return await readHistory({ router, logger, adapter, params, limit })
91
+ let result: { content: { type: 'text'; text: string }[]; details: Details }
92
+ switch (params.mode) {
93
+ case 'history':
94
+ result = await readHistory({ router, logger, adapter, params, limit })
95
+ break
96
+ case 'message':
97
+ result = await readMessage({ router, logger, adapter, params })
98
+ break
99
+ case 'list':
100
+ result = await readList({ router, logger, adapter, params, limit })
101
+ break
87
102
  }
88
- if (params.mode === 'message') {
89
- return await readMessage({ router, logger, adapter, params })
103
+ // These are platform protocol errors, not natural-language intent matching.
104
+ const error = result.details.error?.toLocaleLowerCase() ?? ''
105
+ const accessDenied = [
106
+ 'missing access',
107
+ 'missing permissions',
108
+ 'access denied',
109
+ 'access_denied',
110
+ 'permission-denied',
111
+ 'forbidden',
112
+ 'http_403',
113
+ 'missing_scope',
114
+ 'not_in_channel',
115
+ ].some((code) => error.includes(code))
116
+ if (!result.details.ok && accessDenied && sessionId !== undefined && params.chat !== undefined) {
117
+ const handoffTargets = router
118
+ .searchSessions({
119
+ fromSessionId: sessionId,
120
+ query: '',
121
+ conversation: { adapter, workspace: params.workspace, chat: params.chat, thread: params.thread ?? null },
122
+ })
123
+ .map((entry) => entry.target)
124
+ if (handoffTargets.length > 0) {
125
+ const hint = `Another adapter has an authorized live session for this conversation. Use channel_handoff with a target below instead of asking the user to repair this account's access:\n${JSON.stringify(handoffTargets)}`
126
+ return {
127
+ content: result.content.map((part) => ({ ...part, text: `${part.text}\n\n${hint}` })),
128
+ details: { ...result.details, handoffTargets },
129
+ }
130
+ }
90
131
  }
91
- return await readList({ router, logger, adapter, params, limit })
132
+ return result
92
133
  },
93
134
  })
94
135
  }
95
136
 
96
- type Details = { ok: boolean; error?: string; count?: number; nextCursor?: string }
137
+ type Details = {
138
+ ok: boolean
139
+ error?: string
140
+ count?: number
141
+ nextCursor?: string
142
+ handoffTargets?: readonly ChannelKey[]
143
+ }
97
144
 
98
145
  function fail(error: string): { content: [{ type: 'text'; text: string }]; details: Details } {
99
146
  return { content: [{ type: 'text' as const, text: `channel_read error: ${error}` }], details: { ok: false, error } }