@frockbot/plugin-shell 0.3.11 → 0.3.13

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/applets-client.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import {
+  appletSourceFingerprintV1,
   mostRecentlyChangedFileV1,
   readAppletList,
   readAppletSource,
@@ -119,6 +120,67 @@ describe("Applet routes", () => {
       }),
     ).toBe("ui.tsx");
   });
+
+  test("the source fingerprint is the same for a re-read of the same files", () => {
+    // The canvas moves the User to the code when a Turn *writes* source. It
+    // re-reads the source on every poll and gets a fresh view object each
+    // time, so the identity that decides has to be the files themselves —
+    // otherwise a Turn that only called an Applet's own tool throws the User
+    // off the live Applet.
+    const file = {
+      path: "server.ts",
+      text: "export default class {}",
+      generationId: "w-1",
+      changedAt: "2026-09-03T00:01:00.000Z",
+    };
+    const view = {
+      appletId: "u1abc.todo",
+      truncated: false,
+      files: [file, { ...file, path: "ui.tsx", generationId: "w-2" }],
+    };
+    expect(appletSourceFingerprintV1(view)).toBe(
+      appletSourceFingerprintV1(structuredClone(view)),
+    );
+    // Order is not a change either: two reads may sort the store differently.
+    expect(
+      appletSourceFingerprintV1({ ...view, files: view.files.toReversed() }),
+    ).toBe(appletSourceFingerprintV1(view));
+    expect(appletSourceFingerprintV1(undefined)).toBe("");
+  });
+
+  test("the source fingerprint changes when a Turn writes a file", () => {
+    const view = {
+      appletId: "u1abc.todo",
+      truncated: false,
+      files: [
+        {
+          path: "server.ts",
+          text: "",
+          generationId: "w-1",
+          changedAt: "2026-09-03T00:01:00.000Z",
+        },
+      ],
+    };
+    expect(
+      appletSourceFingerprintV1({
+        ...view,
+        files: [
+          {
+            ...view.files[0]!,
+            generationId: "w-2",
+            changedAt: "2026-09-03T00:02:00.000Z",
+          },
+        ],
+      }),
+    ).not.toBe(appletSourceFingerprintV1(view));
+    // A new file is a write too.
+    expect(
+      appletSourceFingerprintV1({
+        ...view,
+        files: [...view.files, { ...view.files[0]!, path: "ui.tsx" }],
+      }),
+    ).not.toBe(appletSourceFingerprintV1(view));
+  });
 });
 
 describe("the applets feed a page receives", () => {

package/src/client/applets-client.ts

@@ -137,3 +137,22 @@ export function mostRecentlyChangedFileV1(
   });
   return ordered[0]?.path;
 }
+
+/**
+ * A stable identity for the source the canvas is showing.
+ *
+ * The canvas follows the Turn: a Turn that writes source lands the User on the
+ * code. "Wrote source" has to be a fact about the files, though, not about the
+ * store having been re-read — `refreshAppletCanvas` assigns a fresh view object
+ * on every poll, so a watcher on the array itself fired on Turns that touched
+ * no file at all and yanked the User off the live Applet.
+ */
+export function appletSourceFingerprintV1(
+  source: AppletSourceViewV1 | undefined,
+): string {
+  if (!source) return "";
+  return source.files
+    .map((file) => `${file.path}@${file.generationId}@${file.changedAt ?? ""}`)
+    .toSorted()
+    .join("\n");
+}