@frockbot/plugin-shell 0.3.25 → 0.3.27

package/package.json

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

package/src/backend-applets.test.ts

@@ -526,6 +526,65 @@ describe("ctx.applets", () => {
     );
   });
 
+  // Production, 2026-09-04, run 76b4f8d9: `applet build` printed
+  // `dist/manifest.json 2 tool(s)`, the publish sync reported `ok` and moved
+  // nothing, and the publish then said "run `applet build` … first" about a
+  // file that was sitting on the Computer. A sync that reported `ok` is not a
+  // reason to blame the build when the sync itself says it saw the file.
+  test("publish names the hash the Computer held when the Workspace answers not-found", async () => {
+    const { host: capability } = host({
+      files: {
+        [`${APPLET}/dist/server.js`]: "export class Applet {}",
+        [`${APPLET}/dist/ui.html`]: "<h1>hi</h1>",
+      },
+      synced: {
+        status: "ok",
+        detail: "",
+        required: [
+          {
+            path: `${APPLET}/dist/server.js`,
+            contentHash: "a".repeat(64),
+            durable: true,
+          },
+          {
+            path: `${APPLET}/dist/ui.html`,
+            contentHash: "b".repeat(64),
+            durable: true,
+          },
+          {
+            path: `${APPLET}/dist/manifest.json`,
+            contentHash: "e0e3ce78fabf".padEnd(64, "0"),
+            durable: false,
+          },
+        ],
+      },
+    });
+
+    const outcome = await capability.publish({ appletId: APPLET }, scope);
+
+    expect(outcome.status).toBe("failed");
+    const reason = outcome.status === "failed" ? outcome.reason : "";
+    expect(reason).toBe(
+      '"dist/manifest.json" is on the Computer (sha256 e0e3ce78fabf) but the Workspace answered not-found: the publish sync reported ok and did not carry it',
+    );
+    expect(reason).not.toMatch(/applet build/);
+  });
+
+  test("publish still blames the build when the sync saw no such file", async () => {
+    const { host: capability } = host({
+      files: {},
+      synced: {
+        status: "ok",
+        detail: "",
+        required: [{ path: `${APPLET}/dist/server.js`, durable: false }],
+      },
+    });
+    const outcome = await capability.publish({ appletId: APPLET }, scope);
+    expect(outcome.status === "failed" && outcome.reason).toMatch(
+      /applet build/,
+    );
+  });
+
   test("publish refuses a manifest whose hashes do not match the bytes", async () => {
     const { host: capability } = host({
       files: {

package/src/backend-applets.ts

@@ -70,6 +70,19 @@ export interface AppletSourceSyncOutcomeV1 {
   status: "ok" | "degraded" | "unavailable" | "refused" | "skipped";
   /** What the sync said went wrong, empty when it had nothing to say. */
   detail: string;
+  /**
+   * What the sync saw for each `dist/` file the publish named required: the
+   * hash of the bytes on the Computer, and whether the store ended up holding
+   * them. It is the evidence behind the publish's own failure sentence — a
+   * build output that demonstrably exists is never answered with "run `applet
+   * build` first" (production, 2026-09-04).
+   */
+  required?: readonly {
+    /** The source-root-relative path, `<appletId>/dist/…`. */
+    path: string;
+    contentHash?: string;
+    durable: boolean;
+  }[];
 }
 
 /** The three files `applet build` writes, read from the durable root. */
@@ -148,8 +161,13 @@ export interface AppletInstanceBindingV1 {
         diagnostics: string[];
       }
   >;
+  /**
+   * `generationId` is the Applet generation the calling Turn pinned. The
+   * instance runs that generation or refuses the call (ADR 0038).
+   */
   invokeTool(input: {
     appletId: string;
+    generationId: string;
     tool: string;
     input: unknown;
   }): Promise<{ status: "ok" | "error"; content: string }>;
@@ -249,7 +267,11 @@ export function createAppletInstanceBindingV1(
         const answer = JSON.parse(
           JSON.stringify(
             await rpc.invokeTool(
-              envelope({ tool: input.tool, toolInput: input.input ?? null }),
+              envelope({
+                generationId: input.generationId,
+                tool: input.tool,
+                toolInput: input.input ?? null,
+              }),
             ),
           ),
         ) as { status?: unknown; content?: unknown };
@@ -618,6 +640,18 @@ export function createAppletCapabilityHostV1(
       appletDistPathV1(options.userId, appletId, file),
     );
     if (outcome.status !== "ok") {
+      // Verify before reporting. The sync was asked for these exact paths, so
+      // it can say whether the Computer held the file and whether the store
+      // took it. A build output that is on disk is never answered with "run
+      // `applet build` first": that sends a Bot round a loop that cannot end.
+      const seen = synced?.required?.find(
+        (entry) => entry.path === `${appletId}/${file}`,
+      );
+      if (seen?.contentHash !== undefined) {
+        return {
+          failure: `"${file}" is on the Computer (sha256 ${seen.contentHash.slice(0, 12)}) but the Workspace answered ${outcome.status}: the publish sync reported ${synced?.status ?? "nothing"} and did not carry it${synced?.detail ? ` — ${synced.detail}` : ""}`,
+        };
+      }
       // A pull that did not finish is the likelier explanation than an
       // unbuilt Applet, and telling the Bot to build again would send it
       // round a loop that cannot end.

package/src/backend-composition.test.ts

@@ -1,13 +1,26 @@
+// Two things this seam owns, tested together because they share a Composition.
+//
+// First: which built-in members a Bot follows across a deployment.
+//
+// Second, the Applet half. An Applet member contributes no module and nothing
+// to health-check, so the only thing this seam does with it is register its
+// tools. What matters is *which* generation those tools reach: the description
+// handed to the model names the pinned generation, and ADR 0038 requires the
+// call to name it too, so the Applet Durable Object executes that generation or
+// refuses. A DTO that carried only the Applet id let a publish landing mid-Turn
+// run new code behind the schema and provenance the model was shown.
 import { describe, expect, test } from "bun:test";
 import type { ApplicationPlan } from "@frockbot/kernel-composition/compiler";
 import {
   compositionArtifactSetHashV1,
   decodeCompositionGenerationV1,
+  type CompositionAppletMemberV1,
   type CompositionGenerationV1,
   type CompositionMemberV1,
 } from "@frockbot/kernel-composition/generation";
 import {
   bootstrapCompositionGeneration,
+  createShellCompositionHost,
   resolveDeploymentCompositionV1,
   DEPLOYMENT_FOLLOW_SUMMARY_V1,
 } from "./backend-composition.js";
@@ -219,3 +232,114 @@ describe("a Bot's built-in members follow the deployment", () => {
     ).toBeUndefined();
   });
 });
+
+const USER = "user-42";
+const APPLET = `${USER}.${"a".repeat(32)}`;
+
+const APPLET_MEMBER: CompositionAppletMemberV1 = {
+  kind: "applet",
+  appletId: APPLET,
+  generationId: "2026-09-05T00:00:00.000Z:A",
+  tools: [
+    {
+      name: "add_todo",
+      description: "Add a todo",
+      inputSchema: {
+        type: "object",
+        properties: { title: { type: "string" } },
+      },
+    },
+  ],
+  provenance: {
+    kind: "user",
+    packageId: APPLET,
+    version: "2026-09-05T00:00:00.000Z:A",
+    userId: USER,
+    authoredAt: "2026-09-05T00:00:00.000Z",
+  },
+};
+
+async function generationWithApplet(): Promise<CompositionGenerationV1> {
+  const members = [
+    {
+      packageId: "shell",
+      specifier: "@frockbot/plugin-shell",
+      version: "1.0.0",
+      manifestHash: "c".repeat(64),
+      provenance: {
+        kind: "first-party" as const,
+        packageId: "shell",
+        version: "1.0.0",
+      },
+    },
+  ];
+  const applets = [APPLET_MEMBER];
+  const artifactSetHash = await compositionArtifactSetHashV1(members, applets);
+  return decodeCompositionGenerationV1({
+    schemaVersion: 1,
+    generationId: `2026-09-05T00:00:00.000Z:${artifactSetHash.slice(0, 16)}`,
+    artifactSetHash,
+    createdAt: "2026-09-05T00:00:00.000Z",
+    origin: { kind: "bootstrap" },
+    members,
+    applets,
+    status: "active",
+  });
+}
+
+describe("Applet tools mounted into a Turn's Composition", () => {
+  test("the call carries the generation the Turn pinned, not just the Applet id", async () => {
+    const calls: Array<{ appletId: string; generationId: string }> = [];
+    const generation = await generationWithApplet();
+    const { signal } = new AbortController();
+    const mounted = await createShellCompositionHost({
+      botId: "bot-1",
+      sessionId: `${USER}:bot-1`,
+      sessionEvents: [],
+      admitEffect: () => Promise.resolve(true),
+      applets: {
+        invokeTool: (request) => {
+          calls.push({
+            appletId: request.appletId,
+            generationId: request.generationId,
+          });
+          return Promise.resolve({ status: "ok" as const, content: "added" });
+        },
+      },
+    }).mount(generation, signal);
+    try {
+      await mounted.verify(signal);
+      const schema = mounted.root.tools
+        .schemas({ turnType: "chat" })
+        .find((entry) => entry.name === "add_todo");
+      expect(schema).toBeDefined();
+      // The pin the model is shown, and the pin the call carries, are one
+      // string. If they ever diverge the Turn stops being reconstructable.
+      expect(schema?.description).toContain(APPLET_MEMBER.generationId);
+
+      const call = { id: "call-1", name: "add_todo", input: { title: "milk" } };
+      const context = {
+        botId: "bot-1",
+        agentId: "bot-1",
+        sessionId: `${USER}:bot-1`,
+        compositionGenerationId: generation.generationId,
+        effectId: "effect-1",
+        toolCall: call,
+        turnType: "chat" as const,
+        signal,
+      };
+      const prepared = await mounted.root.tools.prepare(call, context);
+      expect(prepared.kind).toBe("ready");
+      const outcome = await mounted.root.tools.executePrepared(
+        prepared as Extract<typeof prepared, { kind: "ready" }>,
+        context,
+      );
+      expect(outcome).toMatchObject({ isError: false });
+      expect(calls).toEqual([
+        { appletId: APPLET, generationId: APPLET_MEMBER.generationId },
+      ]);
+    } finally {
+      await mounted.dispose();
+    }
+  });
+});

package/src/backend-composition.ts

@@ -185,10 +185,16 @@ export interface ShellIsolateMountOptions {
  * (`docs/research/spike-applet-facets.md` §8). Absent when the Bot Durable
  * Object has no Applet binding: an Applet member's tools are then simply not
  * registered, exactly as an isolate member fails without a loader.
+ *
+ * `generationId` is the Applet generation this Turn's Composition pinned, and
+ * it is not decoration: the Applet Durable Object runs that generation or
+ * refuses the call (ADR 0038). Without it a publish landing mid-Turn would
+ * execute new code behind the schema and provenance the model was shown.
  */
 export interface ShellAppletMountOptions {
   invokeTool(request: {
     appletId: string;
+    generationId: string;
     tool: string;
     input: unknown;
   }): Promise<{ status: "ok" | "error"; content: string }>;
@@ -385,6 +391,9 @@ export function createShellCompositionHost(
               execute: async (input) => {
                 const outcome = await routing.invokeTool({
                   appletId: applet.appletId,
+                  // The pin the description above advertises, carried into the
+                  // call so the instance executes it or refuses.
+                  generationId: applet.generationId,
                   tool: tool.name,
                   input: input ?? null,
                 });

package/src/backend.ts

@@ -2521,7 +2521,11 @@ export class ShellBotBackendContribution {
               ),
               signal: active.signal,
             });
-            return { status: summary.status, detail: summary.detail };
+            return {
+              status: summary.status,
+              detail: summary.detail,
+              ...(summary.required ? { required: summary.required } : {}),
+            };
           }
         : undefined,
       composition: {