@k2b/cloud 0.22.0 → 0.24.0

package/src/_internal/page-responses.ts

@@ -1,6 +1,7 @@
 import type { HtmlFn } from "@k2b/ssr";
 import type { Context } from "hono";
 import type { ClientErrorStatusCode, ServerErrorStatusCode } from "hono/utils/http-status";
+import { PWA_AUTH_PATH, PWA_SCOPE } from "../contracts/pwa";
 import { getLocale } from "../server/locale";
 import { preloadLayoutAnnouncements } from "../server/middleware/settings";
 import { createLoginRedirectUrl } from "../shared/redirect";
@@ -10,8 +11,8 @@ export type PageErrorOptions = {
   title?: string;
   description?: string;
   action?: { label: string; href: string; icon?: string };
-  /** Keep standalone/public pages outside the Cloud navigation shell. */
-  layout?: "cloud" | "minimal";
+  /** Keep standalone/public pages outside the Cloud navigation shell; `pwa` renders a page of the mobile app. */
+  layout?: "cloud" | "minimal" | "pwa";
 };
 
 export type PageErrorStatus = ClientErrorStatusCode | ServerErrorStatusCode;
@@ -22,7 +23,7 @@ export const createPageResponses = (html: HtmlFn<PageOptions>) => {
     // Auth middleware may reject before ssr() initializes page metadata.
     c.set("page", { lang: getLocale(c) });
     c.header("Cache-Control", "private, no-store");
-    await preloadLayoutAnnouncements(c);
+    if (options.layout !== "pwa") await preloadLayoutAnnouncements(c);
     // Load JSX only after the application's SSR plugin has been installed.
     const { renderPageError } = await import("../ssr/PageError");
     const response = await html(renderPageError(c, status, options), c.get("page"));
@@ -38,5 +39,20 @@ export const createPageResponses = (html: HtmlFn<PageOptions>) => {
     },
   };
 
-  return { access, error };
+  /**
+   * Route policy for pages of the mobile app (preview), below `/pwa/`. Only an app session reaches them. Without
+   * one, Core renews the app session with the phone's device key and returns to the same page; `pwa_launch` marks
+   * that return, so a second miss stops at the shell's "unavailable" state instead of bouncing again.
+   */
+  const pwaAccess = {
+    onReject: (c: Context, reason: "unauthenticated" | "forbidden") => {
+      c.header("Cache-Control", "private, no-store");
+      if (reason === "forbidden" || c.get("actor")) return error(c, 403, { layout: "pwa" });
+      const url = new URL(c.req.url);
+      if (url.searchParams.has("pwa_launch")) return `${PWA_SCOPE}?pwa=unavailable`;
+      return `${PWA_AUTH_PATH}/session/launch?to=${encodeURIComponent(url.pathname + url.search)}`;
+    },
+  };
+
+  return { access, pwaAccess, error };
 };

package/src/_internal/registry-validation.ts

@@ -104,6 +104,12 @@ export const validateAppRegistryEntry = (value: unknown): string | null => {
     )
       return invalid("searchLinks", "an array of same-origin navigation links");
   }
+  if (value.pwa !== undefined) {
+    if (!isRecord(value.pwa) || value.pwa.href !== `/pwa/${value.id as string}`) return invalid("pwa", "a mobile app part at /pwa/<id>");
+    if (value.pwa.requiresRoles !== undefined && !isStringArray(value.pwa.requiresRoles)) {
+      return invalid("pwa.requiresRoles", "an array of strings");
+    }
+  }
   if (value.widgets !== undefined) {
     if (
       !Array.isArray(value.widgets) ||

package/src/_internal/registry.ts

@@ -1,6 +1,7 @@
 import type { EphemeralConfig } from "@k2b/sync";
 import type { AppAppearanceColor } from "../contracts/app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "../contracts/capabilities";
+import { fileProviderIssues } from "../contracts/file-provider";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
 import type { DashboardWidgetPresentation } from "../contracts/widgets";
 import { resolveAppPresentations } from "../shared/app-presentation";
@@ -174,24 +175,98 @@ const capabilityEndpoint = (baseUrl: string): string | null => {
 const appAccent = (value: string | undefined): AppAppearanceColor | undefined =>
   /^#[0-9a-f]{6}$/i.test(value ?? "") ? (value as AppAppearanceColor) : undefined;
 
+/** Last manifest per app whose left-out entries were checked, so each registered manifest logs once. */
+const checkedLeftOutEntries = new Map<string, string>();
+
+/**
+ * Logs the entries of a registered manifest that this release left out, typically because the app runs a
+ * newer Cloud release. Core answers those operations as not found, so the operator needs their names.
+ * A left-out file provider is named too, because the app then quietly stops offering files. `manifest` is
+ * the manifest as read, before the file-provider contract check, which logs its own rejections.
+ */
+const reportLeftOutEntries = (sent: unknown, manifest: CapabilityManifest): void => {
+  if (checkedLeftOutEntries.get(manifest.appId) === manifest.manifestHash) return;
+  checkedLeftOutEntries.set(manifest.appId, manifest.manifestHash);
+  const kept = new Set([...manifest.types, ...manifest.queries, ...manifest.actions, ...manifest.commands].map((entry) => entry.localId));
+  const groups = sent as Record<string, unknown>;
+  const leftOut = (["types", "queries", "actions", "commands"] as const).flatMap((group) => {
+    const entries = groups[group];
+    if (!Array.isArray(entries)) return [];
+    return entries.flatMap((entry: unknown) => {
+      const localId = entry && typeof entry === "object" ? (entry as { localId?: unknown }).localId : undefined;
+      return typeof localId === "string" && !kept.has(localId) ? [`${group}/${localId}`] : [];
+    });
+  });
+  if (groups.fileProvider !== undefined && !manifest.fileProvider) leftOut.push("fileProvider");
+  if (leftOut.length === 0) return;
+  console.warn(
+    JSON.stringify({
+      level: "warn",
+      source: "capability-registry",
+      message: "Left out capability entries this Cloud release cannot read",
+      appId: manifest.appId,
+      manifestHash: manifest.manifestHash,
+      leftOutCount: leftOut.length,
+      leftOut: leftOut.slice(0, 20),
+    }),
+  );
+};
+
+/** Last checked manifest per app: its hash and whether its file provider passed the contract check. */
+const checkedFileProviders = new Map<string, { manifestHash: string; valid: boolean }>();
+
+/**
+ * Ignores a file provider that does not match the contract, logging once per manifest; the app's other
+ * capabilities stay available. The delivered `manifestHash` stays, because it identifies what the app registered.
+ */
+const withValidFileProvider = (manifest: CapabilityManifest): CapabilityManifest => {
+  if (!manifest.fileProvider) return manifest;
+  const checked = checkedFileProviders.get(manifest.appId);
+  let valid = checked?.manifestHash === manifest.manifestHash ? checked.valid : undefined;
+  if (valid === undefined) {
+    const issues = fileProviderIssues(manifest);
+    valid = issues.length === 0;
+    checkedFileProviders.set(manifest.appId, { manifestHash: manifest.manifestHash, valid });
+    if (!valid) {
+      console.error(
+        JSON.stringify({
+          level: "error",
+          source: "capability-registry",
+          message: "Ignored a file provider that does not match the file-provider contract",
+          appId: manifest.appId,
+          manifestHash: manifest.manifestHash,
+          issues: issues
+            .slice(0, 10)
+            .map(({ function: name, localId, code, path, message }) => ({ function: name, localId, code, path, message })),
+        }),
+      );
+    }
+  }
+  if (valid) return manifest;
+  const { fileProvider: _ignored, ...rest } = manifest;
+  return rest;
+};
+
+/** Ignores record fields from a newer release; the endpoint always comes from the live app registry. */
 export const resolveLiveCapabilityRegistryEntry = (
   key: string,
   value: unknown,
   app: AppRegistryEntry | undefined,
 ): CapabilityRegistryEntry | null => {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  if (Object.keys(value).some((field) => field !== "appId" && field !== "manifest" && field !== "presentation")) return null;
   const record = value as Partial<CapabilityRegistryRecord>;
   if (!app || typeof record.appId !== "string" || key !== `capabilities/${record.appId}` || record.appId !== app.id) return null;
   if (!app.capabilities) return null;
   const endpoint = capabilityEndpoint(app.baseUrl);
   if (!endpoint) return null;
   try {
-    const manifest = parseCapabilityManifest(record.manifest, app.id);
-    const presentation = compileCapabilityPresentation(manifest, record.presentation);
+    const read = parseCapabilityManifest(record.manifest, app.id);
+    const manifest = withValidFileProvider(read);
+    const presentation = compileCapabilityPresentation(manifest, record.presentation, "reader");
     if (app.capabilities.protocolVersion !== manifest.protocolVersion || app.capabilities.manifestHash !== manifest.manifestHash) {
       return null;
     }
+    reportLeftOutEntries(record.manifest, read);
     return {
       appId: app.id,
       appName: app.name,

package/src/_internal/runtime-context.ts

@@ -67,6 +67,7 @@ export const buildRuntimeFromRegistry = (entries: AppRegistryEntry[], capabiliti
       ),
       legalLinks: e.legalLinks ? e.legalLinks.map((l) => ({ ...l })) : undefined,
       searchLinks: e.searchLinks?.map((link) => ({ ...link, keywords: link.keywords ? [...link.keywords] : undefined })),
+      pwa: e.pwa ? { href: e.pwa.href, requiresRoles: e.pwa.requiresRoles ? ([...e.pwa.requiresRoles] as Role[]) : undefined } : undefined,
       openapi: e.openapi,
     };
   }),

package/src/_internal/static-assets.ts

@@ -33,6 +33,15 @@ function acceptsEncoding(header: string | null, encoding: "br" | "gzip"): boolea
   });
 }
 
+/** `If-None-Match` names the current file: a list of tags, possibly weak, or `*`. */
+function matchesEtag(header: string | null, etag: string): boolean {
+  if (!header) return false;
+  return header.split(",").some((part) => {
+    const tag = part.trim();
+    return tag === "*" || tag === etag || tag === `W/${etag}`;
+  });
+}
+
 async function encodedFile(path: string, encoding: "br" | "gzip"): Promise<Bun.BunFile | null> {
   const suffix = encoding === "br" ? ".br" : ".gz";
   const file = Bun.file(`${path}${suffix}`);
@@ -72,13 +81,19 @@ export function servePublicAsset(isDevelopment: boolean) {
       }
     }
 
+    // Development rebuilds files in place under the same address, so the browser asks again on every use; an
+    // unchanged file then costs one round trip instead of its whole size on every page.
+    const etag = `"${selectedEncoding ?? "identity"}-${selected.size.toString(36)}-${selected.lastModified.toString(36)}"`;
     const headers = new Headers({
-      "Cache-Control": isDevelopment ? "no-store" : "public, max-age=31536000, immutable",
-      "Content-Length": String(selected.size),
-      "Content-Type": sourceFile.type || "application/octet-stream",
+      "Cache-Control": isDevelopment ? "no-cache" : "public, max-age=31536000, immutable",
+      ETag: etag,
       Vary: "Accept-Encoding",
     });
 
+    if (matchesEtag(c.req.header("If-None-Match") ?? null, etag)) return new Response(null, { status: 304, headers });
+
+    headers.set("Content-Length", String(selected.size));
+    headers.set("Content-Type", sourceFile.type || "application/octet-stream");
     if (selectedEncoding) headers.set("Content-Encoding", selectedEncoding);
 
     return new Response(c.req.method === "HEAD" ? null : selected, { headers });

package/src/access/ResourceApiKeys.tsx

@@ -1,6 +1,18 @@
 import { dates } from "@k2b/stdlib";
 import { mutation as mutations } from "@k2b/stdlib/solid";
-import { Button, CopyButton, DateTimePicker, NoticeCard, Placeholder, prompts, Select, Tag, TextInput, useLocale } from "@k2b/ui";
+import {
+  Button,
+  CopyButton,
+  DateTimePicker,
+  DetailPanel,
+  NoticeCard,
+  Placeholder,
+  prompts,
+  Select,
+  Tag,
+  TextInput,
+  useLocale,
+} from "@k2b/ui";
 import { createEffect, createSignal, For, Show } from "solid-js";
 import type { PermissionLevel, ServiceAccountCredential } from "../contracts/shared";
 import { accessMessages } from "./messages";
@@ -56,9 +68,7 @@ function TokenDialog(props: { token: string }) {
   const t = () => accessMessages.resolve([locale()]).t;
   return (
     <div class="flex flex-col gap-4">
-      <NoticeCard tone="warning" icon={false}>
-        {t().copyOnce}
-      </NoticeCard>
+      <NoticeCard tone="warning">{t().copyOnce}</NoticeCard>
       <div class="rounded-lg border border-zinc-200 bg-zinc-50 p-3 dark:border-zinc-800 dark:bg-zinc-900">
         <code class="block break-all font-mono text-xs text-primary">{props.token}</code>
       </div>
@@ -203,39 +213,29 @@ export default function ResourceApiKeys(props: ResourceApiKeysProps) {
     if (confirmed) await revokeMutation.mutate({ id: key.id, name: key.name });
   };
 
+  // The heading is a detail panel section heading: in a detail panel the keys line up with the sections around them,
+  // and below a settings group title they read as one level down.
   return (
-    <section class="flex flex-col gap-4">
-      <div class="flex items-start justify-between gap-3">
-        <div>
-          <h3 class="flex items-center gap-1.5 text-sm font-semibold text-primary">
-            <i class="ti ti-key text-sm" />
-            {props.title ?? t().apiKeys}
-          </h3>
-          <p class="mt-1 text-xs text-dimmed">{props.description ?? t().apiKeysDescription}</p>
-        </div>
-        <Button type="button" variant="secondary" size="sm" class="shrink-0" onClick={openCreate} disabled={createMutation.loading()}>
-          <i class="ti ti-plus" />
+    <DetailPanel.Section
+      title={props.title ?? t().apiKeys}
+      icon="ti ti-key"
+      description={props.description ?? t().apiKeysDescription}
+      actions={
+        <Button type="button" variant="secondary" size="sm" onClick={openCreate} disabled={createMutation.loading()}>
+          <i class="ti ti-plus" aria-hidden="true" />
           {t().add}
         </Button>
-      </div>
-
-      <Show
-        when={keys().length > 0}
-        fallback={
-          <Placeholder
-            icon="ti ti-key"
-            class="rounded-lg border border-dashed border-zinc-200 dark:border-zinc-800"
-            description={t().noApiKeys}
-          />
-        }
-      >
+      }
+    >
+      <Show when={keys().length > 0} fallback={<Placeholder icon="ti ti-key" align="left" description={t().noApiKeys} />}>
         <div class="flex flex-col gap-2">
           <For each={keys()}>
             {(key) => (
               <div class="group/api-key flex items-center gap-3 rounded-lg bg-zinc-50/70 p-3 dark:bg-zinc-900/35">
                 <div class="min-w-0 flex-1">
-                  <div class="flex min-w-0 items-center gap-2">
-                    <span class="truncate text-sm font-medium text-primary">{key.name}</span>
+                  {/* The name and its tags wrap instead of squeezing the name to a few letters in a narrow section. */}
+                  <div class="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
+                    <span class="max-w-full truncate text-sm font-medium text-primary">{key.name}</span>
                     <Tag color={key.permission === "none" ? "#dc2626" : "#2563eb"}>
                       {permissionLabel(key.permission, options(), t().noAccess)}
                     </Tag>
@@ -266,6 +266,6 @@ export default function ResourceApiKeys(props: ResourceApiKeysProps) {
           </For>
         </div>
       </Show>
-    </section>
+    </DetailPanel.Section>
   );
 }

package/src/ai/capability-execution.ts

@@ -8,6 +8,7 @@ import type { AccessSubject } from "../server/services/access";
 import { isAccountCategoryAllowed } from "../services/account-category-policy";
 import { isAccountExpired } from "../services/account-model";
 import { accounts } from "../services/accounts";
+import { withoutAdminRole } from "../services/session/user";
 import { LOCALE_HEADER } from "../shared/locale";
 import type { AiCapabilityCatalogEntry } from "./capabilities";
 import { aiToolAudit } from "./tool-audit";
@@ -30,6 +31,10 @@ export const resolveAiCapabilityActor = async (input: {
   const user = await (input.getUser ?? accounts.users.get)({ id: conversation.createdByUserId });
   if (!user || isAccountExpired(user.accountExpires)) throw new Error("Cloud capability actor is no longer active.");
   if (!(await isAccountCategoryAllowed(user))) throw new Error("Cloud capability actor category is disabled.");
+  // A turn started in the mobile app keeps its limits: no administrator role, and invocations say so.
+  if (input.persistedActor.sessionKind === "app") {
+    return { actor: { kind: "user", user: withoutAdminRole(user), sessionKind: "app" }, accessSubject: { type: "user", userId: user.id } };
+  }
   return { actor: { kind: "user", user }, accessSubject: { type: "user", userId: user.id } };
 };
 

package/src/ai/chat/blocks.tsx

@@ -705,11 +705,12 @@ function ToolBlockView(props: { turnId: string; block: ToolBlock; active?: boole
 
 /** Render one unified turn block. Shared by persisted assistant groups and the live turn. */
 export function AiTurnBlockView(props: { block: AiTurnBlock; turnId: string; streaming?: boolean; active?: boolean }) {
+  const locale = useLocale();
   // The id/kind remain stable while the immutable block value changes during a turn.
   return (
     <Switch>
       <Match when={props.block.kind === "text" && props.block}>
-        {(block) => <AssistantMarkdownBlock html={markdown.renderSync(block().text)} />}
+        {(block) => <AssistantMarkdownBlock html={markdown.renderSync(block().text, { locale: locale() })} />}
       </Match>
       <Match when={props.block.kind === "thinking" && props.block}>
         {(block) => <ThinkingBlockView text={block().text} streaming={props.streaming} />}

package/src/ai/chat/messages.ts

@@ -22,6 +22,9 @@ const messages = i18n.define({
       thinking: "Thinking",
       showReasoning: "Show reasoning",
       byteRange: ({ start, end }: { start: string; end: string }) => `Bytes ${start}–${end}`,
+      streamLoginRequired: "Your session has ended. Sign in again to continue this chat.",
+      streamAccessDenied: "You no longer have access to this chat.",
+      streamNotFound: "This chat is no longer available.",
     },
     de: {
       backgroundRun: "Hintergrundlauf",
@@ -43,6 +46,9 @@ const messages = i18n.define({
       thinking: "Denkt nach",
       showReasoning: "Denkprozess anzeigen",
       byteRange: ({ start, end }) => `Bytes ${start}–${end}`,
+      streamLoginRequired: "Deine Sitzung ist abgelaufen. Melde dich erneut an, um diesen Chat fortzusetzen.",
+      streamAccessDenied: "Du hast keinen Zugriff mehr auf diesen Chat.",
+      streamNotFound: "Dieser Chat ist nicht mehr verfügbar.",
     },
   },
 });

package/src/ai/client/controller.ts

@@ -1,6 +1,7 @@
 import { type Accessor, createMemo, createSignal, onCleanup } from "solid-js";
 import { createStore, reconcile } from "solid-js/store";
 import { type AiAttachmentRef, aiAttachmentMarker } from "../attachments";
+import { aiChatMessages } from "../chat/messages";
 import { type AiStreamEvent, type AiTurnBlock, type AiTurnSnapshot, steerMessageBlockId } from "../protocol";
 import { type AiResourceMarker, aiResourceMarker } from "../resource-markers";
 import type {
@@ -24,7 +25,14 @@ import {
   reduceProjection,
   visibleMessages,
 } from "./projection";
-import { type AiConversationStreamTransport, type AiStreamHandle, aiSseConversationStreamTransport } from "./transport";
+import {
+  type AiConversationStreamTransport,
+  AiStreamError,
+  type AiStreamErrorCode,
+  type AiStreamHandle,
+  aiSseConversationStreamTransport,
+  terminalAiStreamErrorCode,
+} from "./transport";
 
 type ComposerDraftInput = {
   draftContent?: AiDraftContentPart[];
@@ -108,7 +116,7 @@ export type CreateAiChatControllerOptions = {
   frontendTools?: Record<string, AiFrontendToolHandler>;
   /** Explicitly advertise only client tools with a connected handler. */
   clientToolIds?: AiClientToolId[];
-  /** Overrides the default SSE transport, for example with a shared WebSocket channel. */
+  /** Overrides the default SSE transport of the conversation stream. */
   streamTransport?: AiConversationStreamTransport;
 };
 
@@ -142,6 +150,21 @@ const completeFrontendToolBlock = (blocks: AiTurnBlock[], callId: string, result
 const isActiveConversationLoading = (activeConversationId: string | null, loadingConversationId: string | null): boolean =>
   activeConversationId !== null && loadingConversationId === activeConversationId;
 
+/**
+ * Why the stream ended, in the request's locale: the server renders it into
+ * `<html lang>`, which is also what `useLocale()` of `@k2b/ui` resolves in an
+ * island. The controller stays headless and does not load the component library.
+ */
+const streamErrorText = (code: AiStreamErrorCode): string => {
+  const t = aiChatMessages(typeof document === "undefined" ? "en" : document.documentElement.lang || "en");
+  if (code === "login_required") return t.streamLoginRequired;
+  return code === "access_denied" ? t.streamAccessDenied : t.streamNotFound;
+};
+
+/** A chat that cannot continue says why in the page's language; any other error shows its own message. */
+const errorText = (error: unknown, fallback: string): string =>
+  error instanceof AiStreamError ? streamErrorText(error.code) : error instanceof Error ? error.message : fallback;
+
 export const createAiChatController = (options: CreateAiChatControllerOptions) => {
   const [activeConversationId, setActiveConversationIdSignal] = createSignal<string | null>(options.initialConversationId ?? null);
   const [globalError, setGlobalError] = createSignal<string | null>(options.initialError ?? null);
@@ -178,6 +201,8 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
   const abortRequests = new Map<string, Promise<boolean>>();
   let stream: AiStreamHandle | null = null;
   let streamSession: AiStreamSession | null = null;
+  /** The chat error left by a stream that ended for good, until a stream opens again. */
+  let streamError: string | null = null;
   let streamGeneration = 0;
   let conversationOpenGeneration = 0;
   let historyTargetSeq: number | null = null;
@@ -217,9 +242,12 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
     if (activeConversationId()) setGlobalError(message);
     else setGlobalError(message);
   };
+  /** Starts the person's next action in the active chat clean, including a stream that ended with an error. */
   const clearErrors = () => {
     setGlobalError(null);
     setRunError(null);
+    const conversationId = activeConversationId();
+    if (conversationId) openStream(conversationId);
   };
   const error = () => globalError() ?? runError();
 
@@ -314,17 +342,29 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
       conversationId,
       url: url(`/conversations/${conversationId}/stream`),
       onStatus: (status) => {
-        if (isCurrentStreamSession(streamSession, session)) setStreamStatus(status);
+        if (!isCurrentStreamSession(streamSession, session)) return;
+        setStreamStatus(status);
+        if (status !== "open" || streamError === null) return;
+        if (globalError() === streamError) setGlobalError(null);
+        streamError = null;
       },
       onEvent: (event) => applyEvent(session, event),
+      // The transport has stopped. Drop its handle so the next visit, refresh,
+      // or action in this chat can subscribe again.
       onError: (error) => {
         if (!isCurrentStreamSession(streamSession, session)) return;
-        setStreamStatus("idle");
-        setConversationError(conversationId, error.message);
+        endStream(conversationId, error);
       },
     });
   };
 
+  /** Stops the chat's stream for good and shows why. */
+  const endStream = (conversationId: string, error: Error) => {
+    closeStream();
+    streamError = errorText(error, error.message);
+    setConversationError(conversationId, streamError);
+  };
+
   // ---- frontend tools ---------------------------------------------------
 
   const runFrontendTools = () => {
@@ -381,13 +421,20 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
     } catch {}
   };
 
+  /** Loads a chat. A status after which no retry can load it throws an `AiStreamError`, like the stream's. */
+  const fetchDetail = async (conversationId: string, fallback: string): Promise<AiConversationDetail> => {
+    const response = await fetch(url(`/conversations/${conversationId}`));
+    if (response.ok) return (await response.json()) as AiConversationDetail;
+    const message = await readError(response, fallback);
+    const ended = terminalAiStreamErrorCode(response.status);
+    throw ended ? new AiStreamError(ended, message) : new Error(message);
+  };
+
   const loadDetail = async (conversationId: string, shouldReportError: () => boolean): Promise<AiConversationDetail | null> => {
     try {
-      return await request<AiConversationDetail>(`/conversations/${conversationId}`, { method: "GET" }, "Failed to open conversation");
+      return await fetchDetail(conversationId, "Failed to open conversation");
     } catch (loadError) {
-      if (shouldReportError()) {
-        setConversationError(conversationId, loadError instanceof Error ? loadError.message : "Failed to open conversation");
-      }
+      if (shouldReportError()) setConversationError(conversationId, errorText(loadError, "Failed to open conversation"));
       return null;
     }
   };
@@ -422,6 +469,7 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
 
   const openConversation = async (conversationId: string) => {
     if (activeConversationId() === conversationId && state.conversation?.id === conversationId) {
+      openStream(conversationId);
       void markConversationViewed(conversationId);
       return "current" as const;
     }
@@ -461,22 +509,31 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
   };
 
   let conversationRefreshGeneration = 0;
-  const refreshActiveConversation = async (): Promise<void> => {
+  /**
+   * Loads the active chat again. Resolves `false` when it no longer exists or
+   * is no longer readable: the chat then ends like its stream, with the reason
+   * as its error, because no retry can load it. A response that a newer
+   * refresh or a newer opening of a chat overtook changes nothing.
+   */
+  const refreshActiveConversation = async (): Promise<boolean> => {
     const conversationId = activeConversationId();
-    if (!conversationId) return;
+    if (!conversationId) return true;
     const refreshGeneration = ++conversationRefreshGeneration;
     const openGeneration = conversationOpenGeneration;
-    const detail = await request<AiConversationDetail>(
-      `/conversations/${conversationId}`,
-      { method: "GET" },
-      "Failed to refresh conversation",
-    );
-    if (
+    const overtaken = () =>
       !isActiveConversation(conversationId) ||
       refreshGeneration !== conversationRefreshGeneration ||
-      openGeneration !== conversationOpenGeneration
-    )
-      return;
+      openGeneration !== conversationOpenGeneration;
+    let detail: AiConversationDetail;
+    try {
+      detail = await fetchDetail(conversationId, "Failed to refresh conversation");
+    } catch (refreshError) {
+      if (!(refreshError instanceof AiStreamError)) throw refreshError;
+      if (overtaken()) return true;
+      endStream(conversationId, refreshError);
+      return false;
+    }
+    if (overtaken()) return true;
     const currentDraft = state.conversation?.draft;
     if (currentDraft && currentDraft.revision > detail.conversation.draft.revision) detail.conversation.draft = currentDraft;
     const windowOldest = detail.messages[0]?.seq;
@@ -485,6 +542,8 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
     if (preservedOlder.length === 0) setHasMore(conversationId, detail.hasMoreMessages ?? false);
     if (detail.timeline) setTimeline(conversationId, detail.timeline);
     setRunError(conversationRunError(detail.conversation));
+    openStream(conversationId);
+    return true;
   };
 
   const requestMessagesPage = async (conversationId: string, before: number, limit: number): Promise<AiMessagesPage> => {
@@ -573,8 +632,8 @@ export const createAiChatController = (options: CreateAiChatControllerOptions) =
     if (conversationId) void openConversation(conversationId);
     else {
       conversationOpenGeneration += 1;
-      clearErrors();
       setActiveConversationIdSignal(null);
+      clearErrors();
       historyTargetSeq = null;
       setLoadingConversationId(null);
       closeStream();

package/src/ai/client/transport.ts

@@ -13,6 +13,38 @@ export type AiConversationStreamTransport = {
   }) => AiStreamHandle;
 };
 
+/** Why a conversation stream ended for good. A client shows its own text for the code. */
+export type AiStreamErrorCode = "login_required" | "access_denied" | "not_found";
+
+/** A stream that will not recover by reconnecting; `message` comes from the server when it sent one. */
+export class AiStreamError extends Error {
+  readonly code: AiStreamErrorCode;
+
+  constructor(code: AiStreamErrorCode, message: string) {
+    super(message);
+    this.name = "AiStreamError";
+    this.code = code;
+  }
+}
+
+const TERMINAL_STATUS_CODES: Readonly<Record<number, AiStreamErrorCode>> = {
+  401: "login_required",
+  403: "access_denied",
+  404: "not_found",
+};
+
+/** The code of an HTTP status after which a conversation cannot continue, by retrying or reconnecting. */
+export const terminalAiStreamErrorCode = (status: number): AiStreamErrorCode | undefined => TERMINAL_STATUS_CODES[status];
+
+const terminalStreamError = async (response: Response, code: AiStreamErrorCode): Promise<AiStreamError> => {
+  const body: unknown = await response.json().catch(() => null);
+  const message =
+    body && typeof body === "object" && "message" in body && typeof body.message === "string" && body.message
+      ? body.message
+      : `AI stream failed: ${response.status}`;
+  return new AiStreamError(code, message);
+};
+
 const RECONNECT_BASE_MS = 500;
 const RECONNECT_MAX_MS = 5_000;
 const CONNECT_TIMEOUT_MS = 10_000;
@@ -53,12 +85,15 @@ export async function* parseAiSse(response: Response, signal: AbortSignal): Asyn
 /**
  * Subscribe to a conversation's SSE stream with automatic reconnect. Each
  * (re)connect starts with a fresh `state` event, so the projection self-heals on
- * every reconnect without cursor bookkeeping.
+ * every reconnect without cursor bookkeeping. A 401, 403, or 404 cannot heal
+ * that way: the subscription stops and reports an `AiStreamError` once through
+ * `onError`, its only signal that the stream ended. Status stays where it was.
  */
 export const subscribeAiStream = (input: {
   url: string;
   onEvent: (event: AiStreamEvent) => void;
   onStatus?: (status: AiStreamConnectionStatus) => void;
+  onError?: (error: AiStreamError) => void;
   fetch?: AiStreamFetch;
 }): AiStreamHandle => {
   const fetchStream: AiStreamFetch = input.fetch ?? fetch;
@@ -80,8 +115,17 @@ export const subscribeAiStream = (input: {
       try {
         input.onStatus?.(reconnectDelay === RECONNECT_BASE_MS ? "connecting" : "reconnecting");
         const response = await fetchStream(input.url, { signal: attempt.signal, headers: { Accept: "text/event-stream" } });
-        clearConnectTimer();
         if (stopped) return;
+        const terminalCode = terminalAiStreamErrorCode(response.status);
+        if (terminalCode) {
+          // The connect timeout still bounds reading the error body.
+          const error = await terminalStreamError(response, terminalCode);
+          if (stopped) return;
+          stopped = true;
+          input.onError?.(error);
+          return;
+        }
+        clearConnectTimer();
         if (!response.ok || !response.body) throw new Error(`AI stream failed: ${response.status}`);
         input.onStatus?.("open");
         reconnectDelay = RECONNECT_BASE_MS;
@@ -113,5 +157,5 @@ export const subscribeAiStream = (input: {
 };
 
 export const aiSseConversationStreamTransport: AiConversationStreamTransport = {
-  subscribe: ({ url, onEvent, onStatus }) => subscribeAiStream({ url, onEvent, onStatus }),
+  subscribe: ({ url, onEvent, onStatus, onError }) => subscribeAiStream({ url, onEvent, onStatus, onError }),
 };