@frockbot/plugin-shell 0.3.22 → 0.3.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.22",
+  "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.22",
-    "@frockbot/application-foundation": "0.3.22",
-    "@frockbot/catalog-core": "0.3.22",
-    "@frockbot/client-core": "0.3.22",
-    "@frockbot/client-ui": "0.3.22",
-    "@frockbot/computer-core": "0.3.22",
-    "@frockbot/computer-host-protocol": "0.3.22",
-    "@frockbot/configuration-core": "0.3.22",
-    "@frockbot/connection-core": "0.3.22",
-    "@frockbot/kernel-agent-loop": "0.3.22",
-    "@frockbot/kernel-composition": "0.3.22",
-    "@frockbot/kernel-contracts": "0.3.22",
-    "@frockbot/kernel-do": "0.3.22",
-    "@frockbot/machine-protocol": "0.3.22",
-    "@frockbot/plugin-applets": "0.3.22",
-    "@frockbot/plugin-authoring": "0.3.22",
-    "@frockbot/plugin-bot-template": "0.3.22",
-    "@frockbot/plugin-computer": "0.3.22",
-    "@frockbot/plugin-flock": "0.3.22",
-    "@frockbot/plugin-image": "0.3.22",
-    "@frockbot/plugin-machine-messages": "0.3.22",
-    "@frockbot/plugin-mcp": "0.3.22",
-    "@frockbot/plugin-memory": "0.3.22",
-    "@frockbot/plugin-package-catalog": "0.3.22",
-    "@frockbot/plugin-routines": "0.3.22",
-    "@frockbot/plugin-skills": "0.3.22",
-    "@frockbot/plugin-subagents": "0.3.22",
-    "@frockbot/plugin-user-machine": "0.3.22",
-    "@frockbot/protocol": "0.3.22",
+    "@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.22",
-    "@frockbot/plugin-tools": "0.3.22",
+    "@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-recovery-integration.test.ts

@@ -19,6 +19,7 @@ import { planBotRunRecovery } from "./backend-recovery.js";
 import {
   CLIENT_RUN_LIST_MAX_BYTES,
   CLIENT_RUN_PAGE_LIMIT,
+  CLIENT_RUN_SCAN_LIMIT,
   clientRunListWireBytes,
 } from "./run-protocol.js";
 
@@ -1475,6 +1476,139 @@ describe("Bot recovery", () => {
     ).toBe(false);
   });
 
+  /**
+   * The run index is global; the transcript is one conversation. These cover
+   * the shape that used to answer "this conversation is empty" whenever the
+   * newest page of the index happened to hold nothing the reader could see.
+   */
+  async function writeRunHistory(
+    storage: MemoryStorage,
+    runs: Array<{
+      runId: string;
+      sessionId: string;
+      turnType?: "chat" | "automation";
+    }>,
+  ): Promise<void> {
+    const baseTime = Date.parse("2026-09-01T00:00:00.000Z");
+    for (const [index, entry] of runs.entries()) {
+      const acceptedAt = new Date(baseTime + index * 1_000).toISOString();
+      const run = {
+        runId: entry.runId,
+        commandFingerprint: `fingerprint-${index}`,
+        sessionId: entry.sessionId,
+        acceptedAt,
+        input: "hello",
+        events: [],
+        effectAdmissions: [],
+        status: "completed",
+        phase: "executing",
+        compositionGenerationId: "test-composition-generation",
+        configurationSnapshot: initializeBotSettingsV1("primary"),
+        previousEventCount: 0,
+        responseText: "answer",
+        ...(entry.turnType && entry.turnType !== "chat"
+          ? { admission: { schemaVersion: 1, turnType: entry.turnType } }
+          : {}),
+      } satisfies StoredRun;
+      await storage.put({
+        [`run:${entry.runId}`]: run,
+        [`run-index:${acceptedAt}:${entry.runId}`]: entry.runId,
+      });
+    }
+  }
+
+  test("reaches an older conversation buried under newer Turns", async () => {
+    const storage = new MemoryStorage();
+    await writeRunHistory(storage, [
+      { runId: "run-older", sessionId: "user:primary:older" },
+      ...Array.from({ length: CLIENT_RUN_PAGE_LIMIT + 2 }, (_value, index) => ({
+        runId: `run-newer-${index.toString().padStart(3, "0")}`,
+        sessionId: "user:primary:newer",
+      })),
+    ]);
+    const contribution = createShellBotBackendContribution({
+      state: { storage } as unknown as DurableObjectState,
+      env: {} as never,
+    });
+
+    const page = await contribution.listRuns({
+      schemaVersion: 1,
+      conversationId: "user:primary:older",
+    });
+
+    expect(page.runs.map((run) => run.runId)).toEqual(["run-older"]);
+    expect(page.page.truncated).toBe(false);
+  });
+
+  test("keeps the visible chat reachable behind a page of automation", async () => {
+    const storage = new MemoryStorage();
+    await writeRunHistory(storage, [
+      { runId: "run-chat", sessionId: "user:primary" },
+      ...Array.from({ length: CLIENT_RUN_PAGE_LIMIT + 2 }, (_value, index) => ({
+        runId: `run-automation-${index.toString().padStart(3, "0")}`,
+        sessionId: "user:primary",
+        turnType: "automation" as const,
+      })),
+    ]);
+    const contribution = createShellBotBackendContribution({
+      state: { storage } as unknown as DurableObjectState,
+      env: {} as never,
+    });
+
+    const page = await contribution.listRuns({
+      schemaVersion: 1,
+      conversationId: "user:primary",
+    });
+
+    expect(page.runs.map((run) => run.runId)).toEqual(["run-chat"]);
+  });
+
+  test("offers a continuation when a scanned page selects nothing", async () => {
+    const storage = new MemoryStorage();
+    const buried = CLIENT_RUN_SCAN_LIMIT + CLIENT_RUN_PAGE_LIMIT;
+    await writeRunHistory(storage, [
+      { runId: "run-older", sessionId: "user:primary:older" },
+      ...Array.from({ length: buried }, (_value, index) => ({
+        runId: `run-newer-${index.toString().padStart(4, "0")}`,
+        sessionId: "user:primary:newer",
+      })),
+    ]);
+    const contribution = createShellBotBackendContribution({
+      state: { storage } as unknown as DurableObjectState,
+      env: {} as never,
+    });
+
+    let page = await contribution.listRuns({
+      schemaVersion: 1,
+      conversationId: "user:primary:older",
+    });
+    // The budget stops the scan short of the match, so the page must be empty
+    // *and* say where to resume. Answering `truncated: false` here is the
+    // defect: it told the client the conversation had nothing in it.
+    expect(page.runs).toEqual([]);
+    expect(page.page.truncated).toBe(true);
+    expect(page.page.nextCursor).toBeDefined();
+
+    const seen = new Set<string>();
+    let requests = 0;
+    while (page.runs.length === 0 && page.page.nextCursor) {
+      if (seen.has(page.page.nextCursor)) {
+        throw new Error("run list cursor stopped advancing");
+      }
+      seen.add(page.page.nextCursor);
+      requests += 1;
+      if (requests > 20) throw new Error("run list did not converge");
+      page = await contribution.listRuns({
+        schemaVersion: 1,
+        conversationId: "user:primary:older",
+        before: page.page.nextCursor,
+      });
+    }
+
+    expect(page.runs.map((run) => run.runId)).toEqual(["run-older"]);
+    expect(page.page.truncated).toBe(false);
+  });
+
   test("pages large run history with bounded indexed reads and wire bytes", async () => {
     const storage = new MemoryStorage();
     const baseTime = Date.parse("2026-08-28T00:00:00.000Z");