@frockbot/plugin-shell 0.3.5 → 0.3.7

package/src/client/index.ts

@@ -55,6 +55,7 @@ import { decodeStartConnectionResultV1 } from "@frockbot/connection-core";
 import { decodeClientSkillCatalogV1 } from "../skill-protocol.js";
 import {
   ClientTurnRefusedErrorV1,
+  type ClientTurnRefusalReasonV1,
   decodeClientTurnV1,
 } from "../run-protocol.js";
 import {
@@ -69,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,
@@ -243,10 +246,8 @@ function activeRunView(run: ClientRun): WebActiveRun | undefined {
       runId: run.runId,
       status: run.status,
       message: run.stopRequestedAt
-        ? "Stop accepted; reconciling the provider outcome before cancelling."
-        : (run.recovery?.message ??
-          run.failure ??
-          "This Turn requires provider reconciliation before it can continue."),
+        ? "Stopping…"
+        : "Something went wrong mid-reply. Try again to pick it up.",
       // Offered whenever the run is parked, Stop included. Hiding it there
       // hid it in exactly the case Stop creates: a Turn that was stopped
       // while the model was mid-answer parks, and the person was left with a
@@ -257,6 +258,31 @@ function activeRunView(run: ClientRun): WebActiveRun | undefined {
   return undefined;
 }
 
+/**
+ * What a refused send tells the person. The refusal's own `error` names the
+ * durable invariant that declined it, which the debug surface needs and the
+ * composer does not, so the typed reason picks the sentence instead.
+ */
+function turnRefusalCopyV1(reason: ClientTurnRefusalReasonV1): string {
+  if (reason === "busy")
+    return "This Bot is still working on your last message.";
+  if (reason === "reconciliation-required")
+    return "This Bot's last reply stopped partway. Try again to continue it.";
+  if (reason === "duplicate") return "That message was already sent.";
+  return "That message didn't go through. Try sending it again.";
+}
+
+/**
+ * The Bot's voice is its sends. When a Turn delivered anything to the User the
+ * model's own assistant text is scratch space and the thread does not draw it
+ * (issue 153): drawing both is how a one-word reply arrived twice, once as the
+ * model's text and once as the bubble that was actually delivered.
+ */
+function visibleAssistantText(run: ClientRun, fallback = ""): string {
+  if (sendsFrom(run.events).length > 0) return "";
+  return run.responseText ?? fallback;
+}
+
 function isTerminalRun(run: ClientRun): boolean {
   return (
     run.status === "completed" ||
@@ -277,7 +303,7 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text: run.responseText ?? "",
+      text: visibleAssistantText(run),
       status: "streaming",
       // A Turn that has not started shows nothing of its own: the greyed user
       // message is the whole of what the thread says about it.
@@ -294,8 +320,8 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text: run.responseText ?? "",
-      notice: run.failure ?? "Interrupted by your next message.",
+      text: visibleAssistantText(run),
+      notice: "Interrupted by your next message.",
       status: "aborted",
       tools: toolsFrom(run.events),
       sends: sendsFrom(run.events),
@@ -307,10 +333,7 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text:
-        run.recovery?.message ??
-        run.failure ??
-        "Provider reconciliation is required before this Turn can continue.",
+      text: "This reply stopped partway. Try again to continue it.",
       status: "reconciliation-required",
       tools: toolsFrom(run.events),
       sends: sendsFrom(run.events),
@@ -322,22 +345,39 @@ function assistantMessage(
       id: `${run.runId}:assistant`,
       runId: run.runId,
       role: "assistant",
-      text: run.responseText ?? "",
-      notice: run.failure ?? "Stopped by an authenticated Stop command.",
+      text: visibleAssistantText(run),
+      notice: "You stopped this.",
       status: "aborted",
       tools: toolsFrom(run.events),
       sends: sendsFrom(run.events),
       tasks: tasksFrom(run.events),
     };
   }
+  // A Turn that broke after it had started talking keeps what it said, with
+  // the reason underneath it — the treatment a stopped Turn already gets, for
+  // the same reason: the words arrived and the person read them (ADR 0028).
+  // A Turn that broke before saying anything is still just the reason.
+  if (run.status === "failed" && run.responseText) {
+    return {
+      id: `${run.runId}:assistant`,
+      runId: run.runId,
+      role: "assistant",
+      text: run.responseText,
+      notice: run.failure ?? "Agent request failed.",
+      status: "error",
+      tools: toolsFrom(run.events),
+      sends: sendsFrom(run.events),
+      tasks: tasksFrom(run.events),
+    };
+  }
   return {
     id: `${run.runId}:assistant`,
     runId: run.runId,
     role: "assistant",
     text:
       run.status === "failed"
-        ? (run.failure ?? "Agent request failed.")
-        : (run.responseText ?? notification?.body ?? ""),
+        ? "This Bot couldn't finish its reply. Try again."
+        : visibleAssistantText(run, notification?.body ?? ""),
     status: run.status === "failed" ? "error" : "completed",
     tools: toolsFrom(run.events),
     sends: sendsFrom(run.events),
@@ -429,8 +469,12 @@ export function projectDurableRuns(
     activeRun = activeRunView(run) ?? activeRun;
     if (run.status === "running" || run.status === "reconciliation-required") {
       busyRunId = run.runId;
-      if (!run.queued) runningRunId = run.runId;
     }
+    // Stop belongs to a Turn that is executing. A Turn parked on a
+    // reconciliation is busy but not running: there is nothing to stop, and
+    // offering it left a Stop button standing for good — across reloads,
+    // because the state it was keyed off never became terminal.
+    if (run.status === "running" && !run.queued) runningRunId = run.runId;
     if (notification && isTerminalRun(run)) {
       projected.add(notification.notificationId);
     }
@@ -448,7 +492,13 @@ export function projectDurableRuns(
     state.activeRunId = undefined;
   }
   if (runningRunId) state.runningRunId = runningRunId;
-  else if (state.runningRunId && terminalRunIds.has(state.runningRunId)) {
+  else if (
+    state.runningRunId &&
+    runs.some((run) => run.runId === state.runningRunId)
+  ) {
+    // The channel is carrying this run and it is not executing, whatever it
+    // settled as. A run the list does not carry yet is the one this tab just
+    // submitted, which keeps its Stop.
     state.runningRunId = undefined;
   }
   if (activeRun) state.activeRun = activeRun;
@@ -704,7 +754,7 @@ export function decodePluginCatalog(value: unknown): PluginCatalogItem[] {
     !Array.isArray(value.packages) ||
     value.packages.length > 256
   ) {
-    throw new Error("Application manifest is invalid");
+    throw new Error("FrockBot couldn't load this deployment. Reload the page.");
   }
   return value.packages.flatMap((candidate) => {
     if (
@@ -737,7 +787,9 @@ export function decodePluginCatalog(value: unknown): PluginCatalogItem[] {
           kind === "mobile",
       )
     ) {
-      throw new Error("Application Package metadata is invalid");
+      throw new Error(
+        "FrockBot couldn't load this deployment. Reload the page.",
+      );
     }
     const decoded = decodeFrockBotManifest({
       // v4, so a Capability carrying an admission ceiling decodes here too.
@@ -812,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;
@@ -919,7 +980,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     web.value.activeRun = {
       runId,
       status: "running",
-      message: "Confirming whether this Turn was admitted.",
+      message: "Checking whether your message went through…",
       canResume: false,
     };
     if (!ctx.transport.lookupRun || !ctx.transport.fenceRunAdmission) {
@@ -959,7 +1020,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         reconciliationError = `${
           error instanceof Error
             ? error.message
-            : "Turn admission lookup failed"
+            : "Couldn't check on your message."
         } Retrying…`;
         web.value.settingsError = reconciliationError;
       }
@@ -978,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(
@@ -987,11 +1049,14 @@ 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;
         }
-        if (!run) throw new Error("Stopped Turn is unavailable");
+        if (!run) throw new Error("Couldn't load that reply.");
         if (web.value.settingsError === observationError) {
           web.value.settingsError = undefined;
         }
@@ -1001,7 +1066,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       } catch (error) {
         if (signal.aborted) return;
         observationError = `${
-          error instanceof Error ? error.message : "Turn lookup failed"
+          error instanceof Error ? error.message : "Couldn't load that reply."
         } Retrying…`;
         web.value.settingsError = observationError;
       }
@@ -1014,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.
@@ -1031,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.
@@ -1049,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;
@@ -1187,9 +1250,25 @@ 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",
-    modelLabel: "Model unavailable",
+    ...(connectionReturn ? { connectionReturn } : {}),
+    modelLabel: "No model available — set one up in Models",
     modelReady: false,
     modelSource: "none",
     settingsAvailable: true,
@@ -1254,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
@@ -1519,12 +1633,10 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       const botId = web.value.activeBotId;
       const catalog = web.value.packageUi;
       if (!post || !botId || !catalog || catalog.botId !== botId) {
-        throw new Error("Package UI is unavailable");
+        throw new Error("That plugin's page isn't available.");
       }
       if (!packageIframeToolAllowedV1(contribution, name)) {
-        throw new Error(
-          `Package "${contribution.packageId}" did not declare tool "${name}"`,
-        );
+        throw new Error(`That plugin isn't allowed to use ${name}.`);
       }
       const turn = decodeClientTurnV1(
         await post(
@@ -1951,9 +2063,22 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         updateSettingsLoadError("package-catalog");
       } catch (error) {
         if (generation !== packageCatalogGeneration) return;
+        // The gateway answers 404 `catalog generation was not found` when the
+        // deployment has published no Catalog at all. That is a state, not a
+        // fault, and the raw server sentence means nothing to a person — so it
+        // is translated here and the surface renders it instead of the
+        // "nothing matched your search" empty state.
+        const raw =
+          error instanceof Error ? error.message : "Could not load the Catalog";
+        web.value.packageCatalog = [];
+        web.value.packageCatalogGeneration = undefined;
         updateSettingsLoadError(
           "package-catalog",
-          error instanceof Error ? error.message : "Could not load the Catalog",
+          /catalog generation was not found|Package Catalog is not configured/.test(
+            raw,
+          )
+            ? "No plugins are published for this deployment yet."
+            : `Plugins could not be loaded: ${raw}`,
         );
       }
     },
@@ -1983,7 +2108,8 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       if (!settings || !ctx.transport.executeConfiguration) {
         throw new Error("Plugins are unavailable");
       }
-      if (!generation) throw new Error("The Catalog generation is unknown");
+      if (!generation)
+        throw new Error("The catalog isn't loaded yet. Try again in a moment.");
       const receipt = await ctx.transport.executeConfiguration({
         schemaVersion: 1,
         type: "user/install-package",
@@ -2266,8 +2392,8 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
       if (result.status !== "applied") {
         throw new Error(
           result.status === "reconciliation-required"
-            ? "Connection revocation requires reconciliation"
-            : "Connection revocation failed",
+            ? "Disconnecting didn't finish. Try again."
+            : "Couldn't disconnect that account.",
         );
       }
     },
@@ -2370,7 +2496,10 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
           id: `${result.runId}:assistant`,
           runId: result.runId,
           role: "assistant",
-          text: result.text,
+          // The same rule the durable projection follows: a Turn that
+          // delivered something speaks through its sends, not through the
+          // model's own text (issue 153).
+          text: sendsFrom(result.events).length > 0 ? "" : result.text,
           at: optimisticAt,
           status: "completed",
           tools: toolsFrom(result.events),
@@ -2401,8 +2530,9 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         // that was never admitted only threw the reason away.
         if (error instanceof ClientTurnRefusedErrorV1) {
           removeMessages(web.value.messages, pendingRunId);
-          web.value.error = error.refusal.error;
-          return { accepted: false, error: error.refusal.error };
+          const refusal = turnRefusalCopyV1(error.refusal.reason);
+          web.value.error = refusal;
+          return { accepted: false, error: refusal };
         }
         const aborted =
           error instanceof DOMException && error.name === "AbortError";
@@ -2410,9 +2540,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
           id: `${pendingRunId}:assistant`,
           runId: pendingRunId,
           role: "assistant",
-          text: aborted
-            ? "Request stopped locally; checking whether it started."
-            : "Confirming whether this Turn was admitted.",
+          text: "Checking whether your message went through…",
           at: optimisticAt,
           status: "interrupted",
           tools: [],
@@ -2441,14 +2569,18 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
             id: `${pendingRunId}:assistant`,
             runId: pendingRunId,
             role: "assistant",
-            text: "Turn was not admitted.",
+            text: "Your message didn't go through. Try sending it again.",
             at: optimisticAt,
             status: "error",
             tools: [],
             sends: [],
           });
-          web.value.error = "Turn was not admitted";
-          return { accepted: false, error: "Turn was not admitted" };
+          web.value.error =
+            "Your message didn't go through. Try sending it again.";
+          return {
+            accepted: false,
+            error: "Your message didn't go through. Try sending it again.",
+          };
         }
         return { accepted: true, runId: pendingRunId };
       } finally {
@@ -2471,14 +2603,14 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
     },
     async resumeRun(runId: string): Promise<void> {
       if (!ctx.transport.reconcileRun) {
-        web.value.settingsError = "Turn reconciliation is unavailable";
+        web.value.settingsError = "Can't retry this right now.";
         return;
       }
       if (web.value.activeRun?.runId !== runId) return;
       web.value.activeRun = {
         runId,
         status: "running",
-        message: "Reconciliation requested; checking progress.",
+        message: "Retrying…",
         canResume: false,
       };
       const botId = web.value.activeBotId;
@@ -2487,7 +2619,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         await ctx.transport.reconcileRun(botId, runId);
       } catch (error) {
         web.value.settingsError =
-          error instanceof Error ? error.message : "Reconciliation failed";
+          error instanceof Error ? error.message : "Couldn't retry that.";
       }
       try {
         await deliverNotifications(botId);
@@ -2495,7 +2627,7 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
         web.value.settingsError =
           error instanceof Error
             ? error.message
-            : "Could not refresh the reconciled Turn";
+            : "Couldn't refresh this reply.";
       }
     },
     async stopRun(): Promise<void> {

package/src/client/model-presentation.test.ts

@@ -31,12 +31,14 @@ describe("model runtime presentation", () => {
       "Llama 3 · Ollama Cloud · Account model",
     );
     expect(modelRuntimeLabel({ ...label, source: "bot" })).toBe(
-      "Llama 3 · Ollama Cloud · Bot override",
+      "Llama 3 · Ollama Cloud · this Bot only",
     );
   });
 
   test("shows unavailable and backend failure states", () => {
-    expect(modelRuntimeLabel({ source: "none" })).toBe("Model unavailable");
+    expect(modelRuntimeLabel({ source: "none" })).toBe(
+      "No model available — set one up in Models",
+    );
     expect(
       modelRuntimeLabel({
         source: "account",

package/src/client/model-presentation.ts

@@ -14,13 +14,13 @@ export function modelRuntimeLabel(input: {
 }): string {
   if (input.failure) return input.failure;
   if (input.source === "none" || !input.providerModelId) {
-    return "Model unavailable";
+    return "No model available — set one up in Models";
   }
   const model =
     input.modelDisplayName ?? input.providerModelId ?? "Connected model";
   const provider = input.packageDisplayName ?? input.connectionDisplayName;
   const runtime = provider ? `${model} · ${provider}` : model;
-  if (input.source === "bot") return `${runtime} · Bot override`;
+  if (input.source === "bot") return `${runtime} · this Bot only`;
   if (input.source === "account") return `${runtime} · Account model`;
   return runtime;
 }

package/src/client/styles.css

@@ -301,13 +301,27 @@
   font-size: var(--frock-text-xs);
 }
 
-/* An assistant Turn is its avatar and, once there is text, its bubble. */
+/*
+ * An assistant Turn is its avatar and, beside it, one column holding
+ * everything the Turn produced. The row has exactly two children: bubbles,
+ * notices, sends and chips stack inside the column, so a one-word reply is a
+ * bubble the width of its word rather than a sliver of a shared row.
+ */
 .message-assistant {
   flex-direction: row;
   align-items: flex-start;
   gap: 8px;
 }
 
+.message-column {
+  display: flex;
+  min-width: 0;
+  flex: 1 1 auto;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 6px;
+}
+
 .bot-avatar {
   position: relative;
   display: grid;

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