@botiverse/porthole 0.13.0 → 0.14.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.
Files changed (77) hide show
  1. package/CHANGELOG.md +770 -0
  2. package/dist/annotate/types.d.ts +36 -4
  3. package/dist/annotate/types.js +6 -0
  4. package/dist/annotate/validate.d.ts +2 -1
  5. package/dist/annotate/validate.js +30 -6
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/compile/policy.d.ts +7 -0
  8. package/dist/compile/policy.js +13 -1
  9. package/dist/config/schema.d.ts +11 -0
  10. package/dist/config/validate.js +19 -0
  11. package/dist/conformance/harness-source.js +1 -1
  12. package/dist/displays/displays.js +3 -1
  13. package/dist/guide/limits.js +1 -1
  14. package/dist/host/create-host.d.ts +2 -0
  15. package/dist/host/create-host.js +78 -3
  16. package/dist/host/pass-on.d.ts +15 -0
  17. package/dist/host/pass-on.js +65 -0
  18. package/dist/host/types.d.ts +29 -0
  19. package/dist/index.d.ts +4 -1
  20. package/dist/index.js +4 -1
  21. package/dist/isolation/types.d.ts +8 -0
  22. package/dist/isolation/types.js +8 -0
  23. package/dist/platform/focus-guard.d.ts +71 -2
  24. package/dist/platform/focus-guard.js +187 -12
  25. package/dist/platform/types.d.ts +8 -1
  26. package/dist/platform/web.js +60 -4
  27. package/dist/presets/presets.d.ts +2 -0
  28. package/dist/presets/presets.js +1 -0
  29. package/dist/react/frame.d.ts +4 -3
  30. package/dist/server/files.js +19 -3
  31. package/dist/server/index.d.ts +1 -0
  32. package/dist/server/index.js +5 -0
  33. package/dist/server/naming.js +4 -0
  34. package/dist/server/nested.d.ts +59 -0
  35. package/dist/server/nested.js +96 -0
  36. package/dist/server/server.js +193 -23
  37. package/dist/server/types.d.ts +5 -0
  38. package/dist/shell/annotate.d.ts +4 -3
  39. package/dist/shell/annotate.js +179 -9
  40. package/dist/shell/frame.d.ts +45 -0
  41. package/dist/shell/frame.js +250 -0
  42. package/dist/shell/plan.js +2 -1
  43. package/dist/shell/runtime.d.ts +6 -0
  44. package/dist/shell/runtime.js +60 -15
  45. package/docs/ADOPTING.md +85 -2
  46. package/docs/ARCHITECTURE.md +28 -0
  47. package/docs/DECISIONS.md +416 -1
  48. package/docs/DESIGN.md +21 -4
  49. package/docs/THREAT_MODEL.md +102 -5
  50. package/package.json +6 -5
  51. package/src/annotate/types.ts +32 -4
  52. package/src/annotate/validate.ts +34 -8
  53. package/src/compile/policy.ts +14 -1
  54. package/src/config/schema.ts +11 -0
  55. package/src/config/validate.ts +23 -0
  56. package/src/displays/displays.ts +3 -1
  57. package/src/guide/limits.ts +1 -1
  58. package/src/host/create-host.ts +81 -4
  59. package/src/host/pass-on.ts +73 -0
  60. package/src/host/types.ts +27 -0
  61. package/src/index.ts +4 -1
  62. package/src/isolation/types.ts +12 -0
  63. package/src/platform/focus-guard.ts +258 -15
  64. package/src/platform/types.ts +8 -1
  65. package/src/platform/web.ts +81 -9
  66. package/src/presets/presets.ts +3 -0
  67. package/src/react/frame.tsx +4 -3
  68. package/src/server/files.ts +19 -3
  69. package/src/server/index.ts +14 -0
  70. package/src/server/naming.ts +4 -0
  71. package/src/server/nested.ts +116 -0
  72. package/src/server/server.ts +224 -21
  73. package/src/server/types.ts +5 -0
  74. package/src/shell/annotate.ts +179 -9
  75. package/src/shell/frame.ts +268 -0
  76. package/src/shell/plan.ts +2 -1
  77. package/src/shell/runtime.ts +61 -15
@@ -26,8 +26,9 @@ import { isRefused } from "../bridge/refusal.ts";
26
26
  import { capabilitySpec } from "../config/capabilities.ts";
27
27
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
28
28
  import { locateServed } from "./locate.ts";
29
+ import { mayPassOn } from "./pass-on.ts";
29
30
  import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
30
- import type { FrameSource } from "../isolation/types.ts";
31
+ import { STORAGE_USED_METHOD, type FrameSource } from "../isolation/types.ts";
31
32
  import { webPlatform } from "../platform/web.ts";
32
33
  import { TAKES } from "../platform/focus-guard.ts";
33
34
  import type { Surface } from "../platform/types.ts";
@@ -66,8 +67,12 @@ const REPORTS: Readonly<Record<string, AnnotationReport["type"]>> = {
66
67
  [ANNOTATE_METHODS.cancelled]: "cancelled",
67
68
  [ANNOTATE_METHODS.anchored]: "anchored",
68
69
  [ANNOTATE_METHODS.activated]: "activated",
70
+ [ANNOTATE_METHODS.tracked]: "tracked",
69
71
  };
70
72
 
73
+ /** The most `tracked` reports a second the host takes (P112): one per animation frame at 60 Hz. */
74
+ export const TRACKED_PER_SECOND = 60;
75
+
71
76
  const isRecord = (value: unknown): value is Record<string, unknown> =>
72
77
  value !== null && typeof value === "object" && !Array.isArray(value);
73
78
  const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
@@ -95,6 +100,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
95
100
 
96
101
  return {
97
102
  compiled,
103
+ mayPassOn: (declaration) => mayPassOn(config, declaration),
98
104
  mount(container: HTMLElement, mount: MountOptions): DisplayHandle<C> {
99
105
  const handlers = { ...options.handlers, ...mount.handlers };
100
106
  // A host whose consent is a Refused refuses every consent-gated call before its handler:
@@ -184,7 +190,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
184
190
  let annotating: Required<AnnotateMode> | null = null;
185
191
  let marks: AnnotationMark[] = [];
186
192
  let activeMark: string | null = null;
193
+ // The mark the host follows (P112), and when it took each `tracked` in the last second.
194
+ let tracking: string | null = null;
195
+ const trackedTimes: number[] = [];
187
196
  let handshaken = false;
197
+ let storageTold = false;
188
198
  const toFrame = (method: string, params: Record<string, unknown>) => {
189
199
  if (handshaken && surface !== null) {
190
200
  surface.transport.send({ jsonrpc: "2.0", method, params });
@@ -200,6 +210,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
200
210
  if (annotating !== null) {
201
211
  toFrame(ANNOTATE_METHODS.start, { ...annotating });
202
212
  }
213
+ if (tracking !== null) {
214
+ toFrame(ANNOTATE_METHODS.track, { id: tracking });
215
+ }
203
216
  };
204
217
  /**
205
218
  * The frame's viewport as the platform tells it now; undefined where it can't (no
@@ -243,6 +256,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
243
256
  switch (report.type) {
244
257
  case "selected":
245
258
  case "activated":
259
+ case "tracked":
246
260
  return { ...report, rect: clampRect(report.rect, viewport) };
247
261
  case "anchored":
248
262
  return {
@@ -281,6 +295,25 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
281
295
  void through.call("annotate", null);
282
296
  return;
283
297
  }
298
+ // The followed mark's box (P112): the mark the host follows and no other, while it is
299
+ // shown, at most 60 a second; past the bridge's rate for reports, which a card that follows
300
+ // its mark at every frame would spend at once.
301
+ if (report.type === "tracked") {
302
+ const { id } = report;
303
+ if (id !== tracking || !marks.some((mark) => mark.id === id)) {
304
+ return;
305
+ }
306
+ const at = Date.now();
307
+ while (trackedTimes.length > 0 && at - (trackedTimes[0] as number) >= 1_000) {
308
+ trackedTimes.shift();
309
+ }
310
+ if (trackedTimes.length >= TRACKED_PER_SECOND) {
311
+ return;
312
+ }
313
+ trackedTimes.push(at);
314
+ emit("annotation", withinFrame(report));
315
+ return;
316
+ }
284
317
  switch (report.type) {
285
318
  case "selected": {
286
319
  const kind = report.anchor.kind;
@@ -290,7 +323,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
290
323
  ) {
291
324
  return;
292
325
  }
293
- if (kind === "element") {
326
+ // A pick ends with it; holding a block (P112) lasts until the host stops it.
327
+ if (kind === "element" && annotating.elements === true) {
294
328
  annotating = annotating.text ? { elements: false, text: true } : null;
295
329
  }
296
330
  break;
@@ -301,10 +335,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
301
335
  }
302
336
  break;
303
337
  case "cancelled":
304
- if (annotating?.elements !== true) {
338
+ // While the host asked for a pick or for text (P112: Escape while selecting text);
339
+ // a pick ends with it, text selection is the host's to stop.
340
+ if (annotating === null) {
305
341
  return;
306
342
  }
307
- annotating = annotating.text ? { elements: false, text: true } : null;
343
+ if (annotating.elements === true) {
344
+ annotating = annotating.text ? { elements: false, text: true } : null;
345
+ }
308
346
  break;
309
347
  case "anchored": {
310
348
  const known = new Set(marks.map((mark) => mark.id));
@@ -354,6 +392,10 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
354
392
  if (activeMark !== null && !marks.some((mark) => mark.id === activeMark)) {
355
393
  activeMark = null;
356
394
  }
395
+ if (tracking !== null && !marks.some((mark) => mark.id === tracking)) {
396
+ tracking = null;
397
+ toFrame(ANNOTATE_METHODS.track, { id: null });
398
+ }
357
399
  toFrame(ANNOTATE_METHODS.show, {
358
400
  marks,
359
401
  ...(activeMark === null ? {} : { active: activeMark }),
@@ -367,12 +409,27 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
367
409
  activeMark = id;
368
410
  toFrame(ANNOTATE_METHODS.focus, { id });
369
411
  },
412
+ track(id) {
413
+ needsAnnotate("track");
414
+ if (id !== null && !marks.some((mark) => mark.id === id)) {
415
+ throw new TypeError(`annotations.track: no mark ${JSON.stringify(id)} is shown`);
416
+ }
417
+ tracking = id;
418
+ trackedTimes.length = 0;
419
+ toFrame(ANNOTATE_METHODS.track, { id });
420
+ },
370
421
  clear() {
371
422
  needsAnnotate("clear");
372
423
  marks = [];
373
424
  activeMark = null;
425
+ tracking = null;
374
426
  toFrame(ANNOTATE_METHODS.clear, {});
375
427
  },
428
+ clearSelection() {
429
+ // Host → frame only, and kept for no later frame (P115).
430
+ needsAnnotate("clearSelection");
431
+ toFrame(ANNOTATE_METHODS.clearSelection, {});
432
+ },
376
433
  };
377
434
 
378
435
  const hostContext = (): HostContext => {
@@ -436,6 +493,11 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
436
493
  };
437
494
 
438
495
  const stop = () => {
496
+ // A run that ran a page with storage of its own making and never heard it used: no (P111).
497
+ if (bridge !== null && handshaken && !storageTold && compiled.shell?.storage === "memory") {
498
+ emit("storage", { used: false });
499
+ }
500
+ storageTold = false;
439
501
  // The run's bridge refuses what still waits for a confirmation: a yes to it runs nothing
440
502
  // (P095, after the review), and the next run's bridge starts its count again.
441
503
  bridge?.close();
@@ -469,6 +531,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
469
531
  allow: compiled.allow,
470
532
  referrerPolicy: compiled.referrerPolicy,
471
533
  colorScheme: scheme,
534
+ // A nested page's shell (P111): the config's word, never the frame's.
535
+ ...(config.nested === true ? { nested: true } : {}),
472
536
  // An app reports no size: its frame fills the host's container, at least the minimum;
473
537
  // so does any display the host mounts to fill, or whose layout fills (P065): its
474
538
  // content scrolls itself.
@@ -563,6 +627,19 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
563
627
  if (annotates) {
564
628
  created.transport.listen((raw) => onAnnotation(raw, opening));
565
629
  }
630
+ // Whether the page used storage (P111): once per run, the page's word (a count, no more).
631
+ created.transport.listen((raw) => {
632
+ if (
633
+ !storageTold &&
634
+ isRecord(raw) &&
635
+ raw.jsonrpc === "2.0" &&
636
+ raw.method === STORAGE_USED_METHOD &&
637
+ !("id" in raw)
638
+ ) {
639
+ storageTold = true;
640
+ emit("storage", { used: true });
641
+ }
642
+ });
566
643
  bridge = opening;
567
644
  const opened = adapter.connect({
568
645
  display: { id: mount.displayId, title: mount.title },
@@ -0,0 +1,73 @@
1
+ import type { CapabilityName } from "../config/capabilities.ts";
2
+ import type { PortholeConfig } from "../config/schema.ts";
3
+ import { egressOrigins, type EgressKind } from "../compile/policy.ts";
4
+ import { LIBRARY_CDNS } from "../presets/presets.ts";
5
+ import { familyOf, runtimeCapability } from "../runtime/contract.ts";
6
+ import type { PageDeclaration } from "../runtime/declaration.ts";
7
+
8
+ /** Every kind a page reaches the network by. */
9
+ const KINDS: readonly EgressKind[] = ["connect", "script", "style", "img", "font", "media"];
10
+
11
+ /**
12
+ * The host functions that carry what a page puts in them to someone other than the person viewing
13
+ * it (P112, after the review, porthole#54): stores others read (`db`, a new version through
14
+ * `artifact`, the asset library through `assets`), a URL the person opens (`openLink`), the agent's
15
+ * conversation and context (`sendPrompt`, `setModelContext`), and the host's data services, which
16
+ * may be someone else's (`callTool`, `readData`, `subscribeData`: their arguments are the page's).
17
+ * Not here: the person's own clipboard and disk (`copyText`, `downloadFile`), the host's own UI
18
+ * (`annotate`, `resize`, `comments`: the composer is the person's, under the host's duties), and
19
+ * what only reads (`user`). `reportError` is one where the config sends errors to the agent.
20
+ */
21
+ const CARRIERS: readonly CapabilityName[] = [
22
+ "db",
23
+ "artifact",
24
+ "assets",
25
+ "openLink",
26
+ "sendPrompt",
27
+ "setModelContext",
28
+ "callTool",
29
+ "readData",
30
+ "subscribeData",
31
+ ];
32
+
33
+ /**
34
+ * Whether a page shown under `config` with `declaration` may pass on what it is given (P112: a
35
+ * person's draft, which a host shows a page only where it can't). It may when it can reach one of
36
+ * the host functions that carry what it puts in them to others (`CARRIERS`; `reportError` where
37
+ * errors go to the agent), or the network beyond the library CDNs (`LIBRARY_CDNS`): any https site
38
+ * (`anyHttps`), or an origin the host (or a capability) added for connections, scripts, styles,
39
+ * images, fonts or media. A library CDN serves published packages by their path, and its logs are
40
+ * its operator's, not the page author's: not counted. A page reaches a host function the config
41
+ * declares: under the runtime with a declaration, only through a built-in family or one it
42
+ * declared (one no family serves, wherever the config declares it); without a declaration (a page from before 0.7), or without the runtime, every one, as
43
+ * 0.6's globals. The host's rule made checkable: "a page with a channel gets no drafts".
44
+ */
45
+ export function mayPassOn(config: PortholeConfig, declaration: PageDeclaration | null): boolean {
46
+ const declared = (declaration?.capabilities ?? {}) as Readonly<Record<string, unknown>>;
47
+ const reaches = (name: CapabilityName): boolean => {
48
+ if (config.capabilities[name] === undefined) {
49
+ return false;
50
+ }
51
+ if (config.runtime === undefined || declaration === null) {
52
+ return true;
53
+ }
54
+ // One no runtime family serves (`reportError`: the shell reports what the page throws) is
55
+ // the page's wherever the config declares it.
56
+ const family = familyOf(name);
57
+ return (
58
+ family === null ||
59
+ runtimeCapability(family.name).builtIn ||
60
+ declared[family.name] !== undefined
61
+ );
62
+ };
63
+ if (CARRIERS.some(reaches) || (config.errors === "agent" && reaches("reportError"))) {
64
+ return true;
65
+ }
66
+ if ((config.egress.anyHttps ?? []).length > 0) {
67
+ return true;
68
+ }
69
+ return KINDS.some((kind) => {
70
+ const cdns = new Set(LIBRARY_CDNS[kind] ?? []);
71
+ return egressOrigins(config, kind).some((origin) => !cdns.has(origin));
72
+ });
73
+ }
package/src/host/types.ts CHANGED
@@ -209,6 +209,13 @@ export interface DisplayEvents {
209
209
  * runs it again).
210
210
  */
211
211
  readonly focusTaken: { readonly typing: boolean };
212
+ /**
213
+ * Whether the page touched `localStorage` or `sessionStorage` (the in-memory stand-in of a frame
214
+ * without storage of its own: opaque, or a nested page, P111): once per run, `used: true` when
215
+ * the page first did, else `used: false` as the run ends. Never what it kept: for a host to count
216
+ * the pages that would need storage.
217
+ */
218
+ readonly storage: { readonly used: boolean };
212
219
  /**
213
220
  * What the frame reported about annotations (`annotate`, P053), checked and taken only while
214
221
  * the host asked for it: a selection, its clearing, a cancelled pick, where marks are. The
@@ -229,8 +236,22 @@ export interface AnnotationControls {
229
236
  show(marks: readonly AnnotationMark[]): void;
230
237
  /** Brings a mark into view in the frame and makes it the active one. */
231
238
  focus(id: string): void;
239
+ /**
240
+ * Follows one shown mark (P112): while it moves (a scroll, a layout change) the display reports
241
+ * `{ type: "tracked", id, rect }` at most once per animation frame (60 a second), its box clamped
242
+ * to the frame, for that mark only; `null` stops. One at a time: a new id replaces the last.
243
+ * Throws for an id no shown mark has; a `show` without it, or `clear`, stops it.
244
+ */
245
+ track(id: string | null): void;
232
246
  /** Removes every mark. */
233
247
  clear(): void;
248
+ /**
249
+ * Takes the page's text selection away (P115), its highlight with it: for when the host has
250
+ * used it (a comment posted, a draft added). No `unselected` follows; marks (posted and drafts),
251
+ * the mode and a followed mark stay as they are. Nothing selected: nothing happens. Not kept for
252
+ * a frame that runs later (it has no selection to clear).
253
+ */
254
+ clearSelection(): void;
234
255
  }
235
256
 
236
257
  export interface DisplayControls {
@@ -270,4 +291,10 @@ export interface PortholeHost<C extends AdapterConnection = ShellConnection> {
270
291
  * none (here or in the host's options), so a manual never teaches a function nobody serves.
271
292
  */
272
293
  mount(container: HTMLElement, options: MountOptions): DisplayHandle<C>;
294
+ /**
295
+ * Whether a page with `declaration` may pass on what it is given (`mayPassOn`, P112): true where
296
+ * it can store what others read (`db` and `user`) or reaches the network beyond the library CDNs.
297
+ * A host shows such a page none of a person's drafts.
298
+ */
299
+ mayPassOn(declaration: PageDeclaration | null): boolean;
273
300
  }
package/src/index.ts CHANGED
@@ -50,7 +50,9 @@ export {
50
50
  type UrlSandboxExtra,
51
51
  } from "./config/schema.ts";
52
52
  export { hostOriginProblem, isHostOrigin } from "./isolation/served.ts";
53
- export { FRAME_STATUS_METHOD } from "./isolation/types.ts";
53
+ export { FRAME_STATUS_METHOD, SHELL_STATE_METHOD, STORAGE_USED_METHOD } from "./isolation/types.ts";
54
+ export { PAGE_SANDBOX_TOKENS } from "./compile/policy.ts";
55
+ export { SHELL_GESTURE_MS } from "./platform/focus-guard.ts";
54
56
 
55
57
  // The capability runtime (P085-P090): its contract, levels, a page's declaration, its services'
56
58
  // shapes. Hosts implement the services; Porthole carries, checks and gates the calls.
@@ -275,6 +277,7 @@ export type {
275
277
  DbContext,
276
278
  } from "./bridge/types.ts";
277
279
  export { createHost } from "./host/create-host.ts";
280
+ export { mayPassOn } from "./host/pass-on.ts";
278
281
  export { focusField } from "./platform/focus-guard.ts";
279
282
  // The client half of the host kit, and the display registry (P072).
280
283
  export {
@@ -74,6 +74,18 @@ export interface FrameLocation {
74
74
  /** The message a served page sends its host about loading (own-prefixed, P040). */
75
75
  export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
76
76
 
77
+ /** A nested page's shell's report of its own state to the host (P111). */
78
+ export const SHELL_STATE_METHOD = "porthole/shell/state";
79
+
80
+ /** A nested page's shell's heartbeat, every 50 ms while it runs (P111, after its review). */
81
+ export const SHELL_BEAT_METHOD = "porthole/shell/beat";
82
+
83
+ /** The shell's own namespace (P111): the shell drops a page's message that names a method in it. */
84
+ export const SHELL_METHOD_PREFIX = "porthole/shell/";
85
+
86
+ /** A page's word that it used storage, once per load (P111): never a key or a value. */
87
+ export const STORAGE_USED_METHOD = "porthole/storage-used";
88
+
77
89
  /**
78
90
  * Turns an instance into the URL its frame loads. Implemented by the host, usually by asking its
79
91
  * own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called on every