@frockbot/plugin-shell 0.1.4 → 0.2.1

package/src/backend-composition-input.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import {
+  compositionFailureDurableInputV1,
+  compositionFailureTurnTextV1,
+} from "./backend-composition-input.ts";
+
+describe("Composition failure durable Bot input", () => {
+  test("includes the authored Package, phase, diagnostics, and quarantine", () => {
+    const text = compositionFailureDurableInputV1({
+      attemptedGenerationId: "generation-broken",
+      generation: {
+        schemaVersion: 1,
+        generationId: "generation-broken",
+        artifactSetHash: "a".repeat(64),
+        createdAt: "2026-09-02T00:00:00.000Z",
+        origin: {
+          kind: "bot-authored",
+          runId: "run-1",
+          sessionId: "session-1",
+          turnId: "turn-1",
+        },
+        members: [
+          {
+            packageId: "weather-lookup",
+            specifier: "bot-authored:weather-lookup",
+            version: "0.0.1",
+            manifestHash: "b".repeat(64),
+            provenance: {
+              kind: "bot",
+              packageId: "weather-lookup",
+              version: "0.0.1",
+              botId: "bot-1",
+              sessionId: "session-1",
+              turnId: "turn-1",
+              runId: "run-1",
+              authoredAt: "2026-09-02T00:00:00.000Z",
+            },
+          },
+        ],
+        status: "quarantined",
+      },
+      failure: {
+        generationId: "generation-broken",
+        attempt: 3,
+        at: "2026-09-02T00:01:00.000Z",
+        phase: "health",
+        message: "declared tools do not match",
+        diagnostics: ["declared=weather_lookup", "reported=other"],
+      },
+      quarantined: true,
+    });
+
+    expect(text).toContain("Generation: generation-broken");
+    expect(text).toContain("Package: weather-lookup");
+    expect(text).toContain("Phase: health");
+    expect(text).toContain("- reported=other");
+    expect(text).toContain("Status: quarantined");
+    expect(
+      compositionFailureTurnTextV1("please continue", {
+        attemptedGenerationId: "generation-broken",
+        quarantined: false,
+      }),
+    ).toEndWith("\n\nplease continue");
+  });
+});

package/src/backend-composition-input.ts

@@ -0,0 +1,58 @@
+import type { CompositionFailureV1 } from "@frockbot/kernel-composition/activation";
+import type { CompositionGenerationV1 } from "@frockbot/kernel-composition/generation";
+
+/**
+ * Model-visible durable input for the Turn that fell back from a broken
+ * Composition. The caller places this exact text in `user/message`, from
+ * which the exact recorded `model/request` is reconstructed.
+ */
+export function compositionFailureDurableInputV1(input: {
+  attemptedGenerationId: string;
+  generation?: CompositionGenerationV1;
+  failure?: CompositionFailureV1;
+  quarantined: boolean;
+}): string {
+  const origin = input.generation?.origin;
+  const authoredPackageId =
+    origin?.kind === "bot-authored"
+      ? input.generation?.members.find(
+          (member) =>
+            member.provenance.kind === "bot" &&
+            member.provenance.runId === origin.runId,
+        )?.packageId
+      : undefined;
+  const failure = input.failure;
+  const packageId =
+    authoredPackageId ??
+    failure?.message.match(/package "([^"]+)"/i)?.[1] ??
+    (input.generation?.members.filter(
+      (member) => member.provenance.kind === "bot",
+    ).length === 1
+      ? input.generation.members.find(
+          (member) => member.provenance.kind === "bot",
+        )?.packageId
+      : undefined);
+  const diagnostics = failure?.diagnostics.length
+    ? failure.diagnostics.map((entry) => `- ${entry}`).join("\n")
+    : "- none";
+  return [
+    "[Durable Package activation failure]",
+    `Generation: ${input.attemptedGenerationId}`,
+    `Package: ${packageId ?? "unknown"}`,
+    `Phase: ${failure?.phase ?? "resolve"}`,
+    `Message: ${failure?.message ?? "This quarantined generation remains unavailable."}`,
+    "Diagnostics:",
+    diagnostics,
+    input.quarantined
+      ? "Status: quarantined after repeated activation failures; the last working Package setup was mounted. Author a repair or use package_undo."
+      : "Status: activation failed; the last working Package setup was mounted for this Turn. Author a repair or use package_undo.",
+  ].join("\n");
+}
+
+/** The exact command text handed to the Agent loop on a fallback Turn. */
+export function compositionFailureTurnTextV1(
+  ordinaryInput: string,
+  failure: Parameters<typeof compositionFailureDurableInputV1>[0],
+): string {
+  return `${compositionFailureDurableInputV1(failure)}\n\n${ordinaryInput}`;
+}

package/src/backend-composition.ts

@@ -65,6 +65,8 @@ export interface ShellIsolateMountOptions {
   turnId: string;
   loader: BotIsolateLoader;
   artifacts: BotIsolateArtifactStore;
+  /** Reads the exact manifest whose hash the member records. */
+  manifestFor(member: CompositionMemberV1): Promise<unknown>;
   /**
    * Mints the loopback `CAPABILITIES` service binding for one Package —
    * `ctx.exports.BotCapabilities({ props })` in the Durable Object.
@@ -177,12 +179,27 @@ export function createShellCompositionHost(
             loader: isolate.loader,
             artifacts: isolate.artifacts,
             tools: runtime.root.tools,
+            loop: runtime.root,
             userId: isolate.userId,
             botId: options.botId,
             sessionId: options.sessionId,
             runId: isolate.runId,
             turnId: isolate.turnId,
             generationId: generation.generationId,
+            turnType: options.turnType ?? "chat",
+            ...(options.subagentRole === undefined
+              ? {}
+              : { subagentRole: options.subagentRole }),
+            recordHookFailure: async (failure) => {
+              const session = runtime.root.sessions.get(options.sessionId);
+              if (!session) {
+                throw new Error(
+                  `session "${options.sessionId}" is unavailable for hook failure recording`,
+                );
+              }
+              session.append({ type: "package/hook-failed", ...failure });
+              await session.flush();
+            },
             capabilities: isolate.capabilitiesFor(member),
             compatibilityDate: isolate.compatibilityDate,
             bindingDigest: isolate.bindingDigest,
@@ -192,8 +209,9 @@ export function createShellCompositionHost(
               : { deadlineMs: isolate.deadlineMs }),
           });
           // Mount and health-check are one guarded phase (Worker Loader spike).
+          const storedManifest = await isolate.manifestFor(member);
           const prepared = await host.prepare(
-            botIsolatePackageDescriptorV1(member),
+            await botIsolatePackageDescriptorV1(member, storedManifest),
           );
           if (!prepared) {
             failures.push({

package/src/backend-configuration.test.ts

@@ -7,6 +7,7 @@ import type {
 } from "@frockbot/configuration-core";
 import type { PackageSettingDefinition } from "@frockbot/kernel-composition";
 import { createShellBotBackendContribution } from "./backend.js";
+import { createIsolateCapabilityHost } from "./backend-isolate.js";
 
 class MemoryStorage {
   readonly values = new Map<string, unknown>();
@@ -218,6 +219,58 @@ function request(command: BotConfigurationCommandV1) {
 }
 
 describe("Bot configuration admission", () => {
+  test("reads old Bot settings purely and writes the migrated shape on the next command", async () => {
+    const storage = new MemoryStorage();
+    // Literal durable shape from eb0283edcce5daea976a21a9f6a6414bedc6e2bc,
+    // the first parent of PR #134's merge commit.
+    const historical = {
+      schemaVersion: 1,
+      botId: "primary",
+      revision: 4,
+      profile: { name: "Primary" },
+      notifications: { enabled: true },
+      assignments: [],
+      assignmentOperations: [],
+      model: {
+        connectionId: "ollama-1",
+        providerModelId: "glm-5.3-flash:cloud",
+      },
+    };
+    await storage.put({
+      identity: { userId: "user-1", botId: "primary" },
+      "bot-configuration": historical,
+    });
+    const contribution = host(storage, configuredUser);
+    const identity = { userId: "user-1", botId: "primary" };
+
+    await expect(contribution.getSettings(identity)).resolves.toMatchObject({
+      revision: 4,
+      packageValues: {},
+    });
+    expect(await storage.get<unknown>("bot-configuration")).toEqual(historical);
+
+    await contribution.executeConfiguration(
+      request({
+        schemaVersion: 1,
+        type: "bot/update-profile",
+        commandId: "migrate-bot-settings",
+        botId: "primary",
+        expectedRevision: 4,
+        profile: { name: "Migrated Bot" },
+      }),
+    );
+    const written =
+      await storage.get<Record<string, unknown>>("bot-configuration");
+    expect(written).toMatchObject({
+      revision: 5,
+      profile: { name: "Migrated Bot" },
+      packageValues: {},
+    });
+    expect(written).not.toHaveProperty("assignments");
+    expect(written).not.toHaveProperty("assignmentOperations");
+    expect(written).not.toHaveProperty("model");
+  });
+
   test("rejects an unmaterialized Bot without writing durable state", async () => {
     const storage = new MemoryStorage();
     const contribution = host(storage, configuredUser);
@@ -414,6 +467,65 @@ describe("Bot configuration admission", () => {
 });
 
 describe("generic per-Turn model resolution", () => {
+  test("projects the platform model into an otherwise unconfigured Bot's isolate list", async () => {
+    const storage = new MemoryStorage();
+    const contribution = host(storage, configuredUser);
+    const identity = { userId: "user-1", botId: "primary" };
+    const settings = await contribution.materializeSettings(identity, {
+      name: "Primary",
+    });
+    const snapshot = await (
+      contribution as unknown as {
+        isolateAuthoritySnapshot(
+          identity: { userId: string; botId: string },
+          settings: BotSettingsViewV1,
+        ): Promise<{
+          connections: Array<{
+            connectionId: string;
+            packageId: string;
+            connectionTypeId: string;
+            displayName: string;
+            generation: string;
+            safeMetadata: Record<string, unknown>;
+          }>;
+          model?: {
+            connectionId: string;
+            packageId: string;
+            provider: string;
+            providerModelId: string;
+            connectionGeneration: string;
+            catalogGeneration?: string;
+          };
+          memory: boolean;
+          workspace: boolean;
+        }>;
+      }
+    ).isolateAuthoritySnapshot(identity, settings);
+    const listed = await createIsolateCapabilityHost({
+      storage: {
+        put: () => Promise.resolve(),
+        list: () => Promise.resolve(new Map()),
+      },
+      botId: identity.botId,
+      packageId: "bot-authored",
+      generationId: "composition-1",
+      connections: snapshot.connections,
+      ...(snapshot.model ? { modelBinding: snapshot.model } : {}),
+      memory: snapshot.memory,
+      workspace: snapshot.workspace,
+    }).list();
+
+    expect(listed.model).toEqual({
+      connectionId: "flock-ai-ambient",
+      packageId: "provider-flock-ai",
+      provider: "flock-ai",
+      providerModelId: "@flock/auto",
+      connectionGeneration: "foundation-generation-1",
+      catalogGeneration: "catalog-1",
+    });
+    expect(Object.hasOwn(settings, "model")).toBe(false);
+  });
+
   test("runs on the platform model without creating a per-Bot model record", async () => {
     const storage = new MemoryStorage();
     const contribution = host(storage, configuredUser);
@@ -429,11 +541,65 @@ describe("generic per-Turn model resolution", () => {
     });
 
     expect(result.text).toBe("Cordis runtime: hello");
+    const durableEvents = storage.values.get("latest-events") as
+      Array<{ seq: number }> | undefined;
+    expect(durableEvents?.length).toBeGreaterThan(0);
+    expect(durableEvents?.map((event) => event.seq)).toEqual(
+      durableEvents?.map((_, index) => index),
+    );
     const settings = await contribution.getSettings(identity);
     expect(settings).toMatchObject({ revision: 0, packageValues: {} });
     expect(Object.hasOwn(settings, "model")).toBe(false);
   });
 
+  test("a Connection disabled after admission is unavailable and records a visible failure", async () => {
+    const storage = new MemoryStorage();
+    const user = configuredUser();
+    const contribution = host(storage, () => user);
+    const identity = { userId: "user-1", botId: "primary" };
+    await contribution.materializeSettings(identity, { name: "Primary" });
+    (
+      contribution as unknown as {
+        activeTurn: unknown;
+      }
+    ).activeTurn = {
+      runId: "run-1",
+      sessionId: "session-1",
+      turnId: "turn-1",
+      generationId: "composition-1",
+      mounted: {
+        generation: {
+          members: [
+            { packageId: "bot-authored", artifact: { contentHash: "hash" } },
+          ],
+        },
+      },
+    };
+    user.connections[0] = { ...user.connections[0]!, state: "disabled" };
+
+    await expect(
+      contribution.isolateConnection({
+        ...identity,
+        runId: "run-1",
+        sessionId: "session-1",
+        turnId: "turn-1",
+        packageId: "bot-authored",
+        generationId: "composition-1",
+        request: "flock-ai-ambient",
+      }),
+    ).resolves.toEqual({
+      status: "unavailable",
+      reason: "the Connection is unavailable",
+    });
+    await expect(contribution.listNotifications()).resolves.toEqual([
+      expect.objectContaining({
+        notificationId:
+          "package-connection-unavailable:run-1:bot-authored:flock-ai-ambient",
+        title: "Connection unavailable",
+      }),
+    ]);
+  });
+
   test("uses an enabled Bot-scoped model value and preserves it while disabled", async () => {
     const storage = new MemoryStorage();
     let user = configuredUser();

package/src/backend-contracts.test.ts

@@ -20,6 +20,34 @@ function storedRun(): StoredRun {
 }
 
 describe("StoredRun durable contract", () => {
+  test("migrates a historical configuration snapshot before strict decoding", () => {
+    // Literal Bot settings shape from eb0283edcce5daea976a21a9f6a6414bedc6e2bc.
+    const decoded = requireStoredRunV1({
+      ...storedRun(),
+      configurationSnapshot: {
+        schemaVersion: 1,
+        botId: "primary",
+        revision: 4,
+        profile: { name: "Primary" },
+        notifications: { enabled: true },
+        assignments: [],
+        assignmentOperations: [],
+        model: {
+          connectionId: "ollama-1",
+          providerModelId: "glm-5.3-flash:cloud",
+        },
+      },
+    });
+    expect(decoded.configurationSnapshot).toEqual({
+      schemaVersion: 1,
+      botId: "primary",
+      revision: 4,
+      profile: { name: "Primary", description: undefined },
+      notifications: { enabled: true },
+      packageValues: {},
+    });
+  });
+
   test("uses the public run identifier grammar", () => {
     expect(() =>
       requireStoredRunV1({ ...storedRun(), runId: "run:1" }),

package/src/backend-contracts.ts

@@ -8,6 +8,7 @@ import {
 import {
   decodeBotSettingsViewV1,
   isPublicIdentifier,
+  migrateStoredBotSettingsV1,
   type BotSettingsViewV1,
 } from "@frockbot/configuration-core";
 
@@ -36,7 +37,8 @@ export function decodeRunIdV1(value: unknown): string {
 export const storedRunCodecV1: StoredRunCodecV1<BotSettingsViewV1> =
   createStoredRunCodecV1<BotSettingsViewV1>({
     decodeRunId: decodeRunIdV1,
-    decodeConfigurationSnapshot: decodeBotSettingsViewV1,
+    decodeConfigurationSnapshot: (stored) =>
+      decodeBotSettingsViewV1(migrateStoredBotSettingsV1(stored)),
   });
 
 export function requireStoredRunV1(input: unknown): StoredRun {

package/src/backend-iframe-ui.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from "bun:test";
+import type { PackageIframeCompositionV1 } from "@frockbot/kernel-contracts";
+import type { FrockBotManifest } from "@frockbot/kernel-composition";
+import type { CompositionGenerationV1 } from "@frockbot/kernel-composition/generation";
+import { requirePackageUiToolDeclarationV1 } from "./backend.js";
+import { projectPackageIframeCompositionV1 } from "./composition-views.js";
+
+describe("Package iframe server admission", () => {
+  const catalog: PackageIframeCompositionV1 = {
+    schemaVersion: 1,
+    botId: "bot",
+    generationId: "generation-1",
+    contributions: [
+      {
+        packageId: "weather-page",
+        displayName: "Weather page",
+        provenance: "Bot-authored",
+        artifact: {
+          contentHash: "a".repeat(64),
+          size: 123,
+          mediaType: "text/html",
+          bundlerVersion: "frockbot-inline-html@1",
+        },
+        mounts: [{ slot: "frockbot.tool-result:weather_lookup" }],
+        declaredTools: ["weather_lookup"],
+      },
+    ],
+  };
+
+  test("refuses an undeclared tool before admitting a durable Turn", () => {
+    expect(() =>
+      requirePackageUiToolDeclarationV1(catalog, {
+        generationId: "generation-1",
+        packageId: "weather-page",
+        name: "package_author",
+      }),
+    ).toThrow('did not declare tool "package_author"');
+  });
+
+  test("refuses a stale page after its Composition generation changed", () => {
+    expect(() =>
+      requirePackageUiToolDeclarationV1(catalog, {
+        generationId: "generation-old",
+        packageId: "weather-page",
+        name: "weather_lookup",
+      }),
+    ).toThrow('generation "generation-old"');
+  });
+
+  test("projects a Catalog member through the same manifest reader", async () => {
+    const manifestHash = "c".repeat(64);
+    const uiArtifact = {
+      contentHash: "d".repeat(64),
+      size: 42,
+      mediaType: "text/html" as const,
+      bundlerVersion: "frockbot-inline-html@1",
+    };
+    const manifest: FrockBotManifest = {
+      schemaVersion: 3,
+      id: "weather-page",
+      displayName: "Weather page",
+      version: "0.0.1",
+      compatibility: { frockbot: "*" },
+      dependencies: {},
+      contributions: {
+        runtime: { entry: "./package.js", host: "bot-isolate" },
+        client: {
+          kind: "iframe",
+          artifact: uiArtifact,
+          mounts: [{ slot: "frockbot.tool-result:weather_lookup" }],
+        },
+      },
+      tools: [
+        { name: "weather_lookup", description: "Looks up", inputSchema: {} },
+      ],
+      permissions: [],
+    };
+    const generation: CompositionGenerationV1 = {
+      schemaVersion: 1,
+      generationId: "generation-1",
+      artifactSetHash: "a".repeat(64),
+      createdAt: "2026-09-02T00:00:00.000Z",
+      origin: { kind: "bootstrap" },
+      members: [
+        {
+          packageId: "weather-page",
+          specifier: "catalog:weather-page",
+          version: "0.0.1",
+          manifestHash,
+          provenance: {
+            kind: "catalog",
+            packageId: "weather-page",
+            version: "0.0.1",
+            catalogId: "weather-page",
+            catalogGeneration: "catalog-1",
+            contentHash: "b".repeat(64),
+          },
+          artifact: {
+            contentHash: "b".repeat(64),
+            size: 512,
+            mediaType: "application/javascript",
+            bundlerVersion: "catalog-test@1",
+          },
+        },
+      ],
+      status: "active",
+    };
+    const requested: string[] = [];
+
+    const projected = await projectPackageIframeCompositionV1({
+      botId: "bot",
+      generation,
+      readMemberManifest: (member) => {
+        requested.push(member.manifestHash);
+        return Promise.resolve(manifest);
+      },
+    });
+
+    expect(requested).toEqual([manifestHash]);
+    expect(projected.contributions).toEqual([
+      {
+        packageId: "weather-page",
+        displayName: "Weather page",
+        provenance: "User-installed",
+        artifact: uiArtifact,
+        mounts: [{ slot: "frockbot.tool-result:weather_lookup" }],
+        declaredTools: ["weather_lookup"],
+      },
+    ]);
+  });
+});