@frockbot/kernel-composition 0.1.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-composition",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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.2"
+    "@frockbot/kernel-contracts": "0.1.4"
   },
   "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

@@ -139,6 +139,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}"`,
         );

package/src/index.test.ts

@@ -427,11 +427,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 +523,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"],
           },
         ],
       },

package/src/isolate-host.test.ts

@@ -178,7 +178,7 @@ describe("Bot isolate contribution host", () => {
   test("a caller that omits the binding digest does not compile", () => {
     // @ts-expect-error the binding digest is required: an isolate loaded with
     // no digest of its granted bindings would share a loader id across
-    // Assignments and generations.
+    // enabled bindings and generations.
     void botIsolateModuleSetHashV1(CONTENT_HASH);
     expect(true).toBe(true);
   });
@@ -191,20 +191,60 @@ describe("Bot isolate contribution host", () => {
     expect(loads[0]!.loaderId).not.toBe(other.loads[0]!.loaderId);
   });
 
-  test("keys the loader id on the User, the Bot and the module set", async () => {
+  test("reuses the loader id only for the same Bot, generation, and enabled set", async () => {
     const { host: subject, loads } = host();
     await subject.prepare(descriptor());
-    const other = host({ botId: "bot-2" });
-    await other.host.prepare(descriptor());
+    const same = host();
+    await same.host.prepare(descriptor());
     const expected = await botIsolateModuleSetHashV1(
       CONTENT_HASH,
       BINDING_DIGEST,
     );
-    expect(loads[0]!.loaderId).toBe(`bot-package:user-1:bot-1:${expected}`);
-    expect(other.loads[0]!.loaderId).toBe(
-      `bot-package:user-1:bot-2:${expected}`,
+    expect(loads[0]!.loaderId).toBe(`bot-package:user-1:${expected}`);
+    expect(same.loads[0]!.loaderId).toBe(loads[0]!.loaderId);
+  });
+
+  test("changes the loader id with the Bot, generation, or enabled set", async () => {
+    const first = host();
+    const otherBot = host({ botId: "bot-2", bindingDigest: "d".repeat(64) });
+    const otherGeneration = host({
+      generationId: "gen-2",
+      bindingDigest: "e".repeat(64),
+    });
+    const otherEnabledSet = host({ bindingDigest: "f".repeat(64) });
+
+    await Promise.all([
+      first.host.prepare(descriptor()),
+      otherBot.host.prepare(descriptor()),
+      otherGeneration.host.prepare(descriptor()),
+      otherEnabledSet.host.prepare(descriptor()),
+    ]);
+
+    const loaderIds = [
+      first.loads[0]!.loaderId,
+      otherBot.loads[0]!.loaderId,
+      otherGeneration.loads[0]!.loaderId,
+      otherEnabledSet.loads[0]!.loaderId,
+    ];
+    expect(new Set(loaderIds).size).toBe(loaderIds.length);
+  });
+
+  test("never shares a loader id across Users", async () => {
+    const first = host();
+    const otherUser = host({ userId: "user-2" });
+
+    await Promise.all([
+      first.host.prepare(descriptor()),
+      otherUser.host.prepare(descriptor()),
+    ]);
+
+    expect(first.loads[0]!.loaderId).toMatch(
+      /^bot-package:user-1:[0-9a-f]{64}$/,
+    );
+    expect(otherUser.loads[0]!.loaderId).toMatch(
+      /^bot-package:user-2:[0-9a-f]{64}$/,
     );
-    expect(loads[0]!.loaderId).not.toBe(other.loads[0]!.loaderId);
+    expect(otherUser.loads[0]!.loaderId).not.toBe(first.loads[0]!.loaderId);
   });
 
   test("health failure is a prepare failure with a diagnostic", async () => {

package/src/isolate-host.ts

@@ -5,12 +5,12 @@
 // It sits beside `LocalCordisContributionHost` because it is the *other*
 // execution host the constitution names — first-party Packages run in the
 // kernel isolate, everything else runs in a loaded Worker with
-// `globalOutbound` disabled and only Assignment-derived bindings.
+// `globalOutbound` disabled and only enabled-capability bindings.
 //
 // Two behaviours come straight from `docs/research/spike-worker-loader-from-do.md`:
 // `.get()` never throws, so mount and `health()` are a single guarded phase;
 // and a reused loader id silently serves the first code, so the id is nothing
-// but the content address of the module set actually mounted.
+// but the content address of the mounted modules and their baked-in bindings.
 import {
   decodeIsolateHealthV1,
   decodeIsolateToolResultV1,
@@ -95,11 +95,11 @@ export interface BotIsolateHostOptions {
    */
   capabilities: BotCapabilitiesStub;
   /**
-   * A content address of the Assignment-derived bindings this isolate is
-   * loaded with. Required, and part of the loader id, because a loader id is
-   * served from cache: the `env` a Bot isolate was first loaded with is the
-   * `env` it keeps, so a change in the Bot's Assignments must produce a new
-   * isolate or the isolate would keep answering from a revoked authority.
+   * A content address of every binding this isolate is loaded with: User, Bot,
+   * Composition generation, and the User's enabled capability set. Required,
+   * and part of the loader id, because the `env` first loaded under one id is
+   * the `env` it keeps. Any changed binding must therefore produce a new
+   * isolate (AGENTS.md Package composition; ADR 0019).
    */
   bindingDigest: string;
   compatibilityDate: string;
@@ -120,8 +120,8 @@ export const BOT_ISOLATE_DEFAULT_HEALTH_DEADLINE_MS = 10_000;
 
 /**
  * The content address of what a Bot isolate mounts: the kernel wrapper text,
- * the Package artifact, and the digest of the Assignment-derived bindings it
- * is loaded with. A change to any of the three is a new isolate.
+ * the Package artifact, and the digest of every binding baked into its `env`.
+ * A change to any of the three is a new isolate.
  */
 export async function botIsolateModuleSetHashV1(
   artifactContentHash: string,
@@ -241,7 +241,6 @@ export class BotIsolateContributionHost implements ContributionHost {
     const source = await this.loadSource(packageId, artifact.contentHash);
     const loaderId = isolateLoaderIdV1({
       userId: this.options.userId,
-      botId: this.options.botId,
       artifactSetHash: await botIsolateModuleSetHashV1(
         artifact.contentHash,
         this.options.bindingDigest,

package/src/manifest.ts

@@ -81,6 +81,12 @@ export interface PackageSettingDefinition {
   id: string;
   schemaVersion: number;
   scopes: SettingScope[];
+  /**
+   * A kernel-consumed semantic role. The model role is deliberately generic:
+   * ADR 0019 lets a Package opt the User into model choice without teaching
+   * the kernel that Package's identity or policy.
+   */
+  role?: "model";
   schema: PackageSettingSchema;
 }
 
@@ -130,6 +136,7 @@ export interface FrockBotManifest {
   version: string;
   compatibility: { frockbot: string };
   dependencies: Record<string, string>;
+  defaultEnablement?: "enabled" | "disabled";
   contributions: {
     backend?: BackendContribution[];
     runtime?: RuntimeContribution;
@@ -221,6 +228,18 @@ function decodeDependencies(value: unknown): Record<string, string> {
   return dependencies;
 }
 
+function decodeDefaultEnablement(
+  value: unknown,
+): FrockBotManifest["defaultEnablement"] {
+  if (value === undefined) return undefined;
+  if (value !== "enabled" && value !== "disabled") {
+    throw new Error(
+      'manifest defaultEnablement must be "enabled" or "disabled"',
+    );
+  }
+  return value;
+}
+
 function decodeIdentity(
   value: Record<string, unknown>,
 ): Pick<FrockBotManifest, "id" | "displayName" | "version" | "permissions"> {
@@ -301,6 +320,7 @@ function isV3OrLater(value: Record<string, unknown>): boolean {
 
 function decodeV2(value: Record<string, unknown>): FrockBotManifest {
   const identity = decodeIdentity(value);
+  const defaultEnablement = decodeDefaultEnablement(value.defaultEnablement);
   if (!isRecord(value.compatibility)) {
     throw new Error("manifest compatibility must be an object");
   }
@@ -437,6 +457,7 @@ function decodeV2(value: Record<string, unknown>): FrockBotManifest {
       frockbot: requiredString(value.compatibility, "frockbot"),
     },
     dependencies: decodeDependencies(value.dependencies),
+    ...(defaultEnablement ? { defaultEnablement } : {}),
     contributions,
   };
 }
@@ -905,6 +926,44 @@ function safeSchema(value: unknown): PackageSettingSchema {
   return decodeSafeSchema(value, 0);
 }
 
+/**
+ * The one object contract the kernel interprets from a setting value. Keeping
+ * this exact prevents a Package from smuggling provider policy into the model
+ * seam while still letting ordinary settings use the supported schema subset.
+ */
+function assertModelBindingSchema(schema: PackageSettingSchema): void {
+  const fields = Reflect.ownKeys(schema);
+  const properties = schema.properties;
+  const required = schema.required;
+  if (
+    fields.length !== 4 ||
+    !fields.every((field) =>
+      ["type", "properties", "required", "additionalProperties"].includes(
+        String(field),
+      ),
+    ) ||
+    schema.type !== "object" ||
+    schema.additionalProperties !== false ||
+    !properties ||
+    Reflect.ownKeys(properties).length !== 2 ||
+    !Object.hasOwn(properties, "connectionId") ||
+    !Object.hasOwn(properties, "providerModelId") ||
+    Reflect.ownKeys(properties.connectionId ?? {}).length !== 1 ||
+    properties.connectionId?.type !== "string" ||
+    Reflect.ownKeys(properties.providerModelId ?? {}).length !== 1 ||
+    properties.providerModelId?.type !== "string" ||
+    !required ||
+    required.length !== 2 ||
+    new Set(required).size !== 2 ||
+    !required.includes("connectionId") ||
+    !required.includes("providerModelId")
+  ) {
+    throw new Error(
+      'manifest model setting schema must be exactly an object with required string properties "connectionId" and "providerModelId" and no additional properties',
+    );
+  }
+}
+
 function decodeCapabilityAdmission(value: unknown): {
   turnTypes: TurnTypeV1[];
   subagentRoles?: string[];
@@ -984,7 +1043,13 @@ function settingDefinitions(
     // that round-trips through this decoder decodes again unchanged.
     exactFields(
       setting,
-      ["id", "schemaVersion", "schema", "scopes"],
+      [
+        "id",
+        "schemaVersion",
+        "schema",
+        "scopes",
+        ...(scope === "package" ? ["role"] : []),
+      ],
       "manifest setting definition",
     );
     const schemaVersion = setting.schemaVersion;
@@ -1019,11 +1084,17 @@ function settingDefinitions(
     ) {
       throw new Error("manifest setting scopes must contain user or bot");
     }
+    if (setting.role !== undefined && setting.role !== "model") {
+      throw new Error('manifest setting role must be "model"');
+    }
+    const schema = safeSchema(setting.schema);
+    if (setting.role === "model") assertModelBindingSchema(schema);
     return {
       id: definitionId(setting),
       schemaVersion: schemaVersion as number,
       scopes: scopes as SettingScope[],
-      schema: safeSchema(setting.schema),
+      ...(setting.role === undefined ? {} : { role: setting.role }),
+      schema,
     };
   });
 }
@@ -1196,6 +1267,7 @@ export function decodeFrockBotManifest(value: unknown): FrockBotManifest {
         "permissions",
         "compatibility",
         "dependencies",
+        "defaultEnablement",
         "contributions",
         ...(isV3OrLater(value) ? ["configuration"] : []),
       ],