@frockbot/plugin-shell 0.3.22 → 0.3.23

package/src/client/applet-progress.ts

@@ -0,0 +1,339 @@
+/**
+ * What the Bot is doing to the focused Applet, in words a person reads.
+ *
+ * Building an Applet takes minutes: the Bot scaffolds it, edits the files on
+ * the Computer, runs `applet check` and `applet build` there, and only then
+ * publishes it. Until that publish lands there is nothing to run, so the
+ * canvas beside the conversation used to say "Not published yet" for the whole
+ * of it — true, unchanging, and no help to somebody watching. This module is
+ * the missing sentence: it reads what the client already knows and returns the
+ * one line that says where the work has got to.
+ *
+ * It is a projection, never an authority. Nothing here is stored, nothing here
+ * is asked of the backend, and every input is something the thread was already
+ * drawing. When the signals say nothing specific, the answer is the honest
+ * fallback rather than an invented step.
+ */
+import type {
+  AppletBuildViewV1,
+  AppletSourceViewV1,
+  AppletSummaryV1,
+} from "@frockbot/kernel-contracts";
+import type { WebChatMessage, WebToolActivity } from "../shared.js";
+
+/**
+ * Where the work has got to.
+ *
+ * The order is the order the Bot does them in, and the projection takes the
+ * furthest one it has evidence for. `unknown` is a draft with nothing said
+ * about it yet — the Bot has been asked, and the Turn that answers has not
+ * reached the Applet.
+ */
+export type AppletProgressStageV1 =
+  | "unknown"
+  | "created"
+  | "writing"
+  | "checking"
+  | "building"
+  | "publishing"
+  | "published";
+
+/** The tail of a check or a build, so a long log never fills the panel. */
+export const APPLET_PROGRESS_OUTPUT_LINES_V1 = 12;
+export const APPLET_PROGRESS_LINE_CHARACTERS_V1 = 200;
+/** A failure is a sentence in the panel, not a wall of text. */
+export const APPLET_PROGRESS_FAILURE_CHARACTERS_V1 = 400;
+
+export interface AppletProgressV1 {
+  stage: AppletProgressStageV1;
+  /** The line the canvas and the phone both show. */
+  label: string;
+  /** True while the Turn doing this is still going. */
+  working: boolean;
+  /** True when this step finished and finished cleanly. */
+  done: boolean;
+  /** What went wrong, in the words of whatever refused. */
+  failure?: string;
+  /** The last lines the check or the build printed. */
+  output?: string[];
+}
+
+export interface AppletProgressInputV1 {
+  /** The focused Applet's directory entry, when there is one. */
+  applet?: AppletSummaryV1 | null;
+  /** The Applet's source, as the canvas already reads it. */
+  source?: AppletSourceViewV1;
+  /** The outcome the Applet authority recorded, when it has recorded one. */
+  build?: AppletBuildViewV1;
+  /** The newest Turn's tool activity, oldest first. */
+  tools?: readonly WebToolActivity[];
+  /** True while that Turn is still running. */
+  running?: boolean;
+}
+
+/**
+ * The words for each step, and for the step having finished.
+ *
+ * A check that has come back clean is worth its own sentence: "Checking the
+ * code" would keep saying a thing was happening after it stopped happening.
+ */
+const LABELS: Record<AppletProgressStageV1, { doing: string; done: string }> = {
+  // Matches the Applets list, which says "Still being built" for a draft.
+  unknown: { doing: "Still being built", done: "Still being built" },
+  created: { doing: "Just getting started", done: "Just getting started" },
+  writing: { doing: "Writing the code", done: "Writing the code" },
+  checking: { doing: "Checking the code", done: "The code checks out" },
+  building: {
+    doing: "Putting it together",
+    done: "Built and ready to go live",
+  },
+  publishing: {
+    doing: "Getting it ready to open",
+    done: "Getting it ready to open",
+  },
+  published: { doing: "Ready to use", done: "Ready to use" },
+};
+
+const ORDER: AppletProgressStageV1[] = [
+  "unknown",
+  "created",
+  "writing",
+  "checking",
+  "building",
+  "publishing",
+  "published",
+];
+
+function furthest(
+  left: AppletProgressStageV1,
+  right: AppletProgressStageV1,
+): AppletProgressStageV1 {
+  return ORDER.indexOf(right) > ORDER.indexOf(left) ? right : left;
+}
+
+/** The bare tool name, whether it arrived namespaced or native. */
+function toolName(activity: WebToolActivity): string {
+  const slash = activity.name.lastIndexOf("/");
+  return slash < 0 ? activity.name : activity.name.slice(slash + 1);
+}
+
+/**
+ * Whether this tool call is about the Applet in the canvas.
+ *
+ * A dynamic call carries its parsed arguments, so a publish of some other
+ * Applet never moves this one's line. `applet_create` names no id — it is
+ * making one — so it counts for whichever Applet the Session then focuses,
+ * which is the one it just created.
+ */
+function namesApplet(activity: WebToolActivity, appletId: string): boolean {
+  const input = activity.input;
+  if (!input || typeof input !== "object" || Array.isArray(input)) return true;
+  const named = (input as Record<string, unknown>).appletId;
+  return typeof named === "string" ? named === appletId : true;
+}
+
+function trimLine(line: string): string {
+  return line.length > APPLET_PROGRESS_LINE_CHARACTERS_V1
+    ? `${line.slice(0, APPLET_PROGRESS_LINE_CHARACTERS_V1 - 1)}…`
+    : line;
+}
+
+function tail(text: string): string[] {
+  const lines = text
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+  return lines.slice(-APPLET_PROGRESS_OUTPUT_LINES_V1).map(trimLine);
+}
+
+function sentence(text: string): string {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return "";
+  return trimmed.length > APPLET_PROGRESS_FAILURE_CHARACTERS_V1
+    ? `${trimmed.slice(0, APPLET_PROGRESS_FAILURE_CHARACTERS_V1 - 1)}…`
+    : trimmed;
+}
+
+/**
+ * Whether a shell command's output is the `applet` CLI reporting on itself.
+ *
+ * The client is never told what a `computer_exec` ran: the Turn projection
+ * carries the input of dynamic tool calls only, and `computer_exec` is a
+ * native tool. What it does carry is the result, and the CLI's output is a
+ * stated contract — `applet check:` on one line, and the three `dist/` paths a
+ * build writes — so recognising it is reading a published shape rather than
+ * guessing at a command. Anything else the Bot ran on the Computer looks like
+ * nothing here and is ignored, which is the right failure: no line rather than
+ * a wrong one.
+ */
+export function appletCommandOutputV1(
+  text: string | undefined,
+): { command: "check" | "build"; output: string[] } | undefined {
+  if (!text) return undefined;
+  if (/^applet check:/m.test(text)) {
+    return { command: "check", output: tail(text) };
+  }
+  if (/dist\/manifest\.json\b/.test(text) && /dist\/server\.js\b/.test(text)) {
+    return { command: "build", output: tail(text) };
+  }
+  return undefined;
+}
+
+/** Whether the `applet check` output the CLI printed found errors. */
+function checkFailed(text: string): boolean {
+  return /^applet check: \d+ error/m.test(text);
+}
+
+/**
+ * The one line about the focused Applet, and what sits under it.
+ *
+ * Returns `undefined` when there is no Applet in the canvas to say it about.
+ */
+export function appletProgressV1(
+  input: AppletProgressInputV1,
+): AppletProgressV1 | undefined {
+  const applet = input.applet;
+  if (!applet) return undefined;
+
+  let stage: AppletProgressStageV1 = "unknown";
+  let failure: string | undefined;
+  let output: string[] | undefined;
+  let done = false;
+
+  // The directory entry is the settled fact: a generation is current, so the
+  // Applet runs. A Turn working on it now moves the line off this again.
+  if (applet.currentGenerationId) {
+    stage = "published";
+    done = true;
+  }
+
+  // What the Applet authority recorded, where it has recorded anything. It is
+  // read before the Turn's own evidence so a running Turn wins.
+  const recorded = input.build;
+  if (recorded && recorded.status !== "unknown") {
+    stage = furthest(
+      stage,
+      recorded.command === "build" ? "building" : "checking",
+    );
+    done = recorded.status === "passed";
+    if (recorded.status === "failed") {
+      failure = sentence(recorded.summary ?? "The last check did not pass.");
+      if (recorded.diagnostics && recorded.diagnostics.length > 0) {
+        output = recorded.diagnostics
+          .slice(-APPLET_PROGRESS_OUTPUT_LINES_V1)
+          .map(trimLine);
+      }
+    }
+  }
+
+  // Source on the Workspace means the Bot has written files, whether or not
+  // this Turn is the one that wrote them.
+  if ((input.source?.files.length ?? 0) > 0) stage = furthest(stage, "writing");
+
+  let working = false;
+  for (const activity of input.tools ?? []) {
+    const name = toolName(activity);
+    if (name === "computer_exec") {
+      const ran = appletCommandOutputV1(activity.text);
+      if (activity.status === "running") {
+        // A shell command in flight during a build is the Bot working on the
+        // Applet; which command it is only becomes knowable when it returns.
+        working = true;
+        done = false;
+        continue;
+      }
+      if (!ran) continue;
+      stage = furthest(
+        stage,
+        ran.command === "build" ? "building" : "checking",
+      );
+      output = ran.output;
+      const wrong =
+        activity.status === "failed" ||
+        (ran.command === "check" && checkFailed(activity.text ?? ""));
+      failure = wrong
+        ? ran.command === "build"
+          ? "Putting it together did not work."
+          : "The code has problems that need fixing."
+        : undefined;
+      done = !wrong;
+      continue;
+    }
+    if (!namesApplet(activity, applet.appletId)) continue;
+    if (name === "applet_create") {
+      stage = furthest(stage, "created");
+      if (activity.status === "running") {
+        working = true;
+        done = false;
+      } else if (activity.status === "failed") {
+        failure = sentence(activity.text ?? "This Applet could not be made.");
+        done = false;
+      } else done = true;
+      continue;
+    }
+    if (name === "applet_publish") {
+      if (activity.status === "running") {
+        stage = furthest(stage, "publishing");
+        working = true;
+        failure = undefined;
+        done = false;
+        continue;
+      }
+      if (activity.status === "failed") {
+        stage = furthest(stage, "publishing");
+        failure = sentence(
+          activity.text ?? "It could not be made ready to open.",
+        );
+        done = false;
+        continue;
+      }
+      stage = furthest(stage, "published");
+      failure = undefined;
+      done = true;
+      continue;
+    }
+  }
+
+  if (input.running) working = true;
+
+  return {
+    stage,
+    label: done ? LABELS[stage].done : LABELS[stage].doing,
+    working,
+    done,
+    ...(failure ? { failure } : {}),
+    ...(output && output.length > 0 ? { output } : {}),
+  };
+}
+
+/**
+ * The tool activity the line is read from: every Turn's, oldest first.
+ *
+ * Not just the Turn that is running. Building an Applet takes several Turns —
+ * the Bot writes, checks, fixes, builds, publishes, and the User says things
+ * in between — and the last thing that happened to the Applet is what a person
+ * wants to know, whether or not it happened in the Turn still open. The
+ * reducer takes the last relevant activity, so a settled failure stays on
+ * screen until something newer replaces it.
+ */
+export function appletProgressToolsV1(
+  messages: readonly Pick<WebChatMessage, "role" | "tools">[],
+): WebToolActivity[] {
+  const tools: WebToolActivity[] = [];
+  for (const message of messages) {
+    if (message.role !== "assistant") continue;
+    tools.push(...message.tools);
+  }
+  return tools;
+}
+
+/**
+ * Whether the canvas should be showing the building view rather than the
+ * Applet. A published Applet with a Turn working on it keeps showing what it
+ * has: replacing a working Applet with a progress line takes something away.
+ */
+export function appletIsBeingBuiltV1(
+  progress: AppletProgressV1 | undefined,
+): boolean {
+  return Boolean(progress && progress.stage !== "published");
+}

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;