@botiverse/porthole 0.6.0 → 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 (145) hide show
  1. package/README.md +16 -0
  2. package/dist/bridge/bridge.d.ts +13 -0
  3. package/dist/bridge/bridge.js +200 -8
  4. package/dist/bridge/refusal.d.ts +5 -1
  5. package/dist/bridge/refusal.js +16 -0
  6. package/dist/bridge/types.d.ts +41 -4
  7. package/dist/check/check.d.ts +7 -0
  8. package/dist/check/check.js +1 -0
  9. package/dist/check/instrument.d.ts +3 -0
  10. package/dist/check/lint.js +4 -2
  11. package/dist/check/page-source.js +1 -1
  12. package/dist/check/page.js +14 -0
  13. package/dist/check/tools.js +2 -3
  14. package/dist/compile/policy.d.ts +19 -0
  15. package/dist/compile/policy.js +42 -0
  16. package/dist/config/capabilities.d.ts +62 -3
  17. package/dist/config/capabilities.js +20 -0
  18. package/dist/config/schema.d.ts +24 -0
  19. package/dist/config/validate.d.ts +1 -1
  20. package/dist/config/validate.js +66 -4
  21. package/dist/conformance/harness-source.js +1 -1
  22. package/dist/conformance/index.d.ts +1 -0
  23. package/dist/conformance/index.js +2 -0
  24. package/dist/conformance/runtime.d.ts +58 -0
  25. package/dist/conformance/runtime.js +314 -0
  26. package/dist/guide/gates.d.ts +3 -0
  27. package/dist/guide/gates.js +19 -0
  28. package/dist/guide/guide.d.ts +2 -0
  29. package/dist/guide/guide.js +34 -32
  30. package/dist/guide/limits.js +4 -4
  31. package/dist/guide/runtime.d.ts +13 -0
  32. package/dist/guide/runtime.js +202 -0
  33. package/dist/host/create-host.js +24 -0
  34. package/dist/host/locate.js +8 -0
  35. package/dist/host/locator.js +7 -0
  36. package/dist/host/types.d.ts +18 -0
  37. package/dist/index.d.ts +8 -2
  38. package/dist/index.js +9 -1
  39. package/dist/isolation/types.d.ts +8 -0
  40. package/dist/presets/presets.d.ts +6 -0
  41. package/dist/presets/presets.js +1 -0
  42. package/dist/protocol/runtime-calls.d.ts +28 -0
  43. package/dist/protocol/runtime-calls.js +113 -0
  44. package/dist/protocol/shell-adapter.js +48 -3
  45. package/dist/react/dialog.js +31 -0
  46. package/dist/react/frame.d.ts +13 -0
  47. package/dist/react/frame.js +6 -0
  48. package/dist/runtime/contract.d.ts +193 -0
  49. package/dist/runtime/contract.js +216 -0
  50. package/dist/runtime/db.d.ts +153 -0
  51. package/dist/runtime/db.js +398 -0
  52. package/dist/runtime/declaration.d.ts +86 -0
  53. package/dist/runtime/declaration.js +266 -0
  54. package/dist/runtime/levels.d.ts +33 -0
  55. package/dist/runtime/levels.js +41 -0
  56. package/dist/runtime/requests.d.ts +125 -0
  57. package/dist/runtime/requests.js +199 -0
  58. package/dist/runtime/segments.d.ts +8 -0
  59. package/dist/runtime/segments.js +14 -0
  60. package/dist/runtime/types.generated.d.ts +1 -0
  61. package/dist/runtime/types.generated.js +19 -0
  62. package/dist/server/files.d.ts +14 -1
  63. package/dist/server/files.js +97 -3
  64. package/dist/server/host.d.ts +6 -1
  65. package/dist/server/host.js +5 -0
  66. package/dist/server/index.d.ts +2 -1
  67. package/dist/server/index.js +1 -0
  68. package/dist/server/pseudonym.d.ts +9 -0
  69. package/dist/server/pseudonym.js +20 -0
  70. package/dist/server/server.d.ts +0 -5
  71. package/dist/server/server.js +214 -35
  72. package/dist/server/types.d.ts +69 -0
  73. package/dist/shell/document.d.ts +8 -0
  74. package/dist/shell/document.js +16 -2
  75. package/dist/shell/legacy.d.ts +21 -0
  76. package/dist/shell/legacy.js +63 -0
  77. package/dist/shell/plan.d.ts +17 -1
  78. package/dist/shell/plan.js +13 -2
  79. package/dist/shell/runtime.js +29 -42
  80. package/dist/shell/use.d.ts +15 -0
  81. package/dist/shell/use.js +235 -0
  82. package/docs/ADOPTING.md +91 -6
  83. package/docs/ARCHITECTURE.md +22 -3
  84. package/docs/DECISIONS.md +415 -6
  85. package/docs/DESIGN.md +66 -0
  86. package/package.json +3 -1
  87. package/src/bridge/bridge.ts +273 -12
  88. package/src/bridge/refusal.ts +16 -0
  89. package/src/bridge/types.ts +46 -4
  90. package/src/check/check.ts +8 -0
  91. package/src/check/instrument.ts +3 -0
  92. package/src/check/lint.ts +4 -2
  93. package/src/check/page.ts +14 -0
  94. package/src/check/tools.ts +2 -3
  95. package/src/compile/policy.ts +54 -0
  96. package/src/config/capabilities.ts +49 -2
  97. package/src/config/schema.ts +24 -0
  98. package/src/config/validate.ts +99 -4
  99. package/src/conformance/index.ts +7 -0
  100. package/src/conformance/runtime.ts +573 -0
  101. package/src/guide/gates.ts +25 -0
  102. package/src/guide/guide.ts +59 -53
  103. package/src/guide/limits.ts +4 -4
  104. package/src/guide/runtime.ts +244 -0
  105. package/src/host/create-host.ts +34 -0
  106. package/src/host/locate.ts +10 -0
  107. package/src/host/locator.ts +11 -0
  108. package/src/host/types.ts +18 -0
  109. package/src/index.ts +89 -0
  110. package/src/isolation/types.ts +8 -0
  111. package/src/presets/presets.ts +7 -0
  112. package/src/protocol/runtime-calls.ts +138 -0
  113. package/src/protocol/shell-adapter.ts +52 -3
  114. package/src/react/dialog.tsx +33 -0
  115. package/src/react/frame.tsx +19 -0
  116. package/src/runtime/contract.ts +305 -0
  117. package/src/runtime/db.ts +530 -0
  118. package/src/runtime/declaration.ts +378 -0
  119. package/src/runtime/levels.ts +69 -0
  120. package/src/runtime/requests.ts +339 -0
  121. package/src/runtime/segments.ts +17 -0
  122. package/src/runtime/types.generated.ts +19 -0
  123. package/src/server/files.ts +117 -4
  124. package/src/server/host.ts +12 -0
  125. package/src/server/index.ts +3 -0
  126. package/src/server/pseudonym.ts +21 -0
  127. package/src/server/server.ts +247 -37
  128. package/src/server/types.ts +68 -0
  129. package/src/shell/document.ts +21 -4
  130. package/src/shell/legacy.ts +64 -0
  131. package/src/shell/plan.ts +37 -3
  132. package/src/shell/runtime.ts +29 -42
  133. package/src/shell/use.ts +235 -0
  134. package/types/runtime/v1/artifact.d.ts +50 -0
  135. package/types/runtime/v1/assets.d.ts +43 -0
  136. package/types/runtime/v1/chat.d.ts +13 -0
  137. package/types/runtime/v1/clipboard.d.ts +14 -0
  138. package/types/runtime/v1/comments.d.ts +24 -0
  139. package/types/runtime/v1/context.d.ts +16 -0
  140. package/types/runtime/v1/data.d.ts +29 -0
  141. package/types/runtime/v1/db.d.ts +110 -0
  142. package/types/runtime/v1/downloads.d.ts +22 -0
  143. package/types/runtime/v1/links.d.ts +13 -0
  144. package/types/runtime/v1/porthole.d.ts +44 -0
  145. package/types/runtime/v1/user.d.ts +19 -0
@@ -0,0 +1,305 @@
1
+ import type { CapabilityName, Gate } from "../config/capabilities.ts";
2
+ import type { PortholeConfig } from "../config/schema.ts";
3
+ import { atLeast, higher, type ViewerLevel } from "./levels.ts";
4
+
5
+ /**
6
+ * The capability runtime's contract (P085): what a page reaches through its one global,
7
+ * `porthole.use(name)`, by contract version. A version is pinned per artifact when it is published
8
+ * (`declareCapabilities`) and served as pinned, so a page keeps the API it was written against.
9
+ *
10
+ * Each runtime capability is a namespace of methods; each method is served by one of the config's
11
+ * host functions (PRINCIPLE 4: the config still says what the host offers, with its gates), needs
12
+ * a viewer level (P087), and is either a call or a watch (a subscription). A built-in is reachable
13
+ * by any page whose host offers it; every other one only by a page that declared it (P086).
14
+ */
15
+
16
+ /** The contract versions this Porthole serves. */
17
+ export const RUNTIME_VERSIONS = ["1"] as const;
18
+
19
+ export type RuntimeVersion = (typeof RUNTIME_VERSIONS)[number];
20
+
21
+ /** The version a declaration is pinned to unless its author asks for another. */
22
+ export const RUNTIME_VERSION: RuntimeVersion = "1";
23
+
24
+ export function isRuntimeVersion(value: unknown): value is RuntimeVersion {
25
+ return typeof value === "string" && (RUNTIME_VERSIONS as readonly string[]).includes(value);
26
+ }
27
+
28
+ /** The one global the shell defines for the runtime, with `use` its only member. */
29
+ export const RUNTIME_GLOBAL = "porthole";
30
+
31
+ /** Where the host's roster goes in the handshake: MCP Apps' experimental host capabilities. */
32
+ export const RUNTIME_EXPERIMENTAL_KEY = "porthole/runtime";
33
+
34
+ /** A runtime call (own-prefixed, P002): `{ capability, method, args }`. */
35
+ export const RUNTIME_CALL_METHOD = "porthole/call";
36
+
37
+ /** A watch's end, frame to host (a notification, never gated): `{ watch }`. */
38
+ export const RUNTIME_UNWATCH_METHOD = "porthole/unwatch";
39
+
40
+ /** A watch's update, host to frame: `{ watch, data }`. */
41
+ export const RUNTIME_EVENT_METHOD = "porthole/event";
42
+
43
+ export interface RuntimeMethod {
44
+ /** The config's host function that serves it: declared there, gated as it says. */
45
+ readonly serves: CapabilityName;
46
+ /** The least level that may call it, unless the host's config or the page's says more. */
47
+ readonly level: ViewerLevel;
48
+ /** The least a host's config may set it to (`CapabilityConfig.levels`). */
49
+ readonly floor: ViewerLevel;
50
+ /** A subscription: the content passes callbacks and gets a function that stops it. */
51
+ readonly watch?: true;
52
+ /**
53
+ * Gates of its own, over its host function's (after the review, P088): what changes the
54
+ * artifact for everyone needs the person's click and their yes. A host's config may replace
55
+ * them (`CapabilityConfig.methodGates`).
56
+ */
57
+ readonly gates?: readonly Gate[];
58
+ }
59
+
60
+ export interface RuntimeCapability {
61
+ /**
62
+ * Built in (P086): any page whose host offers it may use it without declaring it: the effect is
63
+ * the host's own UI, shown to the person (a copy, a link, a download, the comment composer).
64
+ */
65
+ readonly builtIn: boolean;
66
+ readonly methods: Readonly<Record<string, RuntimeMethod>>;
67
+ }
68
+
69
+ const method = (
70
+ serves: CapabilityName,
71
+ level: ViewerLevel,
72
+ extra: {
73
+ readonly floor?: ViewerLevel;
74
+ readonly watch?: true;
75
+ readonly gates?: readonly Gate[];
76
+ } = {},
77
+ ): RuntimeMethod => ({
78
+ serves,
79
+ level,
80
+ floor: extra.floor ?? "view",
81
+ ...(extra.watch === undefined ? {} : { watch: true }),
82
+ ...(extra.gates === undefined ? {} : { gates: extra.gates }),
83
+ });
84
+
85
+ /** What changes the artifact for everyone: the person's click, then their yes. */
86
+ const CHANGES: readonly Gate[] = ["user-activation", "confirm"];
87
+
88
+ /** Contract 1's capabilities, by the name a page passes to `use`. */
89
+ export const RUNTIME_CAPABILITIES = {
90
+ /** Who is viewing: `{ id, name, level }`, as the host says. Declared: the page learns who. */
91
+ user: { builtIn: false, methods: { get: method("user", "view") } },
92
+ /** Opens the host's comment composer at an anchor the page names. Write-only (P090). */
93
+ comments: { builtIn: true, methods: { open: method("comments", "view") } },
94
+ /** Copies text, done and shown by the host (P051, P052). */
95
+ clipboard: { builtIn: true, methods: { copy: method("copyText", "view") } },
96
+ /** Opens an http(s) link outside the frame. */
97
+ links: { builtIn: true, methods: { open: method("openLink", "view") } },
98
+ /** Hands the person a file to save. */
99
+ downloads: { builtIn: true, methods: { save: method("downloadFile", "view") } },
100
+ /** Sends text to the agent as the person's message. */
101
+ chat: { builtIn: false, methods: { send: method("sendPrompt", "interact") } },
102
+ /** The host's data (MCP resources and tools, P079): read, follow, call. */
103
+ data: {
104
+ builtIn: false,
105
+ methods: {
106
+ read: method("readData", "view"),
107
+ subscribe: method("subscribeData", "view", { watch: true }),
108
+ call: method("callTool", "interact"),
109
+ },
110
+ },
111
+ /** Context for the agent's next turns. */
112
+ context: { builtIn: false, methods: { set: method("setModelContext", "interact") } },
113
+ /** This artifact itself: its current version, and a new version of it (P088). */
114
+ artifact: {
115
+ builtIn: false,
116
+ methods: {
117
+ get: method("artifact", "view"),
118
+ publish: method("artifact", "admin", { floor: "admin", gates: CHANGES }),
119
+ },
120
+ },
121
+ /** The artifact's asset library, served at `/_blob/<id>` (P089). */
122
+ assets: {
123
+ builtIn: false,
124
+ methods: {
125
+ list: method("assets", "view"),
126
+ // In the frame alone (P091): the address that loads an asset in this page now.
127
+ url: method("assets", "view"),
128
+ // An upload's own gate depends on whether what is uploaded may run (`methodGates`).
129
+ upload: method("assets", "admin", { floor: "interact" }),
130
+ delete: method("assets", "admin", { floor: "admin", gates: CHANGES }),
131
+ },
132
+ },
133
+ /** The artifact's shared document store (P088). */
134
+ db: {
135
+ builtIn: false,
136
+ methods: {
137
+ get: method("db", "view"),
138
+ query: method("db", "view"),
139
+ watch: method("db", "view", { watch: true }),
140
+ set: method("db", "interact", { floor: "interact" }),
141
+ update: method("db", "interact", { floor: "interact" }),
142
+ delete: method("db", "interact", { floor: "interact" }),
143
+ batch: method("db", "interact", { floor: "interact" }),
144
+ },
145
+ },
146
+ } as const satisfies Readonly<Record<string, RuntimeCapability>>;
147
+
148
+ export type RuntimeCapabilityName = keyof typeof RUNTIME_CAPABILITIES;
149
+
150
+ export const RUNTIME_CAPABILITY_NAMES = Object.keys(
151
+ RUNTIME_CAPABILITIES,
152
+ ) as readonly RuntimeCapabilityName[];
153
+
154
+ export function isRuntimeCapabilityName(value: unknown): value is RuntimeCapabilityName {
155
+ return typeof value === "string" && Object.hasOwn(RUNTIME_CAPABILITIES, value);
156
+ }
157
+
158
+ /** A runtime capability's spec, as the general shape. */
159
+ export function runtimeCapability(name: RuntimeCapabilityName): RuntimeCapability {
160
+ return RUNTIME_CAPABILITIES[name];
161
+ }
162
+
163
+ /** The host functions the runtime added in contract 1 (P085): the config needs `runtime` for them. */
164
+ export const RUNTIME_HOST_FUNCTIONS: readonly CapabilityName[] = [
165
+ "user",
166
+ "comments",
167
+ "artifact",
168
+ "assets",
169
+ "db",
170
+ ];
171
+
172
+ /**
173
+ * Where a host function sits in the runtime: its capability and the methods it serves. Null for
174
+ * the shell's own (`resize`, `reportError`, `annotate`), which content never calls by name.
175
+ */
176
+ export function familyOf(
177
+ serves: CapabilityName,
178
+ ): { readonly name: RuntimeCapabilityName; readonly methods: readonly string[] } | null {
179
+ for (const name of RUNTIME_CAPABILITY_NAMES) {
180
+ const methods = Object.entries(runtimeCapability(name).methods)
181
+ .filter(([, each]) => each.serves === serves)
182
+ .map(([each]) => each);
183
+ if (methods.length > 0) {
184
+ return { name, methods };
185
+ }
186
+ }
187
+ return null;
188
+ }
189
+
190
+ /**
191
+ * The runtime method a host function's validated call is: the `op` of one that serves several
192
+ * (`artifact`, `assets`, `db`), else its one method.
193
+ */
194
+ export function methodOf(serves: CapabilityName, args: unknown): string | null {
195
+ const family = familyOf(serves);
196
+ if (family === null) {
197
+ return null;
198
+ }
199
+ if (family.methods.length === 1) {
200
+ return family.methods[0] ?? null;
201
+ }
202
+ const op =
203
+ args !== null && typeof args === "object" ? (args as { readonly op?: unknown }).op : undefined;
204
+ return typeof op === "string" && family.methods.includes(op) ? op : null;
205
+ }
206
+
207
+ /**
208
+ * Whether a config's asset uploads are its admins' alone (`assets.upload` at admin or above,
209
+ * P089): only then may scripts and styles an admin uploaded run from the library.
210
+ */
211
+ export function assetCodeRuns(config: PortholeConfig): boolean {
212
+ const level = methodLevel(config, "assets", "upload");
213
+ return level !== null && atLeast(level, "admin");
214
+ }
215
+
216
+ /**
217
+ * A runtime method's own gates (after the review): the config's (`CapabilityConfig.methodGates`),
218
+ * else the contract's; an upload where uploaded code may run is confirmed (P089).
219
+ */
220
+ export function methodGates(
221
+ config: PortholeConfig,
222
+ family: RuntimeCapabilityName,
223
+ name: string,
224
+ ): readonly Gate[] {
225
+ const methods: Readonly<Record<string, RuntimeMethod>> = runtimeCapability(family).methods;
226
+ const spec = Object.hasOwn(methods, name) ? methods[name] : undefined;
227
+ if (spec === undefined) {
228
+ return [];
229
+ }
230
+ const own = config.capabilities[spec.serves]?.methodGates;
231
+ if (own !== undefined && Object.hasOwn(own, name)) {
232
+ return own[name] ?? [];
233
+ }
234
+ if (family === "assets" && name === "upload") {
235
+ return assetCodeRuns(config) ? ["confirm"] : [];
236
+ }
237
+ return spec.gates ?? [];
238
+ }
239
+
240
+ /** What a page declared for one capability, as far as levels go (P086). */
241
+ export interface DeclaredLevels {
242
+ readonly levels?: Readonly<Record<string, ViewerLevel>>;
243
+ }
244
+
245
+ /**
246
+ * The least level that may call `family.method` (P087): the contract's, or the host's config
247
+ * (`CapabilityConfig.levels`, no lower than the floor), raised by the page's declaration.
248
+ */
249
+ export function methodLevel(
250
+ config: PortholeConfig,
251
+ family: RuntimeCapabilityName,
252
+ name: string,
253
+ declared?: DeclaredLevels,
254
+ ): ViewerLevel | null {
255
+ const methods: Readonly<Record<string, RuntimeMethod>> = runtimeCapability(family).methods;
256
+ const spec = Object.hasOwn(methods, name) ? methods[name] : undefined;
257
+ if (spec === undefined) {
258
+ return null;
259
+ }
260
+ const host = config.capabilities[spec.serves]?.levels?.[name];
261
+ const base = host === undefined ? spec.level : higher(host, spec.floor);
262
+ const page = declared?.levels?.[name];
263
+ return page === undefined ? base : higher(base, page);
264
+ }
265
+
266
+ /**
267
+ * What the host offers a display (P085): each runtime capability the config serves at least one
268
+ * method of (with those methods), reachable when it is built in or the page declared it. Without
269
+ * `config.runtime`, nothing: the display is 0.6's. `declared` is the page's declaration's names;
270
+ * absent, the page declared nothing (built-ins only).
271
+ */
272
+ export function rosterOf(
273
+ config: PortholeConfig,
274
+ declared?: readonly string[],
275
+ ): Readonly<Partial<Record<RuntimeCapabilityName, readonly string[]>>> {
276
+ if (config.runtime === undefined) {
277
+ return {};
278
+ }
279
+ const roster: Partial<Record<RuntimeCapabilityName, readonly string[]>> = {};
280
+ for (const name of RUNTIME_CAPABILITY_NAMES) {
281
+ const spec = runtimeCapability(name);
282
+ if (!spec.builtIn && !(declared ?? []).includes(name)) {
283
+ continue;
284
+ }
285
+ const methods = Object.entries(spec.methods)
286
+ .filter(([, each]) => config.capabilities[each.serves] !== undefined)
287
+ .map(([each]) => each);
288
+ if (methods.length > 0) {
289
+ roster[name] = methods;
290
+ }
291
+ }
292
+ return roster;
293
+ }
294
+
295
+ /** The capabilities a config offers to pages that declare them (for the manual and `declareCapabilities`). */
296
+ export function offeredCapabilities(config: PortholeConfig): RuntimeCapabilityName[] {
297
+ if (config.runtime === undefined) {
298
+ return [];
299
+ }
300
+ return RUNTIME_CAPABILITY_NAMES.filter((name) =>
301
+ Object.values(runtimeCapability(name).methods).some(
302
+ (each) => config.capabilities[each.serves] !== undefined,
303
+ ),
304
+ );
305
+ }