@frockbot/plugin-shell 0.3.11 → 0.3.12

package/src/run-protocol.ts

@@ -244,14 +244,30 @@ export interface ClientRunPageV1 {
  * A durable Session event that belongs to no Turn. The WebUI renders it as a
  * system line in the conversation.
  */
-export interface ClientAnnouncementV1 {
-  type: "bot/renamed";
-  announcementId: string;
-  at: string;
-  from: string;
-  to: string;
-  namedBy: "user" | "bot";
-}
+/**
+ * A session-level line in the transcript that belongs to neither party.
+ *
+ * `conversation/compacted` is ADR 0030's one user-visible surface: the earlier
+ * Turns are still there and still readable, and this says plainly that the
+ * model now carries a summary of them instead of the Turns themselves. ADR
+ * 0027's "not summarised" notice still stands where Turns were genuinely
+ * evicted, so the two never claim each other's ground.
+ */
+export type ClientAnnouncementV1 =
+  | {
+      type: "bot/renamed";
+      announcementId: string;
+      at: string;
+      from: string;
+      to: string;
+      namedBy: "user" | "bot";
+    }
+  | {
+      type: "conversation/compacted";
+      announcementId: string;
+      at: string;
+      throughTurn: number;
+    };
 
 export interface ClientRunListV1 {
   schemaVersion: 1;
@@ -286,6 +302,19 @@ export interface ClientConversationListV1 {
   conversations: ClientConversationV1[];
 }
 
+/**
+ * The answer to "start a new conversation": the list, or the reason not now.
+ *
+ * A refusal is a value, not an exception. The request crosses a Durable Object
+ * boundary and a Worker boundary to get here, and an exception that crosses
+ * either is logged by workerd as `Uncaught Error` — the log then showed the
+ * isolate going down with a broken pipe behind it. Carrying the refusal as
+ * data means the only thing that reaches the client is the 409 it expects.
+ */
+export type ClientConversationOutcomeV1 =
+  | ({ status: "started" } & ClientConversationListV1)
+  | { status: "refused"; schemaVersion: 1; reason: string };
+
 export function decodeClientConversationListV1(
   input: unknown,
 ): ClientConversationListV1 {
@@ -983,24 +1012,74 @@ export function createClientRunListV1(
 const MAX_ANNOUNCEMENTS = 64;
 const MAX_ANNOUNCEMENT_NAME_BYTES = 400;
 
-/** Projects the Bot's durable announcement events onto the wire. */
+/**
+ * Where each Turn ended, by Turn number.
+ *
+ * A compaction is written at the end of the Turn that crossed the threshold,
+ * which is the *newest* Turn — so its own timestamp would place its marker at
+ * the bottom of the thread, far from the range it describes. The boundary it
+ * actually names is the end of `throughTurn`, and that is what the marker is
+ * dated with.
+ */
+function turnEndTimestampsV1(
+  session: readonly SessionEvent[],
+): Map<number, string> {
+  const ends = new Map<number, string>();
+  for (const event of session) {
+    if (event.type === "turn/end") ends.set(event.turn, event.timestamp);
+  }
+  return ends;
+}
+
+/**
+ * Projects the Bot's durable announcement events onto the wire.
+ *
+ * `session` is the conversation's own log, used only to date a compaction
+ * marker at the boundary it covers. Omitting it dates the marker by when the
+ * compaction was written, which is where it used to sit.
+ */
 export function projectClientAnnouncementsV1(
   events: readonly SessionEvent[],
+  session: readonly SessionEvent[] = events,
 ): ClientAnnouncementV1[] {
-  return events.flatMap((event) =>
-    event.type === "bot/renamed"
-      ? [
-          {
-            type: "bot/renamed" as const,
-            announcementId: `announcement-${event.seq}`,
-            at: truncate(event.timestamp, MAX_TIMESTAMP_LENGTH),
-            from: truncateWireString(event.from, MAX_ANNOUNCEMENT_NAME_BYTES),
-            to: truncateWireString(event.to, MAX_ANNOUNCEMENT_NAME_BYTES),
-            namedBy: event.namedBy,
-          },
-        ]
-      : [],
-  );
+  const turnEnds = turnEndTimestampsV1(session);
+  return events.flatMap((event): ClientAnnouncementV1[] => {
+    if (event.type === "bot/renamed") {
+      return [
+        {
+          type: "bot/renamed" as const,
+          announcementId: `announcement-${event.seq}`,
+          at: truncate(event.timestamp, MAX_TIMESTAMP_LENGTH),
+          from: truncateWireString(event.from, MAX_ANNOUNCEMENT_NAME_BYTES),
+          to: truncateWireString(event.to, MAX_ANNOUNCEMENT_NAME_BYTES),
+          namedBy: event.namedBy,
+        },
+      ];
+    }
+    if (event.type === "conversation/compacted") {
+      // The summary itself is deliberately not on the wire. A person can read
+      // every Turn it covers, unchanged, immediately above this line; the
+      // summary is what the model carries, and it belongs to the audit view.
+      return [
+        {
+          type: "conversation/compacted" as const,
+          // A distinct prefix: a compaction is numbered by the session log and
+          // a rename by this Bot's announcement log, and the two counters would
+          // otherwise collide on an id the client upserts by.
+          announcementId: `compaction-${event.seq}`,
+          // Dated where the covered range ends, not when the summariser ran,
+          // so the marker sits between the last compacted Turn and the first
+          // verbatim one and stays there as newer Turns arrive.
+          at: truncate(
+            turnEnds.get(event.throughTurn) ?? event.timestamp,
+            MAX_TIMESTAMP_LENGTH,
+          ),
+          throughTurn: event.throughTurn,
+        },
+      ];
+    }
+    return [];
+  });
 }
 
 export function clientRunListWireBytes(value: ClientRunListV1): number {
@@ -1828,14 +1907,19 @@ export function decodeClientRunLookupV1(input: unknown): ClientRunLookup {
 
 function decodeAnnouncement(value: unknown): ClientAnnouncementV1 {
   const announcement = record(value, "run list.announcement");
+  if (
+    announcement.type !== "bot/renamed" &&
+    announcement.type !== "conversation/compacted"
+  ) {
+    throw new Error("run list.announcement.type is invalid");
+  }
   exactKeys(
     announcement,
-    ["type", "announcementId", "at", "from", "to", "namedBy"],
+    announcement.type === "conversation/compacted"
+      ? ["type", "announcementId", "at", "throughTurn"]
+      : ["type", "announcementId", "at", "from", "to", "namedBy"],
     "run list.announcement",
   );
-  if (announcement.type !== "bot/renamed") {
-    throw new Error("run list.announcement.type is invalid");
-  }
   const at = string(
     announcement,
     "at",
@@ -1845,20 +1929,35 @@ function decodeAnnouncement(value: unknown): ClientAnnouncementV1 {
   if (!Number.isFinite(Date.parse(at))) {
     throw new Error("run list.announcement.at is invalid");
   }
+  const announcementId = publicEventId(
+    string(
+      announcement,
+      "announcementId",
+      MAX_EVENT_ID_LENGTH,
+      "run list.announcement",
+    ),
+    "run list.announcement.announcementId",
+  );
+  if (announcement.type === "conversation/compacted") {
+    if (
+      !Number.isSafeInteger(announcement.throughTurn) ||
+      (announcement.throughTurn as number) < 1
+    ) {
+      throw new Error("run list.announcement.throughTurn is invalid");
+    }
+    return {
+      type: "conversation/compacted",
+      announcementId,
+      at,
+      throughTurn: announcement.throughTurn as number,
+    };
+  }
   if (announcement.namedBy !== "user" && announcement.namedBy !== "bot") {
     throw new Error("run list.announcement.namedBy is invalid");
   }
   return {
     type: "bot/renamed",
-    announcementId: publicEventId(
-      string(
-        announcement,
-        "announcementId",
-        MAX_EVENT_ID_LENGTH,
-        "run list.announcement",
-      ),
-      "run list.announcement.announcementId",
-    ),
+    announcementId,
     at,
     from: wireString(
       announcement,

package/src/settings-links.test.ts

@@ -62,10 +62,16 @@ describe("settings link scheme", () => {
     });
   });
 
-  test("drops a fragment belonging to another surface", () => {
+  test("a fragment belonging to another surface opens that surface", () => {
+    // The row is the specific request; the query parameter is where the link
+    // was written from, and rows move between surfaces.
     expect(
       decodeSettingsLinkV1("/?settings=bot-settings#bot-info-computer"),
-    ).toEqual({ surface: "bot-settings" });
+    ).toEqual({ surface: "bot-panel", anchor: "bot-info-computer" });
+    expect(decodeSettingsLinkV1("/?settings=bot-panel#bot-routines")).toEqual({
+      surface: "bot-settings",
+      anchor: "bot-routines",
+    });
   });
 
   test("drops an anchor nobody registered", () => {

package/src/settings-links.ts

@@ -275,9 +275,18 @@ export function decodeSettingsLinkV1(
   const fragment = decodeURIComponent(url.hash.replace(/^#/u, ""));
   const entry = fragment ? settingsAnchorV1(fragment) : undefined;
   const botId = url.searchParams.get("bot") ?? undefined;
+  /*
+   * A fragment naming a row that lives somewhere else is still a request for
+   * that row, so the anchor decides which surface opens. Dropping it instead
+   * is what made `?settings=bot-panel#bot-routines` open the panel and then
+   * sit there: a link that resolves to nothing visible reads as a broken app,
+   * and a row moving between surfaces is exactly what these links have to
+   * survive. A fragment nobody registered still opens the named surface with
+   * no row.
+   */
   return {
-    surface,
-    ...(entry && entry.surface === surface ? { anchor: entry.anchor } : {}),
+    surface: entry ? entry.surface : surface,
+    ...(entry ? { anchor: entry.anchor } : {}),
     ...(botId ? { botId } : {}),
   };
 }

package/src/shared.ts

@@ -222,6 +222,29 @@ export function withoutConnectionReturnV1(search: string): string {
   return rest ? `?${rest}` : "";
 }
 
+/**
+ * What the shell holds of the conversations the User is not looking at, as
+ * everything outside the shell may address it.
+ *
+ * Two callers: the thread, which records and reads back where the reader had
+ * each Bot scrolled, and any surface that changes a Bot enough that its held
+ * transcript would be a lie rather than merely old — archive, delete, and a
+ * change of signed-in User.
+ */
+export interface TranscriptMemoryV1 {
+  /** Records where the reader had this Bot's thread. */
+  rememberViewport(
+    botId: string,
+    viewport: { scrollTop: number; pinnedToLatest: boolean },
+  ): void;
+  /** Where the reader had this Bot's thread, if it is still held. */
+  viewportFor(
+    botId: string,
+  ): { scrollTop: number; pinnedToLatest: boolean } | undefined;
+  /** Drops what is held for one Bot, or — with no argument — for every Bot. */
+  forget(botId?: string): void;
+}
+
 export interface FrockBotWebData {
   connection: WebConnection;
   modelLabel: string;
@@ -249,6 +272,14 @@ export interface FrockBotWebData {
   runningRunId?: string;
   activeRun?: WebActiveRun;
   error?: string;
+  /**
+   * The Bot list could not be read, so "no Bot is open" means "we do not know
+   * yet" rather than "this account has none". Set by whichever Package owns
+   * the list. Without it a transport failure reads as data loss: the
+   * first-run empty state offering to add a first Bot to a User who has
+   * several is the worst thing this surface can say.
+   */
+  botsUnavailable?: boolean;
   botSettings?: BotSettingsViewV1;
   userSettings?: UserSettingsViewV1;
   pluginCatalog: PluginCatalogItem[];
@@ -328,6 +359,11 @@ export interface FrockBotWebData {
    * cancelled or failed grant is reported rather than silently discarded.
    */
   connectionReturn?: ConnectionReturnV1;
+  /**
+   * The conversations this client is still holding, so switching back to a
+   * Bot is a paint rather than a reload.
+   */
+  transcripts: TranscriptMemoryV1;
   selectBot(botId: string): Promise<void>;
   loadBotSettings(): Promise<void>;
   saveBotProfile(profile: BotProfile): Promise<void>;

package/tsconfig.json

@@ -4,9 +4,8 @@
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "allowImportingTsExtensions": true,
-    "baseUrl": ".",
     "paths": {
-      "@cordisjs/client": ["src/client/cordis-client-shim.d.ts"]
+      "@cordisjs/client": ["./src/client/cordis-client-shim.d.ts"]
     },
     "strict": true,
     "noEmit": true,

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

@@ -1,89 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import {
-  ACTIVITY_RING_MAX_LAPS_V1,
-  ACTIVITY_RING_SEGMENTS_V1,
-  activityRingV1,
-  type ActivityStepStatusV1,
-} from "./activity-ring.js";
-
-/** `count` settled steps, plus whatever is still in flight. */
-function steps(settled: number, inFlight = 0): ActivityStepStatusV1[] {
-  return [
-    ...Array.from<ActivityStepStatusV1>({ length: settled }).fill("completed"),
-    ...Array.from<ActivityStepStatusV1>({ length: inFlight }).fill("running"),
-  ];
-}
-
-describe("the avatar's activity ring", () => {
-  test("a Turn with nothing done yet still shows a ring", () => {
-    // Liveness before progress: the ring is the answer to "is it paused?", so
-    // it is drawn from the first moment of the Turn, empty and pulsing.
-    const ring = activityRingV1({ toolStatuses: [], status: "streaming" });
-    expect(ring.active).toBe(true);
-    expect(ring.running).toBe(true);
-    expect(ring.filled).toBe(0);
-    expect(ring.progress).toBe(0);
-  });
-
-  test("a step that is still running has not ticked the ring", () => {
-    const ring = activityRingV1({
-      toolStatuses: steps(2, 1),
-      status: "streaming",
-    });
-    expect(ring.steps).toBe(2);
-    expect(ring.filled).toBe(2);
-  });
-
-  test("a failed step ticks like any other — it is a step that happened", () => {
-    const ring = activityRingV1({
-      toolStatuses: ["completed", "failed"],
-      status: "streaming",
-    });
-    expect(ring.filled).toBe(2);
-  });
-
-  test("each settled step fills one more segment of the lap", () => {
-    for (let settled = 0; settled < ACTIVITY_RING_SEGMENTS_V1; settled += 1) {
-      const ring = activityRingV1({
-        toolStatuses: steps(settled),
-        status: "streaming",
-      });
-      expect(ring.filled).toBe(settled);
-      expect(ring.progress).toBeCloseTo(settled / ACTIVITY_RING_SEGMENTS_V1);
-      expect(ring.laps).toBe(0);
-    }
-  });
-
-  test("a full lap leaves a faint ring behind and starts again", () => {
-    const ring = activityRingV1({
-      toolStatuses: steps(ACTIVITY_RING_SEGMENTS_V1 + 1),
-      status: "streaming",
-    });
-    expect(ring.laps).toBe(1);
-    expect(ring.filled).toBe(1);
-  });
-
-  test("a Turn of forty tool calls never grows a fortieth ring", () => {
-    // The bound is the point: the ring reports that work is happening, not how
-    // much, so past the last lap it loops inside the strokes it already has.
-    const ring = activityRingV1({
-      toolStatuses: steps(40),
-      status: "streaming",
-    });
-    expect(ring.laps).toBe(ACTIVITY_RING_MAX_LAPS_V1);
-    expect(ring.filled).toBeLessThan(ACTIVITY_RING_SEGMENTS_V1);
-  });
-
-  test("a settled Turn keeps no ring, however it ended", () => {
-    for (const status of [
-      "completed",
-      "failed",
-      "interrupted",
-      "reconciliation-required",
-    ] as const) {
-      const ring = activityRingV1({ toolStatuses: steps(3), status });
-      expect(ring.active).toBe(false);
-      expect(ring.running).toBe(false);
-    }
-  });
-});

package/src/client/activity-ring.ts

@@ -1,94 +0,0 @@
-/**
- * The activity ring: how much a running Turn has done, without saying so.
- *
- * A Turn can spend a minute making tool calls, and the thread used to answer
- * that with either nothing or a list of tool names. Neither is right — the
- * first reads as a paused app, the second puts the model's plumbing into a
- * conversation. The ring is the third answer: a stroke around the Bot's avatar
- * that pulses while the Turn runs and advances one segment for every step that
- * settles, so a person sees liveness and rough progress and reads no words at
- * all.
- *
- * This module is the whole rule, kept out of the component so it is testable
- * without mounting Vue.
- */
-
-/** Segments in one lap of the ring. A step fills one. */
-export const ACTIVITY_RING_SEGMENTS_V1 = 8;
-
-/**
- * How many laps the ring will draw at once. A Turn making forty tool calls
- * must not grow a fortieth ring, so the lap beyond the first is the last one:
- * past it the ring keeps looping inside those two strokes.
- */
-export const ACTIVITY_RING_MAX_LAPS_V1 = 1;
-
-/** A step's state, as the Turn's tool activity reports it. */
-export type ActivityStepStatusV1 = "running" | "completed" | "failed";
-
-/**
- * A Turn's state, as the thread's message carries it.
- *
- * Deliberately the whole string rather than the union: only `streaming` means
- * the Turn is still going, and every other value — including one a newer Bot
- * invents — is an ending. The ring is drawn off that one positive test, so it
- * cannot be left spinning by a status this file has never heard of.
- */
-export type ActivityTurnStatusV1 = string;
-
-export interface ActivityRingViewV1 {
-  /** Whether the ring is drawn at all. A settled Turn keeps none. */
-  active: boolean;
-  /** Whether the ring pulses. False once the Turn has settled. */
-  running: boolean;
-  /** Steps that have settled in this Turn. Unbounded, and never rendered. */
-  steps: number;
-  /** Filled segments of the current lap, `0 … ACTIVITY_RING_SEGMENTS_V1`. */
-  filled: number;
-  /** Faint laps completed behind the live stroke, capped. */
-  laps: number;
-  /** The fraction of the circumference the live stroke draws, `0 … 1`. */
-  progress: number;
-}
-
-/**
- * The ring for one assistant line.
- *
- * A running Turn ticks: every settled tool call advances the stroke one
- * segment, and the lap that fills leaves a faint ring behind it — up to
- * {@link ACTIVITY_RING_MAX_LAPS_V1}, after which the ring simply loops. A Turn
- * that has settled draws no ring; the reply is the answer by then, and the
- * component fades the ring out on its way off screen.
- */
-export function activityRingV1(input: {
-  toolStatuses: readonly ActivityStepStatusV1[];
-  status: ActivityTurnStatusV1;
-}): ActivityRingViewV1 {
-  const running = input.status === "streaming";
-  const steps = input.toolStatuses.filter(
-    (status) => status !== "running",
-  ).length;
-  if (!running) {
-    return {
-      active: false,
-      running: false,
-      steps,
-      filled: 0,
-      laps: 0,
-      progress: 0,
-    };
-  }
-  const filled = steps % ACTIVITY_RING_SEGMENTS_V1;
-  const laps = Math.min(
-    Math.floor(steps / ACTIVITY_RING_SEGMENTS_V1),
-    ACTIVITY_RING_MAX_LAPS_V1,
-  );
-  return {
-    active: true,
-    running: true,
-    steps,
-    filled,
-    laps,
-    progress: filled / ACTIVITY_RING_SEGMENTS_V1,
-  };
-}