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
@@ -12,7 +12,7 @@
12
12
  * MCP. No cookie is read: whoever calls is nobody but their
13
13
  * conversation's contact.
14
14
  * - **Who calls.** With the app's `caller` settings, the caller's address,
15
- * as its front says it (see shared/caller.ts); a request that came around
15
+ * as its front says it (the runtime's `callerFrom`); a request that came around
16
16
  * the front (without its secret) is refused (403).
17
17
  * - **At once.** Tool calls running at once: in the runtime (`mcp.atOnce`,
18
18
  * 4), on the line (`limits.atOnce`, 4), from one caller's address
@@ -39,17 +39,22 @@
39
39
  * request without `MCP-Protocol-Version` is 2025-03-26). Any other is 400,
40
40
  * -32022, with those it takes.
41
41
  * - **Methods.** `initialize`, `server/discover`, `ping`, `tools/list`,
42
- * `tools/call` (see tools.ts). Tools are all the server has.
42
+ * `tools/call` (see tools.ts); with widgets (a line whose tools are shown
43
+ * through the app's web Views, and the web host's `widgets`: see
44
+ * widgets.ts), `resources/list` and `resources/read` (the widgets'
45
+ * template), and the widgets' own calls: the entries only they may call,
46
+ * refused without their grant, which the model never has.
43
47
  *
44
48
  * Sources: https://modelcontextprotocol.io/specification/2026-07-28 (transport,
45
49
  * versioning, tools), https://modelcontextprotocol.io/specification/2025-11-25,
46
50
  * https://developers.openai.com/apps-sdk/reference (ChatGPT's `_meta`).
47
51
  */
48
- import { linksOf } from "../../../../runtime/mod.js";
49
- import { callerFrom } from "../shared/caller.js";
50
- import { atOnceOf, callerOf, lineOf, PATH } from "../shared/settings.js";
51
- import { isBusy } from "./running.js";
52
- import { called, listed, mirrored, offeredOf, usable } from "./tools.js";
52
+ import { callerFrom, linksOf, secretsOf, } from "../../../../runtime/mod.js";
53
+ import { addressKey, callIdOf, threadOf, userOf } from "../shared/keys.js";
54
+ import { appOnly, atOnceOf, callerOf, lineOf, PATH, READ } from "../shared/settings.js";
55
+ import { busy, hold, isBusy } from "./running.js";
56
+ import { called, conversationHere, listed, mirrored, offeredOf, usable, } from "./tools.js";
57
+ import { appCalled, CALL, grantedContact, NOT_YOURS, resourceRead, resourcesListed, templateOf, widgetMeta, } from "./widgets.js";
53
58
  /** The version without a handshake, and the ones with one, newest first. */
54
59
  const MODERN = "2026-07-28";
55
60
  const LEGACY = ["2025-11-25", "2025-06-18", "2025-03-26"];
@@ -123,8 +128,8 @@ export async function serveMcp(request, host) {
123
128
  catch {
124
129
  return respond(400, fault(undefined, PARSE, "Parse error"));
125
130
  }
126
- const secret = linksOf(resources)?.secret;
127
- if (!secret)
131
+ const links = linksOf(resources);
132
+ if (!links)
128
133
  return respond(500, fault(undefined, INTERNAL, "Internal error"));
129
134
  const org = resources.org?.id;
130
135
  const { runtime } = host;
@@ -134,8 +139,10 @@ export async function serveMcp(request, host) {
134
139
  resources,
135
140
  request,
136
141
  caller,
137
- scope: { line: line.name, ...(org ? { org } : {}), secret },
142
+ scope: { line: line.name, ...(org ? { org } : {}), secrets: secretsOf(links) },
138
143
  atOnce: atOnceOf({ resources }),
144
+ ...(host.widgets ? { widgets: host.widgets } : {}),
145
+ origin: linksOf(resources)?.origin,
139
146
  };
140
147
  if (Array.isArray(parsed)) {
141
148
  // Batches were MCP's only in 2025-03-26.
@@ -261,9 +268,9 @@ async function answered(c, raw, batched) {
261
268
  try {
262
269
  switch (method) {
263
270
  case "initialize":
264
- return ok(initialized(c.line, params));
271
+ return ok(initialized(c.line, params, await withWidgets(c)));
265
272
  case "server/discover":
266
- return ok(discovered(c.line));
273
+ return ok(discovered(c.line, await withWidgets(c)));
267
274
  case "ping":
268
275
  return ok({});
269
276
  case "tools/list": {
@@ -271,16 +278,42 @@ async function answered(c, raw, batched) {
271
278
  return failed(status(PARAMS), rpc, PARAMS, "No such cursor");
272
279
  }
273
280
  const names = await offeredOf(c.runtime, c.line, usable(c.runtime, c.line));
281
+ const template = await templateOf(c.line, c.widgets, c.origin);
274
282
  return ok({
275
- tools: listed(c.line, c.resources, names),
283
+ tools: listed(c.line, c.resources, names, c.runtime.describe().actions, template?.uri),
276
284
  ttlMs: TTL_MS,
277
285
  cacheScope: "public",
278
286
  });
279
287
  }
288
+ case "resources/list":
289
+ case "resources/templates/list":
290
+ case "resources/read": {
291
+ // The template is large (an app's whole widget code): a caller reads it a few times a
292
+ // minute, not in a loop.
293
+ if (method === "resources/read" && !counted(c, "read", READS_A_MINUTE))
294
+ throw busy();
295
+ // Resources are the widgets' template: without widgets, there are none to ask about.
296
+ if (!await withWidgets(c))
297
+ return failed(status(METHOD), rpc, METHOD, "Method not found");
298
+ if (method === "resources/list") {
299
+ return ok(await resourcesListed(c.line, c.widgets, c.origin));
300
+ }
301
+ if (method === "resources/templates/list")
302
+ return ok({ resourceTemplates: [] });
303
+ const read = await resourceRead(c.line, c.widgets, c.origin, params.uri);
304
+ if (!read) {
305
+ return failed(status(PARAMS), rpc, PARAMS, `No such resource: ${String(params.uri).slice(0, 200)}`);
306
+ }
307
+ return ok(read);
308
+ }
280
309
  case "tools/call": {
281
310
  const tool = params.name;
282
311
  const input = params.arguments ?? {};
283
- if (typeof tool !== "string" || !usable(c.runtime, c.line).includes(tool)) {
312
+ const template = await templateOf(c.line, c.widgets, c.origin);
313
+ const theirs = typeof tool === "string" && (tool === READ || (Object.hasOwn(c.line.tools, tool) && appOnly(c.line.tools[tool])));
314
+ // What only the widgets call exists only where they do.
315
+ if (typeof tool !== "string" || (theirs && !template) ||
316
+ (tool !== READ && !usable(c.runtime, c.line).includes(tool))) {
284
317
  return failed(status(PARAMS), rpc, PARAMS, `Unknown tool: ${String(tool).slice(0, 128)}`);
285
318
  }
286
319
  if (!isObject(input))
@@ -292,14 +325,25 @@ async function answered(c, raw, batched) {
292
325
  if (!conversation) {
293
326
  return failed(status(PARAMS), rpc, PARAMS, "openai/session and openai/subject are text");
294
327
  }
295
- return ok(await called(c.runtime, c.line, c.scope, {
328
+ if (theirs)
329
+ return ok(await widgetCalled(c, tool, input, rpc, conversation, meta));
330
+ const { conversation: whose, ...result } = await called(c.runtime, c.line, c.scope, {
296
331
  tool,
297
332
  input,
298
333
  request: rpc,
299
334
  said: conversation,
300
335
  caller: c.caller,
301
336
  atOnce: c.atOnce,
302
- }));
337
+ });
338
+ // Drawn by a widget: what it draws, for the widget alone (`_meta`: never the model's).
339
+ const drawn = template && c.widgets && c.line.tools[tool]?.widget && whose &&
340
+ !result.isError;
341
+ return ok(drawn
342
+ ? {
343
+ ...result,
344
+ _meta: await widgetMeta(c.runtime, c.widgets, c.line, c.scope, { tool, input }, whose),
345
+ }
346
+ : result);
303
347
  }
304
348
  default:
305
349
  return failed(status(METHOD), rpc, METHOD, "Method not found");
@@ -386,27 +430,125 @@ function headerProblem(c, method, params, said) {
386
430
  }
387
431
  return undefined;
388
432
  }
433
+ /** How many times a minute one caller's address reads the template, and asks for the tools. */
434
+ const READS_A_MINUTE = 30;
435
+ /** What's asked of a line besides tool calls, by caller's address, this minute (in this process). */
436
+ const asked = new Map();
437
+ /** Counts one of a caller's asks; false past `most` a minute. Callers the front exempts aren't counted. */
438
+ function counted(c, what, most) {
439
+ if (c.caller?.exempt)
440
+ return true;
441
+ const minute = Math.floor(Date.now() / 60_000);
442
+ const key = `${c.line.name}|${what}|${c.caller?.counted ?? "unknown"}`;
443
+ const seen = asked.get(key);
444
+ const count = seen?.minute === minute ? seen.count : 0;
445
+ if (count >= most)
446
+ return false;
447
+ asked.set(key, { minute, count: count + 1 });
448
+ if (asked.size > 10_000) {
449
+ for (const [k, v] of asked)
450
+ if (v.minute !== minute)
451
+ asked.delete(k);
452
+ }
453
+ return true;
454
+ }
455
+ /** Whether the line's widgets are served here: a template to draw them in. */
456
+ const withWidgets = async (c) => !!await templateOf(c.line, c.widgets, c.origin);
457
+ /**
458
+ * A call to what only the line's widgets call (see widgets.ts): refused to anyone without the
459
+ * widget's grant (the model never has one), and to a grant from another conversation than the
460
+ * one the call names; else made, as the conversation's contact, within its places at once.
461
+ */
462
+ async function widgetCalled(c, tool, input, request, said, meta) {
463
+ const [secret] = c.scope.secrets;
464
+ // The conversation the call names (ChatGPT's always do): its contact and chat, under whichever
465
+ // of the app's secrets it was made with.
466
+ const named = said.session === undefined
467
+ ? undefined
468
+ : await conversationHere(c.runtime, c.scope, {
469
+ session: said.session,
470
+ ...(said.subject ? { subject: said.subject } : {}),
471
+ });
472
+ const contact = await grantedContact(c.scope, c.line, input, meta, () => Promise.resolve(named?.contact));
473
+ if (!contact)
474
+ return { content: [{ type: "text", text: NOT_YOURS }], isError: true };
475
+ const entry = tool === READ ? undefined : c.line.tools[tool];
476
+ const { _grant: _, ...rest } = input;
477
+ // A tool only the widgets call runs as any tool does, for the grant's conversation (what it
478
+ // would read after is the widget's to ask: a tool takes only its own input).
479
+ if (entry && !entry.action) {
480
+ const { _reads: _after, ...own } = rest;
481
+ const { conversation: _whose, ...result } = await called(c.runtime, c.line, c.scope, {
482
+ tool,
483
+ input: own,
484
+ request,
485
+ said,
486
+ caller: c.caller,
487
+ atOnce: c.atOnce,
488
+ contact,
489
+ ...(named ? { thread: named.thread } : {}),
490
+ });
491
+ return result;
492
+ }
493
+ const address = c.caller && !c.caller.exempt ? c.caller.counted : undefined;
494
+ const thread = named?.thread ?? await threadOf(secret, contact);
495
+ const release = hold(c.runtime, [
496
+ { key: "runtime", most: c.atOnce },
497
+ { key: `line:${c.line.name}`, most: c.line.limits.atOnce },
498
+ ...(address
499
+ ? [{ key: `address:${c.line.name}|${address}`, most: c.line.limits.addressAtOnce }]
500
+ : []),
501
+ { key: `chat:${c.line.name}|${thread}`, most: c.line.limits.chatAtOnce },
502
+ ]);
503
+ if (!release)
504
+ throw busy();
505
+ try {
506
+ // The call's id: its own (`_call`, which a retry of it shares), never the JSON-RPC request's
507
+ // alone (a host may number its requests from 1 again: two taps would be one call).
508
+ const own = typeof rest[CALL] === "string" && /^[\w-]{8,64}$/.test(rest[CALL])
509
+ ? rest[CALL]
510
+ : crypto.randomUUID();
511
+ const [id, user, counted] = await Promise.all([
512
+ callIdOf(thread, own, tool, rest),
513
+ said.subject ? userOf(secret, c.scope, said.subject) : undefined,
514
+ address ? addressKey(secret, address) : undefined,
515
+ ]);
516
+ return await appCalled(c.runtime, c.line, c.scope, {
517
+ tool,
518
+ input: rest,
519
+ contact,
520
+ thread,
521
+ id,
522
+ ...(user ? { user } : {}),
523
+ ...(counted ? { address: counted } : {}),
524
+ });
525
+ }
526
+ finally {
527
+ release();
528
+ }
529
+ }
389
530
  /** Who the server is. */
390
531
  const serverOf = (line) => ({
391
532
  name: line.name,
392
533
  ...(line.title ? { title: line.title } : {}),
393
534
  version: line.version,
394
535
  });
395
- const CAPABILITIES = { tools: {} };
536
+ /** What the server has: tools, and with widgets, their template (a resource). */
537
+ const capabilitiesOf = (widgets) => widgets ? { tools: {}, resources: {} } : { tools: {} };
396
538
  /** A legacy client's handshake: the version it asked for when taken, else the newest legacy one. */
397
- function initialized(line, params) {
539
+ function initialized(line, params, widgets) {
398
540
  const asked = params.protocolVersion;
399
541
  return {
400
542
  protocolVersion: typeof asked === "string" && LEGACY.includes(asked) ? asked : LEGACY[0],
401
- capabilities: CAPABILITIES,
543
+ capabilities: capabilitiesOf(widgets),
402
544
  serverInfo: serverOf(line),
403
545
  ...(line.instructions ? { instructions: line.instructions } : {}),
404
546
  };
405
547
  }
406
548
  /** What `server/discover` says: versions, what it has, who it is. */
407
- const discovered = (line) => ({
549
+ const discovered = (line, widgets) => ({
408
550
  supportedVersions: VERSIONS,
409
- capabilities: CAPABILITIES,
551
+ capabilities: capabilitiesOf(widgets),
410
552
  _meta: { "io.modelcontextprotocol/serverInfo": serverOf(line) },
411
553
  ...(line.instructions ? { instructions: line.instructions } : {}),
412
554
  ttlMs: TTL_MS,
@@ -33,9 +33,8 @@
33
33
  * content (a result's `_meta` is the host's, never the model's), so
34
34
  * that's where it must be. On a line without handles, it's refused.
35
35
  */
36
- import type { Runtime } from "../../../../runtime/mod.js";
37
- import type { Caller } from "../shared/caller.js";
38
- import { type Scope } from "../shared/keys.js";
36
+ import type { Caller, Runtime } from "../../../../runtime/mod.js";
37
+ import { type Key, type Scope } from "../shared/keys.js";
39
38
  import { type Line } from "../shared/settings.js";
40
39
  type Resources = Record<string, Record<string, unknown>>;
41
40
  /** What a tool's input says, as far as the route looks into it. */
@@ -44,7 +43,10 @@ type Schema = {
44
43
  properties?: Record<string, unknown>;
45
44
  [key: string]: unknown;
46
45
  };
47
- /** The tools the line lists that have their `tool:<name>` View; the others, said once in the log. */
46
+ /**
47
+ * The tools the line lists that have their `tool:<name>` View (an Action offered to the widgets
48
+ * needs none: its result goes to the widget alone); the others, said once in the log.
49
+ */
48
50
  export declare function usable(runtime: Pick<Runtime, "describe">, line: Line): string[];
49
51
  /**
50
52
  * Of `names`, those a contact is offered, before any conversation (a
@@ -52,8 +54,19 @@ export declare function usable(runtime: Pick<Runtime, "describe">, line: Line):
52
54
  * are asked; nothing is read when none is.
53
55
  */
54
56
  export declare function offeredOf(runtime: Pick<Runtime, "describe" | "observe">, line: Line, names: string[]): Promise<string[]>;
55
- /** The tools `names` (the line's), as `tools/list` answers them. */
56
- export declare function listed(line: Line, resources: Resources, names: string[]): {
57
+ /** What a widget's call carries beside its input: its grant, and the reads to answer after. */
58
+ export declare const GRANT = "_grant";
59
+ export declare const READS = "_reads";
60
+ /**
61
+ * The tools `names` (the line's), as `tools/list` answers them. With widgets (`template`: the
62
+ * URI of the page their Views are drawn in), each says who may call it (`ui.visibility`; ChatGPT's
63
+ * `openai/visibility` and `openai/widgetAccessible`), a tool shown through a widget says its
64
+ * template (`ui.resourceUri`, `openai/outputTemplate`), and the widgets' read tool is listed too.
65
+ */
66
+ export declare function listed(line: Line, resources: Resources, names: string[], actions?: Record<string, {
67
+ description?: string;
68
+ input?: unknown;
69
+ }>, template?: string): ({
57
70
  description: string;
58
71
  inputSchema: Schema;
59
72
  annotations: {
@@ -69,12 +82,43 @@ export declare function listed(line: Line, resources: Resources, names: string[]
69
82
  securitySchemes: {
70
83
  type: string;
71
84
  }[];
85
+ "openai/visibility"?: string | undefined;
86
+ "openai/widgetAccessible"?: boolean | undefined;
87
+ "openai/outputTemplate"?: string | undefined;
88
+ ui?: {
89
+ resourceUri?: string | undefined;
90
+ visibility: import("../shared/settings.js").Visibility[];
91
+ } | undefined;
72
92
  "openai/toolInvocation/invoked"?: string | undefined;
73
93
  "openai/toolInvocation/invoking"?: string | undefined;
74
94
  };
75
95
  title?: string | undefined;
76
96
  name: string;
77
- }[];
97
+ } | {
98
+ name: string;
99
+ title: string;
100
+ description: string;
101
+ inputSchema: Schema;
102
+ annotations: {
103
+ readOnlyHint: boolean;
104
+ destructiveHint: boolean;
105
+ idempotentHint: boolean;
106
+ openWorldHint: boolean;
107
+ };
108
+ securitySchemes: {
109
+ type: string;
110
+ }[];
111
+ _meta: {
112
+ ui: {
113
+ visibility: string[];
114
+ };
115
+ "openai/widgetAccessible": boolean;
116
+ "openai/visibility": string;
117
+ securitySchemes: {
118
+ type: string;
119
+ }[];
120
+ };
121
+ })[];
78
122
  /**
79
123
  * The input properties a tool mirrors into headers (`x-mcp-header`, MCP
80
124
  * 2026-07-28): each header's name and where its value is in the input.
@@ -88,13 +132,26 @@ export type Said = {
88
132
  session?: string;
89
133
  subject?: string;
90
134
  };
135
+ /**
136
+ * The conversation a key names: its contact and chat under the app's own
137
+ * secret, or under the one before it (`links.previous`) when that's the one
138
+ * there (made before the secret changed): the owner says which.
139
+ */
140
+ export declare function conversationHere(runtime: Pick<Runtime, "call">, scope: Scope & {
141
+ secrets: string[];
142
+ }, key: Key): Promise<{
143
+ contact: string;
144
+ thread: string;
145
+ }>;
91
146
  /**
92
147
  * Runs a call (`tools/call`) on the line, for its conversation, and answers
93
148
  * as MCP does: the text, and `isError` when it didn't work. `request` is the
94
149
  * JSON-RPC request's id.
95
150
  */
96
- export declare function called(runtime: Pick<Runtime, "call" | "cancel" | "describe">, line: Line, scope: Scope & {
97
- secret: string;
151
+ export declare function called(runtime: Pick<Runtime, "call" | "cancel" | "describe">, line: Line,
152
+ /** The line's scope, and the app's secrets (`secretsOf`: its own first). */
153
+ scope: Scope & {
154
+ secrets: string[];
98
155
  }, call: {
99
156
  tool: string;
100
157
  input: Record<string, unknown>;
@@ -104,11 +161,30 @@ export declare function called(runtime: Pick<Runtime, "call" | "cancel" | "descr
104
161
  caller?: Exclude<Caller, "refused">;
105
162
  /** Calls the runtime runs at once. */
106
163
  atOnce: number;
107
- }): Promise<{
108
- isError?: boolean | undefined;
164
+ /**
165
+ * The conversation's contact, when a widget's grant named it (an app-only tool, called by
166
+ * the line's widgets): its conversation must be one already; and its chat, as the route
167
+ * found it.
168
+ */
169
+ contact?: string;
170
+ thread?: string;
171
+ }): Promise<Answered>;
172
+ /**
173
+ * What a call answers: MCP's content (and whether it's an error), and, when it ran, whose
174
+ * conversation it was and (for a tool shown through a widget) what the tool returned: for the
175
+ * route, which never sends it as it is.
176
+ */
177
+ export type Answered = {
109
178
  content: {
110
179
  type: string;
111
180
  text: string;
112
181
  }[];
113
- }>;
182
+ isError?: boolean;
183
+ conversation?: {
184
+ contact: string;
185
+ thread: string;
186
+ output?: string;
187
+ call?: string;
188
+ };
189
+ };
114
190
  export {};
@@ -1,16 +1,19 @@
1
- import { addressKey, callIdOf, conversationOf, HANDLE, newHandle, sameCallOf, userOf, } from "../shared/keys.js";
2
- import { hintsOf } from "../shared/settings.js";
1
+ import { addressKey, callIdOf, conversationsOf, HANDLE, newHandle, sameCallOf, threadOf, userOf, } from "../shared/keys.js";
2
+ import { appOnly, hasWidgets, hintsOf, READ, visibilityOf } from "../shared/settings.js";
3
3
  import { busy, hold } from "./running.js";
4
4
  /** Who needs no sign-in: every tool, until a line signs people in. */
5
5
  const NOAUTH = [{ type: "noauth" }];
6
6
  const toolsOf = (resources) => (resources.tools ?? {});
7
7
  /** Lines already told about in the log, by runtime: once each. */
8
8
  const told = new WeakMap();
9
- /** The tools the line lists that have their `tool:<name>` View; the others, said once in the log. */
9
+ /**
10
+ * The tools the line lists that have their `tool:<name>` View (an Action offered to the widgets
11
+ * needs none: its result goes to the widget alone); the others, said once in the log.
12
+ */
10
13
  export function usable(runtime, line) {
11
14
  const { views } = runtime.describe();
12
15
  const names = Object.keys(line.tools);
13
- const shown = names.filter((name) => views[`tool:${name}`]?.includes("llm"));
16
+ const shown = names.filter((name) => line.tools[name].action !== undefined || views[`tool:${name}`]?.includes("llm"));
14
17
  const left = names.filter((name) => !shown.includes(name));
15
18
  const seen = told.get(runtime) ?? new Set();
16
19
  told.set(runtime, seen);
@@ -27,9 +30,9 @@ export function usable(runtime, line) {
27
30
  */
28
31
  export function offeredOf(runtime, line, names) {
29
32
  const tools = toolsOf(runtime.describe().resources);
30
- if (!names.some((name) => typeof tools[name]?.offer === "function")) {
33
+ const offers = (name) => line.tools[name]?.action === undefined && typeof tools[name]?.offer === "function";
34
+ if (!names.some(offers))
31
35
  return Promise.resolve(names);
32
- }
33
36
  // The same for every listing: asked once a minute, however many list at once.
34
37
  const lines = listings.get(runtime) ??
35
38
  new Map();
@@ -100,27 +103,89 @@ function mcpHintsOf(line, name, tool) {
100
103
  openWorldHint: said.openWorld ?? true,
101
104
  };
102
105
  }
103
- /** The tools `names` (the line's), as `tools/list` answers them. */
104
- export function listed(line, resources, names) {
106
+ /** What a widget's call carries beside its input: its grant, and the reads to answer after. */
107
+ export const GRANT = "_grant";
108
+ export const READS = "_reads";
109
+ /** An input as a widget's call takes it: with its grant (and, for an Action, reads to answer). */
110
+ const forWidgets = (input, reads) => ({
111
+ ...input,
112
+ properties: {
113
+ ...input.properties,
114
+ [GRANT]: {
115
+ type: "string",
116
+ description: "The widget's grant: its host passes it, from the tool result that drew it.",
117
+ },
118
+ _call: { type: "string", description: "This call's own id: a retry of it sends the same." },
119
+ ...(reads
120
+ ? { [READS]: { type: "array", maxItems: 32, description: "Reads to answer after it." } }
121
+ : {}),
122
+ },
123
+ });
124
+ /** The widgets' read tool, as listed: only they call it. */
125
+ const readTool = () => ({
126
+ name: READ,
127
+ title: "Read",
128
+ description: "What a widget of this app reads, as its conversation: named queries only.",
129
+ inputSchema: forWidgets({
130
+ type: "object",
131
+ properties: { reads: { type: "array", maxItems: 32 } },
132
+ required: ["reads"],
133
+ }, false),
134
+ annotations: {
135
+ readOnlyHint: true,
136
+ destructiveHint: false,
137
+ idempotentHint: true,
138
+ openWorldHint: false,
139
+ },
140
+ securitySchemes: NOAUTH,
141
+ _meta: {
142
+ ui: { visibility: ["app"] },
143
+ "openai/widgetAccessible": true,
144
+ "openai/visibility": "private",
145
+ securitySchemes: NOAUTH,
146
+ },
147
+ });
148
+ /**
149
+ * The tools `names` (the line's), as `tools/list` answers them. With widgets (`template`: the
150
+ * URI of the page their Views are drawn in), each says who may call it (`ui.visibility`; ChatGPT's
151
+ * `openai/visibility` and `openai/widgetAccessible`), a tool shown through a widget says its
152
+ * template (`ui.resourceUri`, `openai/outputTemplate`), and the widgets' read tool is listed too.
153
+ */
154
+ export function listed(line, resources, names, actions = {}, template) {
105
155
  const tools = toolsOf(resources);
106
- return names.map((name) => {
107
- const tool = tools[name];
156
+ const widgets = !!template && hasWidgets(line);
157
+ // Without widgets, what only they call isn't listed: nothing could call it.
158
+ const entries = names.filter((name) => widgets || !appOnly(line.tools[name])).map((name) => {
108
159
  const how = line.tools[name];
109
- const title = how.title ?? tool.title;
160
+ const action = how.action ? actions[how.action] : undefined;
161
+ const tool = how.action ? undefined : tools[name];
162
+ const title = how.title ?? tool?.title;
163
+ const app = appOnly(how);
164
+ const shown = !!(widgets && how.widget);
165
+ const input = action ? (action.input ?? { type: "object" }) : inputOf(line, tool);
110
166
  return {
111
167
  name,
112
168
  ...(title ? { title } : {}),
113
- description: tool.description,
114
- inputSchema: inputOf(line, tool),
115
- annotations: mcpHintsOf(line, name, tool),
169
+ description: action ? how.description ?? action.description ?? name : tool.description,
170
+ inputSchema: app ? forWidgets(input, !!action) : input,
171
+ annotations: mcpHintsOf(line, name, tool ?? {}),
116
172
  securitySchemes: NOAUTH,
117
173
  _meta: {
118
174
  ...(how.invoking ? { "openai/toolInvocation/invoking": how.invoking } : {}),
119
175
  ...(how.invoked ? { "openai/toolInvocation/invoked": how.invoked } : {}),
176
+ ...(widgets
177
+ ? {
178
+ ui: { visibility: visibilityOf(how), ...(shown ? { resourceUri: template } : {}) },
179
+ ...(shown ? { "openai/outputTemplate": template } : {}),
180
+ "openai/widgetAccessible": visibilityOf(how).includes("app"),
181
+ ...(app ? { "openai/visibility": "private" } : {}),
182
+ }
183
+ : {}),
120
184
  securitySchemes: NOAUTH,
121
185
  },
122
186
  };
123
187
  });
188
+ return widgets ? [...entries, readTool()] : entries;
124
189
  }
125
190
  /**
126
191
  * The input properties a tool mirrors into headers (`x-mcp-header`, MCP
@@ -144,13 +209,27 @@ export function mirrored(line, name, resources) {
144
209
  walk(toolsOf(resources)[name]?.input, []);
145
210
  return found;
146
211
  }
212
+ /**
213
+ * The conversation a key names: its contact and chat under the app's own
214
+ * secret, or under the one before it (`links.previous`) when that's the one
215
+ * there (made before the secret changed): the owner says which.
216
+ */
217
+ export async function conversationHere(runtime, scope, key) {
218
+ const each = await conversationsOf(scope.secrets, scope, key);
219
+ if (each.length === 1)
220
+ return each[0];
221
+ const at = await runtime.call("mcp.conversation", { conversations: each });
222
+ return each[at] ?? each[0];
223
+ }
147
224
  /**
148
225
  * Runs a call (`tools/call`) on the line, for its conversation, and answers
149
226
  * as MCP does: the text, and `isError` when it didn't work. `request` is the
150
227
  * JSON-RPC request's id.
151
228
  */
152
- export async function called(runtime, line, scope, call) {
153
- const { secret } = scope;
229
+ export async function called(runtime, line,
230
+ /** The line's scope, and the app's secrets (`secretsOf`: its own first). */
231
+ scope, call) {
232
+ const [secret] = scope.secrets;
154
233
  const input = { ...call.input };
155
234
  const given = input.chat;
156
235
  if (line.handles)
@@ -158,7 +237,10 @@ export async function called(runtime, line, scope, call) {
158
237
  let key;
159
238
  let made;
160
239
  let by;
161
- if (call.said.session !== undefined) {
240
+ if (call.contact !== undefined) {
241
+ by = "handle";
242
+ }
243
+ else if (call.said.session !== undefined) {
162
244
  key = {
163
245
  session: call.said.session,
164
246
  ...(call.said.subject ? { subject: call.said.subject } : {}),
@@ -181,7 +263,10 @@ export async function called(runtime, line, scope, call) {
181
263
  key = { handle: made };
182
264
  by = "new";
183
265
  }
184
- const { contact, thread } = await conversationOf(secret, scope, key);
266
+ // A widget's call names its conversation by its grant (the route found its chat).
267
+ const { contact, thread } = call.contact !== undefined
268
+ ? { contact: call.contact, thread: call.thread ?? await threadOf(secret, call.contact) }
269
+ : await conversationHere(runtime, scope, key);
185
270
  const [id, same] = await Promise.all([
186
271
  callIdOf(thread, call.request, call.tool, input),
187
272
  sameCallOf(thread, call.tool, input),
@@ -216,6 +301,7 @@ export async function called(runtime, line, scope, call) {
216
301
  tool: call.tool,
217
302
  input,
218
303
  call: id,
304
+ thread,
219
305
  by,
220
306
  ...(user ? { user } : {}),
221
307
  ...(counted ? { address: counted } : {}),
@@ -278,7 +364,15 @@ export async function called(runtime, line, scope, call) {
278
364
  ? `${said.slice(0, line.limits.result)}\n[…cut]`
279
365
  : said;
280
366
  // The handle, once: in the answer that made the conversation.
281
- return answer(made && done.ran ? `${text}\n\nchat: ${made}` : text, !!done.isError);
367
+ return {
368
+ ...answer(made && done.ran ? `${text}\n\nchat: ${made}` : text, !!done.isError),
369
+ // For a tool shown through a widget: whose conversation it is, and what the tool returned.
370
+ conversation: {
371
+ contact,
372
+ thread,
373
+ ...(done.output !== undefined ? { output: done.output, call: id } : {}),
374
+ },
375
+ };
282
376
  }
283
377
  /**
284
378
  * What an answer begins with when it's an identical, earlier request's (it ran once): so a model