@hachej/boring-agent 0.1.22 → 0.1.24

package/dist/front/index.js

@@ -3,6 +3,9 @@ import {
   WORKSPACE_AGENT_PLUGINS_RELOADED_EVENT,
   extractToolUiMetadata
 } from "../chunk-B5JECXMG.js";
+import {
+  ErrorCode
+} from "../chunk-FILARC5X.js";
 import {
   DebugDrawer,
   cn
@@ -256,6 +259,7 @@ import { DefaultChatTransport } from "ai";
 import { useEffect as useEffect4, useMemo as useMemo2, useRef as useRef4, useState as useState3 } from "react";
 function useAgentChat(opts) {
   const { sessionId } = opts;
+  const hydrateMessages = opts.hydrateMessages ?? true;
   const optsRef = useRef4(opts);
   optsRef.current = opts;
   const transport = useMemo2(
@@ -273,7 +277,7 @@ function useAgentChat(opts) {
   const chat = useChat({
     id: sessionId,
     transport,
-    resume: true,
+    resume: hydrateMessages,
     // Match AI SDK's documented React smoothing knob: render at most every
     // ~50ms while chunks stream instead of once per incoming chunk. This only
     // throttles AI SDK's own messages store; pi's custom data-pi projection
@@ -288,6 +292,10 @@ function useAgentChat(opts) {
   const [hydrated, setHydrated] = useState3(false);
   useEffect4(() => {
     if (!sessionId || !cacheKey) return;
+    if (!hydrateMessages) {
+      setHydrated(true);
+      return;
+    }
     let aborted = false;
     setHydrated(false);
     const loadFromCache = () => {
@@ -306,24 +314,30 @@ function useAgentChat(opts) {
     const request = fetchOpts ? fetch(messagesUrl, fetchOpts) : fetch(messagesUrl);
     request.then((res) => res.ok ? res.json() : null).then((payload) => {
       if (aborted) return;
+      const localTurnStarted = statusRef.current === "submitted" || statusRef.current === "streaming" || messagesRef.current.length > 0;
       const serverMessages = payload?.messages;
       if (Array.isArray(serverMessages) && serverMessages.length > 0) {
-        setMessages(serverMessages);
+        if (!localTurnStarted) setMessages(serverMessages);
         return;
       }
-      loadFromCache();
+      if (!localTurnStarted) loadFromCache();
     }).catch(() => {
       if (aborted) return;
-      loadFromCache();
+      const localTurnStarted = statusRef.current === "submitted" || statusRef.current === "streaming" || messagesRef.current.length > 0;
+      if (!localTurnStarted) loadFromCache();
     }).finally(() => {
       if (!aborted) setHydrated(true);
     });
     return () => {
       aborted = true;
     };
-  }, [sessionId, cacheKey, setMessages]);
+  }, [hydrateMessages, sessionId, cacheKey, setMessages]);
   const messages = chat.messages;
   const status = chat.status;
+  const messagesRef = useRef4(messages);
+  const statusRef = useRef4(status);
+  messagesRef.current = messages;
+  statusRef.current = status;
   useEffect4(() => {
     if (opts.persistMessages === false) return;
     if (!hydrated || !cacheKey) return;
@@ -444,6 +458,20 @@ function applyBufferedDeltas(items, deltas) {
     items
   );
 }
+function messageVisibleText(message) {
+  return (message.parts ?? []).filter((part) => part.type === "text").map((part) => "text" in part && typeof part.text === "string" ? part.text : "").join("\n").trim();
+}
+function countExistingSdkUserTexts(messages) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const message of messages) {
+    if (message.role !== "user") continue;
+    if ((message.parts ?? []).some((part) => typeof part.type === "string" && part.type.startsWith("data-pi-"))) continue;
+    const text = messageVisibleText(message);
+    if (!text) continue;
+    counts.set(text, (counts.get(text) ?? 0) + 1);
+  }
+  return counts;
+}
 function rebuildPiMessagesFromDataParts(sourceMessages) {
   const dataParts = sourceMessages.flatMap((message) => message.parts ?? []).map(asPiDataPart).filter(Boolean);
   if (dataParts.length === 0) return [];
@@ -535,7 +563,16 @@ function mergeRebuiltPiMessages(existing, rebuilt) {
     if (rebuiltIds.has(message.id)) return false;
     return !(message.parts ?? []).some((part) => typeof part.type === "string" && part.type.startsWith("data-pi-"));
   });
-  return [...preserved, ...rebuilt];
+  const sdkUserTextCounts = countExistingSdkUserTexts(preserved);
+  const rebuiltMissingFromSdk = rebuilt.filter((message) => {
+    if (message.role !== "user") return true;
+    const text = messageVisibleText(message);
+    const alreadyRepresentedCount = text ? sdkUserTextCounts.get(text) ?? 0 : 0;
+    if (alreadyRepresentedCount <= 0) return true;
+    sdkUserTextCounts.set(text, alreadyRepresentedCount - 1);
+    return false;
+  });
+  return [...preserved, ...rebuiltMissingFromSdk];
 }
 function usePiChatProjection({
   messages,
@@ -709,8 +746,7 @@ function usePiChatProjection({
     if (status !== "ready") return;
     if (prev !== "streaming" && prev !== "submitted") return;
     if (!sessionId || piMessages.length === 0) return;
-    const canonicalMessages = rebuildPiMessagesFromDataParts(piMessages);
-    const messagesToPersist = canonicalMessages.length > 0 ? mergeRebuiltPiMessages(piMessages, canonicalMessages) : piMessages;
+    const messagesToPersist = mergeRebuiltPiMessages(messages, piMessages);
     const stripped = messagesToPersist.map((msg) => ({
       ...msg,
       parts: msg.parts?.filter((part) => {
@@ -1760,6 +1796,38 @@ var ShimmerComponent = ({
 };
 var Shimmer = memo(ShimmerComponent);
 
+// src/front/workspaceReadinessStatus.ts
+var COPY = {
+  "workspace-fs": "Files are still loading.",
+  "sandbox-exec": "Sandbox is still waking.",
+  "ui-bridge": "Workspace UI is still connecting."
+};
+var VALID_REQUIREMENTS = /* @__PURE__ */ new Set([
+  "workspace-fs",
+  "sandbox-exec",
+  "ui-bridge"
+]);
+function detailsFromOutput(output) {
+  if (!output || typeof output !== "object") return null;
+  const record = output;
+  const details = record.details && typeof record.details === "object" ? record.details : record;
+  return details;
+}
+function getWorkspaceNotReadyStatus(output) {
+  const details = detailsFromOutput(output);
+  if (!details) return null;
+  if (details.code !== ErrorCode.enum.WORKSPACE_NOT_READY) return null;
+  if (details.retryable !== true) return null;
+  const requirement = details.requirement;
+  if (typeof requirement !== "string" || !VALID_REQUIREMENTS.has(requirement)) return null;
+  return {
+    code: ErrorCode.enum.WORKSPACE_NOT_READY,
+    retryable: true,
+    requirement,
+    message: COPY[requirement]
+  };
+}
+
 // src/front/primitives/tool-call-group.tsx
 import { jsx as jsx10, jsxs as jsxs9 } from "react/jsx-runtime";
 function isSettledState(state) {
@@ -1795,10 +1863,14 @@ var ToolCallGroup = memo2(({ tools, mergedToolRenderers }) => {
     if (!isToolUIPart(part)) return true;
     return isSettledState(part.state);
   });
+  const workspaceNotReady = tools.map(({ part }) => {
+    if (!isToolUIPart(part)) return null;
+    return getWorkspaceNotReadyStatus(part.output);
+  }).find(Boolean);
   const hasError = tools.some(({ part }) => {
     if (!isToolUIPart(part)) return false;
     return part.state === "output-error";
-  });
+  }) && !workspaceNotReady;
   const [isOpen, setIsOpen] = useState9(false);
   const handleOpenChange = useCallback6((open) => setIsOpen(open), []);
   const title = useMemo5(() => buildTitle(tools, isSettled), [tools, isSettled]);
@@ -1831,7 +1903,7 @@ var ToolCallGroup = memo2(({ tools, mergedToolRenderers }) => {
               )
             }
           ),
-          !isSettled ? /* @__PURE__ */ jsx10(Shimmer, { as: "span", duration: 1.5, children: title }) : /* @__PURE__ */ jsx10("span", { children: title }),
+          workspaceNotReady ? /* @__PURE__ */ jsx10("span", { children: workspaceNotReady.message }) : !isSettled ? /* @__PURE__ */ jsx10(Shimmer, { as: "span", duration: 1.5, children: title }) : /* @__PURE__ */ jsx10("span", { children: title }),
           /* @__PURE__ */ jsx10("span", { className: cn(
             "ml-1 shrink-0 rounded-sm border border-border/40 px-1 tabular-nums",
             "text-[10px] text-muted-foreground/50"
@@ -2498,6 +2570,17 @@ function PathLabel({ path }) {
     }
   );
 }
+function renderWorkspaceNotReady(part) {
+  const status = getWorkspaceNotReadyStatus(part.output);
+  if (!status) return null;
+  return /* @__PURE__ */ jsxs13(Tool2, { children: [
+    /* @__PURE__ */ jsx15(ToolHeader, { title: `${part.toolName} \xB7 ${status.message}`, ...toHeaderProps(part) }),
+    /* @__PURE__ */ jsx15(ToolContent, { children: /* @__PURE__ */ jsxs13("div", { className: "rounded-md border border-border/60 bg-muted/30 px-3 py-2 text-sm text-muted-foreground", children: [
+      status.message,
+      " Try again in a moment."
+    ] }) })
+  ] });
+}
 function pathTitle(prefix, path) {
   return /* @__PURE__ */ jsxs13("span", { className: "flex min-w-0 items-center gap-1.5", children: [
     /* @__PURE__ */ jsx15("span", { className: "text-muted-foreground", children: prefix }),
@@ -2506,6 +2589,8 @@ function pathTitle(prefix, path) {
   ] });
 }
 function renderBash2(part) {
+  const readiness = renderWorkspaceNotReady(part);
+  if (readiness) return readiness;
   const input = asRecord2(part.input);
   const output = asRecord2(part.output);
   const command = typeof input.command === "string" ? input.command : "";
@@ -2537,6 +2622,8 @@ function renderBash2(part) {
   ] });
 }
 function renderRead2(part) {
+  const readiness = renderWorkspaceNotReady(part);
+  if (readiness) return readiness;
   const input = asRecord2(part.input);
   const output = asRecord2(part.output);
   const path = typeof input.path === "string" ? input.path : "";
@@ -2554,6 +2641,8 @@ function renderRead2(part) {
   ] });
 }
 function renderWrite2(part) {
+  const readiness = renderWorkspaceNotReady(part);
+  if (readiness) return readiness;
   const input = asRecord2(part.input);
   const path = typeof input.path === "string" ? input.path : "";
   const content = typeof input.content === "string" ? input.content : "";
@@ -2616,6 +2705,8 @@ function renderWrite2(part) {
   ] });
 }
 function renderEdit2(part) {
+  const readiness = renderWorkspaceNotReady(part);
+  if (readiness) return readiness;
   const input = asRecord2(part.input);
   const path = typeof input.path === "string" ? input.path : "";
   const oldString = typeof input.oldString === "string" ? input.oldString : "";
@@ -2641,6 +2732,8 @@ function renderEdit2(part) {
   ] });
 }
 function renderSearchLike2(toolName, part) {
+  const readiness = renderWorkspaceNotReady(part);
+  if (readiness) return readiness;
   const input = asRecord2(part.input);
   const SearchLikeIcon = toolName === "find" || toolName === "grep" ? SearchIcon : FileTextIcon;
   const pattern = typeof input.pattern === "string" ? input.pattern : "";
@@ -2677,6 +2770,8 @@ function extractParamTokens(value, depth = 0) {
   return [String(value)];
 }
 function renderExecUi2(part) {
+  const readiness = renderWorkspaceNotReady(part);
+  if (readiness) return readiness;
   const input = asRecord2(part.input);
   const kind = typeof input.kind === "string" ? input.kind : "(empty)";
   const tokens = extractParamTokens(input.params);
@@ -2733,6 +2828,8 @@ function renderExecUi2(part) {
   ] });
 }
 function renderFallback2(part) {
+  const readiness = renderWorkspaceNotReady(part);
+  if (readiness) return readiness;
   return /* @__PURE__ */ jsxs13(Tool2, { children: [
     /* @__PURE__ */ jsx15(ToolHeader, { title: part.toolName, ...toHeaderProps(part) }),
     /* @__PURE__ */ jsxs13(ToolContent, { children: [
@@ -3678,23 +3775,25 @@ var PromptInput = ({
             return item;
           })
         );
-        const result = onSubmit({ files: convertedFiles, text }, event);
-        if (result instanceof Promise) {
-          try {
-            await result;
-            clear();
-            if (usingProvider) {
-              controller.textInput.clear();
-            }
-          } catch {
-          }
-        } else {
-          clear();
+        const result = await onSubmit({ files: convertedFiles, text }, event);
+        if (result === false) {
           if (usingProvider) {
-            controller.textInput.clear();
+            controller.textInput.setInput(text);
+          } else {
+            const textInput = form.elements.namedItem("message");
+            if (textInput) textInput.value = text;
           }
+          return;
+        }
+        clear();
+        if (usingProvider) {
+          controller.textInput.clear();
         }
       } catch {
+        if (!usingProvider) {
+          const textInput = form.elements.namedItem("message");
+          if (textInput && textInput.value === "") textInput.value = text;
+        }
       }
     },
     [usingProvider, controller, files, onSubmit, clear]
@@ -4121,10 +4220,23 @@ function friendlyError(err) {
         detail: `${label} ${message?.toLowerCase() ?? "failed validation"}.`
       };
     }
+    if (code3 === ErrorCode.enum.AGENT_RUNTIME_NOT_READY) {
+      return {
+        title: "Preparing workspace\u2026",
+        code: code3
+      };
+    }
+    if (code3 === ErrorCode.enum.RUNTIME_PROVISIONING_FAILED) {
+      return {
+        title: "Workspace setup failed.",
+        detail: message ?? "Reload the workspace and try again.",
+        code: code3
+      };
+    }
     if (code3 === "internal" || code3 === "internal_error") {
-      return { title: "The server hit an internal error.", detail: message };
+      return { title: "The server hit an internal error.", detail: message, code: code3 };
     }
-    return { title: message ?? "Something went wrong.", detail: code3 };
+    return { title: message ?? "Something went wrong.", detail: code3, code: code3 };
   } catch {
     return { title: raw };
   }
@@ -4429,7 +4541,8 @@ function encodeModelKey(sel) {
 // src/front/hooks/useChatModelSelection.ts
 function useChatModelSelection({
   defaultModel,
-  requestHeaders
+  requestHeaders,
+  enabled = true
 }) {
   const initialModelState = useMemo11(readStoredModelState, []);
   const [model, setModelState] = useState15(
@@ -4456,6 +4569,7 @@ function useChatModelSelection({
     setModelState(defaultModel);
   }, [defaultModel]);
   useEffect14(() => {
+    if (!enabled) return;
     let aborted = false;
     fetch("/api/v1/agent/models", { headers: requestHeaders }).then((res) => res.ok ? res.json() : null).then((payload) => {
       if (aborted || !payload?.models) return;
@@ -4474,7 +4588,7 @@ function useChatModelSelection({
     return () => {
       aborted = true;
     };
-  }, [requestHeaders]);
+  }, [enabled, requestHeaders]);
   useEffect14(() => {
     const onChange = (event) => {
       const next = parseModelSelection(event.detail);
@@ -4490,10 +4604,12 @@ function useChatModelSelection({
 import { useEffect as useEffect15, useState as useState16 } from "react";
 function useServerSkills({
   registry,
-  requestHeaders
+  requestHeaders,
+  enabled = true
 }) {
   const [skillsStamp, setSkillsStamp] = useState16(0);
   useEffect15(() => {
+    if (!enabled) return;
     let aborted = false;
     fetch("/api/v1/agent/skills", { headers: requestHeaders }).then((res) => res.ok ? res.json() : null).then((payload) => {
       if (aborted || !payload?.skills) return;
@@ -4511,7 +4627,7 @@ function useServerSkills({
     return () => {
       aborted = true;
     };
-  }, [requestHeaders, registry]);
+  }, [enabled, requestHeaders, registry]);
   return skillsStamp;
 }
 
@@ -4551,7 +4667,7 @@ function useAttachmentNotice(timeoutMs = 4e3) {
 
 // src/front/chatPanelComposerControls.tsx
 import { useState as useState19 } from "react";
-import { BotIcon, BrainIcon as BrainIcon2, CheckIcon as CheckIcon2, ChevronDownIcon as ChevronDownIcon5, EyeIcon, EyeOffIcon } from "lucide-react";
+import { CheckIcon as CheckIcon2, ChevronDownIcon as ChevronDownIcon5, EyeIcon, EyeOffIcon } from "lucide-react";
 import {
   Command as Command2,
   CommandEmpty as CommandEmpty2,
@@ -4603,6 +4719,33 @@ var THINKING_LEVEL_LABELS = {
   medium: "Med",
   high: "High"
 };
+function ThinkingLevelGlyph({ level }) {
+  const lit = level === "off" ? 0 : level === "low" ? 1 : level === "medium" ? 2 : 3;
+  return /* @__PURE__ */ jsx23(
+    "svg",
+    {
+      "aria-hidden": "true",
+      width: "14",
+      height: "14",
+      viewBox: "0 0 14 14",
+      fill: "none",
+      className: "shrink-0",
+      children: [0, 1, 2].map((i) => /* @__PURE__ */ jsx23(
+        "rect",
+        {
+          x: 2 + i * 4,
+          y: 10 - i * 2,
+          width: "2",
+          height: 3 + i * 2,
+          rx: "0.5",
+          fill: "currentColor",
+          opacity: i < lit ? 1 : 0.25
+        },
+        i
+      ))
+    }
+  );
+}
 function ModelSelect({
   value,
   onChange,
@@ -4641,13 +4784,16 @@ function ModelSelect({
         "aria-label": "Model",
         className: cn(
           composerActionClass,
-          "w-auto max-w-[min(52vw,200px)] px-2 text-xs font-medium",
-          open && "bg-muted/60 text-foreground"
+          // Model is the only piece of state the composer carries between
+          // turns — give it a status-pill shape so it reads as data, not
+          // another tertiary control. The label is the signal; no icon
+          // (the bot/AI glyph was decoration, not information).
+          "w-auto max-w-[min(52vw,260px)] gap-1 rounded-full bg-muted/40 px-2.5 text-[12px] font-medium text-foreground/85 hover:bg-muted/70",
+          open && "bg-muted/70 text-foreground"
         ),
         children: [
-          /* @__PURE__ */ jsx23(BotIcon, { className: "h-4 w-4 shrink-0", "aria-hidden": "true" }),
           /* @__PURE__ */ jsx23("span", { className: "min-w-0 truncate", children: triggerLabel }),
-          /* @__PURE__ */ jsx23(ChevronDownIcon5, { className: "h-3 w-3 shrink-0 text-muted-foreground/60", "aria-hidden": "true" })
+          /* @__PURE__ */ jsx23(ChevronDownIcon5, { className: "h-3 w-3 shrink-0 text-muted-foreground/50", "aria-hidden": "true" })
         ]
       }
     ) }),
@@ -4657,7 +4803,7 @@ function ModelSelect({
         align: "start",
         sideOffset: 6,
         "data-boring-agent": "",
-        className: "w-[min(90vw,260px)] rounded-xl border-border/60 bg-popover p-1 shadow-xl",
+        className: "w-[min(92vw,340px)] rounded-xl border-border/60 bg-popover p-1 shadow-xl",
         children: /* @__PURE__ */ jsxs21(Command2, { children: [
           menuOptions.length > 8 && /* @__PURE__ */ jsx23(
             CommandInput2,
@@ -4686,7 +4832,13 @@ function ModelSelect({
                       },
                       className: cn(
                         "flex items-center gap-2 rounded-md px-2 py-1.5 text-[13px]",
-                        key === currentKey && "bg-accent text-accent-foreground"
+                        // Soften cmdk's full-saturation `data-[selected=true]:bg-accent`
+                        // (keyboard-cursor focus) to a subtle warm tint so the
+                        // active row doesn't read as a saturated tile in dark mode.
+                        "data-[selected=true]:bg-[color:oklch(from_var(--accent)_l_c_h/0.15)] data-[selected=true]:text-foreground",
+                        // The user's CURRENTLY-SELECTED model gets a neutral wash +
+                        // the CheckIcon (accent is reserved for primary CTA / focus).
+                        key === currentKey && "bg-foreground/[0.06] text-foreground"
                       ),
                       children: [
                         /* @__PURE__ */ jsx23(
@@ -4694,12 +4846,12 @@ function ModelSelect({
                           {
                             className: cn(
                               "h-3.5 w-3.5 shrink-0",
-                              key === currentKey ? "opacity-100" : "opacity-0"
+                              key === currentKey ? "text-[color:var(--accent)] opacity-100" : "opacity-0"
                             )
                           }
                         ),
                         /* @__PURE__ */ jsx23("span", { className: "truncate", children: label }),
-                        /* @__PURE__ */ jsx23("span", { className: "ml-auto shrink-0 text-[10px] text-muted-foreground/70", children: m.id })
+                        /* @__PURE__ */ jsx23("span", { className: "ml-auto shrink-0 text-[10px] text-muted-foreground/60", children: m.id })
                       ]
                     },
                     key
@@ -4733,12 +4885,17 @@ function ThinkingSelect({
           {
             "data-boring-agent-part": "thinking-select",
             "data-boring-state": disabled ? "disabled" : void 0,
-            className: cn(composerActionClass, "w-8 px-0"),
-            "aria-label": "Thinking level",
+            className: cn(
+              composerActionClass,
+              "w-8 px-0 [&>span[aria-hidden]]:hidden",
+              value !== "off" && "text-foreground"
+            ),
+            "aria-label": `Thinking level: ${THINKING_LEVEL_LABELS[value]}`,
+            title: `Thinking: ${THINKING_LEVEL_LABELS[value]}`,
             "data-testid": "thinking-select",
             children: [
               THINKING_LEVELS.map((level) => /* @__PURE__ */ jsx23("span", { "data-value": level, hidden: true }, level)),
-              /* @__PURE__ */ jsx23(BrainIcon2, { className: "h-3.5 w-3.5" })
+              /* @__PURE__ */ jsx23(ThinkingLevelGlyph, { level: value })
             ]
           }
         ),
@@ -4772,25 +4929,26 @@ function ThoughtVisibilityButton({
       variant: "ghost",
       size: "icon-sm",
       onClick: onToggle,
-      className: cn(composerActionClass, "w-8"),
+      className: cn(composerActionClass, "w-8", visible && "text-foreground"),
       "aria-pressed": visible,
       "aria-label": visible ? "Hide thoughts" : "Show thoughts",
       title: visible ? "Hide thoughts" : "Show thoughts",
-      children: /* @__PURE__ */ jsx23(Icon, { className: "h-3.5 w-3.5" })
+      children: /* @__PURE__ */ jsx23(Icon, { className: "h-3.5 w-3.5", strokeWidth: 1.75 })
     }
   );
 }
 
 // src/front/chatPanelKbdHints.tsx
+import { Kbd } from "@hachej/boring-ui-kit";
 import { jsx as jsx24, jsxs as jsxs22 } from "react/jsx-runtime";
 function KbdHints() {
   return /* @__PURE__ */ jsxs22(
-    "kbd",
+    Kbd,
     {
       "aria-hidden": "true",
+      title: "Shift + Enter for newline",
       className: cn(
-        "hidden h-5 items-center gap-0.5 rounded-[var(--radius-sm)] border border-border/50",
-        "bg-background/50 px-1.5 font-mono text-[10px] text-muted-foreground/40",
+        "hidden gap-0.5 border-border/60 bg-muted/40 leading-none shadow-none",
         "sm:inline-flex"
       ),
       children: [
@@ -4830,6 +4988,9 @@ function hasVisibleMessageContent(message) {
     return Boolean(reasoning?.text.trim());
   });
 }
+function messageText(message) {
+  return (message.parts ?? []).filter(isTextPart).map((part) => part.text).join("\n").trim();
+}
 function hasPiVisibleDataParts(messages) {
   return messages.some(
     (message) => (message.parts ?? []).some((part) => {
@@ -4848,7 +5009,8 @@ function collectSdkRepresentedMessageIds(messages) {
     if (!hasVisibleMessageContent(message)) continue;
     represented.add(message.id);
     for (const part of message.parts ?? []) {
-      if (dataPartType(part) !== "data-pi-message-start") continue;
+      const type = dataPartType(part);
+      if (type !== "data-pi-message-start" && type !== "data-pi-message-end") continue;
       const data = part.data;
       if (typeof data?.messageId === "string") represented.add(data.messageId);
     }
@@ -4865,6 +5027,19 @@ function uniqueVisiblePiMessages(messages) {
   }
   return out;
 }
+function sdkVisibleMessagesWithoutPiOnlyAssistants(messages) {
+  return messages.filter((message) => {
+    if (!hasVisibleMessageContent(message)) return false;
+    if (message.role !== "assistant") return true;
+    const hasVisibleAssistantPart = (message.parts ?? []).some((part) => {
+      if (isTextPart(part)) return !isBlankTextPart(part);
+      if (isToolUIPart2(part)) return true;
+      const reasoning = getReasoningPart(part);
+      return Boolean(reasoning?.text.trim());
+    });
+    return hasVisibleAssistantPart;
+  });
+}
 function getSettledPiAssistantIds(message) {
   const ids = [];
   for (const part of message.parts ?? []) {
@@ -4901,6 +5076,23 @@ function mergeSettledPiFallbacksInPlace(messages, piMessages) {
   }
   return out;
 }
+function composerNoticeForWarmup(status) {
+  if (!status || status.status === "ready") return null;
+  if (status.status === "failed") {
+    return {
+      title: "Workspace setup failed.",
+      detail: status.message ?? "Reload the workspace and try again.",
+      code: ErrorCode.enum.RUNTIME_PROVISIONING_FAILED
+    };
+  }
+  return {
+    title: "Preparing workspace\u2026",
+    code: ErrorCode.enum.AGENT_RUNTIME_NOT_READY
+  };
+}
+function isComposerRuntimeNotice(error) {
+  return error?.code === ErrorCode.enum.AGENT_RUNTIME_NOT_READY || error?.code === ErrorCode.enum.RUNTIME_PROVISIONING_FAILED;
+}
 function getQueuedPiTail(messages, piMessages) {
   if (piMessages.length === 0) return [];
   const queuedIds = /* @__PURE__ */ new Set();
@@ -4955,8 +5147,19 @@ function ChatPanel(props) {
     defaultModel,
     onData,
     requestHeaders,
+    hydrateMessages,
     onOpenArtifact,
     debug = false,
+    initialDraft,
+    autoSubmitInitialDraft = false,
+    onDraftRestored,
+    onAutoSubmitInitialDraftAccepted,
+    onAutoSubmitInitialDraftSettled,
+    onBeforeSubmit,
+    serverResourcesEnabled = true,
+    emptyPlacement = "default",
+    composerPlaceholder,
+    workspaceWarmupStatus,
     composerBlockers = [],
     onComposerStop,
     onComposerBlockerAction
@@ -4969,6 +5172,23 @@ function ChatPanel(props) {
   });
   const followUpDataHandlerRef = useRef13(() => {
   });
+  const autoSubmittedDraftRef = useRef13(void 0);
+  const autoSubmittingDraftRef = useRef13(void 0);
+  const pendingAutoSubmitUnlockRef = useRef13(void 0);
+  const pendingAutoSubmitSettleRef = useRef13(void 0);
+  const activeAutoSubmitSessionRef = useRef13(sessionId);
+  const liveSessionIdRef = useRef13(sessionId);
+  liveSessionIdRef.current = sessionId;
+  activeAutoSubmitSessionRef.current = sessionId;
+  const [acceptedAutoSubmittedDraft, setAcceptedAutoSubmittedDraft] = useState20(void 0);
+  const [composerRuntimeNotice, setComposerRuntimeNotice] = useState20(null);
+  useEffect18(() => {
+    autoSubmittedDraftRef.current = void 0;
+    autoSubmittingDraftRef.current = void 0;
+    pendingAutoSubmitUnlockRef.current = void 0;
+    pendingAutoSubmitSettleRef.current = void 0;
+    setAcceptedAutoSubmittedDraft(void 0);
+  }, [sessionId]);
   const {
     messages,
     sendMessage,
@@ -4985,7 +5205,8 @@ function ChatPanel(props) {
       onData?.(part);
     },
     requestHeaders,
-    persistMessages: capabilities.aiSdkOwnsHistory
+    persistMessages: capabilities.aiSdkOwnsHistory,
+    hydrateMessages
   });
   const { piMessages, handleData: handlePiData } = usePiChatProjection({
     messages,
@@ -5014,9 +5235,14 @@ function ChatPanel(props) {
     followUpDataHandlerRef.current = handleFollowUpData;
   }, [handleFollowUpData]);
   const mergedToolRenderers = mergeShadcnToolRenderers(toolRenderers);
-  const composerBlocked = composerBlockers.length > 0;
+  const friendlyChatError = error ? friendlyError(error) : null;
+  const runtimeErrorNotice = isComposerRuntimeNotice(friendlyChatError) ? friendlyChatError : null;
+  const warmupNotice = composerNoticeForWarmup(workspaceWarmupStatus);
+  const composerStatusNotice = composerRuntimeNotice ?? runtimeErrorNotice ?? warmupNotice;
+  const workspaceWarmupBlocked = Boolean(warmupNotice);
+  const composerBlocked = workspaceWarmupBlocked || composerBlockers.length > 0;
   const primaryComposerBlocker = composerBlockers[0];
-  const composerBlockerLabel = primaryComposerBlocker?.label ?? "Complete the pending workspace action to continue.";
+  const composerBlockerLabel = workspaceWarmupBlocked ? warmupNotice?.title ?? "Preparing workspace\u2026" : primaryComposerBlocker?.label ?? "Complete the pending workspace action to continue.";
   const registry = useMemo12(
     () => {
       const effectiveBuiltins = hotReloadEnabled ? builtinCommands : builtinCommands.filter((cmd) => cmd.name !== "reload");
@@ -5024,11 +5250,12 @@ function ChatPanel(props) {
     },
     [extraCommands, hotReloadEnabled]
   );
-  const skillsStamp = useServerSkills({ registry, requestHeaders });
+  const skillsStamp = useServerSkills({ registry, requestHeaders, enabled: serverResourcesEnabled });
   const allCommands = useMemo12(() => registry.list(), [registry, skillsStamp]);
   const { availableModels, model, setModel } = useChatModelSelection({
     defaultModel,
-    requestHeaders
+    requestHeaders,
+    enabled: serverResourcesEnabled
   });
   const { thinkingLevel, setThinkingLevel, showThoughts, setShowThoughts } = useThinkingSettings(thinkingControl);
   const { attachmentNotice, setAttachmentNotice } = useAttachmentNotice();
@@ -5127,23 +5354,49 @@ ${formatPluginReloadDiagnostics(diagnostics)}` : base;
     const waitingTail = projectedTailMessages.filter((message) => projectedStatusById.get(message.id) === "queued");
     const queuedPiTail = getQueuedPiTail(messages, piMessages);
     const sdkHasVisibleAssistant = hasStandardVisibleAssistantParts(messages);
+    let baseMessages;
     if (sdkHasVisibleAssistant) {
       const mergedMessages = mergeSettledPiFallbacksInPlace(messages, piMessages);
-      return [
+      baseMessages = [
         ...mergedMessages,
         ...coalesceAssistantToolFragments(queuedPiTail),
         ...waitingTail
       ];
+    } else if (piMessages.length > 0 && queuedPiTail.length > 0) {
+      baseMessages = [...coalesceAssistantToolFragments(piMessages), ...waitingTail];
+    } else if (piMessages.length > 0 && status === "ready" && hasPiVisibleDataParts(messages)) {
+      baseMessages = [
+        ...sdkVisibleMessagesWithoutPiOnlyAssistants(messages),
+        ...coalesceAssistantToolFragments(piMessages),
+        ...waitingTail
+      ];
+    } else {
+      baseMessages = [...messages, ...waitingTail];
     }
-    if (piMessages.length > 0 && queuedPiTail.length > 0) {
-      return [...coalesceAssistantToolFragments(piMessages), ...waitingTail];
-    }
-    if (piMessages.length > 0 && status === "ready" && hasPiVisibleDataParts(messages)) {
-      return [...coalesceAssistantToolFragments(piMessages), ...waitingTail];
+    const autoSubmittedDraft = acceptedAutoSubmittedDraft?.trim();
+    if (!autoSubmittedDraft) return baseMessages;
+    const hasUserTurn = baseMessages.some((message) => message.role === "user" && messageText(message).includes(autoSubmittedDraft));
+    if (hasUserTurn) return baseMessages;
+    const syntheticUserMessage = {
+      id: `auto-submitted-user:${sessionId}:${autoSubmittedDraft}`,
+      role: "user",
+      parts: [{ type: "text", text: autoSubmittedDraft }]
+    };
+    let insertAt = baseMessages.length;
+    for (let index = baseMessages.length - 1; index >= 0; index -= 1) {
+      if (baseMessages[index]?.role === "assistant") {
+        insertAt = index;
+        break;
+      }
     }
-    return [...messages, ...waitingTail];
-  }, [messages, piMessages, projectedTailMessages, projectedStatusById, status]);
-  const renderMessages = displayMessages;
+    return [
+      ...baseMessages.slice(0, insertAt),
+      syntheticUserMessage,
+      ...baseMessages.slice(insertAt)
+    ];
+  }, [acceptedAutoSubmittedDraft, messages, piMessages, projectedTailMessages, projectedStatusById, sessionId, status]);
+  const renderMessages = displayMessages.filter((message) => message.role !== "assistant" || hasVisibleMessageContent(message));
+  const emptyHero = emptyPlacement === "hero" && renderMessages.length === 0;
   const handleStop = useCallback16(() => {
     onComposerStop?.();
     stopAndClearFollowUps();
@@ -5167,6 +5420,14 @@ ${formatPluginReloadDiagnostics(diagnostics)}` : base;
     [messages]
   );
   const textareaRef = useRef13(null);
+  const promptInputController = useOptionalPromptInputController();
+  const setComposerDraft = useCallback16((draft, focus = true) => {
+    promptInputController?.textInput.setInput(draft);
+    if (textareaRef.current) {
+      textareaRef.current.value = draft;
+      if (focus) textareaRef.current.focus();
+    }
+  }, [promptInputController]);
   const {
     mentionState,
     slashQuery,
@@ -5183,12 +5444,31 @@ ${formatPluginReloadDiagnostics(diagnostics)}` : base;
     textareaRef,
     disabled: mentionState !== null || slashQuery !== null
   });
-  async function handleSubmit({ text, files }) {
-    if (composerBlocked) return;
+  const restoredDraftRef = useRef13(void 0);
+  useEffect18(() => {
+    if (initialDraft === void 0) return;
+    if (restoredDraftRef.current === initialDraft) return;
+    if (!promptInputController && !textareaRef.current) return;
+    setComposerDraft(initialDraft, initialDraft.length > 0);
+    restoredDraftRef.current = initialDraft;
+    onDraftRestored?.();
+  }, [initialDraft, onDraftRestored, promptInputController, setComposerDraft]);
+  async function runBeforeSubmit(draft, files, source) {
+    const result = await onBeforeSubmit?.(draft, { files, sessionId, source });
+    return result !== false;
+  }
+  async function handleSubmit({ text, files }, source = "composer") {
+    if (composerBlocked) {
+      if (warmupNotice) setComposerRuntimeNotice(warmupNotice);
+      return false;
+    }
     const trimmed = text.trim();
     if (trimmed.length === 0 && (!files || files.length === 0)) {
       return;
     }
+    setComposerRuntimeNotice(null);
+    if (!await runBeforeSubmit(text, files ?? [], source)) return false;
+    if (liveSessionIdRef.current !== sessionId) return false;
     const parsed = parseSlashCommand(text);
     if (parsed) {
       const cmd = registry.get(parsed.name);
@@ -5240,6 +5520,7 @@ ${parsed.args}` : `skill: ${parsed.name}`;
       files: files ?? [],
       mentionedFiles
     });
+    if (liveSessionIdRef.current !== sessionId) return false;
     clearMentionedFiles();
     if (isStreaming && files.length > 0) {
       setAttachmentNotice("Attachments can be sent after the current response finishes.");
@@ -5277,6 +5558,48 @@ ${parsed.args}` : `skill: ${parsed.name}`;
       }
     );
   }
+  useEffect18(() => {
+    const pendingDraft = pendingAutoSubmitUnlockRef.current;
+    if (!pendingDraft) return;
+    const localTurnStarted = status === "submitted" || status === "streaming" || messages.some(
+      (message) => message.role === "user" && message.parts.some((part) => isTextPart(part) && part.text.includes(pendingDraft))
+    );
+    if (!localTurnStarted) return;
+    pendingAutoSubmitUnlockRef.current = void 0;
+    onAutoSubmitInitialDraftAccepted?.();
+  }, [messages, onAutoSubmitInitialDraftAccepted, status]);
+  const prevAutoSubmitStatusRef = useRef13(status);
+  useEffect18(() => {
+    const prev = prevAutoSubmitStatusRef.current;
+    prevAutoSubmitStatusRef.current = status;
+    if (!pendingAutoSubmitSettleRef.current) return;
+    if (status !== "ready") return;
+    if (prev !== "submitted" && prev !== "streaming") return;
+    pendingAutoSubmitSettleRef.current = void 0;
+    onAutoSubmitInitialDraftSettled?.();
+  }, [onAutoSubmitInitialDraftSettled, status]);
+  useEffect18(() => {
+    if (workspaceWarmupStatus?.status === "ready") setComposerRuntimeNotice(null);
+  }, [workspaceWarmupStatus?.status]);
+  useEffect18(() => {
+    if (!autoSubmitInitialDraft) return;
+    if (!initialDraft?.trim()) return;
+    if (autoSubmittedDraftRef.current === initialDraft) return;
+    if (autoSubmittingDraftRef.current === initialDraft) return;
+    const targetSessionId = sessionId;
+    autoSubmittingDraftRef.current = initialDraft;
+    void (async () => {
+      const result = await handleSubmit({ text: initialDraft, files: [] }, "composer");
+      if (activeAutoSubmitSessionRef.current !== targetSessionId) return;
+      autoSubmittingDraftRef.current = void 0;
+      if (result === false) return;
+      autoSubmittedDraftRef.current = initialDraft;
+      pendingAutoSubmitUnlockRef.current = initialDraft;
+      pendingAutoSubmitSettleRef.current = initialDraft;
+      setAcceptedAutoSubmittedDraft(initialDraft);
+      setComposerDraft("", false);
+    })();
+  }, [autoSubmitInitialDraft, handleSubmit, initialDraft, sessionId, setComposerDraft]);
   return /* @__PURE__ */ jsx25(ArtifactOpenProvider, { onOpenArtifact, children: /* @__PURE__ */ jsxs23(
     "div",
     {
@@ -5296,6 +5619,7 @@ ${parsed.args}` : `skill: ${parsed.name}`;
           {
             className: cn(
               "flex h-full min-h-0 flex-col overflow-hidden",
+              emptyHero && "justify-center",
               chrome && "mx-3 my-3 rounded-xl bg-[color:var(--surface-chat)] shadow-[0_1px_0_oklch(0_0_0/0.02),0_1px_2px_-1px_oklch(0_0_0/0.04),inset_0_0_0_1px_oklch(from_var(--border)_l_c_h/0.6)]"
             ),
             children: [
@@ -5325,7 +5649,7 @@ ${parsed.args}` : `skill: ${parsed.name}`;
               /* @__PURE__ */ jsxs23(
                 Conversation,
                 {
-                  className: "flex-1",
+                  className: emptyHero ? "max-h-[45vh] flex-none" : "flex-1",
                   "aria-label": "Agent conversation",
                   "aria-live": "polite",
                   onScrollToBottomReady: (scrollToBottom) => {
@@ -5334,29 +5658,24 @@ ${parsed.args}` : `skill: ${parsed.name}`;
                   children: [
                     /* @__PURE__ */ jsxs23(ConversationContent, { className: cn(
                       "mx-auto flex w-full flex-col gap-6",
-                      chrome ? "max-w-3xl px-6 py-8" : "max-w-[680px] px-4 py-4"
+                      chrome ? "max-w-3xl px-6 py-8" : "max-w-[680px] px-4 py-4",
+                      emptyHero && "py-4 text-center"
                     ), children: [
-                      displayMessages.length === 0 && /* @__PURE__ */ jsx25(
+                      renderMessages.length === 0 && /* @__PURE__ */ jsx25(
                         ChatEmptyState,
                         {
                           eyebrow: emptyState?.eyebrow,
                           title: emptyState?.title,
                           description: emptyState?.description,
                           suggestions,
+                          className: emptyHero ? "items-center text-center [&>p]:mx-auto" : void 0,
                           onSelect: (s) => {
                             const text = s.prompt ?? s.label;
                             if (!text.trim()) return;
-                            void sendMessage(
-                              { text, files: [] },
-                              {
-                                body: {
-                                  sessionId,
-                                  message: text,
-                                  ...modelPayload(model),
-                                  attachments: []
-                                }
-                              }
-                            );
+                            void (async () => {
+                              const submitted = await handleSubmit({ text, files: [] }, "suggestion");
+                              if (submitted === false) setComposerDraft(text);
+                            })();
                           }
                         }
                       ),
@@ -5372,7 +5691,11 @@ ${parsed.args}` : `skill: ${parsed.name}`;
                           const key = `${message.id}-${index}`;
                           if (!reasoningPart) {
                             if (!isBlankTextPart(part)) {
-                              items.push({ kind: "part", part, key });
+                              const previous2 = items[items.length - 1];
+                              const duplicateAdjacentAssistantText = role === "assistant" && isTextPart(part) && previous2?.kind === "part" && isTextPart(previous2.part) && previous2.part.text.trim() === part.text.trim();
+                              if (!duplicateAdjacentAssistantText) {
+                                items.push({ kind: "part", part, key });
+                              }
                             }
                             return items;
                           }
@@ -5399,6 +5722,12 @@ ${reasoningPart.text}`;
                               acc.push({ kind: "tool-group", tools: [{ part: item.part, key: item.key }], key: item.key });
                             }
                           } else if (item.kind === "part" && !isTextPart(item.part)) {
+                          } else if (item.kind === "part" && isTextPart(item.part)) {
+                            const prev = acc[acc.length - 1];
+                            const duplicateAdjacentAssistantText = role === "assistant" && prev?.kind === "part" && isTextPart(prev.part) && prev.part.text.trim() === item.part.text.trim();
+                            if (!duplicateAdjacentAssistantText) {
+                              acc.push(item);
+                            }
                           } else {
                             acc.push(item);
                           }
@@ -5559,8 +5888,8 @@ ${reasoningPart.text}`;
                         );
                       }),
                       (() => {
-                        if (!error) return null;
-                        const friendly = friendlyError(error);
+                        if (!friendlyChatError || isComposerRuntimeNotice(friendlyChatError)) return null;
+                        const friendly = friendlyChatError;
                         return /* @__PURE__ */ jsx25(Message, { from: "assistant", className: "!max-w-full", children: /* @__PURE__ */ jsx25(MessageContent, { className: "rounded-xl border border-destructive/40 bg-destructive/10 px-4 py-3", children: /* @__PURE__ */ jsxs23("div", { role: "alert", className: "flex items-start gap-3 text-sm text-destructive", children: [
                           /* @__PURE__ */ jsx25("div", { className: "mt-0.5 shrink-0", children: /* @__PURE__ */ jsxs23("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
                             /* @__PURE__ */ jsx25("circle", { cx: "12", cy: "12", r: "10" }),
@@ -5627,7 +5956,26 @@ ${reasoningPart.text}`;
                     )
                   }
                 ),
-                composerBlocked && /* @__PURE__ */ jsxs23(
+                composerStatusNotice && /* @__PURE__ */ jsx25(
+                  "div",
+                  {
+                    "data-testid": "chat-composer-runtime-notice",
+                    role: "status",
+                    "aria-live": "polite",
+                    className: cn(
+                      "mx-auto mb-2 w-full max-w-3xl rounded-[var(--radius-md)] border border-accent/40 bg-[color:var(--accent-soft)]",
+                      "px-3 py-2 text-xs text-foreground"
+                    ),
+                    children: /* @__PURE__ */ jsxs23("div", { className: "flex items-start gap-2", children: [
+                      composerStatusNotice.code === ErrorCode.enum.AGENT_RUNTIME_NOT_READY ? /* @__PURE__ */ jsx25(Loader2, { "aria-hidden": "true", className: "mt-0.5 size-3.5 shrink-0 animate-spin text-muted-foreground" }) : /* @__PURE__ */ jsx25(AlertCircleIcon, { "aria-hidden": "true", className: "mt-0.5 size-3.5 shrink-0 text-destructive" }),
+                      /* @__PURE__ */ jsxs23("div", { className: "min-w-0", children: [
+                        /* @__PURE__ */ jsx25("div", { className: "font-medium", children: composerStatusNotice.title }),
+                        composerStatusNotice.detail && /* @__PURE__ */ jsx25("div", { className: "mt-0.5 text-muted-foreground", children: composerStatusNotice.detail })
+                      ] })
+                    ] })
+                  }
+                ),
+                composerBlocked && !workspaceWarmupBlocked && /* @__PURE__ */ jsxs23(
                   "div",
                   {
                     role: "status",
@@ -5722,7 +6070,7 @@ ${reasoningPart.text}`;
                       PromptInput,
                       {
                         "data-boring-state": status,
-                        onSubmit: handleSubmit,
+                        onSubmit: (message) => handleSubmit(message),
                         multiple: true,
                         maxFiles: attachmentsDisabled ? 0 : 20,
                         maxFileSize: 5 * 1024 * 1024,
@@ -5744,14 +6092,16 @@ ${reasoningPart.text}`;
                           /* @__PURE__ */ jsx25(
                             PromptInputTextarea,
                             {
-                              placeholder: composerBlocked ? composerBlockerLabel : "Ask anything\u2026",
+                              defaultValue: promptInputController ? void 0 : initialDraft,
+                              placeholder: composerBlocked ? composerBlockerLabel : composerPlaceholder ?? "Ask anything\u2026",
                               disabled: composerBlocked,
                               readOnly: composerBlocked,
+                              ref: textareaRef,
                               onChange: handleComposerChange,
                               onKeyDown: handleComposerKeyDown,
                               className: cn(
-                                "min-h-[48px] resize-none border-0 bg-transparent shadow-none",
-                                "px-4 py-3 text-[13px] leading-[1.55] placeholder:text-muted-foreground/50",
+                                "min-h-11 resize-none border-0 bg-transparent shadow-none",
+                                "px-4 py-2.5 text-[13px] leading-[1.55] placeholder:text-muted-foreground/45",
                                 "focus-visible:ring-0 focus-visible:ring-offset-0"
                               )
                             }
@@ -5809,7 +6159,7 @@ ${reasoningPart.text}`;
                                           // to earn the real estate. Becomes a Stop affordance
                                           // (square icon + aria-label="Stop") while the turn
                                           // streams.
-                                          "h-8 w-8 shrink-0 rounded-[var(--radius-lg)]",
+                                          "h-8 w-8 shrink-0 rounded-full",
                                           "bg-[color:var(--accent)] text-[color:var(--accent-foreground)]",
                                           "transition-all duration-150 ease-[cubic-bezier(0.22,1,0.36,1)]",
                                           "hover:shadow-[0_0_0_3px_oklch(from_var(--accent)_l_c_h/0.30)] hover:brightness-110 hover:scale-[1.04]",
@@ -5863,7 +6213,7 @@ function AttachmentButton({ disabled }) {
       className: cn(composerActionClass, "w-8"),
       "aria-label": "Attach files",
       title: disabled ? "Attachments are available after the current response finishes." : "Attach files",
-      children: /* @__PURE__ */ jsx25(PaperclipIcon2, { className: "h-4 w-4" })
+      children: /* @__PURE__ */ jsx25(PaperclipIcon2, { className: "h-3.5 w-3.5", strokeWidth: 1.75 })
     }
   );
 }
@@ -6103,7 +6453,7 @@ function getAgentCommands(options = {}) {
 }
 
 // src/front/hooks/useSessions.ts
-import { useState as useState21, useEffect as useEffect19, useCallback as useCallback17, useRef as useRef14 } from "react";
+import { useState as useState21, useEffect as useEffect19, useCallback as useCallback17, useMemo as useMemo13, useRef as useRef14 } from "react";
 var API_BASE = "/api/v1/agent/sessions";
 var STORAGE_KEY = "boring-agent:activeSessionId";
 function readPersistedId(storageKey) {
@@ -6120,6 +6470,9 @@ function persistId(storageKey, id) {
   } catch {
   }
 }
+function headersScopeKey(headers) {
+  return JSON.stringify(Object.entries(headers ?? {}).sort(([a], [b]) => a.localeCompare(b)));
+}
 function requestInit(headers) {
   if (!headers || Object.keys(headers).length === 0) return void 0;
   return { headers };
@@ -6133,21 +6486,46 @@ async function fetchSessions(headers) {
 function useSessions(opts = {}) {
   const storageKey = opts.storageKey ?? STORAGE_KEY;
   const requestHeaders = opts.requestHeaders;
+  const enabled = opts.enabled ?? true;
+  const refreshKey = opts.refreshKey;
+  const scopeKey = useMemo13(
+    () => `${storageKey}
+${headersScopeKey(requestHeaders)}`,
+    [requestHeaders, storageKey]
+  );
   const [sessions, setSessions] = useState21([]);
   const [activeSessionId, setActiveSessionId] = useState21(
     () => readPersistedId(storageKey)
   );
   const [loading, setLoading] = useState21(true);
   const [error, setError] = useState21();
+  const [loaded, setLoaded] = useState21(false);
   const versionRef = useRef14(0);
+  const loadedScopeRef = useRef14(scopeKey);
   const refresh = useCallback17(async () => {
     const v = ++versionRef.current;
+    if (!enabled) {
+      setSessions([]);
+      setActiveSessionId(void 0);
+      setError(void 0);
+      setLoaded(false);
+      setLoading(false);
+      return;
+    }
+    setLoaded(false);
+    setLoading(true);
     try {
       const data = await fetchSessions(requestHeaders);
       if (v === versionRef.current) {
+        const replacingLoadedScope = loadedScopeRef.current !== scopeKey;
+        loadedScopeRef.current = scopeKey;
+        const persisted = readPersistedId(storageKey);
+        setError(void 0);
+        setLoaded(true);
         setSessions(data);
         setActiveSessionId((prev) => {
-          if (prev && data.some((session) => session.id === prev)) return prev;
+          const preferred = replacingLoadedScope ? persisted : prev ?? persisted;
+          if (preferred && data.some((session) => session.id === preferred)) return preferred;
           const next = data[0]?.id;
           persistId(storageKey, next);
           return next;
@@ -6156,16 +6534,32 @@ function useSessions(opts = {}) {
       }
     } catch (err) {
       if (v === versionRef.current) {
+        const replacingLoadedScope = loadedScopeRef.current !== scopeKey;
+        loadedScopeRef.current = scopeKey;
+        if (replacingLoadedScope) {
+          setSessions([]);
+          setActiveSessionId(void 0);
+        }
+        setLoaded(true);
         setError(err instanceof Error ? err : new Error(String(err)));
         setLoading(false);
       }
     }
-  }, [requestHeaders, storageKey]);
+  }, [enabled, requestHeaders, scopeKey, storageKey]);
   useEffect19(() => {
+    if (!enabled) {
+      setSessions([]);
+      setActiveSessionId(void 0);
+      setError(void 0);
+      setLoaded(false);
+      setLoading(false);
+      return;
+    }
     void refresh();
-  }, [refresh]);
+  }, [enabled, refresh, refreshKey, scopeKey]);
   const create = useCallback17(
     async (init) => {
+      if (!enabled) throw new Error("Sessions are disabled");
       const res = await fetch(API_BASE, {
         method: "POST",
         headers: { ...requestHeaders, "Content-Type": "application/json" },
@@ -6183,7 +6577,7 @@ function useSessions(opts = {}) {
       void refresh();
       return session;
     },
-    [refresh, requestHeaders, storageKey]
+    [enabled, refresh, requestHeaders, storageKey]
   );
   const switchSession = useCallback17((id) => {
     setActiveSessionId(id);
@@ -6191,6 +6585,7 @@ function useSessions(opts = {}) {
   }, [storageKey]);
   const deleteSession = useCallback17(
     async (id) => {
+      if (!enabled) throw new Error("Sessions are disabled");
       setSessions((prev) => prev.filter((s) => s.id !== id));
       setActiveSessionId((prev) => {
         if (prev === id) {
@@ -6214,13 +6609,16 @@ function useSessions(opts = {}) {
       }
       void refresh();
     },
-    [refresh, requestHeaders, storageKey]
+    [enabled, refresh, requestHeaders, storageKey]
   );
+  const scopeMatches = loadedScopeRef.current === scopeKey;
+  const visibleSessions = enabled && scopeMatches ? sessions : [];
+  const visibleActiveSessionId = enabled && scopeMatches ? activeSessionId : void 0;
   return {
-    sessions,
-    activeSession: sessions.find((s) => s.id === activeSessionId),
-    activeSessionId,
-    loading,
+    sessions: visibleSessions,
+    activeSession: visibleSessions.find((s) => s.id === visibleActiveSessionId),
+    activeSessionId: visibleActiveSessionId,
+    loading: enabled ? !scopeMatches || loading || !loaded : false,
     error,
     create,
     switch: switchSession,