@openparachute/agent 0.1.2 → 0.2.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 (605) hide show
  1. package/.parachute/module.json +124 -8
  2. package/LICENSE +2 -16
  3. package/README.md +118 -166
  4. package/package.json +32 -43
  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/tsconfig.json +2 -1
  103. package/.claude/scheduled_tasks.lock +0 -1
  104. package/.claude/settings.json +0 -5
  105. package/.claude/skills/add-atomic-chat-tool/SKILL.md +0 -243
  106. package/.claude/skills/add-atomic-chat-tool/atomic-chat-mcp-stdio.ts +0 -229
  107. package/.claude/skills/add-codex/SKILL.md +0 -161
  108. package/.claude/skills/add-dashboard/SKILL.md +0 -138
  109. package/.claude/skills/add-dashboard/resources/dashboard-pusher.ts +0 -495
  110. package/.claude/skills/add-emacs/SKILL.md +0 -296
  111. package/.claude/skills/add-gcal-tool/SKILL.md +0 -210
  112. package/.claude/skills/add-gchat/REMOVE.md +0 -6
  113. package/.claude/skills/add-gchat/SKILL.md +0 -92
  114. package/.claude/skills/add-gchat/VERIFY.md +0 -3
  115. package/.claude/skills/add-github/REMOVE.md +0 -6
  116. package/.claude/skills/add-github/SKILL.md +0 -148
  117. package/.claude/skills/add-github/VERIFY.md +0 -3
  118. package/.claude/skills/add-gmail-tool/SKILL.md +0 -229
  119. package/.claude/skills/add-imessage/REMOVE.md +0 -6
  120. package/.claude/skills/add-imessage/SKILL.md +0 -113
  121. package/.claude/skills/add-imessage/VERIFY.md +0 -3
  122. package/.claude/skills/add-karpathy-llm-wiki/SKILL.md +0 -110
  123. package/.claude/skills/add-karpathy-llm-wiki/llm-wiki.md +0 -75
  124. package/.claude/skills/add-linear/REMOVE.md +0 -6
  125. package/.claude/skills/add-linear/SKILL.md +0 -168
  126. package/.claude/skills/add-linear/VERIFY.md +0 -3
  127. package/.claude/skills/add-macos-statusbar/SKILL.md +0 -133
  128. package/.claude/skills/add-macos-statusbar/add/src/statusbar.swift +0 -147
  129. package/.claude/skills/add-matrix/REMOVE.md +0 -6
  130. package/.claude/skills/add-matrix/SKILL.md +0 -148
  131. package/.claude/skills/add-matrix/VERIFY.md +0 -3
  132. package/.claude/skills/add-ollama-provider/SKILL.md +0 -179
  133. package/.claude/skills/add-ollama-tool/SKILL.md +0 -193
  134. package/.claude/skills/add-opencode/SKILL.md +0 -229
  135. package/.claude/skills/add-parallel/SKILL.md +0 -290
  136. package/.claude/skills/add-resend/REMOVE.md +0 -6
  137. package/.claude/skills/add-resend/SKILL.md +0 -93
  138. package/.claude/skills/add-resend/VERIFY.md +0 -3
  139. package/.claude/skills/add-signal/REMOVE.md +0 -13
  140. package/.claude/skills/add-signal/SKILL.md +0 -318
  141. package/.claude/skills/add-signal/VERIFY.md +0 -5
  142. package/.claude/skills/add-slack/REMOVE.md +0 -6
  143. package/.claude/skills/add-slack/SKILL.md +0 -112
  144. package/.claude/skills/add-slack/VERIFY.md +0 -3
  145. package/.claude/skills/add-teams/REMOVE.md +0 -6
  146. package/.claude/skills/add-teams/SKILL.md +0 -207
  147. package/.claude/skills/add-teams/VERIFY.md +0 -3
  148. package/.claude/skills/add-vercel/SKILL.md +0 -147
  149. package/.claude/skills/add-vercel/container-skills/vercel-cli/SKILL.md +0 -103
  150. package/.claude/skills/add-webex/REMOVE.md +0 -6
  151. package/.claude/skills/add-webex/SKILL.md +0 -88
  152. package/.claude/skills/add-webex/VERIFY.md +0 -3
  153. package/.claude/skills/add-wechat/REMOVE.md +0 -49
  154. package/.claude/skills/add-wechat/SKILL.md +0 -170
  155. package/.claude/skills/add-wechat/scripts/wire-dm.ts +0 -172
  156. package/.claude/skills/add-whatsapp/SKILL.md +0 -264
  157. package/.claude/skills/add-whatsapp-cloud/REMOVE.md +0 -6
  158. package/.claude/skills/add-whatsapp-cloud/SKILL.md +0 -95
  159. package/.claude/skills/add-whatsapp-cloud/VERIFY.md +0 -3
  160. package/.claude/skills/claw/SKILL.md +0 -131
  161. package/.claude/skills/claw/scripts/claw +0 -374
  162. package/.claude/skills/convert-to-apple-container/SKILL.md +0 -212
  163. package/.claude/skills/customize/SKILL.md +0 -110
  164. package/.claude/skills/debug/SKILL.md +0 -349
  165. package/.claude/skills/get-qodo-rules/SKILL.md +0 -122
  166. package/.claude/skills/get-qodo-rules/references/output-format.md +0 -41
  167. package/.claude/skills/get-qodo-rules/references/pagination.md +0 -33
  168. package/.claude/skills/get-qodo-rules/references/repository-scope.md +0 -26
  169. package/.claude/skills/init-first-agent/SKILL.md +0 -120
  170. package/.claude/skills/init-onecli/SKILL.md +0 -270
  171. package/.claude/skills/manage-channels/SKILL.md +0 -87
  172. package/.claude/skills/manage-mounts/SKILL.md +0 -47
  173. package/.claude/skills/migrate-from-openclaw/MIGRATE_CRONS.md +0 -100
  174. package/.claude/skills/migrate-from-openclaw/SKILL.md +0 -447
  175. package/.claude/skills/migrate-from-openclaw/scripts/discover-openclaw.ts +0 -734
  176. package/.claude/skills/migrate-from-openclaw/scripts/extract-channel-credentials.ts +0 -476
  177. package/.claude/skills/migrate-nanoclaw/SKILL.md +0 -484
  178. package/.claude/skills/migrate-nanoclaw/diagnostics.md +0 -51
  179. package/.claude/skills/qodo-pr-resolver/SKILL.md +0 -326
  180. package/.claude/skills/qodo-pr-resolver/resources/providers.md +0 -329
  181. package/.claude/skills/update-nanoclaw/SKILL.md +0 -243
  182. package/.claude/skills/update-nanoclaw/diagnostics.md +0 -48
  183. package/.claude/skills/update-skills/SKILL.md +0 -130
  184. package/.claude/skills/use-native-credential-proxy/SKILL.md +0 -167
  185. package/.claude/skills/x-integration/SKILL.md +0 -417
  186. package/.claude/skills/x-integration/agent.ts +0 -243
  187. package/.claude/skills/x-integration/host.ts +0 -155
  188. package/.claude/skills/x-integration/lib/browser.ts +0 -148
  189. package/.claude/skills/x-integration/lib/config.ts +0 -62
  190. package/.claude/skills/x-integration/scripts/like.ts +0 -56
  191. package/.claude/skills/x-integration/scripts/post.ts +0 -66
  192. package/.claude/skills/x-integration/scripts/quote.ts +0 -80
  193. package/.claude/skills/x-integration/scripts/reply.ts +0 -74
  194. package/.claude/skills/x-integration/scripts/retweet.ts +0 -62
  195. package/.claude/skills/x-integration/scripts/setup.ts +0 -87
  196. package/.github/CODEOWNERS +0 -10
  197. package/.github/PULL_REQUEST_TEMPLATE.md +0 -18
  198. package/.github/workflows/bump-version.yml +0 -35
  199. package/.github/workflows/ci.yml +0 -39
  200. package/.github/workflows/label-pr.yml +0 -40
  201. package/.github/workflows/update-tokens.yml +0 -43
  202. package/.husky/pre-commit +0 -1
  203. package/.mcp.json +0 -3
  204. package/.nvmrc +0 -1
  205. package/.prettierrc +0 -4
  206. package/CHANGELOG.md +0 -263
  207. package/CLAUDE.md +0 -307
  208. package/CODE_OF_CONDUCT.md +0 -128
  209. package/CONTRIBUTING.md +0 -159
  210. package/CONTRIBUTORS.md +0 -26
  211. package/LICENSE-NANOCLAW-MIT +0 -21
  212. package/README_ja.md +0 -194
  213. package/README_zh.md +0 -194
  214. package/assets/nanoclaw-favicon.png +0 -0
  215. package/assets/nanoclaw-icon.png +0 -0
  216. package/assets/nanoclaw-logo-dark.png +0 -0
  217. package/assets/nanoclaw-logo.png +0 -0
  218. package/assets/nanoclaw-profile.jpeg +0 -0
  219. package/assets/nanoclaw-sales.png +0 -0
  220. package/assets/social-preview.jpg +0 -0
  221. package/config-examples/mount-allowlist.json +0 -25
  222. package/container/.dockerignore +0 -2
  223. package/container/CLAUDE.md +0 -21
  224. package/container/Dockerfile +0 -121
  225. package/container/agent-runner/bun.lock +0 -243
  226. package/container/agent-runner/package.json +0 -22
  227. package/container/agent-runner/scripts/sdk-signal-probe.ts +0 -169
  228. package/container/agent-runner/src/config.ts +0 -55
  229. package/container/agent-runner/src/db/connection.ts +0 -267
  230. package/container/agent-runner/src/db/index.ts +0 -20
  231. package/container/agent-runner/src/db/messages-in.ts +0 -138
  232. package/container/agent-runner/src/db/messages-out.ts +0 -143
  233. package/container/agent-runner/src/db/session-routing.ts +0 -30
  234. package/container/agent-runner/src/db/session-state.test.ts +0 -100
  235. package/container/agent-runner/src/db/session-state.ts +0 -79
  236. package/container/agent-runner/src/destinations.ts +0 -135
  237. package/container/agent-runner/src/formatter.test.ts +0 -167
  238. package/container/agent-runner/src/formatter.ts +0 -260
  239. package/container/agent-runner/src/index.ts +0 -110
  240. package/container/agent-runner/src/integration.test.ts +0 -121
  241. package/container/agent-runner/src/mcp-tools/agents.instructions.md +0 -26
  242. package/container/agent-runner/src/mcp-tools/agents.ts +0 -66
  243. package/container/agent-runner/src/mcp-tools/core.instructions.md +0 -27
  244. package/container/agent-runner/src/mcp-tools/core.ts +0 -262
  245. package/container/agent-runner/src/mcp-tools/index.ts +0 -22
  246. package/container/agent-runner/src/mcp-tools/interactive.instructions.md +0 -22
  247. package/container/agent-runner/src/mcp-tools/interactive.ts +0 -169
  248. package/container/agent-runner/src/mcp-tools/scheduling.instructions.md +0 -40
  249. package/container/agent-runner/src/mcp-tools/scheduling.ts +0 -299
  250. package/container/agent-runner/src/mcp-tools/self-mod.instructions.md +0 -25
  251. package/container/agent-runner/src/mcp-tools/self-mod.ts +0 -120
  252. package/container/agent-runner/src/mcp-tools/server.ts +0 -54
  253. package/container/agent-runner/src/mcp-tools/types.ts +0 -6
  254. package/container/agent-runner/src/poll-loop.test.ts +0 -248
  255. package/container/agent-runner/src/poll-loop.ts +0 -437
  256. package/container/agent-runner/src/providers/claude.ts +0 -379
  257. package/container/agent-runner/src/providers/factory.test.ts +0 -19
  258. package/container/agent-runner/src/providers/factory.ts +0 -13
  259. package/container/agent-runner/src/providers/index.ts +0 -6
  260. package/container/agent-runner/src/providers/mock.ts +0 -77
  261. package/container/agent-runner/src/providers/provider-registry.ts +0 -33
  262. package/container/agent-runner/src/providers/types.ts +0 -82
  263. package/container/agent-runner/src/scheduling/task-script.ts +0 -121
  264. package/container/agent-runner/src/timezone.test.ts +0 -93
  265. package/container/agent-runner/src/timezone.ts +0 -107
  266. package/container/agent-runner/tsconfig.json +0 -14
  267. package/container/build.sh +0 -48
  268. package/container/entrypoint.sh +0 -16
  269. package/container/skills/agent-browser/SKILL.md +0 -159
  270. package/container/skills/frontend-engineer/SKILL.md +0 -157
  271. package/container/skills/self-customize/SKILL.md +0 -87
  272. package/container/skills/slack-formatting/SKILL.md +0 -94
  273. package/container/skills/vercel-cli/SKILL.md +0 -111
  274. package/container/skills/welcome/SKILL.md +0 -85
  275. package/docs/APPLE-CONTAINER-NETWORKING.md +0 -90
  276. package/docs/BRANCH-FORK-MAINTENANCE.md +0 -81
  277. package/docs/README.md +0 -25
  278. package/docs/SDK_DEEP_DIVE.md +0 -643
  279. package/docs/SECURITY.md +0 -162
  280. package/docs/agent-runner-details.md +0 -749
  281. package/docs/api-details.md +0 -365
  282. package/docs/architecture-diagram.html +0 -422
  283. package/docs/architecture-diagram.md +0 -215
  284. package/docs/architecture.md +0 -751
  285. package/docs/audit/2026-04-30-channel-endpoint-audit.md +0 -36
  286. package/docs/build-and-runtime.md +0 -80
  287. package/docs/cross-mount-stress/README.md +0 -112
  288. package/docs/cross-mount-stress/container-writer-retry.mjs +0 -55
  289. package/docs/cross-mount-stress/container-writer-slow.mjs +0 -42
  290. package/docs/cross-mount-stress/container-writer.mjs +0 -47
  291. package/docs/cross-mount-stress/host-writer-retry.mjs +0 -55
  292. package/docs/cross-mount-stress/host-writer-slow.mjs +0 -43
  293. package/docs/cross-mount-stress/host-writer.mjs +0 -47
  294. package/docs/db-central.md +0 -316
  295. package/docs/db-session.md +0 -183
  296. package/docs/db.md +0 -119
  297. package/docs/design/2026-04-29-vault-management-ui.md +0 -231
  298. package/docs/design/2026-04-30-channel-wiring-rework.md +0 -234
  299. package/docs/design/2026-05-01-channel-wiring-approvals-deep-dive.md +0 -272
  300. package/docs/design/2026-05-02-channel-policy-and-approval-routing.md +0 -250
  301. package/docs/docker-sandboxes.md +0 -359
  302. package/docs/isolation-model.md +0 -88
  303. package/docs/ollama.md +0 -79
  304. package/docs/parachute-integration.md +0 -109
  305. package/docs/post-night-rebirth-reflections.md +0 -151
  306. package/eslint.config.js +0 -32
  307. package/pnpm-workspace.yaml +0 -8
  308. package/repo-tokens/README.md +0 -113
  309. package/repo-tokens/action.yml +0 -186
  310. package/repo-tokens/badge.svg +0 -23
  311. package/repo-tokens/examples/green.svg +0 -14
  312. package/repo-tokens/examples/red.svg +0 -14
  313. package/repo-tokens/examples/yellow-green.svg +0 -14
  314. package/repo-tokens/examples/yellow.svg +0 -14
  315. package/scripts/chat.ts +0 -101
  316. package/scripts/cleanup-sessions.sh +0 -150
  317. package/scripts/init-cli-agent.ts +0 -172
  318. package/scripts/init-first-agent.ts +0 -378
  319. package/scripts/parachute.ts +0 -158
  320. package/scripts/run-migrations.ts +0 -105
  321. package/scripts/sanity-live-poll.ts +0 -95
  322. package/scripts/seed-discord.ts +0 -80
  323. package/scripts/test-v2-agent.ts +0 -106
  324. package/scripts/test-v2-channel-e2e.ts +0 -265
  325. package/scripts/test-v2-host.ts +0 -184
  326. package/src/channels/adapter.ts +0 -214
  327. package/src/channels/api-translator.test.ts +0 -306
  328. package/src/channels/api-translator.ts +0 -214
  329. package/src/channels/ask-question.ts +0 -46
  330. package/src/channels/channel-registry.test.ts +0 -421
  331. package/src/channels/channel-registry.ts +0 -313
  332. package/src/channels/chat-sdk-bridge.test.ts +0 -84
  333. package/src/channels/chat-sdk-bridge.ts +0 -652
  334. package/src/channels/cli.ts +0 -276
  335. package/src/channels/discord.ts +0 -90
  336. package/src/channels/index.ts +0 -17
  337. package/src/channels/telegram-markdown-sanitize.test.ts +0 -78
  338. package/src/channels/telegram-markdown-sanitize.ts +0 -55
  339. package/src/channels/telegram-pairing.test.ts +0 -254
  340. package/src/channels/telegram-pairing.ts +0 -339
  341. package/src/channels/telegram.ts +0 -279
  342. package/src/channels/trust-hint.test.ts +0 -48
  343. package/src/channels/trust-hint.ts +0 -75
  344. package/src/claude-md-compose.migrate.test.ts +0 -64
  345. package/src/claude-md-compose.ts +0 -205
  346. package/src/command-gate.ts +0 -63
  347. package/src/config.test.ts +0 -93
  348. package/src/config.ts +0 -128
  349. package/src/container-config.ts +0 -167
  350. package/src/container-runner.test.ts +0 -32
  351. package/src/container-runner.ts +0 -576
  352. package/src/container-runtime.test.ts +0 -269
  353. package/src/container-runtime.ts +0 -167
  354. package/src/db/_bun-sqlite-shim.ts +0 -88
  355. package/src/db/agent-activity.test.ts +0 -155
  356. package/src/db/agent-activity.ts +0 -121
  357. package/src/db/agent-groups.ts +0 -77
  358. package/src/db/connection.migrate.test.ts +0 -176
  359. package/src/db/connection.ts +0 -259
  360. package/src/db/db-v2.test.ts +0 -440
  361. package/src/db/dropped-messages.ts +0 -44
  362. package/src/db/index.ts +0 -40
  363. package/src/db/messaging-groups.ts +0 -252
  364. package/src/db/migrations/001-initial.ts +0 -112
  365. package/src/db/migrations/002-chat-sdk-state.ts +0 -36
  366. package/src/db/migrations/008-dropped-messages.ts +0 -27
  367. package/src/db/migrations/009-drop-pending-credentials.ts +0 -13
  368. package/src/db/migrations/010-engage-modes.ts +0 -103
  369. package/src/db/migrations/011-pending-sender-approvals.ts +0 -40
  370. package/src/db/migrations/012-channel-registration.ts +0 -48
  371. package/src/db/migrations/013-approval-render-metadata.ts +0 -27
  372. package/src/db/migrations/014-secrets.ts +0 -44
  373. package/src/db/migrations/015-secrets-drop-host-pattern.ts +0 -18
  374. package/src/db/migrations/016-secret-assignments.ts +0 -30
  375. package/src/db/migrations/017-agent-activity.ts +0 -40
  376. package/src/db/migrations/018-oauth-app-configs.ts +0 -34
  377. package/src/db/migrations/019-oauth-app-connections.ts +0 -48
  378. package/src/db/migrations/020-agent-app-connections.ts +0 -28
  379. package/src/db/migrations/021-pending-oauth-states.ts +0 -35
  380. package/src/db/migrations/022-app-connections-provider.ts +0 -25
  381. package/src/db/migrations/023-agent-group-secret-mode.test.ts +0 -124
  382. package/src/db/migrations/023-agent-group-secret-mode.ts +0 -65
  383. package/src/db/migrations/024-collapse-approvals.test.ts +0 -249
  384. package/src/db/migrations/024-collapse-approvals.ts +0 -182
  385. package/src/db/migrations/025-secret-mode-check.test.ts +0 -155
  386. package/src/db/migrations/025-secret-mode-check.ts +0 -49
  387. package/src/db/migrations/026-user-dms-bot-id.test.ts +0 -116
  388. package/src/db/migrations/026-user-dms-bot-id.ts +0 -54
  389. package/src/db/migrations/027-provider-credentials.ts +0 -41
  390. package/src/db/migrations/_test-helpers.ts +0 -41
  391. package/src/db/migrations/index.ts +0 -127
  392. package/src/db/migrations/module-agent-to-agent-destinations.ts +0 -84
  393. package/src/db/migrations/module-approvals-pending-approvals.ts +0 -42
  394. package/src/db/migrations/module-approvals-title-options.ts +0 -40
  395. package/src/db/schema.ts +0 -258
  396. package/src/db/session-db.test.ts +0 -93
  397. package/src/db/session-db.ts +0 -325
  398. package/src/db/sessions.ts +0 -241
  399. package/src/delivery.test.ts +0 -148
  400. package/src/delivery.ts +0 -445
  401. package/src/env.ts +0 -74
  402. package/src/group-folder.test.ts +0 -35
  403. package/src/group-folder.ts +0 -44
  404. package/src/group-init.ts +0 -92
  405. package/src/host-core.test.ts +0 -456
  406. package/src/host-sweep.test.ts +0 -146
  407. package/src/host-sweep.ts +0 -287
  408. package/src/index.ts +0 -232
  409. package/src/install-slug.ts +0 -33
  410. package/src/log.test.ts +0 -81
  411. package/src/log.ts +0 -117
  412. package/src/mcp/http.ts +0 -72
  413. package/src/mcp/server.ts +0 -92
  414. package/src/mcp/stdio.ts +0 -51
  415. package/src/mcp/tools/activity.ts +0 -88
  416. package/src/mcp/tools/agent-groups.ts +0 -183
  417. package/src/mcp/tools/approvals.ts +0 -122
  418. package/src/mcp/tools/channels.test.ts +0 -126
  419. package/src/mcp/tools/channels.ts +0 -134
  420. package/src/mcp/tools/index.ts +0 -27
  421. package/src/mcp/tools/oauth.ts +0 -48
  422. package/src/mcp/tools/secrets.ts +0 -169
  423. package/src/mcp/tools/sessions.ts +0 -135
  424. package/src/mcp/types.ts +0 -51
  425. package/src/modules/agent-to-agent/agent-route.test.ts +0 -46
  426. package/src/modules/agent-to-agent/agent-route.ts +0 -223
  427. package/src/modules/agent-to-agent/create-agent.ts +0 -127
  428. package/src/modules/agent-to-agent/db/agent-destinations.ts +0 -135
  429. package/src/modules/agent-to-agent/index.ts +0 -22
  430. package/src/modules/agent-to-agent/write-destinations.ts +0 -59
  431. package/src/modules/approvals/agent.md +0 -45
  432. package/src/modules/approvals/index.ts +0 -21
  433. package/src/modules/approvals/picks.test.ts +0 -291
  434. package/src/modules/approvals/primitive.ts +0 -279
  435. package/src/modules/approvals/project.md +0 -27
  436. package/src/modules/approvals/response-handler.ts +0 -87
  437. package/src/modules/index.ts +0 -24
  438. package/src/modules/interactive/agent.md +0 -21
  439. package/src/modules/interactive/index.ts +0 -69
  440. package/src/modules/interactive/project.md +0 -12
  441. package/src/modules/mount-security/expand-path.test.ts +0 -82
  442. package/src/modules/mount-security/index.ts +0 -459
  443. package/src/modules/mount-security/migrate.test.ts +0 -91
  444. package/src/modules/permissions/access.ts +0 -28
  445. package/src/modules/permissions/channel-approval.test.ts +0 -389
  446. package/src/modules/permissions/channel-approval.ts +0 -188
  447. package/src/modules/permissions/db/agent-group-members.ts +0 -44
  448. package/src/modules/permissions/db/pending-channel-approvals.test.ts +0 -86
  449. package/src/modules/permissions/db/pending-channel-approvals.ts +0 -66
  450. package/src/modules/permissions/db/pending-sender-approvals.ts +0 -60
  451. package/src/modules/permissions/db/user-dms.ts +0 -58
  452. package/src/modules/permissions/db/user-roles.ts +0 -85
  453. package/src/modules/permissions/db/users.ts +0 -38
  454. package/src/modules/permissions/index.ts +0 -421
  455. package/src/modules/permissions/permissions.test.ts +0 -358
  456. package/src/modules/permissions/sender-approval.test.ts +0 -641
  457. package/src/modules/permissions/sender-approval.ts +0 -165
  458. package/src/modules/permissions/user-dm.ts +0 -200
  459. package/src/modules/provider-credentials/db.ts +0 -121
  460. package/src/modules/provider-credentials/index.ts +0 -12
  461. package/src/modules/provider-credentials/spawn.test.ts +0 -206
  462. package/src/modules/provider-credentials/spawn.ts +0 -114
  463. package/src/modules/scheduling/actions.ts +0 -113
  464. package/src/modules/scheduling/db.test.ts +0 -282
  465. package/src/modules/scheduling/db.ts +0 -148
  466. package/src/modules/scheduling/index.ts +0 -34
  467. package/src/modules/scheduling/recurrence.test.ts +0 -98
  468. package/src/modules/scheduling/recurrence.ts +0 -54
  469. package/src/modules/self-mod/agent.md +0 -30
  470. package/src/modules/self-mod/apply.ts +0 -85
  471. package/src/modules/self-mod/index.ts +0 -30
  472. package/src/modules/self-mod/project.md +0 -39
  473. package/src/modules/self-mod/request.ts +0 -91
  474. package/src/modules/typing/index.ts +0 -165
  475. package/src/oauth/agent-app-connections.ts +0 -103
  476. package/src/oauth/app-configs.test.ts +0 -64
  477. package/src/oauth/app-configs.ts +0 -114
  478. package/src/oauth/app-connections.test.ts +0 -109
  479. package/src/oauth/app-connections.ts +0 -178
  480. package/src/oauth/crypto.ts +0 -56
  481. package/src/oauth/flow.ts +0 -104
  482. package/src/oauth/providers/google.test.ts +0 -38
  483. package/src/oauth/providers/google.ts +0 -46
  484. package/src/oauth/providers/index.ts +0 -48
  485. package/src/oauth/state-store.test.ts +0 -54
  486. package/src/oauth/state-store.ts +0 -93
  487. package/src/parachute/README.md +0 -27
  488. package/src/parachute/create-agent.test.ts +0 -83
  489. package/src/parachute/create-agent.ts +0 -122
  490. package/src/parachute/group-status.test.ts +0 -165
  491. package/src/parachute/group-status.ts +0 -136
  492. package/src/parachute/types.ts +0 -41
  493. package/src/parachute/vault-mcp.test.ts +0 -251
  494. package/src/parachute/vault-mcp.ts +0 -232
  495. package/src/platform-id.test.ts +0 -104
  496. package/src/platform-id.ts +0 -109
  497. package/src/providers/index.ts +0 -6
  498. package/src/providers/provider-container-registry.ts +0 -58
  499. package/src/response-registry.ts +0 -45
  500. package/src/router.ts +0 -530
  501. package/src/secrets/crypto.test.ts +0 -45
  502. package/src/secrets/crypto.ts +0 -55
  503. package/src/secrets/index.ts +0 -461
  504. package/src/secrets/master-key.ts +0 -70
  505. package/src/secrets/secrets.test.ts +0 -651
  506. package/src/session-manager.attachments.test.ts +0 -171
  507. package/src/session-manager.dup-skip.test.ts +0 -173
  508. package/src/session-manager.migrate.test.ts +0 -59
  509. package/src/session-manager.ts +0 -451
  510. package/src/startup-bootstrap.test.ts +0 -226
  511. package/src/startup-bootstrap.ts +0 -207
  512. package/src/state-sqlite.ts +0 -182
  513. package/src/timezone.test.ts +0 -64
  514. package/src/timezone.ts +0 -37
  515. package/src/types.ts +0 -233
  516. package/src/web/auth.test.ts +0 -335
  517. package/src/web/auth.ts +0 -214
  518. package/src/web/discord-validate.test.ts +0 -77
  519. package/src/web/discord-validate.ts +0 -88
  520. package/src/web/hub-discovery.test.ts +0 -98
  521. package/src/web/hub-discovery.ts +0 -69
  522. package/src/web/routes/activity.ts +0 -106
  523. package/src/web/routes/agent-provider.test.ts +0 -282
  524. package/src/web/routes/agent-provider.ts +0 -309
  525. package/src/web/routes/approvals.ts +0 -185
  526. package/src/web/routes/apps.ts +0 -434
  527. package/src/web/routes/channels-mg-detail.test.ts +0 -324
  528. package/src/web/routes/channels-mga-detail.test.ts +0 -472
  529. package/src/web/routes/channels.ts +0 -311
  530. package/src/web/routes/oauth-providers.ts +0 -42
  531. package/src/web/routes/secrets.test.ts +0 -220
  532. package/src/web/routes/secrets.ts +0 -317
  533. package/src/web/routes/sessions.ts +0 -123
  534. package/src/web/routes/settings.test.ts +0 -106
  535. package/src/web/routes/settings.ts +0 -247
  536. package/src/web/routes/setup-status.ts +0 -205
  537. package/src/web/routes/vaults.test.ts +0 -389
  538. package/src/web/routes/vaults.ts +0 -225
  539. package/src/web/server-version.test.ts +0 -16
  540. package/src/web/server.ts +0 -1024
  541. package/src/web/services-manifest.test.ts +0 -148
  542. package/src/web/services-manifest.ts +0 -66
  543. package/src/web/static-serve.test.ts +0 -255
  544. package/src/web/static-serve.ts +0 -104
  545. package/src/web/telegram-validate.test.ts +0 -116
  546. package/src/web/telegram-validate.ts +0 -107
  547. package/src/web/vault-proxy.test.ts +0 -214
  548. package/src/web/vault-proxy.ts +0 -120
  549. package/src/web/wire-channel.ts +0 -181
  550. package/src/webhook-server.ts +0 -134
  551. package/vitest.config.ts +0 -18
  552. package/web/README.md +0 -63
  553. package/web/ui/index.html +0 -13
  554. package/web/ui/package.json +0 -35
  555. package/web/ui/pnpm-lock.yaml +0 -2164
  556. package/web/ui/scripts/verify-base.mjs +0 -31
  557. package/web/ui/src/App.tsx +0 -88
  558. package/web/ui/src/components/ActivityFeed.tsx +0 -444
  559. package/web/ui/src/components/AgentGroupPicker.tsx +0 -263
  560. package/web/ui/src/components/AgentProviderCards.tsx +0 -220
  561. package/web/ui/src/components/CredentialForm.tsx +0 -214
  562. package/web/ui/src/components/ScopeGrants.tsx +0 -74
  563. package/web/ui/src/components/StatusDot.tsx +0 -43
  564. package/web/ui/src/components/VaultPicker.tsx +0 -127
  565. package/web/ui/src/components/setup/AdapterInstallStep.tsx +0 -178
  566. package/web/ui/src/components/setup/AgentGroupStep.tsx +0 -43
  567. package/web/ui/src/components/setup/ChannelPickStep.tsx +0 -74
  568. package/web/ui/src/components/setup/DoneStep.tsx +0 -49
  569. package/web/ui/src/components/setup/PrereqStep.tsx +0 -129
  570. package/web/ui/src/components/setup/TestConnectionStep.tsx +0 -108
  571. package/web/ui/src/components/setup/TestMessageStep.tsx +0 -104
  572. package/web/ui/src/components/setup/WireChannelStep.tsx +0 -166
  573. package/web/ui/src/components/setup/types.ts +0 -105
  574. package/web/ui/src/lib/api.test.ts +0 -410
  575. package/web/ui/src/lib/api.ts +0 -1248
  576. package/web/ui/src/lib/auth.test.ts +0 -352
  577. package/web/ui/src/lib/auth.ts +0 -405
  578. package/web/ui/src/lib/channel-adapters.ts +0 -136
  579. package/web/ui/src/main.tsx +0 -19
  580. package/web/ui/src/routes/ApprovalsList.tsx +0 -294
  581. package/web/ui/src/routes/Apps.tsx +0 -613
  582. package/web/ui/src/routes/ChannelWireDetail.test.tsx +0 -233
  583. package/web/ui/src/routes/ChannelWireDetail.tsx +0 -403
  584. package/web/ui/src/routes/ChannelsList.tsx +0 -158
  585. package/web/ui/src/routes/GroupDetail.test.tsx +0 -206
  586. package/web/ui/src/routes/GroupDetail.tsx +0 -880
  587. package/web/ui/src/routes/GroupList.tsx +0 -187
  588. package/web/ui/src/routes/MessagingGroupDetail.test.tsx +0 -233
  589. package/web/ui/src/routes/MessagingGroupDetail.tsx +0 -306
  590. package/web/ui/src/routes/NewGroupWizard.tsx +0 -390
  591. package/web/ui/src/routes/OAuthCallback.tsx +0 -56
  592. package/web/ui/src/routes/SecretsList.tsx +0 -942
  593. package/web/ui/src/routes/SessionsList.tsx +0 -220
  594. package/web/ui/src/routes/SettingsAgentProvider.tsx +0 -109
  595. package/web/ui/src/routes/SettingsApprovals.tsx +0 -234
  596. package/web/ui/src/routes/SetupWizard.tsx +0 -219
  597. package/web/ui/src/routes/VaultDetail.test.tsx +0 -363
  598. package/web/ui/src/routes/VaultDetail.tsx +0 -960
  599. package/web/ui/src/routes/VaultsList.tsx +0 -295
  600. package/web/ui/src/routes/WireChannelPage.tsx +0 -413
  601. package/web/ui/src/styles.css +0 -608
  602. package/web/ui/src/test/setup.ts +0 -23
  603. package/web/ui/src/vite-env.d.ts +0 -10
  604. package/web/ui/vite.config.ts +0 -34
  605. 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
- ```