@frockbot/plugin-shell 0.3.25 → 0.3.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.25",
+  "version": "0.3.26",
   "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.26",
+    "@frockbot/application-foundation": "0.3.26",
+    "@frockbot/catalog-core": "0.3.26",
+    "@frockbot/client-core": "0.3.26",
+    "@frockbot/client-ui": "0.3.26",
+    "@frockbot/computer-core": "0.3.26",
+    "@frockbot/computer-host-protocol": "0.3.26",
+    "@frockbot/configuration-core": "0.3.26",
+    "@frockbot/connection-core": "0.3.26",
+    "@frockbot/kernel-agent-loop": "0.3.26",
+    "@frockbot/kernel-composition": "0.3.26",
+    "@frockbot/kernel-contracts": "0.3.26",
+    "@frockbot/kernel-do": "0.3.26",
+    "@frockbot/machine-protocol": "0.3.26",
+    "@frockbot/plugin-applets": "0.3.26",
+    "@frockbot/plugin-authoring": "0.3.26",
+    "@frockbot/plugin-bot-template": "0.3.26",
+    "@frockbot/plugin-computer": "0.3.26",
+    "@frockbot/plugin-flock": "0.3.26",
+    "@frockbot/plugin-image": "0.3.26",
+    "@frockbot/plugin-machine-messages": "0.3.26",
+    "@frockbot/plugin-mcp": "0.3.26",
+    "@frockbot/plugin-memory": "0.3.26",
+    "@frockbot/plugin-package-catalog": "0.3.26",
+    "@frockbot/plugin-routines": "0.3.26",
+    "@frockbot/plugin-skills": "0.3.26",
+    "@frockbot/plugin-subagents": "0.3.26",
+    "@frockbot/plugin-user-machine": "0.3.26",
+    "@frockbot/protocol": "0.3.26",
     "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.26",
+    "@frockbot/plugin-tools": "0.3.26",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/backend-applets.ts

@@ -148,8 +148,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 +254,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 };

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,
                 });