@botiverse/porthole 0.3.0 → 0.3.2

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 (56) hide show
  1. package/README.md +3 -2
  2. package/dist/check/check.d.ts +20 -3
  3. package/dist/check/check.js +88 -25
  4. package/dist/check/drivers.d.ts +25 -6
  5. package/dist/check/drivers.js +99 -28
  6. package/dist/check/index.d.ts +2 -2
  7. package/dist/check/index.js +1 -1
  8. package/dist/check/instrument.d.ts +71 -0
  9. package/dist/check/instrument.js +84 -0
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/page.d.ts +2 -40
  12. package/dist/check/page.js +63 -43
  13. package/dist/conformance/harness-source.d.ts +2 -0
  14. package/dist/conformance/harness-source.js +2 -0
  15. package/dist/conformance/host-kit.d.ts +20 -7
  16. package/dist/conformance/host-kit.js +42 -48
  17. package/dist/conformance/index.d.ts +1 -1
  18. package/dist/conformance/reporter.d.ts +14 -0
  19. package/dist/conformance/reporter.js +28 -0
  20. package/dist/host/client.d.ts +33 -15
  21. package/dist/host/client.js +39 -24
  22. package/dist/node/index.d.ts +6 -2
  23. package/dist/node/index.js +53 -8
  24. package/dist/react/frame.d.ts +13 -5
  25. package/dist/react/frame.js +67 -27
  26. package/dist/react/index.d.ts +1 -1
  27. package/dist/react/view.js +6 -1
  28. package/dist/server/host.d.ts +5 -3
  29. package/dist/server/host.js +41 -12
  30. package/docs/ADOPTING.md +115 -26
  31. package/docs/DECISIONS.md +167 -0
  32. package/docs/DESIGN.md +38 -13
  33. package/examples/app.mjs +23 -17
  34. package/examples/conformance/playwright.config.mjs +2 -1
  35. package/examples/conformance/porthole.spec.mjs +2 -1
  36. package/examples/displays.mjs +2 -0
  37. package/examples/node/server.mjs +16 -34
  38. package/examples/workers/worker.mjs +19 -7
  39. package/package.json +9 -3
  40. package/src/check/check.ts +122 -25
  41. package/src/check/drivers.ts +137 -39
  42. package/src/check/index.ts +8 -1
  43. package/src/check/instrument.ts +138 -0
  44. package/src/check/page-source.ts +4 -3
  45. package/src/check/page.ts +94 -68
  46. package/src/conformance/harness-source.ts +23 -0
  47. package/src/conformance/host-kit.ts +69 -46
  48. package/src/conformance/index.ts +1 -0
  49. package/src/conformance/reporter.ts +38 -0
  50. package/src/host/client.ts +65 -34
  51. package/src/node/index.ts +56 -10
  52. package/src/react/frame.tsx +89 -33
  53. package/src/react/index.ts +1 -0
  54. package/src/react/view.tsx +6 -1
  55. package/src/server/host.ts +53 -15
  56. package/dist/conformance/harness.js +0 -1662
@@ -1,42 +1,5 @@
1
- import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
2
- /**
3
- * The check page (P073): runs content in the real sandbox (the core's `createHost`, the config's
4
- * own CSP) at one width and scheme at a time, and hears what happens inside from a small script
5
- * the check puts first in the content: what it throws, what the sandbox blocks, what fails to
6
- * load, what it logs, and its width. Bundled into one script (`@botiverse/porthole/check/page`)
7
- * that `checkPage` loads into a blank page through its driver.
8
- */
9
- export interface CheckRunSpec {
10
- readonly config: PortholeConfig;
11
- readonly content: string;
12
- readonly widthPx: number;
13
- readonly heightPx?: number;
14
- readonly scheme: ColorScheme;
15
- readonly hostTheme?: Readonly<Record<string, string>>;
16
- }
17
- export interface CheckRunData {
18
- readonly errors: string[];
19
- readonly blocked: {
20
- readonly url: string;
21
- readonly directive: string;
22
- }[];
23
- readonly failedLoads: {
24
- readonly url: string;
25
- readonly tag: string;
26
- }[];
27
- readonly console: {
28
- readonly level: "error" | "warning";
29
- readonly text: string;
30
- }[];
31
- readonly height: number | null;
32
- readonly scrollWidth: number | null;
33
- readonly clientWidth: number | null;
34
- readonly outcome: string | null;
35
- }
36
- /** Put first in the content: it reports to the page that frames it. */
37
- export declare const INSTRUMENT = "<script>(() => {\n const send = (kind, data) => { try { parent.postMessage({ portholeCheck: kind, data }, \"*\"); } catch (_) {} };\n const text = (value) => { try { return String(value && value.stack ? value.message || value : value); } catch (_) { return \"?\"; } };\n for (const [method, level] of [[\"error\", \"error\"], [\"warn\", \"warning\"]]) {\n const original = console[method];\n console[method] = (...args) => { send(\"console\", { level, text: args.map(text).join(\" \").slice(0, 400) }); return original.apply(console, args); };\n }\n addEventListener(\"error\", (event) => {\n const target = event.target;\n if (target && target !== window && (target.src || target.href)) {\n send(\"load\", { url: String(target.src || target.href).slice(0, 400), tag: String(target.tagName || \"\").toLowerCase() });\n } else if (event.message || event.error) {\n const where = event.lineno ? \" (line \" + event.lineno + \")\" : \"\";\n send(\"error\", (event.error && event.error.message ? (event.error.name || \"Error\") + \": \" + event.error.message : String(event.message)).slice(0, 400) + where);\n }\n }, true);\n addEventListener(\"unhandledrejection\", (event) => send(\"error\", (\"Unhandled rejection: \" + text(event.reason)).slice(0, 400)));\n addEventListener(\"securitypolicyviolation\", (event) => send(\"blocked\", { url: String(event.blockedURI || \"inline\").slice(0, 400), directive: String(event.effectiveDirective) }));\n addEventListener(\"message\", (event) => {\n if (event.source === parent && event.data && event.data.portholeCheck === \"measure\") {\n const root = document.documentElement;\n send(\"measure\", { scrollWidth: Math.max(root.scrollWidth, document.body ? document.body.scrollWidth : 0), clientWidth: root.clientWidth });\n }\n });\n})();</script>";
38
- /** The content with the instrument first: after a document's <head>, or before a fragment. */
39
- export declare function instrumented(content: string): string;
1
+ import { type CheckRunData, type CheckRunSpec } from "./instrument.ts";
2
+ export type { CheckCall, CheckRunData, CheckRunSpec } from "./instrument.ts";
40
3
  declare const check: {
41
4
  /** Shows the content at one width and scheme; returns its run id. */
42
5
  run(spec: CheckRunSpec): number;
@@ -48,4 +11,3 @@ declare const check: {
48
11
  end(id: number): void;
49
12
  };
50
13
  export type CheckPageApi = typeof check;
51
- export {};
@@ -1,45 +1,36 @@
1
+ import { capabilitySpec, isCapabilityName, } from "../config/capabilities.js";
1
2
  import { createHost } from "../host/create-host.js";
2
- /** Put first in the content: it reports to the page that frames it. */
3
- export const INSTRUMENT = `<script>(() => {
4
- const send = (kind, data) => { try { parent.postMessage({ portholeCheck: kind, data }, "*"); } catch (_) {} };
5
- const text = (value) => { try { return String(value && value.stack ? value.message || value : value); } catch (_) { return "?"; } };
6
- for (const [method, level] of [["error", "error"], ["warn", "warning"]]) {
7
- const original = console[method];
8
- console[method] = (...args) => { send("console", { level, text: args.map(text).join(" ").slice(0, 400) }); return original.apply(console, args); };
9
- }
10
- addEventListener("error", (event) => {
11
- const target = event.target;
12
- if (target && target !== window && (target.src || target.href)) {
13
- send("load", { url: String(target.src || target.href).slice(0, 400), tag: String(target.tagName || "").toLowerCase() });
14
- } else if (event.message || event.error) {
15
- const where = event.lineno ? " (line " + event.lineno + ")" : "";
16
- send("error", (event.error && event.error.message ? (event.error.name || "Error") + ": " + event.error.message : String(event.message)).slice(0, 400) + where);
17
- }
18
- }, true);
19
- addEventListener("unhandledrejection", (event) => send("error", ("Unhandled rejection: " + text(event.reason)).slice(0, 400)));
20
- addEventListener("securitypolicyviolation", (event) => send("blocked", { url: String(event.blockedURI || "inline").slice(0, 400), directive: String(event.effectiveDirective) }));
21
- addEventListener("message", (event) => {
22
- if (event.source === parent && event.data && event.data.portholeCheck === "measure") {
23
- const root = document.documentElement;
24
- send("measure", { scrollWidth: Math.max(root.scrollWidth, document.body ? document.body.scrollWidth : 0), clientWidth: root.clientWidth });
25
- }
26
- });
27
- })();</script>`;
28
- /** The content with the instrument first: after a document's <head>, or before a fragment. */
29
- export function instrumented(content) {
30
- const head = /<head[^>]*>/iu.exec(content);
31
- if (head !== null) {
32
- const at = head.index + head[0].length;
33
- return `${content.slice(0, at)}${INSTRUMENT}${content.slice(at)}`;
34
- }
35
- const html = /<html[^>]*>/iu.exec(content);
36
- if (html !== null) {
37
- const at = html.index + html[0].length;
38
- return `${content.slice(0, at)}<head>${INSTRUMENT}</head>${content.slice(at)}`;
3
+ import { contentLine, instrumented, } from "./instrument.js";
4
+ /**
5
+ * What a host that declines answers each host function with (P074): no prompt sent, no link
6
+ * opened, nothing downloaded or copied; a tool call or a read refused.
7
+ */
8
+ const DECLINED = {
9
+ sendPrompt: () => false,
10
+ openLink: () => false,
11
+ downloadFile: () => false,
12
+ copyText: () => false,
13
+ setModelContext: () => undefined,
14
+ callTool: () => {
15
+ throw new Error("The host declined the tool call");
16
+ },
17
+ readData: () => {
18
+ throw new Error("The host declined the read");
19
+ },
20
+ };
21
+ /** A handler for each host function the config declares: it notes the call and answers no. */
22
+ function declining(capabilities, calls) {
23
+ const handlers = {};
24
+ for (const name of capabilities) {
25
+ if (isCapabilityName(name) && capabilitySpec(name).served === "handler") {
26
+ const answer = DECLINED[name];
27
+ handlers[name] = () => {
28
+ calls.push({ capability: name, outcome: "answered" });
29
+ return answer();
30
+ };
31
+ }
39
32
  }
40
- return /^\s*<!doctype/iu.test(content)
41
- ? content.replace(/^(\s*<!doctype[^>]*>)/iu, `$1${INSTRUMENT}`)
42
- : `${INSTRUMENT}${content}`;
33
+ return handlers;
43
34
  }
44
35
  const runs = new Map();
45
36
  let next = 0;
@@ -55,9 +46,17 @@ addEventListener("message", (event) => {
55
46
  }
56
47
  const said = data.data;
57
48
  switch (data.portholeCheck) {
58
- case "error":
59
- run.data.errors.push(String(data.data));
49
+ case "error": {
50
+ const error = data.data;
51
+ const line = contentLine({
52
+ file: typeof error.file === "string" ? error.file : "",
53
+ line: typeof error.line === "number" ? error.line : 0,
54
+ stack: typeof error.stack === "string" ? error.stack : "",
55
+ }, run.scriptLines);
56
+ const message = typeof error.message === "string" ? error.message : "Error";
57
+ run.data.errors.push(`${message}${line === null ? "" : ` (line ${line})`}`);
60
58
  break;
59
+ }
61
60
  case "blocked":
62
61
  run.data.blocked.push({ url: String(said.url), directive: String(said.directive) });
63
62
  break;
@@ -89,19 +88,31 @@ const check = {
89
88
  box.style.cssText = `width:${spec.widthPx}px;${spec.heightPx === undefined ? "" : `height:${spec.heightPx}px;`}`;
90
89
  document.body.append(box);
91
90
  const theme = spec.hostTheme ?? {};
91
+ const calls = [];
92
92
  const display = createHost(spec.config, {
93
93
  theme: () => theme,
94
94
  hostInfo: { name: "porthole-check", version: "1" },
95
+ // Every host function the config declares, answered as a host that declines (P074): a
96
+ // person asked to confirm says no, a handler says no, and each call is noted.
97
+ handlers: declining(Object.keys(spec.config.capabilities), calls),
98
+ confirm: () => Promise.resolve("declined"),
99
+ // A served config's instance, issued by the check's own server on this page's origin.
100
+ locator: {
101
+ locate: async (instance) => (await (await fetch("/issue", { method: "POST", body: JSON.stringify({ instance }) })).json()),
102
+ },
95
103
  }).mount(box, {
96
104
  displayId: `check-${id}`,
97
105
  title: "Check",
98
106
  scheme: spec.scheme,
107
+ ...(spec.instance === undefined ? {} : { instance: spec.instance }),
99
108
  });
100
109
  const run = {
101
110
  display,
102
111
  box,
112
+ scriptLines: spec.scriptLines,
103
113
  data: {
104
114
  errors: [],
115
+ calls,
105
116
  blocked: [],
106
117
  failedLoads: [],
107
118
  console: [],
@@ -114,11 +125,20 @@ const check = {
114
125
  display.on("resize", ({ height }) => {
115
126
  run.data.height = height;
116
127
  });
128
+ display.on("refused", ({ capability, refusal }) => {
129
+ // "failed": the declining handler's own no, already noted.
130
+ if (refusal !== "failed") {
131
+ calls.push({ capability, outcome: refusal });
132
+ }
133
+ });
117
134
  display.on("outcome", (outcome) => {
118
135
  run.data.outcome = outcome.state === "blocked" ? `blocked: ${outcome.reason}` : outcome.state;
119
136
  });
120
137
  runs.set(id, run);
121
- display.on("initialized", () => display.setContent(instrumented(spec.content)));
138
+ // A stored page comes from the check's server; a shell (served or opaque) gets the content.
139
+ if (spec.instance?.document.kind !== "artifact") {
140
+ display.on("initialized", () => display.setContent(instrumented(spec.content)));
141
+ }
122
142
  return id;
123
143
  },
124
144
  /** Asks the frame for its width; resolves when it answers (or after a second). */
@@ -0,0 +1,2 @@
1
+ declare const source: string;
2
+ export default source;