@frockbot/plugin-shell 0.1.3 → 0.2.0

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,16 +65,18 @@ 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.
    */
   capabilitiesFor(member: CompositionMemberV1): BotCapabilitiesStub;
   /**
-   * Content address of the Assignment-derived bindings this isolate is granted
-   * — the Assignments *and* the Composition generation whose `CAPABILITIES`
-   * stub is baked into its `env`. Required: it is what keeps a cached isolate
-   * from answering under a stale authority.
+   * Content address of the User-enabled bindings this isolate is granted — the
+   * enabled set *and* the Composition generation whose `CAPABILITIES` stub is
+   * baked into its `env`. Required: it is what keeps a cached isolate from
+   * answering under stale authority (ADR 0019).
    */
   bindingDigest: string;
   compatibilityDate: string;
@@ -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({