npm - @frockbot/kernel-contracts - Versions diffs - 0.3.0 → 0.3.2 - Mend

@frockbot/kernel-contracts 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 (12) hide show

package/package.json +4 -2
package/src/applets.test.ts +299 -0
package/src/applets.ts +902 -0
package/src/authoring.test.ts +47 -0
package/src/authoring.ts +57 -21
package/src/contributions.ts +102 -0
package/src/iframe-ui.test.ts +238 -37
package/src/iframe-ui.ts +430 -89
package/src/index.ts +2 -0
package/src/isolate-context-catalog.generated.ts +3 -2
package/src/isolate.ts +98 -0
package/src/types.ts +10 -3

package/src/authoring.test.ts CHANGED Viewed

@@ -31,6 +31,53 @@ describe("the kernel-declared bundler seam", () => {
     expect(decodePackageBundleArtifactV1(ARTIFACT)).toEqual(ARTIFACT as never);
   });
+  test("decodes multi-page UI artifacts exactly", () => {
+    const page = (id: string, hash: string) => ({
+      id,
+      artifact: {
+        contentHash: hash.repeat(64),
+        size: 32,
+        mediaType: "text/html",
+        bundlerVersion: "frockbot-inline-html@1",
+      },
+      html: `<!doctype html><h1>${id}</h1>`,
+    });
+    const bundled = (uiArtifacts: unknown) => ({
+      schemaVersion: 1,
+      effectId: "author-1",
+      status: "bundled",
+      artifact: ARTIFACT,
+      module: "export const tools = [];",
+      uiArtifacts,
+      diagnostics: [],
+    });
+    const result = decodePackageBundleResultV1(
+      bundled([page("main", "b"), page("board", "c")]),
+    );
+    expect(
+      result.status === "bundled"
+        ? result.uiArtifacts?.map((entry) => entry.id)
+        : undefined,
+    ).toEqual(["main", "board"]);
+    expect(() => decodePackageBundleResultV1(bundled([]))).toThrow(
+      "non-empty bounded array",
+    );
+    expect(() =>
+      decodePackageBundleResultV1(
+        bundled([page("main", "b"), page("main", "c")]),
+      ),
+    ).toThrow("duplicate ids");
+    expect(() =>
+      decodePackageBundleResultV1(bundled([page("Main", "b")])),
+    ).toThrow("id is invalid");
+    expect(() =>
+      decodePackageBundleResultV1({
+        ...bundled([page("main", "b")]),
+        uiHtml: "<!doctype html>",
+      }),
+    ).toThrow("invalid fields");
+  });
   test("decodes a failed result exactly", () => {
     expect(
       decodePackageBundleResultV1({

package/src/authoring.ts CHANGED Viewed

@@ -18,11 +18,29 @@ export const PACKAGE_BUNDLE_ENTRY = "package.ts";
 /** Raw HTML is content-addressed without transforming it. */
 export const PACKAGE_UI_ARTIFACT_VERSION = "frockbot-inline-html@1";
+/** Manifest v5: 1..8 UI pages, each hashed and stored under its own id. */
+export const PACKAGE_UI_MAX_PAGES = 8;
+export const PACKAGE_UI_PAGE_ID = /^[a-z][a-z0-9-]{0,31}$/;
 export interface PackageBundleSourceV1 {
   path: string;
   text: string;
 }
+/** One inline-only HTML page in a bundle request. */
+export interface PackageUiPageSourceV1 {
+  id: string;
+  html: string;
+}
+/** One content-addressed HTML page in a bundle result. */
+export interface PackageUiArtifactPageV1 {
+  id: string;
+  artifact: PackageUiArtifactV1;
+  /** Exact HTML bytes; the Durable Object owns the immutable write. */
+  html: string;
+}
 export interface PackageBundleRequestV1 {
   schemaVersion: 1;
   /** Idempotency key: the Durable-Object-recorded authorship intent id. */
@@ -31,8 +49,8 @@ export interface PackageBundleRequestV1 {
   compatibilityDate: string;
   entry: "package.ts";
   sources: PackageBundleSourceV1[];
-  /** Optional immutable inline-only HTML page; never compiled into app code. */
-  ui?: { path: "ui.html"; html: string };
+  /** Immutable inline-only HTML pages; never compiled into app code. */
+  uiPages?: PackageUiPageSourceV1[];
 }
 export interface PackageBundleArtifactV1 {
@@ -57,9 +75,7 @@ export type PackageBundleResultV1 =
       effectId: string;
       status: "bundled";
       artifact: PackageBundleArtifactV1;
-      uiArtifact?: PackageUiArtifactV1;
-      /** Exact HTML bytes; the Durable Object owns the immutable write. */
-      uiHtml?: string;
+      uiArtifacts?: PackageUiArtifactPageV1[];
       /** The module bytes as text; the Durable Object owns the artifact write. */
       module: string;
       diagnostics: string[];
@@ -191,12 +207,7 @@ export function decodePackageBundleResultV1(
     throw new Error(`${label}.schemaVersion is unsupported`);
   const effectId = boundedString(value.effectId, `${label}.effectId`, 200);
   if (value.status === "bundled") {
-    const hasUi = value.uiArtifact !== undefined || value.uiHtml !== undefined;
-    if ((value.uiArtifact === undefined) !== (value.uiHtml === undefined)) {
-      throw new Error(
-        `${label} must return UI artifact metadata and HTML together`,
-      );
-    }
+    const hasUi = value.uiArtifacts !== undefined;
     exactKeys(
       value,
       [
@@ -206,7 +217,7 @@ export function decodePackageBundleResultV1(
         "artifact",
         "module",
         "diagnostics",
-        ...(hasUi ? ["uiArtifact", "uiHtml"] : []),
+        ...(hasUi ? ["uiArtifacts"] : []),
       ],
       label,
     );
@@ -216,14 +227,39 @@ export function decodePackageBundleResultV1(
     );
     if (typeof value.module !== "string" || value.module.length === 0)
       throw new Error(`${label}.module must be a non-empty string`);
-    const uiArtifact = hasUi
-      ? decodePackageUiArtifactV1(value.uiArtifact, `${label}.uiArtifact`)
-      : undefined;
-    if (
-      hasUi &&
-      (typeof value.uiHtml !== "string" || value.uiHtml.length === 0)
-    ) {
-      throw new Error(`${label}.uiHtml must be a non-empty string`);
+    let uiArtifacts: PackageUiArtifactPageV1[] | undefined;
+    if (hasUi) {
+      if (
+        !Array.isArray(value.uiArtifacts) ||
+        value.uiArtifacts.length === 0 ||
+        value.uiArtifacts.length > PACKAGE_UI_MAX_PAGES
+      ) {
+        throw new Error(
+          `${label}.uiArtifacts must be a non-empty bounded array`,
+        );
+      }
+      uiArtifacts = value.uiArtifacts.map((candidate, index) => {
+        const pageLabel = `${label}.uiArtifacts[${index}]`;
+        const page = record(candidate, pageLabel);
+        exactKeys(page, ["id", "artifact", "html"], pageLabel);
+        const id = boundedString(page.id, `${pageLabel}.id`, 32);
+        if (!PACKAGE_UI_PAGE_ID.test(id))
+          throw new Error(`${pageLabel}.id is invalid`);
+        if (typeof page.html !== "string" || page.html.length === 0)
+          throw new Error(`${pageLabel}.html must be a non-empty string`);
+        return {
+          id,
+          artifact: decodePackageUiArtifactV1(
+            page.artifact,
+            `${pageLabel}.artifact`,
+          ),
+          html: page.html,
+        };
+      });
+      if (
+        new Set(uiArtifacts.map((page) => page.id)).size !== uiArtifacts.length
+      )
+        throw new Error(`${label}.uiArtifacts contains duplicate ids`);
     }
     return {
       schemaVersion: 1,
@@ -231,7 +267,7 @@ export function decodePackageBundleResultV1(
       status: "bundled",
       artifact,
       module: value.module,
-      ...(uiArtifact ? { uiArtifact, uiHtml: value.uiHtml as string } : {}),
+      ...(uiArtifacts ? { uiArtifacts } : {}),
       diagnostics: diagnostics(value.diagnostics, `${label}.diagnostics`),
     };
   }

package/src/contributions.ts ADDED Viewed

@@ -0,0 +1,102 @@
+import type { Plugin } from "cordis";
+/**
+ * How a first-party Contribution names the code that implements it.
+ *
+ * The constitution's rule is that every Contribution kind is resolved from the
+ * manifest and an artifact, never from a switch over Package identity. A
+ * non-first-party Package satisfies that by carrying an immutable artifact the
+ * loader mounts. A first-party Package that still runs in the kernel's own
+ * isolate satisfies it by exporting a **descriptor** beside its factory: the
+ * Contribution specifier its manifest declares, the host it belongs in, and
+ * the one function that builds it. An application then owns a table keyed by
+ * specifier and nothing else — no `if`, no `switch`, no comparison against a
+ * Package's name — and a specifier in a plan that reaches neither the table
+ * nor an artifact is an error when the application is compiled.
+ *
+ * These types deliberately know nothing about any Package: a descriptor is a
+ * specifier, a host, and a closure whose host object the *application*
+ * supplies. That is what lets the kernel declare them while importing no
+ * Package.
+ */
+/** The execution host a backend Contribution's factory is mounted in. */
+export type BackendContributionHostV1 = "gateway" | "bot" | "user";
+/** What a Contribution's factory is handed to publish the value it mounts. */
+export interface ContributionLifecycleV1<Contribution> {
+  mount(contribution: Contribution): () => void;
+}
+/**
+ * A first-party backend Contribution: the specifier its manifest declares, the
+ * host it belongs in, and the factory that mounts it into a Cordis fiber.
+ *
+ * `Host` is contravariant, so a descriptor written against the narrow host
+ * interface its own Package declares is usable by an application whose wide
+ * host object satisfies every Package's slice of it.
+ */
+export interface BackendContributionDescriptorV1<Host, Contribution> {
+  readonly kind: "backend";
+  readonly specifier: string;
+  readonly host: BackendContributionHostV1;
+  create(host: Host, lifecycle: ContributionLifecycleV1<Contribution>): Plugin;
+}
+/**
+ * A first-party client Contribution. A client Plugin takes no host — the
+ * client runtime is its host — so the descriptor carries the Plugin itself.
+ * The Plugin type stays generic so this module imports no client package.
+ */
+export interface ClientContributionDescriptorV1<ClientPlugin> {
+  readonly kind: "client";
+  readonly specifier: string;
+  readonly plugin: ClientPlugin;
+}
+/** Any first-party Contribution descriptor an application table can hold. */
+export type ContributionDescriptorV1<ClientPlugin = unknown> =
+  | BackendContributionDescriptorV1<never, unknown>
+  | ClientContributionDescriptorV1<ClientPlugin>;
+export function defineBackendContribution<Host, Contribution>(
+  descriptor: Omit<BackendContributionDescriptorV1<Host, Contribution>, "kind">,
+): BackendContributionDescriptorV1<Host, Contribution> {
+  return { kind: "backend", ...descriptor };
+}
+/** `defineBackendContribution` with the host fixed to the gateway. */
+export function defineGatewayContribution<Host, Contribution>(
+  descriptor: Omit<
+    BackendContributionDescriptorV1<Host, Contribution>,
+    "kind" | "host"
+  >,
+): BackendContributionDescriptorV1<Host, Contribution> {
+  return { kind: "backend", host: "gateway", ...descriptor };
+}
+/** `defineBackendContribution` with the host fixed to the User Durable Object. */
+export function defineUserBackendContribution<Host, Contribution>(
+  descriptor: Omit<
+    BackendContributionDescriptorV1<Host, Contribution>,
+    "kind" | "host"
+  >,
+): BackendContributionDescriptorV1<Host, Contribution> {
+  return { kind: "backend", host: "user", ...descriptor };
+}
+/** `defineBackendContribution` with the host fixed to the Bot Durable Object. */
+export function defineBotBackendContribution<Host, Contribution>(
+  descriptor: Omit<
+    BackendContributionDescriptorV1<Host, Contribution>,
+    "kind" | "host"
+  >,
+): BackendContributionDescriptorV1<Host, Contribution> {
+  return { kind: "backend", host: "bot", ...descriptor };
+}
+export function defineClientContribution<ClientPlugin>(
+  descriptor: Omit<ClientContributionDescriptorV1<ClientPlugin>, "kind">,
+): ClientContributionDescriptorV1<ClientPlugin> {
+  return { kind: "client", ...descriptor };
+}

package/src/iframe-ui.test.ts CHANGED Viewed

@@ -1,15 +1,19 @@
 import { describe, expect, test } from "bun:test";
 import {
   decodePackageIframeCatalogV1,
-  decodePackageIframePageMessageV1,
+  decodePackageIframePageMessageV2,
   decodePackageIframeToolCommandV1,
+  iframePageSlotAllowedV1,
+  packageIframeExternalUrlAllowedV2,
+  packageIframeFocusAllowedV2,
   packageIframeToolAllowedV1,
+  PACKAGE_IFRAME_BRIDGE_VERSION,
 } from "./iframe-ui.js";
-describe("Package iframe bridge v1", () => {
+describe("Package iframe bridge v2", () => {
   test("exactly decodes the two page-to-host messages", () => {
     expect(
-      decodePackageIframePageMessageV1({
+      decodePackageIframePageMessageV2({
         schemaVersion: 1,
         type: "callTool",
         name: "weather_lookup",
@@ -17,14 +21,14 @@ describe("Package iframe bridge v1", () => {
       }),
     ).toMatchObject({ type: "callTool", name: "weather_lookup" });
     expect(
-      decodePackageIframePageMessageV1({
+      decodePackageIframePageMessageV2({
         schemaVersion: 1,
         type: "resize",
         height: 320,
       }),
     ).toEqual({ schemaVersion: 1, type: "resize", height: 320 });
     expect(() =>
-      decodePackageIframePageMessageV1({
+      decodePackageIframePageMessageV2({
         schemaVersion: 1,
         type: "resize",
         height: 320,
@@ -33,6 +37,105 @@ describe("Package iframe bridge v1", () => {
     ).toThrow("invalid fields");
   });
+  test("keeps a version 1 page working and adds the version 2 messages", () => {
+    // A v1 page's message decodes as v1 and is answered at v1, so a page
+    // published before this bridge existed is unaffected by the bump.
+    expect(
+      decodePackageIframePageMessageV2({
+        schemaVersion: 1,
+        type: "resize",
+        height: 120,
+      }).schemaVersion,
+    ).toBe(1);
+    expect(PACKAGE_IFRAME_BRIDGE_VERSION).toBe(2);
+    expect(
+      decodePackageIframePageMessageV2({
+        schemaVersion: 2,
+        type: "hello",
+        bridgeVersion: 2,
+      }),
+    ).toEqual({ schemaVersion: 2, type: "hello", bridgeVersion: 2 });
+    expect(
+      decodePackageIframePageMessageV2({
+        schemaVersion: 2,
+        type: "focus",
+        appletId: "todo.abc123",
+      }),
+    ).toEqual({ schemaVersion: 2, type: "focus", appletId: "todo.abc123" });
+    expect(
+      decodePackageIframePageMessageV2({
+        schemaVersion: 2,
+        type: "focus",
+        appletId: null,
+      }),
+    ).toEqual({ schemaVersion: 2, type: "focus", appletId: null });
+    expect(
+      decodePackageIframePageMessageV2({
+        schemaVersion: 2,
+        type: "openExternal",
+        url: "https://ui.example.com/packages/a.html",
+      }),
+    ).toMatchObject({ type: "openExternal" });
+  });
+  test("fails closed on v2 messages claiming version 1 and on bad payloads", () => {
+    // A page cannot reach a v2 capability by claiming the older version.
+    for (const type of ["hello", "focus", "openExternal"]) {
+      expect(() =>
+        decodePackageIframePageMessageV2({
+          schemaVersion: 1,
+          type,
+          appletId: null,
+          url: "https://ui.example.com/",
+          bridgeVersion: 1,
+        }),
+      ).toThrow("type is invalid");
+    }
+    expect(() =>
+      decodePackageIframePageMessageV2({
+        schemaVersion: 2,
+        type: "focus",
+        appletId: "Not An Applet",
+      }),
+    ).toThrow("appletId is invalid");
+    expect(() =>
+      decodePackageIframePageMessageV2({
+        schemaVersion: 2,
+        type: "openExternal",
+        url: "javascript:alert(1)",
+      }),
+    ).toThrow("url is invalid");
+    expect(() =>
+      decodePackageIframePageMessageV2({
+        schemaVersion: 3,
+        type: "resize",
+        height: 1,
+      }),
+    ).toThrow("schemaVersion is unsupported");
+  });
+  test("an external open is limited to the artifact origin", () => {
+    const origin = "https://ui.example.com";
+    expect(
+      packageIframeExternalUrlAllowedV2(`${origin}/packages/a.html`, origin),
+    ).toBe(true);
+    expect(
+      packageIframeExternalUrlAllowedV2("https://evil.example.com/", origin),
+    ).toBe(false);
+    expect(packageIframeExternalUrlAllowedV2("not a url", origin)).toBe(false);
+  });
+  test("only the Package that owns the focus tool may change the focus", () => {
+    expect(
+      packageIframeFocusAllowedV2({
+        declaredTools: ["applet_focus", "applet_list"],
+      }),
+    ).toBe(true);
+    expect(
+      packageIframeFocusAllowedV2({ declaredTools: ["weather_lookup"] }),
+    ).toBe(false);
+  });
   test("refuses a tool the Package did not declare", () => {
     const contribution = { declaredTools: ["weather_lookup"] };
     expect(packageIframeToolAllowedV1(contribution, "weather_lookup")).toBe(
@@ -58,42 +161,140 @@ describe("Package iframe bridge v1", () => {
     ).toThrow("invalid fields");
   });
-  test("bounds projected HTML artifacts at the catalog seam", () => {
-    const catalog = {
-      schemaVersion: 1,
-      botId: "bot",
-      generationId: "generation-1",
-      artifactOrigin: "https://ui.bot.frockbot.com",
-      contributions: [
-        {
-          packageId: "weather-page",
-          displayName: "Weather page",
-          provenance: "Bot-authored",
-          artifact: {
-            contentHash: "a".repeat(64),
-            size: 256 * 1024,
-            mediaType: "text/html",
-            bundlerVersion: "frockbot-inline-html@1",
+  const artifact = (hash: string) => ({
+    contentHash: hash.repeat(64),
+    size: 256 * 1024,
+    mediaType: "text/html",
+    bundlerVersion: "frockbot-inline-html@1",
+  });
+  const catalog = () => ({
+    schemaVersion: 1,
+    botId: "bot",
+    generationId: "generation-1",
+    artifactOrigin: "https://ui.bot.frockbot.com",
+    contributions: [
+      {
+        packageId: "weather-page",
+        displayName: "Weather page",
+        provenance: "Bot-authored",
+        pages: [
+          {
+            id: "main",
+            artifact: artifact("a"),
+            mounts: [{ slot: "frockbot.tool-result:weather_lookup" }],
           },
-          mounts: [{ slot: "frockbot.tool-result:weather_lookup" }],
-          declaredTools: ["weather_lookup"],
-        },
-      ],
-    };
-    expect(decodePackageIframeCatalogV1(catalog).contributions).toHaveLength(1);
-    expect(() =>
-      decodePackageIframeCatalogV1({
-        ...catalog,
-        contributions: [
           {
-            ...catalog.contributions[0],
-            artifact: {
-              ...catalog.contributions[0]!.artifact,
-              size: 256 * 1024 + 1,
-            },
+            id: "board",
+            artifact: artifact("b"),
+            mounts: [
+              { slot: "frockbot.surface:board" },
+              { slot: "frockbot.right-panel" },
+            ],
           },
         ],
-      }),
+        entries: [
+          {
+            id: "open",
+            slot: "frockbot.sidebar-actions",
+            order: 5,
+            label: "Weather board",
+            icon: "sparkle",
+            opens: { kind: "surface", page: "board" },
+          },
+        ],
+        declaredTools: ["weather_lookup"],
+      },
+    ],
+  });
+  const withContribution = (patch: Record<string, unknown>) => ({
+    ...catalog(),
+    contributions: [{ ...catalog().contributions[0]!, ...patch }],
+  });
+  test("bounds projected HTML artifacts at the catalog seam", () => {
+    const decoded = decodePackageIframeCatalogV1(catalog());
+    expect(decoded.contributions).toHaveLength(1);
+    expect(decoded.contributions[0]!.pages.map((page) => page.id)).toEqual([
+      "main",
+      "board",
+    ]);
+    expect(decoded.contributions[0]!.entries).toHaveLength(1);
+    expect(() =>
+      decodePackageIframeCatalogV1(
+        withContribution({
+          pages: [
+            {
+              ...catalog().contributions[0]!.pages[0]!,
+              artifact: { ...artifact("a"), size: 256 * 1024 + 1 },
+            },
+          ],
+          entries: [],
+        }),
+      ),
     ).toThrow("metadata is invalid");
   });
+  test("refuses catalog pages and entries outside the manifest rules", () => {
+    expect(() =>
+      decodePackageIframeCatalogV1(withContribution({ pages: [] })),
+    ).toThrow("non-empty bounded array");
+    expect(() =>
+      decodePackageIframeCatalogV1(
+        withContribution({
+          pages: [
+            {
+              id: "main",
+              artifact: artifact("a"),
+              mounts: [{ slot: "frockbot.surface:absent" }],
+            },
+          ],
+          entries: [],
+        }),
+      ),
+    ).toThrow("unsafe slot");
+    expect(() =>
+      decodePackageIframeCatalogV1(
+        withContribution({
+          entries: [
+            {
+              ...catalog().contributions[0]!.entries[0]!,
+              opens: { kind: "surface", page: "main" },
+            },
+          ],
+        }),
+      ),
+    ).toThrow("names no surface page");
+    expect(() =>
+      decodePackageIframeCatalogV1(
+        withContribution({
+          pages: [
+            catalog().contributions[0]!.pages[0]!,
+            { ...catalog().contributions[0]!.pages[1]!, id: "main" },
+          ],
+        }),
+      ),
+    ).toThrow("duplicate ids");
+  });
+  test("names one slot rule for every iframe seam", () => {
+    const context = { declaredTools: ["weather_lookup"], pageIds: ["board"] };
+    for (const slot of [
+      "frockbot.bot-settings-sections",
+      "frockbot.right-panel",
+      "frockbot.tool-result:weather_lookup",
+      "frockbot.surface:board",
+    ]) {
+      expect(iframePageSlotAllowedV1(slot, context)).toBe(true);
+    }
+    for (const slot of [
+      "root",
+      "frockbot.sidebar-actions",
+      "frockbot.tool-result:package_author",
+      "frockbot.surface:list",
+    ]) {
+      expect(iframePageSlotAllowedV1(slot, context)).toBe(false);
+    }
+  });
 });