@botiverse/porthole 0.5.0 → 0.6.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.
Files changed (90) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.d.ts +12 -4
  3. package/dist/bridge/bridge.js +62 -27
  4. package/dist/bridge/navigation.d.ts +6 -0
  5. package/dist/bridge/navigation.js +41 -0
  6. package/dist/bridge/refusal.d.ts +53 -0
  7. package/dist/bridge/refusal.js +121 -0
  8. package/dist/bridge/types.d.ts +7 -0
  9. package/dist/check/check.d.ts +12 -3
  10. package/dist/check/check.js +54 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/lint.js +27 -10
  14. package/dist/check/page-source.js +1 -1
  15. package/dist/check/page.js +5 -0
  16. package/dist/check/tools.d.ts +23 -0
  17. package/dist/check/tools.js +25 -0
  18. package/dist/compile/policy.d.ts +15 -0
  19. package/dist/compile/policy.js +32 -0
  20. package/dist/config/capabilities.d.ts +5 -0
  21. package/dist/config/schema.d.ts +8 -0
  22. package/dist/config/validate.js +8 -1
  23. package/dist/conformance/harness-source.js +1 -1
  24. package/dist/files/paths.d.ts +99 -0
  25. package/dist/files/paths.js +263 -0
  26. package/dist/files/types.d.ts +24 -0
  27. package/dist/files/types.js +83 -0
  28. package/dist/guide/guide.js +25 -5
  29. package/dist/host/create-host.js +36 -4
  30. package/dist/host/types.d.ts +15 -2
  31. package/dist/index.d.ts +7 -3
  32. package/dist/index.js +10 -3
  33. package/dist/mcp/adapter.js +22 -7
  34. package/dist/protocol/adapter.d.ts +4 -0
  35. package/dist/protocol/mcp-apps.d.ts +12 -0
  36. package/dist/protocol/mcp-apps.js +12 -0
  37. package/dist/protocol/shell-adapter.js +18 -2
  38. package/dist/react/frame.d.ts +19 -4
  39. package/dist/react/frame.js +37 -9
  40. package/dist/server/files.d.ts +44 -0
  41. package/dist/server/files.js +244 -0
  42. package/dist/server/host.d.ts +38 -1
  43. package/dist/server/host.js +37 -2
  44. package/dist/server/index.d.ts +4 -2
  45. package/dist/server/index.js +4 -1
  46. package/dist/server/keys.d.ts +8 -0
  47. package/dist/server/keys.js +34 -0
  48. package/dist/server/server.js +287 -22
  49. package/dist/server/types.d.ts +49 -5
  50. package/dist/shell/document.d.ts +19 -0
  51. package/dist/shell/document.js +30 -0
  52. package/dist/shell/runtime.d.ts +2 -1
  53. package/dist/shell/runtime.js +117 -10
  54. package/docs/ADOPTING.md +95 -13
  55. package/docs/ARCHITECTURE.md +13 -3
  56. package/docs/DECISIONS.md +396 -4
  57. package/docs/DESIGN.md +43 -10
  58. package/package.json +1 -1
  59. package/src/bridge/bridge.ts +74 -23
  60. package/src/bridge/navigation.ts +46 -0
  61. package/src/bridge/refusal.ts +151 -0
  62. package/src/bridge/types.ts +12 -1
  63. package/src/check/check.ts +92 -14
  64. package/src/check/files.ts +384 -0
  65. package/src/check/lint.ts +29 -10
  66. package/src/check/page.ts +7 -0
  67. package/src/check/tools.ts +50 -0
  68. package/src/compile/policy.ts +38 -0
  69. package/src/config/capabilities.ts +5 -1
  70. package/src/config/schema.ts +8 -0
  71. package/src/config/validate.ts +8 -1
  72. package/src/files/paths.ts +323 -0
  73. package/src/files/types.ts +101 -0
  74. package/src/guide/guide.ts +38 -4
  75. package/src/host/create-host.ts +37 -4
  76. package/src/host/types.ts +13 -2
  77. package/src/index.ts +41 -0
  78. package/src/mcp/adapter.ts +26 -6
  79. package/src/protocol/adapter.ts +3 -1
  80. package/src/protocol/mcp-apps.ts +14 -0
  81. package/src/protocol/shell-adapter.ts +20 -2
  82. package/src/react/frame.tsx +53 -14
  83. package/src/server/files.ts +312 -0
  84. package/src/server/host.ts +72 -3
  85. package/src/server/index.ts +19 -0
  86. package/src/server/keys.ts +53 -0
  87. package/src/server/server.ts +353 -24
  88. package/src/server/types.ts +56 -4
  89. package/src/shell/document.ts +53 -0
  90. package/src/shell/runtime.ts +117 -10
package/src/index.ts CHANGED
@@ -67,6 +67,30 @@ export {
67
67
  type VendoredLibrary,
68
68
  } from "./libraries/libraries.ts";
69
69
 
70
+ // A version made of files (P081): the rules its paths follow, its limits and its types.
71
+ export {
72
+ checkFileSet,
73
+ DEFAULT_ENTRY,
74
+ DEFAULT_MAX_FILE_BYTES,
75
+ DEFAULT_MAX_FILES,
76
+ DEFAULT_MAX_VERSION_BYTES,
77
+ fileLimits,
78
+ filePathProblem,
79
+ lookupFile,
80
+ requestFilePath,
81
+ servesFiles,
82
+ type FileLimits,
83
+ type FileLookup,
84
+ type FileSetProblem,
85
+ } from "./files/paths.ts";
86
+ export {
87
+ fileTypeOf,
88
+ KNOWN_EXTENSIONS,
89
+ UNKNOWN_TYPE,
90
+ type FileRole,
91
+ type FileType,
92
+ } from "./files/types.ts";
93
+
70
94
  // The compiler.
71
95
  export { compile, type CompiledConfig } from "./compile/compile.ts";
72
96
  export {
@@ -77,6 +101,9 @@ export {
77
101
  egressOrigins,
78
102
  embedderCsp,
79
103
  embedderFrameSourcesOf,
104
+ FILE_SET_DIRECTIVES,
105
+ fileSetCspDirectives,
106
+ INERT_FILE_CSP,
80
107
  type CspDirective,
81
108
  type EgressKind,
82
109
  } from "./compile/policy.ts";
@@ -122,10 +149,20 @@ export {
122
149
  MCP_APPS_METHODS,
123
150
  MCP_APPS_PROTOCOL_VERSION,
124
151
  MCP_APPS_STYLE_VARIABLES,
152
+ NAVIGATING_METHOD,
153
+ NAVIGATION_BLOCKED_METHOD,
125
154
  PORTHOLE_STYLES,
126
155
  STALE_META,
127
156
  type HostContext,
128
157
  } from "./protocol/mcp-apps.ts";
158
+ // Why a call was refused, as content is told it, and the host's own refusals (P080).
159
+ export {
160
+ REFUSAL_CODES,
161
+ Refused,
162
+ isRefused,
163
+ type RefusalCode,
164
+ type RefusalReason,
165
+ } from "./bridge/refusal.ts";
129
166
  export type {
130
167
  CallContext,
131
168
  CallOptions,
@@ -157,8 +194,12 @@ export {
157
194
  export { defineDisplays, type DisplayKind, type Displays } from "./displays/displays.ts";
158
195
  // The agent's side: what content can be told without running it, and its tools (P073).
159
196
  export { fragmentOf, lintContent, type Finding, type LintRule } from "./check/lint.ts";
197
+ // A page that comes with files (P081): its lint, without running it.
198
+ export { lintFiles, type FileContents, type FileFinding } from "./check/files.ts";
160
199
  export {
161
200
  admitContent,
201
+ admitFiles,
202
+ type AdmitFilesResult,
162
203
  answerGuide,
163
204
  checkTool,
164
205
  guideChanges,
@@ -14,8 +14,13 @@ import {
14
14
  MCP_APPS_PROTOCOL_VERSION,
15
15
  type HostContext,
16
16
  } from "../protocol/mcp-apps.ts";
17
- import { COPY_TEXT_METHOD, MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.ts";
17
+ import {
18
+ COPY_TEXT_METHOD,
19
+ MCP_APPS_STYLE_VARIABLES,
20
+ NAVIGATION_BLOCKED_METHOD,
21
+ } from "../protocol/mcp-apps.ts";
18
22
  import { liveData } from "../protocol/live-data.ts";
23
+ import { reasonFor } from "../bridge/refusal.ts";
19
24
 
20
25
  /**
21
26
  * The MCP Apps adapter (P004, P007): the host side of the protocol for full MCP Apps views, written
@@ -190,12 +195,13 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
190
195
  refuse(request.id, JSON_RPC_ERRORS.internal, `${request.method} failed`);
191
196
  return;
192
197
  }
193
- reply(request, outcome, result);
198
+ reply(request, capability, outcome, result);
194
199
  }
195
200
 
196
201
  /** Answers a request with a capability's outcome. */
197
202
  function reply(
198
203
  request: JsonRpcRequest,
204
+ capability: CapabilityName,
199
205
  outcome: CallOutcome<unknown>,
200
206
  result: (value: unknown) => unknown,
201
207
  ): void {
@@ -204,8 +210,17 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
204
210
  } else if (outcome.refusal === "not-declared") {
205
211
  refuse(request.id, JSON_RPC_ERRORS.methodNotFound, `${request.method} isn't offered here`);
206
212
  } else {
207
- // The spec's "implementation-defined" error for a refused request.
208
- refuse(request.id, -32_000, `${request.method} refused (${outcome.refusal})`);
213
+ // The spec's "implementation-defined" error for a refused request, with why in its data
214
+ // (`{ code, message }`, P080).
215
+ send({
216
+ jsonrpc: "2.0",
217
+ id: request.id,
218
+ error: {
219
+ code: -32_000,
220
+ message: `${request.method} refused (${outcome.refusal})`,
221
+ data: reasonFor(capability, outcome),
222
+ },
223
+ });
209
224
  }
210
225
  }
211
226
 
@@ -275,7 +290,7 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
275
290
  invalid("needs a uri");
276
291
  return;
277
292
  }
278
- reply(request, await live.read(params.uri), (value) =>
293
+ reply(request, "readData", await live.read(params.uri), (value) =>
279
294
  isRecord(value) ? value : { contents: [] },
280
295
  );
281
296
  return;
@@ -298,7 +313,7 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
298
313
  answer(request.id, {});
299
314
  return;
300
315
  }
301
- reply(request, await live.subscribe(params.uri), () => ({}));
316
+ reply(request, "subscribeData", await live.subscribe(params.uri), () => ({}));
302
317
  return;
303
318
  case MCP_APPS_METHODS.updateModelContext:
304
319
  if (
@@ -388,6 +403,11 @@ function connect(session: AdapterSession, options: McpAppsAdapterOptions): McpAp
388
403
  });
389
404
  }
390
405
  return;
406
+ case NAVIGATION_BLOCKED_METHOD:
407
+ // The shell, hardening the view's frame, stopped a navigation (P080): an error report,
408
+ // with its address.
409
+ void bridge.call("reportError", { navigationBlocked: params.url });
410
+ return;
391
411
  case MCP_APPS_METHODS.requestTeardown:
392
412
  session.emit({ type: "teardown-requested" });
393
413
  return;
@@ -40,7 +40,9 @@ export type AdapterEvent =
40
40
  /** The view finished its handshake; content may be sent. */
41
41
  | { readonly type: "initialized" }
42
42
  /** The view asked to be closed. */
43
- | { readonly type: "teardown-requested" };
43
+ | { readonly type: "teardown-requested" }
44
+ /** A page that came with files is opening another page of its set in the frame (P084). */
45
+ | { readonly type: "navigating" };
44
46
 
45
47
  /** What the framework drives on every adapter. Adapters add their protocol's own operations. */
46
48
  export interface AdapterConnection {
@@ -133,6 +133,20 @@ export const COPY_TEXT_METHOD = "porthole/copy-text";
133
133
  */
134
134
  export const STALE_META = "porthole/stale";
135
135
 
136
+ /**
137
+ * Porthole's own notification from the shell (P080): it cancelled a navigation of the frame to
138
+ * `{ url }` (P079). The content's word, sent only where `reportError` is declared, and counted as
139
+ * one of its reports; the host's adapter carries it into `reportError`.
140
+ */
141
+ export const NAVIGATION_BLOCKED_METHOD = "porthole/navigation-blocked";
142
+
143
+ /**
144
+ * 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. The host takes the frame's next load for that
146
+ * page rather than for content that left (P031). The content's word: it only spares a restart.
147
+ */
148
+ export const NAVIGATING_METHOD = "porthole/navigating";
149
+
136
150
  /** The logger name the shell's error reports (`notifications/message`, level `error`) carry. */
137
151
  export const SHELL_LOGGER = "porthole";
138
152
 
@@ -8,8 +8,11 @@ import {
8
8
  type JsonRpcRequest,
9
9
  type JsonRpcResponse,
10
10
  } from "./jsonrpc.ts";
11
+ import { reasonFor, type RefusalReason } from "../bridge/refusal.ts";
11
12
  import {
12
13
  COPY_TEXT_METHOD,
14
+ NAVIGATING_METHOD,
15
+ NAVIGATION_BLOCKED_METHOD,
13
16
  MCP_APPS_METHODS as M,
14
17
  MCP_APPS_PROTOCOL_VERSION,
15
18
  type HostContext,
@@ -67,7 +70,7 @@ const REQUESTS: Readonly<
67
70
  function answer(
68
71
  capability: CapabilityName,
69
72
  outcome: CallOutcome<unknown>,
70
- ): { result: unknown } | { error: { code: number; message: string } } {
73
+ ): { result: unknown } | { error: { code: number; message: string; data?: RefusalReason } } {
71
74
  const flagged =
72
75
  capability === "sendPrompt" ||
73
76
  capability === "openLink" ||
@@ -76,7 +79,14 @@ function answer(
76
79
  if (!outcome.ok) {
77
80
  return flagged
78
81
  ? { result: { isError: true } }
79
- : { error: { code: -32000, message: `Refused (${outcome.refusal})` } };
82
+ : {
83
+ // Why, in the error's data (`{ code, message }`, P080).
84
+ error: {
85
+ code: -32000,
86
+ message: `Refused (${outcome.refusal})`,
87
+ data: reasonFor(capability, outcome),
88
+ },
89
+ };
80
90
  }
81
91
  if (flagged) {
82
92
  return { result: outcome.value === true ? {} : { isError: true } };
@@ -236,6 +246,14 @@ export const shellAdapter: ProtocolAdapter<ShellConnection> = {
236
246
  });
237
247
  }
238
248
  return;
249
+ case NAVIGATION_BLOCKED_METHOD:
250
+ // The shell stopped a navigation (P080): an error report, with its address.
251
+ void bridge.call("reportError", { navigationBlocked: params.url });
252
+ return;
253
+ case NAVIGATING_METHOD:
254
+ // Another page of the set opens in the frame (P084): its next load is that page.
255
+ session.emit({ type: "navigating" });
256
+ return;
239
257
  case M.requestTeardown:
240
258
  session.emit({ type: "teardown-requested" });
241
259
  return;
@@ -27,6 +27,7 @@ import type {
27
27
  Proceed,
28
28
  Refusal,
29
29
  } from "../bridge/types.ts";
30
+ import { isRefused, reasonOf, Refused, type RefusalReason } from "../bridge/refusal.ts";
30
31
  import type { CapabilityName } from "../config/capabilities.ts";
31
32
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
32
33
  import { writeClipboard } from "../host/clipboard.ts";
@@ -65,6 +66,8 @@ interface PageState {
65
66
  readonly confirm?: Confirm;
66
67
  /** The provider's consent and cache (P079), read when a frame asks. */
67
68
  readonly consent?: Consent;
69
+ /** The provider's consent is a `Refused` (P080): its reason, by value. */
70
+ readonly refusesAll?: RefusalReason;
68
71
  readonly cached?: DataCache;
69
72
  readonly hostInfo?: { readonly name: string; readonly version: string };
70
73
  readonly nonce?: string;
@@ -127,9 +130,10 @@ export interface PortholeProviderProps {
127
130
  readonly confirm?: Confirm;
128
131
  /**
129
132
  * Whether a frame below may make its `consent`-gated calls (read the viewer's data, P079):
130
- * asked once per display, before the first. Omitted: those calls are refused.
133
+ * asked once per display, before the first. Omitted: those calls are refused. A `Refused`
134
+ * refuses them all with its reason, and their handlers may be left out (P080).
131
135
  */
132
- readonly consent?: Consent;
136
+ readonly consent?: Consent | Refused;
133
137
  /** What the host last had for a resource, answered stale first (P079). */
134
138
  readonly cached?: DataCache;
135
139
  /** How the host names itself in the handshake. */
@@ -204,7 +208,15 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
204
208
  ownConsent.current = props.consent;
205
209
  ownCached.current = props.cached;
206
210
  });
207
- const consent = useCallback<Consent>((request) => ownConsent.current?.(request) ?? false, []);
211
+ const consent = useCallback<Consent>((request) => {
212
+ const given = ownConsent.current;
213
+ if (isRefused(given)) {
214
+ throw given;
215
+ }
216
+ return given?.(request) ?? false;
217
+ }, []);
218
+ // A Refused for every frame below, by value (an inline one starts nothing again).
219
+ const refusesAll = useByValue(isRefused(props.consent) ? reasonOf(props.consent) : undefined);
208
220
  const cached = useCallback<DataCache>((args, context) => ownCached.current?.(args, context), []);
209
221
  const consents = props.consent !== undefined;
210
222
  const caches = props.cached !== undefined;
@@ -284,6 +296,7 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
284
296
  confirm,
285
297
  copyText,
286
298
  ...(consents ? { consent } : {}),
299
+ ...(refusesAll === undefined ? {} : { refusesAll }),
287
300
  ...(caches ? { cached } : {}),
288
301
  ...(hostInfo === undefined ? {} : { hostInfo }),
289
302
  ...(locates ? { locate } : {}),
@@ -301,6 +314,7 @@ export function PortholeProvider(props: PortholeProviderProps): ReactElement {
301
314
  copyText,
302
315
  consents,
303
316
  consent,
317
+ refusesAll,
304
318
  caches,
305
319
  cached,
306
320
  hostInfo,
@@ -401,8 +415,11 @@ export interface PortholeFrameProps {
401
415
  readonly handlers?: CapabilityHandlers;
402
416
  /** Who confirms this frame's gated calls, over the provider's. */
403
417
  readonly confirm?: Confirm;
404
- /** Whether this frame may make its `consent`-gated calls, over the provider's (P079). */
405
- readonly consent?: Consent;
418
+ /**
419
+ * Whether this frame may make its `consent`-gated calls, over the provider's (P079). A `Refused`
420
+ * refuses them all with its reason, and their handlers may be left out (P080).
421
+ */
422
+ readonly consent?: Consent | Refused;
406
423
  /** This frame's data cache, over the provider's (P079). */
407
424
  readonly cached?: DataCache;
408
425
  /** Bump to run the content again from the start. */
@@ -436,6 +453,12 @@ export interface PortholeFrameProps {
436
453
  readonly onError?: (message: string, source: "content" | "host") => void;
437
454
  /** The content navigated its frame away; it was started again (or stopped, after a few). */
438
455
  readonly onNavigated?: () => void;
456
+ /**
457
+ * The shell stopped the content navigating its frame to `url` (P080): the address whole, the
458
+ * content's word. Served frames only, where the config declares `reportError`; `onContentError`
459
+ * hears it too, without the address's query.
460
+ */
461
+ readonly onNavigationBlocked?: (blocked: { readonly url: string }) => void;
439
462
  readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
440
463
  /** Too many declines: the display stops asking until it runs again. */
441
464
  readonly onMuted?: () => void;
@@ -642,6 +665,10 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
642
665
  const config = useByValue(frame.config);
643
666
  const instance = useByValue(frame.instance);
644
667
  const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
668
+ // A consent that refuses everything (P080), this frame's or else the provider's, by value: a
669
+ // display made with it needs no data handlers, so a change makes the display again.
670
+ const ownRefusal = useByValue(isRefused(frame.consent) ? reasonOf(frame.consent) : undefined);
671
+ const refusesAll = frame.consent === undefined ? page.refusesAll : ownRefusal;
645
672
 
646
673
  // The latest props, read when the display calls back (never during render).
647
674
  const latest = useEffectEvent(() => frame);
@@ -691,6 +718,9 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
691
718
  case "navigated":
692
719
  frame.onNavigated?.();
693
720
  return;
721
+ case "navigationBlocked":
722
+ frame.onNavigationBlocked?.(detail as DisplayEvents["navigationBlocked"]);
723
+ return;
694
724
  case "refused": {
695
725
  const { capability, refusal } = detail as DisplayEvents["refused"];
696
726
  frame.onRefused?.(capability, refusal);
@@ -767,15 +797,22 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
767
797
  ),
768
798
  }
769
799
  : {}),
770
- ...(asksConsent
771
- ? {
772
- consent: (request: ConfirmRequest) =>
773
- (latest().consent ?? pageConsent ?? (() => false))({
774
- ...request,
775
- display: { ...request.display, id: latest().displayId, title: latest().title },
776
- }),
777
- }
778
- : {}),
800
+ ...(refusesAll !== undefined
801
+ ? { consent: new Refused(refusesAll.code, refusesAll.message) }
802
+ : asksConsent
803
+ ? {
804
+ consent: (request: ConfirmRequest) => {
805
+ const given = latest().consent ?? pageConsent ?? (() => false);
806
+ if (isRefused(given)) {
807
+ throw given;
808
+ }
809
+ return given({
810
+ ...request,
811
+ display: { ...request.display, id: latest().displayId, title: latest().title },
812
+ });
813
+ },
814
+ }
815
+ : {}),
779
816
  ...(caches
780
817
  ? {
781
818
  cached: (args: { readonly uri: string }, context: CallContext) =>
@@ -805,6 +842,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
805
842
  "resize",
806
843
  "error",
807
844
  "navigated",
845
+ "navigationBlocked",
808
846
  "refused",
809
847
  "muted",
810
848
  "outcome",
@@ -839,6 +877,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
839
877
  pageConfirm,
840
878
  pageConsent,
841
879
  pageCached,
880
+ refusesAll,
842
881
  hostInfo,
843
882
  locate,
844
883
  nonce,