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
@@ -0,0 +1,134 @@
1
+ /**
2
+ * A web line's budget for the day (UTC), kept with its counters, in memory:
3
+ * what its visitors' model use was charged (`spent`, as the usage ledger
4
+ * prices it), and what's held for messages let in whose turns haven't been
5
+ * charged yet (`holds`, each a visitor's).
6
+ *
7
+ * - **Sending** holds an estimate first (`hold`): the most one of its
8
+ * visitors' model calls cost here lately; before any is known, the rest of
9
+ * the day's budget (so one turn goes at a time until a cost is known). One
10
+ * that doesn't fit beside what's spent and held is refused: messages sent
11
+ * at once can't all pass a budget only one fits.
12
+ * - **A priced call** is charged (`charge`), and the visitor's hold goes
13
+ * with it. A hold not charged in two minutes lapses (its turn failed).
14
+ * - **Before each call** (`left`), a visitor's turn goes on only while the
15
+ * day isn't spent: a tool loop stops there.
16
+ * - **Use nothing prices** (a model the ledger has no price for) closes the
17
+ * line for the day (`close`): a budget that can't be counted holds nothing.
18
+ *
19
+ * Each change is one write that applies only to the day as it was read (its
20
+ * `v`), tried again when another came between.
21
+ */
22
+ import { failure } from "../../../../runtime/mod.js";
23
+ const DAY = 86_400_000;
24
+ /** How long a message's hold lasts without being charged. */
25
+ export const HOLD_MS = 120_000;
26
+ /** How long what one call cost is remembered, as the estimate. */
27
+ const REMEMBERED = 30 * DAY;
28
+ /** How long (ms) a change keeps trying while others change the day too. */
29
+ const PATIENCE = 3_000;
30
+ /** What visitors are told when the budget refuses. */
31
+ export const BUDGET = {
32
+ spent: "This chat has done all it can for today: come back tomorrow.",
33
+ held: "This chat is busy right now: try again in a moment.",
34
+ };
35
+ const dayOf = (line, now) => `${line}|spent@${Math.floor(now / DAY) * DAY}`;
36
+ const costOf = (line) => `${line}|cost`;
37
+ /** What's held now: holds not yet lapsed. */
38
+ const heldOf = (day, now) => Object.fromEntries(Object.entries(day?.holds ?? {}).filter(([, h]) => h.until > now));
39
+ const sum = (holds) => Object.values(holds ?? {}).reduce((total, h) => total + h.amount, 0);
40
+ /**
41
+ * Changes the day as `change` says from what it was: one write, applying
42
+ * only if nothing came between (else read again, with jitter, until `PATIENCE` runs out).
43
+ */
44
+ async function changeDay(rates, line, now, change) {
45
+ const _id = dayOf(line, now);
46
+ const deadline = performance.now() + PATIENCE;
47
+ for (let tries = 0; performance.now() < deadline; tries++) {
48
+ // Another came between: read again after a moment, apart from the others by chance.
49
+ if (tries)
50
+ await new Promise((r) => setTimeout(r, Math.random() * Math.min(5 * tries, 50)));
51
+ const day = await rates.findOne({ _id });
52
+ const next = change(day);
53
+ if (!next)
54
+ return;
55
+ const v = day?.v ?? 0;
56
+ try {
57
+ const done = await rates.updateOne(day ? { _id, v } : { _id, v: { $exists: false } }, { $set: { ...next, v: v + 1, until: Math.floor(now / DAY) * DAY + DAY } }, { upsert: !day });
58
+ if (!day || done.matchedCount > 0)
59
+ return;
60
+ }
61
+ catch (error) {
62
+ // Made meanwhile by another: read it again.
63
+ if (error.code !== "duplicate_key")
64
+ throw error;
65
+ }
66
+ }
67
+ throw failure("too_many", BUDGET.held, { public: true });
68
+ }
69
+ /**
70
+ * Holds an estimate of a visitor's message's cost against the day's budget,
71
+ * or refuses it (`too_many`, said to anyone): spent, or what's held already
72
+ * leaves no room.
73
+ */
74
+ export async function hold(rates, line, contact, now = Date.now()) {
75
+ const known = (await rates.findOne({ _id: costOf(line.name) }))?.spent;
76
+ await changeDay(rates, line.name, now, (day) => {
77
+ if (day?.closed || (day?.spent ?? 0) >= line.budget) {
78
+ throw failure("too_many", BUDGET.spent, { public: true });
79
+ }
80
+ const holds = heldOf(day, now);
81
+ const rest = line.budget - (day?.spent ?? 0) - sum(holds);
82
+ // Nothing known yet: the rest of the day's, so one at a time until a cost is.
83
+ // A call known to cost more than the whole budget holds what's left: it runs, and is charged.
84
+ // (With other holds in place, it must fit beside them.)
85
+ const alone = !Object.keys(holds).length;
86
+ const estimate = known === undefined ? rest : alone ? Math.min(known, rest) : known;
87
+ if (known === undefined ? rest <= 0 : estimate > rest) {
88
+ throw failure("too_many", BUDGET.held, { public: true });
89
+ }
90
+ const mine = holds[contact]?.amount ?? 0;
91
+ return { holds: { ...holds, [contact]: { amount: mine + estimate, until: now + HOLD_MS } } };
92
+ });
93
+ }
94
+ /** A visitor's priced model call: charged to the day, its hold gone with it; remembered as the estimate. */
95
+ export async function charge(rates, line, contact, price, now = Date.now()) {
96
+ // One atomic write: nothing read first, so charges at once can't overwrite each other.
97
+ const _id = dayOf(line, now);
98
+ const until = Math.floor(now / DAY) * DAY + DAY;
99
+ const change = {
100
+ $inc: { spent: price, v: 1 },
101
+ $set: { until },
102
+ ...(contact ? { $unset: { [`holds.${contact}`]: "" } } : {}),
103
+ };
104
+ try {
105
+ await rates.updateOne({ _id }, change, { upsert: true });
106
+ }
107
+ catch (error) {
108
+ // Made meanwhile by another (an upsert race): this one applies to it.
109
+ if (error.code !== "duplicate_key")
110
+ throw error;
111
+ await rates.updateOne({ _id }, change);
112
+ }
113
+ // The most one call cost lately, coming down slowly: what the next message holds.
114
+ const cost = await rates.findOne({ _id: costOf(line) });
115
+ const was = cost?.spent ?? 0;
116
+ await rates.updateOne({ _id: costOf(line) }, { $set: { spent: Math.max(price, was * 0.9), until: now + REMEMBERED } }, { upsert: true });
117
+ }
118
+ /**
119
+ * Use nothing prices: the day is closed, its visitors' messages refused
120
+ * until tomorrow. Whether this closed it (it wasn't already).
121
+ */
122
+ export async function close(rates, line, why, now = Date.now()) {
123
+ let closed = false;
124
+ await changeDay(rates, line, now, (day) => {
125
+ closed = !day?.closed;
126
+ return closed ? { closed: why } : undefined;
127
+ });
128
+ return closed;
129
+ }
130
+ /** Whether a visitor's turn may make another call: not once the day is spent, or closed. */
131
+ export async function left(rates, line, now = Date.now()) {
132
+ const day = await rates.findOne({ _id: dayOf(line.name, now) });
133
+ return !day?.closed && (day?.spent ?? 0) < line.budget;
134
+ }
@@ -0,0 +1,158 @@
1
+ /**
2
+ * The web lines (the `web` resource): browsers that
3
+ * aren't anyone, coming in as visitors. Each line the app declares, by
4
+ * name, is a front door for them: the space their chats live in, who
5
+ * answers, how long a visitor stays the same one, what they may send and
6
+ * its limits. How the app knows who's calling (`caller`) is the runtime's
7
+ * `CallerSettings`, as MCP's lines take it. `lineOf` gives a line with every
8
+ * default filled in; `problemOf` says what's wrong with one, at start.
9
+ */
10
+ import { type CallerSettings, type Resources } from "../../../../runtime/mod.js";
11
+ import type { Keyring } from "./secret.js";
12
+ /**
13
+ * What a line takes before it says no: see `LIMITS`. Those by address hold
14
+ * for each network a visitor came from (`networksOf`): its address (IPv4) or
15
+ * /64 (IPv6) as they say, and wider ones, as many callers' worth as each
16
+ * counts (`SCALE`: an IPv4 /24 eight; an IPv6 /56 four, a /48 eight).
17
+ */
18
+ export type WebLimits = {
19
+ /**
20
+ * New visitors from one address an hour: browsers let in, each its cookie;
21
+ * and as many who speak for the first time, an hour (so visitors let in
22
+ * over days can't all start at once).
23
+ */
24
+ ipVisitorsPerHour: number;
25
+ /** New visitors who speak an hour, on the line: contacts made, at their first message. */
26
+ visitorsPerHour: number;
27
+ /** Messages one visitor sends a minute, and a day. */
28
+ perMinute: number;
29
+ perDay: number;
30
+ /** Messages a minute and a day from one address: every visitor that came in from it. */
31
+ ipPerMinute: number;
32
+ ipPerDay: number;
33
+ /** Messages a minute on the line, all its visitors together. */
34
+ linePerMinute: number;
35
+ /**
36
+ * Of those, what visitors who hadn't spoken before this minute may send:
37
+ * the rest of `linePerMinute` is kept for those who had, so a burst of
38
+ * newcomers never stops a conversation going on.
39
+ */
40
+ newcomersPerMinute: number;
41
+ };
42
+ /** Files a visitor may send with a message, when the line takes any: how many, and how large. */
43
+ export type WebFiles = {
44
+ /** Files with one message (1 unless said). */
45
+ count?: number;
46
+ /** Bytes each may be (5 MB unless said). */
47
+ bytes?: number;
48
+ };
49
+ /** A web line the app declares: a front door for anyone with a browser. */
50
+ export type WebLine = {
51
+ /**
52
+ * The space its visitors' chats live in: one the app declares too (the
53
+ * spaces plugin's `spaces` resource) is made and kept with the line.
54
+ */
55
+ in: string;
56
+ /** Who answers its visitors (an agent's name); else whoever answers new chats in the space. */
57
+ agent?: string;
58
+ /** What its visitors' chats are called, as the space's people see them (the line's name). */
59
+ title?: string;
60
+ /** How long a visitor stays the same one (their browser's cookie), in days: 30. */
61
+ days?: number;
62
+ limits?: Partial<WebLimits>;
63
+ /**
64
+ * Files its visitors may send (none unless said): `{}` for one of 5 MB a
65
+ * message, or how many and how large.
66
+ */
67
+ files?: WebFiles;
68
+ /**
69
+ * Whether what visitors' audio files say is transcribed for the agent (a
70
+ * model's call, paid): not unless said. Without it, audio goes as it is.
71
+ */
72
+ transcribe?: boolean;
73
+ /**
74
+ * What its visitors' model use may be charged a day (UTC), in the usage
75
+ * ledger's prices (the app's currency): what the turns working for them
76
+ * cost, as the usage plugin rates it. Past it, its visitors' messages
77
+ * wait for the next day. None: no budget. Needs the usage plugin.
78
+ */
79
+ budget?: number;
80
+ /**
81
+ * An Action of the app's that a newcomer must pass to be let in (a
82
+ * CAPTCHA's check: Turnstile's, hCaptcha's): asked as the system with
83
+ * `{ line, answer }`, where `answer` is what the page sent coming in
84
+ * (`web({ arrive: { line, challenge } })`'s `challenge`), it answers true
85
+ * to let them in. One back with its cookie isn't asked again.
86
+ */
87
+ challenge?: string;
88
+ /** With the orgs host, the org it's for (its id): no other org has it. */
89
+ org?: string;
90
+ };
91
+ export type WebSettings = {
92
+ lines?: Record<string, WebLine>;
93
+ /**
94
+ * How the app knows who's calling, for the limits by address, when a
95
+ * front before it says (as MCP's lines take it). Without it, a visitor is
96
+ * counted by the address its socket came from, as the web host's listener
97
+ * saw it; with neither, nobody is let in.
98
+ */
99
+ caller?: CallerSettings;
100
+ };
101
+ /**
102
+ * What a line takes, unless it says. From one address: 20 new visitors an
103
+ * hour (a household, an office behind one address), and 30 messages a
104
+ * minute, 1,000 a day; its wider networks as many times that as they count
105
+ * (an IPv6 /48: 160 new visitors an hour, 240 messages a minute). From one
106
+ * visitor: 10 messages a minute, 200 a day. On the line: 600 new visitors
107
+ * who speak an hour, and 300 messages a minute, of which newcomers (those
108
+ * who hadn't spoken before the minute) send 200 at most. Only visitors let
109
+ * in count as new: one coming back with their cookie is no new one; and only
110
+ * those who speak are contacts, counted on the line.
111
+ */
112
+ export declare const LIMITS: WebLimits;
113
+ /** What a line taking files takes, unless it says: one a message, of 5 MB. */
114
+ export declare const FILES: Required<WebFiles>;
115
+ /** How long a visitor stays the same one, unless the line says: 30 days. */
116
+ export declare const DAYS = 30;
117
+ /** The longest a line may keep a visitor the same one, as long as browsers keep a cookie. */
118
+ export declare const MOST_DAYS = 400;
119
+ /** A line as the plugin uses it: its settings, its name, and every default filled in. */
120
+ export type Line = Omit<WebLine, "limits" | "days" | "files"> & {
121
+ name: string;
122
+ days: number;
123
+ limits: WebLimits;
124
+ /** Files it takes with one message; none: `undefined`. */
125
+ files?: Required<WebFiles>;
126
+ };
127
+ export declare const settingsOf: (ctx: {
128
+ resources: Resources;
129
+ }) => WebSettings;
130
+ /**
131
+ * The app's own lines, by name, here: with the orgs host (each org's runtime
132
+ * knows its org, `resources.org`), only those that name this org; a line
133
+ * naming none is the single-org app's.
134
+ */
135
+ export declare const linesOf: (ctx: {
136
+ resources: Resources;
137
+ }) => Record<string, WebLine>;
138
+ /** The line `name`, ready to use; undefined when the app declares none by that name here. */
139
+ export declare function lineOf(ctx: {
140
+ resources: Resources;
141
+ }, name: string): Line | undefined;
142
+ /**
143
+ * What visitors' secrets are signed with here: the app's secret (and the
144
+ * one before it, `links.previous`, while it's given), and the org. Undefined
145
+ * without the app's secret (an app with no web lines): no secret is anyone
146
+ * then.
147
+ */
148
+ export declare function keyringOf(ctx: {
149
+ resources: Resources;
150
+ }): Keyring | undefined;
151
+ /** What's wrong with a line's settings, if anything (checked when the app starts). */
152
+ export declare function problemOf(name: string, line: WebLine, resources: Resources): string | undefined;
153
+ /**
154
+ * What's wrong with the web lines' settings, if anything (checked when the
155
+ * app starts), given the app's Actions: a line's challenge is one, and a
156
+ * budget needs the usage plugin's prices (`usage.quote`).
157
+ */
158
+ export declare function settingsProblem(resources: Resources, actions?: Readonly<Record<string, unknown>>): string | undefined;
@@ -0,0 +1,156 @@
1
+ /**
2
+ * The web lines (the `web` resource): browsers that
3
+ * aren't anyone, coming in as visitors. Each line the app declares, by
4
+ * name, is a front door for them: the space their chats live in, who
5
+ * answers, how long a visitor stays the same one, what they may send and
6
+ * its limits. How the app knows who's calling (`caller`) is the runtime's
7
+ * `CallerSettings`, as MCP's lines take it. `lineOf` gives a line with every
8
+ * default filled in; `problemOf` says what's wrong with one, at start.
9
+ */
10
+ import { callerProblem, linksOf, secretsOf, } from "../../../../runtime/mod.js";
11
+ /**
12
+ * What a line takes, unless it says. From one address: 20 new visitors an
13
+ * hour (a household, an office behind one address), and 30 messages a
14
+ * minute, 1,000 a day; its wider networks as many times that as they count
15
+ * (an IPv6 /48: 160 new visitors an hour, 240 messages a minute). From one
16
+ * visitor: 10 messages a minute, 200 a day. On the line: 600 new visitors
17
+ * who speak an hour, and 300 messages a minute, of which newcomers (those
18
+ * who hadn't spoken before the minute) send 200 at most. Only visitors let
19
+ * in count as new: one coming back with their cookie is no new one; and only
20
+ * those who speak are contacts, counted on the line.
21
+ */
22
+ export const LIMITS = {
23
+ ipVisitorsPerHour: 20,
24
+ visitorsPerHour: 600,
25
+ perMinute: 10,
26
+ perDay: 200,
27
+ ipPerMinute: 30,
28
+ ipPerDay: 1_000,
29
+ linePerMinute: 300,
30
+ newcomersPerMinute: 200,
31
+ };
32
+ /** What a line taking files takes, unless it says: one a message, of 5 MB. */
33
+ export const FILES = { count: 1, bytes: 5_000_000 };
34
+ /** The most files a line may take with one message, and the largest each may be. */
35
+ const MOST_FILES = { count: 10, bytes: 10_000_000 };
36
+ /** How long a visitor stays the same one, unless the line says: 30 days. */
37
+ export const DAYS = 30;
38
+ /** The longest a line may keep a visitor the same one, as long as browsers keep a cookie. */
39
+ export const MOST_DAYS = 400;
40
+ export const settingsOf = (ctx) => (ctx.resources.web ?? {});
41
+ /**
42
+ * The app's own lines, by name, here: with the orgs host (each org's runtime
43
+ * knows its org, `resources.org`), only those that name this org; a line
44
+ * naming none is the single-org app's.
45
+ */
46
+ export const linesOf = (ctx) => {
47
+ const all = settingsOf(ctx).lines ?? {};
48
+ const org = orgOf(ctx);
49
+ return Object.fromEntries(Object.entries(all).filter(([, line]) => line && (org ? line.org === org : !line.org)));
50
+ };
51
+ /** The org this runtime is, with the orgs host. */
52
+ const orgOf = (ctx) => ctx.resources.org?.id;
53
+ /** The line `name`, ready to use; undefined when the app declares none by that name here. */
54
+ export function lineOf(ctx, name) {
55
+ const lines = linesOf(ctx);
56
+ const line = Object.hasOwn(lines, name) ? lines[name] : undefined;
57
+ if (!line)
58
+ return undefined;
59
+ const { files, ...rest } = line;
60
+ return {
61
+ ...rest,
62
+ name,
63
+ days: line.days ?? DAYS,
64
+ limits: { ...LIMITS, ...line.limits },
65
+ ...(files ? { files: { ...FILES, ...files } } : {}),
66
+ };
67
+ }
68
+ /**
69
+ * What visitors' secrets are signed with here: the app's secret (and the
70
+ * one before it, `links.previous`, while it's given), and the org. Undefined
71
+ * without the app's secret (an app with no web lines): no secret is anyone
72
+ * then.
73
+ */
74
+ export function keyringOf(ctx) {
75
+ const links = linksOf(ctx.resources);
76
+ if (!links)
77
+ return undefined;
78
+ const org = orgOf(ctx);
79
+ return { secrets: secretsOf(links), ...(org ? { org } : {}) };
80
+ }
81
+ /** What's wrong with a line's settings, if anything (checked when the app starts). */
82
+ export function problemOf(name, line, resources) {
83
+ if (!/^[\w-]{1,60}$/.test(name))
84
+ return "its name is letters, digits, - and _";
85
+ if (typeof line?.in !== "string" || !line.in)
86
+ return "needs its in (the space its chats live in)";
87
+ if (line.agent !== undefined) {
88
+ if (typeof line.agent !== "string" || !Object.hasOwn(resources.agents ?? {}, line.agent)) {
89
+ return `its agent "${line.agent}" isn't one of the app's agents`;
90
+ }
91
+ }
92
+ if (line.title !== undefined && (typeof line.title !== "string" || !line.title.trim())) {
93
+ return "its title is some text";
94
+ }
95
+ if (line.days !== undefined &&
96
+ !(typeof line.days === "number" && line.days > 0 && line.days <= MOST_DAYS)) {
97
+ return `its days are a number over 0, ${MOST_DAYS} at most (as long as browsers keep a cookie)`;
98
+ }
99
+ for (const [key, value] of Object.entries(line.limits ?? {})) {
100
+ if (!(key in LIMITS))
101
+ return `limits.${key} isn't a limit`;
102
+ if (!(Number.isInteger(value) && value > 0)) {
103
+ return `limits.${key} is a whole number over 0`;
104
+ }
105
+ }
106
+ if (line.files !== undefined) {
107
+ if (!line.files || typeof line.files !== "object")
108
+ return "its files are { count?, bytes? }";
109
+ for (const [key, value] of Object.entries(line.files)) {
110
+ if (!(key in FILES))
111
+ return `files.${key} isn't one: count, bytes`;
112
+ const most = MOST_FILES[key];
113
+ if (!(Number.isInteger(value) && value > 0 && value <= most)) {
114
+ return `files.${key} is a whole number over 0, ${most} at most`;
115
+ }
116
+ }
117
+ }
118
+ if (line.transcribe !== undefined && typeof line.transcribe !== "boolean") {
119
+ return "its transcribe is true or false";
120
+ }
121
+ if (line.budget !== undefined &&
122
+ !(typeof line.budget === "number" && Number.isFinite(line.budget) && line.budget > 0)) {
123
+ return "its budget is a number over 0 (what its visitors' model use may cost a day)";
124
+ }
125
+ if (line.challenge !== undefined && (typeof line.challenge !== "string" || !line.challenge)) {
126
+ return "its challenge is an Action's name";
127
+ }
128
+ return undefined;
129
+ }
130
+ /**
131
+ * What's wrong with the web lines' settings, if anything (checked when the
132
+ * app starts), given the app's Actions: a line's challenge is one, and a
133
+ * budget needs the usage plugin's prices (`usage.quote`).
134
+ */
135
+ export function settingsProblem(resources, actions = {}) {
136
+ const caller = callerProblem(settingsOf({ resources }).caller);
137
+ if (caller)
138
+ return `web.${caller}`;
139
+ const lines = Object.entries(linesOf({ resources }));
140
+ for (const [name, line] of lines) {
141
+ const problem = problemOf(name, line, resources) ??
142
+ (line.challenge && !Object.hasOwn(actions, line.challenge)
143
+ ? `its challenge "${line.challenge}" isn't one of the app's Actions`
144
+ : line.budget && !Object.hasOwn(actions, "usage.quote")
145
+ ? "its budget needs the usage plugin, which prices what visitors' turns use"
146
+ : undefined);
147
+ if (problem)
148
+ return `web.lines.${name} ${problem}`;
149
+ }
150
+ // Visitors' secrets are signed with the app's secret: nothing is kept when a page comes in.
151
+ if (lines.length && !linksOf(resources)) {
152
+ return "web.lines need the app's secret, which visitors' cookies are signed with: " +
153
+ "the links resource ({ origin, secret })";
154
+ }
155
+ return undefined;
156
+ }
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Where a secret is good: the app's secrets (its own first, then the one
3
+ * before it), and the org it's for (with the orgs host).
4
+ */
5
+ export type Keyring = {
6
+ secrets: string[];
7
+ org?: string;
8
+ };
9
+ /** A visitor's secret, read: and which of the app's secrets signed it. */
10
+ export type Visit = {
11
+ line: string;
12
+ id: string;
13
+ issued: number;
14
+ tags: string[];
15
+ secret: string;
16
+ };
17
+ /** A new secret, for a visitor coming in by `line` from the networks tagged `tags` (`tagsOf`). */
18
+ export declare function newSecret(ring: Keyring, line: string, tags: string[]): Promise<string>;
19
+ /** What a secret says, when the app made it; undefined for anything else (forged, garbled). */
20
+ export declare function visitOf(ring: Keyring, secret: unknown): Promise<Visit | undefined>;
21
+ /** The contact a visit is: by the secret that signed it, so the one before it still is who it was. */
22
+ export declare const contactOf: (ring: Keyring, visit: Visit) => Promise<string>;
23
+ /** A web visitor's chat, from its contact: the same however often it's asked for. */
24
+ export declare const chatOf: (ring: Keyring, contact: string) => Promise<string>;
25
+ /**
26
+ * What the networks an address is in (`networksOf`) are counted and kept as:
27
+ * each a tag, its prefix's length and an HMAC of it (`64-3f…`), never the
28
+ * address.
29
+ */
30
+ export declare const tagsOf: (ring: Keyring, line: string, networks: {
31
+ network: string;
32
+ bits: number;
33
+ }[]) => Promise<string[]>;
@@ -0,0 +1,86 @@
1
+ /**
2
+ * A web visitor's secret: what their browser keeps (in an httpOnly cookie
3
+ * the web host sets) and shows to be them. It stands on its own: signed with
4
+ * the visitors' key of the app's secret (the `links` resource's, through
5
+ * `keyOf`: never the secret itself, nor the key its links are signed with),
6
+ * so nothing is kept when a page first comes in, and nobody without the
7
+ * app's secret can make one.
8
+ *
9
+ * `vis_<line>.<id>.<issued>.<tags>.<mac>`: the line it came by, 128 random
10
+ * bits, when it was made (ms, base 36), the tags of the networks it came from
11
+ * (`<bits>-<hmac>`, narrowest first, `~` between, `-` for none: never the
12
+ * address), and an HMAC of all of it. From it, through HMACs with the same
13
+ * key, come the contact it is (`c-…`) and the contact's chat (`web-…`), the
14
+ * same for as long as the secret lasts. A secret signed with the app's
15
+ * previous secret (`links.previous`) is good too, and is the contact it was:
16
+ * that's for a secret changed on schedule. A secret that leaked is never
17
+ * given as `previous` (whoever has it could make any visitor): it goes at
18
+ * once, and every visitor it signed is a newcomer. One made later than now
19
+ * (past a few minutes of clocks' skew) is nobody's: no secret lasts longer
20
+ * than its line says from when it was made.
21
+ */
22
+ import { keyOf } from "../../../../runtime/mod.js";
23
+ const encoder = new TextEncoder();
24
+ const hex = (bytes) => [...new Uint8Array(bytes)].map((b) => b.toString(16).padStart(2, "0")).join("");
25
+ /** HMAC-SHA256 of `parts` (kept apart as JSON) with the visitors' key of `secret`, in hex. */
26
+ const mac = async (secret, parts) => hex(await crypto.subtle.sign("HMAC", await keyOf(secret, "visitors"), encoder.encode(JSON.stringify(parts))));
27
+ /** Whether two strings are the same, taking as long whatever their first difference. */
28
+ const same = (a, b) => {
29
+ let differ = a.length ^ b.length;
30
+ for (let i = 0; i < Math.max(a.length, b.length); i++) {
31
+ differ |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
32
+ }
33
+ return differ === 0;
34
+ };
35
+ const TAG = /^\d{1,2}-[0-9a-f]{16}$/;
36
+ /** How far ahead of this machine's clock a secret's making may be (another's clock): 5 minutes. */
37
+ const SKEW = 5 * 60_000;
38
+ const SHAPE = /^vis_([\w-]{1,60})\.([A-Za-z0-9_-]{22})\.([0-9a-z]{1,12})\.(-|\d{1,2}-[0-9a-f]{16}(?:~\d{1,2}-[0-9a-f]{16}){0,3})\.([0-9a-f]{32})$/;
39
+ const signed = (ring, secret, visit) => mac(secret, [
40
+ "web",
41
+ "visitor",
42
+ ring.org ?? null,
43
+ visit.line,
44
+ visit.id,
45
+ visit.issued,
46
+ visit.tags,
47
+ ]).then((m) => m.slice(0, 32));
48
+ /** A new secret, for a visitor coming in by `line` from the networks tagged `tags` (`tagsOf`). */
49
+ export async function newSecret(ring, line, tags) {
50
+ const bytes = crypto.getRandomValues(new Uint8Array(16));
51
+ const id = btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_")
52
+ .replace(/=+$/, "");
53
+ const visit = { line, id, issued: Date.now(), tags };
54
+ const said = await signed(ring, ring.secrets[0], visit);
55
+ return `vis_${line}.${id}.${visit.issued.toString(36)}.${tags.join("~") || "-"}.${said}`;
56
+ }
57
+ /** What a secret says, when the app made it; undefined for anything else (forged, garbled). */
58
+ export async function visitOf(ring, secret) {
59
+ if (typeof secret !== "string")
60
+ return undefined;
61
+ const found = SHAPE.exec(secret);
62
+ if (!found)
63
+ return undefined;
64
+ const [, line, id, issued, tagged, said] = found;
65
+ const tags = tagged === "-" ? [] : tagged.split("~");
66
+ if (tags.some((tag) => !TAG.test(tag)))
67
+ return undefined;
68
+ const visit = { line, id, issued: parseInt(issued, 36), tags };
69
+ if (visit.issued > Date.now() + SKEW)
70
+ return undefined;
71
+ for (const key of ring.secrets) {
72
+ if (same(said, await signed(ring, key, visit)))
73
+ return { ...visit, secret: key };
74
+ }
75
+ return undefined;
76
+ }
77
+ /** The contact a visit is: by the secret that signed it, so the one before it still is who it was. */
78
+ export const contactOf = async (ring, visit) => `c-${(await mac(visit.secret, ["web", "contact", ring.org ?? null, visit.line, visit.id])).slice(0, 24)}`;
79
+ /** A web visitor's chat, from its contact: the same however often it's asked for. */
80
+ export const chatOf = async (ring, contact) => `web-${(await mac(ring.secrets[0], ["web", "chat", ring.org ?? null, contact])).slice(0, 24)}`;
81
+ /**
82
+ * What the networks an address is in (`networksOf`) are counted and kept as:
83
+ * each a tag, its prefix's length and an HMAC of it (`64-3f…`), never the
84
+ * address.
85
+ */
86
+ export const tagsOf = (ring, line, networks) => Promise.all(networks.map(async ({ network, bits }) => `${bits}-${(await mac(ring.secrets[0], ["web", "address", ring.org ?? null, line, network])).slice(0, 16)}`));
@@ -122,9 +122,9 @@ export declare const phone: {
122
122
  person?: string | undefined;
123
123
  contact?: string | undefined;
124
124
  name?: string | undefined;
125
+ since?: string | undefined;
125
126
  thread?: string | undefined;
126
127
  told?: string | undefined;
127
- since?: string | undefined;
128
128
  space?: string | undefined;
129
129
  linked?: string | undefined;
130
130
  tries?: number | undefined;
@@ -30,7 +30,7 @@
30
30
  * - **What agents say there** to them goes back to the phone, as WhatsApp
31
31
  * formats it, a long answer in several messages; "typing…" shows while
32
32
  * they work, and nothing says "please wait".
33
- * - **WhatsApp is a medium:** a View for it (renderer `whatsapp`) returns
33
+ * - **WhatsApp is a medium:** a View for it (medium `whatsapp`) returns
34
34
  * parts, each one WhatsApp message, built with the toolkit in the contract
35
35
  * (`text`, `buttons`, `list`, `carousel`, `image`, `document`), which
36
36
  * checks Meta's limits. A message shows through its `message` View (this
@@ -30,7 +30,7 @@
30
30
  * - **What agents say there** to them goes back to the phone, as WhatsApp
31
31
  * formats it, a long answer in several messages; "typing…" shows while
32
32
  * they work, and nothing says "please wait".
33
- * - **WhatsApp is a medium:** a View for it (renderer `whatsapp`) returns
33
+ * - **WhatsApp is a medium:** a View for it (medium `whatsapp`) returns
34
34
  * parts, each one WhatsApp message, built with the toolkit in the contract
35
35
  * (`text`, `buttons`, `list`, `carousel`, `image`, `document`), which
36
36
  * checks Meta's limits. A message shows through its `message` View (this
@@ -1,5 +1,5 @@
1
1
  /**
2
- * A chat message on WhatsApp (the `message` View, renderer `whatsapp`): its
2
+ * A chat message on WhatsApp (the `message` View, medium `whatsapp`): its
3
3
  * Markdown as WhatsApp formats it, in parts of at most 4096 characters split
4
4
  * where a reader would pause, then its files: pictures (jpeg or png, up to
5
5
  * 5 MB) as images, anything else as documents. A short text goes as the
@@ -24,7 +24,7 @@ export type { Completion, Generate } from "./shared/generate.js";
24
24
  export type { Embedding } from "./shared/embed.js";
25
25
  export type { Transcript } from "./shared/transcribe.js";
26
26
  export type { Effort, LlmAdapter, LlmChunk, LlmFile, LlmMessage, LlmRequest, LlmState, LlmTool, ToolCall, } from "./shared/types.js";
27
- export type { ModelUse, UseContext, UseListener } from "./shared/use.js";
27
+ export type { ModelCall, ModelUse, UseContext, UseListener } from "./shared/use.js";
28
28
  /** What `models.price` answers: the catalog's cost for a model, and which catalog said it. */
29
29
  export type Price = {
30
30
  cost?: Cost;
@@ -3,7 +3,7 @@ import { adapterFor, keyable, resolve, } from "./choice.js";
3
3
  import { filesFor } from "./files.js";
4
4
  import { calledBy } from "./provider.js";
5
5
  import { backoff, quietly, RETRY, SILENCE, transient, wait } from "./retry.js";
6
- import { used } from "./use.js";
6
+ import { mayUse, used } from "./use.js";
7
7
  import { measure } from "./telemetry.js";
8
8
  import { EFFORTS, } from "./types.js";
9
9
  /** Throws when a model can't take its settings: an effort it has no level for. */
@@ -90,13 +90,22 @@ async function keyed(ctx, m) {
90
90
  }
91
91
  /**
92
92
  * Whether what's about to run may spend (the `spending` resource: whoever
93
- * keeps an org's limits). Not asked from a read, for a model the app doesn't
94
- * pay for (the org's own key, a person's subscription). Saying no is final:
93
+ * keeps an org's limits), which isn't asked for a model the app doesn't pay for
94
+ * (the org's own key, a person's subscription). Saying no is final:
95
95
  * trying again won't help.
96
96
  */
97
97
  async function mayRun(ctx, m, request) {
98
+ // Whoever listens to model use may refuse it first (a web line's budget, spent): a model
99
+ // the app doesn't pay for too, since the line's budget counts a visitor's use of any.
100
+ await mayUse(ctx, {
101
+ meter: "llm",
102
+ subject: m.id,
103
+ ...(request.tags ? { tags: request.tags } : {}),
104
+ });
105
+ if (m.tags?.paid)
106
+ return;
98
107
  const spending = ctx.resources.spending;
99
- if (!spending?.check || !ctx.as || m.tags?.paid)
108
+ if (!spending?.check || !ctx.as)
100
109
  return;
101
110
  const purpose = request.tags?.purpose;
102
111
  const verdict = await ctx.as().call(spending.check, purpose ? { purpose } : {});