@botiverse/porthole 0.4.1 → 0.5.1

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 (77) hide show
  1. package/README.md +3 -1
  2. package/dist/bridge/bridge.d.ts +24 -2
  3. package/dist/bridge/bridge.js +102 -17
  4. package/dist/bridge/navigation.d.ts +11 -0
  5. package/dist/bridge/navigation.js +30 -0
  6. package/dist/bridge/refusal.d.ts +53 -0
  7. package/dist/bridge/refusal.js +121 -0
  8. package/dist/bridge/types.d.ts +51 -6
  9. package/dist/check/lint.js +2 -2
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/page.js +10 -0
  12. package/dist/compile/policy.d.ts +5 -0
  13. package/dist/compile/policy.js +18 -1
  14. package/dist/config/capabilities.d.ts +30 -2
  15. package/dist/config/capabilities.js +13 -0
  16. package/dist/config/schema.d.ts +7 -0
  17. package/dist/config/validate.js +14 -3
  18. package/dist/conformance/harness/page.js +1 -0
  19. package/dist/conformance/harness-source.js +1 -1
  20. package/dist/displays/displays.d.ts +1 -1
  21. package/dist/guide/guide.js +58 -8
  22. package/dist/host/create-host.js +18 -3
  23. package/dist/host/types.d.ts +25 -1
  24. package/dist/index.d.ts +5 -3
  25. package/dist/index.js +4 -1
  26. package/dist/libraries/files.generated.d.ts +1 -0
  27. package/dist/libraries/files.generated.js +8 -0
  28. package/dist/libraries/libraries.d.ts +36 -0
  29. package/dist/libraries/libraries.js +40 -0
  30. package/dist/mcp/adapter.js +49 -5
  31. package/dist/presets/presets.d.ts +15 -0
  32. package/dist/presets/presets.js +27 -2
  33. package/dist/protocol/live-data.d.ts +27 -0
  34. package/dist/protocol/live-data.js +98 -0
  35. package/dist/protocol/mcp-apps.d.ts +15 -0
  36. package/dist/protocol/mcp-apps.js +17 -0
  37. package/dist/protocol/shell-adapter.js +49 -4
  38. package/dist/react/dialog.js +2 -0
  39. package/dist/react/frame.d.ts +30 -1
  40. package/dist/react/frame.js +63 -1
  41. package/dist/server/libraries.d.ts +7 -0
  42. package/dist/server/libraries.js +27 -0
  43. package/dist/server/server.js +2 -1
  44. package/dist/shell/runtime.d.ts +5 -1
  45. package/dist/shell/runtime.js +196 -6
  46. package/docs/ADOPTING.md +89 -3
  47. package/docs/DECISIONS.md +221 -0
  48. package/docs/DESIGN.md +28 -10
  49. package/package.json +3 -1
  50. package/src/bridge/bridge.ts +136 -16
  51. package/src/bridge/navigation.ts +34 -0
  52. package/src/bridge/refusal.ts +151 -0
  53. package/src/bridge/types.ts +57 -4
  54. package/src/check/lint.ts +2 -1
  55. package/src/check/page.ts +12 -0
  56. package/src/compile/policy.ts +19 -1
  57. package/src/config/capabilities.ts +26 -1
  58. package/src/config/schema.ts +7 -0
  59. package/src/config/validate.ts +21 -3
  60. package/src/conformance/harness/page.ts +1 -0
  61. package/src/displays/displays.ts +1 -1
  62. package/src/guide/guide.ts +71 -7
  63. package/src/host/create-host.ts +19 -3
  64. package/src/host/types.ts +23 -1
  65. package/src/index.ts +22 -0
  66. package/src/libraries/files.generated.ts +8 -0
  67. package/src/libraries/libraries.ts +64 -0
  68. package/src/mcp/adapter.ts +63 -5
  69. package/src/presets/presets.ts +46 -3
  70. package/src/protocol/live-data.ts +138 -0
  71. package/src/protocol/mcp-apps.ts +19 -0
  72. package/src/protocol/shell-adapter.ts +50 -5
  73. package/src/react/dialog.tsx +2 -0
  74. package/src/react/frame.tsx +93 -0
  75. package/src/server/libraries.ts +28 -0
  76. package/src/server/server.ts +2 -1
  77. package/src/shell/runtime.ts +196 -6
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Porthole's vendored libraries (P079): a small fixed set, pinned, copied byte for byte from their
3
+ * npm packages when Porthole is built (`scripts/vendor-libraries.ts`), and served by `/server` on
4
+ * every content origin under `LIBRARY_PATH`. A config that sets `egress.libraries` loads scripts
5
+ * from there (its own origin) and the manual teaches the lines below; nothing else is fetched.
6
+ *
7
+ * A path, once released, keeps serving the same bytes: a new version is a new path beside it.
8
+ */
9
+ /** Where the libraries are served on a content origin (inside Porthole's reserved prefix). */
10
+ export declare const LIBRARY_PATH = "/__porthole/lib/";
11
+ export interface VendoredLibrary {
12
+ /** What the manual calls it. */
13
+ readonly title: string;
14
+ /** The npm package. */
15
+ readonly name: string;
16
+ /** Its exact version (published at least two weeks before it was vendored). */
17
+ readonly version: string;
18
+ /** The file served, as a path inside the package (a classic script: it defines `global`). */
19
+ readonly file: string;
20
+ /** The global the script defines. */
21
+ readonly global: string;
22
+ /** Its license (SPDX), and the package's license file, served beside it. */
23
+ readonly license: string;
24
+ readonly licenseFile: string;
25
+ /** What it is for, for the manual. */
26
+ readonly use: string;
27
+ }
28
+ /**
29
+ * What agent-made widgets reach for most: Chart.js for charts, D3 for anything drawn from data
30
+ * (scales, axes, shapes, time and number formats). Both run as classic scripts.
31
+ */
32
+ export declare const VENDORED_LIBRARIES: readonly VendoredLibrary[];
33
+ /** Where a library's file is served, on the frame's own origin. */
34
+ export declare const libraryPath: (library: VendoredLibrary) => string;
35
+ /** Where its license is served, beside it. */
36
+ export declare const licensePath: (library: VendoredLibrary) => string;
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Porthole's vendored libraries (P079): a small fixed set, pinned, copied byte for byte from their
3
+ * npm packages when Porthole is built (`scripts/vendor-libraries.ts`), and served by `/server` on
4
+ * every content origin under `LIBRARY_PATH`. A config that sets `egress.libraries` loads scripts
5
+ * from there (its own origin) and the manual teaches the lines below; nothing else is fetched.
6
+ *
7
+ * A path, once released, keeps serving the same bytes: a new version is a new path beside it.
8
+ */
9
+ /** Where the libraries are served on a content origin (inside Porthole's reserved prefix). */
10
+ export const LIBRARY_PATH = "/__porthole/lib/";
11
+ /**
12
+ * What agent-made widgets reach for most: Chart.js for charts, D3 for anything drawn from data
13
+ * (scales, axes, shapes, time and number formats). Both run as classic scripts.
14
+ */
15
+ export const VENDORED_LIBRARIES = [
16
+ {
17
+ title: "Chart.js",
18
+ name: "chart.js",
19
+ version: "4.5.1",
20
+ file: "dist/chart.umd.min.js",
21
+ global: "Chart",
22
+ license: "MIT",
23
+ licenseFile: "LICENSE.md",
24
+ use: "charts",
25
+ },
26
+ {
27
+ title: "D3",
28
+ name: "d3",
29
+ version: "7.9.0",
30
+ file: "dist/d3.min.js",
31
+ global: "d3",
32
+ license: "ISC",
33
+ licenseFile: "LICENSE",
34
+ use: "scales, axes, shapes, time and number formats",
35
+ },
36
+ ];
37
+ /** Where a library's file is served, on the frame's own origin. */
38
+ export const libraryPath = (library) => `${LIBRARY_PATH}${library.name}@${library.version}/${library.file}`;
39
+ /** Where its license is served, beside it. */
40
+ export const licensePath = (library) => `${LIBRARY_PATH}${library.name}@${library.version}/${library.licenseFile}`;
@@ -1,7 +1,9 @@
1
1
  import { egressOrigins } from "../compile/policy.js";
2
2
  import { JSON_RPC_ERRORS, parseJsonRpc, } from "../protocol/jsonrpc.js";
3
3
  import { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, } from "../protocol/mcp-apps.js";
4
- import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.js";
4
+ import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES, NAVIGATION_BLOCKED_METHOD, } from "../protocol/mcp-apps.js";
5
+ import { liveData } from "../protocol/live-data.js";
6
+ import { reasonFor } from "../bridge/refusal.js";
5
7
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
6
8
  /** Levels of `notifications/message` that are errors: they go to the host as `reportError`. */
7
9
  const ERROR_LEVELS = new Set(["error", "critical", "alert", "emergency"]);
@@ -67,6 +69,10 @@ function connect(session, options) {
67
69
  }
68
70
  };
69
71
  const answer = (id, result) => send({ jsonrpc: "2.0", id, result });
72
+ // Live data (P079): reads, subscriptions and the host's updates, through the bridge.
73
+ const live = liveData(bridge, (uri) => notify(MCP_APPS_METHODS.resourceUpdated, { uri }), {
74
+ userActivated: hostActivation,
75
+ });
70
76
  const refuse = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
71
77
  const hostCapabilities = () => {
72
78
  const declared = (name) => bridge.declared(name);
@@ -80,7 +86,9 @@ function connect(session, options) {
80
86
  ...(declared("openLink") ? { openLinks: {} } : {}),
81
87
  ...(declared("downloadFile") ? { downloadFile: {} } : {}),
82
88
  ...(declared("callTool") ? { serverTools: {} } : {}),
83
- ...(declared("readData") ? { serverResources: {} } : {}),
89
+ ...(declared("readData")
90
+ ? { serverResources: declared("subscribeData") ? { subscribe: true } : {} }
91
+ : {}),
84
92
  ...(declared("sendPrompt") ? { message: { text: {} } } : {}),
85
93
  ...(declared("setModelContext")
86
94
  ? { updateModelContext: { text: {}, structuredContent: {} } }
@@ -104,6 +112,10 @@ function connect(session, options) {
104
112
  refuse(request.id, JSON_RPC_ERRORS.internal, `${request.method} failed`);
105
113
  return;
106
114
  }
115
+ reply(request, capability, outcome, result);
116
+ }
117
+ /** Answers a request with a capability's outcome. */
118
+ function reply(request, capability, outcome, result) {
107
119
  if (outcome.ok) {
108
120
  answer(request.id, result(outcome.value));
109
121
  }
@@ -111,8 +123,17 @@ function connect(session, options) {
111
123
  refuse(request.id, JSON_RPC_ERRORS.methodNotFound, `${request.method} isn't offered here`);
112
124
  }
113
125
  else {
114
- // The spec's "implementation-defined" error for a refused request.
115
- refuse(request.id, -32_000, `${request.method} refused (${outcome.refusal})`);
126
+ // The spec's "implementation-defined" error for a refused request, with why in its data
127
+ // (`{ code, message }`, P080).
128
+ send({
129
+ jsonrpc: "2.0",
130
+ id: request.id,
131
+ error: {
132
+ code: -32_000,
133
+ message: `${request.method} refused (${outcome.refusal})`,
134
+ data: reasonFor(capability, outcome),
135
+ },
136
+ });
116
137
  }
117
138
  }
118
139
  /** `{}` when a host function did it, `{ isError: true }` when it said it couldn't. */
@@ -168,7 +189,24 @@ function connect(session, options) {
168
189
  invalid("needs a uri");
169
190
  return;
170
191
  }
171
- await call(request, "readData", { uri: params.uri }, (value) => isRecord(value) ? value : { contents: [] });
192
+ reply(request, "readData", await live.read(params.uri), (value) => isRecord(value) ? value : { contents: [] });
193
+ return;
194
+ case MCP_APPS_METHODS.subscribeResource:
195
+ case MCP_APPS_METHODS.unsubscribeResource:
196
+ if (!bridge.declared("subscribeData")) {
197
+ refuse(request.id, JSON_RPC_ERRORS.methodNotFound, `${request.method} isn't offered here`);
198
+ return;
199
+ }
200
+ if (typeof params.uri !== "string") {
201
+ invalid("needs a uri");
202
+ return;
203
+ }
204
+ if (request.method === MCP_APPS_METHODS.unsubscribeResource) {
205
+ live.unsubscribe(params.uri);
206
+ answer(request.id, {});
207
+ return;
208
+ }
209
+ reply(request, "subscribeData", await live.subscribe(params.uri), () => ({}));
172
210
  return;
173
211
  case MCP_APPS_METHODS.updateModelContext:
174
212
  if ((params.content !== undefined && !Array.isArray(params.content)) ||
@@ -246,6 +284,11 @@ function connect(session, options) {
246
284
  });
247
285
  }
248
286
  return;
287
+ case NAVIGATION_BLOCKED_METHOD:
288
+ // The shell, hardening the view's frame, stopped a navigation (P080): an error report,
289
+ // with its address.
290
+ void bridge.call("reportError", { navigationBlocked: params.url });
291
+ return;
249
292
  case MCP_APPS_METHODS.requestTeardown:
250
293
  session.emit({ type: "teardown-requested" });
251
294
  return;
@@ -298,6 +341,7 @@ function connect(session, options) {
298
341
  },
299
342
  close() {
300
343
  closed = true;
344
+ live.close();
301
345
  unlisten();
302
346
  queue = [];
303
347
  for (const waiting of pending.values()) {
@@ -35,6 +35,11 @@ export interface PresetOptions {
35
35
  /** Where the content's errors go (`PortholeConfig.errors`); `none` drops `reportError`. */
36
36
  readonly errors?: "agent" | "host" | "none";
37
37
  }
38
+ /**
39
+ * The live widget's options (P079): a widget's, less egress, which stays closed (Porthole's own
40
+ * libraries come with domain isolation). A host adds capabilities, or changes the data ones' gates.
41
+ */
42
+ export type LiveWidgetOptions = Omit<PresetOptions, "egress">;
38
43
  /** The url preset's options: where the app is served, and the embedding page's extra frames. */
39
44
  export interface UrlPresetOptions {
40
45
  readonly contentOrigins: readonly string[];
@@ -59,6 +64,16 @@ export declare const presets: {
59
64
  * frame with the shell, streamed as it is written.
60
65
  */
61
66
  readonly inlineWidget: (options?: PresetOptions) => PortholeConfig;
67
+ /**
68
+ * A widget that shows its host's data, live, and has no network of its own (P079): an inline
69
+ * widget whose egress stays closed (no option opens it). It reads the host's data (`readData`,
70
+ * MCP `resources/read`) and subscribes to it (`subscribeData`, `resources/subscribe`), each
71
+ * behind the viewer's consent (the host's `consent`, asked once per display) and a rate. In
72
+ * domain isolation its scripts load from Porthole's own libraries on its origin
73
+ * (`egress.libraries`: Chart.js, D3), and nowhere else. A host adds what any widget may have (a
74
+ * link, a copy button), or changes the data capabilities' gates.
75
+ */
76
+ readonly liveWidget: (options?: LiveWidgetOptions) => PortholeConfig;
62
77
  /**
63
78
  * A whole HTML page: written into an opaque frame by the shell where the host has the page, or
64
79
  * served on its own origin (`isolation: "domain"`). A document scrolls inside past a shorter cap.
@@ -1,4 +1,4 @@
1
- import { validateConfig } from "../config/validate.js";
1
+ import { ConfigError, validateConfig } from "../config/validate.js";
2
2
  import { DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES } from "../theme/variables.js";
3
3
  /**
4
4
  * Library CDNs a host may open with one line (`egress: LIBRARY_CDNS`): read-only package caches
@@ -69,6 +69,9 @@ const mergeEgress = (base, extra) => {
69
69
  if (passive.length > 0) {
70
70
  merged.anyHttps = passive;
71
71
  }
72
+ if (base.libraries === true || extra?.libraries === true) {
73
+ merged.libraries = true;
74
+ }
72
75
  return merged;
73
76
  };
74
77
  /** The default variables, with the host's changes and additions, less those it dropped (null). */
@@ -87,6 +90,7 @@ function themeVariables(changes) {
87
90
  function build(mode, defaults, options) {
88
91
  const capabilities = {
89
92
  ...BASE_CAPABILITIES,
93
+ ...defaults.capabilities,
90
94
  };
91
95
  if (options.errors === "none") {
92
96
  delete capabilities.reportError;
@@ -103,7 +107,7 @@ function build(mode, defaults, options) {
103
107
  mode,
104
108
  isolation: options.isolation ?? "opaque",
105
109
  capabilities,
106
- egress: mergeEgress({}, options.egress),
110
+ egress: mergeEgress(defaults.egress ?? {}, options.egress),
107
111
  theme: {
108
112
  variables: themeVariables(options.theme?.variables),
109
113
  event: options.theme?.event ?? DEFAULT_THEME_EVENT,
@@ -124,6 +128,27 @@ export const presets = {
124
128
  * frame with the shell, streamed as it is written.
125
129
  */
126
130
  inlineWidget: (options = {}) => build("inline", {}, options),
131
+ /**
132
+ * A widget that shows its host's data, live, and has no network of its own (P079): an inline
133
+ * widget whose egress stays closed (no option opens it). It reads the host's data (`readData`,
134
+ * MCP `resources/read`) and subscribes to it (`subscribeData`, `resources/subscribe`), each
135
+ * behind the viewer's consent (the host's `consent`, asked once per display) and a rate. In
136
+ * domain isolation its scripts load from Porthole's own libraries on its origin
137
+ * (`egress.libraries`: Chart.js, D3), and nowhere else. A host adds what any widget may have (a
138
+ * link, a copy button), or changes the data capabilities' gates.
139
+ */
140
+ liveWidget: (options = {}) => {
141
+ if (options.egress !== undefined) {
142
+ throw new ConfigError("options.egress", "a live widget has no network of its own: its egress stays closed (P079)");
143
+ }
144
+ return build("inline", {
145
+ capabilities: {
146
+ readData: { gates: ["consent", { rateLimit: { perMinute: 120 } }] },
147
+ subscribeData: { gates: ["consent", { rateLimit: { perMinute: 60 } }] },
148
+ },
149
+ egress: options.isolation === "domain" ? { libraries: true } : {},
150
+ }, options);
151
+ },
127
152
  /**
128
153
  * A whole HTML page: written into an opaque frame by the shell where the host has the page, or
129
154
  * served on its own origin (`isolation: "domain"`). A document scrolls inside past a shorter cap.
@@ -0,0 +1,27 @@
1
+ import type { CallOutcome, HostFunctionBridge } from "../bridge/types.ts";
2
+ /**
3
+ * Live data for one frame (P079), as both adapters speak it (MCP `resources/read`,
4
+ * `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`): the frame's
5
+ * subscriptions by URI, each ended by its controller, and a fresh result the host gave for one
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.
8
+ */
9
+ export interface LiveData {
10
+ /** A read: a fresh result kept for it, else the host's (its cache first, when subscribed). */
11
+ read(uri: unknown): Promise<CallOutcome<unknown>>;
12
+ /** Starts the host's subscription; a second for a URI is a no-op. */
13
+ subscribe(uri: unknown): Promise<CallOutcome<undefined>>;
14
+ /** Ends one: never gated, it stops what the host was doing for this frame. */
15
+ unsubscribe(uri: unknown): void;
16
+ /** The frame is gone: every subscription ends. */
17
+ close(): void;
18
+ }
19
+ /** A `resources/read` result marked as the host's cached copy (`STALE_META`). */
20
+ export declare function markedStale(value: unknown): unknown;
21
+ /**
22
+ * `updated(uri)` sends the frame `notifications/resources/updated`; it is called only for a URI
23
+ * the frame subscribes to.
24
+ */
25
+ export declare function liveData(bridge: HostFunctionBridge, updated: (uri: string) => void, options?: {
26
+ readonly userActivated?: () => boolean | undefined;
27
+ }): LiveData;
@@ -0,0 +1,98 @@
1
+ import { STALE_META } from "./mcp-apps.js";
2
+ /** Where MCP results carry their metadata. */
3
+ const META = "_meta";
4
+ /** A `resources/read` result marked as the host's cached copy (`STALE_META`). */
5
+ export function markedStale(value) {
6
+ const result = value !== null && typeof value === "object" ? value : {};
7
+ const given = result[META];
8
+ const meta = given !== null && typeof given === "object" ? given : {};
9
+ return { ...result, [META]: { ...meta, [STALE_META]: true } };
10
+ }
11
+ /**
12
+ * `updated(uri)` sends the frame `notifications/resources/updated`; it is called only for a URI
13
+ * the frame subscribes to.
14
+ */
15
+ export function liveData(bridge, updated, options = {}) {
16
+ const subscriptions = new Map();
17
+ const fresh = new Map();
18
+ let closed = false;
19
+ const tell = (uri) => {
20
+ if (!closed && subscriptions.has(uri)) {
21
+ updated(uri);
22
+ }
23
+ };
24
+ const activation = () => {
25
+ const userActivated = options.userActivated?.();
26
+ return userActivated === undefined ? {} : { userActivated };
27
+ };
28
+ const end = (uri) => {
29
+ subscriptions.get(uri)?.abort();
30
+ subscriptions.delete(uri);
31
+ fresh.delete(uri);
32
+ };
33
+ return {
34
+ async read(uri) {
35
+ if (typeof uri === "string" && fresh.has(uri)) {
36
+ const value = fresh.get(uri);
37
+ fresh.delete(uri);
38
+ return { ok: true, value };
39
+ }
40
+ const subscribed = typeof uri === "string" && subscriptions.has(uri);
41
+ const outcome = await bridge.call("readData", { uri }, { ...activation(), stale: subscribed });
42
+ if (!outcome.ok || outcome.stale !== true || typeof uri !== "string") {
43
+ return outcome;
44
+ }
45
+ // Answered from the host's cache: the fresh result, for the frame's next read, is told once
46
+ // it is here.
47
+ void bridge.call("readData", { uri }, activation()).then((next) => {
48
+ if (next.ok && !closed && subscriptions.has(uri)) {
49
+ fresh.set(uri, next.value);
50
+ tell(uri);
51
+ }
52
+ });
53
+ return { ok: true, value: markedStale(outcome.value) };
54
+ },
55
+ async subscribe(uri) {
56
+ if (typeof uri === "string" && subscriptions.has(uri)) {
57
+ return { ok: true, value: undefined };
58
+ }
59
+ const controller = new AbortController();
60
+ if (typeof uri === "string") {
61
+ subscriptions.set(uri, controller);
62
+ }
63
+ const outcome = await bridge.call("subscribeData", { uri }, {
64
+ ...activation(),
65
+ subscription: {
66
+ signal: controller.signal,
67
+ changed: (result) => {
68
+ if (controller.signal.aborted || closed || typeof uri !== "string") {
69
+ return;
70
+ }
71
+ if (result !== undefined) {
72
+ fresh.set(uri, result);
73
+ }
74
+ tell(uri);
75
+ },
76
+ },
77
+ });
78
+ if (!outcome.ok) {
79
+ controller.abort();
80
+ if (typeof uri === "string" && subscriptions.get(uri) === controller) {
81
+ subscriptions.delete(uri);
82
+ }
83
+ }
84
+ return outcome;
85
+ },
86
+ unsubscribe(uri) {
87
+ if (typeof uri === "string") {
88
+ end(uri);
89
+ }
90
+ },
91
+ close() {
92
+ closed = true;
93
+ for (const uri of subscriptions.keys()) {
94
+ end(uri);
95
+ }
96
+ },
97
+ };
98
+ }
@@ -14,6 +14,8 @@ export declare const MCP_APPS_METHODS: {
14
14
  readonly updateModelContext: "ui/update-model-context";
15
15
  readonly callTool: "tools/call";
16
16
  readonly readResource: "resources/read";
17
+ readonly subscribeResource: "resources/subscribe";
18
+ readonly unsubscribeResource: "resources/unsubscribe";
17
19
  readonly initialized: "ui/notifications/initialized";
18
20
  readonly sizeChanged: "ui/notifications/size-changed";
19
21
  readonly requestTeardown: "ui/notifications/request-teardown";
@@ -23,6 +25,7 @@ export declare const MCP_APPS_METHODS: {
23
25
  readonly toolResult: "ui/notifications/tool-result";
24
26
  readonly toolCancelled: "ui/notifications/tool-cancelled";
25
27
  readonly hostContextChanged: "ui/notifications/host-context-changed";
28
+ readonly resourceUpdated: "notifications/resources/updated";
26
29
  readonly resourceTeardown: "ui/resource-teardown";
27
30
  readonly sandboxProxyReady: "ui/notifications/sandbox-proxy-ready";
28
31
  readonly sandboxResourceReady: "ui/notifications/sandbox-resource-ready";
@@ -52,6 +55,18 @@ export declare const PORTHOLE_STYLES = "porthole/styles";
52
55
  * host copied it and `{ isError: true }` when it didn't. The standard has no clipboard request.
53
56
  */
54
57
  export declare const COPY_TEXT_METHOD = "porthole/copy-text";
58
+ /**
59
+ * The `_meta` key that marks a `resources/read` result as the host's cached copy (P079): stale,
60
+ * with the fresh one to follow as `notifications/resources/updated`. Only for a resource the view
61
+ * subscribes to.
62
+ */
63
+ export declare const STALE_META = "porthole/stale";
64
+ /**
65
+ * Porthole's own notification from the shell (P080): it cancelled a navigation of the frame to
66
+ * `{ url }` (P079). The content's word, sent only where `reportError` is declared, and counted as
67
+ * one of its reports; the host's adapter carries it into `reportError`.
68
+ */
69
+ export declare const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
55
70
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
56
71
  export declare const SHELL_LOGGER = "porthole";
57
72
  /**
@@ -15,6 +15,10 @@ export const MCP_APPS_METHODS = {
15
15
  updateModelContext: "ui/update-model-context",
16
16
  callTool: "tools/call",
17
17
  readResource: "resources/read",
18
+ // MCP's own resource subscriptions (P079), which MCP Apps doesn't list: the view is the host's
19
+ // MCP client here, as for resources/read.
20
+ subscribeResource: "resources/subscribe",
21
+ unsubscribeResource: "resources/unsubscribe",
18
22
  // View → host notifications.
19
23
  initialized: "ui/notifications/initialized",
20
24
  sizeChanged: "ui/notifications/size-changed",
@@ -26,6 +30,7 @@ export const MCP_APPS_METHODS = {
26
30
  toolResult: "ui/notifications/tool-result",
27
31
  toolCancelled: "ui/notifications/tool-cancelled",
28
32
  hostContextChanged: "ui/notifications/host-context-changed",
33
+ resourceUpdated: "notifications/resources/updated",
29
34
  // Host → view requests.
30
35
  resourceTeardown: "ui/resource-teardown",
31
36
  // Sandbox proxy (a second origin that relays between host and view).
@@ -100,5 +105,17 @@ export const PORTHOLE_STYLES = "porthole/styles";
100
105
  * host copied it and `{ isError: true }` when it didn't. The standard has no clipboard request.
101
106
  */
102
107
  export const COPY_TEXT_METHOD = "porthole/copy-text";
108
+ /**
109
+ * The `_meta` key that marks a `resources/read` result as the host's cached copy (P079): stale,
110
+ * with the fresh one to follow as `notifications/resources/updated`. Only for a resource the view
111
+ * subscribes to.
112
+ */
113
+ export const STALE_META = "porthole/stale";
114
+ /**
115
+ * Porthole's own notification from the shell (P080): it cancelled a navigation of the frame to
116
+ * `{ url }` (P079). The content's word, sent only where `reportError` is declared, and counted as
117
+ * one of its reports; the host's adapter carries it into `reportError`.
118
+ */
119
+ export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
103
120
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
104
121
  export const SHELL_LOGGER = "porthole";
@@ -1,5 +1,7 @@
1
1
  import { JSON_RPC_ERRORS, parseJsonRpc, } from "./jsonrpc.js";
2
- import { COPY_TEXT_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, } from "./mcp-apps.js";
2
+ import { reasonFor } from "../bridge/refusal.js";
3
+ import { COPY_TEXT_METHOD, NAVIGATION_BLOCKED_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, } from "./mcp-apps.js";
4
+ import { liveData } from "./live-data.js";
3
5
  /**
4
6
  * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
5
7
  * the official App SDK speaks too. Every message is checked before use; every power goes through
@@ -37,7 +39,6 @@ const REQUESTS = {
37
39
  capability: "callTool",
38
40
  args: (params) => ({ name: params.name, arguments: params.arguments }),
39
41
  },
40
- [M.readResource]: { capability: "readData", args: (params) => ({ uri: params.uri }) },
41
42
  [M.updateModelContext]: {
42
43
  capability: "setModelContext",
43
44
  args: (params) => ({ content: params.content, structuredContent: params.structuredContent }),
@@ -52,7 +53,14 @@ function answer(capability, outcome) {
52
53
  if (!outcome.ok) {
53
54
  return flagged
54
55
  ? { result: { isError: true } }
55
- : { error: { code: -32000, message: `Refused (${outcome.refusal})` } };
56
+ : {
57
+ // Why, in the error's data (`{ code, message }`, P080).
58
+ error: {
59
+ code: -32000,
60
+ message: `Refused (${outcome.refusal})`,
61
+ data: reasonFor(capability, outcome),
62
+ },
63
+ };
56
64
  }
57
65
  if (flagged) {
58
66
  return { result: outcome.value === true ? {} : { isError: true } };
@@ -75,7 +83,8 @@ export function hostCapabilities(declared) {
75
83
  offered.serverTools = {};
76
84
  }
77
85
  if (declared("readData")) {
78
- offered.serverResources = {};
86
+ // MCP's own flag for resources/subscribe (P079), in the field that mirrors MCP's capability.
87
+ offered.serverResources = declared("subscribeData") ? { subscribe: true } : {};
79
88
  }
80
89
  if (declared("setModelContext")) {
81
90
  offered.updateModelContext = { text: {} };
@@ -98,6 +107,8 @@ export const shellAdapter = {
98
107
  const pending = new Map();
99
108
  const respond = (id, body) => transport.send({ jsonrpc: "2.0", id, ...body });
100
109
  const notify = (method, params) => transport.send({ jsonrpc: "2.0", method, params });
110
+ // Live data (P079): reads, subscriptions and the host's updates, through the bridge.
111
+ const live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
101
112
  const flush = () => {
102
113
  if (!initialized || closed || content === null || sentWhole) {
103
114
  return;
@@ -133,6 +144,35 @@ export const shellAdapter = {
133
144
  respond(request.id, { result: { mode: "inline" } });
134
145
  return;
135
146
  }
147
+ if (request.method === M.readResource) {
148
+ const outcome = await live.read(params.uri);
149
+ if (!closed) {
150
+ respond(request.id, answer("readData", outcome));
151
+ }
152
+ return;
153
+ }
154
+ if (request.method === M.subscribeResource || request.method === M.unsubscribeResource) {
155
+ if (!bridge.declared("subscribeData")) {
156
+ respond(request.id, {
157
+ error: {
158
+ code: JSON_RPC_ERRORS.methodNotFound,
159
+ message: `${request.method} isn't offered here`,
160
+ },
161
+ });
162
+ return;
163
+ }
164
+ if (request.method === M.subscribeResource) {
165
+ const outcome = await live.subscribe(params.uri);
166
+ if (!closed) {
167
+ respond(request.id, outcome.ok ? { result: {} } : answer("subscribeData", outcome));
168
+ }
169
+ }
170
+ else {
171
+ live.unsubscribe(params.uri);
172
+ respond(request.id, { result: {} });
173
+ }
174
+ return;
175
+ }
136
176
  const mapped = REQUESTS[request.method];
137
177
  if (mapped === undefined) {
138
178
  respond(request.id, {
@@ -168,6 +208,10 @@ export const shellAdapter = {
168
208
  });
169
209
  }
170
210
  return;
211
+ case NAVIGATION_BLOCKED_METHOD:
212
+ // The shell stopped a navigation (P080): an error report, with its address.
213
+ void bridge.call("reportError", { navigationBlocked: params.url });
214
+ return;
171
215
  case M.requestTeardown:
172
216
  session.emit({ type: "teardown-requested" });
173
217
  return;
@@ -226,6 +270,7 @@ export const shellAdapter = {
226
270
  closed = true;
227
271
  stop();
228
272
  pending.clear();
273
+ live.close();
229
274
  },
230
275
  };
231
276
  },
@@ -47,6 +47,8 @@ function words(request) {
47
47
  return { heading: "Share this with the agent?", accept: "Share", detail: json(request.args) };
48
48
  case "readData":
49
49
  return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
50
+ case "subscribeData":
51
+ return { heading: "Let it follow this?", accept: "Allow", detail: request.args.uri };
50
52
  case "copyText":
51
53
  return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
52
54
  default:
@@ -1,6 +1,7 @@
1
1
  import { type CSSProperties, type ReactElement, type ReactNode } from "react";
2
2
  import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
3
- import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Refusal } from "../bridge/types.ts";
3
+ import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal } from "../bridge/types.ts";
4
+ import { Refused, type RefusalReason } from "../bridge/refusal.ts";
4
5
  import type { CapabilityName } from "../config/capabilities.ts";
5
6
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
6
7
  import type { FrameOutcome, HostErrorKind } from "../host/types.ts";
@@ -23,6 +24,11 @@ interface PageState {
23
24
  /** Heights displays reported, by display id: a frame mounting again starts at its last. */
24
25
  readonly heights: Map<string, number>;
25
26
  readonly confirm?: Confirm;
27
+ /** The provider's consent and cache (P079), read when a frame asks. */
28
+ readonly consent?: Consent;
29
+ /** The provider's consent is a `Refused` (P080): its reason, by value. */
30
+ readonly refusesAll?: RefusalReason;
31
+ readonly cached?: DataCache;
26
32
  readonly hostInfo?: {
27
33
  readonly name: string;
28
34
  readonly version: string;
@@ -77,6 +83,14 @@ export interface PortholeProviderProps {
77
83
  * Pass your own function to replace it.
78
84
  */
79
85
  readonly confirm?: Confirm;
86
+ /**
87
+ * Whether a frame below may make its `consent`-gated calls (read the viewer's data, P079):
88
+ * asked once per display, before the first. Omitted: those calls are refused. A `Refused`
89
+ * refuses them all with its reason, and their handlers may be left out (P080).
90
+ */
91
+ readonly consent?: Consent | Refused;
92
+ /** What the host last had for a resource, answered stale first (P079). */
93
+ readonly cached?: DataCache;
80
94
  /** How the host names itself in the handshake. */
81
95
  readonly hostInfo?: {
82
96
  readonly name: string;
@@ -139,6 +153,13 @@ export interface PortholeFrameProps {
139
153
  readonly handlers?: CapabilityHandlers;
140
154
  /** Who confirms this frame's gated calls, over the provider's. */
141
155
  readonly confirm?: Confirm;
156
+ /**
157
+ * Whether this frame may make its `consent`-gated calls, over the provider's (P079). A `Refused`
158
+ * refuses them all with its reason, and their handlers may be left out (P080).
159
+ */
160
+ readonly consent?: Consent | Refused;
161
+ /** This frame's data cache, over the provider's (P079). */
162
+ readonly cached?: DataCache;
142
163
  /** Bump to run the content again from the start. */
143
164
  readonly generation?: number;
144
165
  /** Run at once, without waiting to near the screen (it still counts toward the page's most). */
@@ -173,6 +194,14 @@ export interface PortholeFrameProps {
173
194
  readonly onError?: (message: string, source: "content" | "host") => void;
174
195
  /** The content navigated its frame away; it was started again (or stopped, after a few). */
175
196
  readonly onNavigated?: () => void;
197
+ /**
198
+ * The shell stopped the content navigating its frame to `url` (P080): the address whole, the
199
+ * content's word. Served frames only, where the config declares `reportError`; `onContentError`
200
+ * hears it too, without the address's query.
201
+ */
202
+ readonly onNavigationBlocked?: (blocked: {
203
+ readonly url: string;
204
+ }) => void;
176
205
  readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
177
206
  /** Too many declines: the display stops asking until it runs again. */
178
207
  readonly onMuted?: () => void;