@frockbot/plugin-shell 0.3.6 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/plugin-shell",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "private": false,
   "type": "module",
   "exports": {
@@ -47,41 +47,41 @@
   },
   "dependencies": {
     "@cordisjs/plugin-webui": "0.8.2",
-    "@frockbot/agent-runtime": "0.3.6",
-    "@frockbot/application-foundation": "0.3.6",
-    "@frockbot/catalog-core": "0.3.6",
-    "@frockbot/client-core": "0.3.6",
-    "@frockbot/client-ui": "0.3.6",
-    "@frockbot/computer-core": "0.3.6",
-    "@frockbot/computer-host-protocol": "0.3.6",
-    "@frockbot/configuration-core": "0.3.6",
-    "@frockbot/connection-core": "0.3.6",
-    "@frockbot/kernel-agent-loop": "0.3.6",
-    "@frockbot/kernel-composition": "0.3.6",
-    "@frockbot/kernel-contracts": "0.3.6",
-    "@frockbot/kernel-do": "0.3.6",
-    "@frockbot/machine-protocol": "0.3.6",
-    "@frockbot/plugin-applets": "0.3.6",
-    "@frockbot/plugin-authoring": "0.3.6",
-    "@frockbot/plugin-bot-template": "0.3.6",
-    "@frockbot/plugin-computer": "0.3.6",
-    "@frockbot/plugin-flock": "0.3.6",
-    "@frockbot/plugin-image": "0.3.6",
-    "@frockbot/plugin-machine-messages": "0.3.6",
-    "@frockbot/plugin-mcp": "0.3.6",
-    "@frockbot/plugin-memory": "0.3.6",
-    "@frockbot/plugin-package-catalog": "0.3.6",
-    "@frockbot/plugin-routines": "0.3.6",
-    "@frockbot/plugin-skills": "0.3.6",
-    "@frockbot/plugin-subagents": "0.3.6",
-    "@frockbot/plugin-user-machine": "0.3.6",
-    "@frockbot/protocol": "0.3.6",
+    "@frockbot/agent-runtime": "0.3.7",
+    "@frockbot/application-foundation": "0.3.7",
+    "@frockbot/catalog-core": "0.3.7",
+    "@frockbot/client-core": "0.3.7",
+    "@frockbot/client-ui": "0.3.7",
+    "@frockbot/computer-core": "0.3.7",
+    "@frockbot/computer-host-protocol": "0.3.7",
+    "@frockbot/configuration-core": "0.3.7",
+    "@frockbot/connection-core": "0.3.7",
+    "@frockbot/kernel-agent-loop": "0.3.7",
+    "@frockbot/kernel-composition": "0.3.7",
+    "@frockbot/kernel-contracts": "0.3.7",
+    "@frockbot/kernel-do": "0.3.7",
+    "@frockbot/machine-protocol": "0.3.7",
+    "@frockbot/plugin-applets": "0.3.7",
+    "@frockbot/plugin-authoring": "0.3.7",
+    "@frockbot/plugin-bot-template": "0.3.7",
+    "@frockbot/plugin-computer": "0.3.7",
+    "@frockbot/plugin-flock": "0.3.7",
+    "@frockbot/plugin-image": "0.3.7",
+    "@frockbot/plugin-machine-messages": "0.3.7",
+    "@frockbot/plugin-mcp": "0.3.7",
+    "@frockbot/plugin-memory": "0.3.7",
+    "@frockbot/plugin-package-catalog": "0.3.7",
+    "@frockbot/plugin-routines": "0.3.7",
+    "@frockbot/plugin-skills": "0.3.7",
+    "@frockbot/plugin-subagents": "0.3.7",
+    "@frockbot/plugin-user-machine": "0.3.7",
+    "@frockbot/protocol": "0.3.7",
     "cordis": "4.0.0-rc.8",
     "vue": "3.5.41"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "latest",
-    "@frockbot/plugin-tools": "0.3.6",
+    "@frockbot/plugin-tools": "0.3.7",
     "@types/bun": "1.3.6",
     "@types/node": "26.2.0",
     "@vitejs/plugin-vue": "6.0.8",

package/src/backend-recovery-integration.test.ts

@@ -354,26 +354,20 @@ describe("Bot recovery", () => {
         text: "uncertain",
       }),
     ).rejects.toThrow("response lost");
-    expect(
-      await storage.get<StoredRun>("run:ollama-run-uncertain"),
-    ).toMatchObject({ status: "reconciliation-required" });
+    // Ollama keeps no addressable copy of a completion, so a failure raised
+    // before the first stream event is definitive rather than uncertain: the
+    // run settles as a failed Turn instead of parking on a retrieval this
+    // provider can never perform.
+    const uncertain = await storage.get<StoredRun>("run:ollama-run-uncertain");
+    expect(uncertain?.status).toBe("failed");
+    expect(uncertain?.failure).toContain("response lost");
+    expect(await storage.get("active-run")).toBeUndefined();
 
+    // The alarm has nothing left to recover: a settled run stays settled.
     await host().alarm();
-    expect(
-      await storage.get<StoredRun>("run:ollama-run-uncertain"),
-    ).toMatchObject({ status: "reconciliation-required" });
-    await expect(
-      host().reconcileRun(
-        { userId: "user-1", botId: "primary" },
-        "ollama-run-uncertain",
-      ),
-    ).rejects.toThrow();
-    expect(
-      await storage.get<StoredRun>("run:ollama-run-uncertain"),
-    ).toMatchObject({
-      status: "failed",
-      failure: expect.stringContaining("explicitly abandoned"),
-    });
+    const settled = await storage.get<StoredRun>("run:ollama-run-uncertain");
+    expect(settled?.status).toBe("failed");
+    expect(settled?.failure).toContain("response lost");
     expect(await storage.get("active-run")).toBeUndefined();
   });
 

package/src/backend.ts

@@ -403,6 +403,7 @@ import {
   projectClientAnnouncementsV1,
   projectClientTurnV1,
   type ClientRunLookupV1,
+  type ClientConversationListV1,
   type ClientRunListV1,
   type ClientRunStopReceiptV1,
   type ClientRunV1,
@@ -5443,6 +5444,15 @@ export class ShellBotBackendContribution {
   ): Promise<ClientRunListV1> {
     const query = decodeClientRunListQueryV1(input);
     await this.authority.recoverActiveRun();
+    // The transcript is one conversation, not every Turn the Bot has ever
+    // run. Absent means the conversation the Bot is on; naming an earlier one
+    // reads it exactly as it was left. A Bot whose object has not learned its
+    // identity yet has no conversation to filter by and shows what it has.
+    const conversationId =
+      query.conversationId ??
+      (await this.authority.readConversationSessionId());
+    const inConversation = (run: { sessionId: string }) =>
+      conversationId === undefined || run.sessionId === conversationId;
     const activeRunId = query.before
       ? undefined
       : await this.authority.readActiveRunId();
@@ -5457,7 +5467,7 @@ export class ShellBotBackendContribution {
       // An automation firing occupies the object like any other run, and is
       // still not part of the conversation: the visible transcript never
       // shows one, running or settled.
-      if (active && isVisibleRunV1(active))
+      if (active && isVisibleRunV1(active) && inConversation(active))
         selected.set(active.runId, {
           run: projectClientRunOrDegradedV1(active),
         });
@@ -5471,7 +5481,8 @@ export class ShellBotBackendContribution {
         continue;
       }
       const stored = await this.authority.readStoredRun(candidate.runId);
-      if (!stored || !isVisibleRunV1(stored)) continue;
+      if (!stored || !isVisibleRunV1(stored) || !inConversation(stored))
+        continue;
       const projected = projectClientRunOrDegradedV1(stored);
       const tentative = [
         ...selected.values(),
@@ -5527,6 +5538,36 @@ export class ShellBotBackendContribution {
     }
     return page;
   }
+  /** The conversations this Bot has had, newest first. */
+  async listConversations(): Promise<ClientConversationListV1> {
+    return {
+      schemaVersion: 1,
+      conversations: (await this.authority.listConversations()).map(
+        (conversation) => ({
+          schemaVersion: 1 as const,
+          conversationId: conversation.sessionId,
+          ordinal: conversation.ordinal,
+          startedAt: conversation.startedAt,
+          ...(conversation.endedAt ? { endedAt: conversation.endedAt } : {}),
+        }),
+      ),
+    };
+  }
+
+  /**
+   * Puts this conversation down and starts the next one.
+   *
+   * Memory is untouched: it is not conversation history, and the point of a
+   * new conversation is to prove that it is not.
+   */
+  async startConversation(
+    identity: BotIdentity,
+  ): Promise<ClientConversationListV1> {
+    await this.validateIdentity(identity);
+    await this.authority.startConversation(identity);
+    return this.listConversations();
+  }
+
   async lookupRun(input: unknown): Promise<ClientRunLookupV1> {
     const query = decodeClientRunLookupQueryV1(input);
     return projectClientRunLookupV1(await this.authority.readRun(query.runId));

package/src/client/FrockBotApp.vue

@@ -1189,6 +1189,19 @@ function handleComposerKeydown(event: KeyboardEvent): void {
               @blur="closeSkillPopover"
             />
           </div>
+          <!--
+            Start a new conversation. Sits beside the composer because that is
+            where you are when you decide the last one is finished. Disabled
+            while a Turn is running: the Bot is still writing to it.
+          -->
+          <UiIconButton
+            icon="plus"
+            label="New conversation"
+            variant="ghost"
+            class="new-conversation-button"
+            :disabled="isRunning"
+            @click="web.startConversation()"
+          />
           <UiIconButton
             v-if="showStop"
             class="stop-button"

package/src/client/index.ts

@@ -70,6 +70,8 @@ import { defineComponent, h, ref, toRaw, watch, type Ref } from "vue";
 import {
   frockBotWebDataKey,
   type FrockBotWebData,
+  decodeConnectionReturnV1,
+  withoutConnectionReturnV1,
   type PluginCatalogItem,
   type SendPromptResult,
   type WebActiveRun,
@@ -862,6 +864,15 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
   let admissionObserver: AbortController | undefined;
   let runObserver: AbortController | undefined;
   let selectionGeneration = 0;
+  /*
+   * Which conversation the transcript is showing.
+   *
+   * A read that was already in flight when the User starts a new conversation
+   * answers with the conversation that just ended, and projecting it puts the
+   * old Turns back on a transcript the User has just been told is empty. The
+   * epoch is bumped at the boundary so those answers are dropped.
+   */
+  let conversationGeneration = 0;
   let userSettingsGeneration = 0;
   let pluginCatalogGeneration = 0;
   let packageCatalogGeneration = 0;
@@ -1028,6 +1039,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     if (!ctx.transport.lookupRun) return;
     let delayMs = 250;
     let observationError: string | undefined;
+    const conversation = conversationGeneration;
     while (!signal.aborted) {
       try {
         const run = await observeWhileAttached(
@@ -1037,6 +1049,9 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         if (
           signal.aborted ||
           generation !== selectionGeneration ||
+          // The Turn belongs to the conversation it was sent in, so a new one
+          // ends the observation rather than drawing it on an empty thread.
+          conversation !== conversationGeneration ||
           web.value.activeBotId !== botId
         ) {
           return;
@@ -1064,15 +1079,18 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     botId: string,
     generation = selectionGeneration,
   ): Promise<void> {
+    const conversation = conversationGeneration;
+    const current = () =>
+      generation === selectionGeneration &&
+      conversation === conversationGeneration &&
+      web.value.activeBotId === botId;
     const runs = await (ctx.transport.listRuns?.(botId) ?? Promise.resolve([]));
-    if (generation !== selectionGeneration || web.value.activeBotId !== botId)
-      return;
+    if (!current()) return;
     projectDurableRuns(web.value, [], runs);
     try {
       const announcements = await (ctx.transport.listAnnouncements?.(botId) ??
         Promise.resolve([]));
-      if (generation === selectionGeneration && web.value.activeBotId === botId)
-        projectAnnouncements(web.value.messages, announcements);
+      if (current()) projectAnnouncements(web.value.messages, announcements);
     } catch {
       // Announcements are conversational history, never admission: a Session
       // that cannot read them still shows every Turn.
@@ -1081,17 +1099,14 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     try {
       notifications = await (ctx.transport.listNotifications?.(botId) ??
         Promise.resolve([]));
-      if (generation !== selectionGeneration || web.value.activeBotId !== botId)
-        return;
+      if (!current()) return;
     } catch (error) {
-      if (generation !== selectionGeneration || web.value.activeBotId !== botId)
-        return;
+      if (!current()) return;
       web.value.settingsError =
         error instanceof Error ? error.message : "Could not load notifications";
       return;
     }
-    if (generation !== selectionGeneration || web.value.activeBotId !== botId)
-      return;
+    if (!current()) return;
     const projected = projectDurableRuns(web.value, notifications, runs);
     // A decision may have been recorded on another device since the last poll,
     // and an expiry is recorded by an alarm nobody clicked.
@@ -1099,12 +1114,10 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     // A background subagent settles after its Turn is over, so the chips in
     // the transcript learn what became of it here and not from the run.
     await web.value.loadTasks();
-    if (generation !== selectionGeneration || web.value.activeBotId !== botId)
-      return;
+    if (!current()) return;
     if (!ctx.transport.acknowledgeNotification) return;
     for (const notification of notifications) {
-      if (generation !== selectionGeneration || web.value.activeBotId !== botId)
-        return;
+      if (!current()) return;
       if (!projected.has(notification.notificationId)) {
         web.value.settingsError = "A completed Bot result is waiting to load";
         continue;
@@ -1237,8 +1250,24 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     ): Promise<void>;
   };
 
+  // Read once, from the URL the authorization redirect landed on, and then
+  // stripped so a reload does not report the same return again.
+  const connectionReturn =
+    typeof window === "undefined"
+      ? undefined
+      : decodeConnectionReturnV1(window.location.search);
+  if (connectionReturn && typeof window !== "undefined") {
+    const rest = withoutConnectionReturnV1(window.location.search);
+    window.history?.replaceState?.(
+      window.history.state,
+      "",
+      `${window.location.pathname}${rest}${window.location.hash}`,
+    );
+  }
+
   const web: Ref<ShellWebData> = ref({
     connection: "ready",
+    ...(connectionReturn ? { connectionReturn } : {}),
     modelLabel: "No model available — set one up in Models",
     modelReady: false,
     modelSource: "none",
@@ -1304,6 +1333,41 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       }
       await web.value.loadBotSettings();
     },
+    /**
+     * Puts this conversation down and starts the next one.
+     *
+     * What the Bot knows about you is Memory and stays; what it carries into
+     * the next model request is the new conversation and nothing else. The
+     * transcript clears because it is showing the conversation, and the one
+     * just ended is still durable behind it.
+     */
+    async startConversation(): Promise<void> {
+      const start = ctx.transport.startConversation;
+      const botId = web.value.activeBotId;
+      if (!start || !botId) return;
+      const generation = selectionGeneration;
+      try {
+        await start(botId);
+      } catch (error) {
+        web.value.settingsError =
+          error instanceof Error
+            ? error.message
+            : "Could not start a new conversation";
+        return;
+      }
+      if (generation !== selectionGeneration || web.value.activeBotId !== botId)
+        return;
+      // Reads already in flight answer with the conversation that just ended;
+      // the epoch drops them instead of letting them redraw it.
+      conversationGeneration += 1;
+      runObserver?.abort();
+      runObserver = undefined;
+      web.value.messages = [];
+      web.value.activeRun = undefined;
+      web.value.activeRunId = undefined;
+      web.value.runningRunId = undefined;
+      web.value.settingsError = undefined;
+    },
     async loadSkillCatalog(): Promise<void> {
       // A missing transport method or an unreadable catalog is an empty
       // popover, never a visible error: a Skill list the User did not ask for

package/src/connection-return.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeConnectionReturnV1,
+  withoutConnectionReturnV1,
+} from "./shared.js";
+
+describe("authorization return parameter", () => {
+  test("reads the status the callback redirected with", () => {
+    expect(decodeConnectionReturnV1("?connection=composio-ready")).toEqual({
+      packageId: "composio",
+      status: "ready",
+    });
+    expect(decodeConnectionReturnV1("?connection=composio-pending")).toEqual({
+      packageId: "composio",
+      status: "pending",
+    });
+  });
+
+  test("carries the reason a failed grant came back with", () => {
+    expect(
+      decodeConnectionReturnV1(
+        "?connection=composio-failed&connection_reason=state%20has%20expired",
+      ),
+    ).toEqual({
+      packageId: "composio",
+      status: "failed",
+      reason: "state has expired",
+    });
+  });
+
+  test("ignores a query string that carries no return", () => {
+    expect(decodeConnectionReturnV1("")).toBeUndefined();
+    expect(decodeConnectionReturnV1("?as_user=someone")).toBeUndefined();
+  });
+
+  test("refuses a malformed or unknown return", () => {
+    expect(decodeConnectionReturnV1("?connection=composio")).toBeUndefined();
+    expect(
+      decodeConnectionReturnV1("?connection=composio-elsewhere"),
+    ).toBeUndefined();
+    expect(decodeConnectionReturnV1("?connection=-ready")).toBeUndefined();
+    expect(
+      decodeConnectionReturnV1("?connection=Not%20A%20Package-ready"),
+    ).toBeUndefined();
+  });
+
+  test("strips the return parameters and keeps the rest", () => {
+    expect(
+      withoutConnectionReturnV1(
+        "?as_user=someone&connection=composio-failed&connection_reason=nope",
+      ),
+    ).toBe("?as_user=someone");
+    expect(withoutConnectionReturnV1("?connection=composio-ready")).toBe("");
+  });
+});

package/src/history.test.ts

@@ -78,6 +78,58 @@ function scoped(events: SessionEvent[]): LlmMessage[] {
   });
 }
 
+function scopedWithBudget(events: SessionEvent[], budget: number) {
+  return turnScopedMessagesV1({
+    events,
+    messages: derive(events),
+    pointer: automationParentPointerV1,
+    sessionId: "bot:scout",
+    budget,
+  });
+}
+
+describe("one request carries a bounded amount of history", () => {
+  test("keeps the current Turn whole and drops the oldest, with a notice", () => {
+    const events = log([
+      ...turn(1, "chat", "the oldest thing", "first reply"),
+      ...turn(2, "chat", "the middle thing", "second reply"),
+      ...turn(3, "chat", "the newest thing", ""),
+    ]);
+    // Room for the current Turn and one older one, not for all three.
+    const messages = scopedWithBudget(events, 200);
+
+    const contents = messages.map((message) => message.content);
+    expect(contents).toContain("the newest thing");
+    expect(contents.join(" ")).not.toContain("the oldest thing");
+    expect(contents[0]).toContain("not included here");
+    expect(contents[0]).toContain("1 Turn");
+  });
+
+  test("carries everything when it fits, and says nothing about omission", () => {
+    const events = log([
+      ...turn(1, "chat", "morning", "hello"),
+      ...turn(2, "chat", "anything new?", ""),
+    ]);
+
+    expect(
+      scopedWithBudget(events, 100_000).map((message) => message.content),
+    ).toEqual(["morning", "hello", "anything new?", ""]);
+  });
+
+  test("keeps the current Turn even when it alone exceeds the budget", () => {
+    const events = log([
+      ...turn(1, "chat", "old", "older"),
+      ...turn(2, "chat", "x".repeat(500), ""),
+    ]);
+    const messages = scopedWithBudget(events, 50);
+
+    // A Turn is never split: dropping the user message and keeping the reply
+    // would be a malformed request, so the current Turn survives whole.
+    expect(messages.at(-2)!.content).toBe("x".repeat(500));
+    expect(messages[0]!.content).toContain("not included here");
+  });
+});
+
 describe("turn-scoped prompt history", () => {
   test("a chat Turn sees only the Turns admitted as chat", () => {
     const events = log([

package/src/history.ts

@@ -68,6 +68,76 @@ export interface TurnScopedMessagesInputV1 {
   /** The parent-transcript pointer, used only on a non-chat Turn. */
   pointer(input: { sessionId: string; chatTurns: number }): string;
   sessionId: string;
+  /**
+   * How many characters of history one request may carry. The current Turn is
+   * always whole; older Turns fill what is left. Absent means the default.
+   */
+  budget?: number;
+}
+
+/**
+ * How much conversation one model request carries.
+ *
+ * A number in characters, not tokens: this is a Package policy bound whose job
+ * is to stop a request growing without limit, and it does not need to agree
+ * with any provider's tokenizer to do that. Roughly 150k characters is well
+ * inside every model FrockBot resolves today while being far more history than
+ * any conversation needs.
+ */
+export const CHAT_HISTORY_BUDGET_CHARS_V1 = 150_000;
+
+/**
+ * The line that stands where the dropped Turns were.
+ *
+ * It is said plainly, because a model that cannot see the beginning of a
+ * conversation and is not told so will confidently answer as though it had.
+ */
+export function omittedHistoryNoticeV1(turns: number): string {
+  return `Earlier in this conversation there ${turns === 1 ? "was 1 Turn" : `were ${turns} Turns`} that are not included here. They are not summarised: if you need something from them, say so or search your memory rather than guessing.`;
+}
+
+function messageChars(message: LlmMessage): number {
+  return JSON.stringify(message).length;
+}
+
+/**
+ * Narrows history to a character budget, oldest Turns first.
+ *
+ * Eviction is by whole Turn on purpose. A tool result whose call has been
+ * dropped is a malformed request to every provider, and a Turn is the
+ * smallest unit that always holds both.
+ */
+function budgetedMessagesV1(
+  messages: readonly LlmMessage[],
+  turns: readonly number[],
+  current: number,
+  budget: number,
+): LlmMessage[] {
+  const total = messages.reduce(
+    (sum, message) => sum + messageChars(message),
+    0,
+  );
+  if (total <= budget) return [...messages];
+  const spendByTurn = new Map<number, number>();
+  for (const [index, message] of messages.entries()) {
+    const turn = turns[index]!;
+    spendByTurn.set(turn, (spendByTurn.get(turn) ?? 0) + messageChars(message));
+  }
+  const ordered = [...spendByTurn.keys()].sort((left, right) => right - left);
+  const kept = new Set<number>([current]);
+  let spent = spendByTurn.get(current) ?? 0;
+  for (const turn of ordered) {
+    if (turn === current) continue;
+    const cost = spendByTurn.get(turn) ?? 0;
+    if (spent + cost > budget) break;
+    kept.add(turn);
+    spent += cost;
+  }
+  const dropped = ordered.filter((turn) => !kept.has(turn)).length;
+  const narrowed = messages.filter((_, index) => kept.has(turns[index]!));
+  return dropped === 0
+    ? narrowed
+    : [{ role: "user", content: omittedHistoryNoticeV1(dropped) }, ...narrowed];
 }
 
 /**
@@ -92,7 +162,15 @@ export function turnScopedMessagesV1(
   const current = currentTurnV1(input.events);
   const chatTurn = (turn: number) => (types.get(turn) ?? "chat") === "chat";
   if (chatTurn(current)) {
-    return input.messages.filter((_, index) => chatTurn(turns[index]!));
+    const conversation = input.messages.filter((_, index) =>
+      chatTurn(turns[index]!),
+    );
+    return budgetedMessagesV1(
+      conversation,
+      turns.filter((turn) => chatTurn(turn)),
+      current,
+      input.budget ?? CHAT_HISTORY_BUDGET_CHARS_V1,
+    );
   }
   const own = input.messages.filter((_, index) => turns[index] === current);
   const chatTurns = new Set(

package/src/run-protocol.ts

@@ -36,6 +36,8 @@ const MAX_NOTIFICATION_TITLE_BYTES = 512;
 const MAX_NOTIFICATION_BODY_BYTES = 2_000;
 const MAX_CLIENT_TURN_BYTES = 256_000;
 const MAX_CURSOR_LENGTH = 320;
+/** A conversation is named by its Session id, which the kernel bounds. */
+const MAX_SESSION_ID_LENGTH = 320;
 const MAX_TASK_DESCRIPTION_BYTES = 800;
 const MAX_TASK_MODEL_BYTES = 512;
 export const CLIENT_RUN_PAGE_LIMIT = 32;
@@ -251,9 +253,85 @@ export interface ClientRunListV1 {
   announcements?: ClientAnnouncementV1[];
 }
 
+/**
+ * One conversation a Bot has had.
+ *
+ * A Bot holds one conversation at a time and keeps the ones before it: the
+ * transcript shows the current one, and an earlier one is still readable.
+ */
+export interface ClientConversationV1 {
+  schemaVersion: 1;
+  /** The Session id this conversation's Turns recorded. */
+  conversationId: string;
+  ordinal: number;
+  startedAt: string;
+  /** Absent while this is the conversation the Bot is on. */
+  endedAt?: string;
+}
+
+export interface ClientConversationListV1 {
+  schemaVersion: 1;
+  /** Newest first; the first entry is the conversation the Bot is on. */
+  conversations: ClientConversationV1[];
+}
+
+export function decodeClientConversationListV1(
+  input: unknown,
+): ClientConversationListV1 {
+  const list = record(input, "conversation list");
+  exactKeys(list, ["schemaVersion", "conversations"], "conversation list");
+  if (list.schemaVersion !== 1) {
+    throw new Error("conversation list.schemaVersion is invalid");
+  }
+  if (!Array.isArray(list.conversations)) {
+    throw new Error("conversation list.conversations is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    conversations: list.conversations.map((entry) => {
+      const conversation = record(entry, "conversation");
+      exactKeys(
+        conversation,
+        ["schemaVersion", "conversationId", "ordinal", "startedAt", "endedAt"],
+        "conversation",
+      );
+      if (conversation.schemaVersion !== 1) {
+        throw new Error("conversation.schemaVersion is invalid");
+      }
+      if (
+        typeof conversation.ordinal !== "number" ||
+        !Number.isSafeInteger(conversation.ordinal) ||
+        conversation.ordinal < 1
+      ) {
+        throw new Error("conversation.ordinal is invalid");
+      }
+      return {
+        schemaVersion: 1 as const,
+        conversationId: string(
+          conversation,
+          "conversationId",
+          MAX_SESSION_ID_LENGTH,
+          "conversation",
+        ),
+        ordinal: conversation.ordinal,
+        startedAt: string(conversation, "startedAt", 64, "conversation"),
+        ...(conversation.endedAt === undefined
+          ? {}
+          : { endedAt: string(conversation, "endedAt", 64, "conversation") }),
+      };
+    }),
+  };
+}
+
 export interface ClientRunListQueryV1 {
   schemaVersion: 1;
   before?: string;
+  /**
+   * The conversation to read. Absent means the one the Bot is on now, which
+   * is what the transcript shows; an earlier conversation is named by the
+   * Session id `listConversations` gave for it.
+   */
+  conversationId?: string;
 }
 
 export interface ClientTurnCommandV1 {
@@ -1385,7 +1463,11 @@ export function decodeClientRunListQueryV1(
   input: unknown,
 ): ClientRunListQueryV1 {
   const query = record(input, "run list query");
-  exactKeys(query, ["schemaVersion", "before"], "run list query");
+  exactKeys(
+    query,
+    ["schemaVersion", "before", "conversationId"],
+    "run list query",
+  );
   if (query.schemaVersion !== 1) {
     throw new Error("run list query.schemaVersion is invalid");
   }
@@ -1400,7 +1482,20 @@ export function decodeClientRunListQueryV1(
       throw new Error("run list query.before is invalid");
     }
   }
-  return { schemaVersion: 1, ...(before ? { before } : {}) };
+  const conversationId =
+    query.conversationId === undefined
+      ? undefined
+      : string(
+          query,
+          "conversationId",
+          MAX_SESSION_ID_LENGTH,
+          "run list query",
+        );
+  return {
+    schemaVersion: 1,
+    ...(before ? { before } : {}),
+    ...(conversationId ? { conversationId } : {}),
+  };
 }
 
 export function decodeClientTurnCommandV1(input: unknown): ClientTurnCommandV1 {

package/src/shared.ts

@@ -161,6 +161,60 @@ export interface PluginCatalogItem {
   settings?: PackageSettingDefinition[];
 }
 
+/** What an external authorization redirect told the app on the way back. */
+export interface ConnectionReturnV1 {
+  /** The Package that owns the Connection, e.g. `composio`. */
+  packageId: string;
+  status: "ready" | "pending" | "failed";
+  /** A provider- or callback-supplied explanation, when there is one. */
+  reason?: string;
+}
+
+const CONNECTION_RETURN_PARAM = "connection";
+const CONNECTION_RETURN_REASON_PARAM = "connection_reason";
+const MAX_CONNECTION_RETURN_REASON = 300;
+
+/**
+ * Read an authorization return out of a URL query string.
+ *
+ * The callback redirects to `/?connection=<packageId>-<status>`. Left unread it
+ * is a stale query string and nothing else: the User is returned to the app
+ * with no confirmation, and a `failed` grant vanishes entirely.
+ */
+export function decodeConnectionReturnV1(
+  search: string,
+): ConnectionReturnV1 | undefined {
+  let params: URLSearchParams;
+  try {
+    params = new URLSearchParams(search);
+  } catch {
+    return undefined;
+  }
+  const raw = params.get(CONNECTION_RETURN_PARAM);
+  if (!raw) return undefined;
+  const separator = raw.lastIndexOf("-");
+  if (separator <= 0) return undefined;
+  const packageId = raw.slice(0, separator);
+  const status = raw.slice(separator + 1);
+  if (status !== "ready" && status !== "pending" && status !== "failed") {
+    return undefined;
+  }
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(packageId)) return undefined;
+  const reason = params
+    .get(CONNECTION_RETURN_REASON_PARAM)
+    ?.slice(0, MAX_CONNECTION_RETURN_REASON);
+  return { packageId, status, ...(reason ? { reason } : {}) };
+}
+
+/** The same query string with the return parameters removed. */
+export function withoutConnectionReturnV1(search: string): string {
+  const params = new URLSearchParams(search);
+  params.delete(CONNECTION_RETURN_PARAM);
+  params.delete(CONNECTION_RETURN_REASON_PARAM);
+  const rest = params.toString();
+  return rest ? `?${rest}` : "";
+}
+
 export interface FrockBotWebData {
   connection: WebConnection;
   modelLabel: string;
@@ -261,6 +315,12 @@ export interface FrockBotWebData {
    */
   mcpServers?: McpServerStatusViewV1;
   settingsError?: string;
+  /**
+   * What the browser came back from an external authorization with. Read once
+   * from the return URL at boot and cleared when the User has seen it, so a
+   * cancelled or failed grant is reported rather than silently discarded.
+   */
+  connectionReturn?: ConnectionReturnV1;
   selectBot(botId: string): Promise<void>;
   loadBotSettings(): Promise<void>;
   saveBotProfile(profile: BotProfile): Promise<void>;
@@ -365,6 +425,11 @@ export interface FrockBotWebData {
     values?: Record<string, JsonValue>,
   ): Promise<void>;
   uninstallPackage(packageId: string): Promise<void>;
+  /**
+   * Puts this conversation down and starts the next one. Memory is kept; only
+   * the history the next Turn carries is new (ADR 0027).
+   */
+  startConversation(): Promise<void>;
   startConnection(
     packageId: string,
     connectionTypeId: string,