@frockbot/plugin-shell 0.3.9 → 0.3.11

package/src/composition-manifest.test.ts

@@ -0,0 +1,126 @@
+// Every Bot-authored Package failed to mount with `package "aud-usd" stored
+// manifest failed hash verification`, deterministically, on byte-identical
+// source. The mount hashed a *decoded* manifest against a hash taken over the
+// *raw* one, so journey 4 step 2 — "use the tool you just built" — was
+// impossible for anybody. First-party members mounted fine, because their
+// reader already returned the raw document.
+import { describe, expect, test } from "bun:test";
+import { authoredManifestV1 } from "@frockbot/plugin-authoring/shared";
+import { decodeFrockBotManifest } from "@frockbot/kernel-composition";
+import type { CompositionMemberV1 } from "@frockbot/kernel-composition/generation";
+import { botIsolatePackageDescriptorV1 } from "@frockbot/kernel-composition/isolate";
+import { canonicalJson, sha256 } from "@frockbot/kernel-composition/compiler";
+
+import {
+  type CompositionManifestSourcesV1,
+  compositionMemberManifestDocumentV1,
+  compositionMemberManifestV1,
+} from "./composition-manifest.js";
+
+/** What `package_author` writes, exactly as `backend-authoring.ts` builds it. */
+function authoredManifest(): unknown {
+  return authoredManifestV1({
+    packageId: "aud-usd",
+    displayName: "AUD/USD",
+    version: "0.0.1",
+    tools: [
+      {
+        name: "aud_usd_rate",
+        description: "The current AUD/USD rate.",
+        inputSchema: { type: "object", properties: {} },
+      },
+    ],
+  });
+}
+
+/** The durable store, as `authorship:manifest:<hash>` holds it. */
+async function storedMember(): Promise<{
+  member: CompositionMemberV1;
+  manifest: unknown;
+  sources: CompositionManifestSourcesV1;
+}> {
+  const manifest = authoredManifest();
+  // The one hash that matters: taken over the raw document at authoring time.
+  const manifestHash = await sha256(canonicalJson(manifest));
+  const member: CompositionMemberV1 = {
+    packageId: "aud-usd",
+    specifier: "bot:aud-usd",
+    version: "0.0.1",
+    manifestHash,
+    provenance: {
+      kind: "bot",
+      packageId: "aud-usd",
+      version: "0.0.1",
+      botId: "toolsmith",
+      sessionId: "user-1:toolsmith",
+      turnId: "turn-1",
+      runId: "run-1",
+      authoredAt: "2026-09-03T23:49:00.416Z",
+    },
+    artifact: {
+      contentHash: "b".repeat(64),
+      size: 128,
+      mediaType: "application/javascript",
+      bundlerVersion: "worker-bundler@0.2.3",
+    },
+  };
+  const sources: CompositionManifestSourcesV1 = {
+    stored: (hash) =>
+      Promise.resolve(hash === manifestHash ? { manifest } : undefined),
+    application: () => Promise.resolve(undefined),
+  };
+  return { member, manifest, sources };
+}
+
+describe("the manifest a mount is handed", () => {
+  test("hashes to what the Composition member recorded", async () => {
+    const { member, sources } = await storedMember();
+
+    const document = await compositionMemberManifestDocumentV1(member, sources);
+    const descriptor = await botIsolatePackageDescriptorV1(member, document);
+
+    expect(descriptor.manifest.id).toBe("aud-usd");
+    expect(descriptor.manifest.version).toBe("0.0.1");
+  });
+
+  test("is the stored document, not a rebuild of it", async () => {
+    const { member, manifest, sources } = await storedMember();
+
+    const document = await compositionMemberManifestDocumentV1(member, sources);
+
+    expect(document).toBe(manifest);
+  });
+
+  test("decoding first is what broke it, and still would", async () => {
+    // The guard this test exists for. `decodeFrockBotManifest` rebuilds the
+    // object — `decodeV5` always writes a `configuration` key — so the decoded
+    // manifest does not canonicalize back to the recorded hash. If the reader
+    // ever decodes again, the test above fails and this one says why.
+    const { member, manifest } = await storedMember();
+    const decoded = decodeFrockBotManifest(manifest);
+
+    expect(canonicalJson(decoded)).not.toBe(canonicalJson(manifest));
+    await expect(
+      botIsolatePackageDescriptorV1(member, decoded),
+    ).rejects.toThrow("stored manifest failed hash verification");
+  });
+
+  test("the typed reader still answers the shape its callers want", async () => {
+    const { member, sources } = await storedMember();
+
+    const typed = await compositionMemberManifestV1(member, sources);
+
+    expect(typed?.id).toBe("aud-usd");
+    expect(typed?.version).toBe("0.0.1");
+  });
+
+  test("a member with no stored manifest falls back to the application's", async () => {
+    const { member, manifest } = await storedMember();
+    const document = await compositionMemberManifestDocumentV1(member, {
+      stored: () => Promise.resolve(undefined),
+      application: () => Promise.resolve(manifest),
+    });
+
+    expect(document).toBe(manifest);
+  });
+});

package/src/composition-manifest.ts

@@ -0,0 +1,55 @@
+import {
+  type FrockBotManifest,
+  decodeFrockBotManifest,
+} from "@frockbot/kernel-composition";
+import type { CompositionMemberV1 } from "@frockbot/kernel-composition/generation";
+
+/**
+ * Where a Composition member's manifest can be found. `stored` is
+ * `authorship:manifest:<hash>` — written by the authoring path and by a
+ * Catalog install, so it covers every member a Bot or its User put into the
+ * Composition. `application` is the compiled-in manifest of a first-party
+ * artifact-backed member (ADR 0022 decision 8), which came from neither and is
+ * already in this bundle. Two *places*, never two answers: the `manifestHash`
+ * decides in both.
+ */
+export interface CompositionManifestSourcesV1 {
+  stored(manifestHash: string): Promise<{ manifest: unknown } | undefined>;
+  application(member: CompositionMemberV1): Promise<unknown | undefined>;
+}
+
+/**
+ * A member's manifest **as the stored document** — byte-for-byte what its
+ * `manifestHash` was taken over.
+ *
+ * This is the seam that broke every Bot-authored Package. Authoring hashes
+ * `canonicalJson(rawManifest)` and stores `rawManifest` verbatim; the mount
+ * re-hashes whatever it is handed and refuses a mismatch
+ * (`botIsolatePackageDescriptorV1`). Returning a *decoded* manifest here put a
+ * rebuilt object on the mount's side of that comparison — `decodeV5` always
+ * writes a `configuration` key, among other things — so the two hashes could
+ * never agree, and every authored Package failed with `stored manifest failed
+ * hash verification` while first-party members (which were already read raw)
+ * mounted fine.
+ *
+ * Callers that want the typed shape decode it themselves, downstream of the
+ * hash check.
+ */
+export async function compositionMemberManifestDocumentV1(
+  member: CompositionMemberV1,
+  sources: CompositionManifestSourcesV1,
+): Promise<unknown | undefined> {
+  const stored = await sources.stored(member.manifestHash);
+  if (stored) return stored.manifest;
+  return await sources.application(member);
+}
+
+/** The same manifest as the typed shape, for readers that are not mounts. */
+export async function compositionMemberManifestV1(
+  member: CompositionMemberV1,
+  sources: CompositionManifestSourcesV1,
+): Promise<FrockBotManifest | undefined> {
+  const document = await compositionMemberManifestDocumentV1(member, sources);
+  if (document === undefined) return undefined;
+  return decodeFrockBotManifest(document);
+}

package/src/notification-id.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from "bun:test";
+
+import { notificationIdV1 } from "./notification-id.js";
+import { decodeClientNotificationAcknowledgementCommandV1 } from "./run-protocol.js";
+
+/** What the acknowledge endpoint does with an id a notification carried. */
+function acknowledge(notificationId: string): string {
+  return decodeClientNotificationAcknowledgementCommandV1({
+    schemaVersion: 1,
+    action: "acknowledge",
+    notificationId,
+  }).notificationId;
+}
+
+describe("notificationIdV1", () => {
+  test("a Composition failure id round-trips through acknowledgement", () => {
+    // The shape that 400'd forever: a generation id is `<ISO instant>:<hash>`,
+    // and the acknowledge decoder admits no colons.
+    const id = notificationIdV1(
+      "composition-failure",
+      "2026-09-03T23:49:00.416Z:dc03a32d9b717619",
+      1,
+    );
+    expect(id).not.toContain(":");
+    expect(acknowledge(id)).toBe(id);
+  });
+
+  test("every minted id shape acknowledges", () => {
+    const minted = [
+      notificationIdV1(
+        "package-connection-unavailable",
+        crypto.randomUUID(),
+        "aud-usd",
+        "gmail",
+      ),
+      notificationIdV1("package", "aud-usd", "rate:moved"),
+      notificationIdV1("routine-failed", "2026-09-03T23:49:00.416Z:fire"),
+      notificationIdV1("task-settled", crypto.randomUUID()),
+      notificationIdV1("routine-wake", crypto.randomUUID()),
+    ];
+    for (const id of minted) expect(acknowledge(id)).toBe(id);
+  });
+
+  test("the same parts mint the same id, so a retry is one intent", () => {
+    const parts = [
+      "composition-failure",
+      "2026-09-03T23:49:00.416Z:abc",
+      2,
+    ] as const;
+    expect(notificationIdV1(...parts)).toBe(notificationIdV1(...parts));
+  });
+
+  test("parts the sanitiser would flatten together stay distinct", () => {
+    // Well under the length ceiling, so nothing else separates them: `a:b` and
+    // `a-b` both sanitise to `a-b`, and one notification silently overwrote
+    // the other.
+    expect(notificationIdV1("package", "a:b")).not.toBe(
+      notificationIdV1("package", "a-b"),
+    );
+    expect(notificationIdV1("a", "b")).not.toBe(notificationIdV1("a-b"));
+  });
+
+  test("distinct parts stay distinct, even past the length ceiling", () => {
+    const long = "x".repeat(400);
+    const a = notificationIdV1("package", long, "one");
+    const b = notificationIdV1("package", long, "two");
+    expect(a).not.toBe(b);
+    expect(a.length).toBeLessThanOrEqual(128);
+    expect(acknowledge(a)).toBe(a);
+    expect(acknowledge(b)).toBe(b);
+  });
+
+  test("a legacy colon id already in the field can still be acknowledged", () => {
+    // Bots that failed a generation before this fix are holding notifications
+    // whose ids were interpolated by hand. If those stay unacknowledgeable the
+    // client retries them forever, so the decoder admits the older shape even
+    // though nothing mints it any more.
+    const legacy =
+      "composition-failure:2026-09-03T23:49:00.416Z:dc03a32d9b717619:1";
+    expect(acknowledge(legacy)).toBe(legacy);
+  });
+
+  test("an id is still bounded, whatever shape it arrives in", () => {
+    expect(() => acknowledge("a".repeat(200))).toThrow();
+    expect(() => acknowledge("../../escape")).toThrow();
+    expect(() => acknowledge("")).toThrow();
+  });
+
+  test("parts that sanitize to nothing still mint an acknowledgeable id", () => {
+    const id = notificationIdV1(":::", "::");
+    expect(acknowledge(id)).toBe(id);
+  });
+});

package/src/run-protocol.ts

@@ -5,7 +5,10 @@ import {
   type SessionEvent,
   type SkillRefV1,
 } from "@frockbot/kernel-contracts";
-import { isPublicIdentifier } from "@frockbot/configuration-core";
+import {
+  isPublicIdentifier,
+  isRpcIdentifier,
+} from "@frockbot/configuration-core";
 import { decodeRunCursorV1, RUN_CURSOR_PATTERN } from "./run-cursor.js";
 export { decodeRunCursorV1, RUN_CURSOR_PATTERN };
 import type {
@@ -1648,7 +1651,15 @@ export function decodeClientNotificationAcknowledgementCommandV1(
     MAX_RUN_ID_LENGTH,
     "notification acknowledgement command",
   );
-  if (!isPublicIdentifier(notificationId)) {
+  // `isRpcIdentifier`, not `isPublicIdentifier`: the same bounded alphabet
+  // plus `:` and `@`. New ids are minted through `notificationIdV1` and carry
+  // neither, but Bots in the field are already holding notifications whose ids
+  // were interpolated by hand — `composition-failure:<generationId>:<attempt>`
+  // and three more like it. Under the stricter pattern those could never be
+  // acknowledged, so the client retried them forever and the Bot answered 400
+  // on every poll for the rest of its life. Accepting them here is what lets
+  // an already-wedged Bot recover without a storage sweep.
+  if (!isRpcIdentifier(notificationId)) {
     throw new Error(
       "notification acknowledgement command.notificationId is invalid",
     );

package/src/settings-links.ts

@@ -81,6 +81,12 @@ export const SETTINGS_ANCHORS_V1: readonly SettingsAnchorV1[] = [
     label: "Label",
     scope: "bot",
   },
+  {
+    anchor: "bot-pinned",
+    surface: "bot-settings",
+    label: "Pinned",
+    scope: "bot",
+  },
   {
     anchor: "bot-description",
     surface: "bot-settings",

package/src/unread.ts

@@ -389,6 +389,15 @@ export interface BotUnreadViewV1 {
   lastViewedAt?: string;
   /** Latest settled assistant/user line, projected for the sidebar only. */
   lastMessage?: SidebarMessagePreviewV1;
+  /**
+   * Whether this Bot has a Turn running right now.
+   *
+   * The sidebar draws it as an activity ring on the row's avatar, so somebody
+   * reading one conversation can see another Bot still working rather than
+   * assuming it stalled. Optional: a view a client older than the Bot decodes,
+   * or one stored before this existed, simply draws no ring.
+   */
+  working?: boolean;
 }
 
 export interface BotUnreadDirectoryViewV1 {
@@ -414,6 +423,8 @@ export function projectBotUnreadViewV1(
    * so it counts here even though the firing that produced it does not.
    */
   automationFailures = 0,
+  /** True while a Turn of this Bot's is running. Drawn as the row's ring. */
+  working = false,
 ): BotUnreadViewV1 {
   const ceiling = state.lastActivityCursor;
   let counted = Math.max(0, automationFailures);
@@ -449,6 +460,7 @@ export function projectBotUnreadViewV1(
       ? {}
       : { lastViewedAt: state.lastViewedAt }),
     ...(lastMessage === undefined ? {} : { lastMessage }),
+    ...(working ? { working: true } : {}),
   };
 }
 
@@ -528,7 +540,13 @@ function decodeBotUnreadViewV1(input: unknown): BotUnreadViewV1 {
   exactKeys(
     value,
     ["schemaVersion", "botId", "count", "capped", "unread", "manuallyUnread"],
-    ["lastActivityCursor", "lastActivityAt", "lastViewedAt", "lastMessage"],
+    [
+      "lastActivityCursor",
+      "lastActivityAt",
+      "lastViewedAt",
+      "lastMessage",
+      "working",
+    ],
     "unread view",
   );
   if (value.schemaVersion !== 1) {
@@ -563,6 +581,9 @@ function decodeBotUnreadViewV1(input: unknown): BotUnreadViewV1 {
   );
   const lastViewedAt = optionalTimestamp(value, "lastViewedAt", "unread view");
   const lastMessage = optionalSidebarMessagePreviewV1(value.lastMessage);
+  if (value.working !== undefined && typeof value.working !== "boolean") {
+    throw new UnreadDecodeError("unread view working is invalid");
+  }
   return {
     schemaVersion: 1,
     botId: value.botId,
@@ -574,6 +595,7 @@ function decodeBotUnreadViewV1(input: unknown): BotUnreadViewV1 {
     ...(lastActivityAt === undefined ? {} : { lastActivityAt }),
     ...(lastViewedAt === undefined ? {} : { lastViewedAt }),
     ...(lastMessage === undefined ? {} : { lastMessage }),
+    ...(value.working === true ? { working: true } : {}),
   };
 }