@botiverse/porthole 0.5.0 → 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/dist/bridge/bridge.d.ts +12 -4
- package/dist/bridge/bridge.js +58 -26
- 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 +7 -0
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +5 -0
- package/dist/config/capabilities.d.ts +5 -0
- package/dist/conformance/harness-source.js +1 -1
- package/dist/guide/guide.js +14 -4
- package/dist/host/create-host.js +15 -4
- package/dist/host/types.d.ts +15 -2
- package/dist/index.d.ts +2 -1
- package/dist/index.js +3 -1
- package/dist/mcp/adapter.js +22 -7
- package/dist/protocol/mcp-apps.d.ts +6 -0
- package/dist/protocol/mcp-apps.js +6 -0
- package/dist/protocol/shell-adapter.js +14 -2
- package/dist/react/frame.d.ts +19 -4
- package/dist/react/frame.js +37 -9
- package/dist/shell/runtime.js +34 -8
- package/docs/ADOPTING.md +39 -9
- package/docs/DECISIONS.md +92 -0
- package/docs/DESIGN.md +12 -7
- package/package.json +1 -1
- package/src/bridge/bridge.ts +70 -22
- package/src/bridge/navigation.ts +34 -0
- package/src/bridge/refusal.ts +151 -0
- package/src/bridge/types.ts +12 -1
- package/src/check/page.ts +7 -0
- package/src/config/capabilities.ts +5 -1
- package/src/guide/guide.ts +18 -4
- package/src/host/create-host.ts +16 -4
- package/src/host/types.ts +13 -2
- package/src/index.ts +9 -0
- package/src/mcp/adapter.ts +26 -6
- package/src/protocol/mcp-apps.ts +7 -0
- package/src/protocol/shell-adapter.ts +15 -2
- package/src/react/frame.tsx +53 -14
- package/src/shell/runtime.ts +34 -8
package/dist/guide/guide.js
CHANGED
|
@@ -218,7 +218,7 @@ function chart(c) {
|
|
|
218
218
|
function gateWords(gates, effect) {
|
|
219
219
|
const sentences = [];
|
|
220
220
|
if (gates.includes("consent")) {
|
|
221
|
-
sentences.push("The first data call asks the person to allow it; if they don't, every one fails (show that the data isn't allowed, not an error).");
|
|
221
|
+
sentences.push("The first data call asks the person to allow it; if they don't, every one fails with code denied (show that the data isn't allowed, not an error).");
|
|
222
222
|
}
|
|
223
223
|
if (gates.includes("confirm")) {
|
|
224
224
|
sentences.push(`The app shows the person ${effect} first, and nothing happens unless they confirm.`);
|
|
@@ -233,6 +233,16 @@ function gateWords(gates, effect) {
|
|
|
233
233
|
}
|
|
234
234
|
return sentences.join(" ");
|
|
235
235
|
}
|
|
236
|
+
/**
|
|
237
|
+
* What a data refusal tells content (P080): the codes and the sentence, for the author to draw. With
|
|
238
|
+
* the shell's globals they are the error's own fields; without, the JSON-RPC error's data.
|
|
239
|
+
*/
|
|
240
|
+
function refusalWords(c, global) {
|
|
241
|
+
const where = global
|
|
242
|
+
? "The error's code says why"
|
|
243
|
+
: "A refusal is an error whose data is { code, message }; code says why";
|
|
244
|
+
return `${where}: consent_required (not allowed yet), denied (the person said no), rate_limited, not_allowed (not here: some places show the ${c.noun} without data) or failed; ${global ? "its" : ""} message is a sentence for the person. Draw the ${c.noun} without that data, with that sentence where it would be; don't retry in a loop.`.replace(/ {2,}/gu, " ");
|
|
245
|
+
}
|
|
236
246
|
const ENTRIES = {
|
|
237
247
|
sendPrompt: (c, gates) => c.global("sendPrompt")
|
|
238
248
|
? `- sendPrompt(text): asks to send text to you as the person's message (at most ${c.config.limits.maxPromptChars.toLocaleString("en-US")} characters). Use it for "explain this point", "try these settings". ${gateWords(gates, "the whole text")} It returns a promise: true if it was sent.`
|
|
@@ -243,10 +253,10 @@ const ENTRIES = {
|
|
|
243
253
|
downloadFile: (_c, gates) => `- Downloads: the MCP Apps request ui/download-file (with the App SDK, app.downloadFile). ${gateWords(gates, "the file")}`,
|
|
244
254
|
callTool: (_c, gates) => `- Tools: the MCP Apps request tools/call (with the App SDK, app.callServerTool). ${gateWords(gates, "the call")}`,
|
|
245
255
|
readData: (c, gates) => c.global("readData")
|
|
246
|
-
? `- readData(uri): reads the app's data at uri (a resource the app names), as the person viewing the ${c.noun} may see it, and returns a promise of it: JSON parsed, else text. ${gateWords(gates, "the request")} It rejects when the app refuses or fails
|
|
247
|
-
: `- Data: the MCP Apps request resources/read (with the App SDK, app.readServerResource). ${gateWords(gates, "the request")}`,
|
|
256
|
+
? `- readData(uri): reads the app's data at uri (a resource the app names), as the person viewing the ${c.noun} may see it, and returns a promise of it: JSON parsed, else text. ${gateWords(gates, "the request")} It rejects when the app refuses or fails. ${refusalWords(c, true)}`
|
|
257
|
+
: `- Data: the MCP Apps request resources/read (with the App SDK, app.readServerResource). ${gateWords(gates, "the request")} ${refusalWords(c, false)}`,
|
|
248
258
|
subscribeData: (c, gates) => c.global("subscribeData")
|
|
249
|
-
? `- subscribeData(uri, onData, onError): keeps the ${c.noun} current. It calls onData(value, { stale }) with the data at uri now, and again each time it changes; the first value may be the app's last copy (stale: true), with the current one right after. It returns a function that stops it. onError(error) hears a refusal. ${gateWords(gates, "the request")} Draw from onData every time; don't poll.`
|
|
259
|
+
? `- subscribeData(uri, onData, onError): keeps the ${c.noun} current. It calls onData(value, { stale }) with the data at uri now, and again each time it changes; the first value may be the app's last copy (stale: true), with the current one right after. It returns a function that stops it. onError(error) hears a refusal, with the same code and message as readData's. ${gateWords(gates, "the request")} Draw from onData every time; don't poll.`
|
|
250
260
|
: `- Live data: the MCP request resources/subscribe with { uri }; the app then sends notifications/resources/updated with { uri } each time it changes: read it again (resources/read). resources/unsubscribe stops it. ${gateWords(gates, "the request")}`,
|
|
251
261
|
setModelContext: (_c, gates) => `- Context for the agent: the MCP Apps request ui/update-model-context (with the App SDK, app.updateModelContext). ${gateWords(gates, "it")}`,
|
|
252
262
|
copyText: (c, gates) => c.global("copyText")
|
package/dist/host/create-host.js
CHANGED
|
@@ -2,7 +2,8 @@ import { ANNOTATE_METHODS, } from "../annotate/types.js";
|
|
|
2
2
|
import { annotateMode, checkMarks, parseReport } from "../annotate/validate.js";
|
|
3
3
|
import { createBridge, onceConsent } from "../bridge/bridge.js";
|
|
4
4
|
import { compile } from "../compile/compile.js";
|
|
5
|
-
import { declaredCapabilities } from "../compile/policy.js";
|
|
5
|
+
import { declaredCapabilities, effectiveGates } from "../compile/policy.js";
|
|
6
|
+
import { isRefused } from "../bridge/refusal.js";
|
|
6
7
|
import { capabilitySpec } from "../config/capabilities.js";
|
|
7
8
|
import { locateServed } from "./locate.js";
|
|
8
9
|
import { watchOutcome } from "./outcome.js";
|
|
@@ -43,8 +44,12 @@ export function createHost(config, options = {}) {
|
|
|
43
44
|
compiled,
|
|
44
45
|
mount(container, mount) {
|
|
45
46
|
const handlers = { ...options.handlers, ...mount.handlers };
|
|
47
|
+
// A host whose consent is a Refused refuses every consent-gated call before its handler:
|
|
48
|
+
// those need none (P080).
|
|
49
|
+
const refusesAll = isRefused(options.consent);
|
|
46
50
|
const missing = declaredCapabilities(config).filter((name) => capabilitySpec(name).served === "handler" &&
|
|
47
|
-
handlers[name] === undefined
|
|
51
|
+
handlers[name] === undefined &&
|
|
52
|
+
!(refusesAll && effectiveGates(config, name).includes("consent")));
|
|
48
53
|
if (missing.length > 0) {
|
|
49
54
|
throw new TypeError(`No handler for the declared capabilities: ${missing.join(", ")}`);
|
|
50
55
|
}
|
|
@@ -76,8 +81,11 @@ export function createHost(config, options = {}) {
|
|
|
76
81
|
let destroyed = false;
|
|
77
82
|
let restarts = 0;
|
|
78
83
|
let generation = 0;
|
|
79
|
-
// The viewer's answer for this display (P079): asked once, kept across its frames
|
|
80
|
-
|
|
84
|
+
// The viewer's answer for this display (P079): asked once, kept across its frames; or the
|
|
85
|
+
// host's refusal of them all (P080).
|
|
86
|
+
const consent = options.consent === undefined || isRefused(options.consent)
|
|
87
|
+
? options.consent
|
|
88
|
+
: onceConsent(options.consent);
|
|
81
89
|
let abort = null;
|
|
82
90
|
let outcomeWatch = null;
|
|
83
91
|
let themeFrame = null;
|
|
@@ -241,6 +249,9 @@ export function createHost(config, options = {}) {
|
|
|
241
249
|
});
|
|
242
250
|
return;
|
|
243
251
|
}
|
|
252
|
+
case "navigationBlocked":
|
|
253
|
+
emit("navigationBlocked", { url: event.url });
|
|
254
|
+
return;
|
|
244
255
|
case "error":
|
|
245
256
|
contentError(event.message);
|
|
246
257
|
return;
|
package/dist/host/types.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
|
|
2
|
+
import type { Refused } from "../bridge/refusal.ts";
|
|
2
3
|
import type { Confirm, CapabilityHandlers, Consent, DataCache, Refusal } from "../bridge/types.ts";
|
|
3
4
|
import type { CompiledConfig } from "../compile/compile.ts";
|
|
4
5
|
import type { CapabilityName } from "../config/capabilities.ts";
|
|
@@ -20,9 +21,11 @@ export interface HostOptions<C extends AdapterConnection = ShellConnection> {
|
|
|
20
21
|
/**
|
|
21
22
|
* Whether a display may make its `consent`-gated calls (read the viewer's data, P079): asked
|
|
22
23
|
* once per display, before the first, and kept for the display's life (its reloads too).
|
|
23
|
-
* Absent: those calls are refused.
|
|
24
|
+
* Absent: those calls are refused. A `Refused` instead of a function refuses every one with its
|
|
25
|
+
* reason, asking nothing, and those capabilities need no handler (a page where live data must
|
|
26
|
+
* not run, P080).
|
|
24
27
|
*/
|
|
25
|
-
readonly consent?: Consent;
|
|
28
|
+
readonly consent?: Consent | Refused;
|
|
26
29
|
/**
|
|
27
30
|
* What the host last had for a resource (P079): a read of one the content subscribes to is
|
|
28
31
|
* answered with it at once, marked stale, then with the handler's fresh result.
|
|
@@ -160,6 +163,16 @@ export interface DisplayEvents {
|
|
|
160
163
|
};
|
|
161
164
|
/** The content navigated its frame away; the frame was started again from its content. */
|
|
162
165
|
readonly navigated: undefined;
|
|
166
|
+
/**
|
|
167
|
+
* The shell stopped the content navigating its frame to `url` (P079, P080): the address whole,
|
|
168
|
+
* as the content gave it (its word: untrusted, may carry data in its query). Only where the
|
|
169
|
+
* config declares `reportError` (it counts as one of the run's reports), and only in frames with
|
|
170
|
+
* an origin of their own (served): an opaque frame's navigations get no events. A
|
|
171
|
+
* `contentError` follows, naming the address without its query or fragment.
|
|
172
|
+
*/
|
|
173
|
+
readonly navigationBlocked: {
|
|
174
|
+
readonly url: string;
|
|
175
|
+
};
|
|
163
176
|
/** A call didn't run. */
|
|
164
177
|
readonly refused: {
|
|
165
178
|
readonly capability: CapabilityName;
|
package/dist/index.d.ts
CHANGED
|
@@ -22,7 +22,8 @@ export type { FrameLocation, FrameSource, InstanceLocator, InstanceRef, ServedDo
|
|
|
22
22
|
export type { PlatformHost, Surface, SurfaceSpec } from "./platform/types.ts";
|
|
23
23
|
export type { Transport } from "./transport/types.ts";
|
|
24
24
|
export type { AdapterConnection, AdapterEvent, AdapterSession, ProtocolAdapter, ShellConnection, } from "./protocol/adapter.ts";
|
|
25
|
-
export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, STALE_META, type HostContext, } from "./protocol/mcp-apps.ts";
|
|
25
|
+
export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, NAVIGATION_BLOCKED_METHOD, PORTHOLE_STYLES, STALE_META, type HostContext, } from "./protocol/mcp-apps.ts";
|
|
26
|
+
export { REFUSAL_CODES, Refused, isRefused, type RefusalCode, type RefusalReason, } from "./bridge/refusal.ts";
|
|
26
27
|
export type { CallContext, CallOptions, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmDisplay, ConfirmRequest, Consent, DataCache, Proceed, HostFunctionBridge, Refusal, SubscriptionContext, } from "./bridge/types.ts";
|
|
27
28
|
export { createHost } from "./host/create-host.ts";
|
|
28
29
|
export { entryTarget, frameFallback, portholeClient, type ContentClientMeta, type FrameFallback, type PortholeClient, type PortholeClientOptions, } from "./host/client.ts";
|
package/dist/index.js
CHANGED
|
@@ -20,7 +20,9 @@ export { generateGuide, generateToolDescription, } from "./guide/guide.js";
|
|
|
20
20
|
export { GUIDE_EXAMPLES } from "./guide/examples.js";
|
|
21
21
|
// Theme.
|
|
22
22
|
export { CHART_PALETTE, DEFAULT_THEME, DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES, resolveTheme, themeDefault, } from "./theme/variables.js";
|
|
23
|
-
export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, STALE_META, } from "./protocol/mcp-apps.js";
|
|
23
|
+
export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, NAVIGATION_BLOCKED_METHOD, PORTHOLE_STYLES, STALE_META, } from "./protocol/mcp-apps.js";
|
|
24
|
+
// Why a call was refused, as content is told it, and the host's own refusals (P080).
|
|
25
|
+
export { REFUSAL_CODES, Refused, isRefused, } from "./bridge/refusal.js";
|
|
24
26
|
export { createHost } from "./host/create-host.js";
|
|
25
27
|
// The client half of the host kit, and the display registry (P072).
|
|
26
28
|
export { entryTarget, frameFallback, portholeClient, } from "./host/client.js";
|
package/dist/mcp/adapter.js
CHANGED
|
@@ -1,8 +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
5
|
import { liveData } from "../protocol/live-data.js";
|
|
6
|
+
import { reasonFor } from "../bridge/refusal.js";
|
|
6
7
|
const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
7
8
|
/** Levels of `notifications/message` that are errors: they go to the host as `reportError`. */
|
|
8
9
|
const ERROR_LEVELS = new Set(["error", "critical", "alert", "emergency"]);
|
|
@@ -111,10 +112,10 @@ function connect(session, options) {
|
|
|
111
112
|
refuse(request.id, JSON_RPC_ERRORS.internal, `${request.method} failed`);
|
|
112
113
|
return;
|
|
113
114
|
}
|
|
114
|
-
reply(request, outcome, result);
|
|
115
|
+
reply(request, capability, outcome, result);
|
|
115
116
|
}
|
|
116
117
|
/** Answers a request with a capability's outcome. */
|
|
117
|
-
function reply(request, outcome, result) {
|
|
118
|
+
function reply(request, capability, outcome, result) {
|
|
118
119
|
if (outcome.ok) {
|
|
119
120
|
answer(request.id, result(outcome.value));
|
|
120
121
|
}
|
|
@@ -122,8 +123,17 @@ function connect(session, options) {
|
|
|
122
123
|
refuse(request.id, JSON_RPC_ERRORS.methodNotFound, `${request.method} isn't offered here`);
|
|
123
124
|
}
|
|
124
125
|
else {
|
|
125
|
-
// The spec's "implementation-defined" error for a refused request
|
|
126
|
-
|
|
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
|
+
});
|
|
127
137
|
}
|
|
128
138
|
}
|
|
129
139
|
/** `{}` when a host function did it, `{ isError: true }` when it said it couldn't. */
|
|
@@ -179,7 +189,7 @@ function connect(session, options) {
|
|
|
179
189
|
invalid("needs a uri");
|
|
180
190
|
return;
|
|
181
191
|
}
|
|
182
|
-
reply(request, await live.read(params.uri), (value) => isRecord(value) ? value : { contents: [] });
|
|
192
|
+
reply(request, "readData", await live.read(params.uri), (value) => isRecord(value) ? value : { contents: [] });
|
|
183
193
|
return;
|
|
184
194
|
case MCP_APPS_METHODS.subscribeResource:
|
|
185
195
|
case MCP_APPS_METHODS.unsubscribeResource:
|
|
@@ -196,7 +206,7 @@ function connect(session, options) {
|
|
|
196
206
|
answer(request.id, {});
|
|
197
207
|
return;
|
|
198
208
|
}
|
|
199
|
-
reply(request, await live.subscribe(params.uri), () => ({}));
|
|
209
|
+
reply(request, "subscribeData", await live.subscribe(params.uri), () => ({}));
|
|
200
210
|
return;
|
|
201
211
|
case MCP_APPS_METHODS.updateModelContext:
|
|
202
212
|
if ((params.content !== undefined && !Array.isArray(params.content)) ||
|
|
@@ -274,6 +284,11 @@ function connect(session, options) {
|
|
|
274
284
|
});
|
|
275
285
|
}
|
|
276
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;
|
|
277
292
|
case MCP_APPS_METHODS.requestTeardown:
|
|
278
293
|
session.emit({ type: "teardown-requested" });
|
|
279
294
|
return;
|
|
@@ -61,6 +61,12 @@ export declare const COPY_TEXT_METHOD = "porthole/copy-text";
|
|
|
61
61
|
* subscribes to.
|
|
62
62
|
*/
|
|
63
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";
|
|
64
70
|
/** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
|
|
65
71
|
export declare const SHELL_LOGGER = "porthole";
|
|
66
72
|
/**
|
|
@@ -111,5 +111,11 @@ export const COPY_TEXT_METHOD = "porthole/copy-text";
|
|
|
111
111
|
* subscribes to.
|
|
112
112
|
*/
|
|
113
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";
|
|
114
120
|
/** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
|
|
115
121
|
export const SHELL_LOGGER = "porthole";
|
|
@@ -1,5 +1,6 @@
|
|
|
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";
|
|
3
4
|
import { liveData } from "./live-data.js";
|
|
4
5
|
/**
|
|
5
6
|
* The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
|
|
@@ -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 } };
|
|
@@ -200,6 +208,10 @@ export const shellAdapter = {
|
|
|
200
208
|
});
|
|
201
209
|
}
|
|
202
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;
|
|
203
215
|
case M.requestTeardown:
|
|
204
216
|
session.emit({ type: "teardown-requested" });
|
|
205
217
|
return;
|
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
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";
|
|
@@ -25,6 +26,8 @@ interface PageState {
|
|
|
25
26
|
readonly confirm?: Confirm;
|
|
26
27
|
/** The provider's consent and cache (P079), read when a frame asks. */
|
|
27
28
|
readonly consent?: Consent;
|
|
29
|
+
/** The provider's consent is a `Refused` (P080): its reason, by value. */
|
|
30
|
+
readonly refusesAll?: RefusalReason;
|
|
28
31
|
readonly cached?: DataCache;
|
|
29
32
|
readonly hostInfo?: {
|
|
30
33
|
readonly name: string;
|
|
@@ -82,9 +85,10 @@ export interface PortholeProviderProps {
|
|
|
82
85
|
readonly confirm?: Confirm;
|
|
83
86
|
/**
|
|
84
87
|
* Whether a frame below may make its `consent`-gated calls (read the viewer's data, P079):
|
|
85
|
-
* asked once per display, before the first. Omitted: those calls are refused.
|
|
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).
|
|
86
90
|
*/
|
|
87
|
-
readonly consent?: Consent;
|
|
91
|
+
readonly consent?: Consent | Refused;
|
|
88
92
|
/** What the host last had for a resource, answered stale first (P079). */
|
|
89
93
|
readonly cached?: DataCache;
|
|
90
94
|
/** How the host names itself in the handshake. */
|
|
@@ -149,8 +153,11 @@ export interface PortholeFrameProps {
|
|
|
149
153
|
readonly handlers?: CapabilityHandlers;
|
|
150
154
|
/** Who confirms this frame's gated calls, over the provider's. */
|
|
151
155
|
readonly confirm?: Confirm;
|
|
152
|
-
/**
|
|
153
|
-
|
|
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;
|
|
154
161
|
/** This frame's data cache, over the provider's (P079). */
|
|
155
162
|
readonly cached?: DataCache;
|
|
156
163
|
/** Bump to run the content again from the start. */
|
|
@@ -187,6 +194,14 @@ export interface PortholeFrameProps {
|
|
|
187
194
|
readonly onError?: (message: string, source: "content" | "host") => void;
|
|
188
195
|
/** The content navigated its frame away; it was started again (or stopped, after a few). */
|
|
189
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;
|
|
190
205
|
readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
|
|
191
206
|
/** Too many declines: the display stops asking until it runs again. */
|
|
192
207
|
readonly onMuted?: () => void;
|
package/dist/react/frame.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
2
2
|
import { createContext, useCallback, useContext, useEffect, useEffectEvent, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
|
|
3
|
+
import { isRefused, reasonOf, Refused } from "../bridge/refusal.js";
|
|
3
4
|
import { writeClipboard } from "../host/clipboard.js";
|
|
4
5
|
import { createHost } from "../host/create-host.js";
|
|
5
6
|
import { ConfirmDialog } from "./dialog.js";
|
|
@@ -52,7 +53,15 @@ export function PortholeProvider(props) {
|
|
|
52
53
|
ownConsent.current = props.consent;
|
|
53
54
|
ownCached.current = props.cached;
|
|
54
55
|
});
|
|
55
|
-
const consent = useCallback((request) =>
|
|
56
|
+
const consent = useCallback((request) => {
|
|
57
|
+
const given = ownConsent.current;
|
|
58
|
+
if (isRefused(given)) {
|
|
59
|
+
throw given;
|
|
60
|
+
}
|
|
61
|
+
return given?.(request) ?? false;
|
|
62
|
+
}, []);
|
|
63
|
+
// A Refused for every frame below, by value (an inline one starts nothing again).
|
|
64
|
+
const refusesAll = useByValue(isRefused(props.consent) ? reasonOf(props.consent) : undefined);
|
|
56
65
|
const cached = useCallback((args, context) => ownCached.current?.(args, context), []);
|
|
57
66
|
const consents = props.consent !== undefined;
|
|
58
67
|
const caches = props.cached !== undefined;
|
|
@@ -123,6 +132,7 @@ export function PortholeProvider(props) {
|
|
|
123
132
|
confirm,
|
|
124
133
|
copyText,
|
|
125
134
|
...(consents ? { consent } : {}),
|
|
135
|
+
...(refusesAll === undefined ? {} : { refusesAll }),
|
|
126
136
|
...(caches ? { cached } : {}),
|
|
127
137
|
...(hostInfo === undefined ? {} : { hostInfo }),
|
|
128
138
|
...(locates ? { locate } : {}),
|
|
@@ -139,6 +149,7 @@ export function PortholeProvider(props) {
|
|
|
139
149
|
copyText,
|
|
140
150
|
consents,
|
|
141
151
|
consent,
|
|
152
|
+
refusesAll,
|
|
142
153
|
caches,
|
|
143
154
|
cached,
|
|
144
155
|
hostInfo,
|
|
@@ -282,6 +293,10 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
282
293
|
const config = useByValue(frame.config);
|
|
283
294
|
const instance = useByValue(frame.instance);
|
|
284
295
|
const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
|
|
296
|
+
// A consent that refuses everything (P080), this frame's or else the provider's, by value: a
|
|
297
|
+
// display made with it needs no data handlers, so a change makes the display again.
|
|
298
|
+
const ownRefusal = useByValue(isRefused(frame.consent) ? reasonOf(frame.consent) : undefined);
|
|
299
|
+
const refusesAll = frame.consent === undefined ? page.refusesAll : ownRefusal;
|
|
285
300
|
// The latest props, read when the display calls back (never during render).
|
|
286
301
|
const latest = useEffectEvent(() => frame);
|
|
287
302
|
// The provider's scheme and theme, read when used: a flip or a new themeKey (a new context
|
|
@@ -320,6 +335,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
320
335
|
case "navigated":
|
|
321
336
|
frame.onNavigated?.();
|
|
322
337
|
return;
|
|
338
|
+
case "navigationBlocked":
|
|
339
|
+
frame.onNavigationBlocked?.(detail);
|
|
340
|
+
return;
|
|
323
341
|
case "refused": {
|
|
324
342
|
const { capability, refusal } = detail;
|
|
325
343
|
frame.onRefused?.(capability, refusal);
|
|
@@ -386,14 +404,22 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
386
404
|
}, proceed),
|
|
387
405
|
}
|
|
388
406
|
: {}),
|
|
389
|
-
...(
|
|
390
|
-
? {
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
407
|
+
...(refusesAll !== undefined
|
|
408
|
+
? { consent: new Refused(refusesAll.code, refusesAll.message) }
|
|
409
|
+
: asksConsent
|
|
410
|
+
? {
|
|
411
|
+
consent: (request) => {
|
|
412
|
+
const given = latest().consent ?? pageConsent ?? (() => false);
|
|
413
|
+
if (isRefused(given)) {
|
|
414
|
+
throw given;
|
|
415
|
+
}
|
|
416
|
+
return given({
|
|
417
|
+
...request,
|
|
418
|
+
display: { ...request.display, id: latest().displayId, title: latest().title },
|
|
419
|
+
});
|
|
420
|
+
},
|
|
421
|
+
}
|
|
422
|
+
: {}),
|
|
397
423
|
...(caches
|
|
398
424
|
? {
|
|
399
425
|
cached: (args, context) => (latest().cached ?? pageCached)?.(args, named(context)),
|
|
@@ -423,6 +449,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
423
449
|
"resize",
|
|
424
450
|
"error",
|
|
425
451
|
"navigated",
|
|
452
|
+
"navigationBlocked",
|
|
426
453
|
"refused",
|
|
427
454
|
"muted",
|
|
428
455
|
"outcome",
|
|
@@ -457,6 +484,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
457
484
|
pageConfirm,
|
|
458
485
|
pageConsent,
|
|
459
486
|
pageCached,
|
|
487
|
+
refusesAll,
|
|
460
488
|
hostInfo,
|
|
461
489
|
locate,
|
|
462
490
|
nonce,
|
package/dist/shell/runtime.js
CHANGED
|
@@ -85,7 +85,9 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
85
85
|
// own getters, kept now, so content can neither stop it nor lie to it. Same-document ones (an
|
|
86
86
|
// anchor) go on, and so do reloads: the same address, on the frame's own origin (or none, in a
|
|
87
87
|
// srcdoc frame), which history can change only within that origin. The host's own (a new
|
|
88
|
-
// frame) are none of this document's.
|
|
88
|
+
// frame) are none of this document's. Each one stopped is told to the host (P080), as an error
|
|
89
|
+
// report: below, once the shell can speak.
|
|
90
|
+
let navigationBlocked = (_url) => {};
|
|
89
91
|
const navigationApi = window.navigation;
|
|
90
92
|
const getterOf = (proto, name) => {
|
|
91
93
|
const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, name) : undefined;
|
|
@@ -94,13 +96,17 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
94
96
|
const navigateProto = typeof NavigateEvent === "function" ? NavigateEvent.prototype : null;
|
|
95
97
|
const destinationOf = getterOf(navigateProto, "destination");
|
|
96
98
|
const navigationTypeOf = getterOf(navigateProto, "navigationType");
|
|
97
|
-
const
|
|
99
|
+
const destinationProto = typeof NavigationDestination === "function" ? NavigationDestination.prototype : null;
|
|
100
|
+
const sameDocumentOf = getterOf(destinationProto, "sameDocument");
|
|
101
|
+
const urlOf = getterOf(destinationProto, "url");
|
|
98
102
|
const preventNavigation = Event.prototype.preventDefault;
|
|
99
103
|
const applyOf = Reflect.apply;
|
|
100
104
|
if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
|
|
101
105
|
navigationApi.addEventListener("navigate", (event) => {
|
|
102
|
-
|
|
106
|
+
const destination = applyOf(destinationOf, event, []);
|
|
107
|
+
if (!applyOf(sameDocumentOf, destination, []) && applyOf(navigationTypeOf, event, []) !== "reload") {
|
|
103
108
|
applyOf(preventNavigation, event, []);
|
|
109
|
+
navigationBlocked(urlOf === null ? "" : String(applyOf(urlOf, destination, [])));
|
|
104
110
|
}
|
|
105
111
|
}, true);
|
|
106
112
|
}
|
|
@@ -475,13 +481,27 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
475
481
|
reported += 1;
|
|
476
482
|
send({ method: "notifications/message", params: { level: "error", logger: "porthole", data: String(message).slice(0, 2000) } });
|
|
477
483
|
};
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
484
|
+
// Nothing secret is ever said from here, so any parent may hear it; what it hears is the
|
|
485
|
+
// content's word, which the host gates before it acts on it.
|
|
486
|
+
const post = (message) => {
|
|
487
|
+
if (window.parent !== window) {
|
|
482
488
|
window.parent.postMessage(Object.assign({ jsonrpc: "2.0" }, message), "*");
|
|
483
489
|
}
|
|
484
490
|
};
|
|
491
|
+
const send = (message) => {
|
|
492
|
+
if (plan.protocol === "shell") {
|
|
493
|
+
post(message);
|
|
494
|
+
}
|
|
495
|
+
};
|
|
496
|
+
// A navigation the guard above stopped (P080): one of the run's error reports, told even where
|
|
497
|
+
// the content speaks for itself (an MCP Apps view), in Porthole's own notification.
|
|
498
|
+
navigationBlocked = (url) => {
|
|
499
|
+
if (!declared("reportError") || reported >= plan.maxErrorReports || url === "") {
|
|
500
|
+
return;
|
|
501
|
+
}
|
|
502
|
+
reported += 1;
|
|
503
|
+
post({ method: "porthole/navigation-blocked", params: { url: url.slice(0, 4096) } });
|
|
504
|
+
};
|
|
485
505
|
|
|
486
506
|
// A parsed tree's scripts are held (each replaced by a numbered marker) and run later, in order,
|
|
487
507
|
// as the page's parser would run them: each made again, live, in its marker's place, and each
|
|
@@ -1020,7 +1040,13 @@ export const SHELL_RUNTIME = String.raw `(() => {
|
|
|
1020
1040
|
if (waiting !== undefined) {
|
|
1021
1041
|
pending.delete(data.id);
|
|
1022
1042
|
if (data.error) {
|
|
1023
|
-
|
|
1043
|
+
// A refusal says why (P080): its code, and a sentence to show the person.
|
|
1044
|
+
const why = data.error.data !== null && typeof data.error.data === "object" ? data.error.data : {};
|
|
1045
|
+
const error = new Error(String(typeof why.message === "string" && why.message !== "" ? why.message : data.error.message || "refused"));
|
|
1046
|
+
if (typeof why.code === "string") {
|
|
1047
|
+
error.code = why.code;
|
|
1048
|
+
}
|
|
1049
|
+
waiting.reject(error);
|
|
1024
1050
|
} else {
|
|
1025
1051
|
waiting.resolve(data.result);
|
|
1026
1052
|
}
|
package/docs/ADOPTING.md
CHANGED
|
@@ -94,7 +94,7 @@ Its only way out is your host: `readData` (MCP `resources/read`) and `subscribeD
|
|
|
94
94
|
`resources/subscribe`, `resources/unsubscribe`, `notifications/resources/updated`).
|
|
95
95
|
|
|
96
96
|
```js
|
|
97
|
-
import { defineDisplays } from "@botiverse/porthole";
|
|
97
|
+
import { defineDisplays, Refused } from "@botiverse/porthole";
|
|
98
98
|
|
|
99
99
|
export const displays = defineDisplays({
|
|
100
100
|
// No egress option exists for it; served, it loads Porthole's Chart.js and D3 from its origin.
|
|
@@ -104,10 +104,14 @@ export const displays = defineDisplays({
|
|
|
104
104
|
createHost(displays.configFor(instance, contentSource), {
|
|
105
105
|
locator,
|
|
106
106
|
handlers: {
|
|
107
|
-
// As the viewer: your own access rules, never the author's. Return MCP's read result
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
107
|
+
// As the viewer: your own access rules, never the author's. Return MCP's read result; refuse
|
|
108
|
+
// what you don't serve with a Refused, whose code and sentence the widget shows (P080).
|
|
109
|
+
readData: async ({ uri }, { displayId }) => {
|
|
110
|
+
if (!servedUri(uri)) throw new Refused("not_allowed", "This widget can read issues only.");
|
|
111
|
+
return {
|
|
112
|
+
contents: [{ uri, mimeType: "application/json", text: JSON.stringify(await load(uri)) }],
|
|
113
|
+
};
|
|
114
|
+
},
|
|
111
115
|
// Call changed() when it changes (the content reads it again), or changed(result) to send it.
|
|
112
116
|
subscribeData: ({ uri }, { changed, signal }) => {
|
|
113
117
|
const stop = realtime.on(uri, () => changed());
|
|
@@ -125,12 +129,37 @@ createHost(displays.configFor(instance, contentSource), {
|
|
|
125
129
|
- **Your handlers decide what a URI may name.** Answer only the resources you mean widgets to read
|
|
126
130
|
(a whitelist of URI shapes), with the viewer's rights. The content's URI is its word.
|
|
127
131
|
- **Consent is your UI.** Without a `consent` function every data call is refused (fail closed).
|
|
128
|
-
React: `PortholeProvider` and `PortholeFrame` take `consent` and `cached`.
|
|
132
|
+
React: `PortholeProvider` and `PortholeFrame` take `consent` and `cached`. A consent function
|
|
133
|
+
that throws a `Refused` gives that answer, kept like `false`; anything else it throws is no
|
|
134
|
+
answer yet (the next call asks again).
|
|
135
|
+
- **A page where data must not run** (beside a frame that reaches the network, below): pass a
|
|
136
|
+
`Refused` as `consent` and no data handlers. Every data call is refused with it, nothing is asked,
|
|
137
|
+
and the widget shows your sentence:
|
|
138
|
+
|
|
139
|
+
```js
|
|
140
|
+
createHost(displays.configFor(instance, contentSource), {
|
|
141
|
+
locator,
|
|
142
|
+
consent: new Refused("not_allowed", "Live data shows on the dashboard."),
|
|
143
|
+
});
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Any other capability you declare still needs its handler.
|
|
147
|
+
- **Refusals tell the widget why** (P080). A refused call's JSON-RPC error carries
|
|
148
|
+
`data: { code, message }`; the shell's `readData` rejects (and `subscribeData`'s `onError` is
|
|
149
|
+
called) with an `Error` whose `code` and `message` are those. `code` is `consent_required` (no
|
|
150
|
+
answer yet), `denied` (the viewer said no), `rate_limited`, `not_allowed` (not here, or not this
|
|
151
|
+
URI) or `failed` (your handler threw); `message` is your `Refused`'s sentence, else Porthole's.
|
|
152
|
+
The manual tells the agent to draw the widget without the data, with that sentence. A handler's
|
|
153
|
+
other errors are `failed` in Porthole's words: their messages stay yours.
|
|
129
154
|
- **Rates stay gates**: 120 reads and 60 subscriptions a minute per display by default; change them
|
|
130
155
|
with the capability's `gates` (keep `"consent"` in the list).
|
|
131
156
|
- **Your page's CSP**: send `displays.embedderCsp(source, …)` (`frame-src` of your content origins
|
|
132
157
|
and the authorize route, nothing else). It keeps a frame from navigating to an outside site; the
|
|
133
|
-
shell keeps a served frame from navigating to another content origin (P079)
|
|
158
|
+
shell keeps a served frame from navigating to another content origin (P079), and tells you:
|
|
159
|
+
`display.on("navigationBlocked", ({ url }) => …)` (React `onNavigationBlocked`) gets the address
|
|
160
|
+
whole, and `contentError` a sentence naming it without its query, for the agent (P080). Only
|
|
161
|
+
where the config declares `reportError`, and only served frames: an opaque frame's navigations
|
|
162
|
+
get no events (you hear `navigated` when one replaces its document).
|
|
134
163
|
- **Keep live widgets off pages with frames that reach the network.** A frame can `postMessage` any
|
|
135
164
|
frame on its page, and nothing in it can stop that: a url-mode app (a dev server's preview) or an
|
|
136
165
|
`anyHttps` display beside a live widget could be handed what it read. Displays with closed egress
|
|
@@ -400,8 +429,9 @@ in the config also has the manual name them). The descriptions are the manual's
|
|
|
400
429
|
warnings with the result. `refuseOn: "never"` only warns.
|
|
401
430
|
- **`guideChanges(from, to)`** is the notice for the agent when a kind flips between served and
|
|
402
431
|
opaque (null when its manual reads the same).
|
|
403
|
-
- **`errors: "agent"`** sends what content throws (and what the sandbox blocks
|
|
404
|
-
once people see it: listen for `contentError` and pass
|
|
432
|
+
- **`errors: "agent"`** sends what content throws (and what the sandbox blocks, and a navigation
|
|
433
|
+
the shell stopped, P080) back to the agent once people see it: listen for `contentError` and pass
|
|
434
|
+
it on.
|
|
405
435
|
|
|
406
436
|
### Checking a page before people see it
|
|
407
437
|
|