@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.
- 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/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/runtime.ts +165 -1
|
@@ -0,0 +1,64 @@
|
|
|
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
|
+
|
|
10
|
+
/** Where the libraries are served on a content origin (inside Porthole's reserved prefix). */
|
|
11
|
+
export const LIBRARY_PATH = "/__porthole/lib/";
|
|
12
|
+
|
|
13
|
+
export interface VendoredLibrary {
|
|
14
|
+
/** What the manual calls it. */
|
|
15
|
+
readonly title: string;
|
|
16
|
+
/** The npm package. */
|
|
17
|
+
readonly name: string;
|
|
18
|
+
/** Its exact version (published at least two weeks before it was vendored). */
|
|
19
|
+
readonly version: string;
|
|
20
|
+
/** The file served, as a path inside the package (a classic script: it defines `global`). */
|
|
21
|
+
readonly file: string;
|
|
22
|
+
/** The global the script defines. */
|
|
23
|
+
readonly global: string;
|
|
24
|
+
/** Its license (SPDX), and the package's license file, served beside it. */
|
|
25
|
+
readonly license: string;
|
|
26
|
+
readonly licenseFile: string;
|
|
27
|
+
/** What it is for, for the manual. */
|
|
28
|
+
readonly use: string;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* What agent-made widgets reach for most: Chart.js for charts, D3 for anything drawn from data
|
|
33
|
+
* (scales, axes, shapes, time and number formats). Both run as classic scripts.
|
|
34
|
+
*/
|
|
35
|
+
export const VENDORED_LIBRARIES: readonly VendoredLibrary[] = [
|
|
36
|
+
{
|
|
37
|
+
title: "Chart.js",
|
|
38
|
+
name: "chart.js",
|
|
39
|
+
version: "4.5.1",
|
|
40
|
+
file: "dist/chart.umd.min.js",
|
|
41
|
+
global: "Chart",
|
|
42
|
+
license: "MIT",
|
|
43
|
+
licenseFile: "LICENSE.md",
|
|
44
|
+
use: "charts",
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
title: "D3",
|
|
48
|
+
name: "d3",
|
|
49
|
+
version: "7.9.0",
|
|
50
|
+
file: "dist/d3.min.js",
|
|
51
|
+
global: "d3",
|
|
52
|
+
license: "ISC",
|
|
53
|
+
licenseFile: "LICENSE",
|
|
54
|
+
use: "scales, axes, shapes, time and number formats",
|
|
55
|
+
},
|
|
56
|
+
];
|
|
57
|
+
|
|
58
|
+
/** Where a library's file is served, on the frame's own origin. */
|
|
59
|
+
export const libraryPath = (library: VendoredLibrary): string =>
|
|
60
|
+
`${LIBRARY_PATH}${library.name}@${library.version}/${library.file}`;
|
|
61
|
+
|
|
62
|
+
/** Where its license is served, beside it. */
|
|
63
|
+
export const licensePath = (library: VendoredLibrary): string =>
|
|
64
|
+
`${LIBRARY_PATH}${library.name}@${library.version}/${library.licenseFile}`;
|
package/src/mcp/adapter.ts
CHANGED
|
@@ -15,6 +15,7 @@ import {
|
|
|
15
15
|
type HostContext,
|
|
16
16
|
} from "../protocol/mcp-apps.ts";
|
|
17
17
|
import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.ts";
|
|
18
|
+
import { liveData } from "../protocol/live-data.ts";
|
|
18
19
|
|
|
19
20
|
/**
|
|
20
21
|
* The MCP Apps adapter (P004, P007): the host side of the protocol for full MCP Apps views, written
|
|
@@ -131,6 +132,10 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
|
|
|
131
132
|
}
|
|
132
133
|
};
|
|
133
134
|
const answer = (id: JsonRpcId, result: unknown): void => send({ jsonrpc: "2.0", id, result });
|
|
135
|
+
// Live data (P079): reads, subscriptions and the host's updates, through the bridge.
|
|
136
|
+
const live = liveData(bridge, (uri) => notify(MCP_APPS_METHODS.resourceUpdated, { uri }), {
|
|
137
|
+
userActivated: hostActivation,
|
|
138
|
+
});
|
|
134
139
|
const refuse = (id: JsonRpcId, code: number, message: string): void =>
|
|
135
140
|
send({ jsonrpc: "2.0", id, error: { code, message } });
|
|
136
141
|
|
|
@@ -150,7 +155,9 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
|
|
|
150
155
|
...(declared("openLink") ? { openLinks: {} } : {}),
|
|
151
156
|
...(declared("downloadFile") ? { downloadFile: {} } : {}),
|
|
152
157
|
...(declared("callTool") ? { serverTools: {} } : {}),
|
|
153
|
-
...(declared("readData")
|
|
158
|
+
...(declared("readData")
|
|
159
|
+
? { serverResources: declared("subscribeData") ? { subscribe: true } : {} }
|
|
160
|
+
: {}),
|
|
154
161
|
...(declared("sendPrompt") ? { message: { text: {} } } : {}),
|
|
155
162
|
...(declared("setModelContext")
|
|
156
163
|
? { updateModelContext: { text: {}, structuredContent: {} } }
|
|
@@ -183,6 +190,15 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
|
|
|
183
190
|
refuse(request.id, JSON_RPC_ERRORS.internal, `${request.method} failed`);
|
|
184
191
|
return;
|
|
185
192
|
}
|
|
193
|
+
reply(request, outcome, result);
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** Answers a request with a capability's outcome. */
|
|
197
|
+
function reply(
|
|
198
|
+
request: JsonRpcRequest,
|
|
199
|
+
outcome: CallOutcome<unknown>,
|
|
200
|
+
result: (value: unknown) => unknown,
|
|
201
|
+
): void {
|
|
186
202
|
if (outcome.ok) {
|
|
187
203
|
answer(request.id, result(outcome.value));
|
|
188
204
|
} else if (outcome.refusal === "not-declared") {
|
|
@@ -259,10 +275,31 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
|
|
|
259
275
|
invalid("needs a uri");
|
|
260
276
|
return;
|
|
261
277
|
}
|
|
262
|
-
|
|
278
|
+
reply(request, await live.read(params.uri), (value) =>
|
|
263
279
|
isRecord(value) ? value : { contents: [] },
|
|
264
280
|
);
|
|
265
281
|
return;
|
|
282
|
+
case MCP_APPS_METHODS.subscribeResource:
|
|
283
|
+
case MCP_APPS_METHODS.unsubscribeResource:
|
|
284
|
+
if (!bridge.declared("subscribeData")) {
|
|
285
|
+
refuse(
|
|
286
|
+
request.id,
|
|
287
|
+
JSON_RPC_ERRORS.methodNotFound,
|
|
288
|
+
`${request.method} isn't offered here`,
|
|
289
|
+
);
|
|
290
|
+
return;
|
|
291
|
+
}
|
|
292
|
+
if (typeof params.uri !== "string") {
|
|
293
|
+
invalid("needs a uri");
|
|
294
|
+
return;
|
|
295
|
+
}
|
|
296
|
+
if (request.method === MCP_APPS_METHODS.unsubscribeResource) {
|
|
297
|
+
live.unsubscribe(params.uri);
|
|
298
|
+
answer(request.id, {});
|
|
299
|
+
return;
|
|
300
|
+
}
|
|
301
|
+
reply(request, await live.subscribe(params.uri), () => ({}));
|
|
302
|
+
return;
|
|
266
303
|
case MCP_APPS_METHODS.updateModelContext:
|
|
267
304
|
if (
|
|
268
305
|
(params.content !== undefined && !Array.isArray(params.content)) ||
|
|
@@ -404,6 +441,7 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
|
|
|
404
441
|
},
|
|
405
442
|
close() {
|
|
406
443
|
closed = true;
|
|
444
|
+
live.close();
|
|
407
445
|
unlisten();
|
|
408
446
|
queue = [];
|
|
409
447
|
for (const waiting of pending.values()) {
|
package/src/presets/presets.ts
CHANGED
|
@@ -14,7 +14,7 @@ import type {
|
|
|
14
14
|
UrlPermission,
|
|
15
15
|
UrlSandboxExtra,
|
|
16
16
|
} from "../config/schema.ts";
|
|
17
|
-
import { validateConfig } from "../config/validate.ts";
|
|
17
|
+
import { ConfigError, validateConfig } from "../config/validate.ts";
|
|
18
18
|
import { DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES } from "../theme/variables.ts";
|
|
19
19
|
|
|
20
20
|
/**
|
|
@@ -52,6 +52,12 @@ export interface PresetOptions {
|
|
|
52
52
|
readonly errors?: "agent" | "host" | "none";
|
|
53
53
|
}
|
|
54
54
|
|
|
55
|
+
/**
|
|
56
|
+
* The live widget's options (P079): a widget's, less egress, which stays closed (Porthole's own
|
|
57
|
+
* libraries come with domain isolation). A host adds capabilities, or changes the data ones' gates.
|
|
58
|
+
*/
|
|
59
|
+
export type LiveWidgetOptions = Omit<PresetOptions, "egress">;
|
|
60
|
+
|
|
55
61
|
/** The url preset's options: where the app is served, and the embedding page's extra frames. */
|
|
56
62
|
export interface UrlPresetOptions {
|
|
57
63
|
readonly contentOrigins: readonly string[];
|
|
@@ -137,6 +143,9 @@ const mergeEgress = (base: EgressConfig, extra: EgressConfig | undefined): Egres
|
|
|
137
143
|
if (passive.length > 0) {
|
|
138
144
|
merged.anyHttps = passive;
|
|
139
145
|
}
|
|
146
|
+
if (base.libraries === true || extra?.libraries === true) {
|
|
147
|
+
merged.libraries = true;
|
|
148
|
+
}
|
|
140
149
|
return merged;
|
|
141
150
|
};
|
|
142
151
|
|
|
@@ -157,11 +166,16 @@ function themeVariables(
|
|
|
157
166
|
|
|
158
167
|
function build(
|
|
159
168
|
mode: PortholeConfig["mode"],
|
|
160
|
-
defaults: {
|
|
169
|
+
defaults: {
|
|
170
|
+
readonly limits?: Partial<Limits>;
|
|
171
|
+
readonly capabilities?: CapabilityMap;
|
|
172
|
+
readonly egress?: EgressConfig;
|
|
173
|
+
},
|
|
161
174
|
options: PresetOptions,
|
|
162
175
|
): PortholeConfig {
|
|
163
176
|
const capabilities: { -readonly [N in CapabilityName]?: CapabilityConfig } = {
|
|
164
177
|
...BASE_CAPABILITIES,
|
|
178
|
+
...defaults.capabilities,
|
|
165
179
|
};
|
|
166
180
|
if (options.errors === "none") {
|
|
167
181
|
delete capabilities.reportError;
|
|
@@ -180,7 +194,7 @@ function build(
|
|
|
180
194
|
mode,
|
|
181
195
|
isolation: options.isolation ?? "opaque",
|
|
182
196
|
capabilities,
|
|
183
|
-
egress: mergeEgress({}, options.egress),
|
|
197
|
+
egress: mergeEgress(defaults.egress ?? {}, options.egress),
|
|
184
198
|
theme: {
|
|
185
199
|
variables: themeVariables(options.theme?.variables),
|
|
186
200
|
event: options.theme?.event ?? DEFAULT_THEME_EVENT,
|
|
@@ -203,6 +217,35 @@ export const presets = {
|
|
|
203
217
|
*/
|
|
204
218
|
inlineWidget: (options: PresetOptions = {}): PortholeConfig => build("inline", {}, options),
|
|
205
219
|
|
|
220
|
+
/**
|
|
221
|
+
* A widget that shows its host's data, live, and has no network of its own (P079): an inline
|
|
222
|
+
* widget whose egress stays closed (no option opens it). It reads the host's data (`readData`,
|
|
223
|
+
* MCP `resources/read`) and subscribes to it (`subscribeData`, `resources/subscribe`), each
|
|
224
|
+
* behind the viewer's consent (the host's `consent`, asked once per display) and a rate. In
|
|
225
|
+
* domain isolation its scripts load from Porthole's own libraries on its origin
|
|
226
|
+
* (`egress.libraries`: Chart.js, D3), and nowhere else. A host adds what any widget may have (a
|
|
227
|
+
* link, a copy button), or changes the data capabilities' gates.
|
|
228
|
+
*/
|
|
229
|
+
liveWidget: (options: LiveWidgetOptions = {}): PortholeConfig => {
|
|
230
|
+
if ((options as PresetOptions).egress !== undefined) {
|
|
231
|
+
throw new ConfigError(
|
|
232
|
+
"options.egress",
|
|
233
|
+
"a live widget has no network of its own: its egress stays closed (P079)",
|
|
234
|
+
);
|
|
235
|
+
}
|
|
236
|
+
return build(
|
|
237
|
+
"inline",
|
|
238
|
+
{
|
|
239
|
+
capabilities: {
|
|
240
|
+
readData: { gates: ["consent", { rateLimit: { perMinute: 120 } }] },
|
|
241
|
+
subscribeData: { gates: ["consent", { rateLimit: { perMinute: 60 } }] },
|
|
242
|
+
},
|
|
243
|
+
egress: options.isolation === "domain" ? { libraries: true } : {},
|
|
244
|
+
},
|
|
245
|
+
options,
|
|
246
|
+
);
|
|
247
|
+
},
|
|
248
|
+
|
|
206
249
|
/**
|
|
207
250
|
* A whole HTML page: written into an opaque frame by the shell where the host has the page, or
|
|
208
251
|
* served on its own origin (`isolation: "domain"`). A document scrolls inside past a shorter cap.
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import type { CallOutcome, HostFunctionBridge } from "../bridge/types.ts";
|
|
2
|
+
import { STALE_META } from "./mcp-apps.ts";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Live data for one frame (P079), as both adapters speak it (MCP `resources/read`,
|
|
6
|
+
* `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`): the frame's
|
|
7
|
+
* subscriptions by URI, each ended by its controller, and a fresh result the host gave for one
|
|
8
|
+
* (pushed through `changed(result)`, or read after a stale answer), kept for the frame's next read
|
|
9
|
+
* of it. Every call goes through the bridge, which gates it; the adapter only says what to send.
|
|
10
|
+
*/
|
|
11
|
+
export interface LiveData {
|
|
12
|
+
/** A read: a fresh result kept for it, else the host's (its cache first, when subscribed). */
|
|
13
|
+
read(uri: unknown): Promise<CallOutcome<unknown>>;
|
|
14
|
+
/** Starts the host's subscription; a second for a URI is a no-op. */
|
|
15
|
+
subscribe(uri: unknown): Promise<CallOutcome<undefined>>;
|
|
16
|
+
/** Ends one: never gated, it stops what the host was doing for this frame. */
|
|
17
|
+
unsubscribe(uri: unknown): void;
|
|
18
|
+
/** The frame is gone: every subscription ends. */
|
|
19
|
+
close(): void;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** Where MCP results carry their metadata. */
|
|
23
|
+
const META = "_meta";
|
|
24
|
+
|
|
25
|
+
/** A `resources/read` result marked as the host's cached copy (`STALE_META`). */
|
|
26
|
+
export function markedStale(value: unknown): unknown {
|
|
27
|
+
const result =
|
|
28
|
+
value !== null && typeof value === "object" ? (value as Record<string, unknown>) : {};
|
|
29
|
+
const given = result[META];
|
|
30
|
+
const meta =
|
|
31
|
+
given !== null && typeof given === "object" ? (given as Record<string, unknown>) : {};
|
|
32
|
+
return { ...result, [META]: { ...meta, [STALE_META]: true } };
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* `updated(uri)` sends the frame `notifications/resources/updated`; it is called only for a URI
|
|
37
|
+
* the frame subscribes to.
|
|
38
|
+
*/
|
|
39
|
+
export function liveData(
|
|
40
|
+
bridge: HostFunctionBridge,
|
|
41
|
+
updated: (uri: string) => void,
|
|
42
|
+
options: { readonly userActivated?: () => boolean | undefined } = {},
|
|
43
|
+
): LiveData {
|
|
44
|
+
const subscriptions = new Map<string, AbortController>();
|
|
45
|
+
const fresh = new Map<string, unknown>();
|
|
46
|
+
let closed = false;
|
|
47
|
+
const tell = (uri: string) => {
|
|
48
|
+
if (!closed && subscriptions.has(uri)) {
|
|
49
|
+
updated(uri);
|
|
50
|
+
}
|
|
51
|
+
};
|
|
52
|
+
const activation = () => {
|
|
53
|
+
const userActivated = options.userActivated?.();
|
|
54
|
+
return userActivated === undefined ? {} : { userActivated };
|
|
55
|
+
};
|
|
56
|
+
const end = (uri: string) => {
|
|
57
|
+
subscriptions.get(uri)?.abort();
|
|
58
|
+
subscriptions.delete(uri);
|
|
59
|
+
fresh.delete(uri);
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
return {
|
|
63
|
+
async read(uri) {
|
|
64
|
+
if (typeof uri === "string" && fresh.has(uri)) {
|
|
65
|
+
const value = fresh.get(uri);
|
|
66
|
+
fresh.delete(uri);
|
|
67
|
+
return { ok: true, value };
|
|
68
|
+
}
|
|
69
|
+
const subscribed = typeof uri === "string" && subscriptions.has(uri);
|
|
70
|
+
const outcome = await bridge.call(
|
|
71
|
+
"readData",
|
|
72
|
+
{ uri },
|
|
73
|
+
{ ...activation(), stale: subscribed },
|
|
74
|
+
);
|
|
75
|
+
if (!outcome.ok || outcome.stale !== true || typeof uri !== "string") {
|
|
76
|
+
return outcome;
|
|
77
|
+
}
|
|
78
|
+
// Answered from the host's cache: the fresh result, for the frame's next read, is told once
|
|
79
|
+
// it is here.
|
|
80
|
+
void bridge.call("readData", { uri }, activation()).then((next) => {
|
|
81
|
+
if (next.ok && !closed && subscriptions.has(uri)) {
|
|
82
|
+
fresh.set(uri, next.value);
|
|
83
|
+
tell(uri);
|
|
84
|
+
}
|
|
85
|
+
});
|
|
86
|
+
return { ok: true, value: markedStale(outcome.value) };
|
|
87
|
+
},
|
|
88
|
+
|
|
89
|
+
async subscribe(uri) {
|
|
90
|
+
if (typeof uri === "string" && subscriptions.has(uri)) {
|
|
91
|
+
return { ok: true, value: undefined };
|
|
92
|
+
}
|
|
93
|
+
const controller = new AbortController();
|
|
94
|
+
if (typeof uri === "string") {
|
|
95
|
+
subscriptions.set(uri, controller);
|
|
96
|
+
}
|
|
97
|
+
const outcome = await bridge.call(
|
|
98
|
+
"subscribeData",
|
|
99
|
+
{ uri },
|
|
100
|
+
{
|
|
101
|
+
...activation(),
|
|
102
|
+
subscription: {
|
|
103
|
+
signal: controller.signal,
|
|
104
|
+
changed: (result?: unknown) => {
|
|
105
|
+
if (controller.signal.aborted || closed || typeof uri !== "string") {
|
|
106
|
+
return;
|
|
107
|
+
}
|
|
108
|
+
if (result !== undefined) {
|
|
109
|
+
fresh.set(uri, result);
|
|
110
|
+
}
|
|
111
|
+
tell(uri);
|
|
112
|
+
},
|
|
113
|
+
},
|
|
114
|
+
},
|
|
115
|
+
);
|
|
116
|
+
if (!outcome.ok) {
|
|
117
|
+
controller.abort();
|
|
118
|
+
if (typeof uri === "string" && subscriptions.get(uri) === controller) {
|
|
119
|
+
subscriptions.delete(uri);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
return outcome;
|
|
123
|
+
},
|
|
124
|
+
|
|
125
|
+
unsubscribe(uri) {
|
|
126
|
+
if (typeof uri === "string") {
|
|
127
|
+
end(uri);
|
|
128
|
+
}
|
|
129
|
+
},
|
|
130
|
+
|
|
131
|
+
close() {
|
|
132
|
+
closed = true;
|
|
133
|
+
for (const uri of subscriptions.keys()) {
|
|
134
|
+
end(uri);
|
|
135
|
+
}
|
|
136
|
+
},
|
|
137
|
+
};
|
|
138
|
+
}
|
package/src/protocol/mcp-apps.ts
CHANGED
|
@@ -17,6 +17,10 @@ export const MCP_APPS_METHODS = {
|
|
|
17
17
|
updateModelContext: "ui/update-model-context",
|
|
18
18
|
callTool: "tools/call",
|
|
19
19
|
readResource: "resources/read",
|
|
20
|
+
// MCP's own resource subscriptions (P079), which MCP Apps doesn't list: the view is the host's
|
|
21
|
+
// MCP client here, as for resources/read.
|
|
22
|
+
subscribeResource: "resources/subscribe",
|
|
23
|
+
unsubscribeResource: "resources/unsubscribe",
|
|
20
24
|
// View → host notifications.
|
|
21
25
|
initialized: "ui/notifications/initialized",
|
|
22
26
|
sizeChanged: "ui/notifications/size-changed",
|
|
@@ -28,6 +32,7 @@ export const MCP_APPS_METHODS = {
|
|
|
28
32
|
toolResult: "ui/notifications/tool-result",
|
|
29
33
|
toolCancelled: "ui/notifications/tool-cancelled",
|
|
30
34
|
hostContextChanged: "ui/notifications/host-context-changed",
|
|
35
|
+
resourceUpdated: "notifications/resources/updated",
|
|
31
36
|
// Host → view requests.
|
|
32
37
|
resourceTeardown: "ui/resource-teardown",
|
|
33
38
|
// Sandbox proxy (a second origin that relays between host and view).
|
|
@@ -121,6 +126,13 @@ export const PORTHOLE_STYLES = "porthole/styles";
|
|
|
121
126
|
*/
|
|
122
127
|
export const COPY_TEXT_METHOD = "porthole/copy-text";
|
|
123
128
|
|
|
129
|
+
/**
|
|
130
|
+
* The `_meta` key that marks a `resources/read` result as the host's cached copy (P079): stale,
|
|
131
|
+
* with the fresh one to follow as `notifications/resources/updated`. Only for a resource the view
|
|
132
|
+
* subscribes to.
|
|
133
|
+
*/
|
|
134
|
+
export const STALE_META = "porthole/stale";
|
|
135
|
+
|
|
124
136
|
/** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
|
|
125
137
|
export const SHELL_LOGGER = "porthole";
|
|
126
138
|
|
|
@@ -14,6 +14,7 @@ import {
|
|
|
14
14
|
MCP_APPS_PROTOCOL_VERSION,
|
|
15
15
|
type HostContext,
|
|
16
16
|
} from "./mcp-apps.ts";
|
|
17
|
+
import { liveData } from "./live-data.ts";
|
|
17
18
|
|
|
18
19
|
/**
|
|
19
20
|
* The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
|
|
@@ -56,7 +57,6 @@ const REQUESTS: Readonly<
|
|
|
56
57
|
capability: "callTool",
|
|
57
58
|
args: (params) => ({ name: params.name, arguments: params.arguments }),
|
|
58
59
|
},
|
|
59
|
-
[M.readResource]: { capability: "readData", args: (params) => ({ uri: params.uri }) },
|
|
60
60
|
[M.updateModelContext]: {
|
|
61
61
|
capability: "setModelContext",
|
|
62
62
|
args: (params) => ({ content: params.content, structuredContent: params.structuredContent }),
|
|
@@ -102,7 +102,8 @@ export function hostCapabilities(
|
|
|
102
102
|
offered.serverTools = {};
|
|
103
103
|
}
|
|
104
104
|
if (declared("readData")) {
|
|
105
|
-
|
|
105
|
+
// MCP's own flag for resources/subscribe (P079), in the field that mirrors MCP's capability.
|
|
106
|
+
offered.serverResources = declared("subscribeData") ? { subscribe: true } : {};
|
|
106
107
|
}
|
|
107
108
|
if (declared("setModelContext")) {
|
|
108
109
|
offered.updateModelContext = { text: {} };
|
|
@@ -124,7 +125,6 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
124
125
|
let sentWhole = false;
|
|
125
126
|
let nextId = 1;
|
|
126
127
|
const pending = new Map<JsonRpcId, (response: JsonRpcResponse) => void>();
|
|
127
|
-
|
|
128
128
|
const respond = (
|
|
129
129
|
id: JsonRpcId,
|
|
130
130
|
body: { result: unknown } | { error: { code: number; message: string } },
|
|
@@ -132,6 +132,9 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
132
132
|
const notify = (method: string, params: Record<string, unknown>) =>
|
|
133
133
|
transport.send({ jsonrpc: "2.0", method, params });
|
|
134
134
|
|
|
135
|
+
// Live data (P079): reads, subscriptions and the host's updates, through the bridge.
|
|
136
|
+
const live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
|
|
137
|
+
|
|
135
138
|
const flush = () => {
|
|
136
139
|
if (!initialized || closed || content === null || sentWhole) {
|
|
137
140
|
return;
|
|
@@ -168,6 +171,34 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
168
171
|
respond(request.id, { result: { mode: "inline" } });
|
|
169
172
|
return;
|
|
170
173
|
}
|
|
174
|
+
if (request.method === M.readResource) {
|
|
175
|
+
const outcome = await live.read(params.uri);
|
|
176
|
+
if (!closed) {
|
|
177
|
+
respond(request.id, answer("readData", outcome));
|
|
178
|
+
}
|
|
179
|
+
return;
|
|
180
|
+
}
|
|
181
|
+
if (request.method === M.subscribeResource || request.method === M.unsubscribeResource) {
|
|
182
|
+
if (!bridge.declared("subscribeData")) {
|
|
183
|
+
respond(request.id, {
|
|
184
|
+
error: {
|
|
185
|
+
code: JSON_RPC_ERRORS.methodNotFound,
|
|
186
|
+
message: `${request.method} isn't offered here`,
|
|
187
|
+
},
|
|
188
|
+
});
|
|
189
|
+
return;
|
|
190
|
+
}
|
|
191
|
+
if (request.method === M.subscribeResource) {
|
|
192
|
+
const outcome = await live.subscribe(params.uri);
|
|
193
|
+
if (!closed) {
|
|
194
|
+
respond(request.id, outcome.ok ? { result: {} } : answer("subscribeData", outcome));
|
|
195
|
+
}
|
|
196
|
+
} else {
|
|
197
|
+
live.unsubscribe(params.uri);
|
|
198
|
+
respond(request.id, { result: {} });
|
|
199
|
+
}
|
|
200
|
+
return;
|
|
201
|
+
}
|
|
171
202
|
const mapped = REQUESTS[request.method];
|
|
172
203
|
if (mapped === undefined) {
|
|
173
204
|
respond(request.id, {
|
|
@@ -264,6 +295,7 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
264
295
|
closed = true;
|
|
265
296
|
stop();
|
|
266
297
|
pending.clear();
|
|
298
|
+
live.close();
|
|
267
299
|
},
|
|
268
300
|
};
|
|
269
301
|
},
|
package/src/react/dialog.tsx
CHANGED
|
@@ -66,6 +66,8 @@ function words(request: ConfirmRequest): Words {
|
|
|
66
66
|
return { heading: "Share this with the agent?", accept: "Share", detail: json(request.args) };
|
|
67
67
|
case "readData":
|
|
68
68
|
return { heading: "Let it read this?", accept: "Allow", detail: request.args.uri };
|
|
69
|
+
case "subscribeData":
|
|
70
|
+
return { heading: "Let it follow this?", accept: "Allow", detail: request.args.uri };
|
|
69
71
|
case "copyText":
|
|
70
72
|
return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
|
|
71
73
|
default:
|
package/src/react/frame.tsx
CHANGED
|
@@ -22,6 +22,8 @@ import type {
|
|
|
22
22
|
Confirm,
|
|
23
23
|
ConfirmAnswer,
|
|
24
24
|
ConfirmRequest,
|
|
25
|
+
Consent,
|
|
26
|
+
DataCache,
|
|
25
27
|
Proceed,
|
|
26
28
|
Refusal,
|
|
27
29
|
} from "../bridge/types.ts";
|
|
@@ -61,6 +63,9 @@ interface PageState {
|
|
|
61
63
|
/** Heights displays reported, by display id: a frame mounting again starts at its last. */
|
|
62
64
|
readonly heights: Map<string, number>;
|
|
63
65
|
readonly confirm?: Confirm;
|
|
66
|
+
/** The provider's consent and cache (P079), read when a frame asks. */
|
|
67
|
+
readonly consent?: Consent;
|
|
68
|
+
readonly cached?: DataCache;
|
|
64
69
|
readonly hostInfo?: { readonly name: string; readonly version: string };
|
|
65
70
|
readonly nonce?: string;
|
|
66
71
|
/** The provider's locator, read when a frame locates (so an inline one restarts nothing). */
|
|
@@ -120,6 +125,13 @@ export interface PortholeProviderProps {
|
|
|
120
125
|
* Pass your own function to replace it.
|
|
121
126
|
*/
|
|
122
127
|
readonly confirm?: Confirm;
|
|
128
|
+
/**
|
|
129
|
+
* Whether a frame below may make its `consent`-gated calls (read the viewer's data, P079):
|
|
130
|
+
* asked once per display, before the first. Omitted: those calls are refused.
|
|
131
|
+
*/
|
|
132
|
+
readonly consent?: Consent;
|
|
133
|
+
/** What the host last had for a resource, answered stale first (P079). */
|
|
134
|
+
readonly cached?: DataCache;
|
|
123
135
|
/** How the host names itself in the handshake. */
|
|
124
136
|
readonly hostInfo?: { readonly name: string; readonly version: string };
|
|
125
137
|
/** Where domain and external frames load from (see `InstanceLocator`). */
|
|
@@ -185,6 +197,17 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
|
|
|
185
197
|
),
|
|
186
198
|
[],
|
|
187
199
|
);
|
|
200
|
+
// The host's consent and cache as of the last render (P079), read when a frame asks.
|
|
201
|
+
const ownConsent = useRef(props.consent);
|
|
202
|
+
const ownCached = useRef(props.cached);
|
|
203
|
+
useLayoutEffect(() => {
|
|
204
|
+
ownConsent.current = props.consent;
|
|
205
|
+
ownCached.current = props.cached;
|
|
206
|
+
});
|
|
207
|
+
const consent = useCallback<Consent>((request) => ownConsent.current?.(request) ?? false, []);
|
|
208
|
+
const cached = useCallback<DataCache>((args, context) => ownCached.current?.(args, context), []);
|
|
209
|
+
const consents = props.consent !== undefined;
|
|
210
|
+
const caches = props.cached !== undefined;
|
|
188
211
|
// The default copyText: the host's page writes the clipboard (in the frame's click, which
|
|
189
212
|
// activated this page too) and shows the person what went on it, or offers to copy it.
|
|
190
213
|
const [notice, setNotice] = useState<CopyNotice | null>(null);
|
|
@@ -260,6 +283,8 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
|
|
|
260
283
|
heights,
|
|
261
284
|
confirm,
|
|
262
285
|
copyText,
|
|
286
|
+
...(consents ? { consent } : {}),
|
|
287
|
+
...(caches ? { cached } : {}),
|
|
263
288
|
...(hostInfo === undefined ? {} : { hostInfo }),
|
|
264
289
|
...(locates ? { locate } : {}),
|
|
265
290
|
...(nonce === undefined ? {} : { nonce }),
|
|
@@ -274,6 +299,10 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
|
|
|
274
299
|
heights,
|
|
275
300
|
confirm,
|
|
276
301
|
copyText,
|
|
302
|
+
consents,
|
|
303
|
+
consent,
|
|
304
|
+
caches,
|
|
305
|
+
cached,
|
|
277
306
|
hostInfo,
|
|
278
307
|
locates,
|
|
279
308
|
locate,
|
|
@@ -372,6 +401,10 @@ export interface PortholeFrameProps {
|
|
|
372
401
|
readonly handlers?: CapabilityHandlers;
|
|
373
402
|
/** Who confirms this frame's gated calls, over the provider's. */
|
|
374
403
|
readonly confirm?: Confirm;
|
|
404
|
+
/** Whether this frame may make its `consent`-gated calls, over the provider's (P079). */
|
|
405
|
+
readonly consent?: Consent;
|
|
406
|
+
/** This frame's data cache, over the provider's (P079). */
|
|
407
|
+
readonly cached?: DataCache;
|
|
375
408
|
/** Bump to run the content again from the start. */
|
|
376
409
|
readonly generation?: number;
|
|
377
410
|
/** Run at once, without waiting to near the screen (it still counts toward the page's most). */
|
|
@@ -620,6 +653,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
620
653
|
handlers: pageHandlers,
|
|
621
654
|
copyText: pageCopyText,
|
|
622
655
|
confirm: pageConfirm,
|
|
656
|
+
consent: pageConsent,
|
|
657
|
+
cached: pageCached,
|
|
623
658
|
hostInfo,
|
|
624
659
|
locate,
|
|
625
660
|
nonce,
|
|
@@ -710,6 +745,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
710
745
|
}
|
|
711
746
|
}
|
|
712
747
|
const asks = first.confirm !== undefined || pageConfirm !== undefined;
|
|
748
|
+
const asksConsent = first.consent !== undefined || pageConsent !== undefined;
|
|
749
|
+
const caches = first.cached !== undefined || pageCached !== undefined;
|
|
713
750
|
let display: DisplayHandle;
|
|
714
751
|
try {
|
|
715
752
|
display = createHost(config, {
|
|
@@ -730,6 +767,21 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
730
767
|
),
|
|
731
768
|
}
|
|
732
769
|
: {}),
|
|
770
|
+
...(asksConsent
|
|
771
|
+
? {
|
|
772
|
+
consent: (request: ConfirmRequest) =>
|
|
773
|
+
(latest().consent ?? pageConsent ?? (() => false))({
|
|
774
|
+
...request,
|
|
775
|
+
display: { ...request.display, id: latest().displayId, title: latest().title },
|
|
776
|
+
}),
|
|
777
|
+
}
|
|
778
|
+
: {}),
|
|
779
|
+
...(caches
|
|
780
|
+
? {
|
|
781
|
+
cached: (args: { readonly uri: string }, context: CallContext) =>
|
|
782
|
+
(latest().cached ?? pageCached)?.(args, named(context)),
|
|
783
|
+
}
|
|
784
|
+
: {}),
|
|
733
785
|
theme: (each) => (latest().theme ?? latestPage().theme)?.(each) ?? {},
|
|
734
786
|
...(hostInfo === undefined ? {} : { hostInfo }),
|
|
735
787
|
...(locate === undefined ? {} : { locator: { locate } }),
|
|
@@ -785,6 +837,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
785
837
|
pageHandlers,
|
|
786
838
|
pageCopyText,
|
|
787
839
|
pageConfirm,
|
|
840
|
+
pageConsent,
|
|
841
|
+
pageCached,
|
|
788
842
|
hostInfo,
|
|
789
843
|
locate,
|
|
790
844
|
nonce,
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { LIBRARY_FILES } from "../libraries/files.generated.ts";
|
|
2
|
+
import { LIBRARY_PATH } from "../libraries/libraries.ts";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Porthole's vendored libraries (P079), as every content origin serves them under `LIBRARY_PATH`:
|
|
6
|
+
* fixed files, the same for everyone, so no ticket or cookie is asked for and they may be cached
|
|
7
|
+
* for good (a path's bytes never change). Same-site only: content origins load them, no one else.
|
|
8
|
+
* Null for any other path (the reserved prefix's 404 answers it).
|
|
9
|
+
*/
|
|
10
|
+
export function libraryFile(pathname: string, method: string): Response | null {
|
|
11
|
+
if (!pathname.startsWith(LIBRARY_PATH) || (method !== "GET" && method !== "HEAD")) {
|
|
12
|
+
return null;
|
|
13
|
+
}
|
|
14
|
+
const body = Object.hasOwn(LIBRARY_FILES, pathname) ? LIBRARY_FILES[pathname] : undefined;
|
|
15
|
+
if (body === undefined) {
|
|
16
|
+
return null;
|
|
17
|
+
}
|
|
18
|
+
return new Response(method === "HEAD" ? null : body, {
|
|
19
|
+
headers: {
|
|
20
|
+
"content-type": pathname.endsWith(".js")
|
|
21
|
+
? "text/javascript; charset=utf-8"
|
|
22
|
+
: "text/plain; charset=utf-8",
|
|
23
|
+
"cache-control": "public, max-age=31536000, immutable",
|
|
24
|
+
"cross-origin-resource-policy": "same-site",
|
|
25
|
+
"x-content-type-options": "nosniff",
|
|
26
|
+
},
|
|
27
|
+
});
|
|
28
|
+
}
|
package/src/server/server.ts
CHANGED
|
@@ -12,6 +12,7 @@ import { base32, createKeys, newTicket, ticketId } from "./keys.ts";
|
|
|
12
12
|
import { randomBytes } from "./crypto.ts";
|
|
13
13
|
import { isHostLabel, reservedLabels } from "./naming.ts";
|
|
14
14
|
import { enterPage, pageScript, SESSION_PATH, statusPage } from "./pages.ts";
|
|
15
|
+
import { libraryFile } from "./libraries.ts";
|
|
15
16
|
import type { FrameBlock } from "../host/types.ts";
|
|
16
17
|
import { memoryTicketStore } from "./tickets.ts";
|
|
17
18
|
import type {
|
|
@@ -1156,7 +1157,7 @@ export function createServer(options: ServerOptions): PortholeServer {
|
|
|
1156
1157
|
if (url.pathname === ENTRY_PATH && authorizeUrl !== null) {
|
|
1157
1158
|
return await redeem(request, url, label);
|
|
1158
1159
|
}
|
|
1159
|
-
const script = pageScript(url.pathname);
|
|
1160
|
+
const script = pageScript(url.pathname) ?? libraryFile(url.pathname, method);
|
|
1160
1161
|
if (script !== null) {
|
|
1161
1162
|
return script;
|
|
1162
1163
|
}
|