@botiverse/porthole 0.5.1 → 0.7.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 (167) hide show
  1. package/README.md +41 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +208 -13
  4. package/dist/bridge/navigation.d.ts +1 -6
  5. package/dist/bridge/navigation.js +11 -0
  6. package/dist/bridge/refusal.d.ts +5 -1
  7. package/dist/bridge/refusal.js +16 -0
  8. package/dist/bridge/types.d.ts +41 -4
  9. package/dist/check/check.d.ts +19 -3
  10. package/dist/check/check.js +55 -8
  11. package/dist/check/files.d.ts +26 -0
  12. package/dist/check/files.js +307 -0
  13. package/dist/check/instrument.d.ts +3 -0
  14. package/dist/check/lint.js +31 -12
  15. package/dist/check/page-source.js +1 -1
  16. package/dist/check/page.js +14 -0
  17. package/dist/check/tools.d.ts +23 -0
  18. package/dist/check/tools.js +27 -3
  19. package/dist/compile/policy.d.ts +34 -0
  20. package/dist/compile/policy.js +74 -0
  21. package/dist/config/capabilities.d.ts +62 -3
  22. package/dist/config/capabilities.js +20 -0
  23. package/dist/config/schema.d.ts +32 -0
  24. package/dist/config/validate.d.ts +1 -1
  25. package/dist/config/validate.js +74 -5
  26. package/dist/conformance/harness-source.js +1 -1
  27. package/dist/conformance/index.d.ts +1 -0
  28. package/dist/conformance/index.js +2 -0
  29. package/dist/conformance/runtime.d.ts +58 -0
  30. package/dist/conformance/runtime.js +314 -0
  31. package/dist/files/paths.d.ts +99 -0
  32. package/dist/files/paths.js +263 -0
  33. package/dist/files/types.d.ts +24 -0
  34. package/dist/files/types.js +83 -0
  35. package/dist/guide/gates.d.ts +3 -0
  36. package/dist/guide/gates.js +19 -0
  37. package/dist/guide/guide.d.ts +2 -0
  38. package/dist/guide/guide.js +44 -32
  39. package/dist/guide/limits.js +4 -4
  40. package/dist/guide/runtime.d.ts +13 -0
  41. package/dist/guide/runtime.js +202 -0
  42. package/dist/host/create-host.js +45 -0
  43. package/dist/host/locate.js +8 -0
  44. package/dist/host/locator.js +7 -0
  45. package/dist/host/types.d.ts +18 -0
  46. package/dist/index.d.ts +13 -4
  47. package/dist/index.js +16 -3
  48. package/dist/isolation/types.d.ts +8 -0
  49. package/dist/presets/presets.d.ts +6 -0
  50. package/dist/presets/presets.js +1 -0
  51. package/dist/protocol/adapter.d.ts +4 -0
  52. package/dist/protocol/mcp-apps.d.ts +6 -0
  53. package/dist/protocol/mcp-apps.js +6 -0
  54. package/dist/protocol/runtime-calls.d.ts +28 -0
  55. package/dist/protocol/runtime-calls.js +113 -0
  56. package/dist/protocol/shell-adapter.js +52 -3
  57. package/dist/react/dialog.js +31 -0
  58. package/dist/react/frame.d.ts +13 -0
  59. package/dist/react/frame.js +6 -0
  60. package/dist/runtime/contract.d.ts +193 -0
  61. package/dist/runtime/contract.js +216 -0
  62. package/dist/runtime/db.d.ts +153 -0
  63. package/dist/runtime/db.js +398 -0
  64. package/dist/runtime/declaration.d.ts +86 -0
  65. package/dist/runtime/declaration.js +266 -0
  66. package/dist/runtime/levels.d.ts +33 -0
  67. package/dist/runtime/levels.js +41 -0
  68. package/dist/runtime/requests.d.ts +125 -0
  69. package/dist/runtime/requests.js +199 -0
  70. package/dist/runtime/segments.d.ts +8 -0
  71. package/dist/runtime/segments.js +14 -0
  72. package/dist/runtime/types.generated.d.ts +1 -0
  73. package/dist/runtime/types.generated.js +19 -0
  74. package/dist/server/files.d.ts +57 -0
  75. package/dist/server/files.js +338 -0
  76. package/dist/server/host.d.ts +44 -2
  77. package/dist/server/host.js +42 -2
  78. package/dist/server/index.d.ts +5 -2
  79. package/dist/server/index.js +5 -1
  80. package/dist/server/keys.d.ts +8 -0
  81. package/dist/server/keys.js +34 -0
  82. package/dist/server/pseudonym.d.ts +9 -0
  83. package/dist/server/pseudonym.js +20 -0
  84. package/dist/server/server.d.ts +0 -5
  85. package/dist/server/server.js +468 -24
  86. package/dist/server/types.d.ts +118 -5
  87. package/dist/shell/document.d.ts +27 -0
  88. package/dist/shell/document.js +46 -2
  89. package/dist/shell/legacy.d.ts +21 -0
  90. package/dist/shell/legacy.js +63 -0
  91. package/dist/shell/plan.d.ts +17 -1
  92. package/dist/shell/plan.js +13 -2
  93. package/dist/shell/runtime.d.ts +2 -1
  94. package/dist/shell/runtime.js +114 -46
  95. package/dist/shell/use.d.ts +15 -0
  96. package/dist/shell/use.js +235 -0
  97. package/docs/ADOPTING.md +142 -5
  98. package/docs/ARCHITECTURE.md +34 -5
  99. package/docs/DECISIONS.md +716 -7
  100. package/docs/DESIGN.md +97 -3
  101. package/package.json +3 -1
  102. package/src/bridge/bridge.ts +281 -17
  103. package/src/bridge/navigation.ts +12 -0
  104. package/src/bridge/refusal.ts +16 -0
  105. package/src/bridge/types.ts +46 -4
  106. package/src/check/check.ts +100 -14
  107. package/src/check/files.ts +384 -0
  108. package/src/check/instrument.ts +3 -0
  109. package/src/check/lint.ts +33 -12
  110. package/src/check/page.ts +14 -0
  111. package/src/check/tools.ts +52 -3
  112. package/src/compile/policy.ts +92 -0
  113. package/src/config/capabilities.ts +49 -2
  114. package/src/config/schema.ts +32 -0
  115. package/src/config/validate.ts +107 -5
  116. package/src/conformance/index.ts +7 -0
  117. package/src/conformance/runtime.ts +573 -0
  118. package/src/files/paths.ts +323 -0
  119. package/src/files/types.ts +101 -0
  120. package/src/guide/gates.ts +25 -0
  121. package/src/guide/guide.ts +78 -52
  122. package/src/guide/limits.ts +4 -4
  123. package/src/guide/runtime.ts +244 -0
  124. package/src/host/create-host.ts +55 -0
  125. package/src/host/locate.ts +10 -0
  126. package/src/host/locator.ts +11 -0
  127. package/src/host/types.ts +18 -0
  128. package/src/index.ts +121 -0
  129. package/src/isolation/types.ts +8 -0
  130. package/src/presets/presets.ts +7 -0
  131. package/src/protocol/adapter.ts +3 -1
  132. package/src/protocol/mcp-apps.ts +7 -0
  133. package/src/protocol/runtime-calls.ts +138 -0
  134. package/src/protocol/shell-adapter.ts +56 -2
  135. package/src/react/dialog.tsx +33 -0
  136. package/src/react/frame.tsx +19 -0
  137. package/src/runtime/contract.ts +305 -0
  138. package/src/runtime/db.ts +530 -0
  139. package/src/runtime/declaration.ts +378 -0
  140. package/src/runtime/levels.ts +69 -0
  141. package/src/runtime/requests.ts +339 -0
  142. package/src/runtime/segments.ts +17 -0
  143. package/src/runtime/types.generated.ts +19 -0
  144. package/src/server/files.ts +425 -0
  145. package/src/server/host.ts +84 -3
  146. package/src/server/index.ts +22 -0
  147. package/src/server/keys.ts +53 -0
  148. package/src/server/pseudonym.ts +21 -0
  149. package/src/server/server.ts +565 -26
  150. package/src/server/types.ts +124 -4
  151. package/src/shell/document.ts +74 -4
  152. package/src/shell/legacy.ts +64 -0
  153. package/src/shell/plan.ts +37 -3
  154. package/src/shell/runtime.ts +114 -46
  155. package/src/shell/use.ts +235 -0
  156. package/types/runtime/v1/artifact.d.ts +50 -0
  157. package/types/runtime/v1/assets.d.ts +43 -0
  158. package/types/runtime/v1/chat.d.ts +13 -0
  159. package/types/runtime/v1/clipboard.d.ts +14 -0
  160. package/types/runtime/v1/comments.d.ts +24 -0
  161. package/types/runtime/v1/context.d.ts +16 -0
  162. package/types/runtime/v1/data.d.ts +29 -0
  163. package/types/runtime/v1/db.d.ts +110 -0
  164. package/types/runtime/v1/downloads.d.ts +22 -0
  165. package/types/runtime/v1/links.d.ts +13 -0
  166. package/types/runtime/v1/porthole.d.ts +44 -0
  167. package/types/runtime/v1/user.d.ts +19 -0
@@ -0,0 +1,113 @@
1
+ import { reasonFor } from "../bridge/refusal.js";
2
+ import { RUNTIME_CAPABILITIES, RUNTIME_EVENT_METHOD, isRuntimeCapabilityName, } from "../runtime/contract.js";
3
+ import { DB_LIMITS } from "../runtime/db.js";
4
+ import { downloadContents } from "../runtime/requests.js";
5
+ /**
6
+ * The host side of the capability runtime's calls (P085): `porthole/call` with `{ capability,
7
+ * method, args }` (and `watch`, a frame-chosen id, for a subscription), each turned into the host
8
+ * function that serves it and passed through the bridge, which alone decides; `porthole/unwatch`
9
+ * ends a watch. A watch's updates go to the frame as `porthole/event` with `{ watch, data }`.
10
+ */
11
+ const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
12
+ /** A runtime call as the host function that serves it gets it, or null for none. */
13
+ export function runtimeCall(capability, method, args) {
14
+ if (!isRuntimeCapabilityName(capability) || typeof method !== "string") {
15
+ return null;
16
+ }
17
+ const methods = RUNTIME_CAPABILITIES[capability].methods;
18
+ const spec = Object.hasOwn(methods, method) ? methods[method] : undefined;
19
+ // `data.subscribe` is MCP's own subscription (resources/subscribe, P079), not a runtime call.
20
+ if (spec === undefined || spec.serves === "subscribeData") {
21
+ return null;
22
+ }
23
+ const given = isRecord(args) ? args : {};
24
+ const watch = spec.watch === true;
25
+ switch (spec.serves) {
26
+ case "downloadFile":
27
+ return {
28
+ serves: spec.serves,
29
+ args: { contents: downloadContents(given.file) ?? undefined },
30
+ watch,
31
+ };
32
+ case "callTool":
33
+ return { serves: spec.serves, args: { name: given.name, arguments: given.arguments }, watch };
34
+ case "readData":
35
+ return { serves: spec.serves, args: { uri: given.uri }, watch };
36
+ case "artifact":
37
+ case "assets":
38
+ case "db":
39
+ // One host function serves several methods: the method is its `op`.
40
+ return { serves: spec.serves, args: { ...given, op: method }, watch };
41
+ default:
42
+ return { serves: spec.serves, args: given, watch };
43
+ }
44
+ }
45
+ /** A runtime call's outcome, as the frame hears it: its value, or why it was refused (P080). */
46
+ export function runtimeAnswer(serves, outcome) {
47
+ if (!outcome.ok) {
48
+ return {
49
+ error: {
50
+ code: -32000,
51
+ message: `Refused (${outcome.refusal})`,
52
+ data: reasonFor(serves, outcome),
53
+ },
54
+ };
55
+ }
56
+ return { result: { value: outcome.value ?? null } };
57
+ }
58
+ const refused = (reason) => ({
59
+ error: { code: -32000, message: `Refused (${reason.code})`, data: reason },
60
+ });
61
+ /** One frame's runtime calls: its watches, and their end. */
62
+ export function runtimeCalls(bridge, notify) {
63
+ const watches = new Map();
64
+ return {
65
+ async call(params) {
66
+ const mapped = runtimeCall(params.capability, params.method, params.args);
67
+ if (mapped === null) {
68
+ return refused({ code: "not_allowed", message: "This isn't available here." });
69
+ }
70
+ if (!mapped.watch) {
71
+ return runtimeAnswer(mapped.serves, await bridge.call(mapped.serves, mapped.args));
72
+ }
73
+ const id = params.watch;
74
+ if (typeof id !== "string" || !/^[\w-]{1,64}$/u.test(id) || watches.has(id)) {
75
+ return refused({ code: "not_allowed", message: "The app can't take this request." });
76
+ }
77
+ if (watches.size >= DB_LIMITS.maxWatches) {
78
+ return refused({ code: "too_large", message: "Too many things followed at once." });
79
+ }
80
+ const controller = new AbortController();
81
+ watches.set(id, controller);
82
+ const outcome = await bridge.call(mapped.serves, mapped.args, {
83
+ subscription: {
84
+ changed: (data) => {
85
+ if (!controller.signal.aborted) {
86
+ notify(RUNTIME_EVENT_METHOD, { watch: id, data: data ?? null });
87
+ }
88
+ },
89
+ signal: controller.signal,
90
+ },
91
+ });
92
+ if (!outcome.ok) {
93
+ controller.abort();
94
+ watches.delete(id);
95
+ }
96
+ return outcome.ok ? { result: { value: null } } : runtimeAnswer(mapped.serves, outcome);
97
+ },
98
+ /** The frame stopped following (never gated). */
99
+ unwatch(params) {
100
+ const id = params.watch;
101
+ if (typeof id === "string") {
102
+ watches.get(id)?.abort();
103
+ watches.delete(id);
104
+ }
105
+ },
106
+ close() {
107
+ for (const controller of watches.values()) {
108
+ controller.abort();
109
+ }
110
+ watches.clear();
111
+ },
112
+ };
113
+ }
@@ -1,7 +1,9 @@
1
1
  import { JSON_RPC_ERRORS, parseJsonRpc, } from "./jsonrpc.js";
2
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
+ import { COPY_TEXT_METHOD, NAVIGATING_METHOD, NAVIGATION_BLOCKED_METHOD, MCP_APPS_METHODS as M, MCP_APPS_PROTOCOL_VERSION, } from "./mcp-apps.js";
4
4
  import { liveData } from "./live-data.js";
5
+ import { runtimeCalls } from "./runtime-calls.js";
6
+ import { RUNTIME_CALL_METHOD, RUNTIME_EXPERIMENTAL_KEY, RUNTIME_UNWATCH_METHOD, } from "../runtime/contract.js";
5
7
  /**
6
8
  * The core's adapter: the host side of the MCP Apps subset the shell speaks, which content using
7
9
  * the official App SDK speaks too. Every message is checked before use; every power goes through
@@ -108,7 +110,20 @@ export const shellAdapter = {
108
110
  const respond = (id, body) => transport.send({ jsonrpc: "2.0", id, ...body });
109
111
  const notify = (method, params) => transport.send({ jsonrpc: "2.0", method, params });
110
112
  // Live data (P079): reads, subscriptions and the host's updates, through the bridge.
111
- const live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
113
+ let live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
114
+ // The capability runtime (P085), where the config has one: its calls and watches.
115
+ const runtime = session.compiled.config.runtime;
116
+ let calls = runtimeCalls(bridge, notify);
117
+ // A new page on the same transport (another of the set's pages, P084; or a reload that says
118
+ // hello again) starts with nothing followed: the last page's watches and subscriptions end,
119
+ // so it never hears their updates or their refusals (after the review).
120
+ let greeted = false;
121
+ const forget = () => {
122
+ calls.close();
123
+ calls = runtimeCalls(bridge, notify);
124
+ live.close();
125
+ live = liveData(bridge, (uri) => notify(M.resourceUpdated, { uri }));
126
+ };
112
127
  const flush = () => {
113
128
  if (!initialized || closed || content === null || sentWhole) {
114
129
  return;
@@ -126,11 +141,28 @@ export const shellAdapter = {
126
141
  const onRequest = async (request) => {
127
142
  const params = request.params ?? {};
128
143
  if (request.method === M.initialize) {
144
+ if (greeted) {
145
+ forget();
146
+ }
147
+ greeted = true;
129
148
  respond(request.id, {
130
149
  result: {
131
150
  protocolVersion: MCP_APPS_PROTOCOL_VERSION,
132
151
  hostInfo: session.hostInfo,
133
- hostCapabilities: hostCapabilities((name) => bridge.declared(name)),
152
+ hostCapabilities: {
153
+ ...hostCapabilities((name) => bridge.declared(name)),
154
+ // What this display's page may `use`, in MCP Apps' extension point (P085).
155
+ ...(runtime === undefined
156
+ ? {}
157
+ : {
158
+ experimental: {
159
+ [RUNTIME_EXPERIMENTAL_KEY]: {
160
+ version: runtime,
161
+ capabilities: bridge.roster(),
162
+ },
163
+ },
164
+ }),
165
+ },
134
166
  hostContext: session.hostContext(),
135
167
  },
136
168
  });
@@ -173,6 +205,13 @@ export const shellAdapter = {
173
205
  }
174
206
  return;
175
207
  }
208
+ if (request.method === RUNTIME_CALL_METHOD && runtime !== undefined) {
209
+ const answered = await calls.call(params);
210
+ if (!closed) {
211
+ respond(request.id, answered);
212
+ }
213
+ return;
214
+ }
176
215
  const mapped = REQUESTS[request.method];
177
216
  if (mapped === undefined) {
178
217
  respond(request.id, {
@@ -212,6 +251,15 @@ export const shellAdapter = {
212
251
  // The shell stopped a navigation (P080): an error report, with its address.
213
252
  void bridge.call("reportError", { navigationBlocked: params.url });
214
253
  return;
254
+ case RUNTIME_UNWATCH_METHOD:
255
+ calls.unwatch(params);
256
+ return;
257
+ case NAVIGATING_METHOD:
258
+ // Another page of the set opens in the frame (P084): its next load is that page, which
259
+ // follows nothing yet.
260
+ forget();
261
+ session.emit({ type: "navigating" });
262
+ return;
215
263
  case M.requestTeardown:
216
264
  session.emit({ type: "teardown-requested" });
217
265
  return;
@@ -271,6 +319,7 @@ export const shellAdapter = {
271
319
  stop();
272
320
  pending.clear();
273
321
  live.close();
322
+ calls.close();
274
323
  },
275
324
  };
276
325
  },
@@ -51,6 +51,37 @@ function words(request) {
51
51
  return { heading: "Let it follow this?", accept: "Allow", detail: request.args.uri };
52
52
  case "copyText":
53
53
  return { heading: "Copy this text?", accept: "Copy", detail: request.args.text };
54
+ // The runtime's (P088, P089): the whole effect, as the page asked for it.
55
+ case "artifact":
56
+ return request.args.op === "publish"
57
+ ? {
58
+ heading: "Publish a new version of this page?",
59
+ accept: "Publish",
60
+ detail: Object.entries(request.args.files)
61
+ .map(([path, file]) => file === null
62
+ ? `${path}: removed`
63
+ : "text" in file
64
+ ? `${path}: ${file.text.length.toLocaleString("en-US")} characters`
65
+ : `${path}: ${Math.floor((file.base64.length * 3) / 4).toLocaleString("en-US")} bytes`)
66
+ .join("\n"),
67
+ note: `From version ${request.args.base}${request.args.label === undefined ? "" : `: ${request.args.label}`}.`,
68
+ }
69
+ : { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
70
+ case "assets":
71
+ return request.args.op === "upload"
72
+ ? {
73
+ heading: "Add this file to the page's library?",
74
+ accept: "Add",
75
+ detail: `${request.args.name} (${request.args.type}, ${request.args.size.toLocaleString("en-US")} bytes)`,
76
+ note: "Everyone who can see the page can load it.",
77
+ }
78
+ : request.args.op === "delete"
79
+ ? {
80
+ heading: "Remove this file from the page's library?",
81
+ accept: "Remove",
82
+ detail: request.args.id,
83
+ }
84
+ : { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
54
85
  default:
55
86
  return { heading: "Allow this?", accept: "Allow", detail: json(request.args) };
56
87
  }
@@ -1,3 +1,5 @@
1
+ import type { PageDeclaration } from "../runtime/declaration.ts";
2
+ import type { ViewerInfo } from "../runtime/levels.ts";
1
3
  import { type CSSProperties, type ReactElement, type ReactNode } from "react";
2
4
  import type { AnnotateMode, AnnotationMark, AnnotationReport } from "../annotate/types.ts";
3
5
  import type { CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, Consent, DataCache, Refusal } from "../bridge/types.ts";
@@ -145,6 +147,17 @@ export interface PortholeFrameProps {
145
147
  * shows, for its confirmations only, never sent to the frame (P077).
146
148
  */
147
149
  readonly instance?: InstanceRef;
150
+ /**
151
+ * What the page declared (P086), as the host stored it with the artifact: the capabilities it
152
+ * reaches through `porthole.use`, and its pinned runtime. By value: a change makes the display
153
+ * again.
154
+ */
155
+ readonly declaration?: PageDeclaration;
156
+ /**
157
+ * Who is viewing (P087), for an opaque frame or one whose issue gave none. By value: a change
158
+ * makes the display again.
159
+ */
160
+ readonly viewer?: ViewerInfo;
148
161
  /** The color scheme it shows in. Default: the provider's `scheme`, else light. */
149
162
  readonly scheme?: ColorScheme;
150
163
  /** The host's live values for the config's theme variables (from its design tokens). */
@@ -292,6 +292,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
292
292
  // By value: a config or instance made inline (each render) is the same display.
293
293
  const config = useByValue(frame.config);
294
294
  const instance = useByValue(frame.instance);
295
+ const declaration = useByValue(frame.declaration);
296
+ const viewer = useByValue(frame.viewer);
295
297
  const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
296
298
  // A consent that refuses everything (P080), this frame's or else the provider's, by value: a
297
299
  // display made with it needs no data handlers, so a change makes the display again.
@@ -436,6 +438,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
436
438
  initialHeightPx: startHeight,
437
439
  ...(view === undefined ? {} : { document: view }),
438
440
  ...(instance === undefined ? {} : { instance }),
441
+ ...(declaration === undefined ? {} : { declaration }),
442
+ ...(viewer === undefined ? {} : { viewer }),
439
443
  ...(fills ? { fill: true } : {}),
440
444
  });
441
445
  }
@@ -477,6 +481,8 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
477
481
  config,
478
482
  view,
479
483
  instance,
484
+ declaration,
485
+ viewer,
480
486
  startHeight,
481
487
  fills,
482
488
  pageHandlers,
@@ -0,0 +1,193 @@
1
+ import type { CapabilityName, Gate } from "../config/capabilities.ts";
2
+ import type { PortholeConfig } from "../config/schema.ts";
3
+ import { type ViewerLevel } from "./levels.ts";
4
+ /**
5
+ * The capability runtime's contract (P085): what a page reaches through its one global,
6
+ * `porthole.use(name)`, by contract version. A version is pinned per artifact when it is published
7
+ * (`declareCapabilities`) and served as pinned, so a page keeps the API it was written against.
8
+ *
9
+ * Each runtime capability is a namespace of methods; each method is served by one of the config's
10
+ * host functions (PRINCIPLE 4: the config still says what the host offers, with its gates), needs
11
+ * a viewer level (P087), and is either a call or a watch (a subscription). A built-in is reachable
12
+ * by any page whose host offers it; every other one only by a page that declared it (P086).
13
+ */
14
+ /** The contract versions this Porthole serves. */
15
+ export declare const RUNTIME_VERSIONS: readonly ["1"];
16
+ export type RuntimeVersion = (typeof RUNTIME_VERSIONS)[number];
17
+ /** The version a declaration is pinned to unless its author asks for another. */
18
+ export declare const RUNTIME_VERSION: RuntimeVersion;
19
+ export declare function isRuntimeVersion(value: unknown): value is RuntimeVersion;
20
+ /** The one global the shell defines for the runtime, with `use` its only member. */
21
+ export declare const RUNTIME_GLOBAL = "porthole";
22
+ /** Where the host's roster goes in the handshake: MCP Apps' experimental host capabilities. */
23
+ export declare const RUNTIME_EXPERIMENTAL_KEY = "porthole/runtime";
24
+ /** A runtime call (own-prefixed, P002): `{ capability, method, args }`. */
25
+ export declare const RUNTIME_CALL_METHOD = "porthole/call";
26
+ /** A watch's end, frame to host (a notification, never gated): `{ watch }`. */
27
+ export declare const RUNTIME_UNWATCH_METHOD = "porthole/unwatch";
28
+ /** A watch's update, host to frame: `{ watch, data }`. */
29
+ export declare const RUNTIME_EVENT_METHOD = "porthole/event";
30
+ export interface RuntimeMethod {
31
+ /** The config's host function that serves it: declared there, gated as it says. */
32
+ readonly serves: CapabilityName;
33
+ /** The least level that may call it, unless the host's config or the page's says more. */
34
+ readonly level: ViewerLevel;
35
+ /** The least a host's config may set it to (`CapabilityConfig.levels`). */
36
+ readonly floor: ViewerLevel;
37
+ /** A subscription: the content passes callbacks and gets a function that stops it. */
38
+ readonly watch?: true;
39
+ /**
40
+ * Gates of its own, over its host function's (after the review, P088): what changes the
41
+ * artifact for everyone needs the person's click and their yes. A host's config may replace
42
+ * them (`CapabilityConfig.methodGates`).
43
+ */
44
+ readonly gates?: readonly Gate[];
45
+ }
46
+ export interface RuntimeCapability {
47
+ /**
48
+ * Built in (P086): any page whose host offers it may use it without declaring it: the effect is
49
+ * the host's own UI, shown to the person (a copy, a link, a download, the comment composer).
50
+ */
51
+ readonly builtIn: boolean;
52
+ readonly methods: Readonly<Record<string, RuntimeMethod>>;
53
+ }
54
+ /** Contract 1's capabilities, by the name a page passes to `use`. */
55
+ export declare const RUNTIME_CAPABILITIES: {
56
+ /** Who is viewing: `{ id, name, level }`, as the host says. Declared: the page learns who. */
57
+ readonly user: {
58
+ readonly builtIn: false;
59
+ readonly methods: {
60
+ readonly get: RuntimeMethod;
61
+ };
62
+ };
63
+ /** Opens the host's comment composer at an anchor the page names. Write-only (P090). */
64
+ readonly comments: {
65
+ readonly builtIn: true;
66
+ readonly methods: {
67
+ readonly open: RuntimeMethod;
68
+ };
69
+ };
70
+ /** Copies text, done and shown by the host (P051, P052). */
71
+ readonly clipboard: {
72
+ readonly builtIn: true;
73
+ readonly methods: {
74
+ readonly copy: RuntimeMethod;
75
+ };
76
+ };
77
+ /** Opens an http(s) link outside the frame. */
78
+ readonly links: {
79
+ readonly builtIn: true;
80
+ readonly methods: {
81
+ readonly open: RuntimeMethod;
82
+ };
83
+ };
84
+ /** Hands the person a file to save. */
85
+ readonly downloads: {
86
+ readonly builtIn: true;
87
+ readonly methods: {
88
+ readonly save: RuntimeMethod;
89
+ };
90
+ };
91
+ /** Sends text to the agent as the person's message. */
92
+ readonly chat: {
93
+ readonly builtIn: false;
94
+ readonly methods: {
95
+ readonly send: RuntimeMethod;
96
+ };
97
+ };
98
+ /** The host's data (MCP resources and tools, P079): read, follow, call. */
99
+ readonly data: {
100
+ readonly builtIn: false;
101
+ readonly methods: {
102
+ readonly read: RuntimeMethod;
103
+ readonly subscribe: RuntimeMethod;
104
+ readonly call: RuntimeMethod;
105
+ };
106
+ };
107
+ /** Context for the agent's next turns. */
108
+ readonly context: {
109
+ readonly builtIn: false;
110
+ readonly methods: {
111
+ readonly set: RuntimeMethod;
112
+ };
113
+ };
114
+ /** This artifact itself: its current version, and a new version of it (P088). */
115
+ readonly artifact: {
116
+ readonly builtIn: false;
117
+ readonly methods: {
118
+ readonly get: RuntimeMethod;
119
+ readonly publish: RuntimeMethod;
120
+ };
121
+ };
122
+ /** The artifact's asset library, served at `/_blob/<id>` (P089). */
123
+ readonly assets: {
124
+ readonly builtIn: false;
125
+ readonly methods: {
126
+ readonly list: RuntimeMethod;
127
+ readonly url: RuntimeMethod;
128
+ readonly upload: RuntimeMethod;
129
+ readonly delete: RuntimeMethod;
130
+ };
131
+ };
132
+ /** The artifact's shared document store (P088). */
133
+ readonly db: {
134
+ readonly builtIn: false;
135
+ readonly methods: {
136
+ readonly get: RuntimeMethod;
137
+ readonly query: RuntimeMethod;
138
+ readonly watch: RuntimeMethod;
139
+ readonly set: RuntimeMethod;
140
+ readonly update: RuntimeMethod;
141
+ readonly delete: RuntimeMethod;
142
+ readonly batch: RuntimeMethod;
143
+ };
144
+ };
145
+ };
146
+ export type RuntimeCapabilityName = keyof typeof RUNTIME_CAPABILITIES;
147
+ export declare const RUNTIME_CAPABILITY_NAMES: readonly RuntimeCapabilityName[];
148
+ export declare function isRuntimeCapabilityName(value: unknown): value is RuntimeCapabilityName;
149
+ /** A runtime capability's spec, as the general shape. */
150
+ export declare function runtimeCapability(name: RuntimeCapabilityName): RuntimeCapability;
151
+ /** The host functions the runtime added in contract 1 (P085): the config needs `runtime` for them. */
152
+ export declare const RUNTIME_HOST_FUNCTIONS: readonly CapabilityName[];
153
+ /**
154
+ * Where a host function sits in the runtime: its capability and the methods it serves. Null for
155
+ * the shell's own (`resize`, `reportError`, `annotate`), which content never calls by name.
156
+ */
157
+ export declare function familyOf(serves: CapabilityName): {
158
+ readonly name: RuntimeCapabilityName;
159
+ readonly methods: readonly string[];
160
+ } | null;
161
+ /**
162
+ * The runtime method a host function's validated call is: the `op` of one that serves several
163
+ * (`artifact`, `assets`, `db`), else its one method.
164
+ */
165
+ export declare function methodOf(serves: CapabilityName, args: unknown): string | null;
166
+ /**
167
+ * Whether a config's asset uploads are its admins' alone (`assets.upload` at admin or above,
168
+ * P089): only then may scripts and styles an admin uploaded run from the library.
169
+ */
170
+ export declare function assetCodeRuns(config: PortholeConfig): boolean;
171
+ /**
172
+ * A runtime method's own gates (after the review): the config's (`CapabilityConfig.methodGates`),
173
+ * else the contract's; an upload where uploaded code may run is confirmed (P089).
174
+ */
175
+ export declare function methodGates(config: PortholeConfig, family: RuntimeCapabilityName, name: string): readonly Gate[];
176
+ /** What a page declared for one capability, as far as levels go (P086). */
177
+ export interface DeclaredLevels {
178
+ readonly levels?: Readonly<Record<string, ViewerLevel>>;
179
+ }
180
+ /**
181
+ * The least level that may call `family.method` (P087): the contract's, or the host's config
182
+ * (`CapabilityConfig.levels`, no lower than the floor), raised by the page's declaration.
183
+ */
184
+ export declare function methodLevel(config: PortholeConfig, family: RuntimeCapabilityName, name: string, declared?: DeclaredLevels): ViewerLevel | null;
185
+ /**
186
+ * What the host offers a display (P085): each runtime capability the config serves at least one
187
+ * method of (with those methods), reachable when it is built in or the page declared it. Without
188
+ * `config.runtime`, nothing: the display is 0.6's. `declared` is the page's declaration's names;
189
+ * absent, the page declared nothing (built-ins only).
190
+ */
191
+ export declare function rosterOf(config: PortholeConfig, declared?: readonly string[]): Readonly<Partial<Record<RuntimeCapabilityName, readonly string[]>>>;
192
+ /** The capabilities a config offers to pages that declare them (for the manual and `declareCapabilities`). */
193
+ export declare function offeredCapabilities(config: PortholeConfig): RuntimeCapabilityName[];