@botiverse/porthole 0.6.0 → 0.8.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 +25 -2
- package/THIRD_PARTY_NOTICES.md +421 -0
- package/dist/bridge/bounded-text.d.ts +34 -0
- package/dist/bridge/bounded-text.js +188 -0
- package/dist/bridge/bridge.d.ts +38 -5
- package/dist/bridge/bridge.js +469 -39
- package/dist/bridge/json-data.d.ts +28 -0
- package/dist/bridge/json-data.js +86 -0
- package/dist/bridge/navigation.d.ts +5 -0
- package/dist/bridge/navigation.js +7 -0
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +17 -0
- package/dist/bridge/types.d.ts +73 -5
- package/dist/check/check.d.ts +7 -0
- package/dist/check/check.js +1 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +4 -2
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +16 -0
- package/dist/check/tools.js +2 -3
- package/dist/compile/compile.d.ts +6 -0
- package/dist/compile/compile.js +3 -1
- package/dist/compile/policy.d.ts +55 -0
- package/dist/compile/policy.js +157 -0
- package/dist/config/capabilities.d.ts +85 -7
- package/dist/config/capabilities.js +32 -2
- package/dist/config/schema.d.ts +35 -0
- package/dist/config/validate.d.ts +9 -3
- package/dist/config/validate.js +92 -8
- package/dist/config/warnings.d.ts +20 -0
- package/dist/config/warnings.js +25 -0
- package/dist/conformance/behavior.js +46 -1
- package/dist/conformance/cookies.d.ts +15 -0
- package/dist/conformance/cookies.js +80 -0
- package/dist/conformance/harness/page.d.ts +1 -0
- package/dist/conformance/harness/page.js +9 -2
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/host-kit.js +5 -1
- package/dist/conformance/index.d.ts +11 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/limits.js +38 -1
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +324 -0
- package/dist/conformance/served.d.ts +2 -0
- package/dist/conformance/served.js +737 -4
- package/dist/files/paths.js +4 -0
- package/dist/guide/gates.d.ts +9 -0
- package/dist/guide/gates.js +31 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +35 -33
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +210 -0
- package/dist/host/create-host.js +73 -37
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/pages-of-set.d.ts +43 -0
- package/dist/host/pages-of-set.js +196 -0
- package/dist/host/types.d.ts +26 -1
- package/dist/index.d.ts +11 -4
- package/dist/index.js +11 -2
- package/dist/isolation/types.d.ts +8 -0
- package/dist/mcp/adapter.js +11 -15
- package/dist/node/index.d.ts +36 -4
- package/dist/node/index.js +402 -101
- package/dist/presets/presets.d.ts +22 -8
- package/dist/presets/presets.js +40 -8
- package/dist/protocol/live-data.d.ts +6 -2
- package/dist/protocol/live-data.js +20 -1
- package/dist/protocol/mcp-apps.d.ts +13 -2
- package/dist/protocol/mcp-apps.js +10 -2
- package/dist/protocol/message-text.d.ts +8 -0
- package/dist/protocol/message-text.js +29 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +116 -0
- package/dist/protocol/shell-adapter.js +64 -25
- package/dist/react/context-notice.d.ts +32 -0
- package/dist/react/context-notice.js +28 -0
- package/dist/react/dialog.js +91 -16
- package/dist/react/frame.d.ts +25 -1
- package/dist/react/frame.js +85 -2
- package/dist/react/index.d.ts +2 -1
- package/dist/react/index.js +2 -1
- package/dist/runtime/contract.d.ts +201 -0
- package/dist/runtime/contract.js +245 -0
- package/dist/runtime/db.d.ts +188 -0
- package/dist/runtime/db.js +502 -0
- package/dist/runtime/declaration.d.ts +100 -0
- package/dist/runtime/declaration.js +363 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +215 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +19 -1
- package/dist/server/files.js +115 -6
- package/dist/server/host.d.ts +24 -2
- package/dist/server/host.js +137 -2
- package/dist/server/index.d.ts +3 -2
- package/dist/server/index.js +2 -1
- package/dist/server/peer.d.ts +4 -0
- package/dist/server/peer.js +19 -0
- package/dist/server/proxy.d.ts +6 -0
- package/dist/server/proxy.js +12 -3
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +318 -52
- package/dist/server/types.d.ts +74 -2
- package/dist/shell/document.d.ts +16 -0
- package/dist/shell/document.js +19 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.js +390 -56
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +205 -15
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +1867 -11
- package/docs/DESIGN.md +137 -17
- package/docs/THREAT_MODEL.md +616 -0
- package/package.json +16 -3
- package/src/bridge/bounded-text.ts +240 -0
- package/src/bridge/bridge.ts +601 -51
- package/src/bridge/json-data.ts +95 -0
- package/src/bridge/navigation.ts +10 -0
- package/src/bridge/refusal.ts +17 -0
- package/src/bridge/types.ts +76 -5
- package/src/check/check.ts +8 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +4 -2
- package/src/check/page.ts +16 -0
- package/src/check/tools.ts +2 -3
- package/src/compile/compile.ts +9 -1
- package/src/compile/policy.ts +177 -0
- package/src/config/capabilities.ts +71 -5
- package/src/config/schema.ts +35 -0
- package/src/config/validate.ts +141 -8
- package/src/config/warnings.ts +42 -0
- package/src/conformance/behavior.ts +54 -1
- package/src/conformance/cookies.ts +93 -0
- package/src/conformance/harness/page.ts +11 -2
- package/src/conformance/host-kit.ts +10 -1
- package/src/conformance/index.ts +17 -0
- package/src/conformance/limits.ts +39 -1
- package/src/conformance/runtime.ts +594 -0
- package/src/conformance/served.ts +888 -4
- package/src/files/paths.ts +4 -0
- package/src/guide/gates.ts +37 -0
- package/src/guide/guide.ts +61 -55
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +253 -0
- package/src/host/create-host.ts +88 -36
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/pages-of-set.ts +226 -0
- package/src/host/types.ts +33 -1
- package/src/index.ts +94 -0
- package/src/isolation/types.ts +8 -0
- package/src/mcp/adapter.ts +16 -20
- package/src/node/index.ts +507 -116
- package/src/presets/presets.ts +67 -17
- package/src/protocol/live-data.ts +31 -3
- package/src/protocol/mcp-apps.ts +11 -2
- package/src/protocol/message-text.ts +36 -0
- package/src/protocol/runtime-calls.ts +141 -0
- package/src/protocol/shell-adapter.ts +79 -26
- package/src/react/context-notice.tsx +95 -0
- package/src/react/dialog.tsx +108 -15
- package/src/react/frame.tsx +120 -0
- package/src/react/index.ts +8 -1
- package/src/runtime/contract.ts +339 -0
- package/src/runtime/db.ts +650 -0
- package/src/runtime/declaration.ts +516 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +355 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +138 -7
- package/src/server/host.ts +170 -3
- package/src/server/index.ts +4 -0
- package/src/server/peer.ts +21 -0
- package/src/server/proxy.ts +13 -3
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +370 -57
- package/src/server/types.ts +73 -2
- package/src/shell/document.ts +29 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +390 -56
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +27 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
package/src/presets/presets.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { RuntimeVersion } from "../runtime/contract.ts";
|
|
1
2
|
import type { CapabilityName } from "../config/capabilities.ts";
|
|
2
3
|
import type {
|
|
3
4
|
CapabilityConfig,
|
|
@@ -50,13 +51,24 @@ export interface PresetOptions {
|
|
|
50
51
|
readonly storage?: StorageConfig;
|
|
51
52
|
/** Where the content's errors go (`PortholeConfig.errors`); `none` drops `reportError`. */
|
|
52
53
|
readonly errors?: "agent" | "host" | "none";
|
|
54
|
+
/**
|
|
55
|
+
* The capability runtime (P085): content reaches capabilities through `porthole.use`, and may
|
|
56
|
+
* be offered the runtime's own (`user`, `comments`, `artifact`, `assets`, `db`).
|
|
57
|
+
*/
|
|
58
|
+
readonly runtime?: RuntimeVersion;
|
|
53
59
|
}
|
|
54
60
|
|
|
61
|
+
/** What a live widget may say about a capability (P103): anything but origins of its own. */
|
|
62
|
+
export type LiveCapabilityConfig = Omit<CapabilityConfig, "connect" | "resource">;
|
|
63
|
+
|
|
55
64
|
/**
|
|
56
65
|
* The live widget's options (P079): a widget's, less egress, which stays closed (Porthole's own
|
|
57
|
-
* libraries come with domain isolation)
|
|
66
|
+
* libraries come with domain isolation), and less a capability's own origins, which are egress
|
|
67
|
+
* too (P103). A host adds capabilities, or changes the data ones' gates.
|
|
58
68
|
*/
|
|
59
|
-
export type LiveWidgetOptions = Omit<PresetOptions, "egress"
|
|
69
|
+
export type LiveWidgetOptions = Omit<PresetOptions, "egress" | "capabilities"> & {
|
|
70
|
+
readonly capabilities?: { readonly [N in CapabilityName]?: LiveCapabilityConfig | false };
|
|
71
|
+
};
|
|
60
72
|
|
|
61
73
|
/** The url preset's options: where the app is served, and the embedding page's extra frames. */
|
|
62
74
|
export interface UrlPresetOptions {
|
|
@@ -149,6 +161,27 @@ const mergeEgress = (base: EgressConfig, extra: EgressConfig | undefined): Egres
|
|
|
149
161
|
return merged;
|
|
150
162
|
};
|
|
151
163
|
|
|
164
|
+
/**
|
|
165
|
+
* A frozen copy of a config's data, all the way down (P103): what a host passed in stays its own
|
|
166
|
+
* and mutable; the copy can't be written into (a capability's `connect`, an egress origin).
|
|
167
|
+
*/
|
|
168
|
+
function frozenCopy<T>(value: T): T {
|
|
169
|
+
if (Array.isArray(value)) {
|
|
170
|
+
return Object.freeze(value.map((each: unknown) => frozenCopy(each))) as T;
|
|
171
|
+
}
|
|
172
|
+
if (value !== null && typeof value === "object") {
|
|
173
|
+
const prototype: unknown = Object.getPrototypeOf(value);
|
|
174
|
+
if (prototype === Object.prototype || prototype === null) {
|
|
175
|
+
const copy: Record<string, unknown> = {};
|
|
176
|
+
for (const [key, each] of Object.entries(value)) {
|
|
177
|
+
copy[key] = frozenCopy(each);
|
|
178
|
+
}
|
|
179
|
+
return Object.freeze(copy) as T;
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
return value;
|
|
183
|
+
}
|
|
184
|
+
|
|
152
185
|
/** The default variables, with the host's changes and additions, less those it dropped (null). */
|
|
153
186
|
function themeVariables(
|
|
154
187
|
changes: Readonly<Record<string, ThemeValue | null>> | undefined,
|
|
@@ -207,6 +240,7 @@ function build(
|
|
|
207
240
|
embedder: options.embedder ?? {},
|
|
208
241
|
...(options.storage === undefined ? {} : { storage: options.storage }),
|
|
209
242
|
...(options.errors === undefined ? {} : { errors: options.errors }),
|
|
243
|
+
...(options.runtime === undefined ? {} : { runtime: options.runtime }),
|
|
210
244
|
});
|
|
211
245
|
}
|
|
212
246
|
|
|
@@ -219,12 +253,13 @@ export const presets = {
|
|
|
219
253
|
|
|
220
254
|
/**
|
|
221
255
|
* 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
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
*
|
|
226
|
-
* (`egress.libraries`: Chart.js, D3),
|
|
227
|
-
* link, a copy button), or changes the
|
|
256
|
+
* widget whose egress stays closed (no option opens it: neither `egress` nor a capability's own
|
|
257
|
+
* `connect` or `resource`, P103). It reads the host's data (`readData`, MCP `resources/read`)
|
|
258
|
+
* and subscribes to it (`subscribeData`, `resources/subscribe`), each behind the viewer's
|
|
259
|
+
* consent (the host's `consent`, asked once per display) and a rate. In domain isolation its
|
|
260
|
+
* scripts load from Porthole's own libraries on its origin (`egress.libraries`: Chart.js, D3),
|
|
261
|
+
* and nowhere else. A host adds what any widget may have (a link, a copy button), or changes the
|
|
262
|
+
* data capabilities' gates.
|
|
228
263
|
*/
|
|
229
264
|
liveWidget: (options: LiveWidgetOptions = {}): PortholeConfig => {
|
|
230
265
|
if ((options as PresetOptions).egress !== undefined) {
|
|
@@ -233,16 +268,31 @@ export const presets = {
|
|
|
233
268
|
"a live widget has no network of its own: its egress stays closed (P079)",
|
|
234
269
|
);
|
|
235
270
|
}
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
{
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
271
|
+
// A capability's own origins join the CSP as egress does (P103): none for a live widget.
|
|
272
|
+
for (const [name, value] of Object.entries((options as PresetOptions).capabilities ?? {})) {
|
|
273
|
+
for (const field of ["connect", "resource"] as const) {
|
|
274
|
+
if (typeof value === "object" && value !== null && value[field] !== undefined) {
|
|
275
|
+
throw new ConfigError(
|
|
276
|
+
`options.capabilities.${name}.${field}`,
|
|
277
|
+
"a live widget has no network of its own: no capability opens origins for it (P079, P103)",
|
|
278
|
+
);
|
|
279
|
+
}
|
|
280
|
+
}
|
|
281
|
+
}
|
|
282
|
+
// Frozen, all the way down (P103): nothing writes an origin into the preset's config after it
|
|
283
|
+
// is made. A config a host builds from it (a spread) is the host's own, not this preset.
|
|
284
|
+
return frozenCopy(
|
|
285
|
+
build(
|
|
286
|
+
"inline",
|
|
287
|
+
{
|
|
288
|
+
capabilities: {
|
|
289
|
+
readData: { gates: ["consent", { rateLimit: { perMinute: 120 } }] },
|
|
290
|
+
subscribeData: { gates: ["consent", { rateLimit: { perMinute: 60 } }] },
|
|
291
|
+
},
|
|
292
|
+
egress: options.isolation === "domain" ? { libraries: true } : {},
|
|
242
293
|
},
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
options,
|
|
294
|
+
options,
|
|
295
|
+
),
|
|
246
296
|
);
|
|
247
297
|
},
|
|
248
298
|
|
|
@@ -6,10 +6,14 @@ import { STALE_META } from "./mcp-apps.ts";
|
|
|
6
6
|
* `resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`): the frame's
|
|
7
7
|
* subscriptions by URI, each ended by its controller, and a fresh result the host gave for one
|
|
8
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
|
|
9
|
+
* of it. Every call goes through the bridge, which gates it, a read answered by a kept result too
|
|
10
|
+
* (P094); the adapter only says what to send.
|
|
10
11
|
*/
|
|
11
12
|
export interface LiveData {
|
|
12
|
-
/**
|
|
13
|
+
/**
|
|
14
|
+
* A read, past the read's gates whatever answers it: a fresh result kept for it, else the
|
|
15
|
+
* host's (its cache first, when subscribed).
|
|
16
|
+
*/
|
|
13
17
|
read(uri: unknown): Promise<CallOutcome<unknown>>;
|
|
14
18
|
/** Starts the host's subscription; a second for a URI is a no-op. */
|
|
15
19
|
subscribe(uri: unknown): Promise<CallOutcome<undefined>>;
|
|
@@ -19,6 +23,12 @@ export interface LiveData {
|
|
|
19
23
|
close(): void;
|
|
20
24
|
}
|
|
21
25
|
|
|
26
|
+
/**
|
|
27
|
+
* The most resources one frame follows at once (P095), as the runtime's watches (50): past it a
|
|
28
|
+
* subscription is refused as too large, and the host isn't asked.
|
|
29
|
+
*/
|
|
30
|
+
const MAX_SUBSCRIPTIONS = 50;
|
|
31
|
+
|
|
22
32
|
/** Where MCP results carry their metadata. */
|
|
23
33
|
const META = "_meta";
|
|
24
34
|
|
|
@@ -62,9 +72,20 @@ export function liveData(
|
|
|
62
72
|
return {
|
|
63
73
|
async read(uri) {
|
|
64
74
|
if (typeof uri === "string" && fresh.has(uri)) {
|
|
75
|
+
// A kept result is the host's answer to a read: it goes through the read's gates as any
|
|
76
|
+
// read does (level, names, rate, gesture, consent, confirm), with no new upstream call
|
|
77
|
+
// (P094). Used once; kept again if the gates refused it and nothing newer came.
|
|
65
78
|
const value = fresh.get(uri);
|
|
66
79
|
fresh.delete(uri);
|
|
67
|
-
|
|
80
|
+
const outcome = await bridge.call(
|
|
81
|
+
"readData",
|
|
82
|
+
{ uri },
|
|
83
|
+
{ ...activation(), held: { uri, value } },
|
|
84
|
+
);
|
|
85
|
+
if (!outcome.ok && !closed && subscriptions.has(uri) && !fresh.has(uri)) {
|
|
86
|
+
fresh.set(uri, value);
|
|
87
|
+
}
|
|
88
|
+
return outcome;
|
|
68
89
|
}
|
|
69
90
|
const subscribed = typeof uri === "string" && subscriptions.has(uri);
|
|
70
91
|
const outcome = await bridge.call(
|
|
@@ -90,6 +111,13 @@ export function liveData(
|
|
|
90
111
|
if (typeof uri === "string" && subscriptions.has(uri)) {
|
|
91
112
|
return { ok: true, value: undefined };
|
|
92
113
|
}
|
|
114
|
+
if (subscriptions.size >= MAX_SUBSCRIPTIONS) {
|
|
115
|
+
return {
|
|
116
|
+
ok: false,
|
|
117
|
+
refusal: "too-large",
|
|
118
|
+
reason: { code: "too_large", message: "Too many things followed at once." },
|
|
119
|
+
};
|
|
120
|
+
}
|
|
93
121
|
const controller = new AbortController();
|
|
94
122
|
if (typeof uri === "string") {
|
|
95
123
|
subscriptions.set(uri, controller);
|
package/src/protocol/mcp-apps.ts
CHANGED
|
@@ -42,6 +42,13 @@ export const MCP_APPS_METHODS = {
|
|
|
42
42
|
|
|
43
43
|
export type McpAppsMethod = (typeof MCP_APPS_METHODS)[keyof typeof MCP_APPS_METHODS];
|
|
44
44
|
|
|
45
|
+
/**
|
|
46
|
+
* What a host that declares `setModelContext` says it takes (`hostCapabilities.updateModelContext`),
|
|
47
|
+
* in both adapters: text blocks and structured content, exactly what the bridge accepts and the
|
|
48
|
+
* person is shown (P100). Images and other blocks aren't offered, and are refused.
|
|
49
|
+
*/
|
|
50
|
+
export const MODEL_CONTEXT_OFFERED = { text: {}, structuredContent: {} } as const;
|
|
51
|
+
|
|
45
52
|
/**
|
|
46
53
|
* What the shell's `tool-input(-partial)` carries: the content to draw. Porthole's own argument
|
|
47
54
|
* names, since the shell is the only view that reads them.
|
|
@@ -142,8 +149,10 @@ export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
|
|
|
142
149
|
|
|
143
150
|
/**
|
|
144
151
|
* Porthole's own notification from the shell (P084): a page that came with files is opening
|
|
145
|
-
* another page of its set, `{ url }`, in the frame
|
|
146
|
-
*
|
|
152
|
+
* another page of its set, `{ url }`, in the frame; and, as it arrives, the page a navigation
|
|
153
|
+
* opened says so, `{ url, arrived: true }` (P098). The host takes the frame's next load (or the
|
|
154
|
+
* load it came after, within `LATE_NOTICE_MS`) for that page rather than for content that left
|
|
155
|
+
* (P031). The content's word: it only spares a restart.
|
|
147
156
|
*/
|
|
148
157
|
export const NAVIGATING_METHOD = "porthole/navigating";
|
|
149
158
|
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/** The most content blocks a message's text is read from: more is no message a person sends. */
|
|
2
|
+
const MAX_BLOCKS = 1_000;
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The text of a `ui/message`'s content blocks, the adapters' one reading of it: its text blocks'
|
|
6
|
+
* text, in order, joined by `separator`; null where there is none, or more blocks than a message
|
|
7
|
+
* holds. Read before any gate, so only as far as `max` characters (S05's class, P095: structured
|
|
8
|
+
* clone delivers a sparse array of any length, or one block shared a million times, for the cost
|
|
9
|
+
* of one): past it, `max + 1` characters, which the bridge refuses as too long.
|
|
10
|
+
*/
|
|
11
|
+
export function messageText(
|
|
12
|
+
blocks: readonly unknown[],
|
|
13
|
+
separator: string,
|
|
14
|
+
max: number,
|
|
15
|
+
): string | null {
|
|
16
|
+
if (blocks.length > MAX_BLOCKS) {
|
|
17
|
+
return null;
|
|
18
|
+
}
|
|
19
|
+
let text: string | null = null;
|
|
20
|
+
for (let index = 0; index < blocks.length; index += 1) {
|
|
21
|
+
const block = blocks[index] as { type?: unknown; text?: unknown } | null | undefined;
|
|
22
|
+
if (
|
|
23
|
+
block !== null &&
|
|
24
|
+
typeof block === "object" &&
|
|
25
|
+
!Array.isArray(block) &&
|
|
26
|
+
block.type === "text" &&
|
|
27
|
+
typeof block.text === "string"
|
|
28
|
+
) {
|
|
29
|
+
text = text === null ? block.text : `${text}${separator}${block.text}`;
|
|
30
|
+
if (text.length > max) {
|
|
31
|
+
return text.slice(0, max + 1);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
return text;
|
|
36
|
+
}
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
import type { CallOutcome, HostFunctionBridge } from "../bridge/types.ts";
|
|
2
|
+
import { reasonFor, type RefusalReason } from "../bridge/refusal.ts";
|
|
3
|
+
import type { CapabilityName } from "../config/capabilities.ts";
|
|
4
|
+
import {
|
|
5
|
+
RUNTIME_CAPABILITIES,
|
|
6
|
+
RUNTIME_EVENT_METHOD,
|
|
7
|
+
isRuntimeCapabilityName,
|
|
8
|
+
type RuntimeMethod,
|
|
9
|
+
} from "../runtime/contract.ts";
|
|
10
|
+
import { DB_LIMITS } from "../runtime/db.ts";
|
|
11
|
+
import { downloadContents } from "../runtime/requests.ts";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* The host side of the capability runtime's calls (P085): `porthole/call` with `{ capability,
|
|
15
|
+
* method, args }` (and `watch`, a frame-chosen id, for a subscription), each turned into the host
|
|
16
|
+
* function that serves it and passed through the bridge, which alone decides; `porthole/unwatch`
|
|
17
|
+
* ends a watch. A watch's updates go to the frame as `porthole/event` with `{ watch, data }`.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
const isRecord = (value: unknown): value is Record<string, unknown> =>
|
|
21
|
+
value !== null && typeof value === "object" && !Array.isArray(value);
|
|
22
|
+
|
|
23
|
+
/** A runtime call as the host function that serves it gets it, or null for none. */
|
|
24
|
+
export function runtimeCall(
|
|
25
|
+
capability: unknown,
|
|
26
|
+
method: unknown,
|
|
27
|
+
args: unknown,
|
|
28
|
+
): { readonly serves: CapabilityName; readonly args: unknown; readonly watch: boolean } | null {
|
|
29
|
+
if (!isRuntimeCapabilityName(capability) || typeof method !== "string") {
|
|
30
|
+
return null;
|
|
31
|
+
}
|
|
32
|
+
const methods: Readonly<Record<string, RuntimeMethod>> = RUNTIME_CAPABILITIES[capability].methods;
|
|
33
|
+
const spec = Object.hasOwn(methods, method) ? methods[method] : undefined;
|
|
34
|
+
// `data.subscribe` is MCP's own subscription (resources/subscribe, P079), not a runtime call.
|
|
35
|
+
if (spec === undefined || spec.serves === "subscribeData") {
|
|
36
|
+
return null;
|
|
37
|
+
}
|
|
38
|
+
const given = isRecord(args) ? args : {};
|
|
39
|
+
const watch = spec.watch === true;
|
|
40
|
+
switch (spec.serves) {
|
|
41
|
+
case "downloadFile":
|
|
42
|
+
return {
|
|
43
|
+
serves: spec.serves,
|
|
44
|
+
args: { contents: downloadContents(given.file) ?? undefined },
|
|
45
|
+
watch,
|
|
46
|
+
};
|
|
47
|
+
case "callTool":
|
|
48
|
+
return { serves: spec.serves, args: { name: given.name, arguments: given.arguments }, watch };
|
|
49
|
+
case "readData":
|
|
50
|
+
return { serves: spec.serves, args: { uri: given.uri }, watch };
|
|
51
|
+
case "artifact":
|
|
52
|
+
case "assets":
|
|
53
|
+
case "db":
|
|
54
|
+
// One host function serves several methods: the method is its `op`.
|
|
55
|
+
return { serves: spec.serves, args: { ...given, op: method }, watch };
|
|
56
|
+
default:
|
|
57
|
+
return { serves: spec.serves, args: given, watch };
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
type Answer =
|
|
62
|
+
| { readonly result: unknown }
|
|
63
|
+
| { readonly error: { code: number; message: string; data?: RefusalReason } };
|
|
64
|
+
|
|
65
|
+
/** A runtime call's outcome, as the frame hears it: its value, or why it was refused (P080). */
|
|
66
|
+
export function runtimeAnswer(serves: CapabilityName, outcome: CallOutcome<unknown>): Answer {
|
|
67
|
+
if (!outcome.ok) {
|
|
68
|
+
return {
|
|
69
|
+
error: {
|
|
70
|
+
code: -32000,
|
|
71
|
+
message: `Refused (${outcome.refusal})`,
|
|
72
|
+
data: reasonFor(serves, outcome),
|
|
73
|
+
},
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
return { result: { value: outcome.value ?? null } };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const refused = (reason: RefusalReason): Answer => ({
|
|
80
|
+
error: { code: -32000, message: `Refused (${reason.code})`, data: reason },
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
/** One frame's runtime calls: its watches, and their end. */
|
|
84
|
+
export function runtimeCalls(
|
|
85
|
+
bridge: HostFunctionBridge,
|
|
86
|
+
notify: (method: string, params: Record<string, unknown>) => void,
|
|
87
|
+
) {
|
|
88
|
+
const watches = new Map<string, AbortController>();
|
|
89
|
+
return {
|
|
90
|
+
async call(params: Record<string, unknown>): Promise<Answer> {
|
|
91
|
+
const mapped = runtimeCall(params.capability, params.method, params.args);
|
|
92
|
+
if (mapped === null) {
|
|
93
|
+
return refused({ code: "not_allowed", message: "This isn't available here." });
|
|
94
|
+
}
|
|
95
|
+
if (!mapped.watch) {
|
|
96
|
+
return runtimeAnswer(mapped.serves, await bridge.call(mapped.serves, mapped.args));
|
|
97
|
+
}
|
|
98
|
+
const id = params.watch;
|
|
99
|
+
if (typeof id !== "string" || !/^[\w-]{1,64}$/u.test(id) || watches.has(id)) {
|
|
100
|
+
return refused({ code: "not_allowed", message: "The app can't take this request." });
|
|
101
|
+
}
|
|
102
|
+
if (watches.size >= DB_LIMITS.maxWatches) {
|
|
103
|
+
return refused({ code: "too_large", message: "Too many things followed at once." });
|
|
104
|
+
}
|
|
105
|
+
const controller = new AbortController();
|
|
106
|
+
watches.set(id, controller);
|
|
107
|
+
const outcome = await bridge.call(mapped.serves, mapped.args, {
|
|
108
|
+
subscription: {
|
|
109
|
+
// Each update is the watch's answer, gated as its read when it started (P091, P094):
|
|
110
|
+
// nothing that check read changes while it lives (the frame's viewer and declaration,
|
|
111
|
+
// the display's kept consent), and a new page or frame ends it. So no gate per update.
|
|
112
|
+
changed: (data?: unknown) => {
|
|
113
|
+
if (!controller.signal.aborted) {
|
|
114
|
+
notify(RUNTIME_EVENT_METHOD, { watch: id, data: data ?? null });
|
|
115
|
+
}
|
|
116
|
+
},
|
|
117
|
+
signal: controller.signal,
|
|
118
|
+
},
|
|
119
|
+
});
|
|
120
|
+
if (!outcome.ok) {
|
|
121
|
+
controller.abort();
|
|
122
|
+
watches.delete(id);
|
|
123
|
+
}
|
|
124
|
+
return outcome.ok ? { result: { value: null } } : runtimeAnswer(mapped.serves, outcome);
|
|
125
|
+
},
|
|
126
|
+
/** The frame stopped following (never gated). */
|
|
127
|
+
unwatch(params: Record<string, unknown>): void {
|
|
128
|
+
const id = params.watch;
|
|
129
|
+
if (typeof id === "string") {
|
|
130
|
+
watches.get(id)?.abort();
|
|
131
|
+
watches.delete(id);
|
|
132
|
+
}
|
|
133
|
+
},
|
|
134
|
+
close(): void {
|
|
135
|
+
for (const controller of watches.values()) {
|
|
136
|
+
controller.abort();
|
|
137
|
+
}
|
|
138
|
+
watches.clear();
|
|
139
|
+
},
|
|
140
|
+
};
|
|
141
|
+
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { CapabilityName } from "../config/capabilities.ts";
|
|
2
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
3
|
import type { CallOutcome } from "../bridge/types.ts";
|
|
3
4
|
import type { AdapterSession, ProtocolAdapter, ShellConnection } from "./adapter.ts";
|
|
4
5
|
import {
|
|
@@ -15,9 +16,17 @@ import {
|
|
|
15
16
|
NAVIGATION_BLOCKED_METHOD,
|
|
16
17
|
MCP_APPS_METHODS as M,
|
|
17
18
|
MCP_APPS_PROTOCOL_VERSION,
|
|
19
|
+
MODEL_CONTEXT_OFFERED,
|
|
18
20
|
type HostContext,
|
|
19
21
|
} from "./mcp-apps.ts";
|
|
20
22
|
import { liveData } from "./live-data.ts";
|
|
23
|
+
import { messageText } from "./message-text.ts";
|
|
24
|
+
import { runtimeCalls } from "./runtime-calls.ts";
|
|
25
|
+
import {
|
|
26
|
+
RUNTIME_CALL_METHOD,
|
|
27
|
+
RUNTIME_EXPERIMENTAL_KEY,
|
|
28
|
+
RUNTIME_UNWATCH_METHOD,
|
|
29
|
+
} from "../runtime/contract.ts";
|
|
21
30
|
|
|
22
31
|
/**
|
|
23
32
|
* The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
|
|
@@ -28,25 +37,24 @@ import { liveData } from "./live-data.ts";
|
|
|
28
37
|
|
|
29
38
|
const LOG_ERRORS = new Set(["error", "critical", "alert", "emergency"]);
|
|
30
39
|
|
|
31
|
-
/**
|
|
40
|
+
/**
|
|
41
|
+
* Requests that are capability calls, and how their params become the capability's args: shallow,
|
|
42
|
+
* or bounded (`messageText`), since they run before any gate (S05's class, P095).
|
|
43
|
+
*/
|
|
32
44
|
const REQUESTS: Readonly<
|
|
33
|
-
Record<
|
|
45
|
+
Record<
|
|
46
|
+
string,
|
|
47
|
+
{
|
|
48
|
+
capability: CapabilityName;
|
|
49
|
+
args: (params: Record<string, unknown>, config: PortholeConfig) => unknown;
|
|
50
|
+
}
|
|
51
|
+
>
|
|
34
52
|
> = {
|
|
35
53
|
[M.message]: {
|
|
36
54
|
capability: "sendPrompt",
|
|
37
|
-
args: (params) => ({
|
|
55
|
+
args: (params, config) => ({
|
|
38
56
|
text: Array.isArray(params.content)
|
|
39
|
-
? params.content
|
|
40
|
-
.map((part: unknown) => {
|
|
41
|
-
const block = part as { type?: unknown; text?: unknown } | null;
|
|
42
|
-
return block !== null &&
|
|
43
|
-
typeof block === "object" &&
|
|
44
|
-
block.type === "text" &&
|
|
45
|
-
typeof block.text === "string"
|
|
46
|
-
? block.text
|
|
47
|
-
: "";
|
|
48
|
-
})
|
|
49
|
-
.join("")
|
|
57
|
+
? (messageText(params.content, "", config.limits.maxPromptChars) ?? "")
|
|
50
58
|
: undefined,
|
|
51
59
|
}),
|
|
52
60
|
},
|
|
@@ -116,7 +124,7 @@ export function hostCapabilities(
|
|
|
116
124
|
offered.serverResources = declared("subscribeData") ? { subscribe: true } : {};
|
|
117
125
|
}
|
|
118
126
|
if (declared("setModelContext")) {
|
|
119
|
-
offered.updateModelContext =
|
|
127
|
+
offered.updateModelContext = MODEL_CONTEXT_OFFERED;
|
|
120
128
|
}
|
|
121
129
|
if (declared("reportError")) {
|
|
122
130
|
offered.logging = {};
|
|
@@ -143,7 +151,20 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
143
151
|
transport.send({ jsonrpc: "2.0", method, params });
|
|
144
152
|
|
|
145
153
|
// Live data (P079): reads, subscriptions and the host's updates, through the bridge.
|
|
146
|
-
|
|
154
|
+
let live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
|
|
155
|
+
// The capability runtime (P085), where the config has one: its calls and watches.
|
|
156
|
+
const runtime = session.compiled.config.runtime;
|
|
157
|
+
let calls = runtimeCalls(bridge, notify);
|
|
158
|
+
// A new page on the same transport (another of the set's pages, P084; or a reload that says
|
|
159
|
+
// hello again) starts with nothing followed: the last page's watches and subscriptions end,
|
|
160
|
+
// so it never hears their updates or their refusals (after the review).
|
|
161
|
+
let greeted = false;
|
|
162
|
+
const forget = () => {
|
|
163
|
+
calls.close();
|
|
164
|
+
calls = runtimeCalls(bridge, notify);
|
|
165
|
+
live.close();
|
|
166
|
+
live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
|
|
167
|
+
};
|
|
147
168
|
|
|
148
169
|
const flush = () => {
|
|
149
170
|
if (!initialized || closed || content === null || sentWhole) {
|
|
@@ -163,11 +184,28 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
163
184
|
const onRequest = async (request: JsonRpcRequest) => {
|
|
164
185
|
const params = request.params ?? {};
|
|
165
186
|
if (request.method === M.initialize) {
|
|
187
|
+
if (greeted) {
|
|
188
|
+
forget();
|
|
189
|
+
}
|
|
190
|
+
greeted = true;
|
|
166
191
|
respond(request.id, {
|
|
167
192
|
result: {
|
|
168
193
|
protocolVersion: MCP_APPS_PROTOCOL_VERSION,
|
|
169
194
|
hostInfo: session.hostInfo,
|
|
170
|
-
hostCapabilities:
|
|
195
|
+
hostCapabilities: {
|
|
196
|
+
...hostCapabilities((name) => bridge.declared(name)),
|
|
197
|
+
// What this display's page may `use`, in MCP Apps' extension point (P085).
|
|
198
|
+
...(runtime === undefined
|
|
199
|
+
? {}
|
|
200
|
+
: {
|
|
201
|
+
experimental: {
|
|
202
|
+
[RUNTIME_EXPERIMENTAL_KEY]: {
|
|
203
|
+
version: runtime,
|
|
204
|
+
capabilities: bridge.roster(),
|
|
205
|
+
},
|
|
206
|
+
},
|
|
207
|
+
}),
|
|
208
|
+
},
|
|
171
209
|
hostContext: session.hostContext(),
|
|
172
210
|
},
|
|
173
211
|
});
|
|
@@ -209,7 +247,15 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
209
247
|
}
|
|
210
248
|
return;
|
|
211
249
|
}
|
|
212
|
-
|
|
250
|
+
if (request.method === RUNTIME_CALL_METHOD && runtime !== undefined) {
|
|
251
|
+
const answered = await calls.call(params);
|
|
252
|
+
if (!closed) {
|
|
253
|
+
respond(request.id, answered);
|
|
254
|
+
}
|
|
255
|
+
return;
|
|
256
|
+
}
|
|
257
|
+
// Its own entries only: `constructor` or `toString` is no request (S05's class, P095).
|
|
258
|
+
const mapped = Object.hasOwn(REQUESTS, request.method) ? REQUESTS[request.method] : undefined;
|
|
213
259
|
if (mapped === undefined) {
|
|
214
260
|
respond(request.id, {
|
|
215
261
|
error: {
|
|
@@ -219,7 +265,10 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
219
265
|
});
|
|
220
266
|
return;
|
|
221
267
|
}
|
|
222
|
-
const outcome = await bridge.call(
|
|
268
|
+
const outcome = await bridge.call(
|
|
269
|
+
mapped.capability,
|
|
270
|
+
mapped.args(params, session.compiled.config),
|
|
271
|
+
);
|
|
223
272
|
if (!closed) {
|
|
224
273
|
respond(request.id, answer(mapped.capability, outcome));
|
|
225
274
|
}
|
|
@@ -238,20 +287,23 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
238
287
|
void bridge.call("resize", { height: params.height, width: params.width });
|
|
239
288
|
return;
|
|
240
289
|
case M.log:
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
typeof data === "string" ? data : JSON.stringify(data ?? null).slice(0, 2_000),
|
|
246
|
-
});
|
|
290
|
+
// What content said, as it came (S05, P095): the bridge reads it only within
|
|
291
|
+
// reportError's declaration and rate, into bounded text, and nothing in it throws here.
|
|
292
|
+
if (typeof params.level === "string" && LOG_ERRORS.has(params.level)) {
|
|
293
|
+
void bridge.call("reportError", { message: params.data });
|
|
247
294
|
}
|
|
248
295
|
return;
|
|
249
296
|
case NAVIGATION_BLOCKED_METHOD:
|
|
250
297
|
// The shell stopped a navigation (P080): an error report, with its address.
|
|
251
298
|
void bridge.call("reportError", { navigationBlocked: params.url });
|
|
252
299
|
return;
|
|
300
|
+
case RUNTIME_UNWATCH_METHOD:
|
|
301
|
+
calls.unwatch(params);
|
|
302
|
+
return;
|
|
253
303
|
case NAVIGATING_METHOD:
|
|
254
|
-
// Another page of the set opens in the frame (P084): its next load is that page
|
|
304
|
+
// Another page of the set opens in the frame (P084): its next load is that page, which
|
|
305
|
+
// follows nothing yet.
|
|
306
|
+
forget();
|
|
255
307
|
session.emit({ type: "navigating" });
|
|
256
308
|
return;
|
|
257
309
|
case M.requestTeardown:
|
|
@@ -314,6 +366,7 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
|
|
|
314
366
|
stop();
|
|
315
367
|
pending.clear();
|
|
316
368
|
live.close();
|
|
369
|
+
calls.close();
|
|
317
370
|
},
|
|
318
371
|
};
|
|
319
372
|
},
|