@openparachute/agent 0.1.2 → 0.2.2

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 (608) hide show
  1. package/.parachute/module.json +124 -8
  2. package/LICENSE +2 -16
  3. package/README.md +118 -166
  4. package/package.json +35 -42
  5. package/scripts/spawn-agent.ts +371 -0
  6. package/src/_parked/interactive-spawn.test.ts +324 -0
  7. package/src/_parked/interactive-spawn.ts +701 -0
  8. package/src/agent-defs.test.ts +1504 -0
  9. package/src/agent-defs.ts +1702 -0
  10. package/src/agent-mcp-config.test.ts +115 -0
  11. package/src/agent-mcp-config.ts +115 -0
  12. package/src/agents.test.ts +360 -0
  13. package/src/agents.ts +379 -0
  14. package/src/auth.test.ts +46 -0
  15. package/src/auth.ts +140 -0
  16. package/src/backends/attached-queue.test.ts +376 -0
  17. package/src/backends/attached-queue.ts +372 -0
  18. package/src/backends/programmatic.test.ts +1715 -0
  19. package/src/backends/programmatic.ts +927 -0
  20. package/src/backends/registry.test.ts +1494 -0
  21. package/src/backends/registry.ts +1202 -0
  22. package/src/backends/stream-json.test.ts +570 -0
  23. package/src/backends/stream-json.ts +392 -0
  24. package/src/backends/types.ts +223 -0
  25. package/src/bridge.ts +417 -0
  26. package/src/channel-backend-wiring.test.ts +237 -0
  27. package/src/credentials.test.ts +274 -0
  28. package/src/credentials.ts +380 -0
  29. package/src/cron.test.ts +342 -0
  30. package/src/cron.ts +380 -0
  31. package/src/daemon-agent-def-api.test.ts +166 -0
  32. package/src/daemon-agent-defs-api.test.ts +953 -0
  33. package/src/daemon-agent-env-api.test.ts +338 -0
  34. package/src/daemon-attached-queue-store.test.ts +65 -0
  35. package/src/daemon-config-api.test.ts +962 -0
  36. package/src/daemon-jobs-api.test.ts +271 -0
  37. package/src/daemon-vault-chat.test.ts +250 -0
  38. package/src/daemon.test.ts +746 -0
  39. package/src/daemon.ts +3314 -0
  40. package/src/def-vaults.test.ts +136 -0
  41. package/src/def-vaults.ts +165 -0
  42. package/src/delivery-state.test.ts +110 -0
  43. package/src/delivery-state.ts +154 -0
  44. package/src/effective-env.test.ts +114 -0
  45. package/src/effective-env.ts +184 -0
  46. package/src/env-compat.ts +39 -0
  47. package/src/grants.test.ts +638 -0
  48. package/src/grants.ts +675 -0
  49. package/src/hub-jwt.test.ts +161 -0
  50. package/src/hub-jwt.ts +182 -0
  51. package/src/jobs.test.ts +245 -0
  52. package/src/jobs.ts +266 -0
  53. package/src/mcp-http.test.ts +265 -0
  54. package/src/mcp-http.ts +771 -0
  55. package/src/mint-token.test.ts +152 -0
  56. package/src/mint-token.ts +139 -0
  57. package/src/module-manifest.test.ts +158 -0
  58. package/src/oauth-discovery.ts +134 -0
  59. package/src/programmatic-wiring.test.ts +838 -0
  60. package/src/registry.test.ts +227 -0
  61. package/src/registry.ts +228 -0
  62. package/src/resolve-port.test.ts +64 -0
  63. package/src/routing.test.ts +184 -0
  64. package/src/routing.ts +76 -0
  65. package/src/runner.test.ts +506 -0
  66. package/src/runner.ts +255 -0
  67. package/src/sandbox/config.test.ts +150 -0
  68. package/src/sandbox/config.ts +102 -0
  69. package/src/sandbox/egress.test.ts +113 -0
  70. package/src/sandbox/egress.ts +123 -0
  71. package/src/sandbox/index.ts +180 -0
  72. package/src/sandbox/live-seatbelt.test.ts +277 -0
  73. package/src/sandbox/mounts.test.ts +154 -0
  74. package/src/sandbox/mounts.ts +133 -0
  75. package/src/sandbox/sandbox.test.ts +168 -0
  76. package/src/sandbox/types.ts +382 -0
  77. package/src/services-manifest.test.ts +106 -0
  78. package/src/services-manifest.ts +95 -0
  79. package/src/spa-serve.test.ts +116 -0
  80. package/src/spa-serve.ts +116 -0
  81. package/src/spawn-agent-cli.test.ts +172 -0
  82. package/src/spawn-agent.test.ts +1218 -0
  83. package/src/spawn-agent.ts +569 -0
  84. package/src/spawn-deps.test.ts +54 -0
  85. package/src/spawn-deps.ts +166 -0
  86. package/src/telegram/api.ts +153 -0
  87. package/src/terminal-assets.test.ts +50 -0
  88. package/src/terminal-assets.ts +79 -0
  89. package/src/terminal-ui.ts +305 -0
  90. package/src/terminal.test.ts +530 -0
  91. package/src/terminal.ts +458 -0
  92. package/src/transport.ts +270 -0
  93. package/src/transports/http-ui.test.ts +455 -0
  94. package/src/transports/http-ui.ts +201 -0
  95. package/src/transports/telegram.test.ts +174 -0
  96. package/src/transports/telegram.ts +426 -0
  97. package/src/transports/vault.test.ts +2011 -0
  98. package/src/transports/vault.ts +1790 -0
  99. package/src/ui-kit.test.ts +178 -0
  100. package/src/ui-kit.ts +402 -0
  101. package/tsconfig.json +8 -14
  102. package/web/ui/dist/assets/index-C-iWdFFV.css +1 -0
  103. package/web/ui/dist/assets/index-VFETBk0a.js +60 -0
  104. package/web/ui/dist/index.html +15 -0
  105. package/web/ui/tsconfig.json +2 -1
  106. package/.claude/scheduled_tasks.lock +0 -1
  107. package/.claude/settings.json +0 -5
  108. package/.claude/skills/add-atomic-chat-tool/SKILL.md +0 -243
  109. package/.claude/skills/add-atomic-chat-tool/atomic-chat-mcp-stdio.ts +0 -229
  110. package/.claude/skills/add-codex/SKILL.md +0 -161
  111. package/.claude/skills/add-dashboard/SKILL.md +0 -138
  112. package/.claude/skills/add-dashboard/resources/dashboard-pusher.ts +0 -495
  113. package/.claude/skills/add-emacs/SKILL.md +0 -296
  114. package/.claude/skills/add-gcal-tool/SKILL.md +0 -210
  115. package/.claude/skills/add-gchat/REMOVE.md +0 -6
  116. package/.claude/skills/add-gchat/SKILL.md +0 -92
  117. package/.claude/skills/add-gchat/VERIFY.md +0 -3
  118. package/.claude/skills/add-github/REMOVE.md +0 -6
  119. package/.claude/skills/add-github/SKILL.md +0 -148
  120. package/.claude/skills/add-github/VERIFY.md +0 -3
  121. package/.claude/skills/add-gmail-tool/SKILL.md +0 -229
  122. package/.claude/skills/add-imessage/REMOVE.md +0 -6
  123. package/.claude/skills/add-imessage/SKILL.md +0 -113
  124. package/.claude/skills/add-imessage/VERIFY.md +0 -3
  125. package/.claude/skills/add-karpathy-llm-wiki/SKILL.md +0 -110
  126. package/.claude/skills/add-karpathy-llm-wiki/llm-wiki.md +0 -75
  127. package/.claude/skills/add-linear/REMOVE.md +0 -6
  128. package/.claude/skills/add-linear/SKILL.md +0 -168
  129. package/.claude/skills/add-linear/VERIFY.md +0 -3
  130. package/.claude/skills/add-macos-statusbar/SKILL.md +0 -133
  131. package/.claude/skills/add-macos-statusbar/add/src/statusbar.swift +0 -147
  132. package/.claude/skills/add-matrix/REMOVE.md +0 -6
  133. package/.claude/skills/add-matrix/SKILL.md +0 -148
  134. package/.claude/skills/add-matrix/VERIFY.md +0 -3
  135. package/.claude/skills/add-ollama-provider/SKILL.md +0 -179
  136. package/.claude/skills/add-ollama-tool/SKILL.md +0 -193
  137. package/.claude/skills/add-opencode/SKILL.md +0 -229
  138. package/.claude/skills/add-parallel/SKILL.md +0 -290
  139. package/.claude/skills/add-resend/REMOVE.md +0 -6
  140. package/.claude/skills/add-resend/SKILL.md +0 -93
  141. package/.claude/skills/add-resend/VERIFY.md +0 -3
  142. package/.claude/skills/add-signal/REMOVE.md +0 -13
  143. package/.claude/skills/add-signal/SKILL.md +0 -318
  144. package/.claude/skills/add-signal/VERIFY.md +0 -5
  145. package/.claude/skills/add-slack/REMOVE.md +0 -6
  146. package/.claude/skills/add-slack/SKILL.md +0 -112
  147. package/.claude/skills/add-slack/VERIFY.md +0 -3
  148. package/.claude/skills/add-teams/REMOVE.md +0 -6
  149. package/.claude/skills/add-teams/SKILL.md +0 -207
  150. package/.claude/skills/add-teams/VERIFY.md +0 -3
  151. package/.claude/skills/add-vercel/SKILL.md +0 -147
  152. package/.claude/skills/add-vercel/container-skills/vercel-cli/SKILL.md +0 -103
  153. package/.claude/skills/add-webex/REMOVE.md +0 -6
  154. package/.claude/skills/add-webex/SKILL.md +0 -88
  155. package/.claude/skills/add-webex/VERIFY.md +0 -3
  156. package/.claude/skills/add-wechat/REMOVE.md +0 -49
  157. package/.claude/skills/add-wechat/SKILL.md +0 -170
  158. package/.claude/skills/add-wechat/scripts/wire-dm.ts +0 -172
  159. package/.claude/skills/add-whatsapp/SKILL.md +0 -264
  160. package/.claude/skills/add-whatsapp-cloud/REMOVE.md +0 -6
  161. package/.claude/skills/add-whatsapp-cloud/SKILL.md +0 -95
  162. package/.claude/skills/add-whatsapp-cloud/VERIFY.md +0 -3
  163. package/.claude/skills/claw/SKILL.md +0 -131
  164. package/.claude/skills/claw/scripts/claw +0 -374
  165. package/.claude/skills/convert-to-apple-container/SKILL.md +0 -212
  166. package/.claude/skills/customize/SKILL.md +0 -110
  167. package/.claude/skills/debug/SKILL.md +0 -349
  168. package/.claude/skills/get-qodo-rules/SKILL.md +0 -122
  169. package/.claude/skills/get-qodo-rules/references/output-format.md +0 -41
  170. package/.claude/skills/get-qodo-rules/references/pagination.md +0 -33
  171. package/.claude/skills/get-qodo-rules/references/repository-scope.md +0 -26
  172. package/.claude/skills/init-first-agent/SKILL.md +0 -120
  173. package/.claude/skills/init-onecli/SKILL.md +0 -270
  174. package/.claude/skills/manage-channels/SKILL.md +0 -87
  175. package/.claude/skills/manage-mounts/SKILL.md +0 -47
  176. package/.claude/skills/migrate-from-openclaw/MIGRATE_CRONS.md +0 -100
  177. package/.claude/skills/migrate-from-openclaw/SKILL.md +0 -447
  178. package/.claude/skills/migrate-from-openclaw/scripts/discover-openclaw.ts +0 -734
  179. package/.claude/skills/migrate-from-openclaw/scripts/extract-channel-credentials.ts +0 -476
  180. package/.claude/skills/migrate-nanoclaw/SKILL.md +0 -484
  181. package/.claude/skills/migrate-nanoclaw/diagnostics.md +0 -51
  182. package/.claude/skills/qodo-pr-resolver/SKILL.md +0 -326
  183. package/.claude/skills/qodo-pr-resolver/resources/providers.md +0 -329
  184. package/.claude/skills/update-nanoclaw/SKILL.md +0 -243
  185. package/.claude/skills/update-nanoclaw/diagnostics.md +0 -48
  186. package/.claude/skills/update-skills/SKILL.md +0 -130
  187. package/.claude/skills/use-native-credential-proxy/SKILL.md +0 -167
  188. package/.claude/skills/x-integration/SKILL.md +0 -417
  189. package/.claude/skills/x-integration/agent.ts +0 -243
  190. package/.claude/skills/x-integration/host.ts +0 -155
  191. package/.claude/skills/x-integration/lib/browser.ts +0 -148
  192. package/.claude/skills/x-integration/lib/config.ts +0 -62
  193. package/.claude/skills/x-integration/scripts/like.ts +0 -56
  194. package/.claude/skills/x-integration/scripts/post.ts +0 -66
  195. package/.claude/skills/x-integration/scripts/quote.ts +0 -80
  196. package/.claude/skills/x-integration/scripts/reply.ts +0 -74
  197. package/.claude/skills/x-integration/scripts/retweet.ts +0 -62
  198. package/.claude/skills/x-integration/scripts/setup.ts +0 -87
  199. package/.github/CODEOWNERS +0 -10
  200. package/.github/PULL_REQUEST_TEMPLATE.md +0 -18
  201. package/.github/workflows/bump-version.yml +0 -35
  202. package/.github/workflows/ci.yml +0 -39
  203. package/.github/workflows/label-pr.yml +0 -40
  204. package/.github/workflows/update-tokens.yml +0 -43
  205. package/.husky/pre-commit +0 -1
  206. package/.mcp.json +0 -3
  207. package/.nvmrc +0 -1
  208. package/.prettierrc +0 -4
  209. package/CHANGELOG.md +0 -263
  210. package/CLAUDE.md +0 -307
  211. package/CODE_OF_CONDUCT.md +0 -128
  212. package/CONTRIBUTING.md +0 -159
  213. package/CONTRIBUTORS.md +0 -26
  214. package/LICENSE-NANOCLAW-MIT +0 -21
  215. package/README_ja.md +0 -194
  216. package/README_zh.md +0 -194
  217. package/assets/nanoclaw-favicon.png +0 -0
  218. package/assets/nanoclaw-icon.png +0 -0
  219. package/assets/nanoclaw-logo-dark.png +0 -0
  220. package/assets/nanoclaw-logo.png +0 -0
  221. package/assets/nanoclaw-profile.jpeg +0 -0
  222. package/assets/nanoclaw-sales.png +0 -0
  223. package/assets/social-preview.jpg +0 -0
  224. package/config-examples/mount-allowlist.json +0 -25
  225. package/container/.dockerignore +0 -2
  226. package/container/CLAUDE.md +0 -21
  227. package/container/Dockerfile +0 -121
  228. package/container/agent-runner/bun.lock +0 -243
  229. package/container/agent-runner/package.json +0 -22
  230. package/container/agent-runner/scripts/sdk-signal-probe.ts +0 -169
  231. package/container/agent-runner/src/config.ts +0 -55
  232. package/container/agent-runner/src/db/connection.ts +0 -267
  233. package/container/agent-runner/src/db/index.ts +0 -20
  234. package/container/agent-runner/src/db/messages-in.ts +0 -138
  235. package/container/agent-runner/src/db/messages-out.ts +0 -143
  236. package/container/agent-runner/src/db/session-routing.ts +0 -30
  237. package/container/agent-runner/src/db/session-state.test.ts +0 -100
  238. package/container/agent-runner/src/db/session-state.ts +0 -79
  239. package/container/agent-runner/src/destinations.ts +0 -135
  240. package/container/agent-runner/src/formatter.test.ts +0 -167
  241. package/container/agent-runner/src/formatter.ts +0 -260
  242. package/container/agent-runner/src/index.ts +0 -110
  243. package/container/agent-runner/src/integration.test.ts +0 -121
  244. package/container/agent-runner/src/mcp-tools/agents.instructions.md +0 -26
  245. package/container/agent-runner/src/mcp-tools/agents.ts +0 -66
  246. package/container/agent-runner/src/mcp-tools/core.instructions.md +0 -27
  247. package/container/agent-runner/src/mcp-tools/core.ts +0 -262
  248. package/container/agent-runner/src/mcp-tools/index.ts +0 -22
  249. package/container/agent-runner/src/mcp-tools/interactive.instructions.md +0 -22
  250. package/container/agent-runner/src/mcp-tools/interactive.ts +0 -169
  251. package/container/agent-runner/src/mcp-tools/scheduling.instructions.md +0 -40
  252. package/container/agent-runner/src/mcp-tools/scheduling.ts +0 -299
  253. package/container/agent-runner/src/mcp-tools/self-mod.instructions.md +0 -25
  254. package/container/agent-runner/src/mcp-tools/self-mod.ts +0 -120
  255. package/container/agent-runner/src/mcp-tools/server.ts +0 -54
  256. package/container/agent-runner/src/mcp-tools/types.ts +0 -6
  257. package/container/agent-runner/src/poll-loop.test.ts +0 -248
  258. package/container/agent-runner/src/poll-loop.ts +0 -437
  259. package/container/agent-runner/src/providers/claude.ts +0 -379
  260. package/container/agent-runner/src/providers/factory.test.ts +0 -19
  261. package/container/agent-runner/src/providers/factory.ts +0 -13
  262. package/container/agent-runner/src/providers/index.ts +0 -6
  263. package/container/agent-runner/src/providers/mock.ts +0 -77
  264. package/container/agent-runner/src/providers/provider-registry.ts +0 -33
  265. package/container/agent-runner/src/providers/types.ts +0 -82
  266. package/container/agent-runner/src/scheduling/task-script.ts +0 -121
  267. package/container/agent-runner/src/timezone.test.ts +0 -93
  268. package/container/agent-runner/src/timezone.ts +0 -107
  269. package/container/agent-runner/tsconfig.json +0 -14
  270. package/container/build.sh +0 -48
  271. package/container/entrypoint.sh +0 -16
  272. package/container/skills/agent-browser/SKILL.md +0 -159
  273. package/container/skills/frontend-engineer/SKILL.md +0 -157
  274. package/container/skills/self-customize/SKILL.md +0 -87
  275. package/container/skills/slack-formatting/SKILL.md +0 -94
  276. package/container/skills/vercel-cli/SKILL.md +0 -111
  277. package/container/skills/welcome/SKILL.md +0 -85
  278. package/docs/APPLE-CONTAINER-NETWORKING.md +0 -90
  279. package/docs/BRANCH-FORK-MAINTENANCE.md +0 -81
  280. package/docs/README.md +0 -25
  281. package/docs/SDK_DEEP_DIVE.md +0 -643
  282. package/docs/SECURITY.md +0 -162
  283. package/docs/agent-runner-details.md +0 -749
  284. package/docs/api-details.md +0 -365
  285. package/docs/architecture-diagram.html +0 -422
  286. package/docs/architecture-diagram.md +0 -215
  287. package/docs/architecture.md +0 -751
  288. package/docs/audit/2026-04-30-channel-endpoint-audit.md +0 -36
  289. package/docs/build-and-runtime.md +0 -80
  290. package/docs/cross-mount-stress/README.md +0 -112
  291. package/docs/cross-mount-stress/container-writer-retry.mjs +0 -55
  292. package/docs/cross-mount-stress/container-writer-slow.mjs +0 -42
  293. package/docs/cross-mount-stress/container-writer.mjs +0 -47
  294. package/docs/cross-mount-stress/host-writer-retry.mjs +0 -55
  295. package/docs/cross-mount-stress/host-writer-slow.mjs +0 -43
  296. package/docs/cross-mount-stress/host-writer.mjs +0 -47
  297. package/docs/db-central.md +0 -316
  298. package/docs/db-session.md +0 -183
  299. package/docs/db.md +0 -119
  300. package/docs/design/2026-04-29-vault-management-ui.md +0 -231
  301. package/docs/design/2026-04-30-channel-wiring-rework.md +0 -234
  302. package/docs/design/2026-05-01-channel-wiring-approvals-deep-dive.md +0 -272
  303. package/docs/design/2026-05-02-channel-policy-and-approval-routing.md +0 -250
  304. package/docs/docker-sandboxes.md +0 -359
  305. package/docs/isolation-model.md +0 -88
  306. package/docs/ollama.md +0 -79
  307. package/docs/parachute-integration.md +0 -109
  308. package/docs/post-night-rebirth-reflections.md +0 -151
  309. package/eslint.config.js +0 -32
  310. package/pnpm-workspace.yaml +0 -8
  311. package/repo-tokens/README.md +0 -113
  312. package/repo-tokens/action.yml +0 -186
  313. package/repo-tokens/badge.svg +0 -23
  314. package/repo-tokens/examples/green.svg +0 -14
  315. package/repo-tokens/examples/red.svg +0 -14
  316. package/repo-tokens/examples/yellow-green.svg +0 -14
  317. package/repo-tokens/examples/yellow.svg +0 -14
  318. package/scripts/chat.ts +0 -101
  319. package/scripts/cleanup-sessions.sh +0 -150
  320. package/scripts/init-cli-agent.ts +0 -172
  321. package/scripts/init-first-agent.ts +0 -378
  322. package/scripts/parachute.ts +0 -158
  323. package/scripts/run-migrations.ts +0 -105
  324. package/scripts/sanity-live-poll.ts +0 -95
  325. package/scripts/seed-discord.ts +0 -80
  326. package/scripts/test-v2-agent.ts +0 -106
  327. package/scripts/test-v2-channel-e2e.ts +0 -265
  328. package/scripts/test-v2-host.ts +0 -184
  329. package/src/channels/adapter.ts +0 -214
  330. package/src/channels/api-translator.test.ts +0 -306
  331. package/src/channels/api-translator.ts +0 -214
  332. package/src/channels/ask-question.ts +0 -46
  333. package/src/channels/channel-registry.test.ts +0 -421
  334. package/src/channels/channel-registry.ts +0 -313
  335. package/src/channels/chat-sdk-bridge.test.ts +0 -84
  336. package/src/channels/chat-sdk-bridge.ts +0 -652
  337. package/src/channels/cli.ts +0 -276
  338. package/src/channels/discord.ts +0 -90
  339. package/src/channels/index.ts +0 -17
  340. package/src/channels/telegram-markdown-sanitize.test.ts +0 -78
  341. package/src/channels/telegram-markdown-sanitize.ts +0 -55
  342. package/src/channels/telegram-pairing.test.ts +0 -254
  343. package/src/channels/telegram-pairing.ts +0 -339
  344. package/src/channels/telegram.ts +0 -279
  345. package/src/channels/trust-hint.test.ts +0 -48
  346. package/src/channels/trust-hint.ts +0 -75
  347. package/src/claude-md-compose.migrate.test.ts +0 -64
  348. package/src/claude-md-compose.ts +0 -205
  349. package/src/command-gate.ts +0 -63
  350. package/src/config.test.ts +0 -93
  351. package/src/config.ts +0 -128
  352. package/src/container-config.ts +0 -167
  353. package/src/container-runner.test.ts +0 -32
  354. package/src/container-runner.ts +0 -576
  355. package/src/container-runtime.test.ts +0 -269
  356. package/src/container-runtime.ts +0 -167
  357. package/src/db/_bun-sqlite-shim.ts +0 -88
  358. package/src/db/agent-activity.test.ts +0 -155
  359. package/src/db/agent-activity.ts +0 -121
  360. package/src/db/agent-groups.ts +0 -77
  361. package/src/db/connection.migrate.test.ts +0 -176
  362. package/src/db/connection.ts +0 -259
  363. package/src/db/db-v2.test.ts +0 -440
  364. package/src/db/dropped-messages.ts +0 -44
  365. package/src/db/index.ts +0 -40
  366. package/src/db/messaging-groups.ts +0 -252
  367. package/src/db/migrations/001-initial.ts +0 -112
  368. package/src/db/migrations/002-chat-sdk-state.ts +0 -36
  369. package/src/db/migrations/008-dropped-messages.ts +0 -27
  370. package/src/db/migrations/009-drop-pending-credentials.ts +0 -13
  371. package/src/db/migrations/010-engage-modes.ts +0 -103
  372. package/src/db/migrations/011-pending-sender-approvals.ts +0 -40
  373. package/src/db/migrations/012-channel-registration.ts +0 -48
  374. package/src/db/migrations/013-approval-render-metadata.ts +0 -27
  375. package/src/db/migrations/014-secrets.ts +0 -44
  376. package/src/db/migrations/015-secrets-drop-host-pattern.ts +0 -18
  377. package/src/db/migrations/016-secret-assignments.ts +0 -30
  378. package/src/db/migrations/017-agent-activity.ts +0 -40
  379. package/src/db/migrations/018-oauth-app-configs.ts +0 -34
  380. package/src/db/migrations/019-oauth-app-connections.ts +0 -48
  381. package/src/db/migrations/020-agent-app-connections.ts +0 -28
  382. package/src/db/migrations/021-pending-oauth-states.ts +0 -35
  383. package/src/db/migrations/022-app-connections-provider.ts +0 -25
  384. package/src/db/migrations/023-agent-group-secret-mode.test.ts +0 -124
  385. package/src/db/migrations/023-agent-group-secret-mode.ts +0 -65
  386. package/src/db/migrations/024-collapse-approvals.test.ts +0 -249
  387. package/src/db/migrations/024-collapse-approvals.ts +0 -182
  388. package/src/db/migrations/025-secret-mode-check.test.ts +0 -155
  389. package/src/db/migrations/025-secret-mode-check.ts +0 -49
  390. package/src/db/migrations/026-user-dms-bot-id.test.ts +0 -116
  391. package/src/db/migrations/026-user-dms-bot-id.ts +0 -54
  392. package/src/db/migrations/027-provider-credentials.ts +0 -41
  393. package/src/db/migrations/_test-helpers.ts +0 -41
  394. package/src/db/migrations/index.ts +0 -127
  395. package/src/db/migrations/module-agent-to-agent-destinations.ts +0 -84
  396. package/src/db/migrations/module-approvals-pending-approvals.ts +0 -42
  397. package/src/db/migrations/module-approvals-title-options.ts +0 -40
  398. package/src/db/schema.ts +0 -258
  399. package/src/db/session-db.test.ts +0 -93
  400. package/src/db/session-db.ts +0 -325
  401. package/src/db/sessions.ts +0 -241
  402. package/src/delivery.test.ts +0 -148
  403. package/src/delivery.ts +0 -445
  404. package/src/env.ts +0 -74
  405. package/src/group-folder.test.ts +0 -35
  406. package/src/group-folder.ts +0 -44
  407. package/src/group-init.ts +0 -92
  408. package/src/host-core.test.ts +0 -456
  409. package/src/host-sweep.test.ts +0 -146
  410. package/src/host-sweep.ts +0 -287
  411. package/src/index.ts +0 -232
  412. package/src/install-slug.ts +0 -33
  413. package/src/log.test.ts +0 -81
  414. package/src/log.ts +0 -117
  415. package/src/mcp/http.ts +0 -72
  416. package/src/mcp/server.ts +0 -92
  417. package/src/mcp/stdio.ts +0 -51
  418. package/src/mcp/tools/activity.ts +0 -88
  419. package/src/mcp/tools/agent-groups.ts +0 -183
  420. package/src/mcp/tools/approvals.ts +0 -122
  421. package/src/mcp/tools/channels.test.ts +0 -126
  422. package/src/mcp/tools/channels.ts +0 -134
  423. package/src/mcp/tools/index.ts +0 -27
  424. package/src/mcp/tools/oauth.ts +0 -48
  425. package/src/mcp/tools/secrets.ts +0 -169
  426. package/src/mcp/tools/sessions.ts +0 -135
  427. package/src/mcp/types.ts +0 -51
  428. package/src/modules/agent-to-agent/agent-route.test.ts +0 -46
  429. package/src/modules/agent-to-agent/agent-route.ts +0 -223
  430. package/src/modules/agent-to-agent/create-agent.ts +0 -127
  431. package/src/modules/agent-to-agent/db/agent-destinations.ts +0 -135
  432. package/src/modules/agent-to-agent/index.ts +0 -22
  433. package/src/modules/agent-to-agent/write-destinations.ts +0 -59
  434. package/src/modules/approvals/agent.md +0 -45
  435. package/src/modules/approvals/index.ts +0 -21
  436. package/src/modules/approvals/picks.test.ts +0 -291
  437. package/src/modules/approvals/primitive.ts +0 -279
  438. package/src/modules/approvals/project.md +0 -27
  439. package/src/modules/approvals/response-handler.ts +0 -87
  440. package/src/modules/index.ts +0 -24
  441. package/src/modules/interactive/agent.md +0 -21
  442. package/src/modules/interactive/index.ts +0 -69
  443. package/src/modules/interactive/project.md +0 -12
  444. package/src/modules/mount-security/expand-path.test.ts +0 -82
  445. package/src/modules/mount-security/index.ts +0 -459
  446. package/src/modules/mount-security/migrate.test.ts +0 -91
  447. package/src/modules/permissions/access.ts +0 -28
  448. package/src/modules/permissions/channel-approval.test.ts +0 -389
  449. package/src/modules/permissions/channel-approval.ts +0 -188
  450. package/src/modules/permissions/db/agent-group-members.ts +0 -44
  451. package/src/modules/permissions/db/pending-channel-approvals.test.ts +0 -86
  452. package/src/modules/permissions/db/pending-channel-approvals.ts +0 -66
  453. package/src/modules/permissions/db/pending-sender-approvals.ts +0 -60
  454. package/src/modules/permissions/db/user-dms.ts +0 -58
  455. package/src/modules/permissions/db/user-roles.ts +0 -85
  456. package/src/modules/permissions/db/users.ts +0 -38
  457. package/src/modules/permissions/index.ts +0 -421
  458. package/src/modules/permissions/permissions.test.ts +0 -358
  459. package/src/modules/permissions/sender-approval.test.ts +0 -641
  460. package/src/modules/permissions/sender-approval.ts +0 -165
  461. package/src/modules/permissions/user-dm.ts +0 -200
  462. package/src/modules/provider-credentials/db.ts +0 -121
  463. package/src/modules/provider-credentials/index.ts +0 -12
  464. package/src/modules/provider-credentials/spawn.test.ts +0 -206
  465. package/src/modules/provider-credentials/spawn.ts +0 -114
  466. package/src/modules/scheduling/actions.ts +0 -113
  467. package/src/modules/scheduling/db.test.ts +0 -282
  468. package/src/modules/scheduling/db.ts +0 -148
  469. package/src/modules/scheduling/index.ts +0 -34
  470. package/src/modules/scheduling/recurrence.test.ts +0 -98
  471. package/src/modules/scheduling/recurrence.ts +0 -54
  472. package/src/modules/self-mod/agent.md +0 -30
  473. package/src/modules/self-mod/apply.ts +0 -85
  474. package/src/modules/self-mod/index.ts +0 -30
  475. package/src/modules/self-mod/project.md +0 -39
  476. package/src/modules/self-mod/request.ts +0 -91
  477. package/src/modules/typing/index.ts +0 -165
  478. package/src/oauth/agent-app-connections.ts +0 -103
  479. package/src/oauth/app-configs.test.ts +0 -64
  480. package/src/oauth/app-configs.ts +0 -114
  481. package/src/oauth/app-connections.test.ts +0 -109
  482. package/src/oauth/app-connections.ts +0 -178
  483. package/src/oauth/crypto.ts +0 -56
  484. package/src/oauth/flow.ts +0 -104
  485. package/src/oauth/providers/google.test.ts +0 -38
  486. package/src/oauth/providers/google.ts +0 -46
  487. package/src/oauth/providers/index.ts +0 -48
  488. package/src/oauth/state-store.test.ts +0 -54
  489. package/src/oauth/state-store.ts +0 -93
  490. package/src/parachute/README.md +0 -27
  491. package/src/parachute/create-agent.test.ts +0 -83
  492. package/src/parachute/create-agent.ts +0 -122
  493. package/src/parachute/group-status.test.ts +0 -165
  494. package/src/parachute/group-status.ts +0 -136
  495. package/src/parachute/types.ts +0 -41
  496. package/src/parachute/vault-mcp.test.ts +0 -251
  497. package/src/parachute/vault-mcp.ts +0 -232
  498. package/src/platform-id.test.ts +0 -104
  499. package/src/platform-id.ts +0 -109
  500. package/src/providers/index.ts +0 -6
  501. package/src/providers/provider-container-registry.ts +0 -58
  502. package/src/response-registry.ts +0 -45
  503. package/src/router.ts +0 -530
  504. package/src/secrets/crypto.test.ts +0 -45
  505. package/src/secrets/crypto.ts +0 -55
  506. package/src/secrets/index.ts +0 -461
  507. package/src/secrets/master-key.ts +0 -70
  508. package/src/secrets/secrets.test.ts +0 -651
  509. package/src/session-manager.attachments.test.ts +0 -171
  510. package/src/session-manager.dup-skip.test.ts +0 -173
  511. package/src/session-manager.migrate.test.ts +0 -59
  512. package/src/session-manager.ts +0 -451
  513. package/src/startup-bootstrap.test.ts +0 -226
  514. package/src/startup-bootstrap.ts +0 -207
  515. package/src/state-sqlite.ts +0 -182
  516. package/src/timezone.test.ts +0 -64
  517. package/src/timezone.ts +0 -37
  518. package/src/types.ts +0 -233
  519. package/src/web/auth.test.ts +0 -335
  520. package/src/web/auth.ts +0 -214
  521. package/src/web/discord-validate.test.ts +0 -77
  522. package/src/web/discord-validate.ts +0 -88
  523. package/src/web/hub-discovery.test.ts +0 -98
  524. package/src/web/hub-discovery.ts +0 -69
  525. package/src/web/routes/activity.ts +0 -106
  526. package/src/web/routes/agent-provider.test.ts +0 -282
  527. package/src/web/routes/agent-provider.ts +0 -309
  528. package/src/web/routes/approvals.ts +0 -185
  529. package/src/web/routes/apps.ts +0 -434
  530. package/src/web/routes/channels-mg-detail.test.ts +0 -324
  531. package/src/web/routes/channels-mga-detail.test.ts +0 -472
  532. package/src/web/routes/channels.ts +0 -311
  533. package/src/web/routes/oauth-providers.ts +0 -42
  534. package/src/web/routes/secrets.test.ts +0 -220
  535. package/src/web/routes/secrets.ts +0 -317
  536. package/src/web/routes/sessions.ts +0 -123
  537. package/src/web/routes/settings.test.ts +0 -106
  538. package/src/web/routes/settings.ts +0 -247
  539. package/src/web/routes/setup-status.ts +0 -205
  540. package/src/web/routes/vaults.test.ts +0 -389
  541. package/src/web/routes/vaults.ts +0 -225
  542. package/src/web/server-version.test.ts +0 -16
  543. package/src/web/server.ts +0 -1024
  544. package/src/web/services-manifest.test.ts +0 -148
  545. package/src/web/services-manifest.ts +0 -66
  546. package/src/web/static-serve.test.ts +0 -255
  547. package/src/web/static-serve.ts +0 -104
  548. package/src/web/telegram-validate.test.ts +0 -116
  549. package/src/web/telegram-validate.ts +0 -107
  550. package/src/web/vault-proxy.test.ts +0 -214
  551. package/src/web/vault-proxy.ts +0 -120
  552. package/src/web/wire-channel.ts +0 -181
  553. package/src/webhook-server.ts +0 -134
  554. package/vitest.config.ts +0 -18
  555. package/web/README.md +0 -63
  556. package/web/ui/index.html +0 -13
  557. package/web/ui/package.json +0 -35
  558. package/web/ui/pnpm-lock.yaml +0 -2164
  559. package/web/ui/scripts/verify-base.mjs +0 -31
  560. package/web/ui/src/App.tsx +0 -88
  561. package/web/ui/src/components/ActivityFeed.tsx +0 -444
  562. package/web/ui/src/components/AgentGroupPicker.tsx +0 -263
  563. package/web/ui/src/components/AgentProviderCards.tsx +0 -220
  564. package/web/ui/src/components/CredentialForm.tsx +0 -214
  565. package/web/ui/src/components/ScopeGrants.tsx +0 -74
  566. package/web/ui/src/components/StatusDot.tsx +0 -43
  567. package/web/ui/src/components/VaultPicker.tsx +0 -127
  568. package/web/ui/src/components/setup/AdapterInstallStep.tsx +0 -178
  569. package/web/ui/src/components/setup/AgentGroupStep.tsx +0 -43
  570. package/web/ui/src/components/setup/ChannelPickStep.tsx +0 -74
  571. package/web/ui/src/components/setup/DoneStep.tsx +0 -49
  572. package/web/ui/src/components/setup/PrereqStep.tsx +0 -129
  573. package/web/ui/src/components/setup/TestConnectionStep.tsx +0 -108
  574. package/web/ui/src/components/setup/TestMessageStep.tsx +0 -104
  575. package/web/ui/src/components/setup/WireChannelStep.tsx +0 -166
  576. package/web/ui/src/components/setup/types.ts +0 -105
  577. package/web/ui/src/lib/api.test.ts +0 -410
  578. package/web/ui/src/lib/api.ts +0 -1248
  579. package/web/ui/src/lib/auth.test.ts +0 -352
  580. package/web/ui/src/lib/auth.ts +0 -405
  581. package/web/ui/src/lib/channel-adapters.ts +0 -136
  582. package/web/ui/src/main.tsx +0 -19
  583. package/web/ui/src/routes/ApprovalsList.tsx +0 -294
  584. package/web/ui/src/routes/Apps.tsx +0 -613
  585. package/web/ui/src/routes/ChannelWireDetail.test.tsx +0 -233
  586. package/web/ui/src/routes/ChannelWireDetail.tsx +0 -403
  587. package/web/ui/src/routes/ChannelsList.tsx +0 -158
  588. package/web/ui/src/routes/GroupDetail.test.tsx +0 -206
  589. package/web/ui/src/routes/GroupDetail.tsx +0 -880
  590. package/web/ui/src/routes/GroupList.tsx +0 -187
  591. package/web/ui/src/routes/MessagingGroupDetail.test.tsx +0 -233
  592. package/web/ui/src/routes/MessagingGroupDetail.tsx +0 -306
  593. package/web/ui/src/routes/NewGroupWizard.tsx +0 -390
  594. package/web/ui/src/routes/OAuthCallback.tsx +0 -56
  595. package/web/ui/src/routes/SecretsList.tsx +0 -942
  596. package/web/ui/src/routes/SessionsList.tsx +0 -220
  597. package/web/ui/src/routes/SettingsAgentProvider.tsx +0 -109
  598. package/web/ui/src/routes/SettingsApprovals.tsx +0 -234
  599. package/web/ui/src/routes/SetupWizard.tsx +0 -219
  600. package/web/ui/src/routes/VaultDetail.test.tsx +0 -363
  601. package/web/ui/src/routes/VaultDetail.tsx +0 -960
  602. package/web/ui/src/routes/VaultsList.tsx +0 -295
  603. package/web/ui/src/routes/WireChannelPage.tsx +0 -413
  604. package/web/ui/src/styles.css +0 -608
  605. package/web/ui/src/test/setup.ts +0 -23
  606. package/web/ui/src/vite-env.d.ts +0 -10
  607. package/web/ui/vite.config.ts +0 -34
  608. package/web/ui/vitest.config.ts +0 -25
package/docs/architecture-diagram.html DELETED
@@ -1,422 +0,0 @@
1
- <!doctype html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="utf-8" />
5
- <meta name="viewport" content="width=device-width,initial-scale=1" />
6
- <title>Paraclaw Architecture</title>
7
- <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
8
- <style>
9
- :root {
10
- --bg: #0b0d12;
11
- --panel: #141821;
12
- --ink: #e7ecf3;
13
- --muted: #8a94a6;
14
- --accent: #7aa2ff;
15
- --border: #232a38;
16
- }
17
- * { box-sizing: border-box; }
18
- html, body {
19
- margin: 0;
20
- padding: 0;
21
- background: var(--bg);
22
- color: var(--ink);
23
- font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", Helvetica, Arial, sans-serif;
24
- font-size: 15px;
25
- line-height: 1.55;
26
- }
27
- header {
28
- padding: 32px 40px 16px;
29
- border-bottom: 1px solid var(--border);
30
- position: sticky;
31
- top: 0;
32
- background: rgba(11, 13, 18, 0.92);
33
- backdrop-filter: saturate(180%) blur(10px);
34
- z-index: 10;
35
- }
36
- header h1 {
37
- margin: 0 0 4px;
38
- font-size: 22px;
39
- font-weight: 600;
40
- letter-spacing: -0.01em;
41
- }
42
- header .sub {
43
- color: var(--muted);
44
- font-size: 13px;
45
- }
46
- nav {
47
- display: flex;
48
- flex-wrap: wrap;
49
- gap: 8px;
50
- margin-top: 14px;
51
- }
52
- nav a {
53
- color: var(--accent);
54
- text-decoration: none;
55
- font-size: 12px;
56
- padding: 4px 10px;
57
- border: 1px solid var(--border);
58
- border-radius: 999px;
59
- background: var(--panel);
60
- }
61
- nav a:hover { border-color: var(--accent); }
62
- main {
63
- max-width: 1280px;
64
- margin: 0 auto;
65
- padding: 28px 40px 80px;
66
- }
67
- section {
68
- margin-bottom: 48px;
69
- }
70
- section h2 {
71
- font-size: 18px;
72
- font-weight: 600;
73
- margin: 0 0 6px;
74
- letter-spacing: -0.005em;
75
- }
76
- section h2 .num {
77
- color: var(--muted);
78
- font-weight: 500;
79
- margin-right: 8px;
80
- }
81
- section p.desc {
82
- color: var(--muted);
83
- margin: 0 0 16px;
84
- max-width: 900px;
85
- }
86
- .diagram {
87
- background: var(--panel);
88
- border: 1px solid var(--border);
89
- border-radius: 14px;
90
- padding: 24px;
91
- overflow-x: auto;
92
- }
93
- .diagram svg { max-width: 100%; height: auto; display: block; margin: 0 auto; }
94
- table {
95
- width: 100%;
96
- border-collapse: collapse;
97
- margin-top: 14px;
98
- font-size: 13px;
99
- }
100
- th, td {
101
- text-align: left;
102
- padding: 10px 12px;
103
- border-bottom: 1px solid var(--border);
104
- }
105
- th {
106
- color: var(--muted);
107
- font-weight: 500;
108
- text-transform: uppercase;
109
- font-size: 11px;
110
- letter-spacing: 0.04em;
111
- }
112
- code {
113
- font-family: "SF Mono", Menlo, Consolas, monospace;
114
- font-size: 12px;
115
- background: #1c2230;
116
- padding: 1px 6px;
117
- border-radius: 4px;
118
- color: #c8d4ee;
119
- }
120
- footer {
121
- color: var(--muted);
122
- font-size: 12px;
123
- text-align: center;
124
- padding: 20px 0 0;
125
- border-top: 1px solid var(--border);
126
- }
127
- </style>
128
- </head>
129
- <body>
130
- <header>
131
- <h1>Paraclaw Architecture</h1>
132
- <div class="sub">Session-DB messaging model · Chat SDK bridge · local AES-GCM secret store · per-session containers</div>
133
- <nav>
134
- <a href="#overview">1 · Overview</a>
135
- <a href="#flow">2 · Message Flow</a>
136
- <a href="#destinations">3 · Destinations &amp; A2A</a>
137
- <a href="#entities">4 · Entity Model</a>
138
- <a href="#twodb">5 · Two-DB Split</a>
139
- </nav>
140
- </header>
141
-
142
- <main>
143
- <section id="overview">
144
- <h2><span class="num">1</span>System Overview</h2>
145
- <p class="desc">
146
- Inbound messages land at the Chat SDK bridge, which hands off to the
147
- router. The router resolves the messaging group → agent group → session
148
- and writes to the session's <code>inbound.db</code>. The container runner
149
- spawns a per-session container (with secrets injected as env vars from
150
- paraclaw's local AES-GCM secret store), and the agent-runner
151
- polls its DB, calls Claude, and writes responses to <code>outbound.db</code>.
152
- Delivery polls the outbound DB, re-validates destinations, and ships
153
- messages back through the same bridge.
154
- </p>
155
- <div class="diagram">
156
- <pre class="mermaid">
157
- flowchart TB
158
- subgraph Platforms["Messaging Platforms"]
159
- P1[Discord]
160
- P2[Telegram]
161
- P3[Slack]
162
- P4[GitHub / Linear]
163
- P5[WhatsApp / iMessage / Teams / GChat / Matrix / Webex / Email]
164
- end
165
-
166
- subgraph Host["Host Process (Node)"]
167
- direction TB
168
- Bridge["Chat SDK Bridge<br/>src/channels/chat-sdk-bridge.ts"]
169
- Router["Router<br/>src/router.ts<br/>platformId + threadId → session"]
170
- SessMgr["Session Manager<br/>src/session-manager.ts"]
171
- Runner["Container Runner<br/>src/container-runner.ts<br/>spawn + secret env injection"]
172
- Delivery["Delivery Poller<br/>src/delivery.ts<br/>1s active / 60s sweep"]
173
- Sweep["Host Sweep<br/>src/host-sweep.ts"]
174
- Central[("Central DB · data/v2.db<br/>agent_groups · messaging_groups<br/>messaging_group_agents · sessions<br/>pending_approvals")]
175
- end
176
-
177
- subgraph Secrets["Local Secret Store"]
178
- Vault["AES-GCM ciphertext<br/>(central DB)<br/>master key on host"]
179
- Approvals["pending_approvals (self-mod)"]
180
- end
181
-
182
- subgraph Session["Per-Session Container"]
183
- direction TB
184
- PollLoop["Poll Loop<br/>container/agent-runner"]
185
- Provider["Claude Agent SDK<br/>(codex / opencode planned)"]
186
- MCP["MCP Tools<br/>send_message · send_file · edit_message<br/>send_card · ask_user_question · schedule_task<br/>create_agent · install_packages · add_mcp_server<br/>request_rebuild"]
187
- InDB[("inbound.db<br/>host writes · even seq")]
188
- OutDB[("outbound.db<br/>container writes · odd seq")]
189
- end
190
-
191
- Folder["Agent Group FS<br/>groups/*<br/>CLAUDE.md · memory · skills"]
192
-
193
- P1 & P2 & P3 & P4 & P5 --> Bridge
194
- Bridge --> Router
195
- Router --> Central
196
- Router --> SessMgr
197
- SessMgr --> InDB
198
- SessMgr --> Runner
199
- Runner --> Vault
200
- Runner --> PollLoop
201
- PollLoop --> InDB
202
- PollLoop --> Provider
203
- Provider --> MCP
204
- MCP --> OutDB
205
- OutDB --> Delivery
206
- Delivery --> Central
207
- Delivery --> Bridge
208
- Bridge --> P1 & P2 & P3 & P4 & P5
209
- Sweep --> InDB
210
- Sweep --> OutDB
211
- Sweep --> Central
212
- Runner -.mounts.-> Folder
213
- MCP -.approval.-> Approvals
214
- Approvals --> Central
215
- Vault -.env vars.-> Provider
216
- </pre>
217
- </div>
218
- </section>
219
-
220
- <section id="flow">
221
- <h2><span class="num">2</span>Message Flow</h2>
222
- <p class="desc">
223
- End-to-end path of a single message. The host and container never write
224
- to the same SQLite file — the split between inbound and outbound DBs is
225
- what makes this lock-free under concurrent activity.
226
- </p>
227
- <div class="diagram">
228
- <pre class="mermaid">
229
- sequenceDiagram
230
- participant P as Platform (Telegram)
231
- participant B as Chat SDK Bridge
232
- participant R as Router
233
- participant SM as Session Manager
234
- participant IDB as inbound.db
235
- participant C as Container (agent-runner)
236
- participant ODB as outbound.db
237
- participant D as Delivery Poller
238
-
239
- P->>B: new message
240
- B->>R: routeInbound(platformId, threadId, msg)
241
- R->>R: resolve messaging_group → agent_group → session<br/>(agent-shared · shared · per-thread)
242
- R->>SM: ensure session + DBs exist
243
- R->>IDB: INSERT messages_in (even seq)
244
- R->>C: wake container (spawn or signal)
245
- C->>IDB: poll messages_in
246
- C->>C: format xml → Claude SDK stream
247
- C->>ODB: INSERT messages_out (odd seq)<br/>parse &lt;message to='name'&gt; blocks
248
- D->>ODB: 1s active poll / 60s sweep
249
- D->>D: hasDestination() re-validate
250
- D->>B: deliver via adapter
251
- B->>P: send · edit · react · file · card
252
- </pre>
253
- </div>
254
- </section>
255
-
256
- <section id="destinations">
257
- <h2><span class="num">3</span>Named Destinations &amp; Agent-to-Agent</h2>
258
- <p class="desc">
259
- Agents address outputs by local name. The host looks up each name against
260
- the agent's destinations table at delivery time — dropping anything
261
- unauthorized. The same table routes agent-to-agent messages to a sibling
262
- agent's <code>inbound.db</code> with bidirectional permission rows.
263
- </p>
264
- <div class="diagram">
265
- <pre class="mermaid">
266
- flowchart LR
267
- subgraph AgentA["Agent Group A (main)"]
268
- A_out["&lt;message to='slack'&gt;...&lt;/message&gt;<br/>&lt;message to='browser-agent'&gt;...&lt;/message&gt;<br/>&lt;internal&gt;scratchpad&lt;/internal&gt;"]
269
- end
270
-
271
- subgraph Dests["inbound.db.destinations (per agent)"]
272
- D1["slack → messaging_group 42"]
273
- D2["browser-agent → agent_group 7<br/>(bidirectional)"]
274
- D3["github → messaging_group 13"]
275
- end
276
-
277
- subgraph AgentB["Agent Group B (browser sub-agent)"]
278
- B_session["own inbound.db / outbound.db<br/>inherited destination back to A"]
279
- end
280
-
281
- Slack[Slack]
282
- GitHub[GitHub PR]
283
-
284
- A_out -->|parse + lookup| Dests
285
- D1 -->|deliver| Slack
286
- D2 -->|write to B's inbound.db| B_session
287
- D3 -->|deliver| GitHub
288
- B_session -.reply via 'parent'.-> Dests
289
- </pre>
290
- </div>
291
- </section>
292
-
293
- <section id="entities">
294
- <h2><span class="num">4</span>Entity Model</h2>
295
- <p class="desc">
296
- Messaging groups and agent groups are many-to-many, joined via
297
- <code>messaging_group_agents</code>. The <code>session_mode</code>
298
- column selects one of three isolation levels.
299
- </p>
300
- <div class="diagram">
301
- <pre class="mermaid">
302
- erDiagram
303
- agent_groups ||--o{ messaging_group_agents : wired
304
- messaging_groups ||--o{ messaging_group_agents : wired
305
- agent_groups ||--o{ sessions : runs
306
- messaging_groups ||--o{ sessions : context
307
- agent_groups ||--o{ agent_destinations : owns
308
- agent_groups ||--o{ pending_approvals : requests
309
-
310
- agent_groups {
311
- int id
312
- string name
313
- string folder
314
- string agent_provider
315
- json container_config
316
- }
317
- messaging_groups {
318
- int id
319
- string channel_type
320
- string platform_id
321
- string name
322
- bool is_group
323
- string unknown_sender_policy "strict | request_approval | public"
324
- }
325
- users {
326
- string id PK "namespaced &lt;channel&gt;:&lt;handle&gt;"
327
- string kind
328
- string display_name
329
- }
330
- user_roles {
331
- string user_id FK
332
- string role "owner | admin"
333
- string agent_group_id FK "null = global"
334
- }
335
- agent_group_members {
336
- string user_id FK
337
- string agent_group_id FK
338
- }
339
- user_dms {
340
- string user_id FK
341
- string channel_type
342
- string messaging_group_id FK
343
- }
344
- messaging_group_agents {
345
- int messaging_group_id
346
- int agent_group_id
347
- string session_mode
348
- json trigger_rules
349
- int priority
350
- }
351
- sessions {
352
- int id
353
- int agent_group_id
354
- int messaging_group_id
355
- string sdk_session_id
356
- string status
357
- }
358
- </pre>
359
- </div>
360
- <table>
361
- <thead>
362
- <tr><th>Level</th><th>session_mode</th><th>Shared</th><th>Example</th></tr>
363
- </thead>
364
- <tbody>
365
- <tr><td>1 · Shared session</td><td><code>agent-shared</code></td><td>Workspace + memory + conversation</td><td>Slack + GitHub webhooks in one thread</td></tr>
366
- <tr><td>2 · Same agent, separate sessions</td><td><code>shared</code> / <code>per-thread</code></td><td>Workspace + memory only</td><td>One agent across 3 Telegram chats</td></tr>
367
- <tr><td>3 · Separate agent groups</td><td>— (different agent_group_id)</td><td>Nothing</td><td>Personal vs work channels</td></tr>
368
- </tbody>
369
- </table>
370
- </section>
371
-
372
- <section id="twodb">
373
- <h2><span class="num">5</span>Two-DB Split</h2>
374
- <p class="desc">
375
- Each SQLite file has exactly one writer. The container touches a
376
- heartbeat file instead of <code>UPDATE</code>-ing a liveness row, so host
377
- sweep can detect staleness via <code>stat(mtime)</code> without opening the
378
- DB. Host uses even seq numbers, container uses odd — collision-free.
379
- </p>
380
- <div class="diagram">
381
- <pre class="mermaid">
382
- flowchart LR
383
- subgraph Mount["/workspace (volume mount)"]
384
- In[("inbound.db")]
385
- Out[("outbound.db")]
386
- HB["/.heartbeat (file touch)"]
387
- end
388
-
389
- Host[Host process] -->|writes · even seq| In
390
- Host -->|reads| Out
391
- Container[agent-runner] -->|reads| In
392
- Container -->|writes · odd seq| Out
393
- Container -->|touch every poll| HB
394
- HostSweep[Host sweep] -->|stat mtime| HB
395
- HostSweep -->|reads processing_ack| In
396
- </pre>
397
- </div>
398
- </section>
399
-
400
- <footer>Paraclaw · generated from docs/architecture.md, isolation-model.md</footer>
401
- </main>
402
-
403
- <script>
404
- mermaid.initialize({
405
- startOnLoad: true,
406
- theme: "dark",
407
- securityLevel: "loose",
408
- flowchart: { curve: "basis", padding: 18 },
409
- themeVariables: {
410
- background: "#141821",
411
- primaryColor: "#1c2230",
412
- primaryTextColor: "#e7ecf3",
413
- primaryBorderColor: "#3a465e",
414
- lineColor: "#6b7893",
415
- secondaryColor: "#222a3a",
416
- tertiaryColor: "#1a2030",
417
- fontSize: "14px",
418
- },
419
- });
420
- </script>
421
- </body>
422
- </html>
package/docs/architecture-diagram.md DELETED
@@ -1,215 +0,0 @@
1
- # Paraclaw Architecture Diagram
2
-
3
- ## System Overview
4
-
5
- ```mermaid
6
- flowchart TB
7
- subgraph Platforms["Messaging Platforms"]
8
- P1[Discord]
9
- P2[Telegram]
10
- P3[Slack]
11
- P4[GitHub / Linear]
12
- P5[WhatsApp / iMessage / Teams / GChat / Matrix / Webex / Email]
13
- end
14
-
15
- subgraph Host["Host Process (Node)"]
16
- direction TB
17
- Bridge["Chat SDK Bridge<br/>(src/channels/chat-sdk-bridge.ts)"]
18
- Router["Router<br/>(src/router.ts)<br/>platformId + threadId -> messaging_group -> agent_group -> session"]
19
- SessMgr["Session Manager<br/>(src/session-manager.ts)<br/>creates inbound.db + outbound.db"]
20
- Runner["Container Runner<br/>(src/container-runner.ts)<br/>spawn + secret env injection"]
21
- Delivery["Delivery Poller<br/>(src/delivery.ts)<br/>1s active / 60s sweep"]
22
- Sweep["Host Sweep<br/>(src/host-sweep.ts)<br/>heartbeat, retry, recurrence"]
23
- Central[("Central DB<br/>data/v2.db<br/>agent_groups<br/>messaging_groups<br/>messaging_group_agents<br/>sessions<br/>pending_approvals")]
24
- end
25
-
26
- subgraph Secrets["Local Secret Store"]
27
- Vault["AES-GCM ciphertext<br/>(central DB)<br/>master key on host"]
28
- Approvals["pending_approvals<br/>(self-mod)"]
29
- end
30
-
31
- subgraph Session["Per-Session Container (Docker / Apple Container)"]
32
- direction TB
33
- PollLoop["Poll Loop<br/>(container/agent-runner)"]
34
- Provider["Agent providers<br/>(claude, opencode, mock; todo: codex)"]
35
- MCP["MCP Tools<br/>send_message, send_file, edit_message,<br/>add_reaction, send_card, ask_user_question,<br/>schedule_task, create_agent,<br/>install_packages, add_mcp_server"]
36
- Skills["Container Skills<br/>(container/skills/)"]
37
- InDB[("inbound.db<br/>host writes<br/>even seq<br/>messages_in<br/>destinations<br/>processing_ack")]
38
- OutDB[("outbound.db<br/>container writes<br/>odd seq<br/>messages_out<br/>heartbeat file")]
39
- end
40
-
41
- subgraph Groups["Agent Group Filesystem (groups/*)"]
42
- Folder["CLAUDE.md<br/>memory<br/>per-group skills<br/>container_config"]
43
- end
44
-
45
- P1 & P2 & P3 & P4 & P5 --> Bridge
46
- Bridge --> Router
47
- Router --> Central
48
- Router --> SessMgr
49
- SessMgr --> InDB
50
- SessMgr --> Runner
51
- Runner --> Vault
52
- Runner --> PollLoop
53
- PollLoop --> InDB
54
- PollLoop --> Provider
55
- Provider --> MCP
56
- Provider --> Skills
57
- MCP --> OutDB
58
- OutDB --> Delivery
59
- Delivery --> Central
60
- Delivery --> Bridge
61
- Bridge --> P1 & P2 & P3 & P4 & P5
62
- Sweep --> InDB
63
- Sweep --> OutDB
64
- Sweep --> Central
65
- Runner -.mounts.-> Folder
66
- MCP -.approval.-> Approvals
67
- Approvals --> Central
68
- Vault -.env vars.-> Provider
69
- ```
70
-
71
- ## Message Flow (inbound -> agent -> outbound)
72
-
73
- ```mermaid
74
- sequenceDiagram
75
- participant P as Platform (e.g. Telegram)
76
- participant B as Chat SDK Bridge
77
- participant R as Router
78
- participant SM as Session Manager
79
- participant IDB as inbound.db
80
- participant C as Container (agent-runner)
81
- participant ODB as outbound.db
82
- participant D as Delivery Poller
83
-
84
- P->>B: new message
85
- B->>R: routeInbound(platformId, threadId, msg)
86
- R->>R: resolve messaging_group -> agent_group -> session<br/>(agent-shared | shared | per-thread)
87
- R->>SM: ensure session + DBs exist
88
- R->>IDB: INSERT messages_in (even seq)
89
- R->>C: wake container (docker run / already running)
90
- C->>IDB: poll messages_in
91
- C->>C: format xml, stream to selected provider
92
- C->>ODB: INSERT messages_out (odd seq)<br/>parse <message to="name"> blocks
93
- D->>ODB: 1s poll (active) / 60s (sweep)
94
- D->>D: hasDestination() re-validate
95
- D->>B: deliver via adapter
96
- B->>P: send message / edit / react / file / card
97
- ```
98
-
99
- ## Named Destinations + Agent-to-Agent
100
-
101
- ```mermaid
102
- flowchart LR
103
- subgraph AgentA["Agent Group A (main)"]
104
- A_out["output:<br/>&lt;message to='slack'&gt;...&lt;/message&gt;<br/>&lt;message to='browser-agent'&gt;...&lt;/message&gt;<br/>&lt;internal&gt;scratchpad&lt;/internal&gt;"]
105
- end
106
-
107
- subgraph Dests["inbound.db.destinations (per agent)"]
108
- D1["slack -> messaging_group 42"]
109
- D2["browser-agent -> agent_group 7<br/>(bidirectional row)"]
110
- D3["github -> messaging_group 13"]
111
- end
112
-
113
- subgraph AgentB["Agent Group B (browser sub-agent)"]
114
- B_session["own inbound.db / outbound.db<br/>inherited destination back to A"]
115
- end
116
-
117
- Slack[Slack channel]
118
- GitHub[GitHub PR thread]
119
-
120
- A_out -->|parse + lookup| Dests
121
- D1 -->|deliver| Slack
122
- D2 -->|write to B's inbound.db| B_session
123
- D3 -->|deliver| GitHub
124
- B_session -.reply via 'parent'.-> Dests
125
- ```
126
-
127
- ## Entity Model + Isolation Levels
128
-
129
- ```mermaid
130
- erDiagram
131
- agent_groups ||--o{ messaging_group_agents : wired
132
- messaging_groups ||--o{ messaging_group_agents : wired
133
- agent_groups ||--o{ sessions : runs
134
- messaging_groups ||--o{ sessions : context
135
- agent_groups ||--o{ agent_destinations : owns
136
- agent_groups ||--o{ pending_approvals : requests
137
-
138
- agent_groups {
139
- int id
140
- string name
141
- string folder
142
- string agent_provider
143
- json container_config
144
- }
145
- messaging_groups {
146
- int id
147
- string channel_type
148
- string platform_id
149
- string name
150
- bool is_group
151
- string unknown_sender_policy "strict | request_approval | public"
152
- }
153
- users {
154
- string id PK "namespaced <channel>:<handle>"
155
- string kind
156
- string display_name
157
- }
158
- user_roles {
159
- string user_id FK
160
- string role "owner | admin"
161
- string agent_group_id FK "null = global"
162
- }
163
- agent_group_members {
164
- string user_id FK
165
- string agent_group_id FK
166
- }
167
- user_dms {
168
- string user_id FK
169
- string channel_type
170
- string messaging_group_id FK
171
- }
172
- messaging_group_agents {
173
- int messaging_group_id
174
- int agent_group_id
175
- string session_mode "agent-shared | shared | per-thread"
176
- json trigger_rules
177
- int priority
178
- }
179
- sessions {
180
- int id
181
- int agent_group_id
182
- int messaging_group_id
183
- string sdk_session_id
184
- string status
185
- }
186
- ```
187
-
188
- ### Isolation Level Cheatsheet
189
-
190
- | Level | `session_mode` | What's shared | Example |
191
- |---|---|---|---|
192
- | 1. Shared session | `agent-shared` | Workspace + memory + conversation | Slack + GitHub webhooks in one thread |
193
- | 2. Same agent, separate sessions | `shared` / `per-thread` | Workspace + memory only | One agent across 3 Telegram chats |
194
- | 3. Separate agent groups | (different `agent_group_id`) | Nothing | Personal vs work channels |
195
-
196
- ## Two-DB Split (why)
197
-
198
- ```mermaid
199
- flowchart LR
200
- subgraph Mount["/workspace (volume mounted into container)"]
201
- In[("inbound.db")]
202
- Out[("outbound.db")]
203
- HB["/.heartbeat (file touch)"]
204
- end
205
-
206
- Host[Host process] -->|"writes only<br/>(even seq)"| In
207
- Host -->|reads| Out
208
- Container[agent-runner] -->|reads| In
209
- Container -->|"writes only<br/>(odd seq)"| Out
210
- Container -->|touch every poll| HB
211
- HostSweep[Host sweep] -->|stat mtime| HB
212
- HostSweep -->|reads processing_ack| In
213
-
214
- note1["Each file has exactly ONE writer.<br/>Eliminates SQLite cross-process write contention.<br/>Collision-free seq numbering."]
215
- ```