@frockbot/plugin-shell 0.1.4 → 0.2.1

package/frockbot.json

@@ -25,6 +25,10 @@
         {
           "slot": "authenticated-root",
           "order": 10000
+        },
+        {
+          "slot": "frockbot.bot-settings-sections",
+          "order": 10000
         }
       ],
       "outlets": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "exports": {
@@ -16,6 +16,7 @@
     "./backend-image": "./src/backend-image.ts",
     "./backend-isolate": "./src/backend-isolate.ts",
     "./backend-memory": "./src/backend-memory.ts",
+    "./backend-package-catalog": "./src/backend-package-catalog.ts",
     "./backend-recovery": "./src/backend-recovery.ts",
     "./backend-runner": "./src/backend-runner.ts",
     "./backend-skills": "./src/backend-skills.ts",
@@ -45,38 +46,39 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/agent-runtime": "0.1.4",
-    "@frockbot/application-foundation": "0.1.4",
-    "@frockbot/catalog-core": "0.1.4",
-    "@frockbot/client-core": "0.1.4",
-    "@frockbot/client-ui": "0.1.4",
-    "@frockbot/computer-core": "0.1.4",
-    "@frockbot/computer-host-protocol": "0.1.4",
-    "@frockbot/configuration-core": "0.1.4",
-    "@frockbot/connection-core": "0.1.4",
-    "@frockbot/kernel-agent-loop": "0.1.4",
-    "@frockbot/kernel-composition": "0.1.4",
-    "@frockbot/kernel-contracts": "0.1.4",
-    "@frockbot/kernel-do": "0.1.4",
-    "@frockbot/machine-protocol": "0.1.4",
-    "@frockbot/plugin-authoring": "0.1.4",
-    "@frockbot/plugin-bot-template": "0.1.4",
-    "@frockbot/plugin-flock": "0.1.4",
-    "@frockbot/plugin-image": "0.1.4",
-    "@frockbot/plugin-machine-messages": "0.1.4",
-    "@frockbot/plugin-mcp": "0.1.4",
-    "@frockbot/plugin-memory": "0.1.4",
-    "@frockbot/plugin-routines": "0.1.4",
-    "@frockbot/plugin-skills": "0.1.4",
-    "@frockbot/plugin-subagents": "0.1.4",
-    "@frockbot/plugin-user-machine": "0.1.4",
-    "@frockbot/protocol": "0.1.4",
+    "@frockbot/agent-runtime": "0.2.1",
+    "@frockbot/application-foundation": "0.2.1",
+    "@frockbot/catalog-core": "0.2.1",
+    "@frockbot/client-core": "0.2.1",
+    "@frockbot/client-ui": "0.2.1",
+    "@frockbot/computer-core": "0.2.1",
+    "@frockbot/computer-host-protocol": "0.2.1",
+    "@frockbot/configuration-core": "0.2.1",
+    "@frockbot/connection-core": "0.2.1",
+    "@frockbot/kernel-agent-loop": "0.2.1",
+    "@frockbot/kernel-composition": "0.2.1",
+    "@frockbot/kernel-contracts": "0.2.1",
+    "@frockbot/kernel-do": "0.2.1",
+    "@frockbot/machine-protocol": "0.2.1",
+    "@frockbot/plugin-authoring": "0.2.1",
+    "@frockbot/plugin-package-catalog": "0.2.1",
+    "@frockbot/plugin-bot-template": "0.2.1",
+    "@frockbot/plugin-flock": "0.2.1",
+    "@frockbot/plugin-image": "0.2.1",
+    "@frockbot/plugin-machine-messages": "0.2.1",
+    "@frockbot/plugin-mcp": "0.2.1",
+    "@frockbot/plugin-memory": "0.2.1",
+    "@frockbot/plugin-routines": "0.2.1",
+    "@frockbot/plugin-skills": "0.2.1",
+    "@frockbot/plugin-subagents": "0.2.1",
+    "@frockbot/plugin-user-machine": "0.2.1",
+    "@frockbot/protocol": "0.2.1",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "latest",
-    "@frockbot/plugin-tools": "0.1.4",
+    "@frockbot/plugin-tools": "0.2.1",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/agent.ts

@@ -9,7 +9,7 @@
 //     `widget` payload ends the Turn; row 53's `approval` payload is the only
 //     other one that does, and for the same reason — the Bot has nothing left
 //     to do until a person answers.
-//  3. One `agent/request` handler, which is where the transcript seam is: a
+//  3. One `agent/message-window` handler, which is where the transcript seam is: a
 //     chat Turn's request carries only chat Turns, and an automation Turn's
 //     carries its own Turn and a pointer to the parent it may not read. See
 //     `history.ts`.
@@ -120,8 +120,6 @@ function sendAcknowledgement(payload: SendToUserPayloadV1): string {
       return "Secret request sent to the user.";
     case "agent-card":
       return "Agent card sent to the user.";
-    case "connect-card":
-      return "Connect card sent to the user. Only they can complete the authorization; you have recorded the request, not granted it.";
     case "approval":
       // Deliberately not "requested permission": nothing has been granted, and
       // the Turn is over whatever the answer turns out to be.
@@ -137,7 +135,6 @@ const SEND_TO_USER_DESCRIPTION = [
   '{"type":"widget","widget":{"prompt":"…","helpText":"…","options":["…"],"allowCustom":false,"dismissOnMoveOn":false}}',
   '{"type":"secret-request","prompt":"…","secretName":"…"}',
   '{"type":"agent-card","agentId":"…","title":"…","body":"…"}',
-  '{"type":"connect-card","connectionId":"…","title":"…","body":"…"}',
   '{"type":"approval","approvalId":"…","action":"…","rationale":"…","risk":"low|medium|high","expiresInSeconds":86400}',
   "A widget asks the user a question with 1 to 6 options and ends your Turn;",
   "their answer arrives as a new Turn. An approval asks the user to allow one",
@@ -313,18 +310,18 @@ export const shellAgentPlugin: Plugin.Function = (ctx) => {
     // Applied after the rest of the chain, so this Package has the last word on
     // what history a request carries — the one rule the visible transcript
     // rests on.
-    ctx.on("agent/request", async (agent, _request, _signal, next) => {
-      const proposed = await next();
-      return {
-        ...proposed,
-        messages: turnScopedMessagesV1({
+    ctx.on(
+      "agent/message-window",
+      async (agent, _messages, _turn, _step, _signal, next) => {
+        const proposed = await next();
+        return turnScopedMessagesV1({
           events: agent.session.events,
-          messages: proposed.messages,
+          messages: proposed,
           pointer: automationParentPointerV1,
           sessionId: agent.session.id,
-        }),
-      };
-    }),
+        });
+      },
+    ),
   ];
   return () => {
     for (const dispose of disposers.toReversed()) dispose();

package/src/backend-authoring.test.ts

@@ -7,17 +7,23 @@ import {
   type CompositionGenerationV1,
   type CompositionMemberV1,
 } from "@frockbot/kernel-composition/generation";
+import { decodeFrockBotManifest } from "@frockbot/kernel-composition";
 import type { PackageBundleResultV1 } from "@frockbot/kernel-contracts";
 import {
   artifactKey,
   authorshipArtifactKey,
   authorshipFailureKey,
   authorshipIntentKey,
+  authorshipManifestKey,
+  authorshipUndoIntentKey,
+  authorshipUndoOutcomeKey,
   AUTHORSHIP_FAILURE_PREFIX,
   type AuthoredArtifactRecordV1,
+  type AuthoredManifestRecordV1,
   type AuthoringFailureRecordV1,
   type AuthorPackageRequestV1,
   type AuthorshipIntentV1,
+  sha256HexV1,
 } from "@frockbot/plugin-authoring";
 import {
   createPackageAuthoringHost,
@@ -34,7 +40,7 @@ function requestFor(overrides: Partial<AuthorPackageRequestV1> = {}) {
     input: {
       packageId: "hello-world",
       displayName: "Hello world",
-      tool: { name: "hello", description: "Says hi", inputSchema: {} },
+      tools: [{ name: "hello", description: "Says hi", inputSchema: {} }],
       source: SOURCE,
     },
     sourceHash: "a".repeat(64),
@@ -56,6 +62,12 @@ function memoryStorage() {
       }
       return Promise.resolve();
     },
+    list: <T>({ prefix }: { prefix: string }) =>
+      Promise.resolve(
+        new Map(
+          [...values.entries()].filter(([key]) => key.startsWith(prefix)),
+        ) as Map<string, T>,
+      ),
   };
   return storage;
 }
@@ -79,13 +91,28 @@ async function memoryComposition() {
     [bootstrap.generationId, bootstrap],
   ]);
   let current = bootstrap.generationId;
+  let lastKnownGood = bootstrap.generationId;
   const store: AuthoringCompositionStore & {
     generations: Map<string, CompositionGenerationV1>;
     currentId(): string;
+    activate(generationId: string): void;
+    fail(generationId: string): void;
   } = {
     generations,
     currentId: () => current,
     current: () => Promise.resolve(generations.get(current)!),
+    lastKnownGood: () => Promise.resolve(generations.get(lastKnownGood)!),
+    activate: (generationId) => {
+      const generation = generations.get(generationId)!;
+      generations.set(generationId, { ...generation, status: "active" });
+      current = generationId;
+      lastKnownGood = generationId;
+    },
+    fail: (generationId) => {
+      const generation = generations.get(generationId)!;
+      generations.set(generationId, { ...generation, status: "failed" });
+      current = generationId;
+    },
     read: (generationId) => Promise.resolve(generations.get(generationId)),
     propose: (generation, options) => {
       if (generations.has(generation.generationId)) {
@@ -96,6 +123,33 @@ async function memoryComposition() {
       return Promise.resolve();
     },
     retainedCount: () => Promise.resolve(generations.size),
+    list: ({ limit }) =>
+      Promise.resolve({
+        generations: [...generations.values()].reverse().slice(0, limit),
+      }),
+    revert: async (toGenerationId, origin, options) => {
+      const target = generations.get(toGenerationId);
+      if (!target) throw new Error("unknown target");
+      const createdAt = options?.createdAt ?? "2026-08-31T02:00:00.000Z";
+      const generation = decodeCompositionGenerationV1({
+        schemaVersion: 1,
+        generationId: compositionGenerationIdV1(
+          createdAt,
+          target.artifactSetHash,
+        ),
+        artifactSetHash: target.artifactSetHash,
+        parentGenerationId: current,
+        createdAt,
+        origin,
+        members: target.members,
+        status: "pending",
+      });
+      const existing = generations.get(generation.generationId);
+      if (existing) return existing;
+      generations.set(generation.generationId, generation);
+      current = generation.generationId;
+      return generation;
+    },
   };
   return store;
 }
@@ -160,12 +214,18 @@ describe("a Bot authoring a Package", () => {
   let storage: ReturnType<typeof memoryStorage>;
   let composition: Awaited<ReturnType<typeof memoryComposition>>;
   let written: string[];
+  let writtenSources: string[];
+  let writtenUi: string[];
+  let sourceContents: Map<string, string>;
   let reservations: unknown[];
 
   beforeEach(async () => {
     storage = memoryStorage();
     composition = await memoryComposition();
     written = [];
+    writtenSources = [];
+    writtenUi = [];
+    sourceContents = new Map();
     reservations = [];
   });
 
@@ -173,6 +233,7 @@ describe("a Bot authoring a Package", () => {
     bundler: ReturnType<typeof countingBundler>;
     quota?: (request: unknown) => unknown;
     runId?: string;
+    currentToolNames?: readonly string[];
   }) {
     let ids = 0;
     return createPackageAuthoringHost({
@@ -184,6 +245,17 @@ describe("a Bot authoring a Package", () => {
           written.push(contentHash);
           return Promise.resolve();
         },
+        putPackageSource: (sourceHash, source) => {
+          writtenSources.push(sourceHash);
+          sourceContents.set(sourceHash, source);
+          return Promise.resolve();
+        },
+        putPackageUiArtifact: (contentHash) => {
+          writtenUi.push(contentHash);
+          return Promise.resolve();
+        },
+        loadPackageSource: (sourceHash) =>
+          Promise.resolve(sourceContents.get(sourceHash)),
         headPackageArtifact: () => Promise.resolve(undefined),
       },
       quota: {
@@ -206,6 +278,7 @@ describe("a Bot authoring a Package", () => {
       runId: options.runId ?? "run-1",
       turnId: options.runId ?? "run-1",
       compatibilityDate: "2026-08-27",
+      currentToolNames: () => options.currentToolNames ?? [],
       now: () => new Date("2026-08-31T01:00:00.000Z"),
       newId: () => `id-${(ids += 1)}`,
     });
@@ -242,7 +315,93 @@ describe("a Bot authoring a Package", () => {
       authoredAt: "2026-08-31T01:00:00.000Z",
     });
     expect(artifact.r2Key).toBe(`packages/${"b".repeat(64)}.mjs`);
+    expect(artifact.sourceR2Key).toBe(`packages/${"a".repeat(64)}.ts`);
+    expect(artifact.sourceHash).toBe("a".repeat(64));
     expect(written).toEqual(["b".repeat(64)]);
+    expect(writtenSources).toEqual(["a".repeat(64)]);
+    const manifestRecord = storage.values.get(
+      authorshipManifestKey(artifact.manifestHash),
+    ) as AuthoredManifestRecordV1;
+    expect(decodeFrockBotManifest(manifestRecord.manifest)).toMatchObject({
+      id: "hello-world",
+      version: "0.0.1",
+      contributions: { runtime: { host: "bot-isolate" } },
+      tools: [{ name: "hello" }],
+    });
+  });
+
+  test("stores declared loop hooks in the authored manifest", async () => {
+    const bundler = countingBundler((effectId) => bundledResult(effectId));
+    const outcome = await host({ bundler }).author(
+      requestFor({
+        input: {
+          ...requestFor().input,
+          hooks: ["agent/tool-exposure", "tools/post-execute"],
+        },
+      }),
+    );
+    if (outcome.status !== "authored") throw new Error(outcome.reason);
+
+    const artifact = storage.values.get(
+      artifactKey(outcome.contentHash),
+    ) as AuthoredArtifactRecordV1;
+    const manifestRecord = storage.values.get(
+      authorshipManifestKey(artifact.manifestHash),
+    ) as AuthoredManifestRecordV1;
+
+    expect(manifestRecord.manifest).toMatchObject({
+      hooks: ["agent/tool-exposure", "tools/post-execute"],
+    });
+  });
+
+  test("stores the second immutable artifact and records it in the same manifest", async () => {
+    const html = "<!doctype html><h1>Hello</h1>";
+    const contentHash = await sha256HexV1(html);
+    const bundler = countingBundler((effectId) => ({
+      ...bundledResult(effectId),
+      uiArtifact: {
+        contentHash,
+        size: new TextEncoder().encode(html).byteLength,
+        mediaType: "text/html",
+        bundlerVersion: "frockbot-inline-html@1",
+      },
+      uiHtml: html,
+    }));
+    const request = requestFor();
+    const outcome = await host({ bundler }).author({
+      ...request,
+      input: {
+        ...request.input,
+        hooks: ["agent/tool-exposure", "tools/post-execute"],
+        ui: {
+          html,
+          mounts: [{ slot: "frockbot.tool-result:hello" }],
+        },
+      },
+    });
+    expect(outcome.status).toBe("authored");
+    expect(writtenUi).toEqual([contentHash]);
+    const artifact = storage.values.get(
+      artifactKey("b".repeat(64)),
+    ) as AuthoredArtifactRecordV1;
+    const stored = storage.values.get(
+      authorshipManifestKey(artifact.manifestHash),
+    ) as AuthoredManifestRecordV1;
+    const manifest = decodeFrockBotManifest(stored.manifest);
+    expect(manifest.contributions.client).toEqual({
+      kind: "iframe",
+      artifact: {
+        contentHash,
+        size: new TextEncoder().encode(html).byteLength,
+        mediaType: "text/html",
+        bundlerVersion: "frockbot-inline-html@1",
+      },
+      mounts: [{ slot: "frockbot.tool-result:hello" }],
+    });
+    expect(manifest.hooks).toEqual([
+      "agent/tool-exposure",
+      "tools/post-execute",
+    ]);
   });
 
   test("proposes a pending generation pinned for the next Turn", async () => {
@@ -287,7 +446,13 @@ describe("a Bot authoring a Package", () => {
       ),
     );
     const first = await host({ bundler }).author(requestFor());
-    const second = await host({ bundler, runId: "run-2" }).author(
+    if (first.status !== "authored") throw new Error(first.reason);
+    composition.activate(first.generationId);
+    const second = await host({
+      bundler,
+      runId: "run-2",
+      currentToolNames: ["hello"],
+    }).author(
       requestFor({ effectId: "author-second", sourceHash: "d".repeat(64) }),
     );
     if (first.status !== "authored" || second.status !== "authored") {
@@ -318,6 +483,105 @@ describe("a Bot authoring a Package", () => {
     ).toBe(first.generationId);
   });
 
+  test("a failed pending generation is never inherited by later authoring", async () => {
+    const bundler = countingBundler((effectId) =>
+      bundledResult(
+        effectId,
+        effectId === "author-first" ? "b".repeat(64) : "c".repeat(64),
+      ),
+    );
+    const first = await host({ bundler, runId: "run-1" }).author(
+      requestFor({ effectId: "author-first" }),
+    );
+    if (first.status !== "authored") throw new Error(first.reason);
+    composition.fail(first.generationId);
+
+    const second = await host({ bundler, runId: "run-2" }).author(
+      requestFor({
+        effectId: "author-second",
+        sourceHash: "d".repeat(64),
+        input: {
+          ...requestFor().input,
+          packageId: "second-package",
+          tools: [
+            { name: "second_tool", description: "Second", inputSchema: {} },
+          ],
+        },
+      }),
+    );
+    if (second.status !== "authored") throw new Error(second.reason);
+    const generation = composition.generations.get(second.generationId)!;
+    expect(generation.parentGenerationId).toBe(
+      (await composition.lastKnownGood()).generationId,
+    );
+    expect(generation.members.map((member) => member.packageId)).toEqual([
+      "second-package",
+      "shell",
+    ]);
+  });
+
+  test("re-authoring the same package repairs a failed proposal from last-known-good", async () => {
+    const bundler = countingBundler((effectId) =>
+      bundledResult(
+        effectId,
+        effectId === "author-broken" ? "b".repeat(64) : "c".repeat(64),
+      ),
+    );
+    const broken = await host({ bundler, runId: "run-broken" }).author(
+      requestFor({ effectId: "author-broken" }),
+    );
+    if (broken.status !== "authored") throw new Error(broken.reason);
+    composition.fail(broken.generationId);
+
+    const repaired = await host({ bundler, runId: "run-repair" }).author(
+      requestFor({
+        effectId: "author-repair",
+        sourceHash: "d".repeat(64),
+        input: { ...requestFor().input, source: `${SOURCE}// repaired\n` },
+      }),
+    );
+
+    if (repaired.status !== "authored") throw new Error(repaired.reason);
+    const generation = composition.generations.get(repaired.generationId)!;
+    expect(generation.parentGenerationId).toBe(
+      (await composition.lastKnownGood()).generationId,
+    );
+    expect(
+      generation.members.find((member) => member.packageId === "hello-world")
+        ?.version,
+    ).toBe("0.0.2");
+    expect(generation.members).toHaveLength(2);
+  });
+
+  test("a registered tool-name collision is refused before quota or bundling", async () => {
+    const bundler = countingBundler((effectId) => bundledResult(effectId));
+    const outcome = await host({
+      bundler,
+      currentToolNames: ["memory_write", "package_author"],
+    }).author(
+      requestFor({
+        input: {
+          ...requestFor().input,
+          tools: [
+            {
+              name: "memory_write",
+              description: "Would collide",
+              inputSchema: {},
+            },
+          ],
+        },
+      }),
+    );
+
+    expect(outcome.status).toBe("refused");
+    if (outcome.status !== "refused") throw new Error("unreachable");
+    expect(outcome.reason).toContain(
+      'Tool "memory_write" is already registered',
+    );
+    expect(reservations).toEqual([]);
+    expect(bundler.calls).toBe(0);
+  });
+
   test("shadowing a first-party Package is refused before any durable effect", async () => {
     const bundler = countingBundler((effectId) => bundledResult(effectId));
     const outcome = await host({ bundler }).author(
@@ -440,6 +704,7 @@ describe("a Bot authoring a Package", () => {
         packageId: "hello-world",
         version: "0.0.1",
         sourceHash: "a".repeat(64),
+        manifestHash: "f".repeat(64),
         sourceBytes: SOURCE.length,
         recordedAt: "2026-08-31T00:30:00.000Z",
         status: "recorded",
@@ -471,6 +736,7 @@ describe("a Bot authoring a Package", () => {
         packageId: "hello-world",
         version: "0.0.1",
         sourceHash: "a".repeat(64),
+        manifestHash: "f".repeat(64),
         sourceBytes: SOURCE.length,
         recordedAt: "2026-08-31T00:30:00.000Z",
         status: "recorded",
@@ -515,4 +781,92 @@ describe("a Bot authoring a Package", () => {
     expect(outcome.status).toBe("refused");
     expect(composition.generations.size).toBe(1);
   });
+
+  test("package undo records intent before an idempotent Bot-origin revert without moving last-known-good", async () => {
+    const bundler = countingBundler((effectId) => bundledResult(effectId));
+    const authored = await host({ bundler }).author(requestFor());
+    if (authored.status !== "authored") throw new Error("authoring failed");
+    composition.activate(authored.generationId);
+    const goodBeforeUndo = await composition.lastKnownGood();
+    const undoHost = host({ bundler, runId: "run-undo" });
+    const effectId = await undoHost.undoEffectIdFor({});
+    const request = {
+      input: {},
+      effectId,
+      sessionId: "user-1:bot-1",
+      position: { turn: 2, step: 1 },
+    } as const;
+
+    const first = await undoHost.undo(request);
+    const replay = await undoHost.undo(request);
+
+    expect(first).toEqual(replay);
+    expect(first.status).toBe("recorded");
+    if (first.status !== "recorded") throw new Error("undo was refused");
+    const reverted = composition.generations.get(first.generationId)!;
+    expect(reverted.origin).toEqual({
+      kind: "revert",
+      revertsTo: first.targetGenerationId,
+      botId: "bot-1",
+      runId: "run-undo",
+      turnId: "run-undo",
+    });
+    expect(reverted.members.map((member) => member.packageId)).toEqual([
+      "shell",
+    ]);
+    expect((await composition.lastKnownGood()).generationId).toBe(
+      goodBeforeUndo.generationId,
+    );
+    expect(storage.values.has(authorshipUndoIntentKey(effectId))).toBe(true);
+    expect(storage.values.has(authorshipUndoOutcomeKey(effectId))).toBe(true);
+  });
+
+  test("package_inspect_self returns generated contract, declared tools, stored source, and latest failure", async () => {
+    const bundler = countingBundler((effectId) => bundledResult(effectId));
+    const authored = await host({ bundler }).author(requestFor());
+    if (authored.status !== "authored") throw new Error("authoring failed");
+    composition.activate(authored.generationId);
+    const inspecting = host({
+      bundler,
+      runId: "run-inspect",
+      currentToolNames: ["hello", "memory_write"],
+    });
+    await inspecting.author(
+      requestFor({
+        effectId: "author-collision",
+        sourceHash: "c".repeat(64),
+        input: {
+          ...requestFor().input,
+          tools: [
+            {
+              name: "memory_write",
+              description: "collides",
+              inputSchema: {},
+            },
+          ],
+        },
+      }),
+    );
+
+    const view = await inspecting.inspectSelf();
+
+    expect(view.contextContract).toContain(
+      "interface BotPackageExecutionContextV1",
+    );
+    expect(view.contextContract).toContain("interface FrockBotIframeBridgeV1");
+    expect(view.contextContract).toContain("window.frockbot=");
+    expect(view.composition.members).toContainEqual(
+      expect.objectContaining({
+        packageId: "hello-world",
+        declaredTools: ["hello"],
+        source: SOURCE,
+      }),
+    );
+    expect(view.failures).toContainEqual(
+      expect.objectContaining({
+        packageId: "hello-world",
+        authoring: expect.objectContaining({ phase: "compose" }),
+      }),
+    );
+  });
 });