@frockbot/kernel-composition 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-composition",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -20,7 +20,7 @@
   "dependencies": {
     "cordis": "4.0.0-rc.8",
     "semver": "7.8.5",
-    "@frockbot/kernel-contracts": "0.1.3"
+    "@frockbot/kernel-contracts": "0.2.0"
   },
   "devDependencies": {
     "@types/bun": "1.4.0",

package/src/compiler.test.ts

@@ -12,6 +12,7 @@ function runtimeManifest(
     version?: string;
     permissions?: string[];
     dependencies?: Record<string, string>;
+    defaultEnablement?: "enabled" | "disabled";
     compatibility?: string;
   } = {},
 ) {
@@ -22,6 +23,7 @@ function runtimeManifest(
     version: options.version ?? "1.0.0",
     compatibility: { frockbot: options.compatibility ?? ">=0.0.1" },
     dependencies: options.dependencies,
+    defaultEnablement: options.defaultEnablement,
     contributions: { runtime: { entry: "./runtime" } },
     permissions: options.permissions ?? [],
   };
@@ -191,6 +193,21 @@ describe("compileApplicationPlan", () => {
     );
   });
 
+  test("allows a disabled Package to depend on a Catalog Package", async () => {
+    const plan = await compileApplicationPlan(
+      { schemaVersion: 1, packages: [selection("@fixture/feature")] },
+      resolver({
+        "@fixture/feature": runtimeManifest("feature", {
+          dependencies: { optional: "^1.0.0" },
+          defaultEnablement: "disabled",
+        }),
+      }),
+      { frockbotVersion: "1.0.0" },
+    );
+
+    expect(plan.packages[0]?.manifest.defaultEnablement).toBe("disabled");
+  });
+
   test("validates client roots and declared outlets", async () => {
     const clientManifest = (
       id: string,

package/src/compiler.ts

@@ -1,4 +1,8 @@
-import { decodeFrockBotManifest, type FrockBotManifest } from "./manifest.ts";
+import {
+  decodeFrockBotManifest,
+  isClientIframeContribution,
+  type FrockBotManifest,
+} from "./manifest.ts";
 import { satisfies, valid } from "semver";
 
 export type JsonValue =
@@ -139,6 +143,10 @@ function orderedPackages(
     ).sort(([left], [right]) => left.localeCompare(right))) {
       const dependency = packages.get(dependencyId);
       if (!dependency) {
+        // A disabled-by-default Package may depend on a Package available only
+        // from the User's Catalog. Settings refuses to enable it until an
+        // installed dependency row exists; enabled built-ins still fail here.
+        if (pkg.manifest.defaultEnablement === "disabled") continue;
         throw new Error(
           `package "${pkg.id}" requires missing package "${dependencyId}"`,
         );
@@ -162,7 +170,9 @@ function orderedPackages(
 function validateClientComposition(packages: readonly CompiledPackage[]): void {
   const clients = packages.flatMap((pkg) => {
     const client = pkg.manifest.contributions.client;
-    return client ? [{ id: pkg.id, client }] : [];
+    return client && !isClientIframeContribution(client)
+      ? [{ id: pkg.id, client }]
+      : [];
   });
   const roots = clients.flatMap(({ id, client }) =>
     client.mounts.filter((mount) => mount.slot === "root").map(() => id),

package/src/generation.test.ts

@@ -200,4 +200,59 @@ describe("Composition generation v1", () => {
       }),
     ).toThrow("mediaType is invalid");
   });
+
+  test("decodes a Catalog isolate member and its plain-language generation summary", async () => {
+    const generation = await bootstrap();
+    const member = {
+      packageId: "parcel-tracking",
+      specifier: "catalog:parcel-tracking",
+      version: "0.0.1",
+      manifestHash: "c".repeat(64),
+      provenance: {
+        kind: "catalog" as const,
+        packageId: "parcel-tracking",
+        version: "0.0.1",
+        catalogId: "parcel-tracking",
+        catalogGeneration: "catalog-1",
+        contentHash: "d".repeat(64),
+      },
+      artifact: {
+        contentHash: "d".repeat(64),
+        size: 512,
+        mediaType: "application/javascript" as const,
+        bundlerVersion: "catalog-test@1",
+      },
+    };
+    const decoded = decodeCompositionGenerationV1({
+      ...generation,
+      members: [member],
+      artifactSetHash: await compositionArtifactSetHashV1([member]),
+      origin: {
+        kind: "bot-catalog",
+        action: "install",
+        packageId: "parcel-tracking",
+        catalogId: "parcel-tracking",
+        botId: "primary",
+        runId: "run-1",
+        sessionId: "user-1:primary",
+        turnId: "turn-1",
+      },
+      summary: "Added parcel tracking",
+    });
+
+    expect(decoded.summary).toBe("Added parcel tracking");
+    expect(decoded.members[0]?.provenance.kind).toBe("catalog");
+    expect(() =>
+      decodeCompositionGenerationV1({
+        ...decoded,
+        members: [{ ...member, artifact: undefined }],
+      }),
+    ).toThrow("must match its Bot-isolate artifact");
+    expect(() =>
+      decodeCompositionGenerationV1({
+        ...decoded,
+        summary: "Added\nparcel tracking",
+      }),
+    ).toThrow("must be one trimmed line");
+  });
 });

package/src/generation.ts

@@ -7,6 +7,14 @@ import { canonicalJson, sha256 } from "./compiler.ts";
 
 export type PackageProvenanceV1 =
   | { kind: "first-party"; packageId: string; version: string }
+  | {
+      kind: "catalog";
+      packageId: string;
+      version: string;
+      catalogId: string;
+      catalogGeneration: string;
+      contentHash: string;
+    }
   | {
       kind: "user";
       packageId: string;
@@ -46,8 +54,25 @@ export interface CompositionMemberV1 {
 export type CompositionOriginV1 =
   | { kind: "bootstrap" }
   | { kind: "bot-authored"; runId: string; sessionId: string; turnId: string }
+  | {
+      kind: "bot-catalog";
+      action: "install" | "update" | "remove";
+      packageId: string;
+      catalogId: string;
+      botId: string;
+      runId: string;
+      sessionId: string;
+      turnId: string;
+    }
   | { kind: "user-install"; userId: string }
-  | { kind: "revert"; revertsTo: string; userId: string };
+  | { kind: "revert"; revertsTo: string; userId: string }
+  | {
+      kind: "revert";
+      revertsTo: string;
+      botId: string;
+      runId: string;
+      turnId: string;
+    };
 
 export type CompositionGenerationStatusV1 =
   "pending" | "active" | "superseded" | "failed" | "quarantined";
@@ -59,6 +84,8 @@ export interface CompositionGenerationV1 {
   /** sha-256 over the canonical member list — the loader identity. */
   artifactSetHash: string;
   parentGenerationId?: string;
+  /** Bot-written one-line audit copy for a setup change. */
+  summary?: string;
   createdAt: string;
   origin: CompositionOriginV1;
   members: CompositionMemberV1[];
@@ -83,6 +110,7 @@ export interface CompositionStore {
   revert(
     toGenerationId: string,
     origin: Extract<CompositionOriginV1, { kind: "revert" }>,
+    options?: { createdAt?: string },
   ): Promise<CompositionGenerationV1>;
   list(query: {
     limit: number;
@@ -115,7 +143,7 @@ const GENERATION_REQUIRED_KEYS = [
   "members",
   "status",
 ] as const;
-const GENERATION_OPTIONAL_KEYS = ["parentGenerationId"] as const;
+const GENERATION_OPTIONAL_KEYS = ["parentGenerationId", "summary"] as const;
 const MEMBER_REQUIRED_KEYS = [
   "packageId",
   "specifier",
@@ -132,6 +160,7 @@ const ARTIFACT_KEYS = [
 ] as const;
 const MAX_COMPOSITION_MEMBERS = 512;
 const SHA256_HEX = /^[0-9a-f]{64}$/;
+export const MAX_COMPOSITION_SUMMARY_V1 = 160;
 
 function record(value: unknown, label: string): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -195,6 +224,17 @@ function decodePackageProvenanceV1(
   if (kind === "first-party") {
     exactKeys(value, common, [], label);
     identity();
+  } else if (kind === "catalog") {
+    exactKeys(
+      value,
+      [...common, "catalogId", "catalogGeneration", "contentHash"],
+      [],
+      label,
+    );
+    identity();
+    boundedString(value.catalogId, `${label}.catalogId`, 64);
+    boundedString(value.catalogGeneration, `${label}.catalogGeneration`, 64);
+    hashString(value.contentHash, `${label}.contentHash`);
   } else if (kind === "user") {
     exactKeys(value, [...common, "userId", "authoredAt"], [], label);
     identity();
@@ -251,15 +291,25 @@ function decodeCompositionMemberV1(
   if (provenance.packageId !== packageId || provenance.version !== version) {
     throw new Error(`${label}.provenance does not match its member`);
   }
+  const artifact =
+    value.artifact === undefined
+      ? undefined
+      : decodeArtifactRefV1(value.artifact, `${label}.artifact`);
+  if (
+    provenance.kind === "catalog" &&
+    (!artifact || artifact.contentHash !== provenance.contentHash)
+  ) {
+    throw new Error(
+      `${label}.catalog provenance must match its Bot-isolate artifact`,
+    );
+  }
   return {
     packageId,
     specifier,
     version,
     manifestHash,
     provenance,
-    ...(value.artifact === undefined
-      ? {}
-      : { artifact: decodeArtifactRefV1(value.artifact, `${label}.artifact`) }),
+    ...(artifact === undefined ? {} : { artifact }),
   };
 }
 
@@ -276,13 +326,54 @@ function decodeCompositionOriginV1(
     boundedString(value.runId, `${label}.runId`, 128);
     boundedString(value.sessionId, `${label}.sessionId`, 257);
     boundedString(value.turnId, `${label}.turnId`, 128);
+  } else if (kind === "bot-catalog") {
+    exactKeys(
+      value,
+      [
+        "kind",
+        "action",
+        "packageId",
+        "catalogId",
+        "botId",
+        "runId",
+        "sessionId",
+        "turnId",
+      ],
+      [],
+      label,
+    );
+    if (
+      value.action !== "install" &&
+      value.action !== "update" &&
+      value.action !== "remove"
+    ) {
+      throw new Error(`${label}.action is invalid`);
+    }
+    boundedString(value.packageId, `${label}.packageId`, 128);
+    boundedString(value.catalogId, `${label}.catalogId`, 64);
+    boundedString(value.botId, `${label}.botId`, 256);
+    boundedString(value.runId, `${label}.runId`, 128);
+    boundedString(value.sessionId, `${label}.sessionId`, 257);
+    boundedString(value.turnId, `${label}.turnId`, 128);
   } else if (kind === "user-install") {
     exactKeys(value, ["kind", "userId"], [], label);
     boundedString(value.userId, `${label}.userId`, 256);
   } else if (kind === "revert") {
-    exactKeys(value, ["kind", "revertsTo", "userId"], [], label);
     boundedString(value.revertsTo, `${label}.revertsTo`, 256);
-    boundedString(value.userId, `${label}.userId`, 256);
+    if (Object.hasOwn(value, "userId")) {
+      exactKeys(value, ["kind", "revertsTo", "userId"], [], label);
+      boundedString(value.userId, `${label}.userId`, 256);
+    } else {
+      exactKeys(
+        value,
+        ["kind", "revertsTo", "botId", "runId", "turnId"],
+        [],
+        label,
+      );
+      boundedString(value.botId, `${label}.botId`, 256);
+      boundedString(value.runId, `${label}.runId`, 128);
+      boundedString(value.turnId, `${label}.turnId`, 128);
+    }
   } else {
     throw new Error(`${label}.kind is invalid`);
   }
@@ -331,6 +422,16 @@ export function decodeCompositionGenerationV1(
   if (value.parentGenerationId !== undefined) {
     boundedString(value.parentGenerationId, `${label}.parentGenerationId`, 256);
   }
+  if (value.summary !== undefined) {
+    const summary = boundedString(
+      value.summary,
+      `${label}.summary`,
+      MAX_COMPOSITION_SUMMARY_V1,
+    );
+    if (summary.trim() !== summary || /[\r\n]/u.test(summary)) {
+      throw new Error(`${label}.summary must be one trimmed line`);
+    }
+  }
   return {
     schemaVersion: 1,
     generationId,
@@ -342,6 +443,9 @@ export function decodeCompositionGenerationV1(
     ...(value.parentGenerationId === undefined
       ? {}
       : { parentGenerationId: value.parentGenerationId as string }),
+    ...(value.summary === undefined
+      ? {}
+      : { summary: value.summary as string }),
   };
 }
 

package/src/index.test.ts

@@ -295,6 +295,84 @@ describe("PackageCatalog", () => {
 });
 
 describe("decodeFrockBotManifest", () => {
+  test("accepts iframe UI only in settings or its own declared tool-result slots", () => {
+    const manifest = {
+      schemaVersion: 3,
+      id: "weather-page",
+      displayName: "Weather page",
+      version: "0.0.1",
+      compatibility: { frockbot: ">=0.0.1" },
+      dependencies: {},
+      contributions: {
+        runtime: { entry: "./package.js", host: "bot-isolate" },
+        client: {
+          kind: "iframe",
+          artifact: {
+            contentHash: "a".repeat(64),
+            size: 123,
+            mediaType: "text/html",
+            bundlerVersion: "frockbot-inline-html@1",
+          },
+          mounts: [
+            { slot: "frockbot.tool-result:weather_lookup" },
+            { slot: "frockbot.bot-settings-sections", order: 10 },
+          ],
+        },
+      },
+      tools: [
+        { name: "weather_lookup", description: "Weather", inputSchema: {} },
+      ],
+      hooks: ["agent/tool-exposure"],
+      permissions: [],
+    };
+    const decoded = decodeFrockBotManifest(manifest);
+    const client = decoded.contributions.client;
+    expect(client && "kind" in client ? client.kind : undefined).toBe("iframe");
+    expect(client?.mounts[0]).toEqual({
+      slot: "frockbot.tool-result:weather_lookup",
+    });
+    expect(decoded.hooks).toEqual(["agent/tool-exposure"]);
+    expect(() =>
+      decodeFrockBotManifest({
+        ...manifest,
+        contributions: {
+          ...manifest.contributions,
+          client: {
+            ...manifest.contributions.client,
+            mounts: [{ slot: "root" }],
+          },
+        },
+      }),
+    ).toThrow("not iframe-safe");
+    expect(() =>
+      decodeFrockBotManifest({
+        ...manifest,
+        contributions: {
+          ...manifest.contributions,
+          client: {
+            ...manifest.contributions.client,
+            mounts: [{ slot: "frockbot.tool-result:package_author" }],
+          },
+        },
+      }),
+    ).toThrow("undeclared tool");
+    expect(() =>
+      decodeFrockBotManifest({
+        ...manifest,
+        contributions: {
+          ...manifest.contributions,
+          client: {
+            ...manifest.contributions.client,
+            artifact: {
+              ...manifest.contributions.client.artifact,
+              size: 256 * 1024 + 1,
+            },
+          },
+        },
+      }),
+    ).toThrow("256 KB quota");
+  });
+
   test("keeps trusted Electron main execution exclusive to manifest v3", () => {
     const contribution = {
       desktop: {
@@ -427,11 +505,95 @@ describe("decodeFrockBotManifest", () => {
     });
   });
 
+  test("decodes the exact provider-neutral model setting role", () => {
+    const decoded = decodeFrockBotManifest({
+      ...manifest("custom-models"),
+      configuration: {
+        settings: [
+          {
+            id: "model",
+            schemaVersion: 1,
+            scopes: ["user", "bot"],
+            role: "model",
+            schema: {
+              type: "object",
+              properties: {
+                connectionId: { type: "string" },
+                providerModelId: { type: "string" },
+              },
+              required: ["connectionId", "providerModelId"],
+              additionalProperties: false,
+            },
+          },
+        ],
+      },
+    });
+
+    expect(decoded.configuration?.settings).toEqual([
+      {
+        id: "model",
+        schemaVersion: 1,
+        scopes: ["user", "bot"],
+        role: "model",
+        schema: {
+          type: "object",
+          properties: {
+            connectionId: { type: "string" },
+            providerModelId: { type: "string" },
+          },
+          required: ["connectionId", "providerModelId"],
+          additionalProperties: false,
+        },
+      },
+    ]);
+  });
+
+  test("rejects any other schema for a model-role setting", () => {
+    const exact = {
+      type: "object",
+      properties: {
+        connectionId: { type: "string" },
+        providerModelId: { type: "string" },
+      },
+      required: ["connectionId", "providerModelId"],
+      additionalProperties: false,
+    };
+    for (const schema of [
+      { ...exact, additionalProperties: true },
+      { ...exact, required: ["connectionId"] },
+      {
+        ...exact,
+        properties: {
+          ...exact.properties,
+          providerModelId: { type: "number" },
+        },
+      },
+      { ...exact, title: "Choose a model" },
+    ]) {
+      expect(() =>
+        decodeFrockBotManifest({
+          ...manifest("custom-models"),
+          configuration: {
+            settings: [
+              {
+                id: "model",
+                schemaVersion: 1,
+                scopes: ["user"],
+                role: "model",
+                schema,
+              },
+            ],
+          },
+        }),
+      ).toThrow(/model setting schema must be exactly/);
+    }
+  });
+
   test("decodes an ambient-native Connection without an authorization driver", () => {
     const decoded = decodeFrockBotManifest({
       schemaVersion: 4,
-      id: "workers-ai",
-      displayName: "Workers AI",
+      id: "flock-ai",
+      displayName: "Flock AI",
       version: "1.0.0",
       compatibility: { frockbot: ">=0.0.1" },
       contributions: { runtime: { entry: "./runtime" } },
@@ -439,18 +601,18 @@ describe("decodeFrockBotManifest", () => {
       configuration: {
         connectionTypes: [
           {
-            id: "workers-ai-account",
-            displayName: "Workers AI",
+            id: "flock-ai-account",
+            displayName: "Flock AI",
             allowMultiple: false,
             authorization: { kind: "ambient-native" },
-            capabilities: ["workers-ai-models"],
+            capabilities: ["flock-ai-models"],
           },
         ],
         capabilities: [
           {
-            id: "workers-ai-models",
+            id: "flock-ai-models",
             kind: "model",
-            connectionTypes: ["workers-ai-account"],
+            connectionTypes: ["flock-ai-account"],
           },
         ],
       },
@@ -1043,6 +1205,70 @@ describe("decodeFrockBotManifest", () => {
     ).toThrow("manifest setting schema is too large");
   });
 
+  test("decodes the exact Bot isolate runtime and tool declaration", () => {
+    const decoded = decodeFrockBotManifest({
+      schemaVersion: 3,
+      id: "authored",
+      displayName: "Authored",
+      version: "0.0.1",
+      compatibility: { frockbot: ">=0.0.1" },
+      dependencies: {},
+      contributions: {
+        runtime: { entry: "./package.js", host: "bot-isolate" },
+      },
+      tools: [
+        {
+          name: "look_up",
+          description: "Looks up a value",
+          inputSchema: { type: "object" },
+        },
+      ],
+      hooks: ["agent/tool-exposure", "tools/post-execute"],
+      permissions: [],
+    });
+
+    expect(decoded.contributions.runtime?.host).toBe("bot-isolate");
+    expect(decoded.tools?.map((tool) => tool.name)).toEqual(["look_up"]);
+    expect(decoded.hooks).toEqual([
+      "agent/tool-exposure",
+      "tools/post-execute",
+    ]);
+  });
+
+  test("requires Bot isolate runtime and tools declarations together", () => {
+    const base = {
+      schemaVersion: 3,
+      id: "authored",
+      displayName: "Authored",
+      version: "0.0.1",
+      compatibility: { frockbot: ">=0.0.1" },
+      dependencies: {},
+      permissions: [],
+    };
+    expect(() =>
+      decodeFrockBotManifest({
+        ...base,
+        contributions: {
+          runtime: { entry: "./package.js", host: "bot-isolate" },
+        },
+      }),
+    ).toThrow(/must appear together/);
+    expect(() =>
+      decodeFrockBotManifest({
+        ...base,
+        contributions: { runtime: { entry: "./package.js" } },
+        hooks: ["agent/tool-exposure"],
+      }),
+    ).toThrow(/hooks require a bot-isolate/);
+    expect(() =>
+      decodeFrockBotManifest({
+        ...base,
+        contributions: { runtime: { entry: "./package.js" } },
+        tools: [{ name: "look_up", description: "Looks", inputSchema: {} }],
+      }),
+    ).toThrow(/must appear together/);
+  });
+
   test("orders normalized contribution kinds", () => {
     const decoded = decodeFrockBotManifest({
       schemaVersion: 3,