@botiverse/porthole 0.7.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 (153) hide show
  1. package/README.md +9 -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 +25 -5
  6. package/dist/bridge/bridge.js +311 -73
  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.js +1 -0
  12. package/dist/bridge/types.d.ts +32 -1
  13. package/dist/check/page-source.js +1 -1
  14. package/dist/check/page.js +2 -0
  15. package/dist/compile/compile.d.ts +6 -0
  16. package/dist/compile/compile.js +3 -1
  17. package/dist/compile/policy.d.ts +38 -2
  18. package/dist/compile/policy.js +122 -7
  19. package/dist/config/capabilities.d.ts +23 -4
  20. package/dist/config/capabilities.js +12 -2
  21. package/dist/config/schema.d.ts +11 -0
  22. package/dist/config/validate.d.ts +8 -2
  23. package/dist/config/validate.js +28 -6
  24. package/dist/config/warnings.d.ts +20 -0
  25. package/dist/config/warnings.js +25 -0
  26. package/dist/conformance/behavior.js +46 -1
  27. package/dist/conformance/cookies.d.ts +15 -0
  28. package/dist/conformance/cookies.js +80 -0
  29. package/dist/conformance/harness/page.d.ts +1 -0
  30. package/dist/conformance/harness/page.js +9 -2
  31. package/dist/conformance/harness-source.js +1 -1
  32. package/dist/conformance/host-kit.js +5 -1
  33. package/dist/conformance/index.d.ts +10 -0
  34. package/dist/conformance/limits.js +38 -1
  35. package/dist/conformance/runtime.js +10 -0
  36. package/dist/conformance/served.d.ts +2 -0
  37. package/dist/conformance/served.js +737 -4
  38. package/dist/files/paths.js +4 -0
  39. package/dist/guide/gates.d.ts +7 -1
  40. package/dist/guide/gates.js +12 -0
  41. package/dist/guide/guide.js +2 -2
  42. package/dist/guide/runtime.js +11 -3
  43. package/dist/host/create-host.js +49 -37
  44. package/dist/host/pages-of-set.d.ts +43 -0
  45. package/dist/host/pages-of-set.js +196 -0
  46. package/dist/host/types.d.ts +8 -1
  47. package/dist/index.d.ts +5 -4
  48. package/dist/index.js +3 -2
  49. package/dist/mcp/adapter.js +11 -15
  50. package/dist/node/index.d.ts +36 -4
  51. package/dist/node/index.js +402 -101
  52. package/dist/presets/presets.d.ts +16 -8
  53. package/dist/presets/presets.js +39 -8
  54. package/dist/protocol/live-data.d.ts +6 -2
  55. package/dist/protocol/live-data.js +20 -1
  56. package/dist/protocol/mcp-apps.d.ts +13 -2
  57. package/dist/protocol/mcp-apps.js +10 -2
  58. package/dist/protocol/message-text.d.ts +8 -0
  59. package/dist/protocol/message-text.js +29 -0
  60. package/dist/protocol/runtime-calls.js +3 -0
  61. package/dist/protocol/shell-adapter.js +16 -22
  62. package/dist/react/context-notice.d.ts +32 -0
  63. package/dist/react/context-notice.js +28 -0
  64. package/dist/react/dialog.js +62 -18
  65. package/dist/react/frame.d.ts +12 -1
  66. package/dist/react/frame.js +79 -2
  67. package/dist/react/index.d.ts +2 -1
  68. package/dist/react/index.js +2 -1
  69. package/dist/runtime/contract.d.ts +9 -1
  70. package/dist/runtime/contract.js +31 -2
  71. package/dist/runtime/db.d.ts +41 -6
  72. package/dist/runtime/db.js +120 -16
  73. package/dist/runtime/declaration.d.ts +15 -1
  74. package/dist/runtime/declaration.js +184 -87
  75. package/dist/runtime/requests.js +27 -11
  76. package/dist/runtime/types.generated.js +1 -1
  77. package/dist/server/files.d.ts +5 -0
  78. package/dist/server/files.js +22 -7
  79. package/dist/server/host.d.ts +18 -1
  80. package/dist/server/host.js +132 -2
  81. package/dist/server/index.d.ts +1 -1
  82. package/dist/server/index.js +1 -1
  83. package/dist/server/peer.d.ts +4 -0
  84. package/dist/server/peer.js +19 -0
  85. package/dist/server/proxy.d.ts +6 -0
  86. package/dist/server/proxy.js +12 -3
  87. package/dist/server/server.js +113 -26
  88. package/dist/server/types.d.ts +6 -3
  89. package/dist/shell/document.d.ts +8 -0
  90. package/dist/shell/document.js +3 -0
  91. package/dist/shell/runtime.js +361 -14
  92. package/docs/ADOPTING.md +119 -14
  93. package/docs/ARCHITECTURE.md +13 -3
  94. package/docs/DECISIONS.md +1455 -8
  95. package/docs/DESIGN.md +79 -25
  96. package/docs/THREAT_MODEL.md +616 -0
  97. package/package.json +14 -3
  98. package/src/bridge/bounded-text.ts +240 -0
  99. package/src/bridge/bridge.ts +373 -84
  100. package/src/bridge/json-data.ts +95 -0
  101. package/src/bridge/navigation.ts +10 -0
  102. package/src/bridge/refusal.ts +1 -0
  103. package/src/bridge/types.ts +30 -1
  104. package/src/check/page.ts +2 -0
  105. package/src/compile/compile.ts +9 -1
  106. package/src/compile/policy.ts +130 -7
  107. package/src/config/capabilities.ts +22 -3
  108. package/src/config/schema.ts +11 -0
  109. package/src/config/validate.ts +43 -5
  110. package/src/config/warnings.ts +42 -0
  111. package/src/conformance/behavior.ts +54 -1
  112. package/src/conformance/cookies.ts +93 -0
  113. package/src/conformance/harness/page.ts +11 -2
  114. package/src/conformance/host-kit.ts +10 -1
  115. package/src/conformance/index.ts +10 -0
  116. package/src/conformance/limits.ts +39 -1
  117. package/src/conformance/runtime.ts +21 -0
  118. package/src/conformance/served.ts +888 -4
  119. package/src/files/paths.ts +4 -0
  120. package/src/guide/gates.ts +13 -1
  121. package/src/guide/guide.ts +3 -3
  122. package/src/guide/runtime.ts +12 -3
  123. package/src/host/create-host.ts +54 -36
  124. package/src/host/pages-of-set.ts +226 -0
  125. package/src/host/types.ts +15 -1
  126. package/src/index.ts +5 -0
  127. package/src/mcp/adapter.ts +16 -20
  128. package/src/node/index.ts +507 -116
  129. package/src/presets/presets.ts +60 -17
  130. package/src/protocol/live-data.ts +31 -3
  131. package/src/protocol/mcp-apps.ts +11 -2
  132. package/src/protocol/message-text.ts +36 -0
  133. package/src/protocol/runtime-calls.ts +3 -0
  134. package/src/protocol/shell-adapter.ts +27 -23
  135. package/src/react/context-notice.tsx +95 -0
  136. package/src/react/dialog.tsx +77 -17
  137. package/src/react/frame.tsx +101 -0
  138. package/src/react/index.ts +8 -1
  139. package/src/runtime/contract.ts +36 -2
  140. package/src/runtime/db.ts +140 -20
  141. package/src/runtime/declaration.ts +227 -89
  142. package/src/runtime/requests.ts +27 -11
  143. package/src/runtime/types.generated.ts +1 -1
  144. package/src/server/files.ts +29 -11
  145. package/src/server/host.ts +158 -3
  146. package/src/server/index.ts +1 -0
  147. package/src/server/peer.ts +21 -0
  148. package/src/server/proxy.ts +13 -3
  149. package/src/server/server.ts +139 -36
  150. package/src/server/types.ts +6 -3
  151. package/src/shell/document.ts +8 -0
  152. package/src/shell/runtime.ts +361 -14
  153. package/types/runtime/v1/context.d.ts +13 -2
@@ -74,6 +74,26 @@ const mergeEgress = (base, extra) => {
74
74
  }
75
75
  return merged;
76
76
  };
77
+ /**
78
+ * A frozen copy of a config's data, all the way down (P103): what a host passed in stays its own
79
+ * and mutable; the copy can't be written into (a capability's `connect`, an egress origin).
80
+ */
81
+ function frozenCopy(value) {
82
+ if (Array.isArray(value)) {
83
+ return Object.freeze(value.map((each) => frozenCopy(each)));
84
+ }
85
+ if (value !== null && typeof value === "object") {
86
+ const prototype = Object.getPrototypeOf(value);
87
+ if (prototype === Object.prototype || prototype === null) {
88
+ const copy = {};
89
+ for (const [key, each] of Object.entries(value)) {
90
+ copy[key] = frozenCopy(each);
91
+ }
92
+ return Object.freeze(copy);
93
+ }
94
+ }
95
+ return value;
96
+ }
77
97
  /** The default variables, with the host's changes and additions, less those it dropped (null). */
78
98
  function themeVariables(changes) {
79
99
  const variables = { ...DEFAULT_THEME_VARIABLES };
@@ -131,24 +151,35 @@ export const presets = {
131
151
  inlineWidget: (options = {}) => build("inline", {}, options),
132
152
  /**
133
153
  * A widget that shows its host's data, live, and has no network of its own (P079): an inline
134
- * widget whose egress stays closed (no option opens it). It reads the host's data (`readData`,
135
- * MCP `resources/read`) and subscribes to it (`subscribeData`, `resources/subscribe`), each
136
- * behind the viewer's consent (the host's `consent`, asked once per display) and a rate. In
137
- * domain isolation its scripts load from Porthole's own libraries on its origin
138
- * (`egress.libraries`: Chart.js, D3), and nowhere else. A host adds what any widget may have (a
139
- * link, a copy button), or changes the data capabilities' gates.
154
+ * widget whose egress stays closed (no option opens it: neither `egress` nor a capability's own
155
+ * `connect` or `resource`, P103). It reads the host's data (`readData`, MCP `resources/read`)
156
+ * and subscribes to it (`subscribeData`, `resources/subscribe`), each behind the viewer's
157
+ * consent (the host's `consent`, asked once per display) and a rate. In domain isolation its
158
+ * scripts load from Porthole's own libraries on its origin (`egress.libraries`: Chart.js, D3),
159
+ * and nowhere else. A host adds what any widget may have (a link, a copy button), or changes the
160
+ * data capabilities' gates.
140
161
  */
141
162
  liveWidget: (options = {}) => {
142
163
  if (options.egress !== undefined) {
143
164
  throw new ConfigError("options.egress", "a live widget has no network of its own: its egress stays closed (P079)");
144
165
  }
145
- return build("inline", {
166
+ // A capability's own origins join the CSP as egress does (P103): none for a live widget.
167
+ for (const [name, value] of Object.entries(options.capabilities ?? {})) {
168
+ for (const field of ["connect", "resource"]) {
169
+ if (typeof value === "object" && value !== null && value[field] !== undefined) {
170
+ throw new ConfigError(`options.capabilities.${name}.${field}`, "a live widget has no network of its own: no capability opens origins for it (P079, P103)");
171
+ }
172
+ }
173
+ }
174
+ // Frozen, all the way down (P103): nothing writes an origin into the preset's config after it
175
+ // is made. A config a host builds from it (a spread) is the host's own, not this preset.
176
+ return frozenCopy(build("inline", {
146
177
  capabilities: {
147
178
  readData: { gates: ["consent", { rateLimit: { perMinute: 120 } }] },
148
179
  subscribeData: { gates: ["consent", { rateLimit: { perMinute: 60 } }] },
149
180
  },
150
181
  egress: options.isolation === "domain" ? { libraries: true } : {},
151
- }, options);
182
+ }, options));
152
183
  },
153
184
  /**
154
185
  * A whole HTML page: written into an opaque frame by the shell where the host has the page, or
@@ -4,10 +4,14 @@ import type { CallOutcome, HostFunctionBridge } from "../bridge/types.ts";
4
4
  * `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`): the frame's
5
5
  * subscriptions by URI, each ended by its controller, and a fresh result the host gave for one
6
6
  * (pushed through `changed(result)`, or read after a stale answer), kept for the frame's next read
7
- * of it. Every call goes through the bridge, which gates it; the adapter only says what to send.
7
+ * of it. Every call goes through the bridge, which gates it, a read answered by a kept result too
8
+ * (P094); the adapter only says what to send.
8
9
  */
9
10
  export interface LiveData {
10
- /** A read: a fresh result kept for it, else the host's (its cache first, when subscribed). */
11
+ /**
12
+ * A read, past the read's gates whatever answers it: a fresh result kept for it, else the
13
+ * host's (its cache first, when subscribed).
14
+ */
11
15
  read(uri: unknown): Promise<CallOutcome<unknown>>;
12
16
  /** Starts the host's subscription; a second for a URI is a no-op. */
13
17
  subscribe(uri: unknown): Promise<CallOutcome<undefined>>;
@@ -1,4 +1,9 @@
1
1
  import { STALE_META } from "./mcp-apps.js";
2
+ /**
3
+ * The most resources one frame follows at once (P095), as the runtime's watches (50): past it a
4
+ * subscription is refused as too large, and the host isn't asked.
5
+ */
6
+ const MAX_SUBSCRIPTIONS = 50;
2
7
  /** Where MCP results carry their metadata. */
3
8
  const META = "_meta";
4
9
  /** A `resources/read` result marked as the host's cached copy (`STALE_META`). */
@@ -33,9 +38,16 @@ export function liveData(bridge, updated, options = {}) {
33
38
  return {
34
39
  async read(uri) {
35
40
  if (typeof uri === "string" && fresh.has(uri)) {
41
+ // A kept result is the host's answer to a read: it goes through the read's gates as any
42
+ // read does (level, names, rate, gesture, consent, confirm), with no new upstream call
43
+ // (P094). Used once; kept again if the gates refused it and nothing newer came.
36
44
  const value = fresh.get(uri);
37
45
  fresh.delete(uri);
38
- return { ok: true, value };
46
+ const outcome = await bridge.call("readData", { uri }, { ...activation(), held: { uri, value } });
47
+ if (!outcome.ok && !closed && subscriptions.has(uri) && !fresh.has(uri)) {
48
+ fresh.set(uri, value);
49
+ }
50
+ return outcome;
39
51
  }
40
52
  const subscribed = typeof uri === "string" && subscriptions.has(uri);
41
53
  const outcome = await bridge.call("readData", { uri }, { ...activation(), stale: subscribed });
@@ -56,6 +68,13 @@ export function liveData(bridge, updated, options = {}) {
56
68
  if (typeof uri === "string" && subscriptions.has(uri)) {
57
69
  return { ok: true, value: undefined };
58
70
  }
71
+ if (subscriptions.size >= MAX_SUBSCRIPTIONS) {
72
+ return {
73
+ ok: false,
74
+ refusal: "too-large",
75
+ reason: { code: "too_large", message: "Too many things followed at once." },
76
+ };
77
+ }
59
78
  const controller = new AbortController();
60
79
  if (typeof uri === "string") {
61
80
  subscriptions.set(uri, controller);
@@ -31,6 +31,15 @@ export declare const MCP_APPS_METHODS: {
31
31
  readonly sandboxResourceReady: "ui/notifications/sandbox-resource-ready";
32
32
  };
33
33
  export type McpAppsMethod = (typeof MCP_APPS_METHODS)[keyof typeof MCP_APPS_METHODS];
34
+ /**
35
+ * What a host that declares `setModelContext` says it takes (`hostCapabilities.updateModelContext`),
36
+ * in both adapters: text blocks and structured content, exactly what the bridge accepts and the
37
+ * person is shown (P100). Images and other blocks aren't offered, and are refused.
38
+ */
39
+ export declare const MODEL_CONTEXT_OFFERED: {
40
+ readonly text: {};
41
+ readonly structuredContent: {};
42
+ };
34
43
  /**
35
44
  * What the shell's `tool-input(-partial)` carries: the content to draw. Porthole's own argument
36
45
  * names, since the shell is the only view that reads them.
@@ -69,8 +78,10 @@ export declare const STALE_META = "porthole/stale";
69
78
  export declare const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
70
79
  /**
71
80
  * Porthole's own notification from the shell (P084): a page that came with files is opening
72
- * another page of its set, `{ url }`, in the frame. The host takes the frame's next load for that
73
- * page rather than for content that left (P031). The content's word: it only spares a restart.
81
+ * another page of its set, `{ url }`, in the frame; and, as it arrives, the page a navigation
82
+ * opened says so, `{ url, arrived: true }` (P098). The host takes the frame's next load (or the
83
+ * load it came after, within `LATE_NOTICE_MS`) for that page rather than for content that left
84
+ * (P031). The content's word: it only spares a restart.
74
85
  */
75
86
  export declare const NAVIGATING_METHOD = "porthole/navigating";
76
87
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
@@ -37,6 +37,12 @@ export const MCP_APPS_METHODS = {
37
37
  sandboxProxyReady: "ui/notifications/sandbox-proxy-ready",
38
38
  sandboxResourceReady: "ui/notifications/sandbox-resource-ready",
39
39
  };
40
+ /**
41
+ * What a host that declares `setModelContext` says it takes (`hostCapabilities.updateModelContext`),
42
+ * in both adapters: text blocks and structured content, exactly what the bridge accepts and the
43
+ * person is shown (P100). Images and other blocks aren't offered, and are refused.
44
+ */
45
+ export const MODEL_CONTEXT_OFFERED = { text: {}, structuredContent: {} };
40
46
  /**
41
47
  * The style variables MCP Apps defines (`McpUiStyleVariableKey`, 2026-01-26). The official App SDK
42
48
  * refuses a host context whose `styles.variables` holds any other name ("Unrecognized key"), so a
@@ -119,8 +125,10 @@ export const STALE_META = "porthole/stale";
119
125
  export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
120
126
  /**
121
127
  * Porthole's own notification from the shell (P084): a page that came with files is opening
122
- * another page of its set, `{ url }`, in the frame. The host takes the frame's next load for that
123
- * page rather than for content that left (P031). The content's word: it only spares a restart.
128
+ * another page of its set, `{ url }`, in the frame; and, as it arrives, the page a navigation
129
+ * opened says so, `{ url, arrived: true }` (P098). The host takes the frame's next load (or the
130
+ * load it came after, within `LATE_NOTICE_MS`) for that page rather than for content that left
131
+ * (P031). The content's word: it only spares a restart.
124
132
  */
125
133
  export const NAVIGATING_METHOD = "porthole/navigating";
126
134
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
@@ -0,0 +1,8 @@
1
+ /**
2
+ * The text of a `ui/message`'s content blocks, the adapters' one reading of it: its text blocks'
3
+ * text, in order, joined by `separator`; null where there is none, or more blocks than a message
4
+ * holds. Read before any gate, so only as far as `max` characters (S05's class, P095: structured
5
+ * clone delivers a sparse array of any length, or one block shared a million times, for the cost
6
+ * of one): past it, `max + 1` characters, which the bridge refuses as too long.
7
+ */
8
+ export declare function messageText(blocks: readonly unknown[], separator: string, max: number): string | null;
@@ -0,0 +1,29 @@
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
+ * The text of a `ui/message`'s content blocks, the adapters' one reading of it: its text blocks'
5
+ * text, in order, joined by `separator`; null where there is none, or more blocks than a message
6
+ * holds. Read before any gate, so only as far as `max` characters (S05's class, P095: structured
7
+ * clone delivers a sparse array of any length, or one block shared a million times, for the cost
8
+ * of one): past it, `max + 1` characters, which the bridge refuses as too long.
9
+ */
10
+ export function messageText(blocks, separator, max) {
11
+ if (blocks.length > MAX_BLOCKS) {
12
+ return null;
13
+ }
14
+ let text = null;
15
+ for (let index = 0; index < blocks.length; index += 1) {
16
+ const block = blocks[index];
17
+ if (block !== null &&
18
+ typeof block === "object" &&
19
+ !Array.isArray(block) &&
20
+ block.type === "text" &&
21
+ typeof block.text === "string") {
22
+ text = text === null ? block.text : `${text}${separator}${block.text}`;
23
+ if (text.length > max) {
24
+ return text.slice(0, max + 1);
25
+ }
26
+ }
27
+ }
28
+ return text;
29
+ }
@@ -81,6 +81,9 @@ export function runtimeCalls(bridge, notify) {
81
81
  watches.set(id, controller);
82
82
  const outcome = await bridge.call(mapped.serves, mapped.args, {
83
83
  subscription: {
84
+ // Each update is the watch's answer, gated as its read when it started (P091, P094):
85
+ // nothing that check read changes while it lives (the frame's viewer and declaration,
86
+ // the display's kept consent), and a new page or frame ends it. So no gate per update.
84
87
  changed: (data) => {
85
88
  if (!controller.signal.aborted) {
86
89
  notify(RUNTIME_EVENT_METHOD, { watch: id, data: data ?? null });
@@ -1,7 +1,8 @@
1
1
  import { JSON_RPC_ERRORS, parseJsonRpc, } from "./jsonrpc.js";
2
2
  import { reasonFor } from "../bridge/refusal.js";
3
- import { COPY_TEXT_METHOD, NAVIGATING_METHOD, NAVIGATION_BLOCKED_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, } from "./mcp-apps.js";
3
+ import { COPY_TEXT_METHOD, NAVIGATING_METHOD, NAVIGATION_BLOCKED_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, MODEL_CONTEXT_OFFERED, } from "./mcp-apps.js";
4
4
  import { liveData } from "./live-data.js";
5
+ import { messageText } from "./message-text.js";
5
6
  import { runtimeCalls } from "./runtime-calls.js";
6
7
  import { RUNTIME_CALL_METHOD, RUNTIME_EXPERIMENTAL_KEY, RUNTIME_UNWATCH_METHOD, } from "../runtime/contract.js";
7
8
  /**
@@ -11,23 +12,16 @@ import { RUNTIME_CALL_METHOD, RUNTIME_EXPERIMENTAL_KEY, RUNTIME_UNWATCH_METHOD,
11
12
  * after the view has initialized.
12
13
  */
13
14
  const LOG_ERRORS = new Set(["error", "critical", "alert", "emergency"]);
14
- /** Requests that are capability calls, and how their params become the capability's args. */
15
+ /**
16
+ * Requests that are capability calls, and how their params become the capability's args: shallow,
17
+ * or bounded (`messageText`), since they run before any gate (S05's class, P095).
18
+ */
15
19
  const REQUESTS = {
16
20
  [M.message]: {
17
21
  capability: "sendPrompt",
18
- args: (params) => ({
22
+ args: (params, config) => ({
19
23
  text: Array.isArray(params.content)
20
- ? params.content
21
- .map((part) => {
22
- const block = part;
23
- return block !== null &&
24
- typeof block === "object" &&
25
- block.type === "text" &&
26
- typeof block.text === "string"
27
- ? block.text
28
- : "";
29
- })
30
- .join("")
24
+ ? (messageText(params.content, "", config.limits.maxPromptChars) ?? "")
31
25
  : undefined,
32
26
  }),
33
27
  },
@@ -89,7 +83,7 @@ export function hostCapabilities(declared) {
89
83
  offered.serverResources = declared("subscribeData") ? { subscribe: true } : {};
90
84
  }
91
85
  if (declared("setModelContext")) {
92
- offered.updateModelContext = { text: {} };
86
+ offered.updateModelContext = MODEL_CONTEXT_OFFERED;
93
87
  }
94
88
  if (declared("reportError")) {
95
89
  offered.logging = {};
@@ -212,7 +206,8 @@ export const shellAdapter = {
212
206
  }
213
207
  return;
214
208
  }
215
- const mapped = REQUESTS[request.method];
209
+ // Its own entries only: `constructor` or `toString` is no request (S05's class, P095).
210
+ const mapped = Object.hasOwn(REQUESTS, request.method) ? REQUESTS[request.method] : undefined;
216
211
  if (mapped === undefined) {
217
212
  respond(request.id, {
218
213
  error: {
@@ -222,7 +217,7 @@ export const shellAdapter = {
222
217
  });
223
218
  return;
224
219
  }
225
- const outcome = await bridge.call(mapped.capability, mapped.args(params));
220
+ const outcome = await bridge.call(mapped.capability, mapped.args(params, session.compiled.config));
226
221
  if (!closed) {
227
222
  respond(request.id, answer(mapped.capability, outcome));
228
223
  }
@@ -240,11 +235,10 @@ export const shellAdapter = {
240
235
  void bridge.call("resize", { height: params.height, width: params.width });
241
236
  return;
242
237
  case M.log:
243
- if (LOG_ERRORS.has(String(params.level))) {
244
- const data = params.data;
245
- void bridge.call("reportError", {
246
- message: typeof data === "string" ? data : JSON.stringify(data ?? null).slice(0, 2_000),
247
- });
238
+ // What content said, as it came (S05, P095): the bridge reads it only within
239
+ // reportError's declaration and rate, into bounded text, and nothing in it throws here.
240
+ if (typeof params.level === "string" && LOG_ERRORS.has(params.level)) {
241
+ void bridge.call("reportError", { message: params.data });
248
242
  }
249
243
  return;
250
244
  case NAVIGATION_BLOCKED_METHOD:
@@ -0,0 +1,32 @@
1
+ import type { ReactElement } from "react";
2
+ import type { CapabilityArgs } from "../config/capabilities.ts";
3
+ /**
4
+ * The default model context notice (P100): when content tells the agent something
5
+ * (`setModelContext`, MCP Apps' `ui/update-model-context`), the host's page shows the person all
6
+ * of it, outside every frame, before the host's handler has it: the text the agent reads at its
7
+ * next turn, in the content's words. One per display, the latest (an update replaces the last, as
8
+ * it does for the agent); it stays until the person hides it. Nothing in it is a question: the
9
+ * update has gone. All of it shows (after the review: the text box grows, never hiding a payload
10
+ * below blank lines, and says how many characters and lines it holds); the stack of displays
11
+ * scrolls within the window, so a later display never pushes an earlier one out of reach. A host replaces it by passing its own `show` (a chip by its composer, say); it
12
+ * styles it through the `porthole-context` class and data attributes.
13
+ */
14
+ export interface ContextUpdate {
15
+ /** The display's id and title, as the host named it. */
16
+ readonly displayId: string;
17
+ readonly title: string;
18
+ /** The update, whole: text blocks and structured content, as the bridge took them. */
19
+ readonly update: CapabilityArgs["setModelContext"];
20
+ }
21
+ export interface ContextNoticeProps {
22
+ /** The latest update of each display that sent one, in the order they came. */
23
+ readonly updates: readonly ContextUpdate[];
24
+ /** The person hid one display's notice (the agent still has its update). */
25
+ readonly onHide: (displayId: string) => void;
26
+ readonly className?: string;
27
+ }
28
+ /** How long an update is, in words: "412 characters, 3 lines". */
29
+ export declare function contextSize(text: string): string;
30
+ /** What the person is shown of an update: its text blocks, then its structured content's JSON. */
31
+ export declare function contextText(update: CapabilityArgs["setModelContext"]): string;
32
+ export declare function ContextNotice({ updates, onHide, className }: ContextNoticeProps): ReactElement;
@@ -0,0 +1,28 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ /** How long an update is, in words: "412 characters, 3 lines". */
3
+ export function contextSize(text) {
4
+ const lines = text === "" ? 0 : text.split("\n").length;
5
+ return `${text.length.toLocaleString("en-US")} characters, ${lines.toLocaleString("en-US")} ${lines === 1 ? "line" : "lines"}`;
6
+ }
7
+ /** What the person is shown of an update: its text blocks, then its structured content's JSON. */
8
+ export function contextText(update) {
9
+ const text = (update.content ?? []).map((block) => block.text).join("\n\n");
10
+ const structured = update.structuredContent === undefined ? "" : JSON.stringify(update.structuredContent, null, 2);
11
+ return [text, structured].filter((part) => part !== "").join("\n\n");
12
+ }
13
+ const STYLE = `.porthole-context{position:fixed;right:16px;bottom:24px;z-index:2147483646;display:flex;flex-direction:column;gap:8px;width:min(380px,calc(100vw - 32px));max-height:calc(100vh - 48px);overflow-y:auto;overscroll-behavior:contain;font:inherit;font-size:.9em}
14
+ .porthole-context[hidden]{display:none}
15
+ .porthole-context>section{flex:none;color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent);border-radius:12px;padding:12px 14px;box-shadow:0 8px 28px rgb(0 0 0 / .25)}
16
+ .porthole-context p{margin:0 0 6px}
17
+ .porthole-context [data-porthole-source],.porthole-context [data-porthole-note],.porthole-context [data-porthole-context-size]{opacity:.72}
18
+ .porthole-context>[data-porthole-context-count]{flex:none;margin:0;padding:6px 12px;border-radius:8px;color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent)}
19
+ .porthole-context [data-porthole-context-size]{margin:6px 0 0}
20
+ .porthole-context pre{margin:0;white-space:pre-wrap;overflow-wrap:anywhere;padding:8px 10px;border-radius:8px;background:color-mix(in srgb,CanvasText 7%,transparent);font:12px/1.45 ui-monospace,SFMono-Regular,Menlo,monospace}
21
+ .porthole-context menu{display:flex;justify-content:flex-end;margin:8px 0 0;padding:0}
22
+ .porthole-context button{font:inherit;min-height:32px;padding:0 12px;border-radius:8px;border:1px solid color-mix(in srgb,CanvasText 25%,transparent);background:transparent;color:inherit;cursor:pointer}`;
23
+ export function ContextNotice({ updates, onHide, className }) {
24
+ return (_jsxs("div", { role: "status", "aria-live": "polite", className: className === undefined ? "porthole-context" : `porthole-context ${className}`, "data-porthole-context": "", hidden: updates.length === 0, children: [_jsx("style", { children: STYLE }), updates.length > 1 ? (_jsx("p", { "data-porthole-context-count": "", children: `${updates.length} displays told the agent something: scroll to read them all.` })) : null, updates.map((each) => {
25
+ const text = contextText(each.update);
26
+ return (_jsxs("section", { "data-porthole-context-display": each.displayId, children: [_jsxs("p", { children: [_jsx("strong", { children: "Context for the agent" }), " ", _jsx("span", { "data-porthole-source": "", children: `from “${each.title}”` })] }), _jsx("p", { "data-porthole-note": "", children: "The agent reads this at its next turn. It is the content\u2019s text, not yours." }), _jsx("pre", { "data-porthole-context-text": "", tabIndex: 0, children: text }), _jsx("p", { "data-porthole-context-size": "", children: contextSize(text) }), _jsx("menu", { children: _jsx("button", { type: "button", "data-porthole-hide": "", onClick: () => onHide(each.displayId), children: "Hide" }) })] }, each.displayId));
27
+ })] }));
28
+ }
@@ -1,5 +1,6 @@
1
1
  import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { useEffect, useId, useRef, useState } from "react";
2
+ import { useEffect, useId, useMemo, useRef, useState } from "react";
3
+ import { formatBounded } from "../bridge/bounded-text.js";
3
4
  /**
4
5
  * The default confirmation dialog (P019): drawn by the host's page, outside every frame, as a
5
6
  * modal (the top layer covers the frames, so content can't draw over it or click it). It shows
@@ -11,7 +12,42 @@ import { useEffect, useId, useRef, useState } from "react";
11
12
  */
12
13
  /** How long the accept button ignores presses after the dialog opens. */
13
14
  export const ARM_DELAY_MS = 500;
14
- const json = (value) => JSON.stringify(value, null, 2) ?? "";
15
+ /**
16
+ * What a call carries, as JSON laid out, within bounds (P095): a frame's arguments come
17
+ * structured-cloned, so a cycle, a BigInt, or a graph billions of nodes long as a tree. Past the
18
+ * bounds the dialog says it shows only part.
19
+ */
20
+ const DIALOG_TEXT_LIMITS = { chars: 20_000, nodes: 2_000, depth: 24 };
21
+ function carried(heading, accept, value, before = "") {
22
+ const { text, whole } = formatBounded(value, DIALOG_TEXT_LIMITS, 2);
23
+ return {
24
+ heading,
25
+ accept,
26
+ detail: `${before}${text}`,
27
+ ...(whole ? {} : { note: "Only part of it is shown: it is more than this dialog shows." }),
28
+ };
29
+ }
30
+ /** How many of one kind of write the summary names before it counts the rest. */
31
+ const MOST_PATHS = 10;
32
+ /**
33
+ * A db change in a line (P094): the writes whose own gates asked for the yes, by kind ("Delete
34
+ * n/x, n/y; and 48 other writes."), or every write by kind where none of them asked (the host
35
+ * function's own confirmation); at most `MOST_PATHS` paths a kind, then a count.
36
+ */
37
+ function writesSummary(writes, askedBy) {
38
+ const asked = writes.filter((each) => askedBy.includes(each.op));
39
+ const lead = asked.length === 0 ? writes : asked;
40
+ const kinds = new Map();
41
+ for (const each of lead) {
42
+ kinds.set(each.op, [...(kinds.get(each.op) ?? []), each.path]);
43
+ }
44
+ const said = [...kinds]
45
+ .map(([op, paths]) => `${op} ${paths.slice(0, MOST_PATHS).join(", ")}${paths.length > MOST_PATHS ? ` and ${paths.length - MOST_PATHS} more` : ""}`)
46
+ .join("; ");
47
+ const others = writes.length - lead.length;
48
+ const text = `${said}${others === 0 ? "" : `; and ${others} other write${others === 1 ? "" : "s"}`}.`;
49
+ return text.charAt(0).toUpperCase() + text.slice(1);
50
+ }
15
51
  function words(request) {
16
52
  switch (request.capability) {
17
53
  case "sendPrompt":
@@ -32,19 +68,11 @@ function words(request) {
32
68
  };
33
69
  }
34
70
  case "downloadFile":
35
- return {
36
- heading: "Download this file?",
37
- accept: "Download",
38
- detail: json(request.args.contents),
39
- };
71
+ return carried("Download this file?", "Download", request.args.contents);
40
72
  case "callTool":
41
- return {
42
- heading: "Run this tool?",
43
- accept: "Run",
44
- detail: `${request.args.name}\n${json(request.args.arguments)}`,
45
- };
73
+ return carried("Run this tool?", "Run", request.args.arguments, `${request.args.name}\n`);
46
74
  case "setModelContext":
47
- return { heading: "Share this with the agent?", accept: "Share", detail: json(request.args) };
75
+ return carried("Share this with the agent?", "Share", request.args);
48
76
  case "readData":
49
77
  return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
50
78
  case "subscribeData":
@@ -66,7 +94,7 @@ function words(request) {
66
94
  .join("\n"),
67
95
  note: `From version ${request.args.base}${request.args.label === undefined ? "" : `: ${request.args.label}`}.`,
68
96
  }
69
- : { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
97
+ : carried("Allow this?", "Allow", request.args);
70
98
  case "assets":
71
99
  return request.args.op === "upload"
72
100
  ? {
@@ -81,15 +109,31 @@ function words(request) {
81
109
  accept: "Remove",
82
110
  detail: request.args.id,
83
111
  }
84
- : { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
112
+ : carried("Allow this?", "Allow", request.args);
113
+ // The page's shared data (P088): a change leads with what asked for the yes (P094).
114
+ case "db": {
115
+ const args = request.args;
116
+ const writes = args.op === "batch"
117
+ ? args.writes
118
+ : args.op === "set" || args.op === "update" || args.op === "delete"
119
+ ? [args]
120
+ : null;
121
+ return writes === null
122
+ ? carried("Allow this?", "Allow", args)
123
+ : {
124
+ ...carried("Change this page's shared data?", "Change", args),
125
+ summary: writesSummary(writes, request.askedBy ?? []),
126
+ };
127
+ }
85
128
  default:
86
- return { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
129
+ return carried("Allow this?", "Allow", request.args);
87
130
  }
88
131
  }
89
132
  const STYLE = `.porthole-confirm{color-scheme:light dark;color:CanvasText;background:Canvas;border:1px solid color-mix(in srgb,CanvasText 18%,transparent);border-radius:12px;padding:20px;width:min(440px,calc(100vw - 32px));font:inherit;box-shadow:0 12px 40px rgb(0 0 0 / .28)}
90
133
  .porthole-confirm::backdrop{background:rgb(0 0 0 / .4)}
91
134
  .porthole-confirm h2{font-size:1.05em;margin:0 0 4px}
92
135
  .porthole-confirm [data-porthole-source],.porthole-confirm [data-porthole-note]{opacity:.72;font-size:.9em;margin:0 0 12px}
136
+ .porthole-confirm [data-porthole-summary]{font-weight:600;overflow-wrap:anywhere;max-height:20vh;overflow:auto;margin:0 0 12px}
93
137
  .porthole-confirm [data-porthole-detail]{white-space:pre-wrap;overflow-wrap:anywhere;max-height:40vh;overflow:auto;padding:10px 12px;border-radius:8px;background:color-mix(in srgb,CanvasText 7%,transparent);margin:0 0 12px;font:inherit}
94
138
  .porthole-confirm menu{display:flex;justify-content:flex-end;gap:8px;margin:16px 0 0;padding:0}
95
139
  .porthole-confirm button{font:inherit;min-height:36px;padding:0 14px;border-radius:8px;border:1px solid color-mix(in srgb,CanvasText 25%,transparent);background:transparent;color:inherit;cursor:pointer}
@@ -119,13 +163,13 @@ export function ConfirmDialog({ request, onAnswer, className }) {
119
163
  const timer = setTimeout(() => setArmedFor(request), ARM_DELAY_MS);
120
164
  return () => clearTimeout(timer);
121
165
  }, [request]);
122
- const said = request === null ? null : words(request);
166
+ const said = useMemo(() => (request === null ? null : words(request)), [request]);
123
167
  return (_jsxs("dialog", { ref: dialog, className: className === undefined ? "porthole-confirm" : `porthole-confirm ${className}`, "aria-labelledby": heading, "data-porthole-confirm": request?.capability ?? "", onCancel: (event) => {
124
168
  event.preventDefault();
125
169
  if (request !== null) {
126
170
  onAnswer(false);
127
171
  }
128
- }, children: [_jsx("style", { children: STYLE }), said === null || request === null ? null : (_jsxs(_Fragment, { children: [_jsx("h2", { id: heading, children: said.heading }), _jsx("p", { "data-porthole-source": "", children: `From “${request.display.title}”` }), _jsx("div", { "data-porthole-detail": "", children: said.detail }), said.note === undefined ? null : _jsx("p", { "data-porthole-note": "", children: said.note }), _jsxs("menu", { children: [_jsx("button", { type: "button", ref: cancel, autoFocus: true, "data-porthole-cancel": "", onClick: () => onAnswer(false), children: "Cancel" }), _jsx("button", { type: "button", "data-porthole-accept": "", "data-armed": String(armed), onClick: () => {
172
+ }, children: [_jsx("style", { children: STYLE }), said === null || request === null ? null : (_jsxs(_Fragment, { children: [_jsx("h2", { id: heading, children: said.heading }), _jsx("p", { "data-porthole-source": "", children: `From “${request.display.title}”` }), said.summary === undefined ? null : _jsx("p", { "data-porthole-summary": "", children: said.summary }), _jsx("div", { "data-porthole-detail": "", children: said.detail }), said.note === undefined ? null : _jsx("p", { "data-porthole-note": "", children: said.note }), _jsxs("menu", { children: [_jsx("button", { type: "button", ref: cancel, autoFocus: true, "data-porthole-cancel": "", onClick: () => onAnswer(false), children: "Cancel" }), _jsx("button", { type: "button", "data-porthole-accept": "", "data-armed": String(armed), onClick: () => {
129
173
  if (armed) {
130
174
  onAnswer(true);
131
175
  }
@@ -2,7 +2,7 @@ import type { PageDeclaration } from "../runtime/declaration.ts";
2
2
  import type { ViewerInfo } from "../runtime/levels.ts";
3
3
  import { type CSSProperties, type ReactElement, type ReactNode } from "react";
4
4
  import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
5
- import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal } from "../bridge/types.ts";
5
+ import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal, Show } from "../bridge/types.ts";
6
6
  import { Refused, type RefusalReason } from "../bridge/refusal.ts";
7
7
  import type { CapabilityName } from "../config/capabilities.ts";
8
8
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
@@ -40,6 +40,8 @@ interface PageState {
40
40
  readonly locate?: InstanceLocator["locate"];
41
41
  /** The default `copyText`: copies on the host's page and shows the toast (P052). */
42
42
  readonly copyText?: CapabilityHandler<"copyText">;
43
+ /** Who shows the person `show`-gated calls: the provider's own, or its notice (P100). */
44
+ readonly show?: Show;
43
45
  }
44
46
  /** The provider's page state, for the binding's other components (`PortholeView`). */
45
47
  export declare const PortholeContext: import("react").Context<PageState>;
@@ -91,6 +93,13 @@ export interface PortholeProviderProps {
91
93
  * refuses them all with its reason, and their handlers may be left out (P080).
92
94
  */
93
95
  readonly consent?: Consent | Refused;
96
+ /**
97
+ * Shows the person each `show`-gated call, outside every frame, before its handler has it
98
+ * (P100): by default, a frame's model context update (`setModelContext`), the content's text for
99
+ * the agent's next turn. Omitted: Porthole's `ContextNotice`. A host that shows it its own way (a
100
+ * chip by its composer) passes this; the update replaces the display's last.
101
+ */
102
+ readonly show?: Show;
94
103
  /** What the host last had for a resource, answered stale first (P079). */
95
104
  readonly cached?: DataCache;
96
105
  /** How the host names itself in the handshake. */
@@ -104,6 +113,8 @@ export interface PortholeProviderProps {
104
113
  readonly dialogClassName?: string;
105
114
  /** A class for the default copy toast, to restyle it. */
106
115
  readonly toastClassName?: string;
116
+ /** A class for the default model context notice, to restyle it. */
117
+ readonly contextClassName?: string;
107
118
  /**
108
119
  * The page's CSP nonce, where its `script-src` is nonce-based: opaque frames inherit the page's
109
120
  * policy, so their shell carries it (P054). `"auto"`: read from the page (a `<meta