clawdbot 2026.1.4

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 (503) hide show
  1. package/CHANGELOG.md +115 -0
  2. package/LICENSE +21 -0
  3. package/README-header.png +0 -0
  4. package/README.md +297 -0
  5. package/dist/agents/agent-paths.js +17 -0
  6. package/dist/agents/bash-process-registry.js +126 -0
  7. package/dist/agents/bash-tools.js +837 -0
  8. package/dist/agents/clawdbot-tools.js +30 -0
  9. package/dist/agents/clawdis-tools.js +27 -0
  10. package/dist/agents/context.js +34 -0
  11. package/dist/agents/defaults.js +6 -0
  12. package/dist/agents/model-auth.js +112 -0
  13. package/dist/agents/model-catalog.js +55 -0
  14. package/dist/agents/model-fallback.js +191 -0
  15. package/dist/agents/model-scan.js +263 -0
  16. package/dist/agents/model-selection.js +116 -0
  17. package/dist/agents/models-config.js +49 -0
  18. package/dist/agents/pi-embedded-helpers.js +74 -0
  19. package/dist/agents/pi-embedded-runner.js +407 -0
  20. package/dist/agents/pi-embedded-subscribe.js +568 -0
  21. package/dist/agents/pi-embedded-utils.js +20 -0
  22. package/dist/agents/pi-embedded.js +1 -0
  23. package/dist/agents/pi-oauth.js +88 -0
  24. package/dist/agents/pi-tools.js +433 -0
  25. package/dist/agents/sandbox-paths.js +68 -0
  26. package/dist/agents/sandbox.js +644 -0
  27. package/dist/agents/shell-utils.js +53 -0
  28. package/dist/agents/skills-install.js +244 -0
  29. package/dist/agents/skills-status.js +157 -0
  30. package/dist/agents/skills.js +470 -0
  31. package/dist/agents/steerable-agent-loop.js +338 -0
  32. package/dist/agents/steerable-provider-transport.js +48 -0
  33. package/dist/agents/system-prompt.js +104 -0
  34. package/dist/agents/tool-display.js +162 -0
  35. package/dist/agents/tool-images.js +138 -0
  36. package/dist/agents/tools/browser-tool.js +339 -0
  37. package/dist/agents/tools/canvas-tool.js +193 -0
  38. package/dist/agents/tools/common.js +88 -0
  39. package/dist/agents/tools/cron-tool.js +124 -0
  40. package/dist/agents/tools/discord-actions-guild.js +186 -0
  41. package/dist/agents/tools/discord-actions-messaging.js +285 -0
  42. package/dist/agents/tools/discord-actions-moderation.js +70 -0
  43. package/dist/agents/tools/discord-actions.js +56 -0
  44. package/dist/agents/tools/discord-schema.js +199 -0
  45. package/dist/agents/tools/discord-tool.js +16 -0
  46. package/dist/agents/tools/gateway-tool.js +46 -0
  47. package/dist/agents/tools/gateway.js +27 -0
  48. package/dist/agents/tools/image-tool.js +132 -0
  49. package/dist/agents/tools/nodes-tool.js +413 -0
  50. package/dist/agents/tools/nodes-utils.js +92 -0
  51. package/dist/agents/tools/sessions-helpers.js +88 -0
  52. package/dist/agents/tools/sessions-history-tool.js +53 -0
  53. package/dist/agents/tools/sessions-list-tool.js +143 -0
  54. package/dist/agents/tools/sessions-send-helpers.js +100 -0
  55. package/dist/agents/tools/sessions-send-tool.js +347 -0
  56. package/dist/agents/tools/slack-actions.js +129 -0
  57. package/dist/agents/tools/slack-schema.js +59 -0
  58. package/dist/agents/tools/slack-tool.js +16 -0
  59. package/dist/agents/usage.js +39 -0
  60. package/dist/agents/workspace.js +241 -0
  61. package/dist/auto-reply/chunk.js +76 -0
  62. package/dist/auto-reply/envelope.js +38 -0
  63. package/dist/auto-reply/group-activation.js +20 -0
  64. package/dist/auto-reply/heartbeat.js +57 -0
  65. package/dist/auto-reply/model.js +14 -0
  66. package/dist/auto-reply/reply/abort.js +14 -0
  67. package/dist/auto-reply/reply/agent-runner.js +371 -0
  68. package/dist/auto-reply/reply/block-streaming.js +34 -0
  69. package/dist/auto-reply/reply/body.js +29 -0
  70. package/dist/auto-reply/reply/commands.js +207 -0
  71. package/dist/auto-reply/reply/directive-handling.js +361 -0
  72. package/dist/auto-reply/reply/directives.js +47 -0
  73. package/dist/auto-reply/reply/followup-runner.js +149 -0
  74. package/dist/auto-reply/reply/groups.js +91 -0
  75. package/dist/auto-reply/reply/mentions.js +38 -0
  76. package/dist/auto-reply/reply/model-selection.js +114 -0
  77. package/dist/auto-reply/reply/queue.js +399 -0
  78. package/dist/auto-reply/reply/reply-tags.js +26 -0
  79. package/dist/auto-reply/reply/session-updates.js +87 -0
  80. package/dist/auto-reply/reply/session.js +160 -0
  81. package/dist/auto-reply/reply/typing.js +75 -0
  82. package/dist/auto-reply/reply.js +535 -0
  83. package/dist/auto-reply/send-policy.js +28 -0
  84. package/dist/auto-reply/status.js +158 -0
  85. package/dist/auto-reply/templating.js +9 -0
  86. package/dist/auto-reply/thinking.js +49 -0
  87. package/dist/auto-reply/tokens.js +2 -0
  88. package/dist/auto-reply/tool-meta.js +74 -0
  89. package/dist/auto-reply/transcription.js +57 -0
  90. package/dist/auto-reply/types.js +1 -0
  91. package/dist/browser/bridge-server.js +37 -0
  92. package/dist/browser/cdp.js +382 -0
  93. package/dist/browser/chrome.js +432 -0
  94. package/dist/browser/client-actions-core.js +67 -0
  95. package/dist/browser/client-actions-observe.js +24 -0
  96. package/dist/browser/client-actions-types.js +1 -0
  97. package/dist/browser/client-actions.js +3 -0
  98. package/dist/browser/client-fetch.js +43 -0
  99. package/dist/browser/client.js +105 -0
  100. package/dist/browser/config.js +140 -0
  101. package/dist/browser/constants.js +4 -0
  102. package/dist/browser/profiles-service.js +122 -0
  103. package/dist/browser/profiles.js +85 -0
  104. package/dist/browser/pw-ai.js +2 -0
  105. package/dist/browser/pw-session.js +144 -0
  106. package/dist/browser/pw-tools-core.js +363 -0
  107. package/dist/browser/routes/agent.js +535 -0
  108. package/dist/browser/routes/basic.js +155 -0
  109. package/dist/browser/routes/index.js +8 -0
  110. package/dist/browser/routes/tabs.js +105 -0
  111. package/dist/browser/routes/utils.js +62 -0
  112. package/dist/browser/screenshot.js +40 -0
  113. package/dist/browser/server-context.js +377 -0
  114. package/dist/browser/server.js +81 -0
  115. package/dist/browser/target-id.js +18 -0
  116. package/dist/browser/trash.js +21 -0
  117. package/dist/canvas-host/a2ui/.bundle.hash +1 -0
  118. package/dist/canvas-host/a2ui/a2ui.bundle.js +17768 -0
  119. package/dist/canvas-host/a2ui/index.html +246 -0
  120. package/dist/canvas-host/a2ui.js +187 -0
  121. package/dist/canvas-host/server.js +382 -0
  122. package/dist/cli/browser-cli-actions-input.js +459 -0
  123. package/dist/cli/browser-cli-actions-observe.js +56 -0
  124. package/dist/cli/browser-cli-examples.js +31 -0
  125. package/dist/cli/browser-cli-inspect.js +97 -0
  126. package/dist/cli/browser-cli-manage.js +286 -0
  127. package/dist/cli/browser-cli-shared.js +1 -0
  128. package/dist/cli/browser-cli.js +26 -0
  129. package/dist/cli/canvas-cli.js +416 -0
  130. package/dist/cli/cron-cli.js +454 -0
  131. package/dist/cli/deps.js +17 -0
  132. package/dist/cli/dns-cli.js +180 -0
  133. package/dist/cli/gateway-cli.js +489 -0
  134. package/dist/cli/gateway-rpc.js +20 -0
  135. package/dist/cli/hooks-cli.js +135 -0
  136. package/dist/cli/models-cli.js +248 -0
  137. package/dist/cli/nodes-camera.js +57 -0
  138. package/dist/cli/nodes-canvas.js +26 -0
  139. package/dist/cli/nodes-cli.js +946 -0
  140. package/dist/cli/nodes-screen.js +37 -0
  141. package/dist/cli/parse-duration.js +20 -0
  142. package/dist/cli/ports.js +97 -0
  143. package/dist/cli/program.js +406 -0
  144. package/dist/cli/prompt.js +19 -0
  145. package/dist/cli/tui-cli.js +35 -0
  146. package/dist/cli/wait.js +8 -0
  147. package/dist/commands/agent.js +645 -0
  148. package/dist/commands/antigravity-oauth.js +327 -0
  149. package/dist/commands/configure.js +480 -0
  150. package/dist/commands/doctor.js +484 -0
  151. package/dist/commands/health.js +108 -0
  152. package/dist/commands/models/aliases.js +64 -0
  153. package/dist/commands/models/fallbacks.js +99 -0
  154. package/dist/commands/models/image-fallbacks.js +99 -0
  155. package/dist/commands/models/list.js +323 -0
  156. package/dist/commands/models/scan.js +266 -0
  157. package/dist/commands/models/set-image.js +23 -0
  158. package/dist/commands/models/set.js +23 -0
  159. package/dist/commands/models/shared.js +72 -0
  160. package/dist/commands/models.js +7 -0
  161. package/dist/commands/onboard-auth.js +70 -0
  162. package/dist/commands/onboard-helpers.js +295 -0
  163. package/dist/commands/onboard-interactive.js +17 -0
  164. package/dist/commands/onboard-non-interactive.js +202 -0
  165. package/dist/commands/onboard-providers.js +634 -0
  166. package/dist/commands/onboard-remote.js +120 -0
  167. package/dist/commands/onboard-skills.js +148 -0
  168. package/dist/commands/onboard-types.js +1 -0
  169. package/dist/commands/onboard.js +12 -0
  170. package/dist/commands/send.js +124 -0
  171. package/dist/commands/sessions.js +212 -0
  172. package/dist/commands/setup.js +58 -0
  173. package/dist/commands/signal-install.js +135 -0
  174. package/dist/commands/status.js +207 -0
  175. package/dist/commands/update.js +16 -0
  176. package/dist/config/config.js +6 -0
  177. package/dist/config/defaults.js +61 -0
  178. package/dist/config/io.js +147 -0
  179. package/dist/config/legacy-migrate.js +13 -0
  180. package/dist/config/legacy.js +159 -0
  181. package/dist/config/paths.js +71 -0
  182. package/dist/config/schema.js +150 -0
  183. package/dist/config/sessions.js +282 -0
  184. package/dist/config/talk.js +31 -0
  185. package/dist/config/types.js +1 -0
  186. package/dist/config/validation.js +29 -0
  187. package/dist/config/zod-schema.js +831 -0
  188. package/dist/cron/isolated-agent.js +499 -0
  189. package/dist/cron/run-log.js +72 -0
  190. package/dist/cron/schedule.js +24 -0
  191. package/dist/cron/service.js +471 -0
  192. package/dist/cron/store.js +43 -0
  193. package/dist/cron/types.js +1 -0
  194. package/dist/discord/index.js +2 -0
  195. package/dist/discord/monitor.js +1188 -0
  196. package/dist/discord/probe.js +54 -0
  197. package/dist/discord/send.js +577 -0
  198. package/dist/discord/token.js +8 -0
  199. package/dist/gateway/auth.js +121 -0
  200. package/dist/gateway/call.js +94 -0
  201. package/dist/gateway/chat-attachments.js +41 -0
  202. package/dist/gateway/client.js +180 -0
  203. package/dist/gateway/config-reload.js +274 -0
  204. package/dist/gateway/control-ui.js +184 -0
  205. package/dist/gateway/hooks-mapping.js +282 -0
  206. package/dist/gateway/hooks.js +168 -0
  207. package/dist/gateway/net.js +29 -0
  208. package/dist/gateway/protocol/index.js +61 -0
  209. package/dist/gateway/protocol/schema.js +560 -0
  210. package/dist/gateway/server-bridge-subscriptions.js +93 -0
  211. package/dist/gateway/server-bridge.js +1013 -0
  212. package/dist/gateway/server-browser.js +12 -0
  213. package/dist/gateway/server-chat.js +159 -0
  214. package/dist/gateway/server-constants.js +8 -0
  215. package/dist/gateway/server-discovery.js +62 -0
  216. package/dist/gateway/server-http.js +165 -0
  217. package/dist/gateway/server-methods/agent-job.js +125 -0
  218. package/dist/gateway/server-methods/agent.js +250 -0
  219. package/dist/gateway/server-methods/chat.js +200 -0
  220. package/dist/gateway/server-methods/config.js +50 -0
  221. package/dist/gateway/server-methods/connect.js +6 -0
  222. package/dist/gateway/server-methods/cron.js +83 -0
  223. package/dist/gateway/server-methods/health.js +28 -0
  224. package/dist/gateway/server-methods/models.js +16 -0
  225. package/dist/gateway/server-methods/nodes.js +294 -0
  226. package/dist/gateway/server-methods/providers.js +217 -0
  227. package/dist/gateway/server-methods/send.js +166 -0
  228. package/dist/gateway/server-methods/sessions.js +305 -0
  229. package/dist/gateway/server-methods/skills.js +83 -0
  230. package/dist/gateway/server-methods/system.js +118 -0
  231. package/dist/gateway/server-methods/talk.js +22 -0
  232. package/dist/gateway/server-methods/types.js +1 -0
  233. package/dist/gateway/server-methods/voicewake.js +30 -0
  234. package/dist/gateway/server-methods/web.js +58 -0
  235. package/dist/gateway/server-methods/wizard.js +100 -0
  236. package/dist/gateway/server-methods.js +53 -0
  237. package/dist/gateway/server-providers.js +644 -0
  238. package/dist/gateway/server-shared.js +1 -0
  239. package/dist/gateway/server-utils.js +35 -0
  240. package/dist/gateway/server.js +1437 -0
  241. package/dist/gateway/session-utils.js +216 -0
  242. package/dist/gateway/ws-log.js +349 -0
  243. package/dist/gateway/ws-logging.js +8 -0
  244. package/dist/globals.js +41 -0
  245. package/dist/hooks/gmail-ops.js +236 -0
  246. package/dist/hooks/gmail-setup-utils.js +278 -0
  247. package/dist/hooks/gmail-watcher.js +175 -0
  248. package/dist/hooks/gmail.js +177 -0
  249. package/dist/index.js +50 -0
  250. package/dist/infra/agent-events.js +46 -0
  251. package/dist/infra/binaries.js +9 -0
  252. package/dist/infra/bonjour-discovery.js +163 -0
  253. package/dist/infra/bonjour.js +200 -0
  254. package/dist/infra/bridge/server.js +562 -0
  255. package/dist/infra/canvas-host-url.js +54 -0
  256. package/dist/infra/env.js +8 -0
  257. package/dist/infra/errors.js +28 -0
  258. package/dist/infra/gateway-lock.js +8 -0
  259. package/dist/infra/heartbeat-events.js +21 -0
  260. package/dist/infra/heartbeat-runner.js +453 -0
  261. package/dist/infra/heartbeat-wake.js +61 -0
  262. package/dist/infra/is-main.js +37 -0
  263. package/dist/infra/machine-name.js +40 -0
  264. package/dist/infra/node-pairing.js +211 -0
  265. package/dist/infra/pam.js +42 -0
  266. package/dist/infra/path-env.js +92 -0
  267. package/dist/infra/ports.js +87 -0
  268. package/dist/infra/provider-summary.js +80 -0
  269. package/dist/infra/restart.js +29 -0
  270. package/dist/infra/retry.js +16 -0
  271. package/dist/infra/runtime-guard.js +59 -0
  272. package/dist/infra/system-events.js +44 -0
  273. package/dist/infra/system-presence.js +216 -0
  274. package/dist/infra/tailnet.js +46 -0
  275. package/dist/infra/tailscale.js +149 -0
  276. package/dist/infra/voicewake.js +77 -0
  277. package/dist/infra/widearea-dns.js +123 -0
  278. package/dist/infra/ws.js +13 -0
  279. package/dist/logger.js +52 -0
  280. package/dist/logging.js +490 -0
  281. package/dist/macos/gateway-daemon.js +141 -0
  282. package/dist/macos/relay.js +46 -0
  283. package/dist/media/constants.js +33 -0
  284. package/dist/media/host.js +42 -0
  285. package/dist/media/image-ops.js +121 -0
  286. package/dist/media/mime.js +115 -0
  287. package/dist/media/parse.js +81 -0
  288. package/dist/media/server.js +64 -0
  289. package/dist/media/store.js +139 -0
  290. package/dist/process/command-queue.js +97 -0
  291. package/dist/process/exec.js +75 -0
  292. package/dist/protocol.schema.json +2918 -0
  293. package/dist/provider-web.js +8 -0
  294. package/dist/providers/web/index.js +2 -0
  295. package/dist/runtime.js +8 -0
  296. package/dist/telegram/bot.js +394 -0
  297. package/dist/telegram/download.js +34 -0
  298. package/dist/telegram/index.js +4 -0
  299. package/dist/telegram/monitor.js +47 -0
  300. package/dist/telegram/probe.js +63 -0
  301. package/dist/telegram/proxy.js +9 -0
  302. package/dist/telegram/send.js +138 -0
  303. package/dist/telegram/token.js +30 -0
  304. package/dist/telegram/webhook-set.js +12 -0
  305. package/dist/telegram/webhook.js +56 -0
  306. package/dist/utils.js +133 -0
  307. package/dist/version.js +18 -0
  308. package/dist/web/active-listener.js +7 -0
  309. package/dist/web/auto-reply.js +1203 -0
  310. package/dist/web/inbound.js +481 -0
  311. package/dist/web/login-qr.js +204 -0
  312. package/dist/web/login.js +59 -0
  313. package/dist/web/media.js +148 -0
  314. package/dist/web/outbound.js +67 -0
  315. package/dist/web/qr-image.js +97 -0
  316. package/dist/web/reconnect.js +60 -0
  317. package/dist/web/reply-heartbeat-wake.js +61 -0
  318. package/dist/web/session.js +346 -0
  319. package/docs/AGENTS.default.md +116 -0
  320. package/docs/CNAME +1 -0
  321. package/docs/RELEASING.md +64 -0
  322. package/docs/_config.yml +51 -0
  323. package/docs/_layouts/default.html +145 -0
  324. package/docs/agent-send.md +21 -0
  325. package/docs/agent.md +104 -0
  326. package/docs/android/connect.md +131 -0
  327. package/docs/architecture.md +89 -0
  328. package/docs/assets/markdown.css +130 -0
  329. package/docs/assets/pixel-lobster.svg +60 -0
  330. package/docs/assets/terminal.css +497 -0
  331. package/docs/assets/theme.js +55 -0
  332. package/docs/audio.md +50 -0
  333. package/docs/background-process.md +74 -0
  334. package/docs/bash.md +32 -0
  335. package/docs/bonjour.md +159 -0
  336. package/docs/browser.md +289 -0
  337. package/docs/camera.md +152 -0
  338. package/docs/clawd.md +199 -0
  339. package/docs/clawdbot-mac.md +104 -0
  340. package/docs/configuration.md +1177 -0
  341. package/docs/control-api.md +49 -0
  342. package/docs/control-ui.md +83 -0
  343. package/docs/cron.md +374 -0
  344. package/docs/dashboard.md +17 -0
  345. package/docs/device-models.md +46 -0
  346. package/docs/discord.md +293 -0
  347. package/docs/discovery.md +112 -0
  348. package/docs/docker.md +251 -0
  349. package/docs/docs.json +86 -0
  350. package/docs/doctor.md +47 -0
  351. package/docs/elevated.md +31 -0
  352. package/docs/faq.md +640 -0
  353. package/docs/gateway/pairing.md +109 -0
  354. package/docs/gateway-lock.md +28 -0
  355. package/docs/gateway.md +174 -0
  356. package/docs/gmail-pubsub.md +191 -0
  357. package/docs/grammy.md +27 -0
  358. package/docs/group-messages.md +71 -0
  359. package/docs/groups.md +78 -0
  360. package/docs/health.md +28 -0
  361. package/docs/heartbeat.md +64 -0
  362. package/docs/images.md +52 -0
  363. package/docs/imessage.md +63 -0
  364. package/docs/index.md +182 -0
  365. package/docs/ios/connect.md +177 -0
  366. package/docs/ios/spec.md +236 -0
  367. package/docs/location-command.md +95 -0
  368. package/docs/logging.md +99 -0
  369. package/docs/lore.md +131 -0
  370. package/docs/mac/bun.md +133 -0
  371. package/docs/mac/canvas.md +161 -0
  372. package/docs/mac/child-process.md +72 -0
  373. package/docs/mac/dev-setup.md +81 -0
  374. package/docs/mac/health.md +28 -0
  375. package/docs/mac/icon.md +26 -0
  376. package/docs/mac/logging.md +51 -0
  377. package/docs/mac/menu-bar.md +69 -0
  378. package/docs/mac/peekaboo.md +170 -0
  379. package/docs/mac/permissions.md +40 -0
  380. package/docs/mac/release.md +76 -0
  381. package/docs/mac/remote.md +57 -0
  382. package/docs/mac/signing.md +41 -0
  383. package/docs/mac/skills.md +27 -0
  384. package/docs/mac/voice-overlay.md +52 -0
  385. package/docs/mac/voicewake.md +56 -0
  386. package/docs/mac/webchat.md +27 -0
  387. package/docs/mac/xpc.md +40 -0
  388. package/docs/models.md +90 -0
  389. package/docs/nix.md +49 -0
  390. package/docs/nodes.md +157 -0
  391. package/docs/onboarding-config-protocol.md +29 -0
  392. package/docs/onboarding.md +185 -0
  393. package/docs/presence.md +133 -0
  394. package/docs/queue.md +78 -0
  395. package/docs/refactor/browser-control-simplification.md +58 -0
  396. package/docs/refactor/canvas-a2ui.md +93 -0
  397. package/docs/refactor/cli-unification.md +64 -0
  398. package/docs/refactor/gateway-client.md +31 -0
  399. package/docs/refactor/gateway.md +99 -0
  400. package/docs/refactor/new-arch.md +171 -0
  401. package/docs/refactor/tui.md +26 -0
  402. package/docs/refactor/web-gateway-troubleshooting.md +37 -0
  403. package/docs/refactor/webagent-session.md +46 -0
  404. package/docs/remote-gateway-readme.md +148 -0
  405. package/docs/remote.md +66 -0
  406. package/docs/research/memory.md +227 -0
  407. package/docs/rpc.md +35 -0
  408. package/docs/security.md +168 -0
  409. package/docs/session-tool.md +119 -0
  410. package/docs/session.md +84 -0
  411. package/docs/sessions.md +8 -0
  412. package/docs/setup.md +118 -0
  413. package/docs/signal.md +113 -0
  414. package/docs/skills-config.md +58 -0
  415. package/docs/skills.md +149 -0
  416. package/docs/slack.md +158 -0
  417. package/docs/surface.md +20 -0
  418. package/docs/tailscale.md +71 -0
  419. package/docs/talk.md +79 -0
  420. package/docs/telegram.md +90 -0
  421. package/docs/templates/AGENTS.md +126 -0
  422. package/docs/templates/BOOTSTRAP.md +53 -0
  423. package/docs/templates/IDENTITY.md +17 -0
  424. package/docs/templates/SOUL.md +41 -0
  425. package/docs/templates/TOOLS.md +41 -0
  426. package/docs/templates/USER.md +22 -0
  427. package/docs/test.md +35 -0
  428. package/docs/thinking.md +46 -0
  429. package/docs/tools.md +248 -0
  430. package/docs/troubleshooting.md +227 -0
  431. package/docs/tui.md +69 -0
  432. package/docs/typebox.md +42 -0
  433. package/docs/voicewake.md +61 -0
  434. package/docs/web.md +115 -0
  435. package/docs/webchat.md +34 -0
  436. package/docs/webhook.md +132 -0
  437. package/docs/whatsapp-clawd.jpg +0 -0
  438. package/docs/whatsapp.md +142 -0
  439. package/docs/wizard.md +158 -0
  440. package/package.json +178 -0
  441. package/skills/apple-notes/SKILL.md +50 -0
  442. package/skills/apple-reminders/SKILL.md +67 -0
  443. package/skills/bear-notes/SKILL.md +79 -0
  444. package/skills/bird/SKILL.md +25 -0
  445. package/skills/blogwatcher/SKILL.md +46 -0
  446. package/skills/blucli/SKILL.md +27 -0
  447. package/skills/brave-search/SKILL.md +30 -0
  448. package/skills/brave-search/scripts/content.mjs +53 -0
  449. package/skills/brave-search/scripts/search.mjs +79 -0
  450. package/skills/camsnap/SKILL.md +25 -0
  451. package/skills/clawdhub/SKILL.md +53 -0
  452. package/skills/coding-agent/SKILL.md +275 -0
  453. package/skills/discord/SKILL.md +369 -0
  454. package/skills/eightctl/SKILL.md +29 -0
  455. package/skills/food-order/SKILL.md +41 -0
  456. package/skills/gemini/SKILL.md +23 -0
  457. package/skills/gifgrep/SKILL.md +47 -0
  458. package/skills/github/SKILL.md +47 -0
  459. package/skills/gog/SKILL.md +36 -0
  460. package/skills/goplaces/SKILL.md +30 -0
  461. package/skills/imsg/SKILL.md +25 -0
  462. package/skills/local-places/SERVER_README.md +101 -0
  463. package/skills/local-places/SKILL.md +91 -0
  464. package/skills/local-places/pyproject.toml +27 -0
  465. package/skills/local-places/src/local_places/__init__.py +2 -0
  466. package/skills/local-places/src/local_places/__pycache__/__init__.cpython-314.pyc +0 -0
  467. package/skills/local-places/src/local_places/__pycache__/google_places.cpython-314.pyc +0 -0
  468. package/skills/local-places/src/local_places/__pycache__/main.cpython-314.pyc +0 -0
  469. package/skills/local-places/src/local_places/__pycache__/schemas.cpython-314.pyc +0 -0
  470. package/skills/local-places/src/local_places/google_places.py +314 -0
  471. package/skills/local-places/src/local_places/main.py +65 -0
  472. package/skills/local-places/src/local_places/schemas.py +107 -0
  473. package/skills/mcporter/SKILL.md +38 -0
  474. package/skills/nano-banana-pro/SKILL.md +29 -0
  475. package/skills/nano-banana-pro/scripts/generate_image.py +167 -0
  476. package/skills/nano-pdf/SKILL.md +20 -0
  477. package/skills/notion/SKILL.md +156 -0
  478. package/skills/obsidian/SKILL.md +55 -0
  479. package/skills/openai-image-gen/SKILL.md +31 -0
  480. package/skills/openai-image-gen/scripts/gen.py +173 -0
  481. package/skills/openai-whisper/SKILL.md +19 -0
  482. package/skills/openai-whisper-api/SKILL.md +43 -0
  483. package/skills/openai-whisper-api/scripts/transcribe.sh +85 -0
  484. package/skills/openhue/SKILL.md +30 -0
  485. package/skills/oracle/SKILL.md +105 -0
  486. package/skills/ordercli/SKILL.md +47 -0
  487. package/skills/peekaboo/SKILL.md +153 -0
  488. package/skills/qmd/SKILL.md +26 -0
  489. package/skills/sag/SKILL.md +62 -0
  490. package/skills/slack/SKILL.md +143 -0
  491. package/skills/songsee/SKILL.md +29 -0
  492. package/skills/sonoscli/SKILL.md +26 -0
  493. package/skills/spotify-player/SKILL.md +34 -0
  494. package/skills/summarize/SKILL.md +49 -0
  495. package/skills/things-mac/SKILL.md +61 -0
  496. package/skills/tmux/SKILL.md +121 -0
  497. package/skills/tmux/scripts/find-sessions.sh +112 -0
  498. package/skills/tmux/scripts/wait-for-text.sh +83 -0
  499. package/skills/trello/SKILL.md +84 -0
  500. package/skills/video-frames/SKILL.md +29 -0
  501. package/skills/video-frames/scripts/frame.sh +81 -0
  502. package/skills/wacli/SKILL.md +42 -0
  503. package/skills/weather/SKILL.md +49 -0
package/docs/_layouts/default.html ADDED
@@ -0,0 +1,145 @@
1
+ <!doctype html>
2
+ <html lang="en" data-theme="auto">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <meta name="color-scheme" content="light dark" />
7
+ <title>
8
+ {% if page.url == "/" %}{{ site.title }}{% else %}{{ page.title | default: page.path | split: "/" | last | replace: ".md", "" }} · {{ site.title }}{% endif %}
9
+ </title>
10
+
11
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
12
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
13
+ <link
14
+ href="https://fonts.googleapis.com/css2?family=Pixelify+Sans:wght@400..700&family=Fragment+Mono:ital,wght@0,400;0,700;1,400;1,700&display=swap"
15
+ rel="stylesheet"
16
+ />
17
+ <script>
18
+ (() => {
19
+ try {
20
+ const stored = localStorage.getItem("clawdbot:theme");
21
+ if (stored === "light" || stored === "dark") document.documentElement.dataset.theme = stored;
22
+ } catch {
23
+ // ignore
24
+ }
25
+ })();
26
+ </script>
27
+ <link rel="stylesheet" href="{{ "/assets/terminal.css" | relative_url }}" />
28
+ <link rel="stylesheet" href="{{ "/assets/markdown.css" | relative_url }}" />
29
+ <script defer src="{{ "/assets/theme.js" | relative_url }}"></script>
30
+ </head>
31
+
32
+ <body>
33
+ <a class="skip-link" href="#content">Skip to content</a>
34
+
35
+ <header class="shell">
36
+ <div class="shell__frame" role="banner">
37
+ <div class="shell__titlebar">
38
+ <div class="brand" aria-label="CLAWDBOT docs terminal">
39
+ <img
40
+ class="brand__logo"
41
+ src="{{ "/assets/pixel-lobster.svg" | relative_url }}"
42
+ alt=""
43
+ width="40"
44
+ height="40"
45
+ decoding="async"
46
+ />
47
+ <div class="brand__text">
48
+ <div class="brand__name">CLAWDBOT</div>
49
+ <div class="brand__hint">docs // lobster terminal</div>
50
+ </div>
51
+ </div>
52
+
53
+ <div class="titlebar__actions">
54
+ <a class="titlebar__cta" href="https://github.com/clawdbot/clawdbot">
55
+ <span class="titlebar__cta-label">GitHub</span>
56
+ <span class="titlebar__cta-meta">repo</span>
57
+ </a>
58
+ <a class="titlebar__cta titlebar__cta--accent" href="https://github.com/clawdbot/clawdbot/releases/latest">
59
+ <span class="titlebar__cta-label">Download</span>
60
+ <span class="titlebar__cta-meta">latest</span>
61
+ </a>
62
+ </div>
63
+ </div>
64
+
65
+ <div class="shell__nav" aria-label="Primary">
66
+ <nav class="nav">
67
+ {% assign nav = site.nav | default: empty %}
68
+ {% for item in nav %}
69
+ {% assign item_url = item.url | relative_url %}
70
+ <a class="nav__link" href="{{ item_url }}">
71
+ <span class="nav__chev">›</span>{{ item.title }}
72
+ </a>
73
+ {% endfor %}
74
+ </nav>
75
+
76
+ <div class="shell__status" aria-hidden="true">
77
+ <span class="status__dot"></span>
78
+ <span class="status__text">
79
+ {% if page.url == "/" %}
80
+ ready
81
+ {% else %}
82
+ viewing: {{ page.path }}
83
+ {% endif %}
84
+ </span>
85
+ </div>
86
+ </div>
87
+ </div>
88
+ </header>
89
+
90
+ <main id="content" class="content" role="main">
91
+ <div class="terminal">
92
+ <div class="terminal__prompt" aria-hidden="true">
93
+ <span class="prompt__user">clawd</span>@<span class="prompt__host">clawdbot</span>:<span class="prompt__path">~/docs</span>$<span class="prompt__cmd">
94
+ {% if page.url == "/" %}cat index.md{% else %}less {{ page.path }}{% endif %}
95
+ </span>
96
+ </div>
97
+
98
+ {% if page.summary %}
99
+ <p class="terminal__summary">{{ page.summary }}</p>
100
+ {% endif %}
101
+
102
+ {% if page.read_when %}
103
+ <details class="terminal__meta">
104
+ <summary>Read when…</summary>
105
+ <ul>
106
+ {% for hint in page.read_when %}
107
+ <li>{{ hint }}</li>
108
+ {% endfor %}
109
+ </ul>
110
+ </details>
111
+ {% endif %}
112
+
113
+ <article class="markdown">
114
+ {{ content }}
115
+ </article>
116
+
117
+ <footer class="terminal__footer" role="contentinfo">
118
+ <div class="footer__line">
119
+ <span class="footer__sig">clawdbot.ai</span>
120
+ <span class="footer__sep">·</span>
121
+ <a href="https://github.com/clawdbot/clawdbot">source</a>
122
+ <span class="footer__sep">·</span>
123
+ <a href="https://github.com/clawdbot/clawdbot/releases">releases</a>
124
+ </div>
125
+ <div class="footer__hint" aria-hidden="true">
126
+ tip: press <kbd>F2</kbd> (Mac: <kbd>fn</kbd>+<kbd>F2</kbd>) to flip
127
+ the universe
128
+ </div>
129
+ <div class="footer__actions">
130
+ <button
131
+ class="theme-toggle"
132
+ type="button"
133
+ data-theme-toggle
134
+ aria-label="Toggle theme (F2; on Mac: fn+F2)"
135
+ aria-pressed="false"
136
+ >
137
+ <span class="theme-toggle__key">F2</span>
138
+ <span class="theme-toggle__label" data-theme-label>theme</span>
139
+ </button>
140
+ </div>
141
+ </footer>
142
+ </div>
143
+ </main>
144
+ </body>
145
+ </html>
package/docs/agent-send.md ADDED
@@ -0,0 +1,21 @@
1
+ ---
2
+ summary: "Design notes for a direct `clawdbot agent` CLI subcommand without WhatsApp delivery"
3
+ read_when:
4
+ - Adding or modifying the agent CLI entrypoint
5
+ ---
6
+ # `clawdbot agent` (direct-to-agent invocation)
7
+
8
+ `clawdbot agent` lets you talk to the **embedded** agent runtime directly (no chat send unless you opt in), while reusing the same session store and thinking/verbose persistence as inbound auto-replies.
9
+
10
+ ## Behavior
11
+ - Required: `--message <text>`
12
+ - Session selection:
13
+ - If `--session-id` is given, reuse it.
14
+ - Else if `--to <e164>` is given, derive the session key from `session.scope` (direct chats collapse to `main`, or `global` when scope is global).
15
+ - Runs the embedded Pi agent (configured via `agent`).
16
+ - Thinking/verbose:
17
+ - Flags `--thinking <off|minimal|low|medium|high>` and `--verbose <on|off>` persist into the session store.
18
+ - Output:
19
+ - Default: prints text (and `MEDIA:<url>` lines) to stdout.
20
+ - `--json`: prints structured payloads + meta.
21
+ - Optional: `--deliver` sends the reply back to the selected provider (`whatsapp`, `telegram`, `discord`, `signal`, `imessage`).
package/docs/agent.md ADDED
@@ -0,0 +1,104 @@
1
+ ---
2
+ summary: "Agent runtime (embedded p-mono), workspace contract, and session bootstrap"
3
+ read_when:
4
+ - Changing agent runtime, workspace bootstrap, or session behavior
5
+ ---
6
+ <!-- {% raw %} -->
7
+ # Agent Runtime 🤖
8
+
9
+ CLAWDBOT runs a single embedded agent runtime derived from **p-mono** (internal name: **p**).
10
+
11
+ ## Workspace (required)
12
+
13
+ You must set an agent home directory via `agent.workspace`. CLAWDBOT uses this as the agent’s **only** working directory (`cwd`) for tools and context.
14
+
15
+ Recommended: use `clawdbot setup` to create `~/.clawdbot/clawdbot.json` if missing and initialize the workspace files.
16
+
17
+ If `agent.sandbox` is enabled, non-main sessions can override this with
18
+ per-session workspaces under `agent.sandbox.workspaceRoot` (see
19
+ `docs/configuration.md`).
20
+
21
+ ## Bootstrap files (injected)
22
+
23
+ Inside `agent.workspace`, CLAWDBOT expects these user-editable files:
24
+ - `AGENTS.md` — operating instructions + “memory”
25
+ - `SOUL.md` — persona, boundaries, tone
26
+ - `TOOLS.md` — user-maintained tool notes (e.g. `imsg`, `sag`, conventions)
27
+ - `BOOTSTRAP.md` — one-time first-run ritual (deleted after completion)
28
+ - `IDENTITY.md` — agent name/vibe/emoji
29
+ - `USER.md` — user profile + preferred address
30
+
31
+ On the first turn of a new session, CLAWDBOT injects the contents of these files directly into the agent context.
32
+
33
+ If a file is missing, CLAWDBOT injects a single “missing file” marker line (and `clawdbot setup` will create a safe default template).
34
+
35
+ ## Built-in tools (internal)
36
+
37
+ p’s embedded core tools (read/bash/edit/write and related internals) are defined in code and always available. `TOOLS.md` does **not** control which tools exist; it’s guidance for how *you* want them used.
38
+
39
+ ## Skills
40
+
41
+ Clawdbot loads skills from three locations (workspace wins on name conflict):
42
+ - Bundled (shipped with the install)
43
+ - Managed/local: `~/.clawdbot/skills`
44
+ - Workspace: `<workspace>/skills`
45
+
46
+ Skills can be gated by config/env (see `skills` in `docs/configuration.md`).
47
+
48
+ ## p-mono integration
49
+
50
+ Clawdbot reuses pieces of the p-mono codebase (models/tools), but **session management, discovery, and tool wiring are Clawdbot-owned**.
51
+
52
+ - No p-coding agent runtime.
53
+ - No `~/.pi/agent` or `<workspace>/.pi` settings are consulted.
54
+
55
+ ## Peter @ steipete (only)
56
+
57
+ Apply these notes **only** when the user is Peter Steinberger at steipete.
58
+
59
+ - Gateway runs on the **Mac Studio in London**.
60
+ - Primary work computer: **MacBook Pro**.
61
+ - Peter travels between **Vienna** and **London**; there are two networks bridged via **Tailscale**.
62
+ - For debugging, connect to the Mac Studio (London) or MacBook Pro (primary).
63
+ - There is also an **M1 MacBook Pro** on the Vienna tailnet you can use to access the Vienna network.
64
+ - Nodes can be accessed via the `clawdbot` binary (`pnpm clawdbot` in `~/Projects/clawdbot`).
65
+ - See also `skills/clawdbot*` for node/browser/canvas/cron usage.
66
+
67
+ ## Sessions
68
+
69
+ Session transcripts are stored as JSONL at:
70
+ - `~/.clawdbot/sessions/<SessionId>.jsonl`
71
+
72
+ The session ID is stable and chosen by CLAWDBOT.
73
+ Legacy Pi/Tau session folders are **not** read.
74
+
75
+ ## Steering while streaming
76
+
77
+ When queue mode is `steer`, inbound messages are injected into the current run.
78
+ The queue is checked **after each tool call**; if a queued message is present,
79
+ remaining tool calls from the current assistant message are skipped (error tool
80
+ results with "Skipped due to queued user message."), then the queued user
81
+ message is injected before the next assistant response.
82
+
83
+ When queue mode is `followup` or `collect`, inbound messages are held until the
84
+ current turn ends, then a new agent turn starts with the queued payloads. See
85
+ `docs/queue.md` for mode + debounce/cap behavior.
86
+
87
+ Block streaming sends completed assistant blocks as soon as they finish; disable
88
+ via `agent.blockStreamingDefault: "off"` if you only want the final response.
89
+ Tune the boundary via `agent.blockStreamingBreak` (`text_end` vs `message_end`; defaults to text_end).
90
+ Control soft block chunking with `agent.blockStreamingChunk` (defaults to
91
+ 800–1200 chars; prefers paragraph breaks, then newlines; sentences last).
92
+ Verbose tool summaries are emitted at tool start (no debounce); Control UI
93
+ streams tool output via agent events when available.
94
+
95
+ ## Configuration (minimal)
96
+
97
+ At minimum, set:
98
+ - `agent.workspace`
99
+ - `whatsapp.allowFrom` (strongly recommended)
100
+
101
+ ---
102
+
103
+ *Next: [Group Chats](./group-messages.md)* 🦞
104
+ <!-- {% endraw %} -->
package/docs/android/connect.md ADDED
@@ -0,0 +1,131 @@
1
+ ---
2
+ summary: "Runbook: connect/pair the Android node to a Clawdbot Gateway and use Canvas/Chat/Camera"
3
+ read_when:
4
+ - Pairing or reconnecting the Android node
5
+ - Debugging Android bridge discovery or auth
6
+ - Verifying chat history parity across clients
7
+ ---
8
+
9
+ # Android Node Connection Runbook
10
+
11
+ Android node app ⇄ (mDNS/NSD + TCP bridge) ⇄ **Gateway bridge** ⇄ (loopback WS) ⇄ **Gateway**
12
+
13
+ The Gateway WebSocket stays loopback-only (`ws://127.0.0.1:18789`). Android talks to the LAN-facing **bridge** (default `tcp://0.0.0.0:18790`) and uses Gateway-owned pairing.
14
+
15
+ ## Prerequisites
16
+
17
+ - You can run the Gateway on the “master” machine.
18
+ - Android device/emulator can reach the gateway bridge:
19
+ - Same LAN with mDNS/NSD, **or**
20
+ - Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
21
+ - Manual bridge host/port (fallback)
22
+ - You can run the CLI (`clawdbot`) on the gateway machine (or via SSH).
23
+
24
+ ## 1) Start the Gateway (with bridge enabled)
25
+
26
+ Bridge is enabled by default (disable via `CLAWDBOT_BRIDGE_ENABLED=0`).
27
+
28
+ ```bash
29
+ pnpm clawdbot gateway --port 18789 --verbose
30
+ ```
31
+
32
+ Confirm in logs you see something like:
33
+ - `bridge listening on tcp://0.0.0.0:18790 (node)`
34
+
35
+ For tailnet-only setups (recommended for Vienna ⇄ London), bind the bridge to the gateway machine’s Tailscale IP instead:
36
+
37
+ - Set `bridge.bind: "tailnet"` in `~/.clawdbot/clawdbot.json` on the gateway host.
38
+ - Restart the Gateway / macOS menubar app.
39
+
40
+ ## 2) Verify discovery (optional)
41
+
42
+ From the gateway machine:
43
+
44
+ ```bash
45
+ dns-sd -B _clawdbot-bridge._tcp local.
46
+ ```
47
+
48
+ More debugging notes: `docs/bonjour.md`.
49
+
50
+ ### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
51
+
52
+ Android NSD/mDNS discovery won’t cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead:
53
+
54
+ 1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records.
55
+ 2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.
56
+
57
+ Details and example CoreDNS config: `docs/bonjour.md`.
58
+
59
+ ## 3) Connect from Android
60
+
61
+ In the Android app:
62
+
63
+ - The app keeps its bridge connection alive via a **foreground service** (persistent notification).
64
+ - Open **Settings**.
65
+ - Under **Discovered Bridges**, select your gateway and hit **Connect**.
66
+ - If mDNS is blocked, use **Advanced → Manual Bridge** (host + port) and **Connect (Manual)**.
67
+
68
+ After the first successful pairing, Android auto-reconnects on launch:
69
+ - Manual endpoint (if enabled), otherwise
70
+ - The last discovered bridge (best-effort).
71
+
72
+ ## 4) Approve pairing (CLI)
73
+
74
+ On the gateway machine:
75
+
76
+ ```bash
77
+ clawdbot nodes pending
78
+ clawdbot nodes approve <requestId>
79
+ ```
80
+
81
+ Pairing details: `docs/gateway/pairing.md`.
82
+
83
+ ## 5) Verify the node is connected
84
+
85
+ - Via nodes status:
86
+ ```bash
87
+ clawdbot nodes status
88
+ ```
89
+ - Via Gateway:
90
+ ```bash
91
+ clawdbot gateway call node.list --params "{}"
92
+ ```
93
+
94
+ ## 6) Chat + history
95
+
96
+ The Android node’s Chat sheet uses the gateway’s **primary session key** (`main`), so history and replies are shared with WebChat and other clients:
97
+
98
+ - History: `chat.history`
99
+ - Send: `chat.send`
100
+ - Push updates (best-effort): `chat.subscribe` → `event:"chat"`
101
+
102
+ ## 7) Canvas + camera
103
+
104
+ ### Gateway Canvas Host (recommended for web content)
105
+
106
+ If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point the node at the Gateway canvas host.
107
+
108
+ Note: nodes always use the standalone canvas host on `canvasHost.port` (default `18793`), bound to the bridge interface.
109
+
110
+ 1) Create `~/clawd/canvas/index.html` on the gateway host.
111
+
112
+ 2) Navigate the node to it (LAN):
113
+
114
+ ```bash
115
+ clawdbot nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18793/__clawdbot__/canvas/"}'
116
+ ```
117
+
118
+ Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18793/__clawdbot__/canvas/`.
119
+
120
+ This server injects a live-reload client into HTML and reloads on file changes.
121
+ The A2UI host lives at `http://<gateway-host>:18793/__clawdbot__/a2ui/`.
122
+
123
+ Canvas commands (foreground only):
124
+ - `canvas.eval`, `canvas.snapshot`, `canvas.navigate` (use `{"url":""}` or `{"url":"/"}` to return to the default scaffold). `canvas.snapshot` returns `{ format, base64 }` (default `format="jpeg"`).
125
+ - A2UI: `canvas.a2ui.push`, `canvas.a2ui.reset` (`canvas.a2ui.pushJSONL` legacy alias)
126
+
127
+ Camera commands (foreground only; permission-gated):
128
+ - `camera.snap` (jpg)
129
+ - `camera.clip` (mp4)
130
+
131
+ See `docs/camera.md` for parameters and CLI helpers.
package/docs/architecture.md ADDED
@@ -0,0 +1,89 @@
1
+ ---
2
+ summary: "Target WebSocket gateway architecture, components, and client flows"
3
+ read_when:
4
+ - Working on gateway protocol, clients, or transports
5
+ ---
6
+ # Gateway Architecture (target state)
7
+
8
+ Last updated: 2025-12-09
9
+
10
+ ## Overview
11
+ - A single long-lived **Gateway** process owns all messaging surfaces (WhatsApp via Baileys, Telegram via grammY, Discord via discord.js) and the control/event plane.
12
+ - All clients (macOS app, CLI, web UI, automations) connect to the Gateway over one transport: **WebSocket on 127.0.0.1:18789** (tunnel or VPN for remote).
13
+ - One Gateway per host; it is the only place that is allowed to open a WhatsApp session. All sends/agent runs go through it.
14
+ - By default: the Gateway exposes a Canvas host on `canvasHost.port` (default `18793`), serving `~/clawd/canvas` at `/__clawdbot__/canvas/` with live-reload; disable via `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`.
15
+
16
+ ## Components and flows
17
+ - **Gateway (daemon)**
18
+ - Maintains Baileys/Telegram/Discord connections.
19
+ - Exposes a typed WS API (req/resp + server push events).
20
+ - Validates every inbound frame against JSON Schema; rejects anything before a mandatory `connect`.
21
+ - **Clients (mac app / CLI / web admin)**
22
+ - One WS connection per client.
23
+ - Send requests (`health`, `status`, `send`, `agent`, `system-presence`, toggles) and subscribe to events (`tick`, `agent`, `presence`, `shutdown`).
24
+ - On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see `docs/clawdbot-mac.md`).
25
+ - **Agent process (Pi)**
26
+ - Spawned by the Gateway on demand for `agent` calls; streams events back over the same WS connection.
27
+ - **WebChat**
28
+ - Serves static assets locally.
29
+ - Holds a single WS connection to the Gateway for control/data; all sends/agent runs go through the Gateway WS.
30
+ - Remote use goes through the same SSH/Tailscale tunnel as other clients.
31
+
32
+ ## Connection lifecycle (single client)
33
+ ```
34
+ Client Gateway
35
+ | |
36
+ |---- req:connect -------->|
37
+ |<------ res (ok) ---------| (or res error + close)
38
+ | (payload=hello-ok carries snapshot: presence + health)
39
+ | |
40
+ |<------ event:presence ---| (deltas)
41
+ |<------ event:tick -------| (keepalive/no-op)
42
+ | |
43
+ |------- req:agent ------->|
44
+ |<------ res:agent --------| (ack: {runId,status:"accepted"})
45
+ |<------ event:agent ------| (streaming)
46
+ |<------ res:agent --------| (final: {runId,status,summary})
47
+ | |
48
+ ```
49
+ ## Wire protocol (summary)
50
+ - Transport: WebSocket, text frames with JSON payloads.
51
+ - First frame must be `req {type:"req", id, method:"connect", params:{minProtocol, maxProtocol, client:{name,version,platform,mode,instanceId}, caps, auth?, locale?, userAgent? } }`.
52
+ - Server replies `res {type:"res", id, ok:true, payload: hello-ok }` or `ok:false` then closes.
53
+ - After handshake:
54
+ - Requests: `{type:"req", id, method, params}` → `{type:"res", id, ok, payload|error}`
55
+ - Events: `{type:"event", event:"agent"|"presence"|"tick"|"shutdown", payload, seq?, stateVersion?}`
56
+ - If `CLAWDBOT_GATEWAY_TOKEN` (or `--token`) is set, `connect.params.auth.token` must match; otherwise the socket closes with policy violation.
57
+ - Presence payload is structured, not free text: `{host, ip, version, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }`.
58
+ - Agent runs are acked `{runId,status:"accepted"}` then complete with a final res `{runId,status,summary}`; streamed output arrives as `event:"agent"`.
59
+ - Protocol versions are bumped on breaking changes; clients must match `minClient`; Gateway chooses within client’s min/max.
60
+ - Idempotency keys are required for side-effecting methods (`send`, `agent`) to safely retry; server keeps a short-lived dedupe cache.
61
+ - Policy in `hello-ok` communicates payload/queue limits and tick interval.
62
+
63
+ ## Type system and codegen
64
+ - Source of truth: TypeBox (or ArkType) definitions in `protocol/` on the server.
65
+ - Build step emits JSON Schema.
66
+ - Clients:
67
+ - TypeScript: uses the same TypeBox types directly.
68
+ - Swift: generated `Codable` models via quicktype from the JSON Schema.
69
+ - Validation: AJV on the server for every inbound frame; optional client-side validation for defensive programming.
70
+
71
+ ## Invariants
72
+ - Exactly one Gateway controls a single Baileys session per host. No fallbacks to ad-hoc direct Baileys sends.
73
+ - Handshake is mandatory; any non-JSON or non-connect first frame is a hard close.
74
+ - All methods and events are versioned; new fields are additive; breaking changes increment `protocol`.
75
+ - No event replay: on seq gaps, clients must refresh (`health` + `system-presence`) and continue; presence is bounded via TTL/max entries.
76
+
77
+ ## Remote access
78
+ - Preferred: Tailscale or VPN; alternate: SSH tunnel `ssh -N -L 18789:127.0.0.1:18789 user@host`.
79
+ - Same protocol over the tunnel; same handshake. If a shared token is configured, clients must send it in `connect.params.auth.token` even over the tunnel.
80
+ - Same protocol over the tunnel; same handshake. If a shared token is configured, clients must send it in `connect.params.auth.token` even over the tunnel.
81
+
82
+ ## Operations snapshot
83
+ - Start: `clawdbot gateway` (foreground, logs to stdout).
84
+ Supervise with launchd/systemd for restarts.
85
+ - Health: request `health` over WS; also surfaced in `hello-ok.health`.
86
+ - Metrics/logging: keep outside this spec; gateway should expose Prometheus text or structured logs separately.
87
+
88
+ ## Migration notes
89
+ - This architecture supersedes the legacy stdin RPC and the ad-hoc TCP control port. New clients should speak only the WS protocol. Legacy compatibility is intentionally dropped.
package/docs/assets/markdown.css ADDED
@@ -0,0 +1,130 @@
1
+ .markdown {
2
+ margin-top: 18px;
3
+ line-height: 1.7;
4
+ }
5
+
6
+ .markdown h1,
7
+ .markdown h2,
8
+ .markdown h3,
9
+ .markdown h4 {
10
+ font-family: var(--font-pixel);
11
+ letter-spacing: 0.04em;
12
+ line-height: 1.15;
13
+ }
14
+
15
+ .markdown h1 {
16
+ font-size: clamp(28px, 4vw, 44px);
17
+ margin: 26px 0 10px;
18
+ }
19
+
20
+ .markdown h2 {
21
+ font-size: 22px;
22
+ margin: 26px 0 10px;
23
+ }
24
+
25
+ .markdown h3 {
26
+ font-size: 18px;
27
+ margin: 22px 0 8px;
28
+ }
29
+
30
+ .markdown p {
31
+ margin: 0 0 14px;
32
+ }
33
+
34
+ .markdown a {
35
+ color: var(--link);
36
+ text-decoration: none;
37
+ border-bottom: 1px dotted color-mix(in oklab, var(--link) 65%, transparent);
38
+ }
39
+
40
+ .markdown a:hover {
41
+ color: var(--link2);
42
+ border-bottom-color: color-mix(in oklab, var(--link2) 75%, transparent);
43
+ }
44
+
45
+ .markdown hr {
46
+ border: 0;
47
+ height: 1px;
48
+ background: linear-gradient(
49
+ 90deg,
50
+ transparent,
51
+ color-mix(in oklab, var(--frame-border) 30%, transparent),
52
+ transparent
53
+ );
54
+ margin: 26px 0;
55
+ }
56
+
57
+ .markdown blockquote {
58
+ margin: 18px 0;
59
+ padding: 14px 14px;
60
+ border-radius: var(--radius-sm);
61
+ background: color-mix(in oklab, var(--panel) 70%, transparent);
62
+ border-left: 6px solid color-mix(in oklab, var(--accent) 60%, transparent);
63
+ color: var(--muted);
64
+ }
65
+
66
+ .markdown ul,
67
+ .markdown ol {
68
+ margin: 0 0 14px 22px;
69
+ }
70
+
71
+ .markdown li {
72
+ margin: 4px 0;
73
+ }
74
+
75
+ .markdown img {
76
+ max-width: 100%;
77
+ height: auto;
78
+ border-radius: 12px;
79
+ border: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
80
+ box-shadow: 0 12px 0 -8px rgba(0, 0, 0, 0.18);
81
+ }
82
+
83
+ .markdown code {
84
+ font-family: var(--font-body);
85
+ font-size: 0.95em;
86
+ padding: 0.15em 0.35em;
87
+ border-radius: 8px;
88
+ background: color-mix(in oklab, var(--panel) 70%, var(--code-bg));
89
+ border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
90
+ }
91
+
92
+ .markdown pre {
93
+ background: var(--code-bg);
94
+ color: var(--code-fg);
95
+ padding: 14px 14px;
96
+ border-radius: var(--radius-sm);
97
+ border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
98
+ overflow-x: auto;
99
+ box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--code-accent) 12%, transparent);
100
+ }
101
+
102
+ .markdown pre code {
103
+ background: transparent;
104
+ border: 0;
105
+ padding: 0;
106
+ color: inherit;
107
+ }
108
+
109
+ .markdown table {
110
+ width: 100%;
111
+ border-collapse: collapse;
112
+ margin: 16px 0 22px;
113
+ border: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
114
+ border-radius: var(--radius-sm);
115
+ overflow: hidden;
116
+ }
117
+
118
+ .markdown th,
119
+ .markdown td {
120
+ padding: 10px 10px;
121
+ border-bottom: 1px solid color-mix(in oklab, var(--frame-border) 15%, transparent);
122
+ vertical-align: top;
123
+ }
124
+
125
+ .markdown th {
126
+ background: color-mix(in oklab, var(--panel2) 85%, transparent);
127
+ font-family: var(--font-pixel);
128
+ letter-spacing: 0.06em;
129
+ }
130
+
package/docs/assets/pixel-lobster.svg ADDED
@@ -0,0 +1,60 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 16 16" role="img" aria-label="Pixel lobster">
2
+ <rect width="16" height="16" fill="none"/>
3
+ <!-- outline -->
4
+ <g fill="#3a0a0d">
5
+ <rect x="1" y="5" width="1" height="3"/>
6
+ <rect x="2" y="4" width="1" height="1"/>
7
+ <rect x="2" y="8" width="1" height="1"/>
8
+ <rect x="3" y="3" width="1" height="1"/>
9
+ <rect x="3" y="9" width="1" height="1"/>
10
+ <rect x="4" y="2" width="1" height="1"/>
11
+ <rect x="4" y="10" width="1" height="1"/>
12
+ <rect x="5" y="2" width="6" height="1"/>
13
+ <rect x="11" y="2" width="1" height="1"/>
14
+ <rect x="12" y="3" width="1" height="1"/>
15
+ <rect x="12" y="9" width="1" height="1"/>
16
+ <rect x="13" y="4" width="1" height="1"/>
17
+ <rect x="13" y="8" width="1" height="1"/>
18
+ <rect x="14" y="5" width="1" height="3"/>
19
+ <rect x="5" y="11" width="6" height="1"/>
20
+ <rect x="4" y="12" width="1" height="1"/>
21
+ <rect x="11" y="12" width="1" height="1"/>
22
+ <rect x="3" y="13" width="1" height="1"/>
23
+ <rect x="12" y="13" width="1" height="1"/>
24
+ <rect x="5" y="14" width="6" height="1"/>
25
+ </g>
26
+
27
+ <!-- body -->
28
+ <g fill="#ff4f40">
29
+ <rect x="5" y="3" width="6" height="1"/>
30
+ <rect x="4" y="4" width="8" height="1"/>
31
+ <rect x="3" y="5" width="10" height="1"/>
32
+ <rect x="3" y="6" width="10" height="1"/>
33
+ <rect x="3" y="7" width="10" height="1"/>
34
+ <rect x="4" y="8" width="8" height="1"/>
35
+ <rect x="5" y="9" width="6" height="1"/>
36
+ <rect x="5" y="12" width="6" height="1"/>
37
+ <rect x="6" y="13" width="4" height="1"/>
38
+ </g>
39
+
40
+ <!-- claws -->
41
+ <g fill="#ff775f">
42
+ <rect x="1" y="6" width="2" height="1"/>
43
+ <rect x="2" y="5" width="1" height="1"/>
44
+ <rect x="2" y="7" width="1" height="1"/>
45
+ <rect x="13" y="6" width="2" height="1"/>
46
+ <rect x="13" y="5" width="1" height="1"/>
47
+ <rect x="13" y="7" width="1" height="1"/>
48
+ </g>
49
+
50
+ <!-- eyes -->
51
+ <g fill="#081016">
52
+ <rect x="6" y="5" width="1" height="1"/>
53
+ <rect x="9" y="5" width="1" height="1"/>
54
+ </g>
55
+ <g fill="#f5fbff">
56
+ <rect x="6" y="4" width="1" height="1"/>
57
+ <rect x="9" y="4" width="1" height="1"/>
58
+ </g>
59
+ </svg>
60
+