@botiverse/porthole 0.3.2 → 0.3.3
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 +2 -5
- package/dist/bridge/types.d.ts +11 -4
- package/dist/check/page-source.js +1 -1
- package/dist/conformance/harness-source.js +1 -1
- package/dist/host/create-host.js +5 -1
- package/dist/index.d.ts +1 -1
- package/dist/node/index.d.ts +4 -1
- package/dist/node/index.js +3 -1
- package/dist/react/frame.js +8 -1
- package/dist/server/host.d.ts +4 -1
- package/dist/server/host.js +6 -0
- package/docs/ADOPTING.md +7 -2
- package/docs/DECISIONS.md +20 -0
- package/docs/DESIGN.md +4 -2
- package/package.json +1 -1
- package/src/bridge/bridge.ts +2 -1
- package/src/bridge/types.ts +12 -1
- package/src/host/create-host.ts +5 -1
- package/src/index.ts +1 -0
- package/src/node/index.ts +7 -2
- package/src/react/frame.tsx +8 -1
- package/src/server/host.ts +10 -1
package/dist/host/create-host.js
CHANGED
|
@@ -301,7 +301,11 @@ export function createHost(config, options = {}) {
|
|
|
301
301
|
}
|
|
302
302
|
const bridge = createBridge({
|
|
303
303
|
config,
|
|
304
|
-
display: {
|
|
304
|
+
display: {
|
|
305
|
+
id: mount.displayId,
|
|
306
|
+
title: mount.title,
|
|
307
|
+
...(mount.instance === undefined ? {} : { instance: mount.instance }),
|
|
308
|
+
},
|
|
305
309
|
handlers,
|
|
306
310
|
...(options.confirm === undefined ? {} : { confirm: options.confirm }),
|
|
307
311
|
userActivation: () => created.userActivation(),
|
package/dist/index.d.ts
CHANGED
|
@@ -22,7 +22,7 @@ export type { PlatformHost, Surface, SurfaceSpec } from "./platform/types.ts";
|
|
|
22
22
|
export type { Transport } from "./transport/types.ts";
|
|
23
23
|
export type { AdapterConnection, AdapterEvent, AdapterSession, ProtocolAdapter, ShellConnection, } from "./protocol/adapter.ts";
|
|
24
24
|
export { COPY_TEXT_METHOD, MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, type HostContext, } from "./protocol/mcp-apps.ts";
|
|
25
|
-
export type { CallContext, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmRequest, Proceed, HostFunctionBridge, Refusal, } from "./bridge/types.ts";
|
|
25
|
+
export type { CallContext, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmAnswer, ConfirmDisplay, ConfirmRequest, Proceed, HostFunctionBridge, Refusal, } from "./bridge/types.ts";
|
|
26
26
|
export { createHost } from "./host/create-host.ts";
|
|
27
27
|
export { entryTarget, frameFallback, portholeClient, type ContentClientMeta, type FrameFallback, type PortholeClient, type PortholeClientOptions, } from "./host/client.ts";
|
|
28
28
|
export { defineDisplays, type DisplayKind, type Displays } from "./displays/displays.ts";
|
package/dist/node/index.d.ts
CHANGED
|
@@ -50,7 +50,10 @@ export interface NodeServerOptions {
|
|
|
50
50
|
/**
|
|
51
51
|
* The content host, or a function giving it when it exists: a host made after the server listens
|
|
52
52
|
* (its content domain names the port `listen(0)` chose, P074). Until it gives one, every request
|
|
53
|
-
* is the app's
|
|
53
|
+
* is the app's. `nodeServer` starts the host's health gate when it listens, asking the function
|
|
54
|
+
* once the server's `listen` callbacks have run (a host made in one starts then), and again at
|
|
55
|
+
* each request until it gives one; `start` is idempotent, so an app may start the host itself
|
|
56
|
+
* as soon as it makes it (P076).
|
|
54
57
|
*/
|
|
55
58
|
readonly content: ContentHost<unknown> | (() => ContentHost<unknown> | null);
|
|
56
59
|
/**
|
package/dist/node/index.js
CHANGED
|
@@ -300,9 +300,11 @@ export function nodeServer(options) {
|
|
|
300
300
|
});
|
|
301
301
|
server.on("listening", () => {
|
|
302
302
|
listening = true;
|
|
303
|
-
|
|
303
|
+
// After the listen callbacks: a host made in one (with the port it got) starts now.
|
|
304
|
+
setImmediate(current);
|
|
304
305
|
});
|
|
305
306
|
server.on("close", () => {
|
|
307
|
+
listening = false;
|
|
306
308
|
const host = typeof given === "function" ? given() : given;
|
|
307
309
|
host?.close();
|
|
308
310
|
});
|
package/dist/react/frame.js
CHANGED
|
@@ -357,7 +357,14 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
|
|
|
357
357
|
handlers,
|
|
358
358
|
...(asks
|
|
359
359
|
? {
|
|
360
|
-
confirm: (request, proceed) => (latest().confirm ?? pageConfirm ?? (() => Promise.resolve(false)))({
|
|
360
|
+
confirm: (request, proceed) => (latest().confirm ?? pageConfirm ?? (() => Promise.resolve(false)))({
|
|
361
|
+
...request,
|
|
362
|
+
display: {
|
|
363
|
+
...request.display,
|
|
364
|
+
id: latest().displayId,
|
|
365
|
+
title: latest().title,
|
|
366
|
+
},
|
|
367
|
+
}, proceed),
|
|
361
368
|
}
|
|
362
369
|
: {}),
|
|
363
370
|
theme: (each) => (latest().theme ?? latestPage().theme)?.(each) ?? {},
|
package/dist/server/host.d.ts
CHANGED
|
@@ -251,7 +251,10 @@ export interface ContentHost<V> {
|
|
|
251
251
|
authorize(viewerOf: (request: Request) => Awaitable<V | null>): (request: Request) => Promise<Response>;
|
|
252
252
|
/** A url-mode app's access for a WebSocket upgrade (`server.access`), or null. */
|
|
253
253
|
access(request: Request): Promise<Access | null>;
|
|
254
|
-
/**
|
|
254
|
+
/**
|
|
255
|
+
* Starts the health gate (after the app listens). Once: starting a started host does nothing,
|
|
256
|
+
* so the app and `nodeServer` may both start it (P076). After `close`, it starts again.
|
|
257
|
+
*/
|
|
255
258
|
start(): void;
|
|
256
259
|
/** Runs one health check now. */
|
|
257
260
|
check(): Promise<ContentHealthView>;
|
package/dist/server/host.js
CHANGED
|
@@ -203,6 +203,7 @@ export function createContentHost(options) {
|
|
|
203
203
|
let timer = null;
|
|
204
204
|
let running = null;
|
|
205
205
|
let closed = false;
|
|
206
|
+
let started = false;
|
|
206
207
|
const schedule = () => {
|
|
207
208
|
if (closed || gate === undefined || view.misconfigured === true || domain === null) {
|
|
208
209
|
return;
|
|
@@ -687,12 +688,17 @@ export function createContentHost(options) {
|
|
|
687
688
|
},
|
|
688
689
|
access: async (request) => (server === null ? null : server.access(request)),
|
|
689
690
|
start() {
|
|
691
|
+
if (started) {
|
|
692
|
+
return;
|
|
693
|
+
}
|
|
694
|
+
started = true;
|
|
690
695
|
closed = false;
|
|
691
696
|
void check();
|
|
692
697
|
},
|
|
693
698
|
check,
|
|
694
699
|
close() {
|
|
695
700
|
closed = true;
|
|
701
|
+
started = false;
|
|
696
702
|
if (timer !== null) {
|
|
697
703
|
clearTimeout(timer);
|
|
698
704
|
timer = null;
|
package/docs/ADOPTING.md
CHANGED
|
@@ -65,7 +65,9 @@ reads the page's), `handlers`, `openLink` (default: a new tab), `notify` (your o
|
|
|
65
65
|
a copy button copied), and `renderConfirm` (your own dialog, given `accept`, `decline` and
|
|
66
66
|
`redirect`: Porthole keeps the queue, runs `accept` inside its click, and counts declines toward
|
|
67
67
|
muting the display; `redirect`, for "edit it first", answers the call `"redirected"` and neither
|
|
68
|
-
counts nor resets the count).
|
|
68
|
+
counts nor resets the count). The request names the display (`request.display`: its `id`,
|
|
69
|
+
`title`, and the `instance` a served frame shows), so the dialog can say what it is from your own
|
|
70
|
+
records. `useRunAgain()` gives a "run again" button.
|
|
69
71
|
|
|
70
72
|
## 4. Served pages: the host kit
|
|
71
73
|
|
|
@@ -132,7 +134,10 @@ nodeServer({ content, app: async (request) => (await routes(request)) ?? app(req
|
|
|
132
134
|
every other request to `app` (fetch-style: Hono's `app.fetch`) or `request` (a Node listener:
|
|
133
135
|
Express), the health gate started on listen and stopped on close. Behind a TLS edge, add
|
|
134
136
|
`scheme: "https"`. A host that needs the port first (`listen(0)`) can come later: `content:
|
|
135
|
-
() => host` (null until made); requests go to the app until it gives one.
|
|
137
|
+
() => host` (null until made); requests go to the app until it gives one. `nodeServer` starts
|
|
138
|
+
the host it is given: a host made in a `listen` callback starts right after it, and one made
|
|
139
|
+
later at the next request. `start()` runs once (a started host ignores it), so starting it
|
|
140
|
+
yourself as soon as you make it is fine too.
|
|
136
141
|
- **`nodeHost(content, { request })`** is for an app that keeps its own `node:http` server (or a
|
|
137
142
|
framework that owns one): put its `request` and `upgrade` listeners on your server, call
|
|
138
143
|
`content.start()` once it listens and `content.close()` when it stops.
|
package/docs/DECISIONS.md
CHANGED
|
@@ -2122,3 +2122,23 @@ on `/check`; a Worker's bundle would fail where the path runs. 0.3.2:
|
|
|
2122
2122
|
and the failure shows only where the path runs.
|
|
2123
2123
|
**Revisit when** a bundler needs code split into chunks of its own (none does yet).
|
|
2124
2124
|
|
|
2125
|
+
## P076 · 2026-10-12 · A confirmation names the instance; a content host starts once · Accepted
|
|
2126
|
+
|
|
2127
|
+
**Decision.** From Ferry, #10. 0.3.3, additive:
|
|
2128
|
+
1. **`ConfirmRequest.display` carries the frame's `instance`** where the display is served
|
|
2129
|
+
(`ConfirmDisplay`: `id`, `title`, `instance?`), in the core's `confirm` and React's
|
|
2130
|
+
`renderConfirm`. A host words its dialog from its own records (Ferry: the transcript the
|
|
2131
|
+
instance belongs to) without keeping an index from display ids to them (28 lines in Ferry). The
|
|
2132
|
+
instance is the host's own, as it gave it to `mount`: nothing the content chose.
|
|
2133
|
+
2. **`ContentHost.start()` runs once**: a started host ignores it until `close`, so the app and
|
|
2134
|
+
`nodeServer` may both start it (before, each start ran a check, and the second came at the first
|
|
2135
|
+
request). **`nodeServer` asks a lazily given host right after the server's `listen` callbacks**
|
|
2136
|
+
(a host made in one, with the port it got, starts then), and again at each request until it
|
|
2137
|
+
gives one. ADOPTING says who starts it.
|
|
2138
|
+
|
|
2139
|
+
**Why.** Each was a workaround in Ferry: the side index, and starting the host itself while
|
|
2140
|
+
`nodeServer` started it again.
|
|
2141
|
+
**Measured.** `leak/react.spec.ts` (`renderConfirm` names the served frame's instance, and none
|
|
2142
|
+
for an opaque one); `test/kit03.test.ts` (a host made in the `listen` callback is checked without a
|
|
2143
|
+
request, once, however often it is started).
|
|
2144
|
+
|
package/docs/DESIGN.md
CHANGED
|
@@ -530,7 +530,8 @@ What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the
|
|
|
530
530
|
served, content source, frame sources, health) and `POST`/`DELETE handoff`.
|
|
531
531
|
`contentHostFor(build)` gives one host per Workers `env`, failing closed with a plain 503;
|
|
532
532
|
`nodeServer({ content, app })` is the whole Node server (`content` may be a function giving the
|
|
533
|
-
host once made, P074
|
|
533
|
+
host once made, P074; asked right after the `listen` callbacks and at each request until it
|
|
534
|
+
gives one, and `start` is idempotent, P076). A missing or short secret throws, naming `PORTHOLE_SECRET`.
|
|
534
535
|
- **The client:** `portholeClient({ displays, base, headers, credentials, handoff })` is the
|
|
535
536
|
locator and knows each kind's config from the meta (null until known), links, `openInTab`
|
|
536
537
|
(a tab opened in the click, then sent to the address), the handoff, and `entryTarget` (the
|
|
@@ -539,7 +540,8 @@ What both adopters still wrote after 0.2 moves into Porthole (ADOPTING.md is the
|
|
|
539
540
|
`denied`, `expired`, `failed`, `timeout`). React: `PortholeView` (a display by kind, served or
|
|
540
541
|
opaque, with its fallback), `usePortholeLink`, and the provider's shared `scheme`, `theme`
|
|
541
542
|
(`cssVariableTheme`), `nonce: "auto"`, `handlers`, `openLink`, `notify` and `renderConfirm`
|
|
542
|
-
(`accept`, `decline`, and `redirect`: `"redirected"`, which doesn't count toward muting, P074
|
|
543
|
+
(`accept`, `decline`, and `redirect`: `"redirected"`, which doesn't count toward muting, P074;
|
|
544
|
+
the request's `display` carries the served frame's `instance`, P076).
|
|
543
545
|
A flip of the provider's scheme or a new themeKey re-themes running frames in place: no effect
|
|
544
546
|
that makes a display depends on the context value those renew (#9, P074).
|
|
545
547
|
- **The viewer handoff** for a page that holds a token: `POST /porthole/handoff` with the app's
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botiverse/porthole",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.3",
|
|
4
4
|
"description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"bin": {
|
package/src/bridge/bridge.ts
CHANGED
|
@@ -15,6 +15,7 @@ import type {
|
|
|
15
15
|
CapabilityHandlers,
|
|
16
16
|
Confirm,
|
|
17
17
|
ConfirmAnswer,
|
|
18
|
+
ConfirmDisplay,
|
|
18
19
|
ConfirmRequest,
|
|
19
20
|
HostFunctionBridge,
|
|
20
21
|
Refusal,
|
|
@@ -35,7 +36,7 @@ export type BridgeEvent =
|
|
|
35
36
|
|
|
36
37
|
export interface BridgeOptions {
|
|
37
38
|
readonly config: PortholeConfig;
|
|
38
|
-
readonly display:
|
|
39
|
+
readonly display: ConfirmDisplay;
|
|
39
40
|
readonly handlers: CapabilityHandlers;
|
|
40
41
|
readonly confirm?: Confirm;
|
|
41
42
|
/** Whether the embedding page has user activation now; undefined where it can't tell. */
|
package/src/bridge/types.ts
CHANGED
|
@@ -4,6 +4,7 @@ import type {
|
|
|
4
4
|
CapabilityResults,
|
|
5
5
|
HandledCapability,
|
|
6
6
|
} from "../config/capabilities.ts";
|
|
7
|
+
import type { InstanceRef } from "../isolation/types.ts";
|
|
7
8
|
|
|
8
9
|
/**
|
|
9
10
|
* The host-function bridge (ARCHITECTURE § Framework layer): carries a capability call from the
|
|
@@ -28,12 +29,22 @@ export type CapabilityHandler<N extends CapabilityName> = (
|
|
|
28
29
|
/** The host's handlers: one for each declared capability served by a handler. */
|
|
29
30
|
export type CapabilityHandlers = { readonly [N in HandledCapability]?: CapabilityHandler<N> };
|
|
30
31
|
|
|
32
|
+
/**
|
|
33
|
+
* The display a confirmation is for, as the host named it: its id and title, and the instance it
|
|
34
|
+
* shows where it is served (P076), so a host can word its dialog from its own records.
|
|
35
|
+
*/
|
|
36
|
+
export interface ConfirmDisplay {
|
|
37
|
+
readonly id: string;
|
|
38
|
+
readonly title: string;
|
|
39
|
+
readonly instance?: InstanceRef;
|
|
40
|
+
}
|
|
41
|
+
|
|
31
42
|
/** What a person is asked to confirm: the call's whole effect, not a summary the content chose. */
|
|
32
43
|
export type ConfirmRequest = {
|
|
33
44
|
[N in CapabilityName]: {
|
|
34
45
|
readonly capability: N;
|
|
35
46
|
readonly args: CapabilityArgs[N];
|
|
36
|
-
readonly display:
|
|
47
|
+
readonly display: ConfirmDisplay;
|
|
37
48
|
};
|
|
38
49
|
}[CapabilityName];
|
|
39
50
|
|
package/src/host/create-host.ts
CHANGED
|
@@ -353,7 +353,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
|
|
|
353
353
|
}
|
|
354
354
|
const bridge = createBridge({
|
|
355
355
|
config,
|
|
356
|
-
display: {
|
|
356
|
+
display: {
|
|
357
|
+
id: mount.displayId,
|
|
358
|
+
title: mount.title,
|
|
359
|
+
...(mount.instance === undefined ? {} : { instance: mount.instance }),
|
|
360
|
+
},
|
|
357
361
|
handlers,
|
|
358
362
|
...(options.confirm === undefined ? {} : { confirm: options.confirm }),
|
|
359
363
|
userActivation: () => created.userActivation(),
|
package/src/index.ts
CHANGED
package/src/node/index.ts
CHANGED
|
@@ -295,7 +295,10 @@ export interface NodeServerOptions {
|
|
|
295
295
|
/**
|
|
296
296
|
* The content host, or a function giving it when it exists: a host made after the server listens
|
|
297
297
|
* (its content domain names the port `listen(0)` chose, P074). Until it gives one, every request
|
|
298
|
-
* is the app's
|
|
298
|
+
* is the app's. `nodeServer` starts the host's health gate when it listens, asking the function
|
|
299
|
+
* once the server's `listen` callbacks have run (a host made in one starts then), and again at
|
|
300
|
+
* each request until it gives one; `start` is idempotent, so an app may start the host itself
|
|
301
|
+
* as soon as it makes it (P076).
|
|
299
302
|
*/
|
|
300
303
|
readonly content: ContentHost<unknown> | (() => ContentHost<unknown> | null);
|
|
301
304
|
/**
|
|
@@ -384,9 +387,11 @@ export function nodeServer(options: NodeServerOptions): Server {
|
|
|
384
387
|
});
|
|
385
388
|
server.on("listening", () => {
|
|
386
389
|
listening = true;
|
|
387
|
-
|
|
390
|
+
// After the listen callbacks: a host made in one (with the port it got) starts now.
|
|
391
|
+
setImmediate(current);
|
|
388
392
|
});
|
|
389
393
|
server.on("close", () => {
|
|
394
|
+
listening = false;
|
|
390
395
|
const host = typeof given === "function" ? given() : given;
|
|
391
396
|
host?.close();
|
|
392
397
|
});
|
package/src/react/frame.tsx
CHANGED
|
@@ -715,7 +715,14 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
|
|
|
715
715
|
? {
|
|
716
716
|
confirm: (request: ConfirmRequest, proceed: Proceed) =>
|
|
717
717
|
(latest().confirm ?? pageConfirm ?? (() => Promise.resolve(false)))(
|
|
718
|
-
{
|
|
718
|
+
{
|
|
719
|
+
...request,
|
|
720
|
+
display: {
|
|
721
|
+
...request.display,
|
|
722
|
+
id: latest().displayId,
|
|
723
|
+
title: latest().title,
|
|
724
|
+
},
|
|
725
|
+
},
|
|
719
726
|
proceed,
|
|
720
727
|
),
|
|
721
728
|
}
|
package/src/server/host.ts
CHANGED
|
@@ -311,7 +311,10 @@ export interface ContentHost<V> {
|
|
|
311
311
|
): (request: Request) => Promise<Response>;
|
|
312
312
|
/** A url-mode app's access for a WebSocket upgrade (`server.access`), or null. */
|
|
313
313
|
access(request: Request): Promise<Access | null>;
|
|
314
|
-
/**
|
|
314
|
+
/**
|
|
315
|
+
* Starts the health gate (after the app listens). Once: starting a started host does nothing,
|
|
316
|
+
* so the app and `nodeServer` may both start it (P076). After `close`, it starts again.
|
|
317
|
+
*/
|
|
315
318
|
start(): void;
|
|
316
319
|
/** Runs one health check now. */
|
|
317
320
|
check(): Promise<ContentHealthView>;
|
|
@@ -533,6 +536,7 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
533
536
|
let timer: ReturnType<typeof setTimeout> | null = null;
|
|
534
537
|
let running: Promise<ContentHealthView> | null = null;
|
|
535
538
|
let closed = false;
|
|
539
|
+
let started = false;
|
|
536
540
|
const schedule = () => {
|
|
537
541
|
if (closed || gate === undefined || view.misconfigured === true || domain === null) {
|
|
538
542
|
return;
|
|
@@ -1114,12 +1118,17 @@ export function createContentHost<V>(options: ContentHostOptions<V>): ContentHos
|
|
|
1114
1118
|
access: async (request) => (server === null ? null : server.access(request)),
|
|
1115
1119
|
|
|
1116
1120
|
start() {
|
|
1121
|
+
if (started) {
|
|
1122
|
+
return;
|
|
1123
|
+
}
|
|
1124
|
+
started = true;
|
|
1117
1125
|
closed = false;
|
|
1118
1126
|
void check();
|
|
1119
1127
|
},
|
|
1120
1128
|
check,
|
|
1121
1129
|
close() {
|
|
1122
1130
|
closed = true;
|
|
1131
|
+
started = false;
|
|
1123
1132
|
if (timer !== null) {
|
|
1124
1133
|
clearTimeout(timer);
|
|
1125
1134
|
timer = null;
|