@frockbot/plugin-shell 0.3.6 → 0.3.8

package/src/client/index.ts

@@ -62,6 +62,12 @@ import {
   decodeApprovalDecisionReceiptV1,
   decodeApprovalListViewV1,
 } from "../approvals.js";
+import {
+  isCertainSendRefusalV1,
+  momentAfterV1,
+  uncertainAdmissionDelayMsV1,
+  UNREACHABLE_BOT_MESSAGE_V1,
+} from "./uncertain-admission.js";
 import {
   decodeTaskListViewV1,
   decodeTaskViewV1,
@@ -70,6 +76,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 +870,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;
@@ -965,7 +982,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     botId: string,
     runId: string,
     signal: AbortSignal,
-  ): Promise<"admitted" | "not-admitted" | "detached"> {
+  ): Promise<"admitted" | "not-admitted" | "detached" | "unreachable"> {
     web.value.activeRun = {
       runId,
       status: "running",
@@ -975,7 +992,6 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     if (!ctx.transport.lookupRun || !ctx.transport.fenceRunAdmission) {
       return "detached";
     }
-    let delayMs = 250;
     let reconciliationError: string | undefined;
     const clearReconciliationError = () => {
       if (web.value.settingsError === reconciliationError) {
@@ -983,7 +999,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       }
       reconciliationError = undefined;
     };
-    while (!signal.aborted) {
+    for (let attempt = 1; !signal.aborted; attempt += 1) {
       try {
         const observed = await observeWhileAttached(
           ctx.transport.lookupRun(botId, runId),
@@ -1013,8 +1029,16 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         } Retrying…`;
         web.value.settingsError = reconciliationError;
       }
+      const delayMs = uncertainAdmissionDelayMsV1(attempt);
+      // The bound is spent. Asking again would only keep a placeholder
+      // spinning over a backend this tab cannot reach, so the caller settles
+      // the Turn and says so in the thread.
+      if (delayMs === undefined) {
+        clearReconciliationError();
+        web.value.activeRun = undefined;
+        return "unreachable";
+      }
       await waitForRunLookup(delayMs, signal);
-      delayMs = Math.min(delayMs * 2, 5_000);
     }
     return "detached";
   }
@@ -1028,6 +1052,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 +1062,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 +1092,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 +1112,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 +1127,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 +1263,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 +1346,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
@@ -2470,14 +2547,39 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
           web.value.error = refusal;
           return { accepted: false, error: refusal };
         }
+        // Every other 4xx is a refusal too, and the answer already says why —
+        // a message over the size limit is answered 413 with the sentence the
+        // person needs. Only 5xx and a lost connection leave admission in
+        // doubt, so anything else here is settled: no optimistic bubbles, no
+        // "checking" placeholder, no reconciliation, and the composer gets the
+        // draft back rather than the thread pretending it was sent.
+        if (isCertainSendRefusalV1(error)) {
+          removeMessages(web.value.messages, pendingRunId);
+          const refusal =
+            error instanceof Error && error.message
+              ? error.message
+              : "That message didn't go through. Try sending it again.";
+          web.value.error = refusal;
+          return { accepted: false, error: refusal };
+        }
         const aborted =
           error instanceof DOMException && error.name === "AbortError";
+        // Strictly after the message it reports on. The thread orders by time,
+        // and the durable projection gives the user's line the run's later
+        // `admittedAt`, so a placeholder carrying the moment the send began
+        // sorted above the message it belongs to.
+        const placeholderAt = momentAfterV1(
+          web.value.messages.find(
+            (message) =>
+              message.runId === pendingRunId && message.role === "user",
+          )?.at ?? optimisticAt,
+        );
         replaceMessage(web.value.messages, pendingRunId, {
           id: `${pendingRunId}:assistant`,
           runId: pendingRunId,
           role: "assistant",
           text: "Checking whether your message went through…",
-          at: optimisticAt,
+          at: placeholderAt,
           status: "interrupted",
           tools: [],
           sends: [],
@@ -2490,7 +2592,8 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         }
         const observer = new AbortController();
         admissionObserver = observer;
-        let disposition: "admitted" | "not-admitted" | "detached";
+        let disposition:
+          "admitted" | "not-admitted" | "detached" | "unreachable";
         try {
           disposition = await reconcileUncertainAdmission(
             botId,
@@ -2500,13 +2603,40 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         } finally {
           if (admissionObserver === observer) admissionObserver = undefined;
         }
+        // The reconciliation ran out of attempts: this tab cannot reach the
+        // backend at all. That is the app's own failure and it says so, in
+        // place of the placeholder, with the Retry the person would otherwise
+        // have to improvise — and with the Turn no longer running, so Stop
+        // stops standing for a Turn nobody is executing.
+        if (disposition === "unreachable") {
+          replaceMessage(web.value.messages, pendingRunId, {
+            id: `${pendingRunId}:assistant`,
+            runId: pendingRunId,
+            role: "assistant",
+            text: UNREACHABLE_BOT_MESSAGE_V1,
+            at: placeholderAt,
+            status: "error",
+            retry: "resend",
+            tools: [],
+            sends: [],
+          });
+          // The bubble is the report, and it is the one carrying the Retry.
+          // Saying the same sentence again in the banner above it is what the
+          // thread already looked like when it was broken — the same string
+          // three times over — so the banner is cleared rather than set.
+          web.value.error = undefined;
+          web.value.activeRun = undefined;
+          web.value.activeRunId = undefined;
+          web.value.runningRunId = undefined;
+          return { accepted: false, error: UNREACHABLE_BOT_MESSAGE_V1 };
+        }
         if (disposition === "not-admitted") {
           replaceMessage(web.value.messages, pendingRunId, {
             id: `${pendingRunId}:assistant`,
             runId: pendingRunId,
             role: "assistant",
             text: "Your message didn't go through. Try sending it again.",
-            at: optimisticAt,
+            at: placeholderAt,
             status: "error",
             tools: [],
             sends: [],

package/src/client/styles.css

@@ -301,6 +301,28 @@
   font-size: var(--frock-text-xs);
 }
 
+/*
+ * The way back from an ending the thread cannot recover on its own: the client
+ * gave up reaching the Bot, and the draft it handed back is one click from
+ * being sent again.
+ */
+.message-retry {
+  align-self: flex-start;
+  margin-top: 4px;
+  padding: 4px 10px;
+  border: 1px solid var(--frock-danger-border);
+  border-radius: var(--frock-radius-control);
+  color: var(--frock-danger-text);
+  background: transparent;
+  font-size: var(--frock-text-xs);
+  cursor: pointer;
+}
+
+.message-retry:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+
 /*
  * An assistant Turn is its avatar and, beside it, one column holding
  * everything the Turn produced. The row has exactly two children: bubbles,
@@ -720,6 +742,18 @@
   gap: 6px;
 }
 
+/* Only ever on screen near the limit, so it sits under the text it counts. */
+.composer-counter {
+  margin: 0;
+  align-self: flex-end;
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-xs);
+}
+
+.composer-counter-over {
+  color: var(--frock-danger-text);
+}
+
 .skill-chips {
   display: flex;
   margin: 0;

package/src/client/turn-limits.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import {
+  TURN_TEXT_COUNTER_FROM_V1,
+  TURN_TEXT_MAX_CHARACTERS_V1,
+  turnTextCounterVisibleV1,
+  turnTextRemainingV1,
+  turnTextTooLongV1,
+} from "./turn-limits.js";
+
+describe("the composer's copy of the send limit", () => {
+  test("mirrors the number the send route refuses on", () => {
+    // The gateway's `TURN_TEXT_MAX_CHARACTERS_V1`. Pinned here because the two
+    // are only equal by intent: the client cannot import the Worker's module.
+    expect(TURN_TEXT_MAX_CHARACTERS_V1).toBe(32_000);
+  });
+
+  test("is quiet until the budget is nearly spent", () => {
+    expect(turnTextCounterVisibleV1("a short message")).toBe(false);
+    expect(
+      turnTextCounterVisibleV1("x".repeat(TURN_TEXT_COUNTER_FROM_V1)),
+    ).toBe(true);
+  });
+
+  test("counts down, then counts the overflow", () => {
+    expect(turnTextRemainingV1("x".repeat(TURN_TEXT_MAX_CHARACTERS_V1))).toBe(
+      0,
+    );
+    expect(
+      turnTextRemainingV1("x".repeat(TURN_TEXT_MAX_CHARACTERS_V1 + 5)),
+    ).toBe(-5);
+  });
+
+  test("refuses only past the limit, never at it", () => {
+    expect(turnTextTooLongV1("x".repeat(TURN_TEXT_MAX_CHARACTERS_V1))).toBe(
+      false,
+    );
+    expect(turnTextTooLongV1("x".repeat(TURN_TEXT_MAX_CHARACTERS_V1 + 1))).toBe(
+      true,
+    );
+  });
+});

package/src/client/turn-limits.ts

@@ -0,0 +1,40 @@
+/**
+ * The composer's copy of the send route's size rule.
+ *
+ * The gateway refuses an oversized Turn with 413 before it ever reaches a Bot
+ * (`TURN_TEXT_MAX_CHARACTERS_V1` in the Cloudflare application's
+ * `request-body.ts`). A refusal the person could have seen coming is a bad
+ * refusal, so the composer enforces the same number: it counts down as the
+ * limit comes into reach and refuses to send past it, and the server's rule
+ * stays the authority for anything that reaches it another way.
+ *
+ * One constant rather than a literal at each use, because a limit written
+ * twice is a limit that drifts.
+ */
+export const TURN_TEXT_MAX_CHARACTERS_V1 = 32_000;
+
+/**
+ * Where the counter appears.
+ *
+ * A character count beside a half-written sentence is noise; it is only news
+ * as the budget runs out. The last tenth is where a person can still act on
+ * it — trim a paragraph, split the message — before the send button closes.
+ */
+export const TURN_TEXT_COUNTER_FROM_V1 = Math.floor(
+  TURN_TEXT_MAX_CHARACTERS_V1 * 0.9,
+);
+
+/** How much of the budget is left; negative once the draft is over it. */
+export function turnTextRemainingV1(text: string): number {
+  return TURN_TEXT_MAX_CHARACTERS_V1 - text.length;
+}
+
+/** True once the draft is longer than the send route would accept. */
+export function turnTextTooLongV1(text: string): boolean {
+  return turnTextRemainingV1(text) < 0;
+}
+
+/** True once the count is worth showing. */
+export function turnTextCounterVisibleV1(text: string): boolean {
+  return text.length >= TURN_TEXT_COUNTER_FROM_V1;
+}

package/src/client/uncertain-admission.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import {
+  isCertainSendRefusalV1,
+  momentAfterV1,
+  uncertainAdmissionDelayMsV1,
+  UNCERTAIN_ADMISSION_MAX_ATTEMPTS_V1,
+  UNREACHABLE_BOT_MESSAGE_V1,
+} from "./uncertain-admission.js";
+
+describe("telling a refusal from a doubt", () => {
+  test("a 4xx is certain and a 5xx is not", () => {
+    const refused = Object.assign(new Error("Your message is too long."), {
+      status: 413,
+    });
+    const failed = Object.assign(new Error("Agent request failed"), {
+      status: 500,
+    });
+    expect(isCertainSendRefusalV1(refused)).toBe(true);
+    expect(isCertainSendRefusalV1(failed)).toBe(false);
+  });
+
+  test("an error with no status is a doubt", () => {
+    // What a dropped connection throws: no answer was read, so nothing about
+    // the send is settled.
+    expect(isCertainSendRefusalV1(new TypeError("Failed to fetch"))).toBe(
+      false,
+    );
+    expect(isCertainSendRefusalV1(undefined)).toBe(false);
+    expect(isCertainSendRefusalV1({ status: "413" })).toBe(false);
+  });
+});
+
+describe("the admission retry bound", () => {
+  test("backs off and then stops asking", () => {
+    const delays = Array.from(
+      { length: UNCERTAIN_ADMISSION_MAX_ATTEMPTS_V1 },
+      (_unused, index) => uncertainAdmissionDelayMsV1(index + 1),
+    );
+    // Five waits between six attempts, doubling; the sixth attempt is the last
+    // one, so it is followed by no wait at all.
+    expect(delays).toEqual([250, 500, 1_000, 2_000, 4_000, undefined]);
+  });
+
+  test("never waits past the ceiling", () => {
+    expect(uncertainAdmissionDelayMsV1(1)).toBe(250);
+    for (let attempt = 1; attempt <= 20; attempt += 1) {
+      const delay = uncertainAdmissionDelayMsV1(attempt);
+      if (delay === undefined) continue;
+      expect(delay).toBeLessThanOrEqual(5_000);
+    }
+  });
+
+  test("the terminal copy names the app's own failure", () => {
+    expect(UNREACHABLE_BOT_MESSAGE_V1).toContain("Couldn't reach the Bot");
+  });
+});
+
+describe("placing a line after the one it reports on", () => {
+  test("is strictly later, and stays sortable as a string", () => {
+    const at = "2026-09-01T00:01:00.000Z";
+    const after = momentAfterV1(at);
+    expect(after > at).toBe(true);
+    expect(after).toBe("2026-09-01T00:01:00.001Z");
+  });
+
+  test("leaves a timestamp it cannot read alone", () => {
+    expect(momentAfterV1("not a time")).toBe("not a time");
+  });
+});

package/src/client/uncertain-admission.ts

@@ -0,0 +1,78 @@
+/**
+ * What a send means when the answer was not a Turn.
+ *
+ * There are two of those and they are not alike. A 4xx is the server having
+ * read the request and decided against it: the Turn does not exist, will not
+ * exist, and the answer says why. Everything else — a 5xx, a socket that
+ * closed, a browser that lost the network — leaves admission genuinely
+ * unknown, and only that case is worth reconciling.
+ *
+ * Telling them apart is the whole point. Treating a 413 as unknown drew the
+ * person's oversized draft into the thread as though it had been sent, then
+ * polled for a run that was never admitted.
+ */
+
+/**
+ * True when the transport's error carries a 4xx: a refusal, not a doubt.
+ *
+ * Duck-typed on `status` rather than on an error class, because the transport
+ * is an interface with more than one implementation and a plain `Error` with a
+ * status is all any of them can be relied on to throw.
+ */
+export function isCertainSendRefusalV1(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  if (!("status" in error)) return false;
+  const status = error.status;
+  return typeof status === "number" && status >= 400 && status < 500;
+}
+
+/**
+ * How many times admission reconciliation asks before it stops asking.
+ *
+ * A bound rather than an ever-retrying loop: a backend the tab cannot reach
+ * does not become reachable by being asked a thousand times, and the person
+ * watching a placeholder deserves an answer inside a few seconds. Six attempts
+ * over the schedule below spans roughly eight seconds, which covers a Worker
+ * cold start and a brief network blip without outliving anybody's patience.
+ */
+export const UNCERTAIN_ADMISSION_MAX_ATTEMPTS_V1 = 6;
+
+const FIRST_DELAY_MS_V1 = 250;
+const MAX_DELAY_MS_V1 = 5_000;
+
+/**
+ * How long to wait before attempt `attempt + 1`, or `undefined` once the bound
+ * is spent and the client should settle instead of asking again.
+ */
+export function uncertainAdmissionDelayMsV1(
+  attempt: number,
+): number | undefined {
+  if (attempt >= UNCERTAIN_ADMISSION_MAX_ATTEMPTS_V1) return undefined;
+  return Math.min(FIRST_DELAY_MS_V1 * 2 ** (attempt - 1), MAX_DELAY_MS_V1);
+}
+
+/**
+ * What the thread says when the client gave up reaching the backend.
+ *
+ * Naming the app's own failure, because nothing else in the product did: every
+ * other line blames the message or the Bot, and a person whose wifi dropped
+ * was told their message "didn't go through" as though the Bot had refused it.
+ */
+export const UNREACHABLE_BOT_MESSAGE_V1 =
+  "Couldn't reach the Bot. Check your connection and try again.";
+
+/**
+ * A timestamp one millisecond after `at`.
+ *
+ * The thread sorts by time, so a line that belongs under another needs a time
+ * of its own: the placeholder used to carry the moment the send *began*, which
+ * put it above the message it was reporting on the instant the durable
+ * projection gave that message its later `admittedAt`.
+ */
+export function momentAfterV1(at: string): string {
+  const moment = new Date(at).getTime();
+  // An unparsable timestamp is not worth inventing an order for; the thread's
+  // insertion order still holds the line where it was put.
+  if (!Number.isFinite(moment)) return at;
+  return new Date(moment + 1).toISOString();
+}

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("");
+  });
+});