@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.
- package/README.md +3 -1
- package/dist/bridge/bridge.d.ts +24 -2
- package/dist/bridge/bridge.js +102 -17
- package/dist/bridge/navigation.d.ts +11 -0
- package/dist/bridge/navigation.js +30 -0
- package/dist/bridge/refusal.d.ts +53 -0
- package/dist/bridge/refusal.js +121 -0
- package/dist/bridge/types.d.ts +51 -6
- package/dist/check/lint.js +2 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +10 -0
- package/dist/compile/policy.d.ts +5 -0
- package/dist/compile/policy.js +18 -1
- package/dist/config/capabilities.d.ts +30 -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 +58 -8
- package/dist/host/create-host.js +18 -3
- package/dist/host/types.d.ts +25 -1
- package/dist/index.d.ts +5 -3
- package/dist/index.js +4 -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 +49 -5
- 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 +15 -0
- package/dist/protocol/mcp-apps.js +17 -0
- package/dist/protocol/shell-adapter.js +49 -4
- package/dist/react/dialog.js +2 -0
- package/dist/react/frame.d.ts +30 -1
- package/dist/react/frame.js +63 -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/runtime.d.ts +5 -1
- package/dist/shell/runtime.js +196 -6
- package/docs/ADOPTING.md +89 -3
- package/docs/DECISIONS.md +221 -0
- package/docs/DESIGN.md +28 -10
- package/package.json +3 -1
- package/src/bridge/bridge.ts +136 -16
- package/src/bridge/navigation.ts +34 -0
- package/src/bridge/refusal.ts +151 -0
- package/src/bridge/types.ts +57 -4
- package/src/check/lint.ts +2 -1
- package/src/check/page.ts +12 -0
- package/src/compile/policy.ts +19 -1
- package/src/config/capabilities.ts +26 -1
- 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 +71 -7
- package/src/host/create-host.ts +19 -3
- package/src/host/types.ts +23 -1
- package/src/index.ts +22 -0
- package/src/libraries/files.generated.ts +8 -0
- package/src/libraries/libraries.ts +64 -0
- package/src/mcp/adapter.ts +63 -5
- package/src/presets/presets.ts +46 -3
- package/src/protocol/live-data.ts +138 -0
- package/src/protocol/mcp-apps.ts +19 -0
- package/src/protocol/shell-adapter.ts +50 -5
- package/src/react/dialog.tsx +2 -0
- package/src/react/frame.tsx +93 -0
- package/src/server/libraries.ts +28 -0
- package/src/server/server.ts +2 -1
- 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}`;
|
package/dist/mcp/adapter.js
CHANGED
|
@@ -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")
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
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,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 {
|
|
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
|
-
: {
|
|
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
|
-
|
|
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
|
},
|
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,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;
|