@frockbot/plugin-shell 0.3.23 → 0.3.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.23",
+  "version": "0.3.24",
   "private": false,
   "type": "module",
   "exports": {
@@ -52,42 +52,42 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/agent-runtime": "0.3.23",
-    "@frockbot/application-foundation": "0.3.23",
-    "@frockbot/catalog-core": "0.3.23",
-    "@frockbot/client-core": "0.3.23",
-    "@frockbot/client-ui": "0.3.23",
-    "@frockbot/computer-core": "0.3.23",
-    "@frockbot/computer-host-protocol": "0.3.23",
-    "@frockbot/configuration-core": "0.3.23",
-    "@frockbot/connection-core": "0.3.23",
-    "@frockbot/kernel-agent-loop": "0.3.23",
-    "@frockbot/kernel-composition": "0.3.23",
-    "@frockbot/kernel-contracts": "0.3.23",
-    "@frockbot/kernel-do": "0.3.23",
-    "@frockbot/machine-protocol": "0.3.23",
-    "@frockbot/plugin-applets": "0.3.23",
-    "@frockbot/plugin-authoring": "0.3.23",
-    "@frockbot/plugin-bot-template": "0.3.23",
-    "@frockbot/plugin-computer": "0.3.23",
-    "@frockbot/plugin-flock": "0.3.23",
-    "@frockbot/plugin-image": "0.3.23",
-    "@frockbot/plugin-machine-messages": "0.3.23",
-    "@frockbot/plugin-mcp": "0.3.23",
-    "@frockbot/plugin-memory": "0.3.23",
-    "@frockbot/plugin-package-catalog": "0.3.23",
-    "@frockbot/plugin-routines": "0.3.23",
-    "@frockbot/plugin-skills": "0.3.23",
-    "@frockbot/plugin-subagents": "0.3.23",
-    "@frockbot/plugin-user-machine": "0.3.23",
-    "@frockbot/protocol": "0.3.23",
+    "@frockbot/agent-runtime": "0.3.24",
+    "@frockbot/application-foundation": "0.3.24",
+    "@frockbot/catalog-core": "0.3.24",
+    "@frockbot/client-core": "0.3.24",
+    "@frockbot/client-ui": "0.3.24",
+    "@frockbot/computer-core": "0.3.24",
+    "@frockbot/computer-host-protocol": "0.3.24",
+    "@frockbot/configuration-core": "0.3.24",
+    "@frockbot/connection-core": "0.3.24",
+    "@frockbot/kernel-agent-loop": "0.3.24",
+    "@frockbot/kernel-composition": "0.3.24",
+    "@frockbot/kernel-contracts": "0.3.24",
+    "@frockbot/kernel-do": "0.3.24",
+    "@frockbot/machine-protocol": "0.3.24",
+    "@frockbot/plugin-applets": "0.3.24",
+    "@frockbot/plugin-authoring": "0.3.24",
+    "@frockbot/plugin-bot-template": "0.3.24",
+    "@frockbot/plugin-computer": "0.3.24",
+    "@frockbot/plugin-flock": "0.3.24",
+    "@frockbot/plugin-image": "0.3.24",
+    "@frockbot/plugin-machine-messages": "0.3.24",
+    "@frockbot/plugin-mcp": "0.3.24",
+    "@frockbot/plugin-memory": "0.3.24",
+    "@frockbot/plugin-package-catalog": "0.3.24",
+    "@frockbot/plugin-routines": "0.3.24",
+    "@frockbot/plugin-skills": "0.3.24",
+    "@frockbot/plugin-subagents": "0.3.24",
+    "@frockbot/plugin-user-machine": "0.3.24",
+    "@frockbot/protocol": "0.3.24",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "latest",
-    "@frockbot/plugin-prompt": "0.3.23",
-    "@frockbot/plugin-tools": "0.3.23",
+    "@frockbot/plugin-prompt": "0.3.24",
+    "@frockbot/plugin-tools": "0.3.24",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/backend-composition.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, test } from "bun:test";
+import type { ApplicationPlan } from "@frockbot/kernel-composition/compiler";
+import {
+  compositionArtifactSetHashV1,
+  decodeCompositionGenerationV1,
+  type CompositionGenerationV1,
+  type CompositionMemberV1,
+} from "@frockbot/kernel-composition/generation";
+import {
+  bootstrapCompositionGeneration,
+  resolveDeploymentCompositionV1,
+  DEPLOYMENT_FOLLOW_SUMMARY_V1,
+} from "./backend-composition.js";
+
+const ARTIFACT_A = {
+  contentHash: "a".repeat(64),
+  size: 10,
+  mediaType: "application/javascript" as const,
+  bundlerVersion: "1",
+};
+const ARTIFACT_B = { ...ARTIFACT_A, contentHash: "b".repeat(64) };
+
+/** A compiled application: the shell in-process, the Applets as an artifact. */
+function plan(input: {
+  appletsManifest: unknown;
+  appletsArtifact?: typeof ARTIFACT_A;
+  extra?: boolean;
+}): ApplicationPlan {
+  return {
+    packages: [
+      {
+        id: "shell",
+        specifier: "@frockbot/plugin-shell",
+        version: "1.0.0",
+        manifest: { id: "shell" },
+      },
+      {
+        id: "applets",
+        specifier: "@frockbot/plugin-applets",
+        version: "1.0.0",
+        manifest: input.appletsManifest,
+        artifact: input.appletsArtifact ?? ARTIFACT_A,
+      },
+      ...(input.extra
+        ? [
+            {
+              id: "extra",
+              specifier: "@frockbot/plugin-extra",
+              version: "1.0.0",
+              manifest: { id: "extra" },
+            },
+          ]
+        : []),
+    ],
+  } as unknown as ApplicationPlan;
+}
+
+function store(current: CompositionGenerationV1) {
+  const proposed: CompositionGenerationV1[] = [];
+  return {
+    proposed,
+    current: () => Promise.resolve(current),
+    propose: (generation: CompositionGenerationV1) => {
+      proposed.push(generation);
+      return Promise.resolve();
+    },
+  };
+}
+
+/** The generation a Bot pinned under yesterday's deployment, plus a User member. */
+async function pinned(
+  deployment: ApplicationPlan,
+  extraMembers: CompositionMemberV1[] = [],
+): Promise<CompositionGenerationV1> {
+  const bootstrap = await bootstrapCompositionGeneration(
+    deployment,
+    "2026-09-04T09:00:00.000Z",
+  );
+  const members = [...bootstrap.members, ...extraMembers].sort((a, b) =>
+    a.packageId.localeCompare(b.packageId),
+  );
+  const applets = [
+    {
+      kind: "applet" as const,
+      appletId: "user-1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      generationId: "g1",
+      tools: [
+        {
+          name: "add_todo",
+          description: "Add",
+          inputSchema: { type: "object" },
+        },
+      ],
+      provenance: {
+        kind: "user" as const,
+        packageId: "user-1.aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        version: "g1",
+        userId: "user-1",
+        authoredAt: "2026-09-04T09:00:00.000Z",
+      },
+    },
+  ];
+  const artifactSetHash = await compositionArtifactSetHashV1(members, applets);
+  return decodeCompositionGenerationV1({
+    schemaVersion: 1,
+    generationId: `2026-09-04T09:00:00.000Z:${artifactSetHash.slice(0, 16)}`,
+    artifactSetHash,
+    createdAt: "2026-09-04T09:00:00.000Z",
+    origin: { kind: "bootstrap" },
+    members,
+    applets,
+    status: "active",
+  });
+}
+
+const USER_MEMBER: CompositionMemberV1 = {
+  packageId: "user-1.notes",
+  specifier: "frockbot:user-1.notes",
+  version: "3",
+  manifestHash: "d".repeat(64),
+  provenance: {
+    kind: "user",
+    packageId: "user-1.notes",
+    version: "3",
+    userId: "user-1",
+    authoredAt: "2026-09-04T10:00:00.000Z",
+  },
+  artifact: { ...ARTIFACT_A, contentHash: "e".repeat(64) },
+};
+
+describe("a Bot's built-in members follow the deployment", () => {
+  test("an unchanged deployment proposes nothing", async () => {
+    const yesterday = plan({ appletsManifest: { id: "applets", v: 1 } });
+    const composition = store(await pinned(yesterday, [USER_MEMBER]));
+    const result = await resolveDeploymentCompositionV1({
+      plan: yesterday,
+      composition,
+      now: new Date("2026-09-05T07:30:00.000Z"),
+    });
+    expect(result).toBeUndefined();
+    expect(composition.proposed).toHaveLength(0);
+  });
+
+  test("a changed manifest or artifact is a new pinned generation with the old one as parent", async () => {
+    const yesterday = plan({ appletsManifest: { id: "applets", v: 1 } });
+    const current = await pinned(yesterday, [USER_MEMBER]);
+    const composition = store(current);
+    const today = plan({
+      appletsManifest: { id: "applets", v: 2 },
+      appletsArtifact: ARTIFACT_B,
+    });
+    const result = await resolveDeploymentCompositionV1({
+      plan: today,
+      composition,
+      now: new Date("2026-09-05T07:30:00.000Z"),
+    });
+    expect(result).toBeDefined();
+    expect(composition.proposed).toEqual([result!]);
+    expect(result!.status).toBe("pending");
+    expect(result!.parentGenerationId).toBe(current.generationId);
+    expect(result!.summary).toBe(DEPLOYMENT_FOLLOW_SUMMARY_V1);
+    const deployed = await bootstrapCompositionGeneration(
+      today,
+      result!.createdAt,
+    );
+    const applets = result!.members.find((m) => m.packageId === "applets");
+    expect(applets).toEqual(
+      deployed.members.find((m) => m.packageId === "applets"),
+    );
+    // The shell did not change, the User's own member is carried over
+    // untouched, and the Applet members stay pinned.
+    expect(result!.members.find((m) => m.packageId === "shell")).toEqual(
+      current.members.find((m) => m.packageId === "shell"),
+    );
+    expect(result!.members.find((m) => m.packageId === "user-1.notes")).toEqual(
+      USER_MEMBER,
+    );
+    expect(result!.applets).toEqual(current.applets);
+    expect(result!.artifactSetHash).toBe(
+      await compositionArtifactSetHashV1(result!.members, result!.applets),
+    );
+  });
+
+  test("a built-in Package the deployment added or dropped changes the set", async () => {
+    const yesterday = plan({ appletsManifest: { id: "applets", v: 1 } });
+    const composition = store(await pinned(yesterday));
+    const today = plan({
+      appletsManifest: { id: "applets", v: 1 },
+      extra: true,
+    });
+    const added = await resolveDeploymentCompositionV1({
+      plan: today,
+      composition,
+    });
+    expect(added!.members.map((m) => m.packageId)).toEqual([
+      "applets",
+      "extra",
+      "shell",
+    ]);
+
+    const dropped = await resolveDeploymentCompositionV1({
+      plan: yesterday,
+      composition: store(await pinned(today)),
+    });
+    expect(dropped!.members.map((m) => m.packageId)).toEqual([
+      "applets",
+      "shell",
+    ]);
+  });
+
+  test("a version bump alone does not spend a generation", async () => {
+    const yesterday = plan({ appletsManifest: { id: "applets", v: 1 } });
+    const composition = store(await pinned(yesterday));
+    const bumped = {
+      packages: yesterday.packages.map((pkg) => ({ ...pkg, version: "1.0.1" })),
+    } as unknown as ApplicationPlan;
+    expect(
+      await resolveDeploymentCompositionV1({ plan: bumped, composition }),
+    ).toBeUndefined();
+  });
+});

package/src/backend-composition.ts

@@ -18,9 +18,13 @@ import {
 import type { ApplicationPlan } from "@frockbot/kernel-composition/compiler";
 import {
   bootstrapGeneration,
+  compositionArtifactSetHashV1,
+  compositionGenerationIdV1,
+  decodeCompositionGenerationV1,
   type CompositionGenerationV1,
   type CompositionHost,
   type CompositionMemberV1,
+  type CompositionStore,
   type MountedComposition,
 } from "@frockbot/kernel-composition/generation";
 import {
@@ -57,6 +61,92 @@ export function bootstrapCompositionGeneration(
   );
 }
 
+/** The audit line a deployment-following generation carries. */
+export const DEPLOYMENT_FOLLOW_SUMMARY_V1 =
+  "Updated the built-in Packages to this deployment's";
+
+/**
+ * Resolve the deployment's built-in Packages into this Bot's next generation.
+ *
+ * A first-party member's manifest and artifact live in the compiled
+ * application, keyed by hash. A deploy that changes one of them (2026-09-05:
+ * the Applets list page) leaves every pinned generation naming a manifest this
+ * deployment no longer ships, and every Turn of every Bot fails to mount. A
+ * built-in member is the deployment's to update, never the Bot's, so before a
+ * Turn is admitted the Bot's first-party members are brought up to the
+ * application's, as a new generation with the old one as its parent. Members
+ * the Bot or its User put in are carried over exactly as they are; Applet
+ * members stay pinned; a deployment that changes nothing proposes nothing.
+ *
+ * Only the manifest and the artifact decide. A version string that moved with
+ * a release while both stayed the same mounts exactly as before, and a
+ * generation per Bot per release would eat the User's retention quota for
+ * nothing.
+ */
+export async function resolveDeploymentCompositionV1(options: {
+  plan: ApplicationPlan;
+  composition: Pick<CompositionStore, "current" | "propose">;
+  now?: Date;
+}): Promise<CompositionGenerationV1 | undefined> {
+  const current = await options.composition.current();
+  const createdAt = (options.now ?? new Date()).toISOString();
+  const deployed = await bootstrapCompositionGeneration(
+    options.plan,
+    createdAt,
+  );
+  const shipped = new Map(
+    deployed.members.map((member) => [member.packageId, member]),
+  );
+  const members: CompositionMemberV1[] = [];
+  let changed = false;
+  for (const member of current.members) {
+    if (member.provenance.kind !== "first-party") {
+      members.push(member);
+      continue;
+    }
+    const replacement = shipped.get(member.packageId);
+    shipped.delete(member.packageId);
+    if (!replacement) {
+      // The deployment no longer ships it; nothing could mount it anyway.
+      changed = true;
+      continue;
+    }
+    if (
+      replacement.manifestHash !== member.manifestHash ||
+      replacement.artifact?.contentHash !== member.artifact?.contentHash
+    ) {
+      changed = true;
+      members.push(replacement);
+    } else {
+      members.push(member);
+    }
+  }
+  for (const added of shipped.values()) {
+    changed = true;
+    members.push(added);
+  }
+  if (!changed) return undefined;
+  const ordered = members.sort((left, right) =>
+    left.packageId.localeCompare(right.packageId),
+  );
+  const applets = current.applets ?? [];
+  const artifactSetHash = await compositionArtifactSetHashV1(ordered, applets);
+  const generation = decodeCompositionGenerationV1({
+    schemaVersion: 1,
+    generationId: compositionGenerationIdV1(createdAt, artifactSetHash),
+    artifactSetHash,
+    parentGenerationId: current.generationId,
+    summary: DEPLOYMENT_FOLLOW_SUMMARY_V1,
+    createdAt,
+    origin: { kind: "bootstrap" },
+    members: ordered,
+    ...(applets.length === 0 ? {} : { applets }),
+    status: "pending",
+  });
+  await options.composition.propose(generation, { pin: true });
+  return generation;
+}
+
 export interface ShellMountedComposition extends MountedComposition {
   readonly runtime: FoundationRuntime;
 }

package/src/backend.ts

@@ -126,12 +126,14 @@ import {
   planBotRunRecovery,
   planInterruptedRunRecoveryV1,
 } from "./backend-recovery.js";
+import { COMPOSITION_CURRENT_KEY } from "@frockbot/kernel-do";
 import {
   bootstrapCompositionGeneration,
   createShellCompositionHost,
   type ShellAppletMountOptions,
   type ShellIsolateMountOptions,
   type ShellMountedComposition,
+  resolveDeploymentCompositionV1,
 } from "./backend-composition.js";
 import {
   createAppletCapabilityHostV1,
@@ -1230,7 +1232,8 @@ export class ShellBotBackendContribution {
     // from the previous Turn has already handed the log back (ADR 0030).
     await yieldCompactionWorkV1(command.sessionId);
     // Before admission, so the pin this Turn takes already carries whatever the
-    // User's Applet directory says now.
+    // deployment ships and whatever the User's Applet directory says now.
+    await this.followDeploymentComposition();
     await this.resolveAppletComposition(
       { userId: command.userId, botId: command.botId },
       command,
@@ -1245,6 +1248,7 @@ export class ShellBotBackendContribution {
     await this.validateIdentity(identity);
     const catalog = await this.listPackageUi(identity);
     const contribution = requirePackageUiToolDeclarationV1(catalog, command);
+    await this.followDeploymentComposition();
     return projectClientTurnV1(
       await this.authority.run({
         ...identity,
@@ -2723,6 +2727,39 @@ export class ShellBotBackendContribution {
     return focused;
   }
 
+  /**
+   * Bring this Bot's built-in members up to the deployment before a Turn is
+   * admitted, so a release that changed a first-party manifest or artifact is
+   * a new generation rather than a Bot that cannot mount (2026-09-05, when
+   * every Bot failed every Turn after the Applets list page changed). Outside
+   * the admission transaction like the Applet resolve below; a failure here
+   * leaves the Bot on the generation it has and is visible where that
+   * generation fails to mount.
+   */
+  private async followDeploymentComposition(): Promise<void> {
+    try {
+      // A Bot with nothing pinned yet bootstraps from this deployment when
+      // its first Turn is admitted; reading the current generation here would
+      // materialize that bootstrap early, and a refused command must leave
+      // storage exactly as it found it.
+      if (
+        (await this.ctx.storage.get<unknown>(COMPOSITION_CURRENT_KEY)) ===
+        undefined
+      )
+        return;
+      await resolveDeploymentCompositionV1({
+        plan: await this.compileApplication(),
+        composition: {
+          current: () => this.authority.composition.current(),
+          propose: (generation, options) =>
+            this.authority.composition.propose(generation, options),
+        },
+      });
+    } catch {
+      // The mount records why; never a wedged Turn on its own.
+    }
+  }
+
   /**
    * Resolve the User's Applet directory into this Bot's next Composition
    * generation, before a Turn is admitted.
@@ -3262,6 +3299,7 @@ export class ShellBotBackendContribution {
     fire: RoutineFireV1,
   ): Promise<RoutineFireOutcomeV1> {
     try {
+      await this.followDeploymentComposition();
       await this.authority.run(
         routineTurnCommandV1(identity, fire, new Date().toISOString()),
       );
@@ -4197,6 +4235,7 @@ export class ShellBotBackendContribution {
       await this.ctx.storage.put(key, { ...context, status: "running" });
       let outcome: TaskOutcomeV1;
       try {
+        await this.followDeploymentComposition();
         await this.authority.run({
           ...identity,
           runId: context.taskId,