@botiverse/porthole 0.4.1 → 0.5.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 (71) hide show
  1. package/README.md +3 -1
  2. package/dist/bridge/bridge.d.ts +16 -2
  3. package/dist/bridge/bridge.js +65 -12
  4. package/dist/bridge/types.d.ts +44 -6
  5. package/dist/check/lint.js +2 -2
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/check/page.js +5 -0
  8. package/dist/compile/policy.d.ts +5 -0
  9. package/dist/compile/policy.js +18 -1
  10. package/dist/config/capabilities.d.ts +25 -2
  11. package/dist/config/capabilities.js +13 -0
  12. package/dist/config/schema.d.ts +7 -0
  13. package/dist/config/validate.js +14 -3
  14. package/dist/conformance/harness/page.js +1 -0
  15. package/dist/conformance/harness-source.js +1 -1
  16. package/dist/displays/displays.d.ts +1 -1
  17. package/dist/guide/guide.js +48 -8
  18. package/dist/host/create-host.js +5 -1
  19. package/dist/host/types.d.ts +12 -1
  20. package/dist/index.d.ts +4 -3
  21. package/dist/index.js +2 -1
  22. package/dist/libraries/files.generated.d.ts +1 -0
  23. package/dist/libraries/files.generated.js +8 -0
  24. package/dist/libraries/libraries.d.ts +36 -0
  25. package/dist/libraries/libraries.js +40 -0
  26. package/dist/mcp/adapter.js +31 -2
  27. package/dist/presets/presets.d.ts +15 -0
  28. package/dist/presets/presets.js +27 -2
  29. package/dist/protocol/live-data.d.ts +27 -0
  30. package/dist/protocol/live-data.js +98 -0
  31. package/dist/protocol/mcp-apps.d.ts +9 -0
  32. package/dist/protocol/mcp-apps.js +11 -0
  33. package/dist/protocol/shell-adapter.js +35 -2
  34. package/dist/react/dialog.js +2 -0
  35. package/dist/react/frame.d.ts +15 -1
  36. package/dist/react/frame.js +35 -1
  37. package/dist/server/libraries.d.ts +7 -0
  38. package/dist/server/libraries.js +27 -0
  39. package/dist/server/server.js +2 -1
  40. package/dist/shell/runtime.d.ts +5 -1
  41. package/dist/shell/runtime.js +165 -1
  42. package/docs/ADOPTING.md +57 -1
  43. package/docs/DECISIONS.md +129 -0
  44. package/docs/DESIGN.md +19 -6
  45. package/package.json +3 -1
  46. package/src/bridge/bridge.ts +85 -13
  47. package/src/bridge/types.ts +45 -3
  48. package/src/check/lint.ts +2 -1
  49. package/src/check/page.ts +5 -0
  50. package/src/compile/policy.ts +19 -1
  51. package/src/config/capabilities.ts +21 -0
  52. package/src/config/schema.ts +7 -0
  53. package/src/config/validate.ts +21 -3
  54. package/src/conformance/harness/page.ts +1 -0
  55. package/src/displays/displays.ts +1 -1
  56. package/src/guide/guide.ts +57 -7
  57. package/src/host/create-host.ts +5 -1
  58. package/src/host/types.ts +12 -1
  59. package/src/index.ts +13 -0
  60. package/src/libraries/files.generated.ts +8 -0
  61. package/src/libraries/libraries.ts +64 -0
  62. package/src/mcp/adapter.ts +40 -2
  63. package/src/presets/presets.ts +46 -3
  64. package/src/protocol/live-data.ts +138 -0
  65. package/src/protocol/mcp-apps.ts +12 -0
  66. package/src/protocol/shell-adapter.ts +35 -3
  67. package/src/react/dialog.tsx +2 -0
  68. package/src/react/frame.tsx +54 -0
  69. package/src/server/libraries.ts +28 -0
  70. package/src/server/server.ts +2 -1
  71. package/src/shell/runtime.ts +165 -1
@@ -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}`;
@@ -2,6 +2,7 @@ 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
4
  import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.js";
5
+ import { liveData } from "../protocol/live-data.js";
5
6
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
6
7
  /** Levels of `notifications/message` that are errors: they go to the host as `reportError`. */
7
8
  const ERROR_LEVELS = new Set(["error", "critical", "alert", "emergency"]);
@@ -67,6 +68,10 @@ function connect(session, options) {
67
68
  }
68
69
  };
69
70
  const answer = (id, result) => send({ jsonrpc: "2.0", id, result });
71
+ // Live data (P079): reads, subscriptions and the host's updates, through the bridge.
72
+ const live = liveData(bridge, (uri) => notify(MCP_APPS_METHODS.resourceUpdated, { uri }), {
73
+ userActivated: hostActivation,
74
+ });
70
75
  const refuse = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
71
76
  const hostCapabilities = () => {
72
77
  const declared = (name) => bridge.declared(name);
@@ -80,7 +85,9 @@ function connect(session, options) {
80
85
  ...(declared("openLink") ? { openLinks: {} } : {}),
81
86
  ...(declared("downloadFile") ? { downloadFile: {} } : {}),
82
87
  ...(declared("callTool") ? { serverTools: {} } : {}),
83
- ...(declared("readData") ? { serverResources: {} } : {}),
88
+ ...(declared("readData")
89
+ ? { serverResources: declared("subscribeData") ? { subscribe: true } : {} }
90
+ : {}),
84
91
  ...(declared("sendPrompt") ? { message: { text: {} } } : {}),
85
92
  ...(declared("setModelContext")
86
93
  ? { updateModelContext: { text: {}, structuredContent: {} } }
@@ -104,6 +111,10 @@ function connect(session, options) {
104
111
  refuse(request.id, JSON_RPC_ERRORS.internal, `${request.method} failed`);
105
112
  return;
106
113
  }
114
+ reply(request, outcome, result);
115
+ }
116
+ /** Answers a request with a capability's outcome. */
117
+ function reply(request, outcome, result) {
107
118
  if (outcome.ok) {
108
119
  answer(request.id, result(outcome.value));
109
120
  }
@@ -168,7 +179,24 @@ function connect(session, options) {
168
179
  invalid("needs a uri");
169
180
  return;
170
181
  }
171
- await call(request, "readData", { uri: params.uri }, (value) => isRecord(value) ? value : { contents: [] });
182
+ reply(request, await live.read(params.uri), (value) => isRecord(value) ? value : { contents: [] });
183
+ return;
184
+ case MCP_APPS_METHODS.subscribeResource:
185
+ case MCP_APPS_METHODS.unsubscribeResource:
186
+ if (!bridge.declared("subscribeData")) {
187
+ refuse(request.id, JSON_RPC_ERRORS.methodNotFound, `${request.method} isn't offered here`);
188
+ return;
189
+ }
190
+ if (typeof params.uri !== "string") {
191
+ invalid("needs a uri");
192
+ return;
193
+ }
194
+ if (request.method === MCP_APPS_METHODS.unsubscribeResource) {
195
+ live.unsubscribe(params.uri);
196
+ answer(request.id, {});
197
+ return;
198
+ }
199
+ reply(request, await live.subscribe(params.uri), () => ({}));
172
200
  return;
173
201
  case MCP_APPS_METHODS.updateModelContext:
174
202
  if ((params.content !== undefined && !Array.isArray(params.content)) ||
@@ -298,6 +326,7 @@ function connect(session, options) {
298
326
  },
299
327
  close() {
300
328
  closed = true;
329
+ live.close();
301
330
  unlisten();
302
331
  queue = [];
303
332
  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,12 @@ 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";
55
64
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
56
65
  export declare const SHELL_LOGGER = "porthole";
57
66
  /**
@@ -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,11 @@ 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";
103
114
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
104
115
  export const SHELL_LOGGER = "porthole";
@@ -1,5 +1,6 @@
1
1
  import { JSON_RPC_ERRORS, parseJsonRpc, } from "./jsonrpc.js";
2
2
  import { COPY_TEXT_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, } from "./mcp-apps.js";
3
+ import { liveData } from "./live-data.js";
3
4
  /**
4
5
  * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
5
6
  * the official App SDK speaks too. Every message is checked before use; every power goes through
@@ -37,7 +38,6 @@ const REQUESTS = {
37
38
  capability: "callTool",
38
39
  args: (params) => ({ name: params.name, arguments: params.arguments }),
39
40
  },
40
- [M.readResource]: { capability: "readData", args: (params) => ({ uri: params.uri }) },
41
41
  [M.updateModelContext]: {
42
42
  capability: "setModelContext",
43
43
  args: (params) => ({ content: params.content, structuredContent: params.structuredContent }),
@@ -75,7 +75,8 @@ export function hostCapabilities(declared) {
75
75
  offered.serverTools = {};
76
76
  }
77
77
  if (declared("readData")) {
78
- offered.serverResources = {};
78
+ // MCP's own flag for resources/subscribe (P079), in the field that mirrors MCP's capability.
79
+ offered.serverResources = declared("subscribeData") ? { subscribe: true } : {};
79
80
  }
80
81
  if (declared("setModelContext")) {
81
82
  offered.updateModelContext = { text: {} };
@@ -98,6 +99,8 @@ export const shellAdapter = {
98
99
  const pending = new Map();
99
100
  const respond = (id, body) => transport.send({ jsonrpc: "2.0", id, ...body });
100
101
  const notify = (method, params) => transport.send({ jsonrpc: "2.0", method, params });
102
+ // Live data (P079): reads, subscriptions and the host's updates, through the bridge.
103
+ const live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
101
104
  const flush = () => {
102
105
  if (!initialized || closed || content === null || sentWhole) {
103
106
  return;
@@ -133,6 +136,35 @@ export const shellAdapter = {
133
136
  respond(request.id, { result: { mode: "inline" } });
134
137
  return;
135
138
  }
139
+ if (request.method === M.readResource) {
140
+ const outcome = await live.read(params.uri);
141
+ if (!closed) {
142
+ respond(request.id, answer("readData", outcome));
143
+ }
144
+ return;
145
+ }
146
+ if (request.method === M.subscribeResource || request.method === M.unsubscribeResource) {
147
+ if (!bridge.declared("subscribeData")) {
148
+ respond(request.id, {
149
+ error: {
150
+ code: JSON_RPC_ERRORS.methodNotFound,
151
+ message: `${request.method} isn't offered here`,
152
+ },
153
+ });
154
+ return;
155
+ }
156
+ if (request.method === M.subscribeResource) {
157
+ const outcome = await live.subscribe(params.uri);
158
+ if (!closed) {
159
+ respond(request.id, outcome.ok ? { result: {} } : answer("subscribeData", outcome));
160
+ }
161
+ }
162
+ else {
163
+ live.unsubscribe(params.uri);
164
+ respond(request.id, { result: {} });
165
+ }
166
+ return;
167
+ }
136
168
  const mapped = REQUESTS[request.method];
137
169
  if (mapped === undefined) {
138
170
  respond(request.id, {
@@ -226,6 +258,7 @@ export const shellAdapter = {
226
258
  closed = true;
227
259
  stop();
228
260
  pending.clear();
261
+ live.close();
229
262
  },
230
263
  };
231
264
  },
@@ -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,6 @@
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
4
  import type { CapabilityName } from "../config/capabilities.ts";
5
5
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
6
6
  import type { FrameOutcome, HostErrorKind } from "../host/types.ts";
@@ -23,6 +23,9 @@ interface PageState {
23
23
  /** Heights displays reported, by display id: a frame mounting again starts at its last. */
24
24
  readonly heights: Map<string, number>;
25
25
  readonly confirm?: Confirm;
26
+ /** The provider's consent and cache (P079), read when a frame asks. */
27
+ readonly consent?: Consent;
28
+ readonly cached?: DataCache;
26
29
  readonly hostInfo?: {
27
30
  readonly name: string;
28
31
  readonly version: string;
@@ -77,6 +80,13 @@ export interface PortholeProviderProps {
77
80
  * Pass your own function to replace it.
78
81
  */
79
82
  readonly confirm?: Confirm;
83
+ /**
84
+ * Whether a frame below may make its `consent`-gated calls (read the viewer's data, P079):
85
+ * asked once per display, before the first. Omitted: those calls are refused.
86
+ */
87
+ readonly consent?: Consent;
88
+ /** What the host last had for a resource, answered stale first (P079). */
89
+ readonly cached?: DataCache;
80
90
  /** How the host names itself in the handshake. */
81
91
  readonly hostInfo?: {
82
92
  readonly name: string;
@@ -139,6 +149,10 @@ export interface PortholeFrameProps {
139
149
  readonly handlers?: CapabilityHandlers;
140
150
  /** Who confirms this frame's gated calls, over the provider's. */
141
151
  readonly confirm?: Confirm;
152
+ /** Whether this frame may make its `consent`-gated calls, over the provider's (P079). */
153
+ readonly consent?: Consent;
154
+ /** This frame's data cache, over the provider's (P079). */
155
+ readonly cached?: DataCache;
142
156
  /** Bump to run the content again from the start. */
143
157
  readonly generation?: number;
144
158
  /** Run at once, without waiting to near the screen (it still counts toward the page's most). */
@@ -45,6 +45,17 @@ export function PortholeProvider(props) {
45
45
  const confirm = useCallback((request, proceed) => own.current !== undefined
46
46
  ? own.current(request, proceed)
47
47
  : new Promise((resolve) => setQueue((waiting) => [...waiting, { request, resolve, proceed }])), []);
48
+ // The host's consent and cache as of the last render (P079), read when a frame asks.
49
+ const ownConsent = useRef(props.consent);
50
+ const ownCached = useRef(props.cached);
51
+ useLayoutEffect(() => {
52
+ ownConsent.current = props.consent;
53
+ ownCached.current = props.cached;
54
+ });
55
+ const consent = useCallback((request) => ownConsent.current?.(request) ?? false, []);
56
+ const cached = useCallback((args, context) => ownCached.current?.(args, context), []);
57
+ const consents = props.consent !== undefined;
58
+ const caches = props.cached !== undefined;
48
59
  // The default copyText: the host's page writes the clipboard (in the frame's click, which
49
60
  // activated this page too) and shows the person what went on it, or offers to copy it.
50
61
  const [notice, setNotice] = useState(null);
@@ -111,6 +122,8 @@ export function PortholeProvider(props) {
111
122
  heights,
112
123
  confirm,
113
124
  copyText,
125
+ ...(consents ? { consent } : {}),
126
+ ...(caches ? { cached } : {}),
114
127
  ...(hostInfo === undefined ? {} : { hostInfo }),
115
128
  ...(locates ? { locate } : {}),
116
129
  ...(nonce === undefined ? {} : { nonce }),
@@ -124,6 +137,10 @@ export function PortholeProvider(props) {
124
137
  heights,
125
138
  confirm,
126
139
  copyText,
140
+ consents,
141
+ consent,
142
+ caches,
143
+ cached,
127
144
  hostInfo,
128
145
  locates,
129
146
  locate,
@@ -271,7 +288,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
271
288
  // value) re-themes the running display, never makes it again (#9, P074). What a display is
272
289
  // made with comes from the provider's stable parts below.
273
290
  const latestPage = useEffectEvent(() => page);
274
- const { handlers: pageHandlers, copyText: pageCopyText, confirm: pageConfirm, hostInfo, locate, nonce, } = page;
291
+ const { handlers: pageHandlers, copyText: pageCopyText, confirm: pageConfirm, consent: pageConsent, cached: pageCached, hostInfo, locate, nonce, } = page;
275
292
  const notify = useEffectEvent((event, detail) => {
276
293
  switch (event) {
277
294
  case "initialized":
@@ -351,6 +368,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
351
368
  }
352
369
  }
353
370
  const asks = first.confirm !== undefined || pageConfirm !== undefined;
371
+ const asksConsent = first.consent !== undefined || pageConsent !== undefined;
372
+ const caches = first.cached !== undefined || pageCached !== undefined;
354
373
  let display;
355
374
  try {
356
375
  display = createHost(config, {
@@ -367,6 +386,19 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
367
386
  }, proceed),
368
387
  }
369
388
  : {}),
389
+ ...(asksConsent
390
+ ? {
391
+ consent: (request) => (latest().consent ?? pageConsent ?? (() => false))({
392
+ ...request,
393
+ display: { ...request.display, id: latest().displayId, title: latest().title },
394
+ }),
395
+ }
396
+ : {}),
397
+ ...(caches
398
+ ? {
399
+ cached: (args, context) => (latest().cached ?? pageCached)?.(args, named(context)),
400
+ }
401
+ : {}),
370
402
  theme: (each) => (latest().theme ?? latestPage().theme)?.(each) ?? {},
371
403
  ...(hostInfo === undefined ? {} : { hostInfo }),
372
404
  ...(locate === undefined ? {} : { locator: { locate } }),
@@ -423,6 +455,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
423
455
  pageHandlers,
424
456
  pageCopyText,
425
457
  pageConfirm,
458
+ pageConsent,
459
+ pageCached,
426
460
  hostInfo,
427
461
  locate,
428
462
  nonce,
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Porthole's vendored libraries (P079), as every content origin serves them under `LIBRARY_PATH`:
3
+ * fixed files, the same for everyone, so no ticket or cookie is asked for and they may be cached
4
+ * for good (a path's bytes never change). Same-site only: content origins load them, no one else.
5
+ * Null for any other path (the reserved prefix's 404 answers it).
6
+ */
7
+ export declare function libraryFile(pathname: string, method: string): Response | null;