copilotz 1.0.0-rc.21 → 1.0.0-rc.23

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 (211) hide show
  1. package/CHANGELOG.md +320 -1
  2. package/README.md +217 -87
  3. package/hosts/orgs/mod.d.ts +33 -13
  4. package/hosts/orgs/mod.js +183 -84
  5. package/hosts/web/address.d.ts +11 -0
  6. package/hosts/web/address.js +46 -0
  7. package/hosts/web/assets.js +11 -5
  8. package/hosts/web/entrances.d.ts +250 -0
  9. package/hosts/web/entrances.js +362 -0
  10. package/hosts/web/host.d.ts +15 -3
  11. package/hosts/web/host.js +31 -18
  12. package/hosts/web/mod.d.ts +4 -2
  13. package/hosts/web/mod.js +6 -0
  14. package/hosts/web/node/bundle.d.ts +5 -0
  15. package/hosts/web/node/bundle.js +1 -1
  16. package/hosts/web/node/mod.d.ts +6 -4
  17. package/hosts/web/node/mod.js +6 -4
  18. package/hosts/web/node/serve.d.ts +20 -23
  19. package/hosts/web/node/serve.js +10 -21
  20. package/hosts/web/routes.d.ts +23 -17
  21. package/hosts/web/routes.js +56 -32
  22. package/hosts/web/server.d.ts +89 -44
  23. package/hosts/web/server.js +208 -108
  24. package/hosts/web/signin.d.ts +7 -10
  25. package/hosts/web/signin.js +6 -3
  26. package/hosts/web/surface.d.ts +20 -0
  27. package/hosts/web/surface.js +42 -0
  28. package/hosts/web/theme/css.d.ts +2 -1
  29. package/hosts/web/theme/css.js +9 -2
  30. package/hosts/web/tickets.d.ts +14 -1
  31. package/hosts/web/tickets.js +30 -7
  32. package/hosts/web/widget.d.ts +31 -0
  33. package/hosts/web/widget.js +429 -0
  34. package/hosts/web/widgets.d.ts +43 -0
  35. package/hosts/web/widgets.js +117 -0
  36. package/package.json +5 -1
  37. package/plugins/access/contacts/actions/forget.js +3 -1
  38. package/plugins/access/contacts/actions/start.js +18 -8
  39. package/plugins/access/contacts/collections/contact.d.ts +2 -2
  40. package/plugins/access/contacts/collections/contact.js +1 -1
  41. package/plugins/access/contacts/contract.d.ts +5 -5
  42. package/plugins/access/contacts/contract.js +5 -5
  43. package/plugins/access/contacts/mod.d.ts +4 -0
  44. package/plugins/access/contacts/mod.js +4 -0
  45. package/plugins/access/contacts/views/contact.js +1 -0
  46. package/plugins/access/dev/actions/sign-in.d.ts +1 -0
  47. package/plugins/access/dev/actions/sign-in.js +38 -0
  48. package/plugins/access/dev/mod.d.ts +17 -0
  49. package/plugins/access/dev/mod.js +31 -0
  50. package/plugins/access/dev/shared/nearby.d.ts +2 -0
  51. package/plugins/access/dev/shared/nearby.js +27 -0
  52. package/plugins/access/directory/actions/invite.js +2 -2
  53. package/plugins/access/directory/actions/org.js +11 -8
  54. package/plugins/access/directory/collections/credit-code.d.ts +1 -1
  55. package/plugins/access/google/actions/sign-in.js +2 -0
  56. package/plugins/access/google/mod.d.ts +4 -2
  57. package/plugins/access/google/mod.js +15 -2
  58. package/plugins/access/identity/actions/session.js +5 -3
  59. package/plugins/access/identity/mod.d.ts +4 -2
  60. package/plugins/access/identity/mod.js +17 -2
  61. package/plugins/access/mod.d.ts +7 -0
  62. package/plugins/access/mod.js +1 -0
  63. package/plugins/access/spaces/shared/declared.d.ts +1 -1
  64. package/plugins/access/spaces/shared/rules.d.ts +16 -5
  65. package/plugins/access/spaces/shared/rules.js +74 -6
  66. package/plugins/agents/chat/actions/send.d.ts +21 -0
  67. package/plugins/agents/chat/actions/send.js +72 -13
  68. package/plugins/agents/chat/collections/file.d.ts +15 -0
  69. package/plugins/agents/chat/collections/file.js +12 -3
  70. package/plugins/agents/chat/collections/live.d.ts +11 -0
  71. package/plugins/agents/chat/collections/live.js +11 -1
  72. package/plugins/agents/chat/collections/message.d.ts +1 -1
  73. package/plugins/agents/chat/collections/wait.d.ts +1 -1
  74. package/plugins/agents/chat/contract.d.ts +3 -2
  75. package/plugins/agents/chat/contract.js +1 -0
  76. package/plugins/agents/chat/mod.d.ts +9 -3
  77. package/plugins/agents/chat/mod.js +28 -7
  78. package/plugins/agents/chat/processors/failed.js +8 -3
  79. package/plugins/agents/chat/processors/turn.js +6 -3
  80. package/plugins/agents/chat/shared/agents.js +11 -2
  81. package/plugins/agents/chat/shared/live.d.ts +4 -2
  82. package/plugins/agents/chat/shared/live.js +2 -1
  83. package/plugins/agents/chat/shared/types.d.ts +8 -0
  84. package/plugins/agents/history/collections/outline.d.ts +2 -2
  85. package/plugins/agents/openapi/shared/files.js +2 -0
  86. package/plugins/agents/routines/collections/routine.d.ts +1 -1
  87. package/plugins/billing/credits/collections/plan.d.ts +2 -2
  88. package/plugins/billing/credits/collections/room.d.ts +1 -1
  89. package/plugins/billing/usage/collections/rollup.d.ts +2 -2
  90. package/plugins/billing/usage/collections/usage.d.ts +2 -2
  91. package/plugins/compute/cloud/actions/pool.js +2 -0
  92. package/plugins/compute/cloud/actions/remote.js +4 -2
  93. package/plugins/compute/cloud/actions/vms.js +2 -0
  94. package/plugins/compute/cloud/collections/pool-vm.d.ts +1 -1
  95. package/plugins/compute/computers/actions/admit.js +2 -0
  96. package/plugins/compute/computers/actions/code.js +2 -0
  97. package/plugins/compute/computers/actions/enrollment.js +2 -0
  98. package/plugins/compute/computers/actions/work.js +3 -0
  99. package/plugins/compute/computers/program/version.d.ts +1 -1
  100. package/plugins/compute/computers/program/version.js +1 -1
  101. package/plugins/compute/computers/resources/downloads.js +1 -1
  102. package/plugins/compute/computers/resources/previews.js +5 -2
  103. package/plugins/interfaces/maintenance/mod.d.ts +3 -1
  104. package/plugins/interfaces/maintenance/mod.js +3 -1
  105. package/plugins/interfaces/mcp/actions/call.d.ts +4 -0
  106. package/plugins/interfaces/mcp/actions/call.js +120 -18
  107. package/plugins/interfaces/mcp/actions/conversation.d.ts +1 -0
  108. package/plugins/interfaces/mcp/actions/conversation.js +49 -0
  109. package/plugins/interfaces/mcp/actions/prune.js +5 -3
  110. package/plugins/interfaces/mcp/collections/opening.d.ts +24 -0
  111. package/plugins/interfaces/mcp/collections/opening.js +28 -0
  112. package/plugins/interfaces/mcp/mod.d.ts +27 -3
  113. package/plugins/interfaces/mcp/mod.js +42 -7
  114. package/plugins/interfaces/mcp/resources/server.d.ts +13 -4
  115. package/plugins/interfaces/mcp/resources/server.js +163 -21
  116. package/plugins/interfaces/mcp/resources/tools.d.ts +88 -12
  117. package/plugins/interfaces/mcp/resources/tools.js +113 -19
  118. package/plugins/interfaces/mcp/resources/widgets.d.ts +161 -0
  119. package/plugins/interfaces/mcp/resources/widgets.js +246 -0
  120. package/plugins/interfaces/mcp/shared/keys.d.ts +25 -19
  121. package/plugins/interfaces/mcp/shared/keys.js +55 -9
  122. package/plugins/interfaces/mcp/shared/settings.d.ts +70 -37
  123. package/plugins/interfaces/mcp/shared/settings.js +64 -39
  124. package/plugins/interfaces/mcp/views/offered.d.ts +1 -1
  125. package/plugins/interfaces/mod.d.ts +2 -1
  126. package/plugins/interfaces/mod.js +2 -1
  127. package/plugins/interfaces/voice/collections/blocked.d.ts +2 -2
  128. package/plugins/interfaces/voice/collections/call.d.ts +3 -3
  129. package/plugins/interfaces/voice/contract.d.ts +1 -1
  130. package/plugins/interfaces/voice/mod.d.ts +3 -3
  131. package/plugins/interfaces/voice/mod.js +3 -3
  132. package/plugins/interfaces/voice/resources/relay.d.ts +5 -3
  133. package/plugins/interfaces/voice/resources/relay.js +17 -6
  134. package/plugins/interfaces/voice/resources/tools.js +2 -0
  135. package/plugins/interfaces/voice/shared/settings.d.ts +5 -0
  136. package/plugins/interfaces/voice/views/call.d.ts +18 -11
  137. package/plugins/interfaces/voice/views/call.js +15 -3
  138. package/plugins/interfaces/voice/views/message.d.ts +1 -1
  139. package/plugins/interfaces/web/actions/arrive.d.ts +1 -0
  140. package/plugins/interfaces/web/actions/arrive.js +120 -0
  141. package/plugins/interfaces/web/actions/prune.d.ts +1 -0
  142. package/plugins/interfaces/web/actions/prune.js +51 -0
  143. package/plugins/interfaces/web/actions/sending.d.ts +1 -0
  144. package/plugins/interfaces/web/actions/sending.js +222 -0
  145. package/plugins/interfaces/web/actions/spent.d.ts +2 -0
  146. package/plugins/interfaces/web/actions/spent.js +59 -0
  147. package/plugins/interfaces/web/collections/rate.d.ts +122 -0
  148. package/plugins/interfaces/web/collections/rate.js +37 -0
  149. package/plugins/interfaces/web/collections/visitor.d.ts +110 -0
  150. package/plugins/interfaces/web/collections/visitor.js +64 -0
  151. package/plugins/interfaces/web/contract.d.ts +4 -0
  152. package/plugins/interfaces/web/contract.js +1 -0
  153. package/plugins/interfaces/web/lines.d.ts +36 -0
  154. package/plugins/interfaces/web/lines.js +78 -0
  155. package/plugins/interfaces/web/processors/forget.d.ts +10 -0
  156. package/plugins/interfaces/web/processors/forget.js +14 -0
  157. package/plugins/interfaces/web/resources/entrance.d.ts +47 -0
  158. package/plugins/interfaces/web/resources/entrance.js +83 -0
  159. package/plugins/interfaces/web/resources/spend.d.ts +2 -0
  160. package/plugins/interfaces/web/resources/spend.js +62 -0
  161. package/plugins/interfaces/web/shared/budget.d.ts +65 -0
  162. package/plugins/interfaces/web/shared/budget.js +134 -0
  163. package/plugins/interfaces/web/shared/lines.d.ts +158 -0
  164. package/plugins/interfaces/web/shared/lines.js +156 -0
  165. package/plugins/interfaces/web/shared/secret.d.ts +33 -0
  166. package/plugins/interfaces/web/shared/secret.js +86 -0
  167. package/plugins/interfaces/whatsapp/collections/phone.d.ts +1 -1
  168. package/plugins/interfaces/whatsapp/mod.d.ts +1 -1
  169. package/plugins/interfaces/whatsapp/mod.js +1 -1
  170. package/plugins/interfaces/whatsapp/views/message.d.ts +1 -1
  171. package/plugins/models/contract.d.ts +1 -1
  172. package/plugins/models/shared/generate.js +13 -4
  173. package/plugins/models/shared/transcribe.js +7 -1
  174. package/plugins/models/shared/use.d.ts +16 -2
  175. package/plugins/models/shared/use.js +20 -0
  176. package/runtime/browsers.d.ts +153 -17
  177. package/runtime/browsers.js +336 -30
  178. package/runtime/cache.js +25 -5
  179. package/runtime/caller.d.ts +117 -0
  180. package/runtime/caller.js +215 -0
  181. package/runtime/client.d.ts +47 -3
  182. package/runtime/client.js +132 -42
  183. package/runtime/define.d.ts +30 -9
  184. package/runtime/executor.js +7 -6
  185. package/runtime/expiring.d.ts +23 -0
  186. package/runtime/expiring.js +64 -0
  187. package/runtime/links.d.ts +27 -4
  188. package/runtime/links.js +49 -11
  189. package/runtime/memory.js +102 -15
  190. package/runtime/mod.d.ts +3 -1
  191. package/runtime/mod.js +3 -1
  192. package/runtime/mongo.d.ts +12 -0
  193. package/runtime/mongo.js +44 -0
  194. package/runtime/observe.js +82 -9
  195. package/runtime/ops.d.ts +9 -1
  196. package/runtime/owner.d.ts +14 -1
  197. package/runtime/owner.js +78 -23
  198. package/runtime/reads.js +2 -2
  199. package/runtime/registry.js +9 -3
  200. package/runtime/runtime.d.ts +7 -0
  201. package/runtime/runtime.js +1 -0
  202. package/runtime/timers.js +2 -0
  203. package/runtime/views.d.ts +1 -1
  204. package/runtime/views.js +2 -2
  205. package/runtime/wire.d.ts +1 -1
  206. package/stores/sql/postgres/maintenance.d.ts +8 -1
  207. package/stores/sql/postgres/maintenance.js +76 -9
  208. package/stores/sql/postgres/mod.d.ts +12 -4
  209. package/stores/sql/postgres/mod.js +21 -8
  210. package/plugins/interfaces/mcp/shared/caller.d.ts +0 -45
  211. package/plugins/interfaces/mcp/shared/caller.js +0 -99
package/README.md CHANGED
@@ -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.21"`),
25
+ On Deno, name it `copilotz` in `deno.json` (`"copilotz": "jsr:@copilotz/copilotz@^1.0.0-rc.23"`),
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.
@@ -89,42 +89,43 @@ events. Time is a caller too: schedules call Actions (see Schedules).
89
89
 
90
90
  The package's entry points, the same names on npm (`copilotz/…`) and JSR (`@copilotz/copilotz/…`):
91
91
 
92
- | Import | What it has |
93
- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
94
- | `copilotz` | the runtime: `createRuntime`, `definePlugin`, `defineCollection`, `defineAction`… |
95
- | `copilotz/stores/memory` | `memoryStore()`: in memory, the reference |
96
- | `copilotz/stores/sqlite` | `sqliteStore({ path })`: `node:sqlite` or `bun:sqlite`, one file |
97
- | `copilotz/stores/postgres` | `postgresStore({ url, schema, tenant })` (a server, or PGlite in the process), `postgresPool`, `copyTenant`… |
98
- | `copilotz/stores/latency` | `withLatency(store, ms)`: a store with round trips, to measure |
99
- | `copilotz/blobs/files` | `fileBlobs({ dir })`: blobs as files |
100
- | `copilotz/blobs/http` | `httpBlobs({ url, headers })`: blobs in a bucket (S3, GCS, R2…) |
101
- | `copilotz/blobs/gcs` | `gcsBlobs({ bucket, prefix })`: blobs in a Google Cloud Storage bucket, as the instance's service account |
102
- | `copilotz/plugins/models` | `models`: llm, embeddings, transcription, the models.dev catalog |
103
- | `copilotz/plugins/agents` | `chat`, `history`, `memory`, `memoryExtraction`, `team`, `skills`, `routines`, `tiers`, `openapi`, `tool` |
104
- | `copilotz/plugins/agents/web` | their web front ends: `chatWeb`, `teamWeb`, `memoryWeb`, `skillsWeb`, `routinesWeb`, `tiersWeb` |
105
- | `copilotz/plugins/agents/terminal` | their terminal front ends: `chatTerminal`, `memoryTerminal` |
106
- | `copilotz/plugins/access` | `access` (`spaces`, `identity`, `contacts`), `accounts`, `directory`, `googleSignIn` |
107
- | `copilotz/plugins/access/web` | `spacesWeb`, `accountsWeb`, `contactsWeb` |
108
- | `copilotz/plugins/access/terminal` | `accessTerminal` |
109
- | `copilotz/plugins/billing` | `usage`: the ledger |
110
- | `copilotz/plugins/billing/web` | `usageWeb` |
111
- | `copilotz/plugins/billing/terminal` | `usageTerminal` |
112
- | `copilotz/plugins/compute` | `computers`: people's computers, where agents work |
113
- | `copilotz/plugins/compute/web` | `computersWeb` |
114
- | `copilotz/plugins/compute/terminal` | `computersTerminal` |
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`, `voice`, `mcp`, `maintenance` |
117
- | `copilotz/plugins/interfaces/web` | `webShell` (the web's root View), `apiWeb`, `whatsappWeb` |
118
- | `copilotz/plugins/interfaces/terminal` | `terminalShell`: the terminal's root View |
119
- | `copilotz/web` | the web host in the browser (`web`), and its toolkit (`Button`, `Markdown`…) |
120
- | `copilotz/web/server` | its server half: `webServer`, `socket`; `routeHost` (the app's routes alone) |
121
- | `copilotz/web/tickets` | `createTickets`: sessions traded for one-time tickets |
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`, `serveRoutes`, `listen` (HTTP, sockets) |
124
- | `copilotz/orgs` | `orgsHost`: many orgs behind one address, each a runtime of its own |
125
- | `copilotz/terminal` | the terminal host: `terminal({ runtime, me })`, and its toolkit |
126
- | `copilotz/exporters` | `otlp`, `exposition`: metrics out, the OpenTelemetry way |
127
- | `copilotz/testing` | one test API for Deno, Node and Bun (`test`, `tempDir`, `serve`…) |
92
+ | Import | What it has |
93
+ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
94
+ | `copilotz` | the runtime: `createRuntime`, `definePlugin`, `defineCollection`, `defineAction`… |
95
+ | `copilotz/stores/memory` | `memoryStore()`: in memory, the reference |
96
+ | `copilotz/stores/sqlite` | `sqliteStore({ path })`: `node:sqlite` or `bun:sqlite`, one file |
97
+ | `copilotz/stores/postgres` | `postgresStore({ url, schema, tenant })` (a server, or PGlite in the process), `postgresPool`, `copyTenant`… |
98
+ | `copilotz/stores/latency` | `withLatency(store, ms)`: a store with round trips, to measure |
99
+ | `copilotz/blobs/files` | `fileBlobs({ dir })`: blobs as files |
100
+ | `copilotz/blobs/http` | `httpBlobs({ url, headers })`: blobs in a bucket (S3, GCS, R2…) |
101
+ | `copilotz/blobs/gcs` | `gcsBlobs({ bucket, prefix })`: blobs in a Google Cloud Storage bucket, as the instance's service account |
102
+ | `copilotz/plugins/models` | `models`: llm, embeddings, transcription, the models.dev catalog |
103
+ | `copilotz/plugins/agents` | `chat`, `history`, `memory`, `memoryExtraction`, `team`, `skills`, `routines`, `tiers`, `openapi`, `tool` |
104
+ | `copilotz/plugins/agents/web` | their web front ends: `chatWeb`, `teamWeb`, `memoryWeb`, `skillsWeb`, `routinesWeb`, `tiersWeb` |
105
+ | `copilotz/plugins/agents/terminal` | their terminal front ends: `chatTerminal`, `memoryTerminal` |
106
+ | `copilotz/plugins/access` | `access` (`spaces`, `identity`, `contacts`), `accounts`, `directory`, `googleSignIn` |
107
+ | `copilotz/plugins/access/web` | `spacesWeb`, `accountsWeb`, `contactsWeb` |
108
+ | `copilotz/plugins/access/terminal` | `accessTerminal` |
109
+ | `copilotz/plugins/billing` | `usage`: the ledger |
110
+ | `copilotz/plugins/billing/web` | `usageWeb` |
111
+ | `copilotz/plugins/billing/terminal` | `usageTerminal` |
112
+ | `copilotz/plugins/compute` | `computers`: people's computers, where agents work |
113
+ | `copilotz/plugins/compute/web` | `computersWeb` |
114
+ | `copilotz/plugins/compute/terminal` | `computersTerminal` |
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`, `voice`, `mcp`, `maintenance` |
117
+ | `copilotz/plugins/interfaces/web` | `webShell` (the web's root View), `apiWeb`, `whatsappWeb` |
118
+ | `copilotz/plugins/interfaces/terminal` | `terminalShell`: the terminal's root View |
119
+ | `copilotz/web` | the web host in the browser (`web`), its toolkit (`Button`, `Markdown`…), what a widget asks (`display`…) |
120
+ | `copilotz/web/server` | its server half: `webServer`, `socket`, `widgetsOf`; the `Entrance`, `SignIn` and `Route` shapes plugins declare |
121
+ | `copilotz/web/widget` | the widget host: an app's web Views inside an outside assistant (`widget`, MCP Apps, ChatGPT) |
122
+ | `copilotz/web/tickets` | `createTickets`: sessions traded for one-time tickets |
123
+ | `copilotz/web/theme` | `themeOf(plugins)`: the app's theme, for the page's first paint |
124
+ | `copilotz/web/node` | `bundle` (the browser's code, with esbuild), `serve` (the one host), `listen` (HTTP, sockets) |
125
+ | `copilotz/orgs` | `orgsHost`: many orgs behind one address, each a runtime of its own |
126
+ | `copilotz/terminal` | the terminal host: `terminal({ runtime, me })`, and its toolkit |
127
+ | `copilotz/exporters` | `otlp`, `exposition`: metrics out, the OpenTelemetry way |
128
+ | `copilotz/testing` | one test API for Deno, Node and Bun (`test`, `tempDir`, `serve`…) |
128
129
 
129
130
  The browser loads only `copilotz/web`, the `…/web` front ends and what they import; every other
130
131
  entry point is for the process that runs the runtime (or the terminal). The npm package is
@@ -132,25 +133,46 @@ JavaScript with its types beside it, so an app's bundler takes the front ends as
132
133
 
133
134
  ## Serve it on the web
134
135
 
135
- The web host runs the app's front ends in the browser, as the person signed in: their reads go to
136
- the owner under the access rules, and every change is pushed to them as it commits. The server half
137
- answers `Request`s with `Response`s and nothing else, so it runs on any runtime; the page's code is
138
- the app's own (its front ends), bundled. On Node:
136
+ One host serves every app: `serve` (on Node, Bun and Deno; `webServer` beneath it is a fetch handler
137
+ for any runtime). What it does comes from the app's plugins, so the same call serves a signed-in
138
+ workspace, a public site where visitors chat with an agent, or a WhatsApp app with no page at all:
139
+
140
+ | Part | Comes from | Without it |
141
+ | -------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------- |
142
+ | Routes: webhooks, APIs, sockets of their own | the `routes` resource | — |
143
+ | The page and its code | `code`: the app's front ends, its shell among them, bundled | no page: the routes, and `/health` |
144
+ | Who a browser is | the `entrances` resource: identity's session (a person), web lines (a visitor) | nobody |
145
+ | Browsers connecting | `tickets`, for whoever an entrance says a request is | no browser connects |
146
+ | Signing in (`POST /signin/<name>`) | the `signIn` resource: `googleSignIn` (`google`), `devSignIn` (`dev`, this machine only) | none |
147
+
148
+ The host keeps every cookie: httpOnly, so the page's code never sees a session's secret, and
149
+ `Secure` anywhere but over plain http to this machine or one on its network (a private address, a
150
+ `.local` name), the session's named `__Host-session` there, so no other host under the domain (a
151
+ preview's) can set one. A page connects by trading its cookie for a one-time ticket (`/connect`,
152
+ which answers only the app's own page: its `Origin`), then talks to the owner over Oxian as an
153
+ untrusted worker bound to that actor, under the access rules. Signing in by name (`devSignIn`) is
154
+ for this machine only: the socket's address and the host must both be this machine's, with no header
155
+ a proxy adds, and an app whose `links` origin is public doesn't start with it. Signing out ends the
156
+ browsers connected as whoever it was. On Node:
139
157
 
140
158
  ```ts
141
159
  // server.ts
142
160
  import { createRuntime } from "copilotz";
143
161
  import { memoryStore } from "copilotz/stores/memory";
162
+ import { devSignIn } from "copilotz/plugins/access";
144
163
  import { socket } from "copilotz/web/server";
145
164
  import { createTickets } from "copilotz/web/tickets";
146
165
  import { themeOf } from "copilotz/web/theme";
147
166
  import { bundle, serve } from "copilotz/web/node";
148
167
  import { plugins } from "./app.ts"; // models, chat, access, … and the app's own
149
168
 
169
+ // This machine alone, unless HOST says (0.0.0.0: everyone's).
170
+ const hostname = process.env.HOST ?? "127.0.0.1";
150
171
  const tickets = createTickets();
151
172
  const runtime = await createRuntime({
152
173
  store: memoryStore(),
153
- plugins,
174
+ // Sign in by name: only while it listens on this machine alone.
175
+ plugins: [...plugins, ...(hostname === "127.0.0.1" ? [devSignIn] : [])],
154
176
  transports: [socket], // browsers connect to the owner here
155
177
  admit: tickets.admit,
156
178
  });
@@ -159,10 +181,12 @@ const server = await serve({
159
181
  tickets,
160
182
  code: await bundle(new URL("./browser.tsx", import.meta.url)),
161
183
  theme: themeOf([]), // Copilotz's look; a brand passes its theme plugins
184
+ hostname,
162
185
  port: 8080,
163
- dev: true, // sign in by name, from this machine only
164
186
  });
165
187
  console.log(`${server.url}`);
188
+ // A deploy's SIGTERM: stop listening, give running turns a while, close the runtime.
189
+ process.once("SIGTERM", () => server.close({ drain: 8_000 }));
166
190
  ```
167
191
 
168
192
  ```tsx
@@ -182,40 +206,104 @@ await web({
182
206
  ```
183
207
 
184
208
  `bundle` splits the code where it imports lazily (math, a terminal), and `serve` takes browsers'
185
- sockets through Oxian's Node adapter; Bun and Deno run it too. On Deno,
186
- `Deno.serve(webServer({ …, upgrade: handler(runtime.hypervisor) }))` with Oxian's Deno adapter, and
187
- `deno bundle` for the code (`examples/terminal-agent/web.ts`). The whole example is in
188
- `examples/web-node/` (`node examples/web-node/server.ts`).
209
+ sockets through Oxian's Node adapter, and says where each request came from; Bun and Deno run it
210
+ too. On Deno, `Deno.serve` serves `webServer({ …, upgrade: handler(runtime.hypervisor) })` with
211
+ Oxian's Deno adapter, each request given the address it came from first
212
+ (`setClientAddress(request, info.remoteAddr.hostname)`: without it, no request is this machine's),
213
+ and `deno bundle` makes the code (`examples/terminal-agent/web.ts`). The whole example is in
214
+ `examples/web-node/` (`node examples/web-node/server.ts`). Google sign-in is `googleSignIn` with the
215
+ `google` resource's `clientId`: the page shows its button.
189
216
 
190
217
  Many orgs behind one address (`copilotz/orgs`, see [design/tenancy.md](design/tenancy.md)): a
191
- directory signs people in and knows their orgs, and each org is a runtime of its own, opened when
192
- first used. Node takes a socket before any handler runs, so `listen` serves the orgs host and hands
193
- each socket to the runtime of the org its request is for:
218
+ directory signs people in (its plugins declare how, as above) and knows their orgs, and each org is
219
+ a runtime of its own, opened when first used. Node takes a socket before any handler runs, so
220
+ `listen` serves the orgs host and hands each socket to the runtime of the org its request is for:
194
221
  `listen({ fetch: host.serve, hypervisor: (request) => host.openRuntime(request)?.hypervisor })`
195
222
  (`examples/web-node/orgs.ts`).
196
223
 
224
+ ### Visitors
225
+
226
+ A public site where anyone chats with the app's agent, signed in or not: the contacts plugin's web
227
+ lines (`resources.web.lines.<name>`), with the app's secret (`links`), which visitors' cookies are
228
+ signed with. A page that asks to come in by one (`web({ arrive: { line } })`) and isn't anyone yet
229
+ becomes a visitor, its browser keeping a signed secret in an httpOnly, `SameSite=Strict` cookie
230
+ (`__Host-visitor` wherever it's Secure) that is the same visitor for the line's `days` (30). Coming
231
+ in makes and keeps nothing: the visitor's first message (`chat.send`, naming no chat) makes it a
232
+ contact in the line's space, with a chat of its own, answered by the line's agent. Someone signed in
233
+ comes in as themselves. A visitor reaches what any contact does: their chat, what's said and filed
234
+ there (`/files/<id>` too), never the agent's private steps (its tools' calls, with what each
235
+ returned, nor a step's words before it's known to be an answer), and nothing else. Its page reads
236
+ what it names of its own (its chat's messages by `thread`; its chats by its memberships, `member`
237
+ `{ member: "contact:<id>" }`): a read that names none is refused, never watched.
238
+
239
+ Its limits, each refused plainly (429) and only for that caller. Those by address hold for each
240
+ network the address is in, as many callers' worth as it counts: an IPv4 address and its /24 (8); an
241
+ IPv6 /64, its /56 (4) and its /48 (8), so one routed /48 is one site, not 65,536 callers:
242
+
243
+ | Limit | Default | Counted |
244
+ | ------------------------- | -------- | --------------------------------------------------------------------- |
245
+ | `ipVisitorsPerHour` | 20 | new visitors from one address, and as many first messages |
246
+ | `perMinute`, `perDay` | 10, 200 | one visitor's messages |
247
+ | `ipPerMinute`, `ipPerDay` | 30, 1000 | messages from the visitors one address brought |
248
+ | `linePerMinute` | 300 | the line's messages, all its visitors |
249
+ | `newcomersPerMinute` | 200 | of those, newcomers' (not spoken before the minute): the rest is kept |
250
+ | `visitorsPerHour` | 600 | new visitors who speak (contacts made), on the line |
251
+
252
+ The caller's address is the one the app's front says (`caller`, as MCP's lines take it), else the
253
+ one its socket came from (`serve` and `listen` know it; a listener of your own says it with
254
+ `setClientAddress`); with neither, nobody's let in, and when every visitor comes from one private
255
+ address (a proxy's) the host says so. A line may also have a `budget`: what its visitors' turns may
256
+ be charged a day, in the usage ledger's prices (with the usage plugin); past it, they wait for
257
+ tomorrow. And a `challenge`: an Action of the app's that checks what the page answered coming in (a
258
+ CAPTCHA's token: `web({ arrive: { line: "site", challenge: token } })`), asked before a newcomer's
259
+ let in. A message says 4,096 characters at most; files only on a line that takes them
260
+ (`files: { count, bytes }`, 1 of 5 MB unless said), and audio is transcribed (a model's call) only
261
+ with `transcribe: true`. A visitor holds two connections, 32 reads on each, and is told a failure's
262
+ words only when they're for anyone. Erasing the contact (`contact.forget`) ends its cookie and its
263
+ connections at once, and so does removing its line; what's past (counters, records, a contact whose
264
+ first message never went in) is collected every ten minutes. To change the app's secret, give the
265
+ old one as `links.previous` for a while: visitors and links it signed are still good. With the orgs
266
+ host, a line names its org (`org`), and its page is the org's, at `/o/<org>/`.
267
+
268
+ ```ts
269
+ resources: {
270
+ agents: { guide: { instructions: "Answer questions about the timetable.", model: "main" } },
271
+ spaces: { visitors: { name: "Website", agents: ["guide"] } },
272
+ web: {
273
+ caller: { header: "cf-connecting-ip", front: env.FRONT_SECRET },
274
+ lines: { site: { in: "visitors", agent: "guide" } },
275
+ },
276
+ links: { origin: "https://example.com", secret: env.LINKS_SECRET },
277
+ }
278
+ ```
279
+
280
+ ```tsx
281
+ // The app's own shell for visitors (a chat window): it sends with `chat.send`, naming no chat at
282
+ // first, and reads its chat's messages (by `thread`).
283
+ await web({ root, plugins: [siteShell, chatWeb], arrive: { line: "site" } });
284
+ ```
285
+
197
286
  ### Without the web app
198
287
 
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.
288
+ An app people use on WhatsApp or on the phone needs no page: `serve` without `code` (or `tickets`)
289
+ serves its plugins' routes alone (`routes` resources: Meta's webhook, Twilio's), `GET /health` for
290
+ whatever watches it, and 404 for anything else, whatever else its plugins declare. Nobody signs in
291
+ there: a route's Action is called as a visitor, and its `allow` decides (a webhook checks the
292
+ request's signature, then acts for the person it's from with `ctx.as`). Deno and Bun run it too.
204
293
 
205
294
  ```ts
206
295
  import { createRuntime } from "copilotz";
207
- import { serveRoutes } from "copilotz/web/node";
296
+ import { serve } from "copilotz/web/node";
208
297
 
209
298
  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.
299
+ const server = await serve({ runtime, hostname: "0.0.0.0", port: 8080 });
212
300
  process.once("SIGTERM", () => server.close({ drain: 8_000 }));
213
301
  ```
214
302
 
215
303
  A `serve` route may take a WebSocket of its own (a voice call's relay): `host.upgrade()` accepts the
216
304
  request's upgrade, and the route answers with the response it gives. It can refuse first (`403`,
217
305
  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.
306
+ `close` go; the listener (`serve`) takes it.
219
307
 
220
308
  ```ts
221
309
  routes: {
@@ -232,8 +320,8 @@ routes: {
232
320
  ```
233
321
 
234
322
  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
323
+ `/oxian`. `webServer({ runtime })` (`copilotz/web/server`) is the same as a fetch handler, for
324
+ another listener; a route's socket needs Oxian's (`copilotz/web/node`'s). The example is
237
325
  `examples/web-node/routes.ts`.
238
326
 
239
327
  ## Installing a computer
@@ -247,7 +335,7 @@ and an app serves it from there by default:
247
335
  import { computerDownloads } from "copilotz/plugins/compute/downloads";
248
336
 
249
337
  plugins: [...plugins, await computerDownloads()], // this Copilotz's release
250
- plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.21" })], // its own: /computer/download/
338
+ plugins: [...plugins, await computerDownloads({ dir: "dist/computer/1.0.0-rc.23" })], // its own: /computer/download/
251
339
  plugins: [...plugins, await computerDownloads({ url: "https://downloads.example.com/computer/" })], // or elsewhere
252
340
  ```
253
341
 
@@ -451,8 +539,12 @@ name, never by importing its code.
451
539
  shut to it unless it says otherwise (`peopleOrContacts`, as `chat.send` does). Its chat lives in
452
540
  the line's space and is shared with it on its own: it reaches that chat, what's said and filed
453
541
  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.
455
- - **`googleSignIn`**: sign-in with a Google ID token (the `google` resource names your client).
542
+ the contact reaches exactly that chat, never its agents' private steps. Agents are told whom
543
+ they're talking with. Its web lines (`web.lines`) let a browser that isn't anyone in as a visitor,
544
+ a contact once it speaks (see "Visitors").
545
+ - **`googleSignIn`**: sign-in with a Google ID token (the `google` resource names your client); the
546
+ web host's page shows its button.
547
+ - **`devSignIn`**: sign-in by name or email, from this machine only, for trying an app out.
456
548
  - **`accounts`**: outside accounts a person connects once, for their agents to use: first their
457
549
  ChatGPT plan, as a model provider, instead of the app's API key. Tokens are a private field only
458
550
  the plugin's Actions read, renewed before they run out.
@@ -526,8 +618,8 @@ filled by the front ends through resources).
526
618
  - **`whatsapp`**: people talk to their agents from WhatsApp, through Meta's Cloud API. A space's
527
619
  managers connect a number; a person links their phone with a code; what they send becomes their
528
620
  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
621
+ for Views (medium `whatsapp`, parts built with its toolkit: text, buttons, a list, a carousel, an
622
+ image, a document, each checked against Meta's limits): after an answer, features show more
531
623
  (`additions`: a carousel of trips, buttons to pay), once per chat per key, the answer's text in
532
624
  the same message when there's room, a fallback when Meta refuses one; taps come back with their
533
625
  ids. Pictures and files go as public links, signed links to the app's routes or files (the `links`
@@ -543,11 +635,11 @@ filled by the front ends through resources).
543
635
  signature, a call is taken within its caller's limits and the line's (calls at once, a day: else
544
636
  busy, nothing spent) and opens the line's socket with a one-time ticket. A caller is a contact in
545
637
  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`).
638
+ the agent writes for them is said as it writes it (a medium for Views: `voice`), a caller speaking
639
+ over it cuts it there (the agent is told what was heard), a failed or slow answer says a short
640
+ line in the line's language, and silence, a call too long or too many prompts, or the agent's
641
+ `end_call` end it. Managers block a caller (`voice.block`). Its socket needs a host that takes a
642
+ route's socket (`serve`).
551
643
  - **`mcp`**: models outside the app (ChatGPT, Claude, any MCP client) call its tools. A line the app
552
644
  declares (`mcp.lines.<name>`: its space, the tools it lists, each with its `tool:<name>` View, how
553
645
  each is shown, who calls, its limits) is an MCP server at `POST /mcp/<name>`: Streamable HTTP,
@@ -558,6 +650,15 @@ filled by the front ends through resources).
558
650
  the app's agents read of it (only public errors say their words); a request sent again to a tool
559
651
  that changes things is answered from the first, and the line's limits (calls at once, a minute,
560
652
  new conversations an hour, by conversation, user, caller's address and in all) refuse the rest.
653
+ **Widgets** (MCP Apps, ChatGPT's Apps SDK): a tool's calls shown through a web View of the app's
654
+ (`tools.<name>.widget`), drawn inside the assistant by the widget host (`copilotz/web/widget`) in
655
+ a template the web host makes (`webServer({ widgets: widgetsOf({ code, plugins }) })`), seeded
656
+ with what the View reads, answered on the server as the conversation's contact (its first paint
657
+ asks nothing). What only widgets call (`visibility: ["app"]`, or an Action: `{ action }`, a
658
+ person's tap or form) is refused without the widget's grant, which only results' `_meta` carry
659
+ (never what the model reads); the widget's reads go through the line's `copilotz_read`, queries
660
+ only. One View serves the web and the widget: `surface()`, `display(mode)`, `remind(text)`… from
661
+ `copilotz/web` are no-ops on the page, and the display mode is the View's `hints.mode`.
561
662
  - **`maintenance`**: HTTP for an app's operators when they can't reach its database, with one key:
562
663
  read SQL, the collections' operations through the owner, raw SQL writes inside it, blobs by id
563
664
  (see [Maintenance](#maintenance)).
@@ -712,18 +813,19 @@ curl https://app.example.com/maintenance/sql -H "authorization: Bearer $KEY" \
712
813
  `inline: true`. SQLite writes name the store's tables in `main`, so nothing temporary stands in
713
814
  for them. Each store runs at most 2 maintenance statements at once
714
815
  (`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.
816
+ - **Where:** SQL needs a SQL store. On a PostgreSQL server only as a role of its own (below) or,
817
+ told so, as the store's own role (below that), never in a schema other tenants share; PGlite, in
818
+ the app's process, runs it as its one session where it reaches no other schema. An orgs host's
819
+ orgs don't get the plugin at all (one key would reach every org). Operations, named queries and
820
+ blobs work everywhere, the memory store too, and need no role.
720
821
 
721
822
  ### A role of its own
722
823
 
723
824
  On a PostgreSQL server, raw SQL runs only as a role of its own, named by the store:
724
825
  `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.
826
+ Without one it's refused, unless the store is told to run it as its own role (below). The store's
827
+ role owns the tables, may stop the app's connections and is whatever the deployment made it (a
828
+ superuser, even): nothing that runs at a key's word should be it.
727
829
 
728
830
  Before each statement, on the connection that runs it, and again after a write in its transaction,
729
831
  maintenance checks that the role holds exactly what the SQL below grants, and refuses it otherwise
@@ -792,6 +894,34 @@ SELECT p.oid::regprocedure FROM pg_proc p WHERE p.prosecdef
792
894
  REVOKE EXECUTE ON FUNCTION some_schema.some_function(…) FROM PUBLIC;
793
895
  ```
794
896
 
897
+ ### Or the store's own role
898
+
899
+ Where a role of its own is more than a deployment wants, raw SQL can run as the store's own role
900
+ instead, said in so many words: `postgresStore({ url, schema, maintenance: { storeRole: true } })`
901
+ (`connections` as above). Each statement then connects as the role in the store's `url` (or its
902
+ pool's). Naming `url` and `storeRole` together stops the store from opening.
903
+
904
+ **What it costs:** anyone holding the maintenance key can do whatever the store's role can. It owns
905
+ the store's tables, so a statement can drop or truncate them, delete from the log, or rewrite any
906
+ document without an event; it can read every schema the role reaches (another app's on the same
907
+ database too, if it may), stop the app's own connections, and create roles or databases if the role
908
+ may. A leaked key is then almost the app's own database login. Only the check above is skipped,
909
+ which the store's role couldn't pass. Everything else holds: the statement filter (no `COMMIT`,
910
+ `SET`, `ALTER ROLE`, `DO`, `LOCK`…); the extended protocol and a connection of its own for each
911
+ statement, closed after; timeouts, the row and byte caps, and at most `connections` at once; writes
912
+ inside the owner, fenced, with their `maintenance.sql` event; a statement that changes `meta` or
913
+ makes a trigger rolled back; the owner's cache emptied after a write; the key and the log line.
914
+
915
+ Still refused, before each statement and again after a write in its transaction, saying why: a role
916
+ that could turn SQL into commands on the database server or access to its files. That is a
917
+ superuser; a member, by any path, of a superuser role (it could switch to it within a statement), or
918
+ of `pg_execute_server_program`, `pg_read_server_files` or `pg_write_server_files`; before PostgreSQL
919
+ 16, one with `CREATEROLE` (enough to grant itself any of those); and one that may run
920
+ `pg_read_file`, `pg_read_binary_file`, `lo_import`, `lo_export` or adminpack's file functions. Cloud
921
+ SQL's `postgres` user isn't a superuser (it's a member of `cloudsqlsuperuser`, which isn't one
922
+ either): from PostgreSQL 16 it passes; on 15 or earlier its `CREATEROLE` is refused, so use a role
923
+ of its own there.
924
+
795
925
  ## The example app
796
926
 
797
927
  `examples/terminal-agent` is an app on all of it: an assistant and a researcher, notes in spaces,
@@ -1062,15 +1192,15 @@ Copilotz runs on Node (first), Deno and Bun, and is built for Cloudflare Workers
1062
1192
  (`hosts/terminal`: `terminal({ runtime, me })`) draws it with Ink: a reply being written grows in
1063
1193
  place, as its own part.
1064
1194
  - **The web** (see [design/views.md](design/views.md), "The web") runs Views in the browser. The
1065
- page signs in (an httpOnly session cookie), trades the cookie for a one-time ticket (`/connect`),
1066
- and connects to the owner over Oxian as an untrusted worker bound to that person
1067
- (`web({ plugins,
1068
- root })` in the browser, `webServer({ runtime, tickets, code, upgrade })`
1069
- beside the runtime, which declares the `socket` transport). A browser reads a collection directly
1070
- only when a rule speaks for it; anything else, through queries that let its person. Writes are
1071
- Actions. Plugins answer their own HTTP through the `routes` resource (a webhook, an OAuth
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.
1195
+ page's cookie (a person's session, a web line's visitor: the `entrances` plugins declare) trades
1196
+ for a one-time ticket (`/connect`), and it connects to the owner over Oxian as an untrusted worker
1197
+ bound to that actor (`web({ plugins, root })` in the browser,
1198
+ `webServer({ runtime, tickets, code,
1199
+ upgrade })` beside the runtime, which declares the `socket`
1200
+ transport). A browser reads a collection directly only when a rule speaks for it; anything else,
1201
+ through queries that let its person. Writes are Actions. Plugins answer their own HTTP through the
1202
+ `routes` resource (a webhook, an OAuth callback, an API, a download, a socket of their own), and
1203
+ files people sent are served at `/files/<id>` to whoever may read them, with ranges.
1074
1204
  - **The design system** (`design/views.md`, "The design system"): the web host owns a token
1075
1205
  vocabulary (shadcn's names) and its defaults, which are Copilotz's look (navy, the logo's cyan and
1076
1206
  blue, Manrope and Space Grotesk, its logo and icon), and an app rebrands with a `theme` resource
@@ -4,19 +4,27 @@
4
4
  * of its own, opened on its first request and closed when nobody's used it
5
5
  * for a while. A browser holds a directory session (`dir`), a session for
6
6
  * each org it has entered (`s_<org>`), and which org it's in (`org`), which
7
- * the switcher changes. Everything an org serves (its page, code, socket,
8
- * files, plugins' routes) is its own web host's (`hosts/web`), as one app.
7
+ * the switcher changes: every cookie here is the host's alone, `__Host-dir`
8
+ * and so on wherever it's Secure (an org's entrances' too), so no other host
9
+ * under the domain (a preview's) can set one. Everything an org serves (its
10
+ * page, code, socket, files, plugins' routes) is its own web host's
11
+ * (`hosts/web`), as one app.
9
12
  *
10
- * - `POST /signin/google` `{ idToken }`, `POST /signin/dev` `{ name }` (this
11
- * machine only, when `dev`): signs in at the directory, makes the person's
12
- * personal org the first time, and enters the org they were in last.
13
+ * - `POST /signin/<name>`: a way to sign in the directory's plugins declare
14
+ * (its `signIn` resource: Google's `{ idToken }`; dev sign-in's `{ name }`,
15
+ * from this machine to this machine only: `fromHere`): signs in at the
16
+ * directory, makes the person's personal org the first time, and enters
17
+ * the org they were in last.
13
18
  * - `GET /orgs`: who's signed in, the org they're in, the orgs they belong
14
19
  * to, the invitations waiting for them, and whether they're staff.
15
20
  * - `POST /orgs` `{ name }`: makes a team org, its maker its owner, and
16
21
  * enters it. `POST /orgs/enter` `{ org }`: goes into another.
17
22
  * - `POST /orgs/invites/answer` `{ invite, accept }`: joins (and enters) or
18
23
  * declines.
19
- * - `POST /signout`: out of the directory and every org.
24
+ * - `POST /signout`: out of the directory and every org it holds a session
25
+ * for (each ends), and every browser connected as them goes. A cookie
26
+ * still held under its name from before it was the host's alone (`dir`,
27
+ * `org`, `s_<org>`) is ended and cleared then, and on connecting.
20
28
  * - `/o/<org>/…`: that org, by its address, for what reaches it without a
21
29
  * browser's session: its API (a key), its webhooks (signed), its
22
30
  * computers' downloads. The org's own handlers say who may.
@@ -43,13 +51,19 @@
43
51
  *
44
52
  * Behind a front (a Cloudflare worker), `front: { secret }`: a request
45
53
  * carrying the secret (`x-copilotz-front`) is for the host it forwards
46
- * (`x-forwarded-host`); any other's forwarded headers are ignored.
54
+ * (`x-forwarded-host`); any other's forwarded headers are ignored. What it
55
+ * answers itself to a POST (signing in and out, orgs, invitations, the
56
+ * console) comes from the app's own page only (`Origin`), as an org's
57
+ * `/connect` does. What it answers itself is never cached (`no-store`), and
58
+ * something going wrong answers its code's status and only words for anyone
59
+ * (`refusal`). A request it hands an org keeps where it came from (its
60
+ * client address: `carry`).
47
61
  *
48
62
  * The app says how to open an org: its store (at the org's placement, as
49
63
  * its tenant), its plugins with the host's `here` (the org's name, and how
50
64
  * it reaches the directory), and `admit` for its browsers.
51
65
  */
52
- import type { Actor, Plugins, Runtime, Transport } from "../../runtime/mod.js";
66
+ import type { Actor, BrowserLimits, Plugins, Runtime, Transport } from "../../runtime/mod.js";
53
67
  import { type Code, type WebServerOptions } from "../web/server.js";
54
68
  /** An org as the host opens it. */
55
69
  export type OrgInfo = {
@@ -60,24 +74,30 @@ export type OrgInfo = {
60
74
  schema: string;
61
75
  };
62
76
  };
63
- export type OrgsHostOptions = Pick<WebServerOptions, "title" | "theme" | "google" | "dev" | "assets" | "front"> & {
77
+ export type OrgsHostOptions = Pick<WebServerOptions, "title" | "theme" | "assets" | "front"> & {
64
78
  /**
65
- * The app's own hosts (`compass.copilotz.com`; patterns as routes' are,
79
+ * The app's own hosts (`app.example.com`; patterns as routes' are,
66
80
  * `*.run.app`): a request to any other is for a host an org claimed.
67
81
  * Unset, every host is the app's, and claims route nothing.
68
82
  */
69
83
  hosts?: string[];
70
- /** The directory's runtime: identity, a sign-in method, and the directory plugin. */
84
+ /**
85
+ * The directory's runtime: identity, the ways to sign in (Google's, dev
86
+ * sign-in's: what its page shows, and `POST /signin/<name>` takes), and
87
+ * the directory plugin.
88
+ */
71
89
  directory: Runtime;
72
90
  /**
73
91
  * Opens an org: the app's runtime for it, with these plugins too, this
74
- * `admit`, and these `transports` (its socket, at `/oxian` and at its
75
- * address, `/o/<org>/oxian`).
92
+ * `admit`, these `transports` (its socket, at `/oxian` and at its
93
+ * address, `/o/<org>/oxian`), and these `browsers` limits (contacts'
94
+ * connections counted with every org's: they share one listener).
76
95
  */
77
96
  open(org: OrgInfo, given: {
78
97
  plugins: Plugins;
79
98
  admit: (ticket: string) => Actor | undefined;
80
99
  transports: Transport[];
100
+ browsers: BrowserLimits;
81
101
  }): Promise<Runtime>;
82
102
  /** The socket upgrade for an org's runtime (its transport for browsers). */
83
103
  upgrade(runtime: Runtime, request: Request): Response | Promise<Response>;