copilotz 1.0.0-rc.20 → 1.0.0-rc.21

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 (340) hide show
  1. package/CHANGELOG.md +417 -0
  2. package/README.md +295 -19
  3. package/hosts/orgs/mod.d.ts +4 -1
  4. package/hosts/orgs/mod.js +2 -2
  5. package/hosts/web/files.d.ts +6 -2
  6. package/hosts/web/files.js +36 -3
  7. package/hosts/web/node/mod.d.ts +1 -1
  8. package/hosts/web/node/mod.js +1 -1
  9. package/hosts/web/node/serve.d.ts +26 -0
  10. package/hosts/web/node/serve.js +23 -1
  11. package/hosts/web/routes.d.ts +28 -1
  12. package/hosts/web/routes.js +65 -10
  13. package/hosts/web/server.d.ts +5 -4
  14. package/hosts/web/server.js +1 -1
  15. package/package.json +2 -2
  16. package/plugins/access/accounts/collections/account.d.ts +2 -2
  17. package/plugins/access/contacts/actions/chat.d.ts +1 -0
  18. package/plugins/access/contacts/actions/chat.js +45 -0
  19. package/plugins/access/contacts/actions/forget.d.ts +1 -0
  20. package/plugins/access/contacts/actions/forget.js +56 -0
  21. package/plugins/access/contacts/actions/start.d.ts +1 -0
  22. package/plugins/access/contacts/actions/start.js +50 -0
  23. package/plugins/access/contacts/collections/contact.d.ts +81 -0
  24. package/plugins/access/contacts/collections/contact.js +58 -0
  25. package/plugins/access/contacts/contract.d.ts +10 -0
  26. package/plugins/access/contacts/contract.js +10 -0
  27. package/plugins/access/contacts/mod.d.ts +27 -0
  28. package/plugins/access/contacts/mod.js +49 -0
  29. package/plugins/access/contacts/views/contact.d.ts +8 -0
  30. package/plugins/access/contacts/views/contact.js +25 -0
  31. package/plugins/access/contacts/web.d.ts +7 -0
  32. package/plugins/access/contacts/web.js +11 -0
  33. package/plugins/access/directory/collections/credit-code.d.ts +1 -1
  34. package/plugins/access/directory/collections/invite.d.ts +1 -1
  35. package/plugins/access/identity/mod.js +8 -6
  36. package/plugins/access/mod.d.ts +7 -1
  37. package/plugins/access/mod.js +7 -2
  38. package/plugins/access/spaces/actions/agents.js +12 -6
  39. package/plugins/access/spaces/actions/create.js +10 -1
  40. package/plugins/access/spaces/actions/invitation.js +5 -2
  41. package/plugins/access/spaces/actions/keep.d.ts +1 -0
  42. package/plugins/access/spaces/actions/keep.js +55 -0
  43. package/plugins/access/spaces/actions/member.js +17 -4
  44. package/plugins/access/spaces/actions/rename.js +4 -0
  45. package/plugins/access/spaces/collections/member.d.ts +1 -1
  46. package/plugins/access/spaces/collections/request.d.ts +1 -1
  47. package/plugins/access/spaces/collections/space.d.ts +9 -0
  48. package/plugins/access/spaces/collections/space.js +2 -0
  49. package/plugins/access/spaces/contract.d.ts +4 -3
  50. package/plugins/access/spaces/contract.js +1 -1
  51. package/plugins/access/spaces/mod.d.ts +7 -1
  52. package/plugins/access/spaces/mod.js +8 -1
  53. package/plugins/access/spaces/resources/tools.d.ts +0 -5
  54. package/plugins/access/spaces/resources/tools.js +11 -1
  55. package/plugins/access/spaces/shared/agents.js +2 -2
  56. package/plugins/access/spaces/shared/can.d.ts +18 -3
  57. package/plugins/access/spaces/shared/can.js +32 -5
  58. package/plugins/access/spaces/shared/declared.d.ts +21 -0
  59. package/plugins/access/spaces/shared/declared.js +8 -0
  60. package/plugins/access/spaces/shared/labels.d.ts +7 -1
  61. package/plugins/access/spaces/shared/labels.js +56 -8
  62. package/plugins/access/spaces/shared/managers.js +2 -2
  63. package/plugins/access/spaces/shared/names.d.ts +9 -5
  64. package/plugins/access/spaces/shared/names.js +36 -19
  65. package/plugins/access/spaces/shared/reach.d.ts +20 -6
  66. package/plugins/access/spaces/shared/reach.js +62 -20
  67. package/plugins/access/spaces/shared/rules.d.ts +10 -5
  68. package/plugins/access/spaces/shared/rules.js +35 -10
  69. package/plugins/access/spaces/shared/seat.d.ts +3 -2
  70. package/plugins/access/spaces/shared/seat.js +9 -2
  71. package/plugins/access/spaces/views/where.d.ts +4 -2
  72. package/plugins/access/spaces/views/where.js +9 -0
  73. package/plugins/access/spaces/web.js +1 -1
  74. package/plugins/access/web.d.ts +1 -0
  75. package/plugins/access/web.js +1 -0
  76. package/plugins/agents/chat/actions/erase.d.ts +1 -0
  77. package/plugins/agents/chat/actions/erase.js +51 -0
  78. package/plugins/agents/chat/actions/open.d.ts +1 -0
  79. package/plugins/agents/chat/actions/open.js +49 -0
  80. package/plugins/agents/chat/actions/quiet.d.ts +1 -0
  81. package/plugins/agents/chat/actions/quiet.js +33 -0
  82. package/plugins/agents/chat/actions/say.d.ts +1 -0
  83. package/plugins/agents/chat/actions/say.js +82 -0
  84. package/plugins/agents/chat/actions/send.js +57 -19
  85. package/plugins/agents/chat/actions/shown.d.ts +1 -0
  86. package/plugins/agents/chat/actions/shown.js +35 -0
  87. package/plugins/agents/chat/collections/intent.d.ts +124 -0
  88. package/plugins/agents/chat/collections/intent.js +52 -0
  89. package/plugins/agents/chat/collections/message.d.ts +74 -1
  90. package/plugins/agents/chat/collections/message.js +23 -1
  91. package/plugins/agents/chat/collections/shown.d.ts +105 -0
  92. package/plugins/agents/chat/collections/shown.js +34 -0
  93. package/plugins/agents/chat/contract.d.ts +15 -7
  94. package/plugins/agents/chat/contract.js +7 -1
  95. package/plugins/agents/chat/mod.d.ts +20 -2
  96. package/plugins/agents/chat/mod.js +43 -4
  97. package/plugins/agents/chat/processors/failed.js +15 -5
  98. package/plugins/agents/chat/processors/turn.d.ts +1 -1
  99. package/plugins/agents/chat/processors/turn.js +95 -35
  100. package/plugins/agents/chat/shared/delivery.d.ts +16 -2
  101. package/plugins/agents/chat/shared/delivery.js +62 -7
  102. package/plugins/agents/chat/shared/send.d.ts +1 -3
  103. package/plugins/agents/chat/shared/send.js +2 -9
  104. package/plugins/agents/chat/shared/tools.d.ts +33 -0
  105. package/plugins/agents/chat/shared/tools.js +28 -0
  106. package/plugins/agents/chat/shared/types.d.ts +59 -1
  107. package/plugins/agents/chat/views/message.d.ts +4 -2
  108. package/plugins/agents/chat/views/message.js +22 -4
  109. package/plugins/agents/chat/views/prompt.js +38 -4
  110. package/plugins/agents/history/collections/outline.d.ts +1 -1
  111. package/plugins/agents/history/collections/summary.d.ts +1 -1
  112. package/plugins/agents/history/mod.js +2 -1
  113. package/plugins/agents/history/processors/erase.d.ts +3 -0
  114. package/plugins/agents/history/processors/erase.js +11 -0
  115. package/plugins/agents/memory/mod.js +2 -1
  116. package/plugins/agents/memory/processors/extract.d.ts +1 -1
  117. package/plugins/agents/memory/processors/extract.js +5 -0
  118. package/plugins/agents/memory/resources/tools.js +1 -1
  119. package/plugins/agents/memory/shared/settings.d.ts +7 -2
  120. package/plugins/agents/memory/shared/settings.js +9 -1
  121. package/plugins/agents/routines/collections/routine.d.ts +1 -1
  122. package/plugins/agents/routines/collections/run.d.ts +1 -1
  123. package/plugins/compute/apps/collections/app.d.ts +2 -2
  124. package/plugins/compute/cloud/resources/tools.js +3 -3
  125. package/plugins/compute/computers/collections/approval.d.ts +2 -2
  126. package/plugins/compute/computers/collections/grant.d.ts +1 -1
  127. package/plugins/compute/computers/collections/preview.d.ts +2 -2
  128. package/plugins/compute/computers/program/version.d.ts +1 -1
  129. package/plugins/compute/computers/program/version.js +1 -1
  130. package/plugins/compute/computers/resources/downloads.js +1 -1
  131. package/plugins/compute/computers/shared/wake.d.ts +1 -1
  132. package/plugins/compute/computers/shared/wake.js +17 -0
  133. package/plugins/interfaces/api/collections/key.d.ts +1 -1
  134. package/plugins/interfaces/api/shared/events.js +5 -4
  135. package/plugins/interfaces/maintenance/actions/read.d.ts +4 -0
  136. package/plugins/interfaces/maintenance/actions/read.js +76 -0
  137. package/plugins/interfaces/maintenance/actions/write.d.ts +4 -0
  138. package/plugins/interfaces/maintenance/actions/write.js +64 -0
  139. package/plugins/interfaces/maintenance/contract.d.ts +60 -0
  140. package/plugins/interfaces/maintenance/contract.js +2 -0
  141. package/plugins/interfaces/maintenance/mod.d.ts +52 -0
  142. package/plugins/interfaces/maintenance/mod.js +66 -0
  143. package/plugins/interfaces/maintenance/resources/routes.d.ts +71 -0
  144. package/plugins/interfaces/maintenance/resources/routes.js +457 -0
  145. package/plugins/interfaces/maintenance/shared/ops.d.ts +4 -0
  146. package/plugins/interfaces/maintenance/shared/ops.js +19 -0
  147. package/plugins/interfaces/mcp/actions/call.d.ts +11 -0
  148. package/plugins/interfaces/mcp/actions/call.js +304 -0
  149. package/plugins/interfaces/mcp/actions/prune.d.ts +1 -0
  150. package/plugins/interfaces/mcp/actions/prune.js +18 -0
  151. package/plugins/interfaces/mcp/collections/closed.d.ts +23 -0
  152. package/plugins/interfaces/mcp/collections/closed.js +17 -0
  153. package/plugins/interfaces/mcp/collections/rate.d.ts +27 -0
  154. package/plugins/interfaces/mcp/collections/rate.js +18 -0
  155. package/plugins/interfaces/mcp/collections/receipt.d.ts +46 -0
  156. package/plugins/interfaces/mcp/collections/receipt.js +46 -0
  157. package/plugins/interfaces/mcp/contract.d.ts +9 -0
  158. package/plugins/interfaces/mcp/contract.js +9 -0
  159. package/plugins/interfaces/mcp/mod.d.ts +84 -0
  160. package/plugins/interfaces/mcp/mod.js +122 -0
  161. package/plugins/interfaces/mcp/processors/closed.d.ts +13 -0
  162. package/plugins/interfaces/mcp/processors/closed.js +16 -0
  163. package/plugins/interfaces/mcp/resources/running.d.ts +21 -0
  164. package/plugins/interfaces/mcp/resources/running.js +36 -0
  165. package/plugins/interfaces/mcp/resources/server.d.ts +54 -0
  166. package/plugins/interfaces/mcp/resources/server.js +423 -0
  167. package/plugins/interfaces/mcp/resources/tools.d.ts +114 -0
  168. package/plugins/interfaces/mcp/resources/tools.js +324 -0
  169. package/plugins/interfaces/mcp/shared/caller.d.ts +45 -0
  170. package/plugins/interfaces/mcp/shared/caller.js +99 -0
  171. package/plugins/interfaces/mcp/shared/keys.d.ts +50 -0
  172. package/plugins/interfaces/mcp/shared/keys.js +53 -0
  173. package/plugins/interfaces/mcp/shared/settings.d.ts +187 -0
  174. package/plugins/interfaces/mcp/shared/settings.js +176 -0
  175. package/plugins/interfaces/mcp/views/offered.d.ts +20 -0
  176. package/plugins/interfaces/mcp/views/offered.js +20 -0
  177. package/plugins/interfaces/mod.d.ts +5 -1
  178. package/plugins/interfaces/mod.js +5 -1
  179. package/plugins/interfaces/terminal/actions/print.js +1 -1
  180. package/plugins/interfaces/terminal/actions/set.js +1 -1
  181. package/plugins/interfaces/terminal/collections/output.d.ts +1 -1
  182. package/plugins/interfaces/terminal/collections/shell.js +1 -1
  183. package/plugins/interfaces/voice/actions/block.d.ts +2 -0
  184. package/plugins/interfaces/voice/actions/block.js +74 -0
  185. package/plugins/interfaces/voice/actions/call.d.ts +19 -0
  186. package/plugins/interfaces/voice/actions/call.js +253 -0
  187. package/plugins/interfaces/voice/actions/hook.d.ts +5 -0
  188. package/plugins/interfaces/voice/actions/hook.js +225 -0
  189. package/plugins/interfaces/voice/actions/prune.d.ts +1 -0
  190. package/plugins/interfaces/voice/actions/prune.js +35 -0
  191. package/plugins/interfaces/voice/collections/blocked.d.ts +87 -0
  192. package/plugins/interfaces/voice/collections/blocked.js +34 -0
  193. package/plugins/interfaces/voice/collections/call.d.ts +279 -0
  194. package/plugins/interfaces/voice/collections/call.js +77 -0
  195. package/plugins/interfaces/voice/collections/phone.d.ts +74 -0
  196. package/plugins/interfaces/voice/collections/phone.js +26 -0
  197. package/plugins/interfaces/voice/contract.d.ts +14 -0
  198. package/plugins/interfaces/voice/contract.js +2 -0
  199. package/plugins/interfaces/voice/mod.d.ts +57 -0
  200. package/plugins/interfaces/voice/mod.js +118 -0
  201. package/plugins/interfaces/voice/processors/forget.d.ts +13 -0
  202. package/plugins/interfaces/voice/processors/forget.js +27 -0
  203. package/plugins/interfaces/voice/resources/relay.d.ts +77 -0
  204. package/plugins/interfaces/voice/resources/relay.js +428 -0
  205. package/plugins/interfaces/voice/resources/tools.d.ts +1 -0
  206. package/plugins/interfaces/voice/resources/tools.js +25 -0
  207. package/plugins/interfaces/voice/shared/caller.d.ts +27 -0
  208. package/plugins/interfaces/voice/shared/caller.js +38 -0
  209. package/plugins/interfaces/voice/shared/settings.d.ts +136 -0
  210. package/plugins/interfaces/voice/shared/settings.js +121 -0
  211. package/plugins/interfaces/voice/shared/signature.d.ts +11 -0
  212. package/plugins/interfaces/voice/shared/signature.js +34 -0
  213. package/plugins/interfaces/voice/views/call.d.ts +41 -0
  214. package/plugins/interfaces/voice/views/call.js +30 -0
  215. package/plugins/interfaces/voice/views/context.d.ts +9 -0
  216. package/plugins/interfaces/voice/views/context.js +14 -0
  217. package/plugins/interfaces/voice/views/message.d.ts +17 -0
  218. package/plugins/interfaces/voice/views/message.js +41 -0
  219. package/plugins/interfaces/whatsapp/actions/connect.js +3 -0
  220. package/plugins/interfaces/whatsapp/actions/disconnect.js +4 -1
  221. package/plugins/interfaces/whatsapp/actions/hook.js +27 -11
  222. package/plugins/interfaces/whatsapp/actions/set.d.ts +8 -0
  223. package/plugins/interfaces/whatsapp/actions/set.js +121 -0
  224. package/plugins/interfaces/whatsapp/collections/blocked.d.ts +29 -0
  225. package/plugins/interfaces/whatsapp/collections/blocked.js +22 -0
  226. package/plugins/interfaces/whatsapp/collections/code.d.ts +1 -1
  227. package/plugins/interfaces/whatsapp/collections/number.d.ts +90 -4
  228. package/plugins/interfaces/whatsapp/collections/number.js +36 -4
  229. package/plugins/interfaces/whatsapp/collections/phone.d.ts +13 -3
  230. package/plugins/interfaces/whatsapp/collections/phone.js +9 -3
  231. package/plugins/interfaces/whatsapp/collections/rate.d.ts +27 -0
  232. package/plugins/interfaces/whatsapp/collections/rate.js +13 -0
  233. package/plugins/interfaces/whatsapp/collections/sent.d.ts +24 -12
  234. package/plugins/interfaces/whatsapp/collections/sent.js +11 -7
  235. package/plugins/interfaces/whatsapp/collections/thread.d.ts +14 -6
  236. package/plugins/interfaces/whatsapp/collections/thread.js +7 -5
  237. package/plugins/interfaces/whatsapp/collections/typing.d.ts +70 -0
  238. package/plugins/interfaces/whatsapp/collections/typing.js +21 -0
  239. package/plugins/interfaces/whatsapp/contract.d.ts +27 -4
  240. package/plugins/interfaces/whatsapp/contract.js +34 -1
  241. package/plugins/interfaces/whatsapp/events/undelivered.d.ts +8 -0
  242. package/plugins/interfaces/whatsapp/events/undelivered.js +17 -0
  243. package/plugins/interfaces/whatsapp/mod.d.ts +28 -2
  244. package/plugins/interfaces/whatsapp/mod.js +65 -6
  245. package/plugins/interfaces/whatsapp/processors/forget.d.ts +6 -0
  246. package/plugins/interfaces/whatsapp/processors/forget.js +11 -0
  247. package/plugins/interfaces/whatsapp/processors/receive.d.ts +17 -3
  248. package/plugins/interfaces/whatsapp/processors/receive.js +264 -81
  249. package/plugins/interfaces/whatsapp/processors/reply.d.ts +25 -5
  250. package/plugins/interfaces/whatsapp/processors/reply.js +216 -20
  251. package/plugins/interfaces/whatsapp/processors/typing.d.ts +8 -0
  252. package/plugins/interfaces/whatsapp/processors/typing.js +25 -0
  253. package/plugins/interfaces/whatsapp/shared/customers.d.ts +13 -0
  254. package/plugins/interfaces/whatsapp/shared/customers.js +16 -0
  255. package/plugins/interfaces/whatsapp/shared/graph.d.ts +31 -6
  256. package/plugins/interfaces/whatsapp/shared/graph.js +117 -10
  257. package/plugins/interfaces/whatsapp/shared/media.d.ts +23 -0
  258. package/plugins/interfaces/whatsapp/shared/media.js +46 -0
  259. package/plugins/interfaces/whatsapp/shared/number.d.ts +19 -8
  260. package/plugins/interfaces/whatsapp/shared/number.js +64 -7
  261. package/plugins/interfaces/whatsapp/shared/parts.d.ts +94 -0
  262. package/plugins/interfaces/whatsapp/shared/parts.js +184 -0
  263. package/plugins/interfaces/whatsapp/shared/payload.d.ts +27 -1
  264. package/plugins/interfaces/whatsapp/shared/payload.js +36 -1
  265. package/plugins/interfaces/whatsapp/shared/settings.d.ts +49 -1
  266. package/plugins/interfaces/whatsapp/shared/settings.js +11 -0
  267. package/plugins/interfaces/whatsapp/views/message.d.ts +13 -0
  268. package/plugins/interfaces/whatsapp/views/message.js +13 -0
  269. package/plugins/interfaces/whatsapp/views/web/line.d.ts +24 -0
  270. package/plugins/interfaces/whatsapp/views/web/line.js +44 -0
  271. package/plugins/interfaces/whatsapp/views/web/space.d.ts +7 -5
  272. package/plugins/interfaces/whatsapp/views/web/space.js +17 -10
  273. package/plugins/interfaces/whatsapp/views/web/style.d.ts +1 -1
  274. package/plugins/interfaces/whatsapp/views/web/style.js +8 -0
  275. package/plugins/models/adapters/llm/anthropic.d.ts +1 -1
  276. package/plugins/models/adapters/llm/anthropic.js +28 -15
  277. package/plugins/models/adapters/llm/gemini.d.ts +1 -1
  278. package/plugins/models/adapters/llm/gemini.js +2 -1
  279. package/plugins/models/adapters/llm/openai-compatible.d.ts +1 -1
  280. package/plugins/models/adapters/llm/openai-compatible.js +2 -1
  281. package/plugins/models/adapters/llm/openai.d.ts +1 -1
  282. package/plugins/models/adapters/llm/openai.js +16 -4
  283. package/plugins/models/shared/types.d.ts +8 -0
  284. package/plugins/models/shared/types.js +10 -0
  285. package/runtime/actor.d.ts +6 -0
  286. package/runtime/actor.js +9 -4
  287. package/runtime/aggregate.js +8 -2
  288. package/runtime/blobs.d.ts +15 -12
  289. package/runtime/blobs.js +58 -11
  290. package/runtime/cache.d.ts +6 -0
  291. package/runtime/cache.js +19 -1
  292. package/runtime/define.d.ts +10 -0
  293. package/runtime/errors.d.ts +20 -2
  294. package/runtime/errors.js +7 -1
  295. package/runtime/executor.js +27 -11
  296. package/runtime/links.d.ts +31 -0
  297. package/runtime/links.js +60 -0
  298. package/runtime/maintain.d.ts +88 -0
  299. package/runtime/maintain.js +120 -0
  300. package/runtime/memory.js +7 -4
  301. package/runtime/mod.d.ts +6 -4
  302. package/runtime/mod.js +5 -2
  303. package/runtime/mongo.d.ts +13 -0
  304. package/runtime/mongo.js +39 -8
  305. package/runtime/observe.d.ts +2 -0
  306. package/runtime/observe.js +14 -10
  307. package/runtime/ops.d.ts +5 -0
  308. package/runtime/ops.js +10 -1
  309. package/runtime/owner.d.ts +18 -1
  310. package/runtime/owner.js +127 -61
  311. package/runtime/presence.d.ts +18 -0
  312. package/runtime/presence.js +25 -0
  313. package/runtime/registry.d.ts +5 -0
  314. package/runtime/registry.js +18 -0
  315. package/runtime/runtime.js +9 -3
  316. package/runtime/store.d.ts +48 -1
  317. package/runtime/wire.d.ts +1 -0
  318. package/runtime/wire.js +3 -1
  319. package/stores/blobs/files/mod.js +4 -2
  320. package/stores/blobs/gcs/mod.d.ts +3 -0
  321. package/stores/blobs/gcs/mod.js +6 -5
  322. package/stores/blobs/http/mod.d.ts +1 -1
  323. package/stores/blobs/http/mod.js +2 -1
  324. package/stores/latency/mod.js +5 -1
  325. package/stores/sql/postgres/maintenance.d.ts +24 -0
  326. package/stores/sql/postgres/maintenance.js +258 -0
  327. package/stores/sql/postgres/mod.d.ts +20 -4
  328. package/stores/sql/postgres/mod.js +363 -96
  329. package/stores/sql/postgres/update.js +3 -1
  330. package/stores/sql/shared/capped.d.ts +2 -0
  331. package/stores/sql/shared/capped.js +22 -0
  332. package/stores/sql/shared/rows.d.ts +14 -0
  333. package/stores/sql/shared/rows.js +29 -0
  334. package/stores/sql/shared/statement.d.ts +12 -0
  335. package/stores/sql/shared/statement.js +244 -0
  336. package/stores/sql/sqlite/apart.d.ts +11 -0
  337. package/stores/sql/sqlite/apart.js +219 -0
  338. package/stores/sql/sqlite/mod.d.ts +16 -2
  339. package/stores/sql/sqlite/mod.js +246 -51
  340. package/testing/mod.js +1 -1
package/README.md CHANGED
@@ -8,11 +8,11 @@ browser.
8
8
 
9
9
  An app is plugins: agents that answer with tools and talk to each other and to people, conversations
10
10
  in shared spaces, memory, skills and routines, a usage ledger, people's computers, sign-in and
11
- connected accounts, a developer API, WhatsApp. Each is a plain object built from the same few
12
- primitives (collections, Actions, Processors, Views, resources and adapters), and the runtime knows
13
- nothing else. Everything durable is an event, a document, an edge, a vector or a blob, written by
14
- one owner to one store (memory, SQLite or PostgreSQL), so every change is on the record and every
15
- screen follows it live: in a terminal, in a browser, or in an agent's prompt.
11
+ connected accounts, a developer API, WhatsApp, phone calls. Each is a plain object built from the
12
+ same few primitives (collections, Actions, Processors, Views, resources and adapters), and the
13
+ runtime knows nothing else. Everything durable is an event, a document, an edge, a vector or a blob,
14
+ written by one owner to one store (memory, SQLite or PostgreSQL), so every change is on the record
15
+ and every screen follows it live: in a terminal, in a browser, or in an agent's prompt.
16
16
 
17
17
  ## Install
18
18
 
@@ -22,7 +22,7 @@ bun add copilotz # Bun
22
22
  deno add jsr:@copilotz/copilotz # Deno (or `deno add npm:copilotz`)
23
23
  ```
24
24
 
25
- On Deno, name it `copilotz` in `deno.json` (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.20"`),
25
+ On Deno, name it `copilotz` in `deno.json` (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.21"`),
26
26
  and the imports below are the same everywhere. Some pieces need a package of their own, installed
27
27
  beside it: `esbuild` to bundle the web host on Node, `@electric-sql/pglite` for PostgreSQL in the
28
28
  process, and `@types/react` for the front ends' types.
@@ -103,8 +103,8 @@ The package's entry points, the same names on npm (`copilotz/…`) and JSR (`@co
103
103
  | `copilotz/plugins/agents` | `chat`, `history`, `memory`, `memoryExtraction`, `team`, `skills`, `routines`, `tiers`, `openapi`, `tool` |
104
104
  | `copilotz/plugins/agents/web` | their web front ends: `chatWeb`, `teamWeb`, `memoryWeb`, `skillsWeb`, `routinesWeb`, `tiersWeb` |
105
105
  | `copilotz/plugins/agents/terminal` | their terminal front ends: `chatTerminal`, `memoryTerminal` |
106
- | `copilotz/plugins/access` | `access` (`spaces`, `identity`), `accounts`, `directory`, `googleSignIn` |
107
- | `copilotz/plugins/access/web` | `spacesWeb`, `accountsWeb` |
106
+ | `copilotz/plugins/access` | `access` (`spaces`, `identity`, `contacts`), `accounts`, `directory`, `googleSignIn` |
107
+ | `copilotz/plugins/access/web` | `spacesWeb`, `accountsWeb`, `contactsWeb` |
108
108
  | `copilotz/plugins/access/terminal` | `accessTerminal` |
109
109
  | `copilotz/plugins/billing` | `usage`: the ledger |
110
110
  | `copilotz/plugins/billing/web` | `usageWeb` |
@@ -113,14 +113,14 @@ The package's entry points, the same names on npm (`copilotz/…`) and JSR (`@co
113
113
  | `copilotz/plugins/compute/web` | `computersWeb` |
114
114
  | `copilotz/plugins/compute/terminal` | `computersTerminal` |
115
115
  | `copilotz/plugins/compute/downloads` | `computerDownloads`: the computer program's release, served by the app (Node) |
116
- | `copilotz/plugins/interfaces` | `terminalPlugin` (the terminal's data), `api`, `whatsapp` |
116
+ | `copilotz/plugins/interfaces` | `terminalPlugin` (the terminal's data), `api`, `whatsapp`, `voice`, `mcp`, `maintenance` |
117
117
  | `copilotz/plugins/interfaces/web` | `webShell` (the web's root View), `apiWeb`, `whatsappWeb` |
118
118
  | `copilotz/plugins/interfaces/terminal` | `terminalShell`: the terminal's root View |
119
119
  | `copilotz/web` | the web host in the browser (`web`), and its toolkit (`Button`, `Markdown`…) |
120
- | `copilotz/web/server` | its server half: `webServer`, `socket` |
120
+ | `copilotz/web/server` | its server half: `webServer`, `socket`; `routeHost` (the app's routes alone) |
121
121
  | `copilotz/web/tickets` | `createTickets`: sessions traded for one-time tickets |
122
122
  | `copilotz/web/theme` | `themeOf(plugins)`: the app's theme, for the page's first paint |
123
- | `copilotz/web/node` | `bundle` (the browser's code, with esbuild), `serve`, `listen` (HTTP, sockets) |
123
+ | `copilotz/web/node` | `bundle` (the browser's code, with esbuild), `serve`, `serveRoutes`, `listen` (HTTP, sockets) |
124
124
  | `copilotz/orgs` | `orgsHost`: many orgs behind one address, each a runtime of its own |
125
125
  | `copilotz/terminal` | the terminal host: `terminal({ runtime, me })`, and its toolkit |
126
126
  | `copilotz/exporters` | `otlp`, `exposition`: metrics out, the OpenTelemetry way |
@@ -194,6 +194,48 @@ each socket to the runtime of the org its request is for:
194
194
  `listen({ fetch: host.serve, hypervisor: (request) => host.openRuntime(request)?.hypervisor })`
195
195
  (`examples/web-node/orgs.ts`).
196
196
 
197
+ ### Without the web app
198
+
199
+ An app people use on WhatsApp or on the phone needs no page: `serveRoutes` serves its plugins'
200
+ routes alone (`routes` resources: Meta's webhook, Twilio's), `GET /health` for whatever watches it,
201
+ and 404 for anything else. Nobody signs in there: a route's Action is called as a visitor, and its
202
+ `allow` decides (a webhook checks the request's signature, then acts for the person it's from with
203
+ `ctx.as`). Deno and Bun run it too.
204
+
205
+ ```ts
206
+ import { createRuntime } from "copilotz";
207
+ import { serveRoutes } from "copilotz/web/node";
208
+
209
+ const runtime = await createRuntime({ store, plugins });
210
+ const server = await serveRoutes({ runtime, hostname: "0.0.0.0", port: 8080 });
211
+ // A deploy's SIGTERM: stop listening, give running turns a while, close the runtime.
212
+ process.once("SIGTERM", () => server.close({ drain: 8_000 }));
213
+ ```
214
+
215
+ A `serve` route may take a WebSocket of its own (a voice call's relay): `host.upgrade()` accepts the
216
+ request's upgrade, and the route answers with the response it gives. It can refuse first (`403`,
217
+ before any handshake). The socket is a browser's `WebSocket` as far as `onmessage`, `send` and
218
+ `close` go; the listener (`serveRoutes`, or the web host's `serve`) takes it.
219
+
220
+ ```ts
221
+ routes: {
222
+ relay: {
223
+ path: "/voice/relay",
224
+ serve: (request, host) => {
225
+ if (!signed(request)) return new Response("Forbidden", { status: 403 });
226
+ const { socket, response } = host.upgrade();
227
+ socket.onmessage = async (event) => socket.send(await answer(host.runtime, event.data));
228
+ return response;
229
+ },
230
+ },
231
+ },
232
+ ```
233
+
234
+ A runtime that declares the `socket` transport (remote executors) still takes its sockets at
235
+ `/oxian`. `routeHost(runtime)` (`copilotz/web/server`) is the same as a fetch handler, for another
236
+ listener; a route's socket needs Oxian's (`copilotz/web/node`'s). The example is
237
+ `examples/web-node/routes.ts`.
238
+
197
239
  ## Installing a computer
198
240
 
199
241
  People's computers run the computer program (`plugins/compute/computers/program/`), a single
@@ -205,7 +247,7 @@ and an app serves it from there by default:
205
247
  import { computerDownloads } from "copilotz/plugins/compute/downloads";
206
248
 
207
249
  plugins: [...plugins, await computerDownloads()], // this Copilotz's release
208
- plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.20" })], // its own: /computer/download/
250
+ plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.21" })], // its own: /computer/download/
209
251
  plugins: [...plugins, await computerDownloads({ url: "https://downloads.example.com/computer/" })], // or elsewhere
210
252
  ```
211
253
 
@@ -313,6 +355,14 @@ name, never by importing its code.
313
355
  last four hours of a conversation, back from its newest message (summaries too, with `history`);
314
356
  what's older stays in the chat. The start moves in steps of a tenth of `maxAge`, so prompts keep
315
357
  hitting the provider's cache ([design](design/views.md#history-as-views)).
358
+ - **A tool call runs once:** before a step's tools run, the step's calls are written (an
359
+ `intent`), and what each returns as soon as it does. A retried turn (it failed after its tools
360
+ ran, its executor died, the runtime restarted) goes on with those calls instead of asking its
361
+ model again: a call that returned isn't run again, and one cut short runs again as itself, with
362
+ the same `ctx.callId` and `ctx.retry` true. Pass `callId` to an outside API as the idempotency
363
+ key, or call recorded Actions (they answer from the log), and a payment behind a tool is made
364
+ once. A turn that ends without its step (failed for good, stopped) keeps it, saying which calls
365
+ never returned, so people and its later turns know what happened.
316
366
  - **Subthreads are forks:** whoever works in one sees the conversation up to the message it hangs
317
367
  from, through every level, without anything being copied. A new thread starts from its first
318
368
  message and records the thread it came from.
@@ -331,6 +381,16 @@ name, never by importing its code.
331
381
  the `transcribe` model alias), and agents read the transcript. If it fails nothing is sent
332
382
  (`transcription_failed`); `transcribe: false` sends audio as it is. A voice message may say
333
383
  nothing else; its file carries `voice` (duration, peaks) for its player.
384
+ - **In spaces:** chat declares its own `shared` entries (threads, messages with labels, files,
385
+ what's being written), so an app with the access plugin needn't. A chat's messages, files and
386
+ live writing are part of it (`part: "thread"`): shared on its own (with a contact), its parts
387
+ come with it. `chat.open` opens an empty chat in a space; `chat.say` has an agent say a fixed
388
+ message there without a turn (trusted code only: a payment confirmed), which goes out like any
389
+ of its answers.
390
+ - **After an answer:** a medium that can (WhatsApp) shows features' additions
391
+ (`resources.additions.<name> = { order?, agents? }` and an `addition:<name>` View there), each
392
+ once per chat per key, recorded in `shown`; the model is told what went (`[then shown: …]`). A
393
+ message tapped from a button carries `tap: { id, title, key }`, and agents read the id.
334
394
  - **`history`** keeps chat history from outgrowing the prompt
335
395
  (`resources: { history: { summarizer: "openai/gpt-5.4-mini" } }`): every message stays whole, a
336
396
  cheap model writes a line for each and merges pairs up a binary tree, and an agent gets recent
@@ -386,6 +446,12 @@ name, never by importing its code.
386
446
  it's one; a new space has the app's default agents. An answer drawn from a space not everyone in
387
447
  the conversation can see shows only to those who see both, marked, until someone shares it.
388
448
  - **`identity`**: people, sessions and keys, and who a secret proves.
449
+ - **`contacts`**: people outside the org who talk to its agents (a WhatsApp customer). A contact is
450
+ its own kind of actor (`{ kind: "contact", id }`), never a person: every Action and query stays
451
+ shut to it unless it says otherwise (`peopleOrContacts`, as `chat.send` does). Its chat lives in
452
+ the line's space and is shared with it on its own: it reaches that chat, what's said and filed
453
+ there, and nothing else; the space's people reach it as any chat there, and the agent working for
454
+ the contact reaches exactly that chat. Agents are told whom they're talking with.
389
455
  - **`googleSignIn`**: sign-in with a Google ID token (the `google` resource names your client).
390
456
  - **`accounts`**: outside accounts a person connects once, for their agents to use: first their
391
457
  ChatGPT plan, as a model provider, instead of the app's API key. Tokens are a private field only
@@ -459,7 +525,42 @@ filled by the front ends through resources).
459
525
  server-sent events, as that person, in that space only.
460
526
  - **`whatsapp`**: people talk to their agents from WhatsApp, through Meta's Cloud API. A space's
461
527
  managers connect a number; a person links their phone with a code; what they send becomes their
462
- messages, and what agents say to them goes back, a long answer in several messages.
528
+ messages, and what agents say to them goes back, a long answer in several messages. It's a medium
529
+ for Views (renderer `whatsapp`, parts built with its toolkit: text, buttons, a list, a carousel,
530
+ an image, a document, each checked against Meta's limits): after an answer, features show more
531
+ (`additions`: a carousel of trips, buttons to pay), once per chat per key, the answer's text in
532
+ the same message when there's room, a fallback when Meta refuses one; taps come back with their
533
+ ids. Pictures and files go as public links, signed links to the app's routes or files (the `links`
534
+ resource, `{ origin, secret }`; the runtime's `signLink`, `verifyLink`), or uploads. Opened to
535
+ anyone (`whatsapp.set`, or declared in the app's settings: `whatsapp.lines`), a number is a
536
+ customer line: a stranger who writes is a contact, in a chat of their own in the number's space,
537
+ answered by its agent, and a chat quiet for the number's `gap` (12 hours) is over: their next
538
+ message starts a new one.
539
+ - **`voice`**: people call the app's phone number and talk to its agents, through Twilio's
540
+ ConversationRelay (Twilio hears them and speaks; the app gets and sends text). The app declares
541
+ its lines (`voice.lines`: the space, Twilio's account and auth token, the app's public address,
542
+ the agent, language, voice, greeting and limits); Twilio's webhook is checked against its
543
+ signature, a call is taken within its caller's limits and the line's (calls at once, a day: else
544
+ busy, nothing spent) and opens the line's socket with a one-time ticket. A caller is a contact in
545
+ a chat of their own, the same one when they call back only if Twilio verified their number; what
546
+ the agent writes for them is said as it writes it (a medium for Views: renderer `voice`), a caller
547
+ speaking over it cuts it there (the agent is told what was heard), a failed or slow answer says a
548
+ short line in the line's language, and silence, a call too long or too many prompts, or the
549
+ agent's `end_call` end it. Managers block a caller (`voice.block`). Its socket needs a host that
550
+ takes a route's socket (`serveRoutes`).
551
+ - **`mcp`**: models outside the app (ChatGPT, Claude, any MCP client) call its tools. A line the app
552
+ declares (`mcp.lines.<name>`: its space, the tools it lists, each with its `tool:<name>` View, how
553
+ each is shown, who calls, its limits) is an MCP server at `POST /mcp/<name>`: Streamable HTTP,
554
+ JSON-RPC 2.0, no session, MCP 2026-07-28 and the versions with a handshake. Each conversation
555
+ (ChatGPT's `openai/session`, or a `chat` handle the app gives a client that names none) is a
556
+ contact in a chat of its own in the line's space, its ids an HMAC with the `links` secret. A call
557
+ runs the tool through chat's runner as that contact, is written there as a step, and answers what
558
+ the app's agents read of it (only public errors say their words); a request sent again to a tool
559
+ that changes things is answered from the first, and the line's limits (calls at once, a minute,
560
+ new conversations an hour, by conversation, user, caller's address and in all) refuse the rest.
561
+ - **`maintenance`**: HTTP for an app's operators when they can't reach its database, with one key:
562
+ read SQL, the collections' operations through the owner, raw SQL writes inside it, blobs by id
563
+ (see [Maintenance](#maintenance)).
463
564
 
464
565
  **Metrics** (`copilotz/exporters`): what the runtime and plugins do, measured. There's no plugin to
465
566
  add: each plugin instruments itself.
@@ -536,6 +637,161 @@ org's rows copy elsewhere unchanged (`copyTenant`). Blobs (strings over 16 KiB,
536
637
  live in the store by default, or as files (`fileBlobs`), in a bucket (`httpBlobs`), or in Google
537
638
  Cloud Storage (`gcsBlobs`).
538
639
 
640
+ ## Maintenance
641
+
642
+ When an app's operators can't reach its database (a client's network that keeps their database user
643
+ out), the `maintenance` plugin (`copilotz/plugins/interfaces`) answers for it over HTTP, under
644
+ `/maintenance/`, with a key the app gives it:
645
+ `resources: { maintenance: { key: process.env.MAINTENANCE_KEY } }`. It's the one place an app runs
646
+ SQL of its own: plugin code never does.
647
+
648
+ ```sh
649
+ curl https://app.example.com/maintenance/sql -H "authorization: Bearer $KEY" \
650
+ -d '{"sql": "SELECT _id, text FROM message WHERE thread = $1", "params": ["t1"]}'
651
+ ```
652
+
653
+ | Endpoint | What it does |
654
+ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
655
+ | `GET /maintenance/` | What's here: whether the store runs SQL, the collections, the limits |
656
+ | `POST /maintenance/sql` | `{ sql, params?, limit?, timeout? }`: one read-only statement: `{ rows, count, truncated, ms }` |
657
+ | `POST /maintenance/sql/write` | `{ sql, params?, limit?, timeout? }`: one that writes, in the owner: `{ changed, rows, event }` |
658
+ | `POST /maintenance/collections/<collection>/<op>` | `insertOne` `{ doc }`… `deleteMany` `{ filter }`, and `find`, `findOne`, `countDocuments`, `aggregate` |
659
+ | `POST /maintenance/queries/<collection>.<name>` | A collection's named query (`booking.stats`), the body its params: `{ result, ms }` |
660
+ | `GET /maintenance/blobs/<sha256-…>` | A blob's bytes and type, as a download |
661
+
662
+ - **Keys:** `key`, or several in `keys` while one rotates (add the new, move clients, drop the old).
663
+ Each is at least 32 random characters: a short one, or one plainly not random, stops the app from
664
+ starting. Every request shows one (`Authorization: Bearer <key>`), compared in constant time;
665
+ without a key configured, every request is unauthorized, the same answer as a wrong key.
666
+ - **Who:** a request acts as the maintenance actor
667
+ (`{ kind: "maintenance", id: "maintenance", by }`, `by` from `X-Maintenance-By`, as said). Its
668
+ Actions let only it call them, and run as the system on the record (`ctx.as()`): no rule keeps it
669
+ from a document, and every event says `via` it. Writes take an `Idempotency-Key`: sent again, one
670
+ answers what it did the first time.
671
+ - **On record twice:** before it runs, each request writes a line (`log`, by default JSON on
672
+ standard output, which Cloud Run keeps): who, what (a statement's SHA-256, its params' count; an
673
+ operation, a query, a blob), which key, when. A SQL write also records a `maintenance.sql` event
674
+ in the same commit. The line is the record the key's holder can't rewrite.
675
+ - **Limits:** `limit` rows (1,000), `timeout` ms (30 s) and `bytes` of rows in an answer (8 MB; past
676
+ it the rows are cut, and `truncated` says so). A request may ask for less. A pipeline stops at the
677
+ limit too.
678
+ - **Operations go through the owner's write path:** checked against the collection's schema,
679
+ recorded as its events, cached and heard by Processors like any write. Prefer them. Named queries
680
+ run as the system does them (`runtime.query` with no actor), and check their own params.
681
+ - **Read SQL** is one statement (a `;` outside its strings and comments ends it; PostgreSQL's line
682
+ comments end at a CR too, and maintenance reads strings with `standard_conforming_strings` on) in
683
+ a read-only transaction, always rolled back, stopped at its limit and cut off at its timeout.
684
+ - **Raw SQL writes run inside the owner** (`runtime.maintenance.write`, see `runtime/maintain.ts`),
685
+ for what operations can't do: alone among its writes (those running end first, the next wait for
686
+ it), in a transaction fenced by its epoch, so an owner that lost the store can't run one, with its
687
+ `maintenance.sql` event in the same commit (the statement, its params, the rows it changed in any
688
+ table, who). It bypasses schemas and per-document events, so the owner then forgets what it
689
+ derived from documents: its cache empties, observed Views run again, and the clock reads the
690
+ timers again. A statement that ends or nests its transaction (`COMMIT`, `SAVEPOINT`…) or changes
691
+ its connection (`SET`, `PREPARE`, `LISTEN`, SQLite's `ATTACH`, `PRAGMA`…) doesn't run, and in
692
+ PostgreSQL neither does one that reaches past the statement: `ALTER ROLE` (a role may set its own
693
+ password and settings, which outlive the key), `DO` (a block runs statements nothing reads first)
694
+ and `LOCK` (it would hold the store's tables against the app's own writes). A write still holds
695
+ the row locks it takes (the rows an `UPDATE` changes) until it commits: app writes to those rows
696
+ wait, at most its `timeout`, and with at most 2 maintenance statements at once. One that changes
697
+ the store's own state (`meta`: the fencing epoch, Processors' positions), or what the role holds
698
+ (a large object, a setting), or, in SQLite, leaves a temporary object, is rolled back. The record
699
+ keeps a password literal as `PASSWORD '***'`.
700
+ - **Nothing outlives its statement:** on a PostgreSQL server each statement runs on a connection of
701
+ its own, closed after, so what it sets on its session (a setting, a session lock, a prepared
702
+ statement) goes with it; and it goes over the extended protocol, where the server refuses a second
703
+ statement whatever the check said. PGlite has one session: it forgets what maintenance left there
704
+ (`DISCARD ALL`). A SQLite read runs apart, in a process of this runtime of its own on a read-only
705
+ connection, killed at its timeout: a statement that never ends doesn't hold the app, a core or the
706
+ WAL. The process is `deno`, `node` or `bun` itself (never a compiled app, which would be the app
707
+ again), with an empty environment, and on Deno and Node allowed to read the database's files and
708
+ nothing else; on Deno it's started only with permission to run already granted, so nothing ever
709
+ asks mid-request. Where none can start (a database opened another way, `:memory:`, a compiled app,
710
+ no permission), reads run on the store's reading connection, one at a time, with no timeout, a
711
+ pragma only from those that only read: the store says so once, with why, and each such answer says
712
+ `inline: true`. SQLite writes name the store's tables in `main`, so nothing temporary stands in
713
+ for them. Each store runs at most 2 maintenance statements at once
714
+ (`maintenance: { connections }`): another answers busy (503).
715
+ - **Where:** SQL needs a SQL store. On a PostgreSQL server only as a role of its own (below), never
716
+ in a schema other tenants share; PGlite, in the app's process, runs it as its one session where it
717
+ reaches no other schema. An orgs host's orgs don't get the plugin at all (one key would reach
718
+ every org). Operations, named queries and blobs work everywhere, the memory store too, and need no
719
+ role.
720
+
721
+ ### A role of its own
722
+
723
+ On a PostgreSQL server, raw SQL runs only as a role of its own, named by the store:
724
+ `postgresStore({ url, schema, maintenance: { url: process.env.MAINTENANCE_DATABASE_URL } })`.
725
+ Without one it's refused. The store's role owns the tables, may stop the app's connections and is
726
+ whatever the deployment made it (a superuser, even): nothing that runs at a key's word should be it.
727
+
728
+ Before each statement, on the connection that runs it, and again after a write in its transaction,
729
+ maintenance checks that the role holds exactly what the SQL below grants, and refuses it otherwise
730
+ (rolling a write back), saying what's more: an attribute beyond `LOGIN` (superuser, `CREATEROLE`…);
731
+ membership in any role at all, predefined (`pg_*`) or not, and whatever its `INHERIT` or `SET`
732
+ options (a member could `SET ROLE` to it); settings of its own (`ALTER ROLE … SET`); anything it
733
+ owns, a large object too (what it makes for its own session, a temporary table, goes with its
734
+ connection); anything granted to it outside the store's schema and database; `CREATE` on any schema
735
+ (`public` too) or on the database; any privilege on a table or a column of another schema; on the
736
+ store's own tables, anything beyond the grants below (no `TRIGGER`, `TRUNCATE` or `REFERENCES`; on
737
+ `events` only `INSERT`); a large object it may read (`lo_compat_privileges`, or one granted to
738
+ `PUBLIC`); a `SECURITY DEFINER` function it may run (one runs as its owner); `dblink` or
739
+ `postgres_fdw` in the database; and a trigger on the store's tables, which the store never makes.
740
+ The checks name every catalog they read as `pg_catalog`'s, after setting the search path back to it,
741
+ so nothing a statement made stands in for them.
742
+
743
+ Prefer a role with no password at all, signed in by the platform: Cloud SQL's IAM database
744
+ authentication, or a client certificate. A password is a second key, valid for as long as nobody
745
+ changes it. On Cloud SQL, with a service account of its own for maintenance:
746
+
747
+ ```sh
748
+ gcloud sql users create maintenance@PROJECT.iam --instance=INSTANCE --type=cloud_iam_service_account
749
+ gcloud projects add-iam-policy-binding PROJECT \
750
+ --member=serviceAccount:maintenance@PROJECT.iam.gserviceaccount.com \
751
+ --role=roles/cloudsql.instanceUser # and roles/cloudsql.client, to connect
752
+ # The app reaches it through the Cloud SQL Auth Proxy, which signs it in (no password):
753
+ # cloud-sql-proxy --auto-iam-authn --impersonate-service-account=maintenance@PROJECT.iam.gserviceaccount.com \
754
+ # --port 5433 PROJECT:REGION:INSTANCE
755
+ # MAINTENANCE_DATABASE_URL=postgres://maintenance%40PROJECT.iam@127.0.0.1:5433/DATABASE
756
+ ```
757
+
758
+ Cloud SQL makes such a role a member of its own marker role (`cloudsqliamserviceaccount`, or
759
+ `cloudsqliamuser` for a person): that one membership is allowed, without ADMIN OPTION. Every IAM
760
+ user is a member of the marker too, so the marker may hold nothing at all: grant it nothing, not
761
+ even the grants below (maintenance refuses a marker that holds anything). Then the grants below,
762
+ naming `"maintenance@PROJECT.iam"`.
763
+
764
+ Elsewhere, as the store's role (the schema's owner), with the schema made (the app has started
765
+ once), and as a role that may create roles for the first line:
766
+
767
+ ```sql
768
+ -- LOGIN and nothing else; never grant it a role. (On Cloud SQL with IAM, gcloud makes it.)
769
+ CREATE ROLE copilotz_maintenance LOGIN PASSWORD '…' NOINHERIT;
770
+ GRANT USAGE ON SCHEMA copilotz TO copilotz_maintenance;
771
+ -- Reading everything there, the collections' views too, now and later.
772
+ GRANT SELECT ON ALL TABLES IN SCHEMA copilotz TO copilotz_maintenance;
773
+ ALTER DEFAULT PRIVILEGES IN SCHEMA copilotz GRANT SELECT ON TABLES TO copilotz_maintenance;
774
+ -- Changing documents, edges, vectors and blobs.
775
+ GRANT INSERT, UPDATE, DELETE ON copilotz.nodes, copilotz.edges, copilotz.vectors, copilotz.blobs
776
+ TO copilotz_maintenance;
777
+ -- Appending to the log (its own audit events), never changing it.
778
+ GRANT INSERT ON copilotz.events TO copilotz_maintenance;
779
+ -- Holding the fence while it writes (FOR SHARE needs it); a statement that changes meta is rolled back.
780
+ GRANT UPDATE (value) ON copilotz.meta TO copilotz_maintenance;
781
+ -- PostgreSQL 14 and earlier let everyone create in public.
782
+ REVOKE CREATE ON SCHEMA public FROM PUBLIC;
783
+ ```
784
+
785
+ Replace `copilotz` with the store's schema. `PUBLIC` keeps `CONNECT` on the database, `TEMPORARY`,
786
+ and `USAGE` on `public`; those are allowed. A `SECURITY DEFINER` function can be run by everyone
787
+ (`PUBLIC`) unless revoked: find them, and revoke it from each (or maintenance refuses, naming them):
788
+
789
+ ```sql
790
+ SELECT p.oid::regprocedure FROM pg_proc p WHERE p.prosecdef
791
+ AND p.pronamespace NOT IN ('pg_catalog'::regnamespace, 'information_schema'::regnamespace);
792
+ REVOKE EXECUTE ON FUNCTION some_schema.some_function(…) FROM PUBLIC;
793
+ ```
794
+
539
795
  ## The example app
540
796
 
541
797
  `examples/terminal-agent` is an app on all of it: an assistant and a researcher, notes in spaces,
@@ -573,7 +829,7 @@ connects a computer to it; `/approve once|thread|always|no` answers what agents
573
829
 
574
830
  Inside the chat: `/new`, `/threads`, `/open <n>`, `/history`, `/memories`, `/usage [all]`,
575
831
  `/metrics [name]` (with `OTEL_EXPORTER_OTLP_ENDPOINT` set, metrics also go to that collector),
576
- `/prompt [agent]`, `/fork`, `/retry`, `/events [n]`, `/stats`, `/sql <query>` (SQLite only),
832
+ `/prompt [agent]`, `/fork`, `/retry`, `/events [n]`, `/stats`, `/sql <query>` (a SQL store),
577
833
  `/quit`. Every turn prints its time, its database round trips, the jobs sent to executors and the
578
834
  calls they made back to the owner.
579
835
 
@@ -615,6 +871,14 @@ The log records what happened, with no bookkeeping tables beside it:
615
871
  completion is the only extra commit.
616
872
  - `started` records the call's own `startedAt`; `completed` and `failed` record its duration in
617
873
  `ms`. An event's `at` is its commit time. An action opts out with `record: false`.
874
+ - **Private fields** (`private: ["buyer", "passengers"]` on an Action, dot paths as a
875
+ collection's): its calls are recorded without them, in `started`'s input and `completed`'s
876
+ result alike, so personal data a call is given stays out of the log while the call is still
877
+ recorded and retried. Its `inputHash` (and a nested call's id) still covers the whole input: a
878
+ retry with the same input finds the call, and a changed one is a new call. That hash is in the
879
+ log: whoever knows the rest of an input could check a guess of a field easy to guess alone (a
880
+ CPF) against it. A result that had any is kept whole in `sys.results`, with the completion
881
+ (`private: true` there), so a retry answers with all of it.
618
882
  - **Retries.** The log is the receipt store; no other table holds them.
619
883
  - `runtime.call(action, input, { id })` makes a call retryable. If that id already completed, the
620
884
  call returns its recorded result without running; if it's still running, the call joins it;
@@ -632,6 +896,10 @@ The log records what happened, with no bookkeeping tables beside it:
632
896
  - **Processor deliveries:** every failed attempt records `processor.retried`
633
897
  `{ attempt, after, error }` before the next one. After the last attempt, `processor.failed`
634
898
  `{ attempts, error }` is the dead letter.
899
+ - **Closing:** `runtime.close()` starts no more deliveries or timer occurrences, and gives the
900
+ running ones `drain` ms to finish (`close({ drain })`, 5 s by default); what's still running
901
+ then stops where it is. A delivery that didn't finish keeps its Processor's cursor before its
902
+ event, so the next owner delivers it again, with `retry`: a deploy never drops one.
635
903
  - **Outside effects (payments, emails, outside APIs):** write the intent first, call out with its
636
904
  id as the idempotency key, then write the result. The intent's commit carries the call's start,
637
905
  so the attempt is on record before anything leaves the system.
@@ -642,7 +910,12 @@ The log records what happened, with no bookkeeping tables beside it:
642
910
  any event back to the request that started it.
643
911
  - **Blobs.** Strings over 16 KiB (configurable) are stored once, named by the hash of their content
644
912
  (`sha256-…`). Documents and events hold `{ $blob, size, type }` in their place. The owner moves
645
- values out on write and back in on read, so plugin code never sees a reference.
913
+ values out on write and back in on read, so plugin code never sees a reference. Only the owner
914
+ makes them: a `$blob` key anywhere in what plugin code writes, or in what an Action is called
915
+ with, is refused (`invalid`), and so is any part of an update's field path that starts with `$` or
916
+ is `__proto__` (an aggregate's `$group` names no `$…` field either). A path ends at a reference as
917
+ at a string. On read, only an exact reference (those three keys, a `sha256-<64 hex>` id) loads a
918
+ blob; any other object is data. Blob stores take no other id.
646
919
 
647
920
  ## Schedules
648
921
 
@@ -698,6 +971,8 @@ changed, a limited result lost a member, or an existing document newly matched a
698
971
  differs between stores); reads inside a transaction, which see the transaction's own writes.
699
972
  - **Freshness:** a read that raced a commit to its collection doesn't fill the cache, and a
700
973
  transaction's changes reach the cache only once committed, before its events go out.
974
+ - **Maintenance SQL** (see [Maintenance](#maintenance)) changes what the cache can't follow: the
975
+ owner empties it after one commits, and a read in flight across that fills nothing.
701
976
 
702
977
  `runtime/tests/cache.test.ts` checks every cached query against a direct store read after each of
703
978
  900 random writes, on every store. `createRuntime({ cache: false })` turns the cache off; `stats()`
@@ -794,8 +1069,8 @@ Copilotz runs on Node (first), Deno and Bun, and is built for Cloudflare Workers
794
1069
  beside the runtime, which declares the `socket` transport). A browser reads a collection directly
795
1070
  only when a rule speaks for it; anything else, through queries that let its person. Writes are
796
1071
  Actions. Plugins answer their own HTTP through the `routes` resource (a webhook, an OAuth
797
- callback, an API, a download), and files people sent are served at `/files/<id>` to whoever may
798
- read them, with ranges.
1072
+ callback, an API, a download, a socket of their own), and files people sent are served at
1073
+ `/files/<id>` to whoever may read them, with ranges.
799
1074
  - **The design system** (`design/views.md`, "The design system"): the web host owns a token
800
1075
  vocabulary (shadcn's names) and its defaults, which are Copilotz's look (navy, the logo's cyan and
801
1076
  blue, Manrope and Space Grotesk, its logo and icon), and an app rebrands with a `theme` resource
@@ -840,7 +1115,8 @@ Copilotz runs on Node (first), Deno and Bun, and is built for Cloudflare Workers
840
1115
  system, which no rule restricts; its events say `via` whom.
841
1116
  - Remote executors prove the deployment key, compared in constant time.
842
1117
  - **Private fields** (`private: ["token"]` on a collection): what an actor's queries and Views
843
- read comes without them; Actions and Processors acting for them still read them.
1118
+ read comes without them; Actions and Processors acting for them still read them. No event holds
1119
+ them, on any store, and none holds an Action's (`private: ["buyer"]`) either.
844
1120
  - **Processors:** per-key ordering, a durable cursor, at-least-once delivery, made idempotent by
845
1121
  deterministic ids. A `where` MongoDB filter on event data keeps unwanted events from being
846
1122
  dispatched at all.
@@ -872,7 +1148,7 @@ plugins/ the features, by theme
872
1148
  directory of orgs
873
1149
  compute/ computers: desks per space, agents' tools, approvals; program/, the computer program
874
1150
  interfaces/ terminal (where each person is, the shell View), web (the web shell), the developer
875
- API and WhatsApp; features'
1151
+ API, WhatsApp, voice (phone calls), MCP and maintenance; features'
876
1152
  own front ends live with them (chat/terminal.ts, chat/web.tsx…), gathered by theme
877
1153
  hosts/ the media the app is used through: terminal (the Ink host and its toolkit); web
878
1154
  (the React host in the browser: theme/, the tokens and their defaults, Copilotz's
@@ -100,6 +100,9 @@ export type OrgsHost = {
100
100
  serve(request: Request): Promise<Response>;
101
101
  openRuntime(request: Request): Runtime | undefined;
102
102
  runtime(org: string): Promise<Runtime | undefined>;
103
- close(): Promise<void>;
103
+ /** Closes every open org, each giving its running work `drain` ms (see `Runtime.close`). */
104
+ close(options?: {
105
+ drain?: number;
106
+ }): Promise<void>;
104
107
  };
105
108
  export declare function orgsHost(options: OrgsHostOptions): OrgsHost;
package/hosts/orgs/mod.js CHANGED
@@ -631,12 +631,12 @@ export function orgsHost(options) {
631
631
  const info = await orgInfo(org);
632
632
  return info ? (await cellOf(info)).runtime : undefined;
633
633
  },
634
- async close() {
634
+ async close(options) {
635
635
  clearInterval(sweep);
636
636
  live.clear();
637
637
  const open = await Promise.all([...cells.values()].map((c) => c.catch(() => undefined)));
638
638
  cells.clear();
639
- await Promise.all(open.map((cell) => cell?.runtime.close().catch(() => { })));
639
+ await Promise.all(open.map((cell) => cell?.runtime.close(options).catch(() => { })));
640
640
  },
641
641
  };
642
642
  }
@@ -13,12 +13,16 @@
13
13
  * file opened on its own (an SVG, an HTML page someone sent) runs no script.
14
14
  * - **Kept privately:** a file never changes once sent; a browser may keep it,
15
15
  * a shared cache may not.
16
+ * - **A signed link** (`/files/<id>?exp=…&sig=…`, the runtime's `signLink`
17
+ * with the app's `links` secret) is served without anyone signed in, as
18
+ * the system: code that could read the file signed it, to send it on
19
+ * (WhatsApp fetches a picture from it). Expired or altered, it's a 404.
16
20
  */
17
- import type { Actor, Runtime } from "../../runtime/mod.js";
21
+ import { type Actor, type Runtime } from "../../runtime/mod.js";
18
22
  /** Where files are served. */
19
23
  export declare const FILES = "/files/";
20
24
  /**
21
25
  * Serves `GET` and `HEAD /files/<id>` as `whom(request)` (the signed-in
22
26
  * person, if any); any other request gets undefined, for the app's routes.
23
27
  */
24
- export declare function fileServer(runtime: Pick<Runtime, "query">, whom: (request: Request) => Promise<Actor | null>): (request: Request) => Promise<Response> | undefined;
28
+ export declare function fileServer(runtime: Pick<Runtime, "query" | "describe">, whom: (request: Request) => Promise<Actor | null>): (request: Request) => Promise<Response> | undefined;
@@ -1,3 +1,24 @@
1
+ /**
2
+ * Files people sent, as the web serves them (`GET /files/<id>`): an image's
3
+ * picture, a voice message's sound, a download. Each is read as the person
4
+ * signed in (chat's `file.content` query), so the rules decide who gets it:
5
+ * nobody signed in, or a file out of their reach, is a 404 alike.
6
+ *
7
+ * - **Ranges:** `Range: bytes=…` answers with that part (206), which Safari
8
+ * needs to play audio and seek it.
9
+ * - **Inline or saved:** images, audio, video and PDFs show where they're
10
+ * linked; anything else, or any file with `?download=1`, is saved under its
11
+ * name.
12
+ * - **Nothing runs:** every answer says `nosniff` and a sandboxed policy, so a
13
+ * file opened on its own (an SVG, an HTML page someone sent) runs no script.
14
+ * - **Kept privately:** a file never changes once sent; a browser may keep it,
15
+ * a shared cache may not.
16
+ * - **A signed link** (`/files/<id>?exp=…&sig=…`, the runtime's `signLink`
17
+ * with the app's `links` secret) is served without anyone signed in, as
18
+ * the system: code that could read the file signed it, to send it on
19
+ * (WhatsApp fetches a picture from it). Expired or altered, it's a 404.
20
+ */
21
+ import { linksOf, verifyLink } from "../../runtime/mod.js";
1
22
  /** Where files are served. */
2
23
  export const FILES = "/files/";
3
24
  const SAFE = {
@@ -31,6 +52,16 @@ function range(header, size) {
31
52
  * person, if any); any other request gets undefined, for the app's routes.
32
53
  */
33
54
  export function fileServer(runtime, whom) {
55
+ // The app's links, checked as the server starts (a secret too short is refused now, not per file).
56
+ const links = linksOf(runtime.describe().resources);
57
+ /** Whether a request is a link signed for its file: then the system reads it. */
58
+ const signed = async (url) => {
59
+ if (!url.searchParams.has("sig"))
60
+ return false;
61
+ const query = Object.fromEntries(url.searchParams);
62
+ delete query.download;
63
+ return !!links && !!await verifyLink(links, url.pathname, query);
64
+ };
34
65
  return (request) => {
35
66
  const url = new URL(request.url);
36
67
  if (!url.pathname.startsWith(FILES))
@@ -45,9 +76,11 @@ export function fileServer(runtime, whom) {
45
76
  catch {
46
77
  return missing();
47
78
  }
48
- const actor = id ? await whom(request) : null;
49
- const file = actor
50
- ? await runtime.query("file.content", { id }, { actor }).catch(() => null)
79
+ const system = id ? await signed(url) : false;
80
+ const actor = id && !system ? await whom(request) : null;
81
+ const file = system || actor
82
+ ? await runtime.query("file.content", { id }, actor ? { actor } : {})
83
+ .catch(() => null)
51
84
  : null;
52
85
  if (!file)
53
86
  return missing();
@@ -26,4 +26,4 @@
26
26
  * ```
27
27
  */
28
28
  export { bundle, type BundleOptions } from "./bundle.js";
29
- export { listen, type Listener, type ListenOptions, serve, type ServeOptions } from "./serve.js";
29
+ export { listen, type Listener, type ListenOptions, type RouteListener, type RoutesOptions, serve, type ServeOptions, serveRoutes, } from "./serve.js";
@@ -26,4 +26,4 @@
26
26
  * ```
27
27
  */
28
28
  export { bundle } from "./bundle.js";
29
- export { listen, serve } from "./serve.js";
29
+ export { listen, serve, serveRoutes, } from "./serve.js";
@@ -7,11 +7,19 @@
7
7
  * through their Node compatibility.
8
8
  *
9
9
  * - `serve`: one runtime's web host (`webServer`), its socket to that runtime.
10
+ * - `serveRoutes`: an app without the web app (on WhatsApp, on the phone):
11
+ * its routes alone (`routeHost`), and `/health`.
10
12
  * - `listen`: any fetch handler, with the Hypervisor each socket goes to
11
13
  * picked per request: a host with a runtime per org names the one a request
12
14
  * is for (`hosts/orgs`: its `openRuntime`).
15
+ *
16
+ * A route may take a socket of its own (`host.upgrade()`, see `routes.ts`):
17
+ * any path but the runtime's goes to the handler, upgrades too, and Oxian's
18
+ * adapter takes the socket the handler accepts.
13
19
  */
14
20
  import type { Hypervisor } from "oxianjs";
21
+ import type { Runtime } from "../../../runtime/mod.js";
22
+ import { type Front } from "../routes.js";
15
23
  import { type WebServerOptions } from "../server.js";
16
24
  /** Where to listen. */
17
25
  type Address = {
@@ -42,11 +50,29 @@ export type Listener = {
42
50
  finished: Promise<void>;
43
51
  shutdown(): Promise<void>;
44
52
  };
53
+ export type RoutesOptions = Address & {
54
+ runtime: Runtime;
55
+ /** The app's front (a Cloudflare worker before it), as `webServer` takes it. */
56
+ front?: Front;
57
+ };
58
+ /** A route host listening. It owns its runtime: `close` stops listening, then closes it. */
59
+ export type RouteListener = Listener & {
60
+ /** Stops listening (its sockets close), then the runtime, passing `drain` on (`Runtime.close`). */
61
+ close(options?: {
62
+ drain?: number;
63
+ }): Promise<void>;
64
+ };
45
65
  /**
46
66
  * Serves the web host for a runtime that declares the `socket` transport
47
67
  * (`createRuntime({ transports: [socket], admit: tickets.admit })`).
48
68
  */
49
69
  export declare function serve(options: ServeOptions): Promise<Listener>;
70
+ /**
71
+ * Serves an app's routes alone (`routeHost`): its webhooks and sockets, and
72
+ * `/health`. Its runtime's own socket (`/oxian`, when it declares one: remote
73
+ * executors) goes to it, as `serve`'s does.
74
+ */
75
+ export declare function serveRoutes(options: RoutesOptions): Promise<RouteListener>;
50
76
  /** Serves a fetch handler, each socket going to the Hypervisor `hypervisor` picks for it. */
51
77
  export declare function listen(options: ListenOptions): Promise<Listener>;
52
78
  export {};