@frockbot/plugin-shell 0.3.1 → 0.3.2

package/src/client/index.ts

@@ -62,7 +62,7 @@ import {
   decodeTaskListViewV1,
   decodeTaskViewV1,
 } from "@frockbot/plugin-subagents/shared";
-import { ref, toRaw, type Ref } from "vue";
+import { defineComponent, h, ref, toRaw, watch, type Ref } from "vue";
 import {
   frockBotWebDataKey,
   type FrockBotWebData,
@@ -75,11 +75,28 @@ import {
   type WebToolActivity,
 } from "../shared.js";
 import FrockBotApp from "./FrockBotApp.vue";
+import PackageEntryTrigger from "./PackageEntryTrigger.vue";
 import PackageIframeSettings from "./PackageIframeSettings.vue";
+import PackageSurfacePage from "./PackageSurfacePage.vue";
+import {
+  packageIframeEntriesV1,
+  type PackageIframeEntryV1,
+} from "./package-iframe-entries.js";
+import { appletsAvailableV1 } from "./applets-state.js";
+import {
+  readAppletBuild,
+  readAppletList,
+  readAppletSource,
+  readAppletUi,
+  readAppletViewerToken,
+  readFocusedAppletId,
+  writeFocusedAppletId,
+} from "./applets-client.js";
 import { modelRuntimeLabel } from "./model-presentation.js";
 import { showClientNotificationV1 } from "./notify.js";
 import "@frockbot/client-core/fonts.css";
 import "./styles.css";
+import { defineClientContribution } from "@frockbot/kernel-contracts/contributions";
 
 function toolsFrom(events: ClientTurnEvent[]): WebToolActivity[] {
   const tools = new Map<string, WebToolActivity>();
@@ -1108,6 +1125,22 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     approvals: [],
     tasks: [],
     packageUi: undefined,
+    applets: [],
+    focusedAppletId: undefined,
+    appletViewer: undefined,
+    appletSource: undefined,
+    appletBuild: undefined,
+    appletCanvas: "idle",
+    /*
+     * The focused Applet, joined with the list the User owns. A getter rather
+     * than a stored field so the two can never disagree: the id is what the
+     * Bot Durable Object recorded, and this is what that id currently names.
+     */
+    get focusedApplet() {
+      const appletId = web.value.focusedAppletId;
+      if (!appletId) return undefined;
+      return web.value.applets.find((applet) => applet.appletId === appletId);
+    },
     async selectBot(botId: string): Promise<void> {
       // Re-selecting the open Bot is not a switch: aborting the live Turn and
       // clearing the transcript would discard state the User is watching.
@@ -1127,6 +1160,14 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       web.value.approvals = [];
       web.value.tasks = [];
       web.value.packageUi = undefined;
+      // The focus is per Session, so switching Bots drops what the previous
+      // Bot's canvas was showing rather than carrying it across.
+      web.value.focusedAppletId = undefined;
+      web.value.appletViewer = undefined;
+      web.value.appletSource = undefined;
+      web.value.appletBuild = undefined;
+      web.value.appletCanvas = "idle";
+      web.value.appletCanvasError = undefined;
       const url = URL.parse(window.location.href);
       if (url) {
         url.searchParams.set("bot", botId);
@@ -1234,6 +1275,162 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         }
       }
     },
+    /*
+     * The Applets the User owns.
+     *
+     * Account-shaped, so this is read once per selection rather than per Bot,
+     * and a deployment with no Applet routes reads as an empty list instead of
+     * an error over the conversation.
+     */
+    async loadApplets(): Promise<void> {
+      const read = ctx.transport.hostedRequest;
+      if (!read || !appletsAvailableV1(web.value.packageUi)) return;
+      const generation = selectionGeneration;
+      try {
+        const applets = await readAppletList(read);
+        if (generation !== selectionGeneration) return;
+        web.value.applets = applets;
+      } catch {
+        if (generation === selectionGeneration) web.value.applets = [];
+      }
+    },
+    async loadFocusedApplet(): Promise<void> {
+      const read = ctx.transport.hostedRequest;
+      const botId = web.value.activeBotId;
+      if (!read || !botId || !appletsAvailableV1(web.value.packageUi)) return;
+      const generation = selectionGeneration;
+      try {
+        const appletId = await readFocusedAppletId(read, botId);
+        if (
+          generation !== selectionGeneration ||
+          web.value.activeBotId !== botId
+        )
+          return;
+        web.value.focusedAppletId = appletId;
+      } catch {
+        if (
+          generation === selectionGeneration &&
+          web.value.activeBotId === botId
+        )
+          web.value.focusedAppletId = null;
+      }
+      await web.value.refreshAppletCanvas();
+    },
+    async setFocusedApplet(appletId: string | null): Promise<void> {
+      const post = ctx.transport.hostedRequest;
+      const botId = web.value.activeBotId;
+      if (!post || !botId || !appletsAvailableV1(web.value.packageUi)) return;
+      const generation = selectionGeneration;
+      try {
+        const recorded = await writeFocusedAppletId(post, botId, appletId);
+        if (
+          generation !== selectionGeneration ||
+          web.value.activeBotId !== botId
+        )
+          return;
+        // What the canvas shows is the focus the backend recorded, never the
+        // one the click asked for.
+        web.value.focusedAppletId = recorded;
+        web.value.appletViewer = undefined;
+        web.value.appletSource = undefined;
+        web.value.appletBuild = undefined;
+        web.value.appletCanvasError = undefined;
+        // Focusing is also when the list is re-read: a publish that landed
+        // between selections is why the canvas has an Applet to show at all,
+        // and a stale list would leave it in the building state forever.
+        await web.value.loadApplets();
+      } catch (error) {
+        if (
+          generation !== selectionGeneration ||
+          web.value.activeBotId !== botId
+        )
+          return;
+        web.value.appletCanvas = "failed";
+        web.value.appletCanvasError =
+          error instanceof Error
+            ? error.message
+            : "Could not focus that Applet";
+        return;
+      }
+      await web.value.refreshAppletCanvas();
+    },
+    /*
+     * What the canvas draws for the focused Applet.
+     *
+     * The source read is the building state and never waits on the Computer:
+     * the Workspace store is read, so a hibernated Computer costs nothing. The
+     * viewer credential is only fetched once a generation is active, because
+     * there is nothing to view before one is.
+     */
+    async refreshAppletCanvas(): Promise<void> {
+      const read = ctx.transport.hostedRequest;
+      const appletId = web.value.focusedAppletId;
+      const botId = web.value.activeBotId;
+      if (!read || !appletId || !botId) {
+        web.value.appletCanvas = "idle";
+        return;
+      }
+      const generation = selectionGeneration;
+      const stale = () =>
+        generation !== selectionGeneration ||
+        web.value.focusedAppletId !== appletId;
+      if (web.value.appletViewer?.appletId !== appletId) {
+        web.value.appletCanvas = "loading";
+      }
+      web.value.appletCanvasError = undefined;
+      try {
+        const [source, build] = await Promise.all([
+          readAppletSource(read, botId, appletId),
+          readAppletBuild(read, botId, appletId).catch(() => ({
+            status: "unknown" as const,
+          })),
+        ]);
+        if (stale()) return;
+        web.value.appletSource = source;
+        web.value.appletBuild = build;
+      } catch (error) {
+        if (stale()) return;
+        web.value.appletCanvas = "failed";
+        web.value.appletCanvasError =
+          error instanceof Error ? error.message : "Could not read this Applet";
+        return;
+      }
+      const applet = web.value.applets.find(
+        (candidate) => candidate.appletId === appletId,
+      );
+      if (!applet?.currentGenerationId) {
+        // No active generation is the building state, not a failure.
+        if (!stale()) {
+          web.value.appletViewer = undefined;
+          web.value.appletCanvas = "ready";
+        }
+        return;
+      }
+      try {
+        const [ui, token] = await Promise.all([
+          readAppletUi(read, appletId),
+          readAppletViewerToken(read, appletId),
+        ]);
+        if (stale()) return;
+        web.value.appletViewer = {
+          appletId,
+          token: token.token,
+          expiresAt: token.expiresAt,
+          socketUrl: token.socketUrl,
+          uiUrl: ui.uiUrl,
+          generationId: ui.generationId ?? applet.currentGenerationId,
+        };
+        web.value.appletCanvas = "ready";
+      } catch (error) {
+        if (stale()) return;
+        // A published Applet whose viewer cannot be opened keeps the code view
+        // up and says so; it never shows an empty frame pretending to work.
+        web.value.appletViewer = undefined;
+        web.value.appletCanvas = "failed";
+        web.value.appletCanvasError =
+          error instanceof Error ? error.message : "Could not open this Applet";
+      }
+    },
     async callPackageUiTool(
       contribution: PackageIframeContributionViewV1,
       name: string,
@@ -1365,6 +1562,18 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         updateSettingsLoadError("bot");
         await deliverNotifications(botId, generation);
         await web.value.loadPackageUi();
+        if (
+          generation !== selectionGeneration ||
+          web.value.activeBotId !== botId
+        )
+          return;
+        await web.value.loadApplets();
+        if (
+          generation !== selectionGeneration ||
+          web.value.activeBotId !== botId
+        )
+          return;
+        await web.value.loadFocusedApplet();
       } catch (error) {
         if (
           generation !== selectionGeneration ||
@@ -2224,6 +2433,90 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     },
   } satisfies Partial<ShellWebData>) as unknown as Ref<ShellWebData>;
 
+  /*
+   * Declarative Package entries.
+   *
+   * An entry is manifest data, so the sidebar control and the surface it opens
+   * are registered from the Bot's Composition rather than by Package code:
+   * nothing a Package ships executes in the app origin. The registrations are
+   * disposed and rebuilt whenever the catalog changes, so switching Bots never
+   * leaves the previous Bot's entries in the sidebar.
+   */
+  let entryDisposers: Array<() => void> = [];
+
+  function syncPackageEntries(entries: PackageIframeEntryV1[]): void {
+    for (const dispose of entryDisposers.splice(0).toReversed()) dispose();
+    entryDisposers = entries.flatMap((entry) => {
+      const trigger = defineComponent({
+        name: `PackageEntry_${entry.contribution.packageId}_${entry.entry.id}`,
+        setup: () => () => h(PackageEntryTrigger, { entry }),
+      });
+      const page = defineComponent({
+        name: `PackageSurface_${entry.contribution.packageId}_${entry.page.id}`,
+        setup: () => () => h(PackageSurfacePage, { entry }),
+      });
+      return [
+        surfaces.register({
+          id: entry.surfaceId,
+          title: entry.entry.label,
+          component: page,
+        }),
+        ctx.slot({
+          slot: entry.entry.slot,
+          order: entry.order,
+          key: entry.surfaceId,
+          component: trigger,
+        }),
+      ];
+    });
+  }
+
+  const stopEntrySync = watch(
+    () => packageIframeEntriesV1(web.value.packageUi),
+    (entries) => syncPackageEntries(entries),
+    { deep: true },
+  );
+
+  /*
+   * The canvas follows the Turn.
+   *
+   * A Turn that creates, publishes, reverts, or deletes an Applet changes what
+   * the canvas should show, and the durable answer is only readable once the
+   * Turn has settled — so the moment `activeRunId` clears, the list and the
+   * focus are read back. While a Turn is running with an Applet focused, the
+   * source is re-read on a cadence so the code view shows files as the Bot
+   * writes them; the read is the Workspace store and wakes nothing.
+   */
+  const APPLET_SOURCE_FOLLOW_MS = 2_000;
+  let sourceFollow: ReturnType<typeof setInterval> | undefined;
+  const stopSourceFollow = (): void => {
+    if (sourceFollow !== undefined) clearInterval(sourceFollow);
+    sourceFollow = undefined;
+  };
+  const stopRunFollow = watch(
+    () => web.value.activeRunId,
+    (runId, previous) => {
+      stopSourceFollow();
+      if (!appletsAvailableV1(web.value.packageUi)) return;
+      if (runId) {
+        if (!web.value.focusedAppletId) return;
+        sourceFollow = setInterval(() => {
+          if (!web.value.focusedAppletId || !web.value.activeRunId) {
+            stopSourceFollow();
+            return;
+          }
+          void web.value.refreshAppletCanvas();
+        }, APPLET_SOURCE_FOLLOW_MS);
+        return;
+      }
+      if (!previous) return;
+      void (async () => {
+        await web.value.loadApplets();
+        await web.value.loadFocusedApplet();
+      })();
+    },
+  );
+
   return [
     ctx.provide(clientSurfaceRegistryKey, surfaces),
     // The shared client projection is updated by the contracts lane. This cast
@@ -2240,6 +2533,10 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       component: PackageIframeSettings,
     }),
     () => {
+      stopEntrySync();
+      stopRunFollow();
+      stopSourceFollow();
+      for (const dispose of entryDisposers.splice(0).toReversed()) dispose();
       activeRequest?.abort();
       admissionObserver?.abort();
       runObserver?.abort();
@@ -2259,3 +2556,13 @@ function replaceMessage(
 }
 
 export default shellClientPlugin;
+
+/**
+ * The manifest's `client` entry, resolved by specifier. The application looks
+ * this descriptor up in its Contribution table; it never branches on which
+ * Package it belongs to.
+ */
+export const clientContribution = defineClientContribution<ClientPlugin>({
+  specifier: "@frockbot/plugin-shell/client",
+  plugin: shellClientPlugin,
+});

package/src/client/package-iframe-entries.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  PackageIframeCatalogV1,
+  PackageIframeContributionViewV1,
+} from "@frockbot/kernel-contracts";
+import {
+  packageIframeEntriesV1,
+  packageIframePagesForSlotV1,
+  packageIframeSurfaceIdV1,
+  PACKAGE_IFRAME_ENTRY_DEFAULT_ORDER_V1,
+} from "./package-iframe-entries.js";
+
+const artifact = {
+  contentHash: "a".repeat(64),
+  size: 128,
+  mediaType: "text/html" as const,
+  bundlerVersion: "frockbot-inline-html@1",
+};
+
+function contribution(
+  packageId: string,
+  entryOrder: number | undefined,
+  pageId = "list",
+): PackageIframeContributionViewV1 {
+  return {
+    packageId,
+    displayName: packageId,
+    provenance: "Bot-authored",
+    pages: [
+      {
+        id: pageId,
+        artifact,
+        mounts: [{ slot: `frockbot.surface:${pageId}` }],
+      },
+      { id: "canvas", artifact, mounts: [{ slot: "frockbot.right-panel" }] },
+    ],
+    entries: [
+      {
+        id: "open",
+        slot: "frockbot.sidebar-actions",
+        ...(entryOrder === undefined ? {} : { order: entryOrder }),
+        label: packageId,
+        icon: "applets",
+        opens: { kind: "surface", page: pageId },
+      },
+    ],
+    declaredTools: ["applet_focus"],
+  };
+}
+
+function catalog(
+  contributions: PackageIframeContributionViewV1[],
+): PackageIframeCatalogV1 {
+  return {
+    schemaVersion: 1,
+    botId: "bot-1",
+    generationId: "generation-1",
+    artifactOrigin: "https://ui.example.com",
+    contributions,
+  };
+}
+
+describe("declarative Package entries", () => {
+  test("orders entries by their declared order, above Connectors at 10", () => {
+    const entries = packageIframeEntriesV1(
+      catalog([
+        contribution("later", 20, "later"),
+        contribution("applets", 5),
+        contribution("middle", 8, "middle"),
+      ]),
+    );
+    expect(entries.map((entry) => entry.contribution.packageId)).toEqual([
+      "applets",
+      "middle",
+      "later",
+    ]);
+    // The Applets entry sits above the Connectors trigger, which registers at
+    // order 10 in the same slot.
+    expect(entries[0]!.order).toBe(5);
+    expect(entries[0]!.order).toBeLessThan(10);
+    expect(entries[2]!.order).toBeGreaterThan(10);
+  });
+
+  test("an entry with no order takes the default and ties break on Package id", () => {
+    const entries = packageIframeEntriesV1(
+      catalog([
+        contribution("zulu", undefined, "zulu"),
+        contribution("alpha", undefined, "alpha"),
+      ]),
+    );
+    expect(entries.map((entry) => entry.contribution.packageId)).toEqual([
+      "alpha",
+      "zulu",
+    ]);
+    expect(entries[0]!.order).toBe(PACKAGE_IFRAME_ENTRY_DEFAULT_ORDER_V1);
+  });
+
+  test("an entry names the page it opens and the surface that hosts it", () => {
+    const [entry] = packageIframeEntriesV1(
+      catalog([contribution("applets", 5)]),
+    );
+    expect(entry!.page.id).toBe("list");
+    expect(entry!.slot).toBe("frockbot.surface:list");
+    expect(entry!.surfaceId).toBe(packageIframeSurfaceIdV1("applets", "list"));
+  });
+
+  test("no catalog is no entries rather than a failure", () => {
+    expect(packageIframeEntriesV1(undefined)).toEqual([]);
+  });
+
+  test("the right-panel slot resolves the page the canvas hosts", () => {
+    const pages = packageIframePagesForSlotV1(
+      catalog([contribution("applets", 5)]),
+      "frockbot.right-panel",
+    );
+    expect(pages).toHaveLength(1);
+    expect(pages[0]!.page.id).toBe("canvas");
+    expect(
+      packageIframePagesForSlotV1(undefined, "frockbot.right-panel"),
+    ).toEqual([]);
+  });
+});

package/src/client/package-iframe-entries.ts

@@ -0,0 +1,112 @@
+/**
+ * Declarative Package entries.
+ *
+ * An entry is manifest data — an id, a label, an icon name, and the page it
+ * opens — so a Package puts a control in the shell's sidebar without shipping
+ * a line of JavaScript into the app origin. This module turns the catalog into
+ * the ordered list the shell registers, and nothing here executes Package
+ * code.
+ */
+import type {
+  PackageIframeCatalogV1,
+  PackageIframeContributionViewV1,
+  PackageIframeEntryViewV1,
+  PackageIframePageViewV1,
+} from "@frockbot/kernel-contracts";
+
+export interface PackageIframeEntryV1 {
+  contribution: PackageIframeContributionViewV1;
+  entry: PackageIframeEntryViewV1;
+  page: PackageIframePageViewV1;
+  /** The slot the page is mounted in when the entry opens it. */
+  slot: string;
+  /** The shell surface id this entry opens. Stable for one Package page. */
+  surfaceId: string;
+  /** Where the entry sits among the slot's other fillers. */
+  order: number;
+}
+
+/** The order a Package entry takes when its manifest names none. */
+export const PACKAGE_IFRAME_ENTRY_DEFAULT_ORDER_V1 = 50;
+
+export function packageIframeSurfaceIdV1(
+  packageId: string,
+  pageId: string,
+): string {
+  return `package-page:${packageId}:${pageId}`;
+}
+
+export function packageIframePageSlotV1(pageId: string): string {
+  return `frockbot.surface:${pageId}`;
+}
+
+/**
+ * Every entry the Bot's active Composition declares, in the order the sidebar
+ * draws them. Ties break on Package id so two Packages asking for the same
+ * order draw in a stable sequence rather than in catalog order.
+ */
+export function packageIframeEntriesV1(
+  catalog: PackageIframeCatalogV1 | undefined,
+): PackageIframeEntryV1[] {
+  return (catalog?.contributions ?? [])
+    .flatMap((contribution) =>
+      contribution.entries.flatMap((entry) => {
+        const page = contribution.pages.find(
+          (candidate) => candidate.id === entry.opens.page,
+        );
+        // The catalog decoder already refuses an entry whose page does not
+        // mount its own surface slot; this keeps the projection total anyway,
+        // because a shell that renders half an entry is worse than one that
+        // renders none.
+        if (!page) return [];
+        return [
+          {
+            contribution,
+            entry,
+            page,
+            slot: packageIframePageSlotV1(page.id),
+            surfaceId: packageIframeSurfaceIdV1(
+              contribution.packageId,
+              page.id,
+            ),
+            order: entry.order ?? PACKAGE_IFRAME_ENTRY_DEFAULT_ORDER_V1,
+          },
+        ];
+      }),
+    )
+    .toSorted(
+      (left, right) =>
+        left.order - right.order ||
+        left.contribution.packageId.localeCompare(
+          right.contribution.packageId,
+        ) ||
+        left.entry.id.localeCompare(right.entry.id),
+    );
+}
+
+/**
+ * The pages mounted in one slot, in mount order. The right panel and the
+ * settings screen both read their pages this way.
+ */
+export function packageIframePagesForSlotV1(
+  catalog: PackageIframeCatalogV1 | undefined,
+  slot: string,
+): Array<{
+  contribution: PackageIframeContributionViewV1;
+  page: PackageIframePageViewV1;
+  order: number;
+}> {
+  return (catalog?.contributions ?? [])
+    .flatMap((contribution) =>
+      contribution.pages.flatMap((page) =>
+        page.mounts
+          .filter((mount) => mount.slot === slot)
+          .map((mount) => ({ contribution, page, order: mount.order ?? 0 })),
+      ),
+    )
+    .toSorted(
+      (left, right) =>
+        left.order - right.order ||
+        left.contribution.packageId.localeCompare(right.contribution.packageId),
+    );
+}

package/src/client/package-iframe-host-message.test.ts

@@ -1,12 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import type { PackageIframeHostMessageV1 } from "@frockbot/kernel-contracts";
+import type { PackageIframeHostMessageV2 } from "@frockbot/kernel-contracts";
 import { postPackageIframeHostMessage } from "./package-iframe-host-message.js";
 
 describe("Package iframe host messages", () => {
   test("posts unchanged state once and posts changed state again", () => {
-    const posted: PackageIframeHostMessageV1[] = [];
+    const posted: PackageIframeHostMessageV2[] = [];
     const target = {
-      postMessage(message: PackageIframeHostMessageV1): void {
+      postMessage(message: PackageIframeHostMessageV2): void {
         posted.push(message);
       },
     } as Pick<Window, "postMessage">;

package/src/client/package-iframe-host-message.ts

@@ -1,10 +1,10 @@
-import type { PackageIframeHostMessageV1 } from "@frockbot/kernel-contracts";
+import type { PackageIframeHostMessageV2 } from "@frockbot/kernel-contracts";
 
 type MessageTarget = Pick<Window, "postMessage">;
 
 export function postPackageIframeHostMessage(
   target: MessageTarget,
-  message: PackageIframeHostMessageV1,
+  message: PackageIframeHostMessageV2,
   lastStateWireByName: Map<string, string>,
 ): void {
   const wire = JSON.stringify(message);
@@ -20,7 +20,7 @@ export function postPackageIframeHostMessage(
 
   // Vue settings values may be reactive proxies, which structured clone
   // rejects. JSON is also the bridge's declared value domain.
-  target.postMessage(JSON.parse(wire) as PackageIframeHostMessageV1, "*");
+  target.postMessage(JSON.parse(wire) as PackageIframeHostMessageV2, "*");
   if (message.type === "state") {
     lastStateWireByName.set(message.name, wire);
   }