@frockbot/plugin-shell 0.3.6 → 0.3.8

package/src/debug-protocol.test.ts

@@ -3,6 +3,7 @@ import {
   BOT_DEBUG_RUN_LIMIT_V1,
   boundDebugEventsV1,
   decodeBotDebugQueryV1,
+  isBotDebugQueryRefusalV1,
 } from "./debug-protocol.js";
 
 describe("debug query", () => {
@@ -36,13 +37,48 @@ describe("debug query", () => {
     ).toThrow("debug query has invalid fields");
   });
 
-  test("rejects a limit past the page bound", () => {
+  test("rejects a limit past the page bound, in words that name the range", () => {
     expect(() =>
       decodeBotDebugQueryV1({
         schemaVersion: 1,
         limit: BOT_DEBUG_RUN_LIMIT_V1 + 1,
       }),
-    ).toThrow("debug query limit is invalid");
+    ).toThrow(
+      `debug query limit must be a whole number from 1 to ${BOT_DEBUG_RUN_LIMIT_V1}`,
+    );
+  });
+
+  // The refusal rides on the error's name, which is all a Durable Object RPC
+  // preserves: a bad query has to arrive at the gateway as a 400 and not as
+  // an uncaught failure in the Bot's isolate.
+  test("refuses a bad query as a refusal, not as an ordinary failure", () => {
+    for (const input of [
+      { schemaVersion: 1, limit: 0 },
+      { schemaVersion: 1, limit: BOT_DEBUG_RUN_LIMIT_V1 + 1 },
+      { schemaVersion: 1, limit: 1.5 },
+      { schemaVersion: 1, limit: Number.NaN },
+      { schemaVersion: 1, sql: "select 1" },
+      { schemaVersion: 2 },
+      "not a query",
+    ]) {
+      let refusal: unknown;
+      try {
+        decodeBotDebugQueryV1(input);
+      } catch (error) {
+        refusal = error;
+      }
+      expect(isBotDebugQueryRefusalV1(refusal)).toBe(true);
+    }
+  });
+
+  test("accepts both ends of the allowed range", () => {
+    expect(decodeBotDebugQueryV1({ schemaVersion: 1, limit: 1 }).limit).toBe(1);
+    expect(
+      decodeBotDebugQueryV1({
+        schemaVersion: 1,
+        limit: BOT_DEBUG_RUN_LIMIT_V1,
+      }).limit,
+    ).toBe(BOT_DEBUG_RUN_LIMIT_V1);
   });
 
   test("rejects a wrong schema version", () => {

package/src/debug-protocol.ts

@@ -90,21 +90,50 @@ export interface BotDebugSnapshotV1 {
   nextCursor?: string;
 }
 
+/**
+ * A debug query the caller got wrong: an unknown field, a `limit` past the cap.
+ * The request is what is bad, not the Bot, so the surface owes a 400 rather
+ * than an uncaught failure in the isolate. The name is what carries that
+ * across the Durable Object RPC boundary — which keeps an error's `name` and
+ * `message` and drops everything else — exactly as `BotTurnRefusedError` does
+ * for a refused admission.
+ */
+export class BotDebugQueryRefusedErrorV1 extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BotDebugQueryRefusedErrorV1";
+  }
+}
+
+/** Whether an error — including one that has crossed RPC — is that refusal. */
+export function isBotDebugQueryRefusalV1(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "name" in error &&
+    String((error as { name: unknown }).name) === "BotDebugQueryRefusedErrorV1"
+  );
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 function boundedString(value: unknown, maximum: number, field: string): string {
   if (typeof value !== "string" || value.length < 1 || value.length > maximum) {
-    throw new Error(`debug query ${field} is invalid`);
+    throw new BotDebugQueryRefusedErrorV1(`debug query ${field} is invalid`);
   }
   return value;
 }
 
 export function decodeBotDebugQueryV1(input: unknown): BotDebugQueryV1 {
-  if (!isRecord(input)) throw new Error("debug query is invalid");
+  if (!isRecord(input)) {
+    throw new BotDebugQueryRefusedErrorV1("debug query is invalid");
+  }
   if (input.schemaVersion !== 1) {
-    throw new Error("debug query schemaVersion is invalid");
+    throw new BotDebugQueryRefusedErrorV1(
+      "debug query schemaVersion is invalid",
+    );
   }
   const allowed = new Set([
     "schemaVersion",
@@ -114,7 +143,7 @@ export function decodeBotDebugQueryV1(input: unknown): BotDebugQueryV1 {
     "events",
   ]);
   if (!Object.keys(input).every((key) => allowed.has(key))) {
-    throw new Error("debug query has invalid fields");
+    throw new BotDebugQueryRefusedErrorV1("debug query has invalid fields");
   }
   const query: BotDebugQueryV1 = { schemaVersion: 1 };
   if (input.runId !== undefined) {
@@ -129,13 +158,17 @@ export function decodeBotDebugQueryV1(input: unknown): BotDebugQueryV1 {
       (input.limit as number) < 1 ||
       (input.limit as number) > BOT_DEBUG_RUN_LIMIT_V1
     ) {
-      throw new Error("debug query limit is invalid");
+      throw new BotDebugQueryRefusedErrorV1(
+        `debug query limit must be a whole number from 1 to ${BOT_DEBUG_RUN_LIMIT_V1}`,
+      );
     }
     query.limit = input.limit as number;
   }
   if (input.events !== undefined) {
     if (typeof input.events !== "boolean") {
-      throw new Error("debug query events is invalid");
+      throw new BotDebugQueryRefusedErrorV1(
+        "debug query events must be true or false",
+      );
     }
     query.events = input.events;
   }

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.test.ts

@@ -24,6 +24,7 @@ import {
   projectClientRunV1,
   projectClientRunOrDegradedV1,
   projectClientTurnV1,
+  UNRECORDED_TOOL_RESULT_TEXT_V1,
 } from "./run-protocol.js";
 
 const timestamp = "2026-08-29T00:00:00.000Z";
@@ -1061,14 +1062,59 @@ describe("client run protocol v1", () => {
     expect(() => projectClientRunListV1([storedRun([result])])).toThrow(
       'tool result has no matching occurrence "tool:1:1:0"',
     );
-    expect(() => projectClientRunListV1([storedRun([call])])).toThrow(
-      'terminal run has no result for tool call "tool-1"',
-    );
     expect(() =>
       projectClientRunListV1([storedRun([call, call, result])]),
     ).toThrow('tool occurrence "tool:1:1:0" has duplicate intent');
   });
 
+  // A READ never throws on a record that is already durable. A settled Turn
+  // whose tool call was never settled used to fail the whole transcript
+  // endpoint — a 500 on every later request — so one malformed row bricked the
+  // conversation for ever. It degrades to a row saying nothing was recorded.
+  test("degrades a settled Turn's unsettled tool call instead of throwing", () => {
+    const call = toolEvents(1)[0]!;
+
+    const projected = projectClientRunListV1([storedRun([call])]).runs[0];
+
+    expect(projected?.events).toEqual([
+      { type: "tool/call", call: { id: "tool-1", name: "lookup" } },
+      {
+        type: "tool/result",
+        callId: "tool-1",
+        content: UNRECORDED_TOOL_RESULT_TEXT_V1,
+        isError: true,
+      },
+    ]);
+    // And the degraded row survives the wire decode, which used to refuse it
+    // for the same reason the projection did.
+    expect(
+      decodeClientRunListV1({
+        schemaVersion: 1,
+        runs: [projected],
+        page: { truncated: false },
+      })[0]?.events,
+    ).toHaveLength(2);
+  });
+
+  test("accepts a settled Turn on the wire whose call carries no result", () => {
+    const projected = projectClientRunListV1([storedRun([])]).runs[0]!;
+
+    expect(
+      decodeClientRunListV1({
+        schemaVersion: 1,
+        runs: [
+          {
+            ...projected,
+            events: [
+              { type: "tool/call", call: { id: "tool-1", name: "lookup" } },
+            ],
+          },
+        ],
+        page: { truncated: false },
+      })[0]?.events,
+    ).toEqual([{ type: "tool/call", call: { id: "tool-1", name: "lookup" } }]);
+  });
+
   test("retains pending calls only for nonterminal runs", () => {
     const call = toolEvents(1)[0]!;
     const projected = projectClientRunListV1([storedRun([call], "running")])

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 {
@@ -422,6 +500,14 @@ interface ProjectionUnitV1 {
   droppable: boolean;
 }
 
+/**
+ * What a settled Turn's tool call shows when the durable record holds no
+ * result for it. Same register as the rest of the transcript copy: it tells
+ * the person what is missing rather than naming an occurrence id.
+ */
+export const UNRECORDED_TOOL_RESULT_TEXT_V1 =
+  "No result was recorded for this tool call.";
+
 function dynamicToolCallInput(
   value: unknown,
 ): ClientDynamicToolCallInputV1 | undefined {
@@ -580,12 +666,23 @@ function projectionUnits(
     }
   }
   if (isTerminalRunStatus(status)) {
-    const orphaned = units.find((unit) => !unit.droppable);
-    if (orphaned) {
-      const call = orphaned.events[0] as ClientToolCallV1;
-      throw new Error(
-        `terminal run has no result for tool call "${call.call.id}"`,
-      );
+    for (const unit of units) {
+      if (unit.droppable) continue;
+      // A settled Turn owes every tool call a result, and `Session`'s
+      // interruption repairs now write one. Records already durable from
+      // before that do not have it, and a READ must never throw on them: one
+      // malformed row used to brick the whole transcript endpoint for ever.
+      // The row degrades instead, and says exactly what is missing — not
+      // through `projectClientRunOrDegradedV1`, which throws the whole Turn
+      // away for an unreadable record. Everything else here is readable.
+      const call = unit.events[0] as ClientToolCallV1;
+      unit.events.push({
+        type: "tool/result",
+        callId: call.call.id,
+        content: UNRECORDED_TOOL_RESULT_TEXT_V1,
+        isError: true,
+      });
+      unit.droppable = true;
     }
   }
   return units;
@@ -1059,10 +1156,12 @@ function decodeEvent(value: unknown): ClientRunEventV1 {
   throw new Error("run event.type is invalid");
 }
 
-function decodeEvents(
-  values: unknown[],
-  runStatus: ClientRunStatusV1,
-): ClientTurnEvent[] {
+/**
+ * The event walk a wire run is decoded through. It no longer takes the run's
+ * status: a settled Turn's tool call with no result is a row the projection
+ * has already degraded, not a message to refuse.
+ */
+function decodeEvents(values: unknown[]): ClientTurnEvent[] {
   const events = values.map(decodeEvent);
   let index = 0;
   if (events[0]?.type === "run/events-truncated") index = 1;
@@ -1100,9 +1199,10 @@ function decodeEvents(
       index += 2;
       continue;
     }
-    if (isTerminalRunStatus(runStatus)) {
-      throw new Error(`terminal run has no result for tool call "${id}"`);
-    }
+    // A settled Turn whose call has no result is a degraded row, not a bad
+    // wire message: the projection above already renders it as "no result
+    // recorded", and refusing it here would put the whole transcript behind
+    // one durable record nobody can now repair.
     index += 1;
   }
   return events;
@@ -1252,7 +1352,7 @@ function decodeRun(value: unknown): ClientRun {
     admittedAt,
     input: wireString(run, "input", MAX_INPUT_BYTES, "run"),
     status: runStatus,
-    events: decodeEvents(run.events, runStatus),
+    events: decodeEvents(run.events),
     ...(stopRequestedAt ? { stopRequestedAt } : {}),
     ...(run.queued === true ? { queued: true as const } : {}),
     ...(outcome?.type === "completed" ? { responseText: outcome.text } : {}),
@@ -1376,7 +1476,7 @@ export function decodeClientTurnV1(input: unknown): ClientTurnResponse {
   return {
     runId,
     text: wireString(turn, "text", MAX_OUTCOME_BYTES, "turn"),
-    events: decodeEvents(turn.events, "completed"),
+    events: decodeEvents(turn.events),
     ...(notification ? { notification } : {}),
   };
 }
@@ -1385,7 +1485,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 +1504,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

@@ -107,6 +107,13 @@ export interface WebChatMessage {
    * Bot had already said, which it keeps (ADR 0024).
    */
   notice?: string;
+  /**
+   * The line offers to send the draft again. Set only where the client gave
+   * up on its own — it could not reach the backend — because that is the one
+   * ending the person cannot act on from the thread otherwise: their text is
+   * back in the composer, and this is the button that sends it.
+   */
+  retry?: "resend";
   tools: WebToolActivity[];
   /** The typed payloads this Turn sent to the user, oldest first. */
   sends: WebSendPayload[];
@@ -161,6 +168,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 +322,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 +432,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,