@frockbot/configuration-core 0.3.9 → 0.3.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/configuration-core",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,8 +12,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/connection-core": "0.3.9",
-    "@frockbot/kernel-composition": "0.3.9"
+    "@frockbot/connection-core": "0.3.11",
+    "@frockbot/kernel-composition": "0.3.11"
   },
   "devDependencies": {
     "@types/bun": "1.3.6",

package/src/bot-identity.test.ts

@@ -182,4 +182,40 @@ describe("bot/set-profile", () => {
       ),
     ).toEqual({ name: "Housework" });
   });
+
+  test("pins with an instant and unpins with the empty string", () => {
+    const at = "2026-09-03T10:15:00.000Z";
+    expect(
+      decodeBotSettingsViewV1(settings({ name: "Housework", pinnedAt: at })),
+    ).toMatchObject({ profile: { pinnedAt: at } });
+    expect(() =>
+      decodeBotSettingsViewV1(
+        settings({ name: "Housework", pinnedAt: "whenever" }),
+      ),
+    ).toThrow("profile.pinnedAt is invalid");
+
+    const current: BotProfile = { name: "Housework", pinnedAt: at };
+    // A later save must not reshuffle the pinned row: the instant is durable,
+    // so only an explicit change moves it.
+    expect(
+      applyBotProfilePatchV1(current, { title: "Chief" }, "user").pinnedAt,
+    ).toBe(at);
+    expect(applyBotProfilePatchV1(current, { pinnedAt: "" }, "user")).toEqual({
+      name: "Housework",
+    });
+    expect(
+      applyBotProfilePatchV1({ name: "Housework" }, { pinnedAt: at }, "user")
+        .pinnedAt,
+    ).toBe(at);
+    expect(() =>
+      decodeConfigurationCommandV1({
+        schemaVersion: 1,
+        type: "bot/set-profile",
+        commandId: "command-1",
+        botId: "primary",
+        expectedRevision: 3,
+        profile: { pinnedAt: "soon" },
+      }),
+    ).toThrow("profile.pinnedAt is invalid");
+  });
 });

package/src/index.test.ts

@@ -26,6 +26,7 @@ import {
   resolveEffectiveBotModelV1,
   type ExecutionPackageDefinition,
   type ModelBindingV1,
+  type UserSettingsViewV1,
 } from "./index.js";
 import {
   isApplicationDeploymentHash,
@@ -1657,6 +1658,144 @@ describe("effective Bot model resolution", () => {
     expect(effective.model).toBeUndefined();
   });
 
+  /**
+   * The real account shape: a platform provider that is always there, and a
+   * separate provider Package the User switched on and bound their model to.
+   */
+  const flockModel: ModelBindingV1 = {
+    connectionId: "flock-ai",
+    providerModelId: "@flock/auto",
+  };
+  const flockPackage: ExecutionPackageDefinition = {
+    packageId: "provider-flock-ai",
+    version: "0.0.1",
+    settings: [],
+    capabilities: [
+      {
+        id: "flock-ai-models",
+        kind: "model",
+        connectionTypes: ["flock-ai-account"],
+      },
+    ],
+    connectionTypes: [
+      { id: "flock-ai-account", capabilities: ["flock-ai-models"] },
+    ],
+  };
+  function withFlock(): UserSettingsViewV1 {
+    const base = user();
+    return {
+      ...base,
+      packages: [
+        ...base.packages,
+        {
+          packageId: "provider-flock-ai",
+          version: "0.0.1",
+          state: "installed",
+        },
+        {
+          packageId: "custom-models",
+          version: "0.0.1",
+          state: "installed",
+          values: { model: accountModel },
+        },
+      ],
+      connections: [
+        ...base.connections,
+        {
+          connectionId: "flock-ai",
+          packageId: "provider-flock-ai",
+          connectionTypeId: "flock-ai-account",
+          displayName: "Flock AI",
+          state: "ready",
+          providerType: "flock-ai",
+          modelCatalog: {
+            schemaVersion: 1,
+            generation: "flock-catalog-1",
+            state: "fresh",
+            models: [
+              {
+                providerModelId: "@flock/auto",
+                displayName: "Auto",
+                capabilities: { tools: true, vision: false, reasoning: true },
+                source: "discovered",
+              },
+            ],
+          },
+          safeMetadata: {},
+        },
+      ],
+      platformModel: flockModel,
+    };
+  }
+  const flockPackages = [...modelPackages, flockPackage];
+
+  test("falls back to the platform model when the bound provider is switched off", () => {
+    const providerOff = (() => {
+      const settings = withFlock();
+      return {
+        ...settings,
+        packages: settings.packages.map((pkg) =>
+          pkg.packageId === "provider-ollama-cloud"
+            ? { ...pkg, state: "disabled" as const }
+            : pkg,
+        ),
+      };
+    })();
+    const effective = resolveEffectiveBotModelV1({
+      bot: { packageValues: {} },
+      user: providerOff,
+      packages: flockPackages,
+    });
+    expect(effective.source).toBe("platform");
+    expect(effective.model).toEqual(flockModel);
+    expect(effective.binding?.state).toBe("ready");
+    expect(effective.fallback).toMatchObject({
+      from: "account",
+      model: accountModel,
+    });
+  });
+
+  test("falls back when a Bot's model has lost its Connection", () => {
+    const settings = withFlock();
+    const connectionGone: UserSettingsViewV1 = {
+      ...settings,
+      connections: settings.connections.filter(
+        (connection) => connection.connectionId !== "ollama-work",
+      ),
+    };
+    const effective = resolveEffectiveBotModelV1({
+      bot: { packageValues: { "custom-models": { model: accountModel } } },
+      user: connectionGone,
+      packages: flockPackages,
+    });
+    expect(effective).toMatchObject({ source: "platform", model: flockModel });
+    expect(effective.fallback?.from).toBe("bot");
+    expect(effective.binding?.state).toBe("ready");
+  });
+
+  test("keeps the failure when the platform model cannot stand in either", () => {
+    // Nothing to degrade to: the platform bootstrap is bound to the same
+    // switched-off Package, so the User still gets the repair sentence.
+    const settings = withFlock();
+    const bothOff: UserSettingsViewV1 = {
+      ...settings,
+      packages: settings.packages.map((pkg) =>
+        pkg.packageId === "provider-ollama-cloud"
+          ? { ...pkg, state: "disabled" as const }
+          : pkg,
+      ),
+      platformModel,
+    };
+    const effective = resolveEffectiveBotModelV1({
+      bot: { packageValues: {} },
+      user: bothOff,
+      packages: flockPackages,
+    });
+    expect(effective.source).toBe("account");
+    expect(effective.binding?.state).toBe("unavailable");
+    expect(effective.fallback).toBeUndefined();
+  });
+
   test("reports none only when no Package or platform model supplies one", () => {
     const withoutPlatform = user();
     delete withoutPlatform.platformModel;

package/src/index.ts

@@ -99,6 +99,12 @@ export interface BotProfile {
   namedBy?: BotNameProvenanceV1;
   /** Keeps the Bot out of the default sidebar list without archiving it. */
   hiddenFromSidebar?: boolean;
+  /**
+   * When the User pinned this Bot, as an ISO 8601 instant. Absent means not
+   * pinned. The instant rather than a flag, so the pinned row keeps a stable
+   * order — earliest pin first — without a second ordering field.
+   */
+  pinnedAt?: string;
 }
 
 /**
@@ -112,6 +118,8 @@ export interface BotProfilePatchV1 {
   description?: string;
   title?: string;
   hiddenFromSidebar?: boolean;
+  /** An ISO 8601 instant pins the Bot; the empty string unpins it. */
+  pinnedAt?: string;
 }
 
 export interface BotNotificationPolicy {
@@ -604,6 +612,17 @@ export interface EffectiveBotModelV1 {
   source: "bot" | "account" | "platform" | "none";
   model?: ModelBindingV1;
   binding?: ResolvedModelBindingV1;
+  /**
+   * Set when a Bot or account choice was present but could not bind — its
+   * provider Package was switched off, or its Connection is gone — and the
+   * platform bootstrap answered in its place. The chosen scope and the reason
+   * it failed survive so the client can say the Bot is running on the default.
+   */
+  fallback?: {
+    from: "bot" | "account";
+    model: ModelBindingV1;
+    failure: string;
+  };
 }
 
 /**
@@ -684,23 +703,68 @@ export function resolveEffectiveBotModelV1(input: {
     };
   };
 
+  /**
+   * A chosen model whose provider Package has been switched off, or whose
+   * Connection is gone, must not stop the Bot answering: the platform
+   * bootstrap stands in for it. Only a binding failure degrades this way — a
+   * scope conflict is the User's own contradiction and still fails closed,
+   * because there is no single choice to stand in for.
+   */
+  const platformStandIn = (
+    from: "bot" | "account",
+    model: ModelBindingV1,
+    binding: ResolvedModelBindingV1,
+  ): EffectiveBotModelV1 | undefined => {
+    const platform = input.user.platformModel;
+    if (!platform) return undefined;
+    if (
+      platform.connectionId === model.connectionId &&
+      platform.providerModelId === model.providerModelId
+    ) {
+      return undefined;
+    }
+    const platformBinding = resolveBotModelBindingV1({
+      model: platform,
+      user: input.user,
+      packages: input.packages,
+    });
+    if (platformBinding.state === "unavailable") return undefined;
+    return {
+      source: "platform",
+      model: structuredClone(platform),
+      binding: platformBinding,
+      fallback: {
+        from,
+        model: structuredClone(model),
+        failure:
+          binding.failure ?? "This Bot's model isn't available right now.",
+      },
+    };
+  };
+
   for (const scope of ["bot", "user"] as const) {
     const resolved = fromScope(scope);
+    const source = scope === "bot" ? "bot" : "account";
     if (resolved?.conflict) {
       return {
-        source: scope === "bot" ? "bot" : "account",
+        source,
         binding: { state: "unavailable", failure: resolved.conflict },
       };
     }
     if (resolved?.model) {
+      const binding = resolveBotModelBindingV1({
+        model: resolved.model,
+        user: input.user,
+        packages: input.packages,
+      });
+      if (binding.state === "unavailable") {
+        const standIn = platformStandIn(source, resolved.model, binding);
+        if (standIn) return standIn;
+      }
       return {
-        source: scope === "bot" ? "bot" : "account",
+        source,
         model: structuredClone(resolved.model),
-        binding: resolveBotModelBindingV1({
-          model: resolved.model,
-          user: input.user,
-          packages: input.packages,
-        }),
+        binding,
       };
     }
   }
@@ -1009,6 +1073,7 @@ const BOT_PROFILE_OPTIONAL_FIELDS = [
   "title",
   "namedBy",
   "hiddenFromSidebar",
+  "pinnedAt",
 ] as const;
 
 function botProfile(value: unknown): BotProfile {
@@ -1040,9 +1105,21 @@ function botProfile(value: unknown): BotProfile {
             "profile.hiddenFromSidebar",
           ),
         }),
+    ...(profile.pinnedAt === undefined
+      ? {}
+      : { pinnedAt: profileTimestamp(profile.pinnedAt, "profile.pinnedAt") }),
   };
 }
 
+/** An ISO 8601 instant a profile field carries. Never a duration or a count. */
+function profileTimestamp(value: unknown, label: string): string {
+  const candidate = text(value, label, 64);
+  if (!Number.isFinite(Date.parse(candidate))) {
+    throw new ConfigurationDecodeError(`${label} is invalid`);
+  }
+  return candidate;
+}
+
 /**
  * A patch field that carries text: a non-empty string sets it, and the empty
  * string clears it. A partial update has no other way to say "remove this".
@@ -1067,7 +1144,7 @@ function botProfilePatch(value: unknown): BotProfilePatchV1 {
     value,
     "profile",
     [],
-    ["name", "label", "description", "title", "hiddenFromSidebar"],
+    ["name", "label", "description", "title", "hiddenFromSidebar", "pinnedAt"],
   );
   if (Reflect.ownKeys(patch).length === 0) {
     throw new ConfigurationDecodeError("profile has invalid fields");
@@ -1092,6 +1169,15 @@ function botProfilePatch(value: unknown): BotProfilePatchV1 {
             "profile.hiddenFromSidebar",
           ),
         }),
+    // An instant pins; the empty string unpins, the same way text clears.
+    ...(patch.pinnedAt === undefined
+      ? {}
+      : {
+          pinnedAt:
+            patchText(patch.pinnedAt, "profile.pinnedAt", 64) === ""
+              ? ""
+              : profileTimestamp(patch.pinnedAt, "profile.pinnedAt"),
+        }),
   };
 }
 
@@ -1111,7 +1197,7 @@ export function applyBotProfilePatchV1(
     next.name = patch.name;
     next.namedBy = namedBy;
   }
-  for (const key of ["label", "description", "title"] as const) {
+  for (const key of ["label", "description", "title", "pinnedAt"] as const) {
     const value = patch[key];
     if (value === undefined) continue;
     if (value === "") delete next[key];