@frockbot/plugin-shell 0.3.11 → 0.3.12

package/src/client/activity-trail.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ACTIVITY_TRAIL_CHARACTERS_PER_PARTICLE_V1,
+  ACTIVITY_TRAIL_MAX_BURSTS_PER_STEP_V1,
+  ACTIVITY_TRAIL_MAX_RATE_V1,
+  ACTIVITY_TRAIL_QUIET_AFTER_MS_V1,
+  ACTIVITY_TRAIL_SEND_BURST_V1,
+  ACTIVITY_TRAIL_TOOL_BURST_V1,
+  ACTIVITY_TRAIL_TRICKLE_RATE_V1,
+  activityTrailBeginV1,
+  activityTrailSampleV1,
+  activityTrailStepV1,
+  type ActivityTrailSampleV1,
+} from "./activity-trail.js";
+
+function sample(
+  overrides: Partial<ActivityTrailSampleV1> = {},
+): ActivityTrailSampleV1 {
+  return {
+    characters: 0,
+    toolStarts: 0,
+    toolSettles: 0,
+    sends: 0,
+    status: "streaming",
+    ...overrides,
+  };
+}
+
+describe("what the transcript says a Turn is doing", () => {
+  test("a tool with no result yet has started but not settled", () => {
+    const reading = activityTrailSampleV1({
+      text: "half a rep",
+      toolStatuses: ["completed", "running"],
+      sends: 1,
+      status: "streaming",
+    });
+    expect(reading.characters).toBe("half a rep".length);
+    expect(reading.toolStarts).toBe(2);
+    expect(reading.toolSettles).toBe(1);
+    expect(reading.sends).toBe(1);
+  });
+});
+
+describe("the comet trail's emission plan", () => {
+  test("a Turn that has produced nothing yet still emits", () => {
+    // Liveness before pace: the first moment of a Turn is exactly when a
+    // person needs to see that something is happening.
+    const memory = activityTrailBeginV1(sample(), 0);
+    const { plan } = activityTrailStepV1(memory, sample(), 16);
+    expect(plan.active).toBe(true);
+    expect(plan.state).toBe("running");
+    expect(plan.rate).toBe(ACTIVITY_TRAIL_TRICKLE_RATE_V1);
+    expect(plan.bursts).toEqual([]);
+  });
+
+  test("the density tracks how fast text is arriving", () => {
+    // Two hundred characters inside the averaging window is well above the
+    // trickle and below saturation, so the rate is the chunk rate itself.
+    let memory = activityTrailBeginV1(sample(), 0);
+    const stepped = activityTrailStepV1(
+      memory,
+      sample({ characters: 200 }),
+      200,
+    );
+    memory = stepped.memory;
+    expect(stepped.plan.rate).toBeGreaterThan(ACTIVITY_TRAIL_TRICKLE_RATE_V1);
+    expect(stepped.plan.rate).toBeLessThan(ACTIVITY_TRAIL_MAX_RATE_V1);
+    expect(stepped.plan.rate).toBeCloseTo(
+      200 / 1.2 / ACTIVITY_TRAIL_CHARACTERS_PER_PARTICLE_V1,
+      5,
+    );
+
+    // Half as much text in the same window is half the density.
+    const slower = activityTrailStepV1(
+      activityTrailBeginV1(sample(), 0),
+      sample({ characters: 100 }),
+      200,
+    );
+    expect(slower.plan.rate).toBeCloseTo(stepped.plan.rate / 2, 5);
+  });
+
+  test("a torrent of text saturates rather than running away", () => {
+    const { plan } = activityTrailStepV1(
+      activityTrailBeginV1(sample(), 0),
+      sample({ characters: 100_000 }),
+      100,
+    );
+    expect(plan.rate).toBe(ACTIVITY_TRAIL_MAX_RATE_V1);
+  });
+
+  test("a tool call starting throws a burst, and settling throws another", () => {
+    let memory = activityTrailBeginV1(sample(), 0);
+    const started = activityTrailStepV1(memory, sample({ toolStarts: 1 }), 100);
+    memory = started.memory;
+    expect(started.plan.bursts).toEqual([
+      { count: ACTIVITY_TRAIL_TOOL_BURST_V1, speed: 1.8, brightness: 1.15 },
+    ]);
+
+    const settled = activityTrailStepV1(
+      memory,
+      sample({ toolStarts: 1, toolSettles: 1 }),
+      200,
+    );
+    expect(settled.plan.bursts).toHaveLength(1);
+    expect(settled.plan.bursts[0]?.count).toBe(ACTIVITY_TRAIL_TOOL_BURST_V1);
+  });
+
+  test("a send landing is a brighter puff than a tool call", () => {
+    const { plan } = activityTrailStepV1(
+      activityTrailBeginV1(sample(), 0),
+      sample({ sends: 1 }),
+      100,
+    );
+    expect(plan.bursts).toEqual([
+      { count: ACTIVITY_TRAIL_SEND_BURST_V1, speed: 1.2, brightness: 1.9 },
+    ]);
+  });
+
+  test("a whole Turn arriving at once does not fire a hundred bursts", () => {
+    // What a reconnect looks like: the projection replays every step of a Turn
+    // in one update. The trail says "a lot just happened", not two hundred
+    // separate shots into one frame.
+    const { plan } = activityTrailStepV1(
+      activityTrailBeginV1(sample(), 0),
+      sample({ toolStarts: 60, toolSettles: 60, sends: 20 }),
+      100,
+    );
+    expect(plan.bursts).toHaveLength(ACTIVITY_TRAIL_MAX_BURSTS_PER_STEP_V1);
+  });
+
+  test("an open Turn that has gone quiet trickles rather than stopping", () => {
+    let memory = activityTrailBeginV1(sample(), 0);
+    memory = activityTrailStepV1(
+      memory,
+      sample({ characters: 40 }),
+      100,
+    ).memory;
+
+    const soon = activityTrailStepV1(
+      memory,
+      sample({ characters: 40 }),
+      100 + ACTIVITY_TRAIL_QUIET_AFTER_MS_V1,
+    );
+    expect(soon.plan.state).toBe("running");
+
+    const later = activityTrailStepV1(
+      memory,
+      sample({ characters: 40 }),
+      101 + ACTIVITY_TRAIL_QUIET_AFTER_MS_V1,
+    );
+    expect(later.plan.active).toBe(true);
+    expect(later.plan.state).toBe("waiting");
+    expect(later.plan.rate).toBe(ACTIVITY_TRAIL_TRICKLE_RATE_V1);
+    expect(later.plan.bursts).toEqual([]);
+  });
+
+  test("a settled Turn emits nothing at all", () => {
+    for (const status of [
+      "completed",
+      "aborted",
+      "error",
+      "interrupted",
+      "reconciliation-required",
+      "a status this file has never heard of",
+    ]) {
+      const { plan } = activityTrailStepV1(
+        activityTrailBeginV1(sample(), 0),
+        sample({ characters: 400, toolStarts: 3, toolSettles: 3, status }),
+        100,
+      );
+      expect(plan.active).toBe(false);
+      expect(plan.state).toBe("ended");
+      expect(plan.rate).toBe(0);
+      expect(plan.bursts).toEqual([]);
+    }
+  });
+
+  test("text the Turn takes back is no work rather than negative work", () => {
+    // A delivered send supersedes the model's own longer draft, so the
+    // transcript's text can shrink between two samples.
+    const memory = activityTrailBeginV1(sample({ characters: 500 }), 0);
+    const { plan } = activityTrailStepV1(
+      memory,
+      sample({ characters: 4, sends: 1 }),
+      100,
+    );
+    expect(plan.rate).toBe(ACTIVITY_TRAIL_TRICKLE_RATE_V1);
+    expect(plan.bursts).toHaveLength(1);
+  });
+
+  test("the rate window forgets text that arrived long ago", () => {
+    let memory = activityTrailBeginV1(sample(), 0);
+    memory = activityTrailStepV1(
+      memory,
+      sample({ characters: 400 }),
+      100,
+    ).memory;
+    const { plan } = activityTrailStepV1(
+      memory,
+      sample({ characters: 400 }),
+      100 + ACTIVITY_TRAIL_QUIET_AFTER_MS_V1 + 1,
+    );
+    expect(plan.rate).toBe(ACTIVITY_TRAIL_TRICKLE_RATE_V1);
+  });
+});

package/src/client/activity-trail.ts

@@ -0,0 +1,227 @@
+/**
+ * The comet trail: what a running Turn is actually doing, drawn as motion.
+ *
+ * A Turn can spend a minute streaming tokens and calling tools, and the thread
+ * used to answer that with a stroke around the avatar that ticked once per
+ * settled step. The stroke was honest but coarse — it said "a step happened"
+ * and nothing about the rate work was arriving at. The trail is the finer
+ * answer: particles stream off the right of the working Bot's avatar, and
+ * their density is the Turn's own pace. Text arriving quickly is a dense
+ * stream; a tool call starting or settling throws a burst; a reply landing is
+ * a bright puff; a Turn waiting on the model still breathes, faintly, so the
+ * app never reads as dead.
+ *
+ * This module is the whole mapping, kept out of the component so it is
+ * testable without a canvas or a mounted Vue tree. It takes samples of what
+ * the client already knows about the open Bot's Turn — the transcript's text,
+ * its tool activity, its sends, its status — and returns the emission plan for
+ * the moment between two samples. It never touches the DOM and never keeps a
+ * clock of its own: the caller supplies `now`.
+ */
+
+/** The most particles a second the trail will ever ask for. */
+export const ACTIVITY_TRAIL_MAX_RATE_V1 = 40;
+
+/**
+ * The floor while a Turn is open. A Turn waiting on a model that has not sent
+ * a token yet is still working, and a trail that stops entirely reads as an
+ * app that has crashed.
+ */
+export const ACTIVITY_TRAIL_TRICKLE_RATE_V1 = 6;
+
+/** Silence longer than this is a wait, not a pause between chunks. */
+export const ACTIVITY_TRAIL_QUIET_AFTER_MS_V1 = 1500;
+
+/** How far back the chunk-rate average looks. */
+export const ACTIVITY_TRAIL_RATE_WINDOW_MS_V1 = 1200;
+
+/**
+ * Characters of streamed text one particle stands for. At the cap above this
+ * makes a full stream about 240 characters a second — faster than that and the
+ * trail is simply saturated, which is the right thing for it to say.
+ */
+export const ACTIVITY_TRAIL_CHARACTERS_PER_PARTICLE_V1 = 6;
+
+/** A tool call starting, or its result settling. */
+export const ACTIVITY_TRAIL_TOOL_BURST_V1 = 15;
+
+/** A payload reaching the person. */
+export const ACTIVITY_TRAIL_SEND_BURST_V1 = 14;
+
+/**
+ * The most burst events one step will honour. A transcript that arrives in one
+ * lump — a reconnect replaying a whole Turn — must not fire two hundred bursts
+ * into the same frame.
+ */
+export const ACTIVITY_TRAIL_MAX_BURSTS_PER_STEP_V1 = 4;
+
+/**
+ * What the trail is saying, and the value the row carries as `data-state` so a
+ * spec can assert on it.
+ *
+ * `running` is work arriving now, `waiting` is an open Turn that has gone
+ * quiet, and `ended` is a settled Turn: nothing new is emitted and whatever is
+ * on screen drains.
+ */
+export type ActivityTrailStateV1 = "running" | "waiting" | "ended";
+
+/** One reading of the open Turn, as the client's projection has it. */
+export interface ActivityTrailSampleV1 {
+  /** Characters of assistant text in the Turn so far. Monotonic. */
+  characters: number;
+  /** Tool calls this Turn has started, settled or not. Monotonic. */
+  toolStarts: number;
+  /** Tool calls whose result has settled. Monotonic. */
+  toolSettles: number;
+  /** Payloads this Turn has delivered to the person. Monotonic. */
+  sends: number;
+  /**
+   * The Turn's status, as the whole string rather than a union: only
+   * `streaming` means the Turn is still going, and every other value —
+   * including one a newer backend invents — is an ending. The trail is driven
+   * off that one positive test, so it cannot be left emitting forever by a
+   * status this file has never heard of.
+   */
+  status: string;
+}
+
+/** A one-off shot of particles, over and above the steady stream. */
+export interface ActivityTrailBurstV1 {
+  /** Particles to spawn at once. */
+  count: number;
+  /** Multiplier on the stream's rightward speed. */
+  speed: number;
+  /** Multiplier on the particles' opacity. Above one reads as a flash. */
+  brightness: number;
+}
+
+/** What to emit for the moment between two samples. */
+export interface ActivityTrailPlanV1 {
+  /** Whether the emitter runs at all. A settled Turn emits nothing. */
+  active: boolean;
+  /** What the trail is saying, for the row's `data-state`. */
+  state: ActivityTrailStateV1;
+  /** Steady particles per second, `0 … ACTIVITY_TRAIL_MAX_RATE_V1`. */
+  rate: number;
+  /** Shots to fire once, now. */
+  bursts: readonly ActivityTrailBurstV1[];
+}
+
+/** What the mapping remembers between two samples. Opaque to the caller. */
+export interface ActivityTrailMemoryV1 {
+  sample: ActivityTrailSampleV1;
+  /** When something last changed, so a wait can be told from a pause. */
+  lastEventAt: number;
+  /** Recent character deltas, for the rate average. */
+  window: ReadonlyArray<{ at: number; characters: number }>;
+}
+
+/**
+ * A sample from the shapes the transcript already carries.
+ *
+ * Kept here rather than in the component so the Turn's vocabulary — a tool
+ * that has not settled is `running`, the text is the whole bubble so far —
+ * lives with the rule that reads it.
+ */
+export function activityTrailSampleV1(input: {
+  text: string;
+  toolStatuses: readonly string[];
+  sends: number;
+  status: string;
+}): ActivityTrailSampleV1 {
+  return {
+    characters: input.text.length,
+    toolStarts: input.toolStatuses.length,
+    toolSettles: input.toolStatuses.filter((status) => status !== "running")
+      .length,
+    sends: input.sends,
+    status: input.status,
+  };
+}
+
+/** The memory a Turn starts with. Its first sample is the baseline. */
+export function activityTrailBeginV1(
+  sample: ActivityTrailSampleV1,
+  now: number,
+): ActivityTrailMemoryV1 {
+  return { sample, lastEventAt: now, window: [] };
+}
+
+function clamp(value: number, low: number, high: number): number {
+  return Math.min(high, Math.max(low, value));
+}
+
+/**
+ * The plan for the moment between the remembered sample and this one.
+ *
+ * Deltas are floored at zero: a projection that replaces a Turn's text with a
+ * shorter final version — a send superseding the model's own draft — is not a
+ * negative amount of work, it is no work.
+ */
+export function activityTrailStepV1(
+  memory: ActivityTrailMemoryV1,
+  sample: ActivityTrailSampleV1,
+  now: number,
+): { memory: ActivityTrailMemoryV1; plan: ActivityTrailPlanV1 } {
+  const characters = Math.max(0, sample.characters - memory.sample.characters);
+  const startedTools = Math.max(
+    0,
+    sample.toolStarts - memory.sample.toolStarts,
+  );
+  const settledTools = Math.max(
+    0,
+    sample.toolSettles - memory.sample.toolSettles,
+  );
+  const delivered = Math.max(0, sample.sends - memory.sample.sends);
+
+  if (sample.status !== "streaming") {
+    return {
+      memory: { sample, lastEventAt: memory.lastEventAt, window: [] },
+      plan: { active: false, state: "ended", rate: 0, bursts: [] },
+    };
+  }
+
+  const window = [...memory.window, { at: now, characters }].filter(
+    (entry) => now - entry.at <= ACTIVITY_TRAIL_RATE_WINDOW_MS_V1,
+  );
+  const streamed = window.reduce((total, entry) => total + entry.characters, 0);
+  const streamRate =
+    streamed /
+    (ACTIVITY_TRAIL_RATE_WINDOW_MS_V1 / 1000) /
+    ACTIVITY_TRAIL_CHARACTERS_PER_PARTICLE_V1;
+
+  const moved =
+    characters > 0 || startedTools > 0 || settledTools > 0 || delivered > 0;
+  const lastEventAt = moved ? now : memory.lastEventAt;
+  const quiet = now - lastEventAt > ACTIVITY_TRAIL_QUIET_AFTER_MS_V1;
+
+  const bursts: ActivityTrailBurstV1[] = [];
+  for (let index = 0; index < startedTools + settledTools; index += 1) {
+    bursts.push({
+      count: ACTIVITY_TRAIL_TOOL_BURST_V1,
+      speed: 1.8,
+      brightness: 1.15,
+    });
+  }
+  for (let index = 0; index < delivered; index += 1) {
+    bursts.push({
+      count: ACTIVITY_TRAIL_SEND_BURST_V1,
+      speed: 1.2,
+      brightness: 1.9,
+    });
+  }
+
+  return {
+    memory: { sample, lastEventAt, window },
+    plan: {
+      active: true,
+      state: quiet ? "waiting" : "running",
+      rate: clamp(
+        Math.max(streamRate, ACTIVITY_TRAIL_TRICKLE_RATE_V1),
+        0,
+        ACTIVITY_TRAIL_MAX_RATE_V1,
+      ),
+      bursts: bursts.slice(0, ACTIVITY_TRAIL_MAX_BURSTS_PER_STEP_V1),
+    },
+  };
+}

package/src/client/index.test.ts

@@ -572,7 +572,11 @@ describe("Bot selection", () => {
     await Promise.all([botLoad, olderLoad]);
 
     expect(provided.value.userSettings?.profile.name).toBe("Newer");
-    expect(provided.value.settingsError).toBe("Bot settings unavailable");
+    // The surface says what failed and what it was for; the thrown text
+    // ("Bot settings unavailable") stays in the console.
+    expect(provided.value.settingsError).toBe(
+      "Couldn't load this Bot's settings.",
+    );
   });
 
   test("says a deployment has no Catalog instead of relaying the gateway's sentence", async () => {
@@ -608,12 +612,14 @@ describe("Bot selection", () => {
       "No plugins are published for this deployment yet.",
     );
 
-    // A genuine fault still reaches the operator, labelled as one.
+    // A genuine fault is labelled as one — and says what failed rather than
+    // what the storage layer called it. "R2 is down" is for the console.
     failure = new Error("R2 is down");
     await provided.value.loadPackageCatalog();
     expect(provided.value.settingsError).toBe(
-      "Plugins could not be loaded: R2 is down",
+      "Couldn't load the plugin catalog.",
     );
+    expect(provided.value.settingsError).not.toContain("R2");
   });
 
   test("commits a catalog without overwriting newer User settings", async () => {
@@ -1258,14 +1264,20 @@ describe("detached Turn projection", () => {
       ],
     );
 
+    // The failure is a notice under the reply, never a bubble that reads as
+    // the Bot saying the provider's own words.
     expect(messages).toMatchObject([
       { role: "user", status: "completed" },
       {
         role: "assistant",
-        text: "This Bot couldn't finish its reply. Try again.",
+        text: "",
+        notice: "This Bot couldn't finish its reply. Try again.",
         status: "error",
       },
     ]);
+    expect(JSON.stringify(messages)).not.toContain(
+      "Provider reconciliation is required",
+    );
   });
 });
 
@@ -1726,6 +1738,9 @@ describe("active durable Turn projection", () => {
         },
       ],
     );
+    // One sentence of the product's own, and the raw provider text nowhere on
+    // screen — the banner, the bubble and the notice all read the same way
+    // whatever the provider called the failure.
     expect(reconciliation.activeRun).toEqual({
       runId: "run-reconciliation",
       status: "reconciliation-required",
@@ -1733,9 +1748,14 @@ describe("active durable Turn projection", () => {
       canResume: true,
     });
     expect(reconciliation.messages[1]).toMatchObject({
-      text: "This reply stopped partway. Try again to continue it.",
+      role: "assistant",
+      text: "",
+      notice: "This reply stopped partway. Try again to continue it.",
       status: "reconciliation-required",
     });
+    expect(JSON.stringify(reconciliation.messages)).not.toContain(
+      "Provider result needs confirmation",
+    );
   });
 
   test("keeps busy state until the durable run becomes terminal", () => {