@botiverse/porthole 0.6.0 → 0.8.0

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 (208) hide show
  1. package/README.md +25 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/bridge/bounded-text.d.ts +34 -0
  4. package/dist/bridge/bounded-text.js +188 -0
  5. package/dist/bridge/bridge.d.ts +38 -5
  6. package/dist/bridge/bridge.js +469 -39
  7. package/dist/bridge/json-data.d.ts +28 -0
  8. package/dist/bridge/json-data.js +86 -0
  9. package/dist/bridge/navigation.d.ts +5 -0
  10. package/dist/bridge/navigation.js +7 -0
  11. package/dist/bridge/refusal.d.ts +5 -1
  12. package/dist/bridge/refusal.js +17 -0
  13. package/dist/bridge/types.d.ts +73 -5
  14. package/dist/check/check.d.ts +7 -0
  15. package/dist/check/check.js +1 -0
  16. package/dist/check/instrument.d.ts +3 -0
  17. package/dist/check/lint.js +4 -2
  18. package/dist/check/page-source.js +1 -1
  19. package/dist/check/page.js +16 -0
  20. package/dist/check/tools.js +2 -3
  21. package/dist/compile/compile.d.ts +6 -0
  22. package/dist/compile/compile.js +3 -1
  23. package/dist/compile/policy.d.ts +55 -0
  24. package/dist/compile/policy.js +157 -0
  25. package/dist/config/capabilities.d.ts +85 -7
  26. package/dist/config/capabilities.js +32 -2
  27. package/dist/config/schema.d.ts +35 -0
  28. package/dist/config/validate.d.ts +9 -3
  29. package/dist/config/validate.js +92 -8
  30. package/dist/config/warnings.d.ts +20 -0
  31. package/dist/config/warnings.js +25 -0
  32. package/dist/conformance/behavior.js +46 -1
  33. package/dist/conformance/cookies.d.ts +15 -0
  34. package/dist/conformance/cookies.js +80 -0
  35. package/dist/conformance/harness/page.d.ts +1 -0
  36. package/dist/conformance/harness/page.js +9 -2
  37. package/dist/conformance/harness-source.js +1 -1
  38. package/dist/conformance/host-kit.js +5 -1
  39. package/dist/conformance/index.d.ts +11 -0
  40. package/dist/conformance/index.js +2 -0
  41. package/dist/conformance/limits.js +38 -1
  42. package/dist/conformance/runtime.d.ts +58 -0
  43. package/dist/conformance/runtime.js +324 -0
  44. package/dist/conformance/served.d.ts +2 -0
  45. package/dist/conformance/served.js +737 -4
  46. package/dist/files/paths.js +4 -0
  47. package/dist/guide/gates.d.ts +9 -0
  48. package/dist/guide/gates.js +31 -0
  49. package/dist/guide/guide.d.ts +2 -0
  50. package/dist/guide/guide.js +35 -33
  51. package/dist/guide/limits.js +4 -4
  52. package/dist/guide/runtime.d.ts +13 -0
  53. package/dist/guide/runtime.js +210 -0
  54. package/dist/host/create-host.js +73 -37
  55. package/dist/host/locate.js +8 -0
  56. package/dist/host/locator.js +7 -0
  57. package/dist/host/pages-of-set.d.ts +43 -0
  58. package/dist/host/pages-of-set.js +196 -0
  59. package/dist/host/types.d.ts +26 -1
  60. package/dist/index.d.ts +11 -4
  61. package/dist/index.js +11 -2
  62. package/dist/isolation/types.d.ts +8 -0
  63. package/dist/mcp/adapter.js +11 -15
  64. package/dist/node/index.d.ts +36 -4
  65. package/dist/node/index.js +402 -101
  66. package/dist/presets/presets.d.ts +22 -8
  67. package/dist/presets/presets.js +40 -8
  68. package/dist/protocol/live-data.d.ts +6 -2
  69. package/dist/protocol/live-data.js +20 -1
  70. package/dist/protocol/mcp-apps.d.ts +13 -2
  71. package/dist/protocol/mcp-apps.js +10 -2
  72. package/dist/protocol/message-text.d.ts +8 -0
  73. package/dist/protocol/message-text.js +29 -0
  74. package/dist/protocol/runtime-calls.d.ts +28 -0
  75. package/dist/protocol/runtime-calls.js +116 -0
  76. package/dist/protocol/shell-adapter.js +64 -25
  77. package/dist/react/context-notice.d.ts +32 -0
  78. package/dist/react/context-notice.js +28 -0
  79. package/dist/react/dialog.js +91 -16
  80. package/dist/react/frame.d.ts +25 -1
  81. package/dist/react/frame.js +85 -2
  82. package/dist/react/index.d.ts +2 -1
  83. package/dist/react/index.js +2 -1
  84. package/dist/runtime/contract.d.ts +201 -0
  85. package/dist/runtime/contract.js +245 -0
  86. package/dist/runtime/db.d.ts +188 -0
  87. package/dist/runtime/db.js +502 -0
  88. package/dist/runtime/declaration.d.ts +100 -0
  89. package/dist/runtime/declaration.js +363 -0
  90. package/dist/runtime/levels.d.ts +33 -0
  91. package/dist/runtime/levels.js +41 -0
  92. package/dist/runtime/requests.d.ts +125 -0
  93. package/dist/runtime/requests.js +215 -0
  94. package/dist/runtime/segments.d.ts +8 -0
  95. package/dist/runtime/segments.js +14 -0
  96. package/dist/runtime/types.generated.d.ts +1 -0
  97. package/dist/runtime/types.generated.js +19 -0
  98. package/dist/server/files.d.ts +19 -1
  99. package/dist/server/files.js +115 -6
  100. package/dist/server/host.d.ts +24 -2
  101. package/dist/server/host.js +137 -2
  102. package/dist/server/index.d.ts +3 -2
  103. package/dist/server/index.js +2 -1
  104. package/dist/server/peer.d.ts +4 -0
  105. package/dist/server/peer.js +19 -0
  106. package/dist/server/proxy.d.ts +6 -0
  107. package/dist/server/proxy.js +12 -3
  108. package/dist/server/pseudonym.d.ts +9 -0
  109. package/dist/server/pseudonym.js +20 -0
  110. package/dist/server/server.d.ts +0 -5
  111. package/dist/server/server.js +318 -52
  112. package/dist/server/types.d.ts +74 -2
  113. package/dist/shell/document.d.ts +16 -0
  114. package/dist/shell/document.js +19 -2
  115. package/dist/shell/legacy.d.ts +21 -0
  116. package/dist/shell/legacy.js +63 -0
  117. package/dist/shell/plan.d.ts +17 -1
  118. package/dist/shell/plan.js +13 -2
  119. package/dist/shell/runtime.js +390 -56
  120. package/dist/shell/use.d.ts +15 -0
  121. package/dist/shell/use.js +235 -0
  122. package/docs/ADOPTING.md +205 -15
  123. package/docs/ARCHITECTURE.md +34 -5
  124. package/docs/DECISIONS.md +1867 -11
  125. package/docs/DESIGN.md +137 -17
  126. package/docs/THREAT_MODEL.md +616 -0
  127. package/package.json +16 -3
  128. package/src/bridge/bounded-text.ts +240 -0
  129. package/src/bridge/bridge.ts +601 -51
  130. package/src/bridge/json-data.ts +95 -0
  131. package/src/bridge/navigation.ts +10 -0
  132. package/src/bridge/refusal.ts +17 -0
  133. package/src/bridge/types.ts +76 -5
  134. package/src/check/check.ts +8 -0
  135. package/src/check/instrument.ts +3 -0
  136. package/src/check/lint.ts +4 -2
  137. package/src/check/page.ts +16 -0
  138. package/src/check/tools.ts +2 -3
  139. package/src/compile/compile.ts +9 -1
  140. package/src/compile/policy.ts +177 -0
  141. package/src/config/capabilities.ts +71 -5
  142. package/src/config/schema.ts +35 -0
  143. package/src/config/validate.ts +141 -8
  144. package/src/config/warnings.ts +42 -0
  145. package/src/conformance/behavior.ts +54 -1
  146. package/src/conformance/cookies.ts +93 -0
  147. package/src/conformance/harness/page.ts +11 -2
  148. package/src/conformance/host-kit.ts +10 -1
  149. package/src/conformance/index.ts +17 -0
  150. package/src/conformance/limits.ts +39 -1
  151. package/src/conformance/runtime.ts +594 -0
  152. package/src/conformance/served.ts +888 -4
  153. package/src/files/paths.ts +4 -0
  154. package/src/guide/gates.ts +37 -0
  155. package/src/guide/guide.ts +61 -55
  156. package/src/guide/limits.ts +4 -4
  157. package/src/guide/runtime.ts +253 -0
  158. package/src/host/create-host.ts +88 -36
  159. package/src/host/locate.ts +10 -0
  160. package/src/host/locator.ts +11 -0
  161. package/src/host/pages-of-set.ts +226 -0
  162. package/src/host/types.ts +33 -1
  163. package/src/index.ts +94 -0
  164. package/src/isolation/types.ts +8 -0
  165. package/src/mcp/adapter.ts +16 -20
  166. package/src/node/index.ts +507 -116
  167. package/src/presets/presets.ts +67 -17
  168. package/src/protocol/live-data.ts +31 -3
  169. package/src/protocol/mcp-apps.ts +11 -2
  170. package/src/protocol/message-text.ts +36 -0
  171. package/src/protocol/runtime-calls.ts +141 -0
  172. package/src/protocol/shell-adapter.ts +79 -26
  173. package/src/react/context-notice.tsx +95 -0
  174. package/src/react/dialog.tsx +108 -15
  175. package/src/react/frame.tsx +120 -0
  176. package/src/react/index.ts +8 -1
  177. package/src/runtime/contract.ts +339 -0
  178. package/src/runtime/db.ts +650 -0
  179. package/src/runtime/declaration.ts +516 -0
  180. package/src/runtime/levels.ts +69 -0
  181. package/src/runtime/requests.ts +355 -0
  182. package/src/runtime/segments.ts +17 -0
  183. package/src/runtime/types.generated.ts +19 -0
  184. package/src/server/files.ts +138 -7
  185. package/src/server/host.ts +170 -3
  186. package/src/server/index.ts +4 -0
  187. package/src/server/peer.ts +21 -0
  188. package/src/server/proxy.ts +13 -3
  189. package/src/server/pseudonym.ts +21 -0
  190. package/src/server/server.ts +370 -57
  191. package/src/server/types.ts +73 -2
  192. package/src/shell/document.ts +29 -4
  193. package/src/shell/legacy.ts +64 -0
  194. package/src/shell/plan.ts +37 -3
  195. package/src/shell/runtime.ts +390 -56
  196. package/src/shell/use.ts +235 -0
  197. package/types/runtime/v1/artifact.d.ts +50 -0
  198. package/types/runtime/v1/assets.d.ts +43 -0
  199. package/types/runtime/v1/chat.d.ts +13 -0
  200. package/types/runtime/v1/clipboard.d.ts +14 -0
  201. package/types/runtime/v1/comments.d.ts +24 -0
  202. package/types/runtime/v1/context.d.ts +27 -0
  203. package/types/runtime/v1/data.d.ts +29 -0
  204. package/types/runtime/v1/db.d.ts +110 -0
  205. package/types/runtime/v1/downloads.d.ts +22 -0
  206. package/types/runtime/v1/links.d.ts +13 -0
  207. package/types/runtime/v1/porthole.d.ts +44 -0
  208. package/types/runtime/v1/user.d.ts +19 -0
@@ -1,3 +1,4 @@
1
+ import type { RuntimeVersion } from "../runtime/contract.ts";
1
2
  import type { CapabilityName } from "../config/capabilities.ts";
2
3
  import type {
3
4
  CapabilityConfig,
@@ -50,13 +51,24 @@ export interface PresetOptions {
50
51
  readonly storage?: StorageConfig;
51
52
  /** Where the content's errors go (`PortholeConfig.errors`); `none` drops `reportError`. */
52
53
  readonly errors?: "agent" | "host" | "none";
54
+ /**
55
+ * The capability runtime (P085): content reaches capabilities through `porthole.use`, and may
56
+ * be offered the runtime's own (`user`, `comments`, `artifact`, `assets`, `db`).
57
+ */
58
+ readonly runtime?: RuntimeVersion;
53
59
  }
54
60
 
61
+ /** What a live widget may say about a capability (P103): anything but origins of its own. */
62
+ export type LiveCapabilityConfig = Omit<CapabilityConfig, "connect" | "resource">;
63
+
55
64
  /**
56
65
  * The live widget's options (P079): a widget's, less egress, which stays closed (Porthole's own
57
- * libraries come with domain isolation). A host adds capabilities, or changes the data ones' gates.
66
+ * libraries come with domain isolation), and less a capability's own origins, which are egress
67
+ * too (P103). A host adds capabilities, or changes the data ones' gates.
58
68
  */
59
- export type LiveWidgetOptions = Omit<PresetOptions, "egress">;
69
+ export type LiveWidgetOptions = Omit<PresetOptions, "egress" | "capabilities"> & {
70
+ readonly capabilities?: { readonly [N in CapabilityName]?: LiveCapabilityConfig | false };
71
+ };
60
72
 
61
73
  /** The url preset's options: where the app is served, and the embedding page's extra frames. */
62
74
  export interface UrlPresetOptions {
@@ -149,6 +161,27 @@ const mergeEgress = (base: EgressConfig, extra: EgressConfig | undefined): Egres
149
161
  return merged;
150
162
  };
151
163
 
164
+ /**
165
+ * A frozen copy of a config's data, all the way down (P103): what a host passed in stays its own
166
+ * and mutable; the copy can't be written into (a capability's `connect`, an egress origin).
167
+ */
168
+ function frozenCopy<T>(value: T): T {
169
+ if (Array.isArray(value)) {
170
+ return Object.freeze(value.map((each: unknown) => frozenCopy(each))) as T;
171
+ }
172
+ if (value !== null && typeof value === "object") {
173
+ const prototype: unknown = Object.getPrototypeOf(value);
174
+ if (prototype === Object.prototype || prototype === null) {
175
+ const copy: Record<string, unknown> = {};
176
+ for (const [key, each] of Object.entries(value)) {
177
+ copy[key] = frozenCopy(each);
178
+ }
179
+ return Object.freeze(copy) as T;
180
+ }
181
+ }
182
+ return value;
183
+ }
184
+
152
185
  /** The default variables, with the host's changes and additions, less those it dropped (null). */
153
186
  function themeVariables(
154
187
  changes: Readonly<Record<string, ThemeValue | null>> | undefined,
@@ -207,6 +240,7 @@ function build(
207
240
  embedder: options.embedder ?? {},
208
241
  ...(options.storage === undefined ? {} : { storage: options.storage }),
209
242
  ...(options.errors === undefined ? {} : { errors: options.errors }),
243
+ ...(options.runtime === undefined ? {} : { runtime: options.runtime }),
210
244
  });
211
245
  }
212
246
 
@@ -219,12 +253,13 @@ export const presets = {
219
253
 
220
254
  /**
221
255
  * A widget that shows its host's data, live, and has no network of its own (P079): an inline
222
- * widget whose egress stays closed (no option opens it). It reads the host's data (`readData`,
223
- * MCP `resources/read`) and subscribes to it (`subscribeData`, `resources/subscribe`), each
224
- * behind the viewer's consent (the host's `consent`, asked once per display) and a rate. In
225
- * domain isolation its scripts load from Porthole's own libraries on its origin
226
- * (`egress.libraries`: Chart.js, D3), and nowhere else. A host adds what any widget may have (a
227
- * link, a copy button), or changes the data capabilities' gates.
256
+ * widget whose egress stays closed (no option opens it: neither `egress` nor a capability's own
257
+ * `connect` or `resource`, P103). It reads the host's data (`readData`, MCP `resources/read`)
258
+ * and subscribes to it (`subscribeData`, `resources/subscribe`), each behind the viewer's
259
+ * consent (the host's `consent`, asked once per display) and a rate. In domain isolation its
260
+ * scripts load from Porthole's own libraries on its origin (`egress.libraries`: Chart.js, D3),
261
+ * and nowhere else. A host adds what any widget may have (a link, a copy button), or changes the
262
+ * data capabilities' gates.
228
263
  */
229
264
  liveWidget: (options: LiveWidgetOptions = {}): PortholeConfig => {
230
265
  if ((options as PresetOptions).egress !== undefined) {
@@ -233,16 +268,31 @@ export const presets = {
233
268
  "a live widget has no network of its own: its egress stays closed (P079)",
234
269
  );
235
270
  }
236
- return build(
237
- "inline",
238
- {
239
- capabilities: {
240
- readData: { gates: ["consent", { rateLimit: { perMinute: 120 } }] },
241
- subscribeData: { gates: ["consent", { rateLimit: { perMinute: 60 } }] },
271
+ // A capability's own origins join the CSP as egress does (P103): none for a live widget.
272
+ for (const [name, value] of Object.entries((options as PresetOptions).capabilities ?? {})) {
273
+ for (const field of ["connect", "resource"] as const) {
274
+ if (typeof value === "object" && value !== null && value[field] !== undefined) {
275
+ throw new ConfigError(
276
+ `options.capabilities.${name}.${field}`,
277
+ "a live widget has no network of its own: no capability opens origins for it (P079, P103)",
278
+ );
279
+ }
280
+ }
281
+ }
282
+ // Frozen, all the way down (P103): nothing writes an origin into the preset's config after it
283
+ // is made. A config a host builds from it (a spread) is the host's own, not this preset.
284
+ return frozenCopy(
285
+ build(
286
+ "inline",
287
+ {
288
+ capabilities: {
289
+ readData: { gates: ["consent", { rateLimit: { perMinute: 120 } }] },
290
+ subscribeData: { gates: ["consent", { rateLimit: { perMinute: 60 } }] },
291
+ },
292
+ egress: options.isolation === "domain" ? { libraries: true } : {},
242
293
  },
243
- egress: options.isolation === "domain" ? { libraries: true } : {},
244
- },
245
- options,
294
+ options,
295
+ ),
246
296
  );
247
297
  },
248
298
 
@@ -6,10 +6,14 @@ import { STALE_META } from "./mcp-apps.ts";
6
6
  * `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`): the frame's
7
7
  * subscriptions by URI, each ended by its controller, and a fresh result the host gave for one
8
8
  * (pushed through `changed(result)`, or read after a stale answer), kept for the frame's next read
9
- * of it. Every call goes through the bridge, which gates it; the adapter only says what to send.
9
+ * of it. Every call goes through the bridge, which gates it, a read answered by a kept result too
10
+ * (P094); the adapter only says what to send.
10
11
  */
11
12
  export interface LiveData {
12
- /** A read: a fresh result kept for it, else the host's (its cache first, when subscribed). */
13
+ /**
14
+ * A read, past the read's gates whatever answers it: a fresh result kept for it, else the
15
+ * host's (its cache first, when subscribed).
16
+ */
13
17
  read(uri: unknown): Promise<CallOutcome<unknown>>;
14
18
  /** Starts the host's subscription; a second for a URI is a no-op. */
15
19
  subscribe(uri: unknown): Promise<CallOutcome<undefined>>;
@@ -19,6 +23,12 @@ export interface LiveData {
19
23
  close(): void;
20
24
  }
21
25
 
26
+ /**
27
+ * The most resources one frame follows at once (P095), as the runtime's watches (50): past it a
28
+ * subscription is refused as too large, and the host isn't asked.
29
+ */
30
+ const MAX_SUBSCRIPTIONS = 50;
31
+
22
32
  /** Where MCP results carry their metadata. */
23
33
  const META = "_meta";
24
34
 
@@ -62,9 +72,20 @@ export function liveData(
62
72
  return {
63
73
  async read(uri) {
64
74
  if (typeof uri === "string" && fresh.has(uri)) {
75
+ // A kept result is the host's answer to a read: it goes through the read's gates as any
76
+ // read does (level, names, rate, gesture, consent, confirm), with no new upstream call
77
+ // (P094). Used once; kept again if the gates refused it and nothing newer came.
65
78
  const value = fresh.get(uri);
66
79
  fresh.delete(uri);
67
- return { ok: true, value };
80
+ const outcome = await bridge.call(
81
+ "readData",
82
+ { uri },
83
+ { ...activation(), held: { uri, value } },
84
+ );
85
+ if (!outcome.ok && !closed && subscriptions.has(uri) && !fresh.has(uri)) {
86
+ fresh.set(uri, value);
87
+ }
88
+ return outcome;
68
89
  }
69
90
  const subscribed = typeof uri === "string" && subscriptions.has(uri);
70
91
  const outcome = await bridge.call(
@@ -90,6 +111,13 @@ export function liveData(
90
111
  if (typeof uri === "string" && subscriptions.has(uri)) {
91
112
  return { ok: true, value: undefined };
92
113
  }
114
+ if (subscriptions.size >= MAX_SUBSCRIPTIONS) {
115
+ return {
116
+ ok: false,
117
+ refusal: "too-large",
118
+ reason: { code: "too_large", message: "Too many things followed at once." },
119
+ };
120
+ }
93
121
  const controller = new AbortController();
94
122
  if (typeof uri === "string") {
95
123
  subscriptions.set(uri, controller);
@@ -42,6 +42,13 @@ export const MCP_APPS_METHODS = {
42
42
 
43
43
  export type McpAppsMethod = (typeof MCP_APPS_METHODS)[keyof typeof MCP_APPS_METHODS];
44
44
 
45
+ /**
46
+ * What a host that declares `setModelContext` says it takes (`hostCapabilities.updateModelContext`),
47
+ * in both adapters: text blocks and structured content, exactly what the bridge accepts and the
48
+ * person is shown (P100). Images and other blocks aren't offered, and are refused.
49
+ */
50
+ export const MODEL_CONTEXT_OFFERED = { text: {}, structuredContent: {} } as const;
51
+
45
52
  /**
46
53
  * What the shell's `tool-input(-partial)` carries: the content to draw. Porthole's own argument
47
54
  * names, since the shell is the only view that reads them.
@@ -142,8 +149,10 @@ export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
142
149
 
143
150
  /**
144
151
  * Porthole's own notification from the shell (P084): a page that came with files is opening
145
- * another page of its set, `{ url }`, in the frame. The host takes the frame's next load for that
146
- * page rather than for content that left (P031). The content's word: it only spares a restart.
152
+ * another page of its set, `{ url }`, in the frame; and, as it arrives, the page a navigation
153
+ * opened says so, `{ url, arrived: true }` (P098). The host takes the frame's next load (or the
154
+ * load it came after, within `LATE_NOTICE_MS`) for that page rather than for content that left
155
+ * (P031). The content's word: it only spares a restart.
147
156
  */
148
157
  export const NAVIGATING_METHOD = "porthole/navigating";
149
158
 
@@ -0,0 +1,36 @@
1
+ /** The most content blocks a message's text is read from: more is no message a person sends. */
2
+ const MAX_BLOCKS = 1_000;
3
+
4
+ /**
5
+ * The text of a `ui/message`'s content blocks, the adapters' one reading of it: its text blocks'
6
+ * text, in order, joined by `separator`; null where there is none, or more blocks than a message
7
+ * holds. Read before any gate, so only as far as `max` characters (S05's class, P095: structured
8
+ * clone delivers a sparse array of any length, or one block shared a million times, for the cost
9
+ * of one): past it, `max + 1` characters, which the bridge refuses as too long.
10
+ */
11
+ export function messageText(
12
+ blocks: readonly unknown[],
13
+ separator: string,
14
+ max: number,
15
+ ): string | null {
16
+ if (blocks.length > MAX_BLOCKS) {
17
+ return null;
18
+ }
19
+ let text: string | null = null;
20
+ for (let index = 0; index < blocks.length; index += 1) {
21
+ const block = blocks[index] as { type?: unknown; text?: unknown } | null | undefined;
22
+ if (
23
+ block !== null &&
24
+ typeof block === "object" &&
25
+ !Array.isArray(block) &&
26
+ block.type === "text" &&
27
+ typeof block.text === "string"
28
+ ) {
29
+ text = text === null ? block.text : `${text}${separator}${block.text}`;
30
+ if (text.length > max) {
31
+ return text.slice(0, max + 1);
32
+ }
33
+ }
34
+ }
35
+ return text;
36
+ }
@@ -0,0 +1,141 @@
1
+ import type { CallOutcome, HostFunctionBridge } from "../bridge/types.ts";
2
+ import { reasonFor, type RefusalReason } from "../bridge/refusal.ts";
3
+ import type { CapabilityName } from "../config/capabilities.ts";
4
+ import {
5
+ RUNTIME_CAPABILITIES,
6
+ RUNTIME_EVENT_METHOD,
7
+ isRuntimeCapabilityName,
8
+ type RuntimeMethod,
9
+ } from "../runtime/contract.ts";
10
+ import { DB_LIMITS } from "../runtime/db.ts";
11
+ import { downloadContents } from "../runtime/requests.ts";
12
+
13
+ /**
14
+ * The host side of the capability runtime's calls (P085): `porthole/call` with `{ capability,
15
+ * method, args }` (and `watch`, a frame-chosen id, for a subscription), each turned into the host
16
+ * function that serves it and passed through the bridge, which alone decides; `porthole/unwatch`
17
+ * ends a watch. A watch's updates go to the frame as `porthole/event` with `{ watch, data }`.
18
+ */
19
+
20
+ const isRecord = (value: unknown): value is Record<string, unknown> =>
21
+ value !== null && typeof value === "object" && !Array.isArray(value);
22
+
23
+ /** A runtime call as the host function that serves it gets it, or null for none. */
24
+ export function runtimeCall(
25
+ capability: unknown,
26
+ method: unknown,
27
+ args: unknown,
28
+ ): { readonly serves: CapabilityName; readonly args: unknown; readonly watch: boolean } | null {
29
+ if (!isRuntimeCapabilityName(capability) || typeof method !== "string") {
30
+ return null;
31
+ }
32
+ const methods: Readonly<Record<string, RuntimeMethod>> = RUNTIME_CAPABILITIES[capability].methods;
33
+ const spec = Object.hasOwn(methods, method) ? methods[method] : undefined;
34
+ // `data.subscribe` is MCP's own subscription (resources/subscribe, P079), not a runtime call.
35
+ if (spec === undefined || spec.serves === "subscribeData") {
36
+ return null;
37
+ }
38
+ const given = isRecord(args) ? args : {};
39
+ const watch = spec.watch === true;
40
+ switch (spec.serves) {
41
+ case "downloadFile":
42
+ return {
43
+ serves: spec.serves,
44
+ args: { contents: downloadContents(given.file) ?? undefined },
45
+ watch,
46
+ };
47
+ case "callTool":
48
+ return { serves: spec.serves, args: { name: given.name, arguments: given.arguments }, watch };
49
+ case "readData":
50
+ return { serves: spec.serves, args: { uri: given.uri }, watch };
51
+ case "artifact":
52
+ case "assets":
53
+ case "db":
54
+ // One host function serves several methods: the method is its `op`.
55
+ return { serves: spec.serves, args: { ...given, op: method }, watch };
56
+ default:
57
+ return { serves: spec.serves, args: given, watch };
58
+ }
59
+ }
60
+
61
+ type Answer =
62
+ | { readonly result: unknown }
63
+ | { readonly error: { code: number; message: string; data?: RefusalReason } };
64
+
65
+ /** A runtime call's outcome, as the frame hears it: its value, or why it was refused (P080). */
66
+ export function runtimeAnswer(serves: CapabilityName, outcome: CallOutcome<unknown>): Answer {
67
+ if (!outcome.ok) {
68
+ return {
69
+ error: {
70
+ code: -32000,
71
+ message: `Refused (${outcome.refusal})`,
72
+ data: reasonFor(serves, outcome),
73
+ },
74
+ };
75
+ }
76
+ return { result: { value: outcome.value ?? null } };
77
+ }
78
+
79
+ const refused = (reason: RefusalReason): Answer => ({
80
+ error: { code: -32000, message: `Refused (${reason.code})`, data: reason },
81
+ });
82
+
83
+ /** One frame's runtime calls: its watches, and their end. */
84
+ export function runtimeCalls(
85
+ bridge: HostFunctionBridge,
86
+ notify: (method: string, params: Record<string, unknown>) => void,
87
+ ) {
88
+ const watches = new Map<string, AbortController>();
89
+ return {
90
+ async call(params: Record<string, unknown>): Promise<Answer> {
91
+ const mapped = runtimeCall(params.capability, params.method, params.args);
92
+ if (mapped === null) {
93
+ return refused({ code: "not_allowed", message: "This isn't available here." });
94
+ }
95
+ if (!mapped.watch) {
96
+ return runtimeAnswer(mapped.serves, await bridge.call(mapped.serves, mapped.args));
97
+ }
98
+ const id = params.watch;
99
+ if (typeof id !== "string" || !/^[\w-]{1,64}$/u.test(id) || watches.has(id)) {
100
+ return refused({ code: "not_allowed", message: "The app can't take this request." });
101
+ }
102
+ if (watches.size >= DB_LIMITS.maxWatches) {
103
+ return refused({ code: "too_large", message: "Too many things followed at once." });
104
+ }
105
+ const controller = new AbortController();
106
+ watches.set(id, controller);
107
+ const outcome = await bridge.call(mapped.serves, mapped.args, {
108
+ subscription: {
109
+ // Each update is the watch's answer, gated as its read when it started (P091, P094):
110
+ // nothing that check read changes while it lives (the frame's viewer and declaration,
111
+ // the display's kept consent), and a new page or frame ends it. So no gate per update.
112
+ changed: (data?: unknown) => {
113
+ if (!controller.signal.aborted) {
114
+ notify(RUNTIME_EVENT_METHOD, { watch: id, data: data ?? null });
115
+ }
116
+ },
117
+ signal: controller.signal,
118
+ },
119
+ });
120
+ if (!outcome.ok) {
121
+ controller.abort();
122
+ watches.delete(id);
123
+ }
124
+ return outcome.ok ? { result: { value: null } } : runtimeAnswer(mapped.serves, outcome);
125
+ },
126
+ /** The frame stopped following (never gated). */
127
+ unwatch(params: Record<string, unknown>): void {
128
+ const id = params.watch;
129
+ if (typeof id === "string") {
130
+ watches.get(id)?.abort();
131
+ watches.delete(id);
132
+ }
133
+ },
134
+ close(): void {
135
+ for (const controller of watches.values()) {
136
+ controller.abort();
137
+ }
138
+ watches.clear();
139
+ },
140
+ };
141
+ }
@@ -1,4 +1,5 @@
1
1
  import type { CapabilityName } from "../config/capabilities.ts";
2
+ import type { PortholeConfig } from "../config/schema.ts";
2
3
  import type { CallOutcome } from "../bridge/types.ts";
3
4
  import type { AdapterSession, ProtocolAdapter, ShellConnection } from "./adapter.ts";
4
5
  import {
@@ -15,9 +16,17 @@ import {
15
16
  NAVIGATION_BLOCKED_METHOD,
16
17
  MCP_APPS_METHODS as M,
17
18
  MCP_APPS_PROTOCOL_VERSION,
19
+ MODEL_CONTEXT_OFFERED,
18
20
  type HostContext,
19
21
  } from "./mcp-apps.ts";
20
22
  import { liveData } from "./live-data.ts";
23
+ import { messageText } from "./message-text.ts";
24
+ import { runtimeCalls } from "./runtime-calls.ts";
25
+ import {
26
+ RUNTIME_CALL_METHOD,
27
+ RUNTIME_EXPERIMENTAL_KEY,
28
+ RUNTIME_UNWATCH_METHOD,
29
+ } from "../runtime/contract.ts";
21
30
 
22
31
  /**
23
32
  * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
@@ -28,25 +37,24 @@ import { liveData } from "./live-data.ts";
28
37
 
29
38
  const LOG_ERRORS = new Set(["error", "critical", "alert", "emergency"]);
30
39
 
31
- /** Requests that are capability calls, and how their params become the capability's args. */
40
+ /**
41
+ * Requests that are capability calls, and how their params become the capability's args: shallow,
42
+ * or bounded (`messageText`), since they run before any gate (S05's class, P095).
43
+ */
32
44
  const REQUESTS: Readonly<
33
- Record<string, { capability: CapabilityName; args: (params: Record<string, unknown>) => unknown }>
45
+ Record<
46
+ string,
47
+ {
48
+ capability: CapabilityName;
49
+ args: (params: Record<string, unknown>, config: PortholeConfig) => unknown;
50
+ }
51
+ >
34
52
  > = {
35
53
  [M.message]: {
36
54
  capability: "sendPrompt",
37
- args: (params) => ({
55
+ args: (params, config) => ({
38
56
  text: Array.isArray(params.content)
39
- ? params.content
40
- .map((part: unknown) => {
41
- const block = part as { type?: unknown; text?: unknown } | null;
42
- return block !== null &&
43
- typeof block === "object" &&
44
- block.type === "text" &&
45
- typeof block.text === "string"
46
- ? block.text
47
- : "";
48
- })
49
- .join("")
57
+ ? (messageText(params.content, "", config.limits.maxPromptChars) ?? "")
50
58
  : undefined,
51
59
  }),
52
60
  },
@@ -116,7 +124,7 @@ export function hostCapabilities(
116
124
  offered.serverResources = declared("subscribeData") ? { subscribe: true } : {};
117
125
  }
118
126
  if (declared("setModelContext")) {
119
- offered.updateModelContext = { text: {} };
127
+ offered.updateModelContext = MODEL_CONTEXT_OFFERED;
120
128
  }
121
129
  if (declared("reportError")) {
122
130
  offered.logging = {};
@@ -143,7 +151,20 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
143
151
  transport.send({ jsonrpc: "2.0", method, params });
144
152
 
145
153
  // Live data (P079): reads, subscriptions and the host's updates, through the bridge.
146
- const live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
154
+ let live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
155
+ // The capability runtime (P085), where the config has one: its calls and watches.
156
+ const runtime = session.compiled.config.runtime;
157
+ let calls = runtimeCalls(bridge, notify);
158
+ // A new page on the same transport (another of the set's pages, P084; or a reload that says
159
+ // hello again) starts with nothing followed: the last page's watches and subscriptions end,
160
+ // so it never hears their updates or their refusals (after the review).
161
+ let greeted = false;
162
+ const forget = () => {
163
+ calls.close();
164
+ calls = runtimeCalls(bridge, notify);
165
+ live.close();
166
+ live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
167
+ };
147
168
 
148
169
  const flush = () => {
149
170
  if (!initialized || closed || content === null || sentWhole) {
@@ -163,11 +184,28 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
163
184
  const onRequest = async (request: JsonRpcRequest) => {
164
185
  const params = request.params ?? {};
165
186
  if (request.method === M.initialize) {
187
+ if (greeted) {
188
+ forget();
189
+ }
190
+ greeted = true;
166
191
  respond(request.id, {
167
192
  result: {
168
193
  protocolVersion: MCP_APPS_PROTOCOL_VERSION,
169
194
  hostInfo: session.hostInfo,
170
- hostCapabilities: hostCapabilities((name) => bridge.declared(name)),
195
+ hostCapabilities: {
196
+ ...hostCapabilities((name) => bridge.declared(name)),
197
+ // What this display's page may `use`, in MCP Apps' extension point (P085).
198
+ ...(runtime === undefined
199
+ ? {}
200
+ : {
201
+ experimental: {
202
+ [RUNTIME_EXPERIMENTAL_KEY]: {
203
+ version: runtime,
204
+ capabilities: bridge.roster(),
205
+ },
206
+ },
207
+ }),
208
+ },
171
209
  hostContext: session.hostContext(),
172
210
  },
173
211
  });
@@ -209,7 +247,15 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
209
247
  }
210
248
  return;
211
249
  }
212
- const mapped = REQUESTS[request.method];
250
+ if (request.method === RUNTIME_CALL_METHOD && runtime !== undefined) {
251
+ const answered = await calls.call(params);
252
+ if (!closed) {
253
+ respond(request.id, answered);
254
+ }
255
+ return;
256
+ }
257
+ // Its own entries only: `constructor` or `toString` is no request (S05's class, P095).
258
+ const mapped = Object.hasOwn(REQUESTS, request.method) ? REQUESTS[request.method] : undefined;
213
259
  if (mapped === undefined) {
214
260
  respond(request.id, {
215
261
  error: {
@@ -219,7 +265,10 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
219
265
  });
220
266
  return;
221
267
  }
222
- const outcome = await bridge.call(mapped.capability, mapped.args(params));
268
+ const outcome = await bridge.call(
269
+ mapped.capability,
270
+ mapped.args(params, session.compiled.config),
271
+ );
223
272
  if (!closed) {
224
273
  respond(request.id, answer(mapped.capability, outcome));
225
274
  }
@@ -238,20 +287,23 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
238
287
  void bridge.call("resize", { height: params.height, width: params.width });
239
288
  return;
240
289
  case M.log:
241
- if (LOG_ERRORS.has(String(params.level))) {
242
- const data = params.data;
243
- void bridge.call("reportError", {
244
- message:
245
- typeof data === "string" ? data : JSON.stringify(data ?? null).slice(0, 2_000),
246
- });
290
+ // What content said, as it came (S05, P095): the bridge reads it only within
291
+ // reportError's declaration and rate, into bounded text, and nothing in it throws here.
292
+ if (typeof params.level === "string" && LOG_ERRORS.has(params.level)) {
293
+ void bridge.call("reportError", { message: params.data });
247
294
  }
248
295
  return;
249
296
  case NAVIGATION_BLOCKED_METHOD:
250
297
  // The shell stopped a navigation (P080): an error report, with its address.
251
298
  void bridge.call("reportError", { navigationBlocked: params.url });
252
299
  return;
300
+ case RUNTIME_UNWATCH_METHOD:
301
+ calls.unwatch(params);
302
+ return;
253
303
  case NAVIGATING_METHOD:
254
- // Another page of the set opens in the frame (P084): its next load is that page.
304
+ // Another page of the set opens in the frame (P084): its next load is that page, which
305
+ // follows nothing yet.
306
+ forget();
255
307
  session.emit({ type: "navigating" });
256
308
  return;
257
309
  case M.requestTeardown:
@@ -314,6 +366,7 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
314
366
  stop();
315
367
  pending.clear();
316
368
  live.close();
369
+ calls.close();
317
370
  },
318
371
  };
319
372
  },