@frockbot/plugin-shell 0.3.1 → 0.3.3

package/src/client/applets-client.ts

@@ -0,0 +1,139 @@
+/**
+ * The client half of the Applet routes.
+ *
+ * The backend is the authority for every one of these reads; this module is
+ * only the typed seam between the hosted transport and the shell's projection,
+ * so a route that is absent from a deployment reads as "no Applets" rather
+ * than as an error over the User's conversation. Every response crosses a
+ * strict decoder before it reaches the shell.
+ */
+import {
+  decodeAppletBuildViewV1,
+  decodeAppletFocusViewV1,
+  decodeAppletListViewV1,
+  decodeAppletSourceViewV1,
+  decodeAppletUiViewV1,
+  decodeAppletViewerTokenV1,
+  type AppletBuildViewV1,
+  type AppletSourceViewV1,
+  type AppletSummaryV1,
+  type AppletUiViewV1,
+  type AppletViewerTokenV1,
+} from "@frockbot/kernel-contracts";
+
+/** Exactly what the shell's hosted transport offers, and nothing more. */
+export type AppletsHostedRequest = (
+  path: string,
+  method?: "GET" | "POST",
+  body?: string,
+) => Promise<unknown>;
+
+const applet = (appletId: string) => encodeURIComponent(appletId);
+
+export async function readAppletList(
+  request: AppletsHostedRequest,
+): Promise<AppletSummaryV1[]> {
+  return decodeAppletListViewV1(await request("/api/applets")).applets;
+}
+
+export async function readAppletViewerToken(
+  request: AppletsHostedRequest,
+  appletId: string,
+): Promise<AppletViewerTokenV1> {
+  return decodeAppletViewerTokenV1(
+    await request(`/api/applets/${applet(appletId)}/token`),
+  );
+}
+
+export async function readAppletUi(
+  request: AppletsHostedRequest,
+  appletId: string,
+): Promise<AppletUiViewV1> {
+  return decodeAppletUiViewV1(
+    await request(`/api/applets/${applet(appletId)}/ui`),
+  );
+}
+
+/*
+ * The canvas's two Workspace-backed reads are Bot-scoped in the URL and
+ * User-scoped in what they answer: the Applets root belongs to the User, and
+ * the Bot in the path only names the Durable Object that holds the Workspace
+ * binding. Reading them wakes no Computer.
+ */
+export async function readAppletSource(
+  request: AppletsHostedRequest,
+  botId: string,
+  appletId: string,
+): Promise<AppletSourceViewV1> {
+  return decodeAppletSourceViewV1(
+    await request(
+      `/api/bots/${encodeURIComponent(botId)}/applets/${applet(appletId)}/source`,
+    ),
+  );
+}
+
+export async function readAppletBuild(
+  request: AppletsHostedRequest,
+  botId: string,
+  appletId: string,
+): Promise<AppletBuildViewV1> {
+  return decodeAppletBuildViewV1(
+    await request(
+      `/api/bots/${encodeURIComponent(botId)}/applets/${applet(appletId)}/build`,
+    ),
+  );
+}
+
+export async function readFocusedAppletId(
+  request: AppletsHostedRequest,
+  botId: string,
+): Promise<string | null> {
+  return decodeAppletFocusViewV1(
+    await request(`/api/bots/${encodeURIComponent(botId)}/applets/focus`),
+  ).appletId;
+}
+
+/**
+ * Records the Session's focused Applet and returns what the backend recorded,
+ * never what the click asked for: a focus the backend refused reads back as
+ * the focus it kept.
+ */
+export async function writeFocusedAppletId(
+  request: AppletsHostedRequest,
+  botId: string,
+  appletId: string | null,
+): Promise<string | null> {
+  return decodeAppletFocusViewV1(
+    await request(
+      `/api/bots/${encodeURIComponent(botId)}/applets/focus`,
+      "POST",
+      JSON.stringify({ schemaVersion: 1, appletId }),
+    ),
+  ).appletId;
+}
+
+/**
+ * The file the canvas shows while a Bot is writing an Applet: the one that
+ * changed most recently, falling back to the first path in sorted order so a
+ * store with no timestamps still opens on something.
+ */
+export function mostRecentlyChangedFileV1(
+  source: AppletSourceViewV1 | undefined,
+): string | undefined {
+  if (!source || source.files.length === 0) return undefined;
+  // A tie on time — a fresh scaffold, one sync — opens on the file a Bot edits
+  // first, not on the README the alphabet would pick.
+  const preferred = ["server.ts", "ui.tsx"];
+  const ordered = source.files.toSorted((left, right) => {
+    const leftAt = left.changedAt ?? "";
+    const rightAt = right.changedAt ?? "";
+    if (leftAt !== rightAt) return rightAt.localeCompare(leftAt);
+    const leftRank = preferred.indexOf(left.path);
+    const rightRank = preferred.indexOf(right.path);
+    const rank = (value: number) => (value < 0 ? preferred.length : value);
+    return (
+      rank(leftRank) - rank(rightRank) || left.path.localeCompare(right.path)
+    );
+  });
+  return ordered[0]?.path;
+}

package/src/client/applets-state.ts

@@ -0,0 +1,64 @@
+/**
+ * The `applets` feed a bridge v2 page receives.
+ *
+ * This is a projection of what the shell has already read, never a second
+ * source of truth: the backend is the authority for the list, the focus, and
+ * the viewer credential, and a page that is handed a stale generation simply
+ * reconnects when the next feed arrives.
+ */
+import {
+  PACKAGE_IFRAME_FOCUS_TOOL_V2,
+  type PackageIframeAppletsStateV2,
+  type PackageIframeCatalogV1,
+  type AppletSummaryV1,
+} from "@frockbot/kernel-contracts";
+import type { FrockBotWebData } from "../shared.js";
+
+/**
+ * Whether this Bot's Composition has Applets in it at all.
+ *
+ * Derived from manifest facts — a Package declaring the Applet focus tool —
+ * never from a Package id. A deployment or a User without the Applets Package
+ * has no Applet routes, and the shell must not ask for them: an absent
+ * capability is silence, not a failed request.
+ */
+export function appletsAvailableV1(
+  catalog: PackageIframeCatalogV1 | undefined,
+): boolean {
+  return (catalog?.contributions ?? []).some((contribution) =>
+    contribution.declaredTools.includes(PACKAGE_IFRAME_FOCUS_TOOL_V2),
+  );
+}
+
+export function focusedAppletSummaryV1(
+  web: Pick<FrockBotWebData, "applets" | "focusedAppletId">,
+): AppletSummaryV1 | null {
+  const appletId = web.focusedAppletId;
+  if (!appletId) return null;
+  return web.applets.find((applet) => applet.appletId === appletId) ?? null;
+}
+
+export function appletsBridgeStateV2(
+  web: Pick<
+    FrockBotWebData,
+    "applets" | "focusedAppletId" | "appletViewer" | "appletBuild"
+  >,
+): PackageIframeAppletsStateV2 {
+  const viewer = web.appletViewer;
+  return {
+    focused: focusedAppletSummaryV1(web),
+    list: web.applets,
+    viewer:
+      viewer && viewer.appletId === web.focusedAppletId
+        ? {
+            token: viewer.token,
+            socketUrl: viewer.socketUrl,
+            uiUrl: viewer.uiUrl,
+            generationId: viewer.generationId,
+          }
+        : null,
+    // The source stays out of the feed: the shell draws the code view itself,
+    // and a source tree would overflow the bridge's 64 KB message bound.
+    ...(web.appletBuild === undefined ? {} : { build: web.appletBuild }),
+  };
+}

package/src/client/index.test.ts

@@ -408,13 +408,19 @@ describe("Bot selection", () => {
       packageId: "weather-page",
       displayName: "Sydney Weather",
       provenance: "Bot-authored" as const,
-      artifact: {
-        contentHash: "a".repeat(64),
-        size: 1,
-        mediaType: "text/html" as const,
-        bundlerVersion: "frockbot-inline-html@1",
-      },
-      mounts: [{ slot: "frockbot.bot-settings-sections", order: 20 }],
+      pages: [
+        {
+          id: "main",
+          artifact: {
+            contentHash: "a".repeat(64),
+            size: 1,
+            mediaType: "text/html" as const,
+            bundlerVersion: "frockbot-inline-html@1",
+          },
+          mounts: [{ slot: "frockbot.bot-settings-sections", order: 20 }],
+        },
+      ],
+      entries: [],
       declaredTools: ["weather_lookup"],
     };
     const requests: Array<{
@@ -968,6 +974,52 @@ describe("Bot selection", () => {
 });
 
 describe("detached Turn projection", () => {
+  test("shows a dynamic call as its namespace/tool with inner arguments", () => {
+    const messages: Parameters<typeof projectCompletedRuns>[0] = [];
+    projectCompletedRuns(
+      messages,
+      [],
+      [
+        {
+          runId: "run-dynamic",
+          input: "Find open issues",
+          status: "completed",
+          responseText: "Done",
+          events: [
+            {
+              type: "tool/call",
+              call: {
+                id: "tool-1",
+                name: "call_dynamic_tool",
+                input: {
+                  namespace: "user-Github--acme",
+                  toolName: "search_issues",
+                  argumentsJson: '{"query":"is:open"}',
+                },
+              },
+            },
+            {
+              type: "tool/result",
+              callId: "tool-1",
+              content: "[]",
+              isError: false,
+            },
+          ],
+        },
+      ],
+    );
+
+    expect(messages[1]?.tools).toEqual([
+      {
+        id: "tool-1",
+        name: "user-Github--acme/search_issues",
+        input: { query: "is:open" },
+        status: "completed",
+        text: "[]",
+      },
+    ]);
+  });
+
   test("projects a completed run before it can be acknowledged", () => {
     const messages: Parameters<typeof projectCompletedRuns>[0] = [];
     const projected = projectCompletedRuns(
@@ -2645,3 +2697,165 @@ describe("Connection operation reconciliation", () => {
     expect(commandIds[1]).not.toBe(commandIds[0]);
   });
 });
+
+describe("a message sent while a Turn is running", () => {
+  test("is accepted, and carries the intent to supersede what is running", async () => {
+    Object.defineProperty(globalThis, "window", {
+      configurable: true,
+      value: {
+        location: { href: "https://app.example/?bot=primary" },
+        history: { replaceState: () => undefined },
+      },
+    });
+    let provided: Ref<FrockBotWebData> | undefined;
+    const sent: {
+      text: string;
+      supersedes?: { runId?: string };
+    }[] = [];
+    let releaseFirst!: () => void;
+    const firstTurn = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    await shellClientPlugin({
+      transport: {
+        turn: async (_botId, text, _signal, commandId, _skills, supersedes) => {
+          sent.push({ text, ...(supersedes ? { supersedes } : {}) });
+          if (sent.length === 1) await firstTurn;
+          return { runId: commandId, text: `answer to ${text}`, events: [] };
+        },
+        readConfiguration: () =>
+          Promise.resolve(initializeBotSettingsV1("primary")),
+        listRuns: () => Promise.resolve([]),
+        listNotifications: () => Promise.resolve([]),
+      },
+      slot: () => () => {},
+      inject: () => {
+        throw new Error("unexpected client provider injection");
+      },
+      provide: (_key, value) => {
+        provided = value as Ref<FrockBotWebData>;
+        return () => {};
+      },
+    });
+    if (!provided) throw new Error("shell data was not provided");
+    provided.value.activeBotId = "primary";
+    provided.value.composerContext = "primary";
+
+    const first = provided.value.sendPrompt("first");
+    await Promise.resolve();
+    const runningRunId = provided.value.activeRunId;
+    expect(runningRunId).toBeString();
+
+    // The composer is open while a Turn runs, and what it sends replaces it.
+    const second = provided.value.sendPrompt("second");
+    releaseFirst();
+    expect(await first).toMatchObject({ accepted: true });
+    expect(await second).toMatchObject({ accepted: true });
+
+    expect(sent.map((entry) => entry.text).sort()).toEqual(["first", "second"]);
+    // Every send carries the intent. The first had observed no run, so it
+    // carries no provenance — and that is exactly the send that used to be
+    // refused when a person typed faster than the client could observe the
+    // Turn it had just started.
+    expect(sent.find((entry) => entry.text === "first")?.supersedes).toEqual(
+      {},
+    );
+    expect(sent.find((entry) => entry.text === "second")?.supersedes).toEqual({
+      runId: runningRunId!,
+    });
+  });
+
+  test("greys the queued Turn, and un-greys it when it starts", () => {
+    const state: Pick<
+      FrockBotWebData,
+      "messages" | "activeRunId" | "runningRunId" | "activeRun"
+    > = { messages: [] };
+
+    projectDurableRuns(
+      state,
+      [],
+      [
+        { runId: "run-1", input: "first", events: [], status: "running" },
+        {
+          runId: "run-2",
+          input: "second",
+          events: [],
+          status: "running",
+          queued: true,
+        },
+      ],
+    );
+
+    // Ordinary messages; the waiting one is simply held back.
+    expect(state.messages.map((message) => message.pending)).toEqual([
+      undefined,
+      undefined,
+      true,
+      true,
+    ]);
+    // A new message supersedes the newest unsettled Turn; Stop cancels the one
+    // that is actually executing.
+    expect(state.activeRunId).toBe("run-2");
+    expect(state.runningRunId).toBe("run-1");
+
+    projectDurableRuns(
+      state,
+      [],
+      [
+        {
+          runId: "run-1",
+          input: "first",
+          events: [],
+          status: "superseded",
+          failure: "Interrupted by your next message.",
+        },
+        { runId: "run-2", input: "second", events: [], status: "running" },
+      ],
+    );
+
+    expect(state.messages.every((message) => !message.pending)).toBe(true);
+    expect(state.activeRunId).toBe("run-2");
+    expect(state.runningRunId).toBe("run-2");
+    // The superseded Turn keeps the quiet treatment a stopped one gets.
+    expect(state.messages[1]).toMatchObject({
+      status: "aborted",
+      text: "Interrupted by your next message.",
+    });
+  });
+
+  test("a reload reconstructs the greyed state from durable runs alone", () => {
+    const reloaded: Pick<
+      FrockBotWebData,
+      "messages" | "activeRunId" | "runningRunId" | "activeRun"
+    > = { messages: [] };
+
+    projectDurableRuns(
+      reloaded,
+      [],
+      [
+        {
+          runId: "run-1",
+          input: "first",
+          events: [],
+          status: "superseded",
+          failure: "Interrupted by your next message.",
+        },
+        {
+          runId: "run-2",
+          input: "second",
+          events: [],
+          status: "running",
+          queued: true,
+        },
+      ],
+    );
+
+    expect(reloaded.messages[2]).toMatchObject({
+      role: "user",
+      text: "second",
+      pending: true,
+    });
+    expect(reloaded.runningRunId).toBeUndefined();
+    expect(reloaded.activeRunId).toBe("run-2");
+  });
+});