@botiverse/porthole 0.2.3 → 0.3.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 (75) hide show
  1. package/README.md +14 -9
  2. package/dist/check/check.d.ts +83 -0
  3. package/dist/check/check.js +169 -0
  4. package/dist/check/drivers.d.ts +24 -0
  5. package/dist/check/drivers.js +110 -0
  6. package/dist/check/index.d.ts +8 -0
  7. package/dist/check/index.js +8 -0
  8. package/dist/check/lint.d.ts +21 -0
  9. package/dist/check/lint.js +131 -0
  10. package/dist/check/page-source.d.ts +2 -0
  11. package/dist/check/page-source.js +2 -0
  12. package/dist/check/page.d.ts +51 -0
  13. package/dist/check/page.js +150 -0
  14. package/dist/check/tools.d.ts +61 -0
  15. package/dist/check/tools.js +140 -0
  16. package/dist/conformance/host-kit.d.ts +10 -2
  17. package/dist/conformance/host-kit.js +9 -2
  18. package/dist/displays/displays.d.ts +61 -0
  19. package/dist/displays/displays.js +113 -0
  20. package/dist/host/client.d.ts +92 -0
  21. package/dist/host/client.js +259 -0
  22. package/dist/index.d.ts +4 -0
  23. package/dist/index.js +6 -0
  24. package/dist/node/index.d.ts +22 -1
  25. package/dist/node/index.js +46 -1
  26. package/dist/react/frame.d.ts +71 -3
  27. package/dist/react/frame.js +120 -19
  28. package/dist/react/index.d.ts +1 -0
  29. package/dist/react/index.js +1 -0
  30. package/dist/react/view.d.ts +54 -0
  31. package/dist/react/view.js +146 -0
  32. package/dist/server/bootstrap.d.ts +27 -0
  33. package/dist/server/bootstrap.js +63 -0
  34. package/dist/server/host.d.ts +74 -7
  35. package/dist/server/host.js +237 -9
  36. package/dist/server/index.d.ts +4 -2
  37. package/dist/server/index.js +3 -1
  38. package/dist/server/pages.d.ts +19 -0
  39. package/dist/server/pages.js +8 -0
  40. package/dist/server/proxy.d.ts +24 -0
  41. package/dist/server/proxy.js +67 -0
  42. package/dist/server/server.js +14 -1
  43. package/dist/server/types.d.ts +8 -0
  44. package/docs/ADOPTING.md +356 -0
  45. package/docs/DECISIONS.md +146 -0
  46. package/docs/DESIGN.md +58 -0
  47. package/examples/app.mjs +62 -64
  48. package/examples/conformance/page.spec.mjs +23 -0
  49. package/examples/conformance/playwright.config.mjs +1 -1
  50. package/examples/conformance/porthole.spec.mjs +5 -3
  51. package/examples/displays.mjs +19 -0
  52. package/examples/mcp/server.mjs +121 -0
  53. package/package.json +9 -1
  54. package/src/check/check.ts +278 -0
  55. package/src/check/drivers.ts +144 -0
  56. package/src/check/index.ts +15 -0
  57. package/src/check/lint.ts +238 -0
  58. package/src/check/page-source.ts +19 -0
  59. package/src/check/page.ts +204 -0
  60. package/src/check/tools.ts +206 -0
  61. package/src/conformance/host-kit.ts +20 -11
  62. package/src/displays/displays.ts +191 -0
  63. package/src/host/client.ts +364 -0
  64. package/src/index.ts +25 -0
  65. package/src/node/index.ts +66 -2
  66. package/src/react/frame.tsx +191 -33
  67. package/src/react/index.ts +8 -0
  68. package/src/react/view.tsx +232 -0
  69. package/src/server/bootstrap.ts +97 -0
  70. package/src/server/host.ts +331 -15
  71. package/src/server/index.ts +11 -1
  72. package/src/server/pages.ts +28 -0
  73. package/src/server/proxy.ts +86 -0
  74. package/src/server/server.ts +26 -2
  75. package/src/server/types.ts +5 -0
package/examples/app.mjs CHANGED
@@ -3,17 +3,10 @@
3
3
  // clean address. examples/node/server.mjs and examples/workers/worker.mjs only adapt it.
4
4
  //
5
5
  // What is the app's own here (the policy): who is signed in (a cookie), which pages exist, who
6
- // may see each. Everything else is Porthole's. Copy this file and replace the policy.
7
- import { presets } from "@botiverse/porthole";
6
+ // may see each, and what a clean address names. Everything else is Porthole's: one mount
7
+ // (`content.routes`, under /porthole) answers frames, the authorize route and the page's meta.
8
8
  import { conformancePage, createContentHost, prefixedName } from "@botiverse/porthole/server";
9
-
10
- /** The config a page is shown under: served on its own origin, or opaque while that's down. */
11
- export const pageConfig = (contentSource) =>
12
- presets.artifact({
13
- // A whole-page viewer: the frame fills its box, and the agent's manual says so.
14
- layout: { kind: "fill" },
15
- ...(contentSource === null ? {} : { isolation: "domain", contentOrigins: [contentSource] }),
16
- });
9
+ import { displays, kinds } from "./displays.mjs";
17
10
 
18
11
  /** The stored pages: id → versions. An app keeps them in its database. */
19
12
  const PAGES = {
@@ -60,6 +53,13 @@ export function makeApp(settings) {
60
53
  };
61
54
  pages.private = { owner: "nobody", versions: { 1: "<!doctype html><p>private</p>" } };
62
55
  }
56
+ const page = (scope) =>
57
+ pages[scope]
58
+ ? scope
59
+ : settings.conformance === true && /^t-[a-z0-9-]{1,40}$/u.test(scope)
60
+ ? "conformance"
61
+ : null;
62
+ const latest = (id) => Object.keys(pages[id].versions).at(-1);
63
63
  /** Who may see an instance: anyone signed in, but a page with an owner only its owner. */
64
64
  const accessOf = (instance, viewer) => {
65
65
  const owner = pages[page(instance.scope) ?? ""]?.owner ?? null;
@@ -67,20 +67,13 @@ export function makeApp(settings) {
67
67
  ? { viewer, subject: viewer }
68
68
  : null;
69
69
  };
70
- const page = (scope) =>
71
- pages[scope]
72
- ? scope
73
- : settings.conformance === true && /^t-[a-z0-9-]{1,40}$/u.test(scope)
74
- ? "conformance"
75
- : null;
76
70
 
77
71
  const content = createContentHost({
78
72
  domain: settings.contentDomain,
79
73
  appOrigins: [appOrigin],
80
74
  secret: settings.secret,
81
75
  ...(settings.tickets === undefined ? {} : { tickets: settings.tickets }),
82
- // The key is the preset a stored page names: an artifact's defaults to "artifact".
83
- configs: (source) => ({ artifact: pageConfig(source) }),
76
+ displays,
84
77
  name: prefixedName("a-"),
85
78
  // Policy 1: the instance a frame request proposes. The server picks the scope, never the client.
86
79
  instance: (proposal) => {
@@ -110,18 +103,21 @@ export function makeApp(settings) {
110
103
  const stored = pages[id]?.versions[version];
111
104
  return stored === undefined ? null : { html: stored };
112
105
  },
113
- // Policy 4: what a clean address names: `/` the latest version, `/v/<n>` version n.
106
+ // Policy 4: what a clean address names: `/` the latest version, `/v/<n>` version n. And the
107
+ // reverse (pathOf), so frames come with their clean address for "open in a new tab".
114
108
  entry: {
115
- authorizeUrl: `${appOrigin}/porthole/authorize`,
116
109
  at: (scope, path) => {
117
110
  const id = page(scope);
118
111
  if (id === null) return null;
119
- const version =
120
- path === "/" ? Object.keys(pages[id].versions).at(-1) : /^\/v\/(\d+)$/u.exec(path)?.[1];
112
+ const version = path === "/" ? latest(id) : /^\/v\/(\d+)$/u.exec(path)?.[1];
121
113
  return pages[id].versions[version] === undefined
122
114
  ? null
123
115
  : { scope, document: { kind: "artifact", id, version } };
124
116
  },
117
+ pathOf: (instance) =>
118
+ instance.document.version === latest(page(instance.scope) ?? "hello")
119
+ ? "/"
120
+ : `/v/${instance.document.version}`,
125
121
  // The app's own sign-in, coming back to the authorize route. Absolute: Node's
126
122
  // Response.redirect needs one.
127
123
  signIn: (returnTo) =>
@@ -130,38 +126,47 @@ export function makeApp(settings) {
130
126
  ...(settings.health === undefined ? {} : { health: settings.health }),
131
127
  log: (event) => console.log(JSON.stringify(event)),
132
128
  });
133
- const issue = content.issue(viewerOf);
134
- const authorize = content.authorize(viewerOf);
129
+ // Frames, the authorize route and the page's meta, under /porthole.
130
+ const routes = content.routes(viewerOf);
135
131
 
136
132
  async function handle(request) {
137
133
  const url = new URL(request.url);
138
134
  const viewer = viewerOf(request);
139
- if (url.pathname === "/porthole/authorize") return authorize(request);
140
- if (url.pathname === "/api/frames") return issue(request);
135
+ const porthole = await routes(request);
136
+ if (porthole !== null) return porthole;
137
+ if (url.pathname === "/porthole-client/displays.mjs") {
138
+ // The page's display kinds: the same as the server's, as a module.
139
+ return new Response(
140
+ `import { defineDisplays } from "@botiverse/porthole";\nexport const displays = defineDisplays(${JSON.stringify(kinds)});\n`,
141
+ { headers: { "content-type": "text/javascript; charset=utf-8" } },
142
+ );
143
+ }
141
144
  if (url.pathname.startsWith("/porthole-client/")) {
142
145
  return (
143
146
  (await settings.client(url.pathname.slice("/porthole-client".length))) ??
144
147
  new Response("not found", { status: 404 })
145
148
  );
146
149
  }
147
- if (url.pathname === "/api/meta") {
148
- // What the page needs: whether frames are served, and the config to show them under.
149
- const meta = content.meta();
150
- return Response.json({
151
- ...meta,
152
- config: pageConfig(meta.served ? meta.contentSource : null),
153
- viewer,
154
- });
150
+ if (url.pathname === "/api/page") {
151
+ // The opaque fallback's content: the latest version, for a viewer who may see it.
152
+ const id = url.searchParams.get("id") ?? "";
153
+ const version = pages[id] === undefined ? undefined : latest(id);
154
+ const instance =
155
+ version === undefined ? null : { scope: id, document: { kind: "artifact", id, version } };
156
+ return instance === null || accessOf(instance, viewer) === null
157
+ ? new Response("not found", { status: 404 })
158
+ : new Response(pages[id].versions[version], {
159
+ headers: { "content-type": "text/html; charset=utf-8" },
160
+ });
155
161
  }
156
162
  if (url.pathname === "/login" && request.method === "GET") {
157
163
  const next = escape(ownPath(url.searchParams.get("next"), appOrigin));
158
164
  return html(
159
165
  `<!doctype html><title>Sign in</title><main id="sign-in-page"><form method="post"><input type="hidden" name="next" value="${next}"><button id="sign-in">Sign in as ada</button></form></main>`,
160
166
  {
161
- "content-security-policy":
162
- // No form-action: after the sign-in POST, redirect entry goes on through the
163
- // content origin, and form-action holds every redirect of a submission.
164
- "default-src 'none'; frame-ancestors 'none'",
167
+ // No form-action: after the sign-in POST, redirect entry goes on through the content
168
+ // origin, and form-action holds every redirect of a submission (docs/ADOPTING.md).
169
+ "content-security-policy": "default-src 'none'; frame-ancestors 'none'",
165
170
  },
166
171
  );
167
172
  }
@@ -175,30 +180,16 @@ export function makeApp(settings) {
175
180
  },
176
181
  });
177
182
  }
178
- if (url.pathname === "/api/page") {
179
- // The opaque fallback's content: the latest version, for a viewer who may see it.
180
- const id = url.searchParams.get("id") ?? "";
181
- const latest = pages[id] === undefined ? undefined : Object.keys(pages[id].versions).at(-1);
182
- const instance =
183
- latest === undefined
184
- ? null
185
- : { scope: id, document: { kind: "artifact", id, version: latest } };
186
- const grant = instance === null ? null : accessOf(instance, viewer);
187
- return grant === null
188
- ? new Response("not found", { status: 404 })
189
- : new Response(pages[id].versions[latest], {
190
- headers: { "content-type": "text/html; charset=utf-8" },
191
- });
192
- }
193
183
  if (url.pathname === "/") {
194
184
  if (viewer === null) return Response.redirect(`${appOrigin}/login?next=/`, 303);
195
185
  const id = url.searchParams.get("page") ?? "hello";
196
186
  if (pages[id] === undefined) return new Response("not found", { status: 404 });
187
+ const frames = content.frameSources;
197
188
  return html(viewerPage(id), {
198
189
  // The embedding page's CSP: its scripts by nonce, and frames only from content origins
199
- // (content.frameSources). An opaque display inherits this policy too, so it leaves
200
- // img/media/font/style/worker open to what inline content uses (docs/ADOPTING.md).
201
- "content-security-policy": `default-src 'self'; script-src 'self' 'nonce-${NONCE}'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; media-src data: blob:; font-src data:; worker-src blob:; frame-src ${content.frameSources.length === 0 ? "'none'" : content.frameSources.join(" ")}; base-uri 'none'; frame-ancestors 'none'`,
190
+ // and the authorize route (content.frameSources). An opaque display inherits this policy
191
+ // too, so it leaves img/media/font/style/worker open to what inline content uses.
192
+ "content-security-policy": `default-src 'self'; script-src 'self' 'nonce-${NONCE}'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; media-src data: blob:; font-src data:; worker-src blob:; frame-src ${frames.length === 0 ? "'none'" : frames.join(" ")}; base-uri 'none'; frame-ancestors 'none'`,
202
193
  });
203
194
  }
204
195
  return new Response("not found", { status: 404 });
@@ -210,22 +201,29 @@ export function makeApp(settings) {
210
201
  id,
211
202
  ) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Pages</title>
212
203
  <style>body{font-family:system-ui;margin:24px} #frame{height:480px;border:1px solid #8884} #problem{color:#b00}</style></head>
213
- <body><main id="app"><p>Signed in. <a id="open-tab" href="${escape(content.urlOf(id) ?? "#")}" target="_blank" rel="noopener">Open in a new tab</a></p>
204
+ <body><main id="app"><p>Signed in. <button id="open-tab" type="button">Open in a new tab</button></p>
214
205
  <div id="frame"></div><p id="problem" role="alert"></p></main>
215
206
  <script type="importmap" nonce="${NONCE}">{"imports":{"@botiverse/porthole":"/porthole-client/index.js"}}</script>
216
207
  <script type="module" nonce="${NONCE}">
217
208
  const problem = (text) => { document.getElementById("problem").textContent = text; };
218
209
  // The client module failing to load would otherwise show nothing at all.
219
- import("@botiverse/porthole").then(async ({ createHost, httpLocator }) => {
220
- const meta = await (await fetch("/api/meta")).json();
221
- const host = createHost(meta.config, { locator: httpLocator("/api/frames"), nonce: ${JSON.stringify(NONCE)} });
210
+ Promise.all([import("@botiverse/porthole"), import("/porthole-client/displays.mjs")]).then(async ([{ createHost, frameFallback, portholeClient }, { displays }]) => {
211
+ const porthole = portholeClient({ displays }); // the server's /porthole routes
212
+ const meta = await porthole.refresh();
213
+ const instance = { scope: ${JSON.stringify(id)}, document: { kind: "artifact", id: ${JSON.stringify(id)}, version: ${JSON.stringify(latest(id))} } };
214
+ // "Open in a new tab": the clean address, opened inside the click.
215
+ document.getElementById("open-tab").addEventListener("click", () => porthole.openInTab(instance));
216
+ // Served while frames are served (located through /porthole/frames); opaque, inline, while not.
217
+ const host = createHost(porthole.config("artifact"), { locator: porthole, nonce: ${JSON.stringify(NONCE)} });
222
218
  const display = host.mount(document.getElementById("frame"), {
223
219
  displayId: ${JSON.stringify(id)}, title: ${JSON.stringify(id)}, scheme: "light",
224
- // Served: located by the issue endpoint. Opaque (frames not served now): the same page, inline.
225
- ...(meta.served ? { instance: { scope: ${JSON.stringify(id)}, document: { kind: "artifact", id: ${JSON.stringify(id)}, version: "1" } } } : {}),
220
+ ...(meta?.served ? { instance } : {}),
221
+ });
222
+ if (!meta?.served) display.setContent(await (await fetch("/api/page?id=${encodeURIComponent(id)}")).text());
223
+ display.on("outcome", (outcome) => {
224
+ const fallback = frameFallback(outcome);
225
+ if (fallback !== null) problem(fallback.title + ": " + fallback.message);
226
226
  });
227
- if (!meta.served) display.setContent(await (await fetch("/api/page?id=${encodeURIComponent(id)}")).text());
228
- display.on("outcome", (outcome) => { if (outcome.state !== "loaded") problem("The page couldn't be shown here (" + (outcome.reason ?? outcome.state) + "): open it in a new tab."); });
229
227
  display.on("hostError", (error) => problem(error.message));
230
228
  }, (error) => problem("Porthole's client didn't load: " + error.message));
231
229
  </script></body></html>`;
@@ -0,0 +1,23 @@
1
+ // The example app's own page, as a person uses it: signed in, its page shown served on its own
2
+ // origin, and "Open in a new tab" opening the clean address.
3
+ import { expect, test } from "@playwright/test";
4
+
5
+ const port = Number(process.env.PORTHOLE_EXAMPLE_PORT ?? 8796);
6
+ const app = `http://localhost:${port}`;
7
+
8
+ test("the viewer shows the page on its own origin, and opens it in a new tab", async ({
9
+ page,
10
+ context,
11
+ }) => {
12
+ await page.goto(`${app}/login?next=/`);
13
+ await Promise.all([page.waitForURL(`${app}/`), page.click("#sign-in")]);
14
+ const frame = page.frameLocator("#frame iframe");
15
+ await expect(frame.locator("h1")).toHaveText("Hello from an agent");
16
+ const element = await page.locator("#frame iframe").elementHandle();
17
+ const origin = await (await element?.contentFrame())?.evaluate(() => location.origin);
18
+ expect(origin).toBe(`http://a-hello.content.localhost:${port}`);
19
+ const [tab] = await Promise.all([context.waitForEvent("page"), page.click("#open-tab")]);
20
+ await tab.waitForURL(`http://a-hello.content.localhost:${port}/`);
21
+ await expect(tab.locator("h1")).toHaveText("Hello from an agent");
22
+ await expect(page.locator("#problem")).toHaveText("");
23
+ });
@@ -18,7 +18,7 @@ export default defineConfig({
18
18
  webServer: {
19
19
  command: "node ../node/server.mjs",
20
20
  cwd: import.meta.dirname,
21
- url: `http://localhost:${port}/api/meta`,
21
+ url: `http://localhost:${port}/porthole/meta`,
22
22
  env: {
23
23
  PORT: String(port),
24
24
  PORTHOLE_SECRET: "example-secret-for-tests-only-0123456789",
@@ -3,7 +3,7 @@
3
3
  // (PORTHOLE_CONFORMANCE=1, examples/app.mjs): pages the suite names itself. Never ship it.
4
4
  import { test } from "@playwright/test";
5
5
  import { defineHostConformance } from "@botiverse/porthole/conformance";
6
- import { pageConfig } from "../app.mjs";
6
+ import { displays } from "../displays.mjs";
7
7
 
8
8
  const port = Number(process.env.PORTHOLE_EXAMPLE_PORT ?? 8796);
9
9
  const app = `http://localhost:${port}`;
@@ -16,8 +16,10 @@ defineHostConformance(test, {
16
16
  await page.goto(`${app}/login?next=/`);
17
17
  await Promise.all([page.waitForURL(`${app}/`), page.click("#sign-in")]);
18
18
  },
19
- issue: { url: "/api/frames" },
20
- config: () => pageConfig(`http://*.content.localhost:${port}`),
19
+ // The app's frame endpoint (content.routes), and its display kinds.
20
+ issue: { url: "/porthole/frames" },
21
+ displays,
22
+ contentSource: `http://*.content.localhost:${port}`,
21
23
  // A stored-pages app: its test page's two versions (the domain cases run on version 1).
22
24
  instances: {
23
25
  artifact: (scope, version) => ({
@@ -0,0 +1,19 @@
1
+ // The app's display kinds, in one place (defineDisplays): the server serves under them, the page
2
+ // frames under them, and the agent's tools and manual come from them. Shared by the server, the
3
+ // page (served to it as a module) and the agent's tools (examples/mcp).
4
+ import { defineDisplays } from "@botiverse/porthole";
5
+
6
+ /** The kinds as plain data: the server also hands them to the page as a module. */
7
+ export const kinds = {
8
+ // A stored page: a kind named "artifact" is the preset an artifact instance names by default.
9
+ artifact: {
10
+ preset: "artifact",
11
+ options: {
12
+ // A whole-page viewer: the frame fills its box, and the agent's manual says so.
13
+ layout: { kind: "fill" },
14
+ guide: { toolName: "show_page", guideToolName: "page_guide" },
15
+ },
16
+ },
17
+ };
18
+
19
+ export const displays = defineDisplays(kinds);
@@ -0,0 +1,121 @@
1
+ // The agent's side, as an MCP server over stdio: show_page, page_guide and check_page, each a
2
+ // tool definition Porthole makes from the app's display kind (names, descriptions and JSON
3
+ // Schemas), answered by Porthole's own helpers. With the official MCP SDK, register the same
4
+ // definitions and handlers; this file speaks the protocol by hand to stay dependency-free.
5
+ //
6
+ // node node_modules/@botiverse/porthole/examples/mcp/server.mjs (an MCP client starts it)
7
+ //
8
+ // show_page refuses only what certainly fails (over the size, nested frames, document.write…) and
9
+ // says exactly what to change; everything else comes back as warnings with the result.
10
+ // check_page runs the page in the real sandbox where this machine has a browser (Playwright);
11
+ // without one, it says so and gives the lint alone (docs/ADOPTING.md: hosts without a browser).
12
+ import { createInterface } from "node:readline";
13
+ import {
14
+ admitContent,
15
+ answerGuide,
16
+ checkTool,
17
+ guideTool,
18
+ lintContent,
19
+ showTool,
20
+ } from "@botiverse/porthole";
21
+ import { displays } from "../displays.mjs";
22
+
23
+ // The manual as served pages get it (the kind's served config, no real origin needed).
24
+ const config = displays.guideConfig("artifact", "served");
25
+ const tools = [showTool(config), guideTool(config), checkTool(config)];
26
+ const shown = new Map(); // title → html: an app stores and shows it (examples/app.mjs)
27
+
28
+ /** A browser, if this machine has Playwright: the check's driver. */
29
+ let browser = null;
30
+ async function driver() {
31
+ try {
32
+ const [{ chromium }, { playwrightDriver }] = await Promise.all([
33
+ import("@playwright/test"),
34
+ import("@botiverse/porthole/check"),
35
+ ]);
36
+ browser ??= await chromium.launch();
37
+ return playwrightDriver(browser);
38
+ } catch {
39
+ return null;
40
+ }
41
+ }
42
+
43
+ const text = (value, isError = false) => ({
44
+ content: [{ type: "text", text: value }],
45
+ ...(isError ? { isError: true } : {}),
46
+ });
47
+
48
+ async function call(name, args) {
49
+ if (name === showTool(config).name) {
50
+ const admitted = admitContent(config, String(args?.html ?? ""));
51
+ if (!admitted.ok) return text(admitted.refusal, true);
52
+ shown.set(String(args?.title ?? "Untitled"), admitted.content);
53
+ return text(admitted.note ?? "Shown.");
54
+ }
55
+ if (name === guideTool(config).name) {
56
+ const answer = answerGuide(config, args);
57
+ return "error" in answer ? text(answer.error, true) : text(answer.text);
58
+ }
59
+ if (name === checkTool(config).name) {
60
+ const html = String(args?.html ?? "");
61
+ const check = await driver();
62
+ if (check === null) {
63
+ const findings = lintContent(config, html);
64
+ return text(
65
+ `No browser here, so only what can be told without running it:\n${findings.length === 0 ? "nothing to fix." : findings.map((each) => `- ${each.message}`).join("\n")}`,
66
+ );
67
+ }
68
+ const { checkPage } = await import("@botiverse/porthole/check");
69
+ const report = await checkPage({
70
+ config,
71
+ content: html,
72
+ driver: check,
73
+ ...(Array.isArray(args?.widths) ? { widths: args.widths } : {}),
74
+ ...(Array.isArray(args?.schemes) ? { schemes: args.schemes } : {}),
75
+ });
76
+ return text(report.text, !report.ok);
77
+ }
78
+ throw Object.assign(new Error(`No tool ${name}`), { code: -32602 });
79
+ }
80
+
81
+ async function respond(message) {
82
+ switch (message.method) {
83
+ case "initialize":
84
+ return {
85
+ protocolVersion: message.params?.protocolVersion ?? "2025-06-18",
86
+ capabilities: { tools: {} },
87
+ serverInfo: { name: "porthole-example", version: "1" },
88
+ instructions: `Call ${guideTool(config).name} once before your first page, and ${checkTool(config).name} before ${showTool(config).name}.`,
89
+ };
90
+ case "tools/list":
91
+ return { tools };
92
+ case "tools/call":
93
+ return call(message.params?.name, message.params?.arguments ?? {});
94
+ case "ping":
95
+ return {};
96
+ default:
97
+ throw Object.assign(new Error(`No method ${message.method}`), { code: -32601 });
98
+ }
99
+ }
100
+
101
+ const lines = createInterface({ input: process.stdin });
102
+ lines.on("line", (line) => void handleLine(line));
103
+
104
+ async function handleLine(line) {
105
+ let message;
106
+ try {
107
+ message = JSON.parse(line);
108
+ } catch {
109
+ return;
110
+ }
111
+ if (message.id === undefined) return; // a notification
112
+ try {
113
+ const result = await respond(message);
114
+ process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", id: message.id, result })}\n`);
115
+ } catch (error) {
116
+ process.stdout.write(
117
+ `${JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: error.code ?? -32603, message: error.message } })}\n`,
118
+ );
119
+ }
120
+ }
121
+ lines.on("close", () => browser?.close());
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@botiverse/porthole",
3
- "version": "0.2.3",
3
+ "version": "0.3.0",
4
4
  "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
5
5
  "license": "Apache-2.0",
6
6
  "bin": {
@@ -39,6 +39,14 @@
39
39
  "./node": {
40
40
  "types": "./dist/node/index.d.ts",
41
41
  "default": "./dist/node/index.js"
42
+ },
43
+ "./check": {
44
+ "types": "./dist/check/index.d.ts",
45
+ "default": "./dist/check/index.js"
46
+ },
47
+ "./check/page": {
48
+ "types": "./dist/check/page-source.d.ts",
49
+ "default": "./dist/check/page-source.js"
42
50
  }
43
51
  },
44
52
  "devDependencies": {