@cosmoops/connect-sdk 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -3,6 +3,130 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.42.0
+
+### Ask AI explains failures instead of printing them
+
+Nothing to wire - update and the panel behaves better on a bad day.
+
+- **A tool step that fails says so where its result would have been.** When
+  Connect cannot reach your application's MCP server - it is down, deploying,
+  or timing out - the step renders a short inline notice such as
+  *"CosmoOps CRM can't be reached right now, so nothing was looked up. Try
+  again in a few minutes."*, and the assistant answers in the same plain
+  words. It used to answer `TypeError: fetch failed`. Your own MCP server's
+  refusals (`isError: true` with a text block) are shown the same way, so
+  write them for your user. Reopened conversations in History show them too.
+- **Request failures are worded by cause**, never shown raw: offline, signed
+  out, no access, throttled, or Connect having trouble. The raw error still
+  goes to the browser console for whoever is debugging.
+- **"Try again"** re-asks the failed question in place of the failed exchange.
+  It is withheld where a retry cannot help - signed out, no access, or Ask AI
+  switched off for the workspace.
+
+### `streamResource` throws `ConnectError`
+
+A failed `streamResource()` from `useConnect()` now throws a `ConnectError`
+carrying `status` and `code`, rather than a bare `Error`. The message is
+unchanged and `ConnectError` extends `Error`, so existing `catch` blocks keep
+working; branch on `error.status` instead of the message if you do.
+
+### Every trip to Connect comes back: `openConnect` and `handoff`
+
+Each Connect button in this package - the user menu's Profile and Billing,
+`ConnectManageSubscriptionButton`, `ConnectInvoicesButton`,
+`ConnectProfileButton`, "Manage on Connect", checkout, a readiness blocker's
+fix, the access gate - now ends back in your app when the task is done. Most
+of them used to open a new tab that went nowhere: the customer finished on
+Connect, stayed there, and your tab still showed the old state.
+
+```tsx
+<ConnectProvider handoff="popup">   {/* the default */}
+```
+
+- **`"popup"`** (default) opens Connect in a new tab that **closes itself**
+  when the task is done and tells your page first. Every Connect component on
+  the page then re-reads, so a new plan or a fixed payment shows up without a
+  reload. A blocked popup falls back to `"redirect"`.
+- **`"redirect"`** sends this tab to Connect and back. Prefer it for an
+  installed PWA or an app inside an iframe.
+
+**Register your app's origin** among your client's redirect URIs in Connect.
+Connect only sends somebody back to an origin registered for your client; an
+unregistered one still reaches Connect, it just gets no way back.
+
+For your own buttons, `useConnect().openConnect(path)` does the same thing -
+`openConnect("/calendar/settings")`, or a readiness blocker's `resolveUrl`.
+Call it from a press handler. `onHandoffResult` on the provider tells you how
+each trip ended (`completed`, `cancelled`, `closed`); a redirect return
+arrives as `?connect_result=`, which the provider reads and strips.
+
+Your bridge now reports your public `clientId` on `/session`, so you do not
+need to pass `clientId` to `<ConnectProvider>` for any of this, and
+`useConnect().clientId` is filled in from it.
+
+Behaviour changes worth knowing:
+
+- **`<ConnectAccessGate>`'s fix button follows `handoff`.** It used to
+  navigate this tab with `?next=`, which only Connect's subscribe page
+  honoured - a lapsed payment, a missing payment method or verification left
+  the customer on Connect. It now comes back from every blocker.
+- **`useConnectCheckout` no longer reports `blocked`.** A blocked window
+  falls back to a same-tab trip instead of asking the customer to click a
+  link. The value stays in `ConnectCheckoutStatus` so code handling it still
+  compiles.
+- `ConnectAppsGrid` still opens a *subscribed* application in a plain new
+  tab - that is leaving for another product, not a task on Connect.
+
+## 0.41.0
+
+### Calling from the browser: `<ConnectCallButton>`
+
+A signed-in member can now ring a number from your app - through the
+**workspace's own number**, so the person called sees the business, never the
+member's phone. Calls are **not recorded**, and every one lands in Connect's
+call log with who placed it, whether it was answered and how long they talked.
+
+```tsx
+import { ConnectCallProvider, ConnectCallButton } from "@cosmoops/connect-sdk/client";
+
+// once, inside <ConnectProvider>, beside your app shell - a call outlives the page
+<ConnectCallProvider onCallEnded={({ callId }) => callId && logCall(callId)}>
+  {children}
+</ConnectCallProvider>
+
+// wherever a person can be rung
+<ConnectCallButton phone="+919812345678" name="Asha Rao" />
+```
+
+`<ConnectCallProvider>` holds the call and draws the in-call bar (mute, hang
+up, a timer), so navigating mid-call does not hang up. `useConnectCall()` is
+there for your own button. Plivo's browser SDK - now this package's one
+runtime dependency - is loaded only when someone presses Call.
+
+**Log the outcome on your server**, not from the browser: `onEnded` /
+`onCallEnded` hand you the call id, and `connect.calls.get(callId)` reads
+`status`, `talkSeconds`, `unansweredReason` and `placedByUserId`. A browser is
+not a witness a call log should trust, and the carrier's report reaches
+Connect a moment after the line drops - read again if `status` is still
+`dialing` or `answered`.
+
+**Two halves of permission, both required.** Your API key needs the new
+`calls:place` scope (and `calls:read` to read outcomes); the member needs
+"Make calls" - from their workspace role, or a role on your application
+carrying `connect:call:place`. Nothing here works server-to-server: a call is
+placed by a person. Re-run your seed with the new scopes.
+
+New on `ConnectCall`: `handler` (`agent` | `member`), `placedByUserId`,
+`talkSeconds` and `unansweredReason`. `CallStatus` gains `dialing` and
+`unanswered`, which outbound calls already passed through - if you switch on
+it exhaustively, add the two cases.
+
+Server-side, `connect.calls` gains `getBrowserCallingToken`,
+`startBrowserCall` and `cancelBrowserCall`; `createConnectHandler` serves
+them as `POST /calls/{browser-token,start,cancel}`. You should not need to
+call either directly.
+
 ## 0.40.0
 
 ### `workspaces.create()` exists now, and the switcher's "Create workspace" row is inline

package/dist/cjs/client/components/access-gate.js

@@ -275,26 +275,26 @@ function AccessGateFallback({ state, blocker, className, }) {
  * to a choice they can act on. Sending them to Connect's own subscribe page
  * always resolves.
  *
- * ### Same tab, and it carries the way back
+ * ### A hand-off, so it ends back here
  *
- * It used to `window.open(resolveUrl, "_blank")`. A new tab is the wrong
- * shape for a step you have to finish before you can continue: the customer
- * subscribes over there, is left on Connect's billing page with nothing
- * pointing home, and the tab they started in is still showing this card. The
- * most common ending was two open tabs and the belief that the payment had
- * not worked.
+ * It used to `window.open(resolveUrl, "_blank")`, and the customer was left on
+ * Connect's billing page with nothing pointing home while the tab they
+ * started in still showed this card - two open tabs and the belief that the
+ * payment had not worked. Then it went same-tab with `?next=`, which only
+ * Connect's subscribe page honoured, so every other blocker (a lapsed
+ * payment, a missing payment method, verification) still stranded them.
  *
- * So: a same-tab navigation carrying `?next=` back to the page they are
- * standing on, which Connect honours after a subscribe once the origin
- * matches one registered for this application's client
- * (`resolveApplicationReturnUrl`). An unregistered origin costs the return
- * trip and nothing else - they still reach Connect, still resolve the
- * blocker, and `ConnectAccessGate`'s focus re-check catches them on the way
- * back. Partners should register their app's origin; the fallback is a
- * degraded path, not a broken one.
+ * Now it is `openConnect`, like every other Connect button: Connect brings
+ * them back from whichever page the blocker points at, closing itself in
+ * `popup` mode or navigating back in `redirect` mode, and the provider
+ * re-reads the entitlements the moment it reports in - so this card is
+ * replaced by the app without anyone reloading. The focus re-check in
+ * `ConnectAccessGate` stays as the backstop for an origin Connect could not
+ * validate, which still reaches the blocker and just gets no way back.
  */
 function GateCard({ icon: Icon, iconClassName, title, message, actionLabel, resolveUrl, className, }) {
-    return ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsx)(motion_js_1.m.div, { initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: motion_js_1.ENTER, children: (0, jsx_runtime_1.jsxs)(react_2.Card, { className: className, children: [(0, jsx_runtime_1.jsxs)(react_2.Card.Header, { children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(Icon, { className: `size-5 shrink-0 ${iconClassName}`, "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)(react_2.Card.Title, { children: title })] }), (0, jsx_runtime_1.jsx)(react_2.Card.Description, { children: message })] }), resolveUrl && ((0, jsx_runtime_1.jsx)(react_2.Card.Footer, { children: (0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "primary", onPress: () => window.location.assign(withReturnTo(resolveUrl)), children: [actionLabel ?? "Resolve on Connect", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] }) }))] }) }) }));
+    const { openConnect } = (0, provider_js_1.useConnect)();
+    return ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsx)(motion_js_1.m.div, { initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: motion_js_1.ENTER, children: (0, jsx_runtime_1.jsxs)(react_2.Card, { className: className, children: [(0, jsx_runtime_1.jsxs)(react_2.Card.Header, { children: [(0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(Icon, { className: `size-5 shrink-0 ${iconClassName}`, "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)(react_2.Card.Title, { children: title })] }), (0, jsx_runtime_1.jsx)(react_2.Card.Description, { children: message })] }), resolveUrl && ((0, jsx_runtime_1.jsx)(react_2.Card.Footer, { children: (0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "primary", onPress: () => openConnect(resolveUrl), children: [actionLabel ?? "Resolve on Connect", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] }) }))] }) }) }));
 }
 /**
  * The skippable payment-due warning. Dismissal is scoped to this specific
@@ -303,36 +303,14 @@ function GateCard({ icon: Icon, iconClassName, title, message, actionLabel, reso
  * though an old dismissal is still on record.
  */
 function PaymentRetryBanner({ blocker, className, }) {
+    const { openConnect } = (0, provider_js_1.useConnect)();
     const dismissKey = blocker.graceEndsAt ? `connect_dismissed_payment_retry_pending_${blocker.graceEndsAt}` : null;
     const [dismissed, setDismissed] = (0, react_1.useState)(() => dismissKey !== null && typeof window !== "undefined" && window.localStorage.getItem(dismissKey) === "1");
     if (dismissed)
         return null;
-    return ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsxs)(motion_js_1.m.div, { className: (0, cn_js_1.cn)("flex flex-wrap items-center justify-between gap-3 rounded-lg bg-accent-soft px-3 py-2 text-sm text-accent", className), role: "status", initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: motion_js_1.ENTER, children: [(0, jsx_runtime_1.jsxs)("span", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.AlertTriangle, { className: "size-4 shrink-0", "aria-hidden": "true" }), blocker.message, blocker.graceEndsAt && ` Resolve by ${formatDate(blocker.graceEndsAt)} to avoid losing access.`] }), (0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2", children: [blocker.resolveUrl && ((0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "secondary", onPress: () => window.open(blocker.resolveUrl, "_blank", "noopener,noreferrer"), children: ["Resolve payment", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] })), (0, jsx_runtime_1.jsx)(react_2.Button, { variant: "tertiary", isIconOnly: true, "aria-label": "Dismiss", onPress: () => {
+    return ((0, jsx_runtime_1.jsx)(motion_js_1.MotionProvider, { children: (0, jsx_runtime_1.jsxs)(motion_js_1.m.div, { className: (0, cn_js_1.cn)("flex flex-wrap items-center justify-between gap-3 rounded-lg bg-accent-soft px-3 py-2 text-sm text-accent", className), role: "status", initial: { opacity: 0, y: -6 }, animate: { opacity: 1, y: 0 }, transition: motion_js_1.ENTER, children: [(0, jsx_runtime_1.jsxs)("span", { className: "flex items-center gap-2", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.AlertTriangle, { className: "size-4 shrink-0", "aria-hidden": "true" }), blocker.message, blocker.graceEndsAt && ` Resolve by ${formatDate(blocker.graceEndsAt)} to avoid losing access.`] }), (0, jsx_runtime_1.jsxs)("div", { className: "flex items-center gap-2", children: [blocker.resolveUrl && ((0, jsx_runtime_1.jsxs)(react_2.Button, { variant: "secondary", onPress: () => openConnect(blocker.resolveUrl), children: ["Resolve payment", (0, jsx_runtime_1.jsx)(lucide_react_1.ExternalLink, { className: "size-3.5" })] })), (0, jsx_runtime_1.jsx)(react_2.Button, { variant: "tertiary", isIconOnly: true, "aria-label": "Dismiss", onPress: () => {
                                 setDismissed(true);
                                 if (dismissKey && typeof window !== "undefined")
                                     window.localStorage.setItem(dismissKey, "1");
                             }, children: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { className: "size-4" }) })] })] }) }));
 }
-/**
- * `resolveUrl` with `?next=` pointing at the page the customer is standing
- * on, so Connect can hand them back once the blocker is gone.
- *
- * Returns the URL untouched if anything is off - no `window`, an unparseable
- * `resolveUrl`, a `next` already set by the server. Getting back is a
- * courtesy on top of resolving the blocker, and it must never be the reason
- * somebody cannot reach the screen that resolves it.
- */
-function withReturnTo(resolveUrl) {
-    if (typeof window === "undefined")
-        return resolveUrl;
-    try {
-        const url = new URL(resolveUrl);
-        if (url.searchParams.has("next"))
-            return resolveUrl;
-        url.searchParams.set("next", window.location.href);
-        return url.toString();
-    }
-    catch {
-        return resolveUrl;
-    }
-}

package/dist/cjs/client/components/apps-grid.js

@@ -105,7 +105,7 @@ function GridSkeleton() {
  * button that opens an empty box.
  */
 function ConnectAppsGrid({ className, label = "Switch app", variant = "row" }) {
-    const { session, isLoading: sessionLoading, appUrl } = (0, provider_js_1.useConnect)();
+    const { session, isLoading: sessionLoading, openConnect } = (0, provider_js_1.useConnect)();
     const { data, isLoading, error } = (0, provider_js_1.useConnectApps)();
     const [query, setQuery] = (0, react_2.useState)("");
     const apps = (0, react_2.useMemo)(() => data?.apps ?? [], [data]);
@@ -126,8 +126,16 @@ function ConnectAppsGrid({ className, label = "Switch app", variant = "row" }) {
         // application's page on Connect, which is where a plan is actually
         // chosen. The SDK owns this mapping so no integration has to know either
         // URL shape.
-        const target = app.subscribed && app.launchUrl ? app.launchUrl : `${appUrl}/apps/${app.applicationId}`;
-        window.open(target, "_blank", "noopener,noreferrer");
+        //
+        // The two are different kinds of trip. Launching another application is
+        // leaving for somewhere else, so it is a plain new tab with no way back
+        // and no `opener`. Choosing a plan on Connect is a task, so it is a
+        // hand-off that ends back here.
+        if (app.subscribed && app.launchUrl) {
+            window.open(app.launchUrl, "_blank", "noopener,noreferrer");
+            return;
+        }
+        openConnect(`/apps/${encodeURIComponent(app.applicationId)}`);
     };
     const showSearch = apps.length > SEARCH_THRESHOLD;
     const isEmpty = !isLoading && !error && mine.length === 0 && explore.length === 0;

package/dist/cjs/client/components/ask-ai-errors.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AskAiStreamError = exports.TOOL_GENERIC_FAILURE = exports.ASK_AI_GENERIC_FAILURE = void 0;
+exports.describeAskAiFailure = describeAskAiFailure;
+exports.isRetryableAskAiFailure = isRetryableAskAiFailure;
+exports.toolFailureFromOutput = toolFailureFromOutput;
+const errors_js_1 = require("../../errors.js");
+/**
+ * What Ask AI shows when something fails - a sentence for a person, never the
+ * error itself.
+ *
+ * The raw text is somebody else's diagnostic: `TypeError: Failed to fetch`
+ * from the browser, `Connect bridge returned 502` from the provider, a
+ * validation message naming a request field. None of it tells the person what
+ * happened or what to do, and the last one tells them something about the
+ * API they should not need to know. The real error is still on the console of
+ * whoever is debugging; this module decides only what is on screen.
+ */
+exports.ASK_AI_GENERIC_FAILURE = "Something went wrong. Please try again.";
+exports.TOOL_GENERIC_FAILURE = "That step couldn't be completed. Try again in a moment.";
+/** Longest partner-written failure shown inline - a sentence or two, not a dump. */
+const MAX_TOOL_FAILURE_CHARS = 280;
+/**
+ * A failure Connect reported inside the stream, after it had opened.
+ *
+ * Kept apart from a transport failure because its text was written for the
+ * person by Connect's own stream error handler, so it may be shown as it is.
+ */
+class AskAiStreamError extends Error {
+    name = "AskAiStreamError";
+}
+exports.AskAiStreamError = AskAiStreamError;
+/** The SDK default and this panel's old fallback - both say nothing. */
+const UNINFORMATIVE = new Set(["", "An error occurred.", "Ask AI failed"]);
+/** The browser's own words for "no response arrived", across engines. */
+function isNetworkFailure(cause) {
+    if (!(cause instanceof Error))
+        return false;
+    return (cause.name === "TypeError" &&
+        /failed to fetch|fetch failed|load failed|networkerror|network error|network connection was lost/i.test(cause.message));
+}
+function describeAskAiFailure(cause) {
+    if (cause instanceof AskAiStreamError) {
+        return UNINFORMATIVE.has(cause.message.trim()) ? exports.ASK_AI_GENERIC_FAILURE : cause.message;
+    }
+    if (cause instanceof errors_js_1.ConnectError) {
+        if (cause.status === 401 || cause.isSessionExpired)
+            return "Your session has ended. Sign in again to keep asking.";
+        if (cause.status === 403)
+            return "You don't have access to Ask AI in this workspace. Ask an admin if you think you should.";
+        if (cause.status === 429)
+            return "That's a lot of questions at once. Wait a moment, then try again.";
+        // The one refusal Connect words for a person: Ask AI is switched off for
+        // this workspace, and retrying will not change that.
+        if (cause.status === 503 && cause.code === "unavailable" && cause.message)
+            return cause.message;
+        if (cause.status === 0 || cause.status >= 500)
+            return "The assistant is having trouble right now. Try again in a moment.";
+        return exports.ASK_AI_GENERIC_FAILURE;
+    }
+    if (isNetworkFailure(cause))
+        return "Couldn't reach the assistant. Check your connection, then try again.";
+    return exports.ASK_AI_GENERIC_FAILURE;
+}
+/**
+ * Whether trying the same question again could help.
+ *
+ * Off for the failures a retry cannot fix - signed out, no access, Ask AI
+ * switched off - so the panel does not offer a button that will fail the same
+ * way every time.
+ */
+function isRetryableAskAiFailure(cause) {
+    if (cause instanceof errors_js_1.ConnectError) {
+        return !(cause.status === 401 || cause.status === 403 || cause.isSessionExpired || (cause.status === 503 && cause.code === "unavailable"));
+    }
+    return true;
+}
+function truncate(text) {
+    const trimmed = text.trim();
+    return trimmed.length > MAX_TOOL_FAILURE_CHARS ? `${trimmed.slice(0, MAX_TOOL_FAILURE_CHARS - 1)}…` : trimmed;
+}
+/**
+ * The failure a tool's *result* reports, or `null` when it succeeded.
+ *
+ * An application's tool answers `{ isError: true, ... }` rather than throwing,
+ * which is MCP's distinction between "the tool refused" and "the call broke".
+ * Connect puts its own sentence in `error.message` when it could not reach
+ * the application at all; otherwise the application's first text block is its
+ * own refusal ("You don't have permission to ..."), written for its own user.
+ */
+function toolFailureFromOutput(output) {
+    if (typeof output !== "object" || output === null)
+        return null;
+    const result = output;
+    if (result.isError !== true)
+        return null;
+    if (typeof result.error?.message === "string" && result.error.message.trim())
+        return truncate(result.error.message);
+    if (Array.isArray(result.content)) {
+        for (const part of result.content) {
+            if (part && typeof part === "object" && part.type === "text") {
+                const text = part.text;
+                if (typeof text === "string" && text.trim())
+                    return truncate(text);
+            }
+        }
+    }
+    return exports.TOOL_GENERIC_FAILURE;
+}

package/dist/cjs/client/components/ask-ai-turns.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.lastTextBlockIndex = lastTextBlockIndex;
 exports.appendText = appendText;
 exports.turnsFromStored = turnsFromStored;
+const ask_ai_errors_js_1 = require("./ask-ai-errors.js");
 /**
  * Index of the final text block, or `-1`. A reverse loop rather than
  * `findLastIndex`, which is ES2023 - this package targets ES2022 so its
@@ -78,6 +79,7 @@ function turnsFromStored(turns) {
                         id: typeof part.toolCallId === "string" ? part.toolCallId : `${turn.id}-${blocks.length}`,
                         name: part.type.slice("tool-".length),
                         input: part.input,
+                        ...storedFailure(part),
                     },
                 ];
             }
@@ -85,3 +87,13 @@ function turnsFromStored(turns) {
         return { id: turn.id, role: turn.role, blocks, reasoning };
     });
 }
+/**
+ * A stored step's failure, worded exactly as it was live. A thrown error is
+ * stored with its raw `errorText`, which is never shown - only the fact.
+ */
+function storedFailure(part) {
+    if (part.state === "output-error")
+        return { failure: ask_ai_errors_js_1.TOOL_GENERIC_FAILURE };
+    const failure = (0, ask_ai_errors_js_1.toolFailureFromOutput)(part.output);
+    return failure ? { failure } : {};
+}

package/dist/cjs/client/components/ask-ai.js

@@ -68,6 +68,7 @@ const ai_screens_js_1 = require("./ai-screens.js");
 const ai_widgets_js_1 = require("./ai-widgets.js");
 const ask_ai_history_js_1 = require("./ask-ai-history.js");
 const ask_ai_turns_js_1 = require("./ask-ai-turns.js");
+const ask_ai_errors_js_1 = require("./ask-ai-errors.js");
 /**
  * The panel's open width. The *inner* pane always carries it, so the content
  * keeps its layout while the outer shell's width animates to zero around it.
@@ -151,6 +152,16 @@ function renderTool(name, input, renderMarkdown, screens, renderLink) {
             return null;
     }
 }
+/**
+ * A step that failed, drawn where its result would have been.
+ *
+ * Small and inline rather than a banner: the turn itself has not failed - the
+ * model goes on to say what happened - and one unreachable application should
+ * read as one missing piece of an answer, not as the panel breaking.
+ */
+function ToolFailure({ message }) {
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "my-2 flex items-start gap-2 rounded-md border border-warning/30 bg-warning/5 px-2.5 py-2 text-xs text-foreground", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.TriangleAlert, { className: "mt-px size-3.5 shrink-0 text-warning", "aria-hidden": true }), (0, jsx_runtime_1.jsx)("p", { children: message })] }));
+}
 /** Placeholder while a tool's arguments are still arriving, sized like the real thing. */
 function ToolSkeleton() {
     return ((0, jsx_runtime_1.jsx)("div", { className: "my-3 flex h-24 animate-pulse items-center justify-center rounded-lg border border-border bg-surface-secondary", role: "status", "aria-label": "Preparing result", children: (0, jsx_runtime_1.jsx)(lucide_react_1.Sparkles, { className: "size-4 text-accent/60", "aria-hidden": true }) }));
@@ -175,7 +186,7 @@ function ToolSkeleton() {
 async function readStream(response, onChunk) {
     const body = response.body;
     if (!body)
-        throw new Error("Ask AI returned no stream");
+        throw new ask_ai_errors_js_1.AskAiStreamError("");
     const reader = body.pipeThrough(new TextDecoderStream()).getReader();
     let buffer = "";
     for (;;) {
@@ -221,8 +232,23 @@ async function readStream(response, onChunk) {
                     if (chunk.toolCallId)
                         onChunk({ toolInput: { id: chunk.toolCallId, input: chunk.input } });
                     break;
+                case "tool-output-available": {
+                    // A tool that answered `isError` - an application that could not be
+                    // reached, or one that refused. Successful output is not drawn: the
+                    // model's prose is the reading of it.
+                    const failure = (0, ask_ai_errors_js_1.toolFailureFromOutput)(chunk.output);
+                    if (chunk.toolCallId && failure)
+                        onChunk({ toolFailure: { id: chunk.toolCallId, message: failure } });
+                    break;
+                }
+                case "tool-output-error":
+                    // `errorText` here is a thrown error's raw message - the fact of the
+                    // failure is shown, its wording never is.
+                    if (chunk.toolCallId)
+                        onChunk({ toolFailure: { id: chunk.toolCallId, message: ask_ai_errors_js_1.TOOL_GENERIC_FAILURE } });
+                    break;
                 case "error":
-                    throw new Error(chunk.errorText || "Ask AI failed");
+                    throw new ask_ai_errors_js_1.AskAiStreamError(chunk.errorText ?? "");
             }
         }
     }
@@ -274,6 +300,12 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
     const [turns, setTurns] = (0, react_1.useState)([]);
     const [input, setInput] = (0, react_1.useState)("");
     const [isBusy, setIsBusy] = (0, react_1.useState)(false);
+    /**
+     * The last request's failure, worded for a person - and the question to ask
+     * again, when asking again could help. `retry` is `null` for a failure no
+     * retry fixes (signed out, no access, Ask AI switched off), so the panel
+     * never offers a button that fails the same way every time.
+     */
     const [error, setError] = (0, react_1.useState)(null);
     const [showHistory, setShowHistory] = (0, react_1.useState)(false);
     /**
@@ -332,7 +364,13 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
         abortRef.current = null;
         setIsBusy(false);
     }, []);
-    const send = (0, react_1.useCallback)(async (text) => {
+    const send = (0, react_1.useCallback)(
+    /**
+     * `prior` is the conversation the question is asked after - the current
+     * one, except on a retry, which drops the failed exchange first so the
+     * question is not shown (or sent) twice.
+     */
+    async (text, prior = turns) => {
         const controller = new AbortController();
         abortRef.current = controller;
         setError(null);
@@ -348,7 +386,7 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
         // strings. Built from the turns *plus* this one rather than from state,
         // which has not been committed yet at this point. Only text is sent back:
         // a widget is a rendering of something the model already said.
-        const history = [...turns, userTurn].map((turn) => ({
+        const history = [...prior, userTurn].map((turn) => ({
             id: turn.id,
             role: turn.role,
             parts: [
@@ -361,7 +399,7 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
                 },
             ],
         }));
-        setTurns((current) => [...current, userTurn]);
+        setTurns([...prior, userTurn]);
         const patchAnswer = (patch) => setTurns((current) => current.map((turn) => (turn.id === answerId ? patch(turn) : turn)));
         try {
             // Relative to the provider's own `basePath` - `streamResource` prefixes
@@ -395,6 +433,13 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
                     const { id, name } = chunk.toolStart;
                     patchAnswer((turn) => ({ ...turn, blocks: [...turn.blocks, { kind: "tool", id, name, input: null }] }));
                 }
+                if (chunk.toolFailure) {
+                    const { id, message } = chunk.toolFailure;
+                    patchAnswer((turn) => ({
+                        ...turn,
+                        blocks: turn.blocks.map((block) => block.kind === "tool" && block.id === id ? { ...block, failure: message } : block),
+                    }));
+                }
                 if (chunk.toolInput) {
                     const { id, input: toolInput } = chunk.toolInput;
                     patchAnswer((turn) => ({
@@ -408,7 +453,10 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
             // Pressing Stop aborts the fetch, which lands here - a decision, not a
             // failure, and nothing to report.
             if (!controller.signal.aborted) {
-                setError(cause instanceof Error ? cause.message : "Ask AI failed");
+                // The real error is for whoever is debugging; the panel shows a
+                // sentence. See `describeAskAiFailure`.
+                console.error("[connect] Ask AI request failed:", cause);
+                setError({ message: (0, ask_ai_errors_js_1.describeAskAiFailure)(cause), retry: (0, ask_ai_errors_js_1.isRetryableAskAiFailure)(cause) ? text : null });
             }
         }
         finally {
@@ -450,6 +498,25 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
         setConversationId(id);
         setShowHistory(false);
     }, []);
+    /**
+     * Asks the failed question again, in place of the failed exchange.
+     *
+     * Everything from the last question onwards is dropped - the question and
+     * whatever half-answer arrived before the failure - so the retry reads as
+     * the same question answered, not as the person asking twice.
+     */
+    const retry = (0, react_1.useCallback)(() => {
+        if (!error?.retry || isBusy)
+            return;
+        let cut = turns.length;
+        for (let index = turns.length - 1; index >= 0; index--) {
+            if (turns[index]?.role === "user") {
+                cut = index;
+                break;
+            }
+        }
+        void send(error.retry, turns.slice(0, cut));
+    }, [error, isBusy, turns, send]);
     const lastTurn = turns.at(-1);
     const isAnswering = isBusy && lastTurn?.role === "assistant";
     const rendered = (0, react_1.useMemo)(() => turns.map((turn) => {
@@ -459,7 +526,7 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
                 // The user's own turn is shown as they typed it - running a
                 // question that happens to start with `#` through the markdown
                 // renderer would turn it into a heading.
-                (0, jsx_runtime_1.jsx)("div", { children: turn.role === "user" ? ((0, jsx_runtime_1.jsx)("p", { className: "whitespace-pre-wrap", children: block.text })) : (renderMarkdown(block.text, isLive && index === lastTextIndex)) }, index)) : block.input === null ? ((0, jsx_runtime_1.jsx)(ToolSkeleton, {}, block.id)) : ((0, jsx_runtime_1.jsx)("div", { children: renderTool(block.name, block.input, renderMarkdown, screens, renderLink) }, block.id))), isLive && lastTextIndex === -1 && turn.blocks.length === 0 && (0, jsx_runtime_1.jsx)(ThinkingShimmer, {})] }, turn.id));
+                (0, jsx_runtime_1.jsx)("div", { children: turn.role === "user" ? ((0, jsx_runtime_1.jsx)("p", { className: "whitespace-pre-wrap", children: block.text })) : (renderMarkdown(block.text, isLive && index === lastTextIndex)) }, index)) : block.failure ? ((0, jsx_runtime_1.jsx)(ToolFailure, { message: block.failure }, block.id)) : block.input === null ? ((0, jsx_runtime_1.jsx)(ToolSkeleton, {}, block.id)) : ((0, jsx_runtime_1.jsx)("div", { children: renderTool(block.name, block.input, renderMarkdown, screens, renderLink) }, block.id))), isLive && lastTextIndex === -1 && turn.blocks.length === 0 && (0, jsx_runtime_1.jsx)(ThinkingShimmer, {})] }, turn.id));
     }), [turns, isAnswering, lastTurn?.id, assistantName, renderMarkdown]);
     // Signed out there is no workspace to ground an answer in, and the bridge
     // would answer 401 - so there is nothing to offer, not even a button.
@@ -480,7 +547,7 @@ function ConnectAskAi({ title = "Ask AI", assistantName = "Assistant", placehold
                                     // Disabled on an empty one rather than hidden: a control that
                                     // appears and disappears as you use the panel is harder to find
                                     // than one that is always in the same place.
-                                    isDisabled: turns.length === 0, onPress: startNewConversation, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Plus, { className: "size-4" }) }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": showHistory ? "Hide past conversations" : "Past conversations", "aria-pressed": showHistory, onPress: () => setShowHistory((open) => !open), children: (0, jsx_runtime_1.jsx)(lucide_react_1.History, { className: "size-4" }) }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Close", onPress: () => setIsOpen(false), children: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { className: "size-4" }) })] }), showHistory ? ((0, jsx_runtime_1.jsx)("div", { className: "min-h-0 flex-1 overflow-y-auto", children: (0, jsx_runtime_1.jsx)(ask_ai_history_js_1.AskAiHistory, { refreshKey: writeCount, activeConversationId: conversationId, onOpenConversation: openConversation }) })) : ((0, jsx_runtime_1.jsxs)("div", { className: "flex-1 space-y-3 overflow-y-auto p-4", children: [turns.length === 0 && ((0, jsx_runtime_1.jsxs)("div", { className: "space-y-3", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-sm text-muted", children: hint }), currentScreen?.suggestions?.length ? ((0, jsx_runtime_1.jsx)("div", { className: "flex flex-wrap gap-1.5", children: currentScreen.suggestions.map((suggestion) => ((0, jsx_runtime_1.jsx)(react_2.Button, { size: "sm", variant: "secondary", className: "h-auto rounded-full px-2.5 py-1 text-start text-xs whitespace-normal", isDisabled: isBusy, onPress: () => void send(suggestion), children: suggestion }, suggestion))) })) : null] })), rendered, isBusy && lastTurn?.role === "user" && ((0, jsx_runtime_1.jsxs)("div", { className: "rounded-md border border-border bg-accent/5 p-2.5 text-sm", children: [(0, jsx_runtime_1.jsx)("p", { className: "mb-1 text-[11px] font-semibold tracking-wide text-muted uppercase", children: assistantName }), (0, jsx_runtime_1.jsx)(ThinkingShimmer, {})] })), error && (0, jsx_runtime_1.jsx)("p", { className: "text-xs text-danger", children: error }), (0, jsx_runtime_1.jsx)("div", { ref: bottomRef })] })), (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, className: "flex gap-2 border-t border-border p-3", children: [(0, jsx_runtime_1.jsxs)(react_2.TextField, { variant: "secondary", className: "flex-1", children: [(0, jsx_runtime_1.jsx)(react_2.Label, { className: "sr-only", children: placeholder }), (0, jsx_runtime_1.jsx)(react_2.Input, { placeholder: placeholder, value: input, onChange: (event) => setInput(event.currentTarget.value), disabled: isBusy })] }), isBusy ? ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "button", isIconOnly: true, variant: "secondary", "aria-label": "Stop generating", onPress: stop, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Square, { className: "size-3.5" }) })) : ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "submit", isIconOnly: true, variant: "primary", "aria-label": "Send", isDisabled: !input.trim(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.Send, { className: "size-3.5" }) }))] })] }) })] }));
+                                    isDisabled: turns.length === 0, onPress: startNewConversation, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Plus, { className: "size-4" }) }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": showHistory ? "Hide past conversations" : "Past conversations", "aria-pressed": showHistory, onPress: () => setShowHistory((open) => !open), children: (0, jsx_runtime_1.jsx)(lucide_react_1.History, { className: "size-4" }) }), (0, jsx_runtime_1.jsx)(react_2.Button, { isIconOnly: true, size: "sm", variant: "tertiary", "aria-label": "Close", onPress: () => setIsOpen(false), children: (0, jsx_runtime_1.jsx)(lucide_react_1.X, { className: "size-4" }) })] }), showHistory ? ((0, jsx_runtime_1.jsx)("div", { className: "min-h-0 flex-1 overflow-y-auto", children: (0, jsx_runtime_1.jsx)(ask_ai_history_js_1.AskAiHistory, { refreshKey: writeCount, activeConversationId: conversationId, onOpenConversation: openConversation }) })) : ((0, jsx_runtime_1.jsxs)("div", { className: "flex-1 space-y-3 overflow-y-auto p-4", children: [turns.length === 0 && ((0, jsx_runtime_1.jsxs)("div", { className: "space-y-3", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-sm text-muted", children: hint }), currentScreen?.suggestions?.length ? ((0, jsx_runtime_1.jsx)("div", { className: "flex flex-wrap gap-1.5", children: currentScreen.suggestions.map((suggestion) => ((0, jsx_runtime_1.jsx)(react_2.Button, { size: "sm", variant: "secondary", className: "h-auto rounded-full px-2.5 py-1 text-start text-xs whitespace-normal", isDisabled: isBusy, onPress: () => void send(suggestion), children: suggestion }, suggestion))) })) : null] })), rendered, isBusy && lastTurn?.role === "user" && ((0, jsx_runtime_1.jsxs)("div", { className: "rounded-md border border-border bg-accent/5 p-2.5 text-sm", children: [(0, jsx_runtime_1.jsx)("p", { className: "mb-1 text-[11px] font-semibold tracking-wide text-muted uppercase", children: assistantName }), (0, jsx_runtime_1.jsx)(ThinkingShimmer, {})] })), error && ((0, jsx_runtime_1.jsxs)("div", { role: "alert", className: "flex items-start gap-2 rounded-md border border-danger/30 bg-danger/5 p-2.5 text-xs text-danger", children: [(0, jsx_runtime_1.jsx)(lucide_react_1.TriangleAlert, { className: "mt-px size-3.5 shrink-0", "aria-hidden": true }), (0, jsx_runtime_1.jsx)("p", { className: "flex-1", children: error.message }), error.retry && ((0, jsx_runtime_1.jsxs)(react_2.Button, { size: "sm", variant: "tertiary", className: "h-6 shrink-0 px-2 text-xs", onPress: retry, isDisabled: isBusy, children: [(0, jsx_runtime_1.jsx)(lucide_react_1.RotateCcw, { className: "size-3", "aria-hidden": true }), "Try again"] }))] })), (0, jsx_runtime_1.jsx)("div", { ref: bottomRef })] })), (0, jsx_runtime_1.jsxs)("form", { onSubmit: handleSubmit, className: "flex gap-2 border-t border-border p-3", children: [(0, jsx_runtime_1.jsxs)(react_2.TextField, { variant: "secondary", className: "flex-1", children: [(0, jsx_runtime_1.jsx)(react_2.Label, { className: "sr-only", children: placeholder }), (0, jsx_runtime_1.jsx)(react_2.Input, { placeholder: placeholder, value: input, onChange: (event) => setInput(event.currentTarget.value), disabled: isBusy })] }), isBusy ? ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "button", isIconOnly: true, variant: "secondary", "aria-label": "Stop generating", onPress: stop, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Square, { className: "size-3.5" }) })) : ((0, jsx_runtime_1.jsx)(react_2.Button, { type: "submit", isIconOnly: true, variant: "primary", "aria-label": "Send", isDisabled: !input.trim(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.Send, { className: "size-3.5" }) }))] })] }) })] }));
 }
 /** Hoisted for the same reference-equality reason as `ANIMATED` - Streamdown compares it by identity. */
 const LINK_SAFETY = { enabled: false };