@botiverse/porthole 0.4.0 → 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.
- package/README.md +3 -1
- package/dist/bridge/bridge.d.ts +16 -2
- package/dist/bridge/bridge.js +65 -12
- package/dist/bridge/types.d.ts +44 -6
- package/dist/check/lint.js +2 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +5 -0
- package/dist/compile/policy.d.ts +5 -0
- package/dist/compile/policy.js +18 -1
- package/dist/config/capabilities.d.ts +25 -2
- package/dist/config/capabilities.js +13 -0
- package/dist/config/schema.d.ts +7 -0
- package/dist/config/validate.js +14 -3
- package/dist/conformance/harness/page.js +1 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/displays/displays.d.ts +1 -1
- package/dist/guide/guide.js +48 -8
- package/dist/host/create-host.js +5 -1
- package/dist/host/types.d.ts +12 -1
- package/dist/index.d.ts +4 -3
- package/dist/index.js +2 -1
- package/dist/libraries/files.generated.d.ts +1 -0
- package/dist/libraries/files.generated.js +8 -0
- package/dist/libraries/libraries.d.ts +36 -0
- package/dist/libraries/libraries.js +40 -0
- package/dist/mcp/adapter.js +31 -2
- package/dist/presets/presets.d.ts +15 -0
- package/dist/presets/presets.js +27 -2
- package/dist/protocol/live-data.d.ts +27 -0
- package/dist/protocol/live-data.js +98 -0
- package/dist/protocol/mcp-apps.d.ts +9 -0
- package/dist/protocol/mcp-apps.js +11 -0
- package/dist/protocol/shell-adapter.js +35 -2
- package/dist/react/dialog.js +2 -0
- package/dist/react/frame.d.ts +15 -1
- package/dist/react/frame.js +35 -1
- package/dist/server/libraries.d.ts +7 -0
- package/dist/server/libraries.js +27 -0
- package/dist/server/server.js +2 -1
- package/dist/shell/annotate.js +4 -1
- package/dist/shell/runtime.d.ts +5 -1
- package/dist/shell/runtime.js +165 -1
- package/docs/ADOPTING.md +57 -1
- package/docs/DECISIONS.md +129 -0
- package/docs/DESIGN.md +19 -6
- package/package.json +3 -1
- package/src/bridge/bridge.ts +85 -13
- package/src/bridge/types.ts +45 -3
- package/src/check/lint.ts +2 -1
- package/src/check/page.ts +5 -0
- package/src/compile/policy.ts +19 -1
- package/src/config/capabilities.ts +21 -0
- package/src/config/schema.ts +7 -0
- package/src/config/validate.ts +21 -3
- package/src/conformance/harness/page.ts +1 -0
- package/src/displays/displays.ts +1 -1
- package/src/guide/guide.ts +57 -7
- package/src/host/create-host.ts +5 -1
- package/src/host/types.ts +12 -1
- package/src/index.ts +13 -0
- package/src/libraries/files.generated.ts +8 -0
- package/src/libraries/libraries.ts +64 -0
- package/src/mcp/adapter.ts +40 -2
- package/src/presets/presets.ts +46 -3
- package/src/protocol/live-data.ts +138 -0
- package/src/protocol/mcp-apps.ts +12 -0
- package/src/protocol/shell-adapter.ts +35 -3
- package/src/react/dialog.tsx +2 -0
- package/src/react/frame.tsx +54 -0
- package/src/server/libraries.ts +28 -0
- package/src/server/server.ts +2 -1
- package/src/shell/annotate.ts +4 -1
- 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}`;
|
package/dist/mcp/adapter.js
CHANGED
|
@@ -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")
|
|
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
|
-
|
|
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.
|
package/dist/presets/presets.js
CHANGED
|
@@ -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
|
-
|
|
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
|
},
|
package/dist/react/dialog.js
CHANGED
|
@@ -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:
|
package/dist/react/frame.d.ts
CHANGED
|
@@ -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). */
|
package/dist/react/frame.js
CHANGED
|
@@ -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;
|