@frockbot/plugin-shell 0.3.10 → 0.3.12

package/src/run-protocol.ts

@@ -5,7 +5,10 @@ import {
   type SessionEvent,
   type SkillRefV1,
 } from "@frockbot/kernel-contracts";
-import { isPublicIdentifier } from "@frockbot/configuration-core";
+import {
+  isPublicIdentifier,
+  isRpcIdentifier,
+} from "@frockbot/configuration-core";
 import { decodeRunCursorV1, RUN_CURSOR_PATTERN } from "./run-cursor.js";
 export { decodeRunCursorV1, RUN_CURSOR_PATTERN };
 import type {
@@ -241,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;
@@ -283,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 {
@@ -980,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 {
@@ -1648,7 +1730,15 @@ export function decodeClientNotificationAcknowledgementCommandV1(
     MAX_RUN_ID_LENGTH,
     "notification acknowledgement command",
   );
-  if (!isPublicIdentifier(notificationId)) {
+  // `isRpcIdentifier`, not `isPublicIdentifier`: the same bounded alphabet
+  // plus `:` and `@`. New ids are minted through `notificationIdV1` and carry
+  // neither, but Bots in the field are already holding notifications whose ids
+  // were interpolated by hand — `composition-failure:<generationId>:<attempt>`
+  // and three more like it. Under the stricter pattern those could never be
+  // acknowledged, so the client retried them forever and the Bot answered 400
+  // on every poll for the rest of its life. Accepting them here is what lets
+  // an already-wedged Bot recover without a storage sweep.
+  if (!isRpcIdentifier(notificationId)) {
     throw new Error(
       "notification acknowledgement command.notificationId is invalid",
     );
@@ -1817,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",
@@ -1834,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

@@ -81,6 +81,12 @@ export const SETTINGS_ANCHORS_V1: readonly SettingsAnchorV1[] = [
     label: "Label",
     scope: "bot",
   },
+  {
+    anchor: "bot-pinned",
+    surface: "bot-settings",
+    label: "Pinned",
+    scope: "bot",
+  },
   {
     anchor: "bot-description",
     surface: "bot-settings",
@@ -269,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/src/unread.ts

@@ -389,6 +389,15 @@ export interface BotUnreadViewV1 {
   lastViewedAt?: string;
   /** Latest settled assistant/user line, projected for the sidebar only. */
   lastMessage?: SidebarMessagePreviewV1;
+  /**
+   * Whether this Bot has a Turn running right now.
+   *
+   * The sidebar draws it as an activity ring on the row's avatar, so somebody
+   * reading one conversation can see another Bot still working rather than
+   * assuming it stalled. Optional: a view a client older than the Bot decodes,
+   * or one stored before this existed, simply draws no ring.
+   */
+  working?: boolean;
 }
 
 export interface BotUnreadDirectoryViewV1 {
@@ -414,6 +423,8 @@ export function projectBotUnreadViewV1(
    * so it counts here even though the firing that produced it does not.
    */
   automationFailures = 0,
+  /** True while a Turn of this Bot's is running. Drawn as the row's ring. */
+  working = false,
 ): BotUnreadViewV1 {
   const ceiling = state.lastActivityCursor;
   let counted = Math.max(0, automationFailures);
@@ -449,6 +460,7 @@ export function projectBotUnreadViewV1(
       ? {}
       : { lastViewedAt: state.lastViewedAt }),
     ...(lastMessage === undefined ? {} : { lastMessage }),
+    ...(working ? { working: true } : {}),
   };
 }
 
@@ -528,7 +540,13 @@ function decodeBotUnreadViewV1(input: unknown): BotUnreadViewV1 {
   exactKeys(
     value,
     ["schemaVersion", "botId", "count", "capped", "unread", "manuallyUnread"],
-    ["lastActivityCursor", "lastActivityAt", "lastViewedAt", "lastMessage"],
+    [
+      "lastActivityCursor",
+      "lastActivityAt",
+      "lastViewedAt",
+      "lastMessage",
+      "working",
+    ],
     "unread view",
   );
   if (value.schemaVersion !== 1) {
@@ -563,6 +581,9 @@ function decodeBotUnreadViewV1(input: unknown): BotUnreadViewV1 {
   );
   const lastViewedAt = optionalTimestamp(value, "lastViewedAt", "unread view");
   const lastMessage = optionalSidebarMessagePreviewV1(value.lastMessage);
+  if (value.working !== undefined && typeof value.working !== "boolean") {
+    throw new UnreadDecodeError("unread view working is invalid");
+  }
   return {
     schemaVersion: 1,
     botId: value.botId,
@@ -574,6 +595,7 @@ function decodeBotUnreadViewV1(input: unknown): BotUnreadViewV1 {
     ...(lastActivityAt === undefined ? {} : { lastActivityAt }),
     ...(lastViewedAt === undefined ? {} : { lastViewedAt }),
     ...(lastMessage === undefined ? {} : { lastMessage }),
+    ...(value.working === true ? { working: true } : {}),
   };
 }
 

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,