@frockbot/plugin-shell 0.3.22 → 0.3.24

package/src/client/deployment.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from "bun:test";
+import {
+  DEPLOYMENT_RELOAD_INTERVAL_MS_V1,
+  DEPLOYMENT_RELOAD_MARKER_V1,
+  DEPLOYMENT_UPDATED_MESSAGE_V1,
+  deploymentFollowV1,
+  deploymentStaleV1,
+  readDeploymentReloadV1,
+  writeDeploymentReloadV1,
+  type DeploymentFollowInputV1,
+  type DeploymentReloadStoreV1,
+} from "./deployment.ts";
+
+const idle: DeploymentFollowInputV1 = {
+  stale: true,
+  turnRunning: false,
+  draft: "",
+  overlayOpen: false,
+  listening: false,
+  holds: 0,
+  now: 10_000_000,
+};
+
+describe("deploymentStaleV1", () => {
+  test("a page whose application still answers is current", () => {
+    expect(deploymentStaleV1("hash-a", "hash-a")).toBe(false);
+  });
+
+  test("a page answered by another application is behind", () => {
+    expect(deploymentStaleV1("hash-a", "hash-b")).toBe(true);
+  });
+
+  test("a document that names no application is never behind", () => {
+    // The vite development document stamps no application hash, and local
+    // development reloads itself.
+    expect(deploymentStaleV1(undefined, "hash-b")).toBe(false);
+  });
+
+  test("an answer that names no application says nothing", () => {
+    expect(deploymentStaleV1("hash-a", undefined)).toBe(false);
+  });
+});
+
+describe("deploymentFollowV1", () => {
+  test("a current page is left alone", () => {
+    expect(deploymentFollowV1({ ...idle, stale: false })).toBe("none");
+  });
+
+  test("an idle page follows the release by itself", () => {
+    expect(deploymentFollowV1(idle)).toBe("reload");
+  });
+
+  test("a running Turn is offered the reload rather than given it", () => {
+    expect(deploymentFollowV1({ ...idle, turnRunning: true })).toBe("offer");
+  });
+
+  test("a typed message is not thrown away", () => {
+    expect(deploymentFollowV1({ ...idle, draft: "half a thought" })).toBe(
+      "offer",
+    );
+  });
+
+  test("whitespace is not a message", () => {
+    expect(deploymentFollowV1({ ...idle, draft: "   \n " })).toBe("reload");
+  });
+
+  test("an open overlay is not closed underneath the User", () => {
+    expect(deploymentFollowV1({ ...idle, overlayOpen: true })).toBe("offer");
+  });
+
+  test("a live capture is not cut off", () => {
+    expect(deploymentFollowV1({ ...idle, listening: true })).toBe("offer");
+  });
+
+  test("live work another Package holds is respected", () => {
+    expect(deploymentFollowV1({ ...idle, holds: 1 })).toBe("offer");
+  });
+
+  test("a tab that just reloaded offers instead of looping", () => {
+    expect(
+      deploymentFollowV1({
+        ...idle,
+        reloadedAt: idle.now - (DEPLOYMENT_RELOAD_INTERVAL_MS_V1 - 1),
+      }),
+    ).toBe("offer");
+  });
+
+  test("a tab may reload again once the guard has passed", () => {
+    expect(
+      deploymentFollowV1({
+        ...idle,
+        reloadedAt: idle.now - DEPLOYMENT_RELOAD_INTERVAL_MS_V1,
+      }),
+    ).toBe("reload");
+  });
+});
+
+function memoryStore(initial?: string): DeploymentReloadStoreV1 & {
+  written: string[];
+} {
+  const values = new Map<string, string>();
+  if (initial !== undefined) values.set(DEPLOYMENT_RELOAD_MARKER_V1, initial);
+  const written: string[] = [];
+  return {
+    written,
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => {
+      values.set(key, value);
+      written.push(value);
+    },
+  };
+}
+
+describe("the reload marker", () => {
+  test("round-trips through storage", () => {
+    const store = memoryStore();
+    writeDeploymentReloadV1(store, 1234);
+    expect(readDeploymentReloadV1(store)).toBe(1234);
+  });
+
+  test("a tab that has never reloaded reads as never", () => {
+    expect(readDeploymentReloadV1(memoryStore())).toBeUndefined();
+  });
+
+  test("a value that is not a time reads as never", () => {
+    expect(readDeploymentReloadV1(memoryStore("later"))).toBeUndefined();
+  });
+
+  test("no storage at all reads as never and swallows the write", () => {
+    expect(readDeploymentReloadV1(undefined)).toBeUndefined();
+    expect(() => writeDeploymentReloadV1(undefined, 1)).not.toThrow();
+  });
+
+  test("storage that throws does not stop the page following a release", () => {
+    const broken: DeploymentReloadStoreV1 = {
+      getItem: () => {
+        throw new Error("storage is unavailable");
+      },
+      setItem: () => {
+        throw new Error("storage is full");
+      },
+    };
+    expect(readDeploymentReloadV1(broken)).toBeUndefined();
+    expect(() => writeDeploymentReloadV1(broken, 1)).not.toThrow();
+  });
+});
+
+test("the bar says what happened in plain words", () => {
+  expect(DEPLOYMENT_UPDATED_MESSAGE_V1).toBe(
+    "FrockBot has updated. Reload when you're ready.",
+  );
+});

package/src/client/deployment.ts

@@ -0,0 +1,138 @@
+/**
+ * Following a release in a page that is already open.
+ *
+ * FrockBot ships several times a day and a tab stays open for days, so the
+ * ordinary case is old client code talking to a new backend. Every answer
+ * names the application it came from; when that stops matching the one this
+ * page was served, the page is behind and has to be replaced.
+ *
+ * Replacing it is destructive — a reload throws away the composer draft, the
+ * open overlay, and any live capture — so the shell only does it on its own
+ * when there is nothing to lose, and otherwise offers it and waits.
+ */
+
+/** What the shell should do about a page that is behind. */
+export type DeploymentFollowV1 = "reload" | "offer" | "none";
+
+/** The bar's whole text. Plain words: nobody needs to hear about a hash. */
+export const DEPLOYMENT_UPDATED_MESSAGE_V1 =
+  "FrockBot has updated. Reload when you're ready.";
+
+/** The bar's button. */
+export const DEPLOYMENT_RELOAD_LABEL_V1 = "Reload";
+
+/**
+ * Where the last automatic reload is remembered. Session storage, so it is
+ * per-tab and goes away with the tab, which is the same lifetime as the
+ * problem it guards.
+ */
+export const DEPLOYMENT_RELOAD_MARKER_V1 = "frockbot.deployment-reloaded-v1";
+
+/**
+ * The shortest gap between two automatic reloads of one tab.
+ *
+ * The guard matters because a reload is not guaranteed to fix the mismatch: a
+ * cached bundle, or a deploy still rolling out, can serve the old client
+ * again. Without this the page would reload forever. One a minute at worst
+ * leaves the bar to say the rest.
+ */
+export const DEPLOYMENT_RELOAD_INTERVAL_MS_V1 = 60_000;
+
+/** Whether the answering application is a different one from the served one. */
+export function deploymentStaleV1(
+  served: string | undefined,
+  answered: string | undefined,
+): boolean {
+  if (!served || !answered) return false;
+  return served !== answered;
+}
+
+export interface DeploymentFollowInputV1 {
+  /** The answering application differs from the served one. */
+  stale: boolean;
+  /** A Turn is executing for the open Bot. */
+  turnRunning: boolean;
+  /** What is typed in the composer and not yet sent. */
+  draft: string;
+  /** A surface is floating over the workspace. */
+  overlayOpen: boolean;
+  /** A microphone is open, dictating or in a Voice session. */
+  listening: boolean;
+  /** Live work another Package holds, which a reload would throw away. */
+  holds: number;
+  now: number;
+  /** When this tab last reloaded itself, if it has. */
+  reloadedAt?: number;
+}
+
+export function deploymentFollowV1(
+  input: DeploymentFollowInputV1,
+): DeploymentFollowV1 {
+  if (!input.stale) return "none";
+  const busy =
+    input.turnRunning ||
+    input.draft.trim().length > 0 ||
+    input.overlayOpen ||
+    input.listening ||
+    input.holds > 0;
+  if (busy) return "offer";
+  if (
+    input.reloadedAt !== undefined &&
+    input.now - input.reloadedAt < DEPLOYMENT_RELOAD_INTERVAL_MS_V1
+  ) {
+    return "offer";
+  }
+  return "reload";
+}
+
+/** The narrowest slice of `sessionStorage` this needs, so a test can pass one. */
+export interface DeploymentReloadStoreV1 {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+/**
+ * When this tab last reloaded itself. A missing, unparseable, or absurd value
+ * reads as "never": storage can be unavailable or full, and a page that
+ * cannot remember should still be able to follow a release once.
+ */
+export function readDeploymentReloadV1(
+  store: DeploymentReloadStoreV1 | undefined,
+): number | undefined {
+  if (!store) return undefined;
+  let raw: string | null;
+  try {
+    raw = store.getItem(DEPLOYMENT_RELOAD_MARKER_V1);
+  } catch {
+    return undefined;
+  }
+  if (raw === null) return undefined;
+  const at = Number(raw);
+  return Number.isFinite(at) && at > 0 ? at : undefined;
+}
+
+/**
+ * This tab's session storage, or nothing where the browser refuses it. A
+ * private window and a blocked-storage setting both throw on the property
+ * itself, before any read.
+ */
+export function deploymentReloadStoreV1(): DeploymentReloadStoreV1 | undefined {
+  try {
+    return typeof window === "undefined" ? undefined : window.sessionStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeDeploymentReloadV1(
+  store: DeploymentReloadStoreV1 | undefined,
+  now: number,
+): void {
+  if (!store) return;
+  try {
+    store.setItem(DEPLOYMENT_RELOAD_MARKER_V1, String(now));
+  } catch {
+    // A tab that cannot record the reload still reloads. The guard is a
+    // safeguard against a loop, not a precondition for following a release.
+  }
+}

package/src/client/index.test.ts

@@ -328,6 +328,77 @@ describe("application manifest protocol", () => {
   });
 });
 
+describe("following a release", () => {
+  async function mountWithDeployment(servedDeployment?: string): Promise<{
+    web: Ref<FrockBotWebData>;
+    answer: (deployment: string) => void;
+  }> {
+    let provided: Ref<FrockBotWebData> | undefined;
+    let observer: ((deployment: string) => void) | undefined;
+    await shellClientPlugin({
+      transport: {
+        ...(servedDeployment ? { servedDeployment } : {}),
+        observeDeployment: (candidate) => {
+          observer = candidate;
+          return () => {
+            observer = undefined;
+          };
+        },
+        turn: () => Promise.resolve({ runId: "run", text: "", events: [] }),
+      },
+      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");
+    if (!observer) throw new Error("the deployment was not observed");
+    const answer = observer;
+    return { web: provided, answer };
+  }
+
+  test("the same application answering leaves the page alone", async () => {
+    const { web, answer } = await mountWithDeployment("hash-a");
+
+    expect(web.value.deploymentStale).toBe(false);
+    answer("hash-a");
+    expect(web.value.deploymentStale).toBe(false);
+  });
+
+  test("another application answering puts the page behind", async () => {
+    const { web, answer } = await mountWithDeployment("hash-a");
+
+    answer("hash-b");
+    expect(web.value.deploymentStale).toBe(true);
+  });
+
+  test("a document that names no application is never behind", async () => {
+    // The vite development document stamps none, and there the page reloads
+    // itself already.
+    const { web, answer } = await mountWithDeployment();
+
+    answer("hash-b");
+    expect(web.value.deploymentStale).toBe(false);
+  });
+
+  test("holds are counted, and letting go twice does not count twice", async () => {
+    const { web } = await mountWithDeployment("hash-a");
+
+    const first = web.value.holdReload();
+    const second = web.value.holdReload();
+    expect(web.value.reloadHolds).toBe(2);
+    first();
+    first();
+    expect(web.value.reloadHolds).toBe(1);
+    second();
+    expect(web.value.reloadHolds).toBe(0);
+  });
+});
+
 describe("composer hydration context", () => {
   test("hides Connection controls when the platform cannot authorize", async () => {
     let provided: Ref<FrockBotWebData> | undefined;

package/src/client/index.ts

@@ -16,6 +16,7 @@ import {
 import { clientSurfaceRegistryKey } from "@frockbot/client-core";
 import { COMPACTED_ANNOUNCEMENT_TEXT_V1 } from "../compaction.js";
 import { voiceCaptureSupportedV1 } from "./voice-microphone.js";
+import { deploymentStaleV1 } from "./deployment.js";
 import { readViewerFocusV1, shouldNotifyForBotV1 } from "../focus.js";
 // Connection mutations use the provider-neutral hosted command contract.
 import type {
@@ -1433,6 +1434,19 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     voiceAvailable:
       typeof ctx.transport.openVoiceDictation === "function" &&
       voiceCaptureSupportedV1(),
+    deploymentStale: false,
+    reloadHolds: 0,
+    holdReload: () => {
+      web.value.reloadHolds += 1;
+      let released = false;
+      return () => {
+        // Idempotent: a Package that lets go twice must not leave the count
+        // below zero, which would read as "another holder released early".
+        if (released) return;
+        released = true;
+        web.value.reloadHolds -= 1;
+      };
+    },
     activeBotId: undefined,
     composerContext: undefined,
     transcripts: {
@@ -3161,6 +3175,43 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     { immediate: true },
   );
 
+  /*
+   * Following a release in a page that is already open.
+   *
+   * Every answer names the application that produced it and the request layer
+   * reports it here, so a page whose own application has stopped answering is
+   * running code the backend has moved past. Nothing polls for this: the
+   * reads the app already makes carry the answer.
+   */
+  const stopDeploymentWatch = ctx.transport.observeDeployment?.((answered) => {
+    if (deploymentStaleV1(ctx.transport.servedDeployment, answered)) {
+      web.value.deploymentStale = true;
+    }
+  });
+  /*
+   * A tab that has been in the background for a day should not have to wait
+   * for the next scheduled read to find out. Coming back asks for the
+   * manifest the client already reads at start-up rather than adding a poll
+   * of its own, and only while the answer is still unknown.
+   */
+  const readManifest = ctx.transport.readApplicationManifest?.bind(
+    ctx.transport,
+  );
+  const followDeploymentOnReturn = () => {
+    if (document.visibilityState !== "visible") return;
+    if (web.value.deploymentStale || !readManifest) return;
+    void readManifest().catch(() => {
+      // A read that failed says nothing about the deployment. The next one,
+      // or the next answer of any kind, will.
+    });
+  };
+  // The Plugin is also installed without a document — the unit tests drive it
+  // headless — and there a tab can neither be hidden nor come back.
+  const inDocument = typeof document !== "undefined";
+  if (inDocument) {
+    document.addEventListener("visibilitychange", followDeploymentOnReturn);
+  }
+
   return [
     ctx.provide(clientSurfaceRegistryKey, surfaces),
     // The shared client projection is updated by the contracts lane. This cast
@@ -3177,6 +3228,13 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       component: PackageIframeSettings,
     }),
     () => {
+      stopDeploymentWatch?.();
+      if (inDocument) {
+        document.removeEventListener(
+          "visibilitychange",
+          followDeploymentOnReturn,
+        );
+      }
       stopEntrySync();
       stopRunFollow();
       stopRunChannelWatch();

package/src/client/styles.css

@@ -644,6 +644,45 @@
   cursor: pointer;
 }
 
+/*
+ * The release bar. It sits where the error banner sits and only one shows at
+ * a time, so it borrows that geometry and none of its colour: nothing here is
+ * wrong, there is just newer code waiting.
+ */
+.update-banner {
+  position: absolute;
+  right: 20px;
+  bottom: 84px;
+  left: 20px;
+  z-index: 5;
+  display: flex;
+  min-height: 38px;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 7px 12px;
+  border: 1px solid var(--frock-border);
+  border-radius: 12px;
+  color: var(--frock-text);
+  background: var(--frock-surface-raised);
+  box-shadow: var(--frock-shadow-card);
+  font-size: var(--frock-text-sm);
+}
+
+.update-banner button {
+  flex: 0 0 auto;
+  padding: 5px 10px;
+  border-radius: 999px;
+  color: var(--frock-on-accent);
+  background: var(--frock-action-primary);
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.update-banner button:hover {
+  background: var(--frock-action-primary-hover);
+}
+
 .banner-enter-active,
 .banner-leave-active {
   transition:
@@ -732,25 +771,73 @@
   left: 0;
   display: inline-flex;
   max-width: 100%;
-  height: var(--frock-control-md);
+  min-height: var(--frock-control-md);
   align-items: center;
-  gap: 6px;
-  padding: 0 10px;
+  gap: 8px;
+  padding: 6px 10px;
   border: 1px solid var(--frock-border-strong);
-  border-radius: 999px;
+  border-radius: var(--frock-radius-card);
   color: var(--frock-text);
   background: var(--frock-surface-raised);
   box-shadow: var(--frock-shadow-control);
   font-size: var(--frock-text-sm);
+  text-align: left;
   cursor: pointer;
 }
 
+.applet-chip-text {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+}
+
 .applet-chip-name {
   overflow: hidden;
   white-space: nowrap;
   text-overflow: ellipsis;
 }
 
+/*
+ * What the Bot is doing to it, so the phone says the same thing the canvas
+ * beside a wide conversation says without opening anything.
+ */
+.applet-chip-status {
+  display: flex;
+  overflow: hidden;
+  align-items: center;
+  gap: 6px;
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-xs);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.applet-chip-dot {
+  width: 6px;
+  height: 6px;
+  flex: 0 0 auto;
+  border-radius: 999px;
+  background: var(--frock-action-primary);
+  animation: applet-chip-pulse 1.4s ease-in-out infinite;
+}
+
+@keyframes applet-chip-pulse {
+  0%,
+  100% {
+    opacity: 0.35;
+  }
+
+  50% {
+    opacity: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .applet-chip-dot {
+    animation: none;
+  }
+}
+
 .applet-chip-action {
   flex: 0 0 auto;
   color: var(--frock-action-primary);

package/src/run-protocol.ts

@@ -45,6 +45,16 @@ const MAX_SESSION_ID_LENGTH = 320;
 const MAX_TASK_DESCRIPTION_BYTES = 800;
 const MAX_TASK_MODEL_BYTES = 512;
 export const CLIENT_RUN_PAGE_LIMIT = 32;
+/**
+ * How many run-index candidates one transcript page may walk past.
+ *
+ * The index is global and the transcript is one conversation, so filling a
+ * page can mean stepping over Turns of other conversations and over
+ * automation firings. Scanning is cheap — a run record, not its journal — but
+ * it is not free, so it stops at a budget and hands back a cursor rather than
+ * walking a Bot's whole history inside one request.
+ */
+export const CLIENT_RUN_SCAN_LIMIT = CLIENT_RUN_PAGE_LIMIT * 8;
 export const CLIENT_RUN_LIST_MAX_BYTES = 512_000;
 
 export type ClientRunStatusV1 =

package/src/shared.ts

@@ -269,6 +269,20 @@ export interface FrockBotWebData {
    * changes shape and nothing about it moves.
    */
   voiceAvailable: boolean;
+  /**
+   * The application answering is no longer the one this page was served, so
+   * the code running here is behind a release. FrockBot ships several times a
+   * day and a tab stays open for days, so this is ordinary rather than rare.
+   */
+  deploymentStale: boolean;
+  /**
+   * Live work a reload would throw away, held by whichever Package holds the
+   * work. Counted rather than flagged so two holders at once do not release
+   * each other. The shell reloads on its own only at zero.
+   */
+  reloadHolds: number;
+  /** Keeps the shell from reloading. Call the result to let go. */
+  holdReload(): () => void;
   activeBotId?: string;
   composerContext?: unknown;
   messages: WebChatMessage[];