@botiverse/porthole 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. package/README.md +25 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/bridge/bounded-text.d.ts +34 -0
  4. package/dist/bridge/bounded-text.js +188 -0
  5. package/dist/bridge/bridge.d.ts +38 -5
  6. package/dist/bridge/bridge.js +469 -39
  7. package/dist/bridge/json-data.d.ts +28 -0
  8. package/dist/bridge/json-data.js +86 -0
  9. package/dist/bridge/navigation.d.ts +5 -0
  10. package/dist/bridge/navigation.js +7 -0
  11. package/dist/bridge/refusal.d.ts +5 -1
  12. package/dist/bridge/refusal.js +17 -0
  13. package/dist/bridge/types.d.ts +73 -5
  14. package/dist/check/check.d.ts +7 -0
  15. package/dist/check/check.js +1 -0
  16. package/dist/check/instrument.d.ts +3 -0
  17. package/dist/check/lint.js +4 -2
  18. package/dist/check/page-source.js +1 -1
  19. package/dist/check/page.js +16 -0
  20. package/dist/check/tools.js +2 -3
  21. package/dist/compile/compile.d.ts +6 -0
  22. package/dist/compile/compile.js +3 -1
  23. package/dist/compile/policy.d.ts +55 -0
  24. package/dist/compile/policy.js +157 -0
  25. package/dist/config/capabilities.d.ts +85 -7
  26. package/dist/config/capabilities.js +32 -2
  27. package/dist/config/schema.d.ts +35 -0
  28. package/dist/config/validate.d.ts +9 -3
  29. package/dist/config/validate.js +92 -8
  30. package/dist/config/warnings.d.ts +20 -0
  31. package/dist/config/warnings.js +25 -0
  32. package/dist/conformance/behavior.js +46 -1
  33. package/dist/conformance/cookies.d.ts +15 -0
  34. package/dist/conformance/cookies.js +80 -0
  35. package/dist/conformance/harness/page.d.ts +1 -0
  36. package/dist/conformance/harness/page.js +9 -2
  37. package/dist/conformance/harness-source.js +1 -1
  38. package/dist/conformance/host-kit.js +5 -1
  39. package/dist/conformance/index.d.ts +11 -0
  40. package/dist/conformance/index.js +2 -0
  41. package/dist/conformance/limits.js +38 -1
  42. package/dist/conformance/runtime.d.ts +58 -0
  43. package/dist/conformance/runtime.js +324 -0
  44. package/dist/conformance/served.d.ts +2 -0
  45. package/dist/conformance/served.js +737 -4
  46. package/dist/files/paths.js +4 -0
  47. package/dist/guide/gates.d.ts +9 -0
  48. package/dist/guide/gates.js +31 -0
  49. package/dist/guide/guide.d.ts +2 -0
  50. package/dist/guide/guide.js +35 -33
  51. package/dist/guide/limits.js +4 -4
  52. package/dist/guide/runtime.d.ts +13 -0
  53. package/dist/guide/runtime.js +210 -0
  54. package/dist/host/create-host.js +73 -37
  55. package/dist/host/locate.js +8 -0
  56. package/dist/host/locator.js +7 -0
  57. package/dist/host/pages-of-set.d.ts +43 -0
  58. package/dist/host/pages-of-set.js +196 -0
  59. package/dist/host/types.d.ts +26 -1
  60. package/dist/index.d.ts +11 -4
  61. package/dist/index.js +11 -2
  62. package/dist/isolation/types.d.ts +8 -0
  63. package/dist/mcp/adapter.js +11 -15
  64. package/dist/node/index.d.ts +36 -4
  65. package/dist/node/index.js +402 -101
  66. package/dist/presets/presets.d.ts +22 -8
  67. package/dist/presets/presets.js +40 -8
  68. package/dist/protocol/live-data.d.ts +6 -2
  69. package/dist/protocol/live-data.js +20 -1
  70. package/dist/protocol/mcp-apps.d.ts +13 -2
  71. package/dist/protocol/mcp-apps.js +10 -2
  72. package/dist/protocol/message-text.d.ts +8 -0
  73. package/dist/protocol/message-text.js +29 -0
  74. package/dist/protocol/runtime-calls.d.ts +28 -0
  75. package/dist/protocol/runtime-calls.js +116 -0
  76. package/dist/protocol/shell-adapter.js +64 -25
  77. package/dist/react/context-notice.d.ts +32 -0
  78. package/dist/react/context-notice.js +28 -0
  79. package/dist/react/dialog.js +91 -16
  80. package/dist/react/frame.d.ts +25 -1
  81. package/dist/react/frame.js +85 -2
  82. package/dist/react/index.d.ts +2 -1
  83. package/dist/react/index.js +2 -1
  84. package/dist/runtime/contract.d.ts +201 -0
  85. package/dist/runtime/contract.js +245 -0
  86. package/dist/runtime/db.d.ts +188 -0
  87. package/dist/runtime/db.js +502 -0
  88. package/dist/runtime/declaration.d.ts +100 -0
  89. package/dist/runtime/declaration.js +363 -0
  90. package/dist/runtime/levels.d.ts +33 -0
  91. package/dist/runtime/levels.js +41 -0
  92. package/dist/runtime/requests.d.ts +125 -0
  93. package/dist/runtime/requests.js +215 -0
  94. package/dist/runtime/segments.d.ts +8 -0
  95. package/dist/runtime/segments.js +14 -0
  96. package/dist/runtime/types.generated.d.ts +1 -0
  97. package/dist/runtime/types.generated.js +19 -0
  98. package/dist/server/files.d.ts +19 -1
  99. package/dist/server/files.js +115 -6
  100. package/dist/server/host.d.ts +24 -2
  101. package/dist/server/host.js +137 -2
  102. package/dist/server/index.d.ts +3 -2
  103. package/dist/server/index.js +2 -1
  104. package/dist/server/peer.d.ts +4 -0
  105. package/dist/server/peer.js +19 -0
  106. package/dist/server/proxy.d.ts +6 -0
  107. package/dist/server/proxy.js +12 -3
  108. package/dist/server/pseudonym.d.ts +9 -0
  109. package/dist/server/pseudonym.js +20 -0
  110. package/dist/server/server.d.ts +0 -5
  111. package/dist/server/server.js +318 -52
  112. package/dist/server/types.d.ts +74 -2
  113. package/dist/shell/document.d.ts +16 -0
  114. package/dist/shell/document.js +19 -2
  115. package/dist/shell/legacy.d.ts +21 -0
  116. package/dist/shell/legacy.js +63 -0
  117. package/dist/shell/plan.d.ts +17 -1
  118. package/dist/shell/plan.js +13 -2
  119. package/dist/shell/runtime.js +390 -56
  120. package/dist/shell/use.d.ts +15 -0
  121. package/dist/shell/use.js +235 -0
  122. package/docs/ADOPTING.md +205 -15
  123. package/docs/ARCHITECTURE.md +34 -5
  124. package/docs/DECISIONS.md +1867 -11
  125. package/docs/DESIGN.md +137 -17
  126. package/docs/THREAT_MODEL.md +616 -0
  127. package/package.json +16 -3
  128. package/src/bridge/bounded-text.ts +240 -0
  129. package/src/bridge/bridge.ts +601 -51
  130. package/src/bridge/json-data.ts +95 -0
  131. package/src/bridge/navigation.ts +10 -0
  132. package/src/bridge/refusal.ts +17 -0
  133. package/src/bridge/types.ts +76 -5
  134. package/src/check/check.ts +8 -0
  135. package/src/check/instrument.ts +3 -0
  136. package/src/check/lint.ts +4 -2
  137. package/src/check/page.ts +16 -0
  138. package/src/check/tools.ts +2 -3
  139. package/src/compile/compile.ts +9 -1
  140. package/src/compile/policy.ts +177 -0
  141. package/src/config/capabilities.ts +71 -5
  142. package/src/config/schema.ts +35 -0
  143. package/src/config/validate.ts +141 -8
  144. package/src/config/warnings.ts +42 -0
  145. package/src/conformance/behavior.ts +54 -1
  146. package/src/conformance/cookies.ts +93 -0
  147. package/src/conformance/harness/page.ts +11 -2
  148. package/src/conformance/host-kit.ts +10 -1
  149. package/src/conformance/index.ts +17 -0
  150. package/src/conformance/limits.ts +39 -1
  151. package/src/conformance/runtime.ts +594 -0
  152. package/src/conformance/served.ts +888 -4
  153. package/src/files/paths.ts +4 -0
  154. package/src/guide/gates.ts +37 -0
  155. package/src/guide/guide.ts +61 -55
  156. package/src/guide/limits.ts +4 -4
  157. package/src/guide/runtime.ts +253 -0
  158. package/src/host/create-host.ts +88 -36
  159. package/src/host/locate.ts +10 -0
  160. package/src/host/locator.ts +11 -0
  161. package/src/host/pages-of-set.ts +226 -0
  162. package/src/host/types.ts +33 -1
  163. package/src/index.ts +94 -0
  164. package/src/isolation/types.ts +8 -0
  165. package/src/mcp/adapter.ts +16 -20
  166. package/src/node/index.ts +507 -116
  167. package/src/presets/presets.ts +67 -17
  168. package/src/protocol/live-data.ts +31 -3
  169. package/src/protocol/mcp-apps.ts +11 -2
  170. package/src/protocol/message-text.ts +36 -0
  171. package/src/protocol/runtime-calls.ts +141 -0
  172. package/src/protocol/shell-adapter.ts +79 -26
  173. package/src/react/context-notice.tsx +95 -0
  174. package/src/react/dialog.tsx +108 -15
  175. package/src/react/frame.tsx +120 -0
  176. package/src/react/index.ts +8 -1
  177. package/src/runtime/contract.ts +339 -0
  178. package/src/runtime/db.ts +650 -0
  179. package/src/runtime/declaration.ts +516 -0
  180. package/src/runtime/levels.ts +69 -0
  181. package/src/runtime/requests.ts +355 -0
  182. package/src/runtime/segments.ts +17 -0
  183. package/src/runtime/types.generated.ts +19 -0
  184. package/src/server/files.ts +138 -7
  185. package/src/server/host.ts +170 -3
  186. package/src/server/index.ts +4 -0
  187. package/src/server/peer.ts +21 -0
  188. package/src/server/proxy.ts +13 -3
  189. package/src/server/pseudonym.ts +21 -0
  190. package/src/server/server.ts +370 -57
  191. package/src/server/types.ts +73 -2
  192. package/src/shell/document.ts +29 -4
  193. package/src/shell/legacy.ts +64 -0
  194. package/src/shell/plan.ts +37 -3
  195. package/src/shell/runtime.ts +390 -56
  196. package/src/shell/use.ts +235 -0
  197. package/types/runtime/v1/artifact.d.ts +50 -0
  198. package/types/runtime/v1/assets.d.ts +43 -0
  199. package/types/runtime/v1/chat.d.ts +13 -0
  200. package/types/runtime/v1/clipboard.d.ts +14 -0
  201. package/types/runtime/v1/comments.d.ts +24 -0
  202. package/types/runtime/v1/context.d.ts +27 -0
  203. package/types/runtime/v1/data.d.ts +29 -0
  204. package/types/runtime/v1/db.d.ts +110 -0
  205. package/types/runtime/v1/downloads.d.ts +22 -0
  206. package/types/runtime/v1/links.d.ts +13 -0
  207. package/types/runtime/v1/porthole.d.ts +44 -0
  208. package/types/runtime/v1/user.d.ts +19 -0
@@ -12,6 +12,7 @@
12
12
  * one host app.
13
13
  */
14
14
  import type { EgressConfig } from "../config/schema.ts";
15
+ import type { ViewerInfo } from "../runtime/levels.ts";
15
16
  /**
16
17
  * Which document a served frame loads. `preset` names the config it is served under (the server's
17
18
  * `configs`); the artifact and the proxy default to their presets' names.
@@ -70,6 +71,11 @@ export interface FrameLocation {
70
71
  * one that loaded. A host's own gateway may send the same message without this.
71
72
  */
72
73
  readonly reports?: boolean;
74
+ /**
75
+ * Who is viewing, as the host's access decided at issue (P087: `Grant.level`, `Grant.user`):
76
+ * the display's bridge checks each runtime method's level against it.
77
+ */
78
+ readonly viewer?: ViewerInfo;
73
79
  }
74
80
  /** The message a served page sends its host about loading (own-prefixed, P040). */
75
81
  export declare const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
@@ -93,4 +99,6 @@ export type FrameSource = {
93
99
  readonly url: string;
94
100
  readonly origin: string;
95
101
  readonly reports?: boolean;
102
+ /** The issue's viewer (`FrameLocation.viewer`), for the display's bridge. */
103
+ readonly viewer?: ViewerInfo;
96
104
  };
@@ -1,8 +1,9 @@
1
1
  import { egressOrigins } from "../compile/policy.js";
2
2
  import { JSON_RPC_ERRORS, parseJsonRpc, } from "../protocol/jsonrpc.js";
3
- import { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, } from "../protocol/mcp-apps.js";
3
+ import { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MODEL_CONTEXT_OFFERED, } from "../protocol/mcp-apps.js";
4
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 { messageText } from "../protocol/message-text.js";
6
7
  import { reasonFor } from "../bridge/refusal.js";
7
8
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
8
9
  /** Levels of `notifications/message` that are errors: they go to the host as `reportError`. */
@@ -32,12 +33,6 @@ export function viewHostContext(context, toolInfo) {
32
33
  }
33
34
  return out;
34
35
  }
35
- /** The text of a `ui/message`'s content: its text blocks, in order (the spec's examples send one). */
36
- function messageText(content) {
37
- const blocks = Array.isArray(content) ? content : [content];
38
- const texts = blocks.flatMap((block) => isRecord(block) && block.type === "text" && typeof block.text === "string" ? [block.text] : []);
39
- return texts.length === 0 ? null : texts.join("\n\n");
40
- }
41
36
  /** Whether the host page has a live user gesture (a gesture in a frame activates its ancestors). */
42
37
  function hostActivation() {
43
38
  const activation = globalThis
@@ -90,9 +85,7 @@ function connect(session, options) {
90
85
  ? { serverResources: declared("subscribeData") ? { subscribe: true } : {} }
91
86
  : {}),
92
87
  ...(declared("sendPrompt") ? { message: { text: {} } } : {}),
93
- ...(declared("setModelContext")
94
- ? { updateModelContext: { text: {}, structuredContent: {} } }
95
- : {}),
88
+ ...(declared("setModelContext") ? { updateModelContext: MODEL_CONTEXT_OFFERED } : {}),
96
89
  sandbox: {
97
90
  csp: {
98
91
  ...(connectDomains.length > 0 ? { connectDomains } : {}),
@@ -154,7 +147,11 @@ function connect(session, options) {
154
147
  answer(request.id, {});
155
148
  return;
156
149
  case MCP_APPS_METHODS.message: {
157
- const text = params.role === "user" ? messageText(params.content) : null;
150
+ // Its text blocks, in order (the spec's examples send one), read bounded (P095).
151
+ const content = params.content;
152
+ const text = params.role === "user"
153
+ ? messageText(Array.isArray(content) ? content : [content], "\n\n", session.compiled.config.limits.maxPromptChars)
154
+ : null;
158
155
  if (text === null) {
159
156
  invalid('needs role "user" and text content');
160
157
  return;
@@ -277,11 +274,10 @@ function connect(session, options) {
277
274
  return;
278
275
  }
279
276
  case MCP_APPS_METHODS.log:
277
+ // What the view said, as it came (S05, P095): the bridge reads it only within
278
+ // reportError's declaration and rate, into bounded text, and nothing in it throws here.
280
279
  if (typeof params.level === "string" && ERROR_LEVELS.has(params.level)) {
281
- const data = params.data;
282
- void bridge.call("reportError", {
283
- message: (typeof data === "string" ? data : (JSON.stringify(data) ?? "")).slice(0, 2_000),
284
- });
280
+ void bridge.call("reportError", { message: params.data });
285
281
  }
286
282
  return;
287
283
  case NAVIGATION_BLOCKED_METHOD:
@@ -8,6 +8,10 @@
8
8
  * const server = http.createServer(porthole.request);
9
9
  * server.on("upgrade", porthole.upgrade);
10
10
  * server.listen(8080, () => content.start());
11
+ *
12
+ * Nothing a request does throws out of these listeners or ends the process (S01, P092): what fetch
13
+ * can't take is 405 or 400; what fails on the app's side (a handler, a listener, an answer Node
14
+ * can't write) is 500, and `onError` hears it.
11
15
  */
12
16
  import type { IncomingMessage, Server, ServerResponse } from "node:http";
13
17
  import type { Duplex } from "node:stream";
@@ -15,6 +19,12 @@ import type { ContentHost, HealthProbe } from "../server/host.ts";
15
19
  import type { Access } from "../server/types.ts";
16
20
  type RequestListener = (request: IncomingMessage, response: ServerResponse) => void;
17
21
  type UpgradeListener = (request: IncomingMessage, socket: Duplex, head: Buffer) => void;
22
+ /**
23
+ * Hears what failed on the app's side while serving a request (its handler or listener threw or
24
+ * rejected, an answer Node can't write), once the client has its 500. Default: a process warning
25
+ * (`process.emitWarning`). Never the client's to read.
26
+ */
27
+ export type NodeErrorListener = (error: unknown, request: IncomingMessage) => void;
18
28
  export interface NodeHostOptions {
19
29
  /** The app's own request listener (Express, Hono's `getRequestListener`, a router). */
20
30
  readonly request: RequestListener;
@@ -22,6 +32,7 @@ export interface NodeHostOptions {
22
32
  readonly upgrade?: UpgradeListener;
23
33
  /** A url-mode app's WebSocket, once its cookie checks out (`ContentHost.access`). */
24
34
  readonly appSocket?: (access: Access, request: IncomingMessage, socket: Duplex, head: Buffer) => void;
35
+ readonly onError?: NodeErrorListener;
25
36
  }
26
37
  export interface NodeHost {
27
38
  readonly request: RequestListener;
@@ -29,16 +40,36 @@ export interface NodeHost {
29
40
  }
30
41
  /**
31
42
  * The Node request as a fetch `Request`: an absolute-form target kept as it came (P056). `signal`
32
- * (`nodeHost` gives one, aborted when the client goes away) lets an upstream stop its work.
43
+ * (`nodeHost` gives one, aborted when the client goes away) lets an upstream stop its work. The
44
+ * body is read only as it is pulled; cancelled, the rest is dropped (bounded), not the connection.
45
+ * The socket's peer goes with it, for the issue endpoint's rate limit (P092).
46
+ * Throws where fetch can't take the request: a method it can't carry (`TRACE`), a Host or a
47
+ * target that is no URL. `nodeListener`, `nodeHost` and `nodeServer` answer those 405 and 400.
33
48
  */
34
49
  export declare function toRequest(request: IncomingMessage, scheme: "https" | "http", signal?: AbortSignal): Request;
35
50
  /**
36
51
  * Writes a fetch `Response` to a Node response, cookies one header each (P070): it waits for the
37
52
  * socket to drain before reading on (a slow client never makes it buffer the body), cancels the
38
- * body when the client goes away (an event stream ends with the page that asked for it), and on
39
- * an error mid-body destroys the response rather than end it looking complete.
53
+ * body when the client goes away, before the answer or during it (an event stream ends with the
54
+ * page that asked for it), and on an error mid-body destroys the response rather than end it
55
+ * looking complete. A HEAD gets the head and its body is cancelled. Never rejects (P092): an
56
+ * answer it can't write (no Response, a body already read, a header value fetch takes and Node
57
+ * doesn't) is a 500, and `onError` hears why. Once the answer is out, a request body no one read
58
+ * is dropped, bounded, before the connection closes.
59
+ */
60
+ export declare function sendResponse(response: ServerResponse, answer: Response, onError?: (error: unknown) => void): Promise<void>;
61
+ export interface NodeListenerOptions {
62
+ /** The requests' URLs' scheme (default `http`; `https` behind a TLS edge). */
63
+ readonly scheme?: "https" | "http";
64
+ readonly onError?: NodeErrorListener;
65
+ }
66
+ /**
67
+ * A fetch-style handler (Hono's `app.fetch`, the app's own) as a Node request listener: what
68
+ * `toRequest` can't convert is 405 or 400, what the handler throws or the answer's writing fails
69
+ * is 500 (`onError` hears it); nothing it does ends the process (S01, P092). The request's
70
+ * `signal` aborts when the client goes away before the answer is out.
40
71
  */
41
- export declare function sendResponse(response: ServerResponse, answer: Response): Promise<void>;
72
+ export declare function nodeListener(app: (request: Request) => Response | Promise<Response>, options?: NodeListenerOptions): RequestListener;
42
73
  export declare function nodeHost<V>(content: ContentHost<V>, app: NodeHostOptions): NodeHost;
43
74
  /**
44
75
  * The health gate's probe on Node: a GET over the real network (DNS, the edge, TLS with Node's
@@ -66,6 +97,7 @@ export interface NodeServerOptions {
66
97
  readonly appSocket?: NodeHostOptions["appSocket"];
67
98
  /** Whether the app's own requests came over https (behind a TLS edge): their URL's scheme. */
68
99
  readonly scheme?: "https" | "http";
100
+ readonly onError?: NodeErrorListener;
69
101
  }
70
102
  /**
71
103
  * The whole Node server (P072): the content domain to Porthole, everything else to the app, its