@frockbot/plugin-shell 0.3.5 → 0.3.7

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;
@@ -179,7 +181,12 @@ export interface ClientDynamicToolCallInputV1 {
 
 export type ClientRunOutcomeV1 =
   | { type: "completed"; text: string }
-  | { type: "failed"; message: string }
+  /**
+   * A Turn that broke keeps what it had already said, for the same reason a
+   * stopped one does: the words arrived, the person read them, and replacing
+   * them with a notice would rewrite what they watched happen (ADR 0028).
+   */
+  | { type: "failed"; message: string; text?: string }
   /**
    * A Turn a Stop or a later message ended keeps what it had already said:
    * `text` is that partial answer, and `message` is the line saying why it
@@ -246,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 {
@@ -673,6 +756,7 @@ export function projectClientRunV1(run: StoredRun): ClientRunV1 {
               run.failure ?? "Agent request failed.",
               MAX_FAILURE_BYTES,
             ),
+            ...interruptedOutcomeTextV1(run),
           } satisfies ClientRunOutcomeV1)
         : status === "cancelled"
           ? ({
@@ -1121,10 +1205,11 @@ function decodeOutcome(
     };
   }
   if (outcome.type === "failed" && runStatus === "failed") {
-    exactKeys(outcome, ["type", "message"], "run.outcome");
+    exactKeys(outcome, ["type", "message", "text"], "run.outcome");
     return {
       type: "failed",
       message: wireString(outcome, "message", MAX_FAILURE_BYTES, "run.outcome"),
+      ...decodeInterruptedTextV1(outcome),
     };
   }
   if (outcome.type === "cancelled" && runStatus === "cancelled") {
@@ -1249,7 +1334,12 @@ function decodeRun(value: unknown): ClientRun {
     ...(stopRequestedAt ? { stopRequestedAt } : {}),
     ...(run.queued === true ? { queued: true as const } : {}),
     ...(outcome?.type === "completed" ? { responseText: outcome.text } : {}),
-    ...(outcome?.type === "failed" ? { failure: outcome.message } : {}),
+    ...(outcome?.type === "failed"
+      ? {
+          failure: outcome.message,
+          ...(outcome.text ? { responseText: outcome.text } : {}),
+        }
+      : {}),
     ...(outcome?.type === "cancelled" || outcome?.type === "superseded"
       ? {
           failure: outcome.message,
@@ -1373,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");
   }
@@ -1388,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,