@elytracms/studio 0.0.55 → 0.0.57

package/convex/auth.ts

@@ -1,7 +1,8 @@
 import { convexAuth } from '@convex-dev/auth/server'
 import { Password } from '@convex-dev/auth/providers/Password'
+import { actionGeneric } from 'convex/server'
 import type { AnyDataModel, GenericMutationCtx } from 'convex/server'
-import { ConvexError } from 'convex/values'
+import { ConvexError, v } from 'convex/values'
 import type { GenericId } from 'convex/values'
 import { classifyInviteSignup, normalizeInviteEmail } from '@elytracms/core/persistence'
 import type { InviteSignupDecision } from '@elytracms/core/persistence'
@@ -9,6 +10,99 @@ import type { InviteSignupDecision } from '@elytracms/core/persistence'
 /** The provider list `convexAuth` accepts, derived from its own signature. */
 type ConvexAuthProviders = Parameters<typeof convexAuth>[0]['providers']
 
+/**
+ * EC-363 — stable, secret-free sign-in failure codes. A PRODUCTION Convex
+ * deployment redacts a thrown error's `.message` to a generic "Server Error"
+ * before it reaches the client; only a `ConvexError`'s `.data` survives. But
+ * `@convex-dev/auth@0.0.94` throws its credential/env failures as PLAIN
+ * `Error`s, so on prod every wrong password collapsed onto the client's
+ * honest-generic fallback (EC-362's key finding). These codes ride in
+ * `ConvexError.data` across that redaction so the sign-in screen can tell the
+ * truth. Codes ONLY — never the raw library message (it can carry the account
+ * id / env-var names).
+ *
+ * EC-377 widened the family beyond sign-in: `users:changePassword` codes its
+ * provider throws with the same table (a wrong CURRENT password is an
+ * `InvalidSecret` → `invalid-credentials`), plus `weak-password` for its own
+ * min-length guard (the reset flow validates it, `modifyAccountCredentials`
+ * does not — and the client UI doesn't pre-validate).
+ */
+export type StudioAuthErrorCode =
+  | 'invalid-credentials'
+  | 'too-many-attempts'
+  | 'account-exists'
+  | 'deployment-misconfigured'
+  | 'weak-password'
+
+/**
+ * Map a `@convex-dev/auth` plain-`Error` message to a stable code — or `null`
+ * when unrecognized (the caller then rethrows the original error untouched, so
+ * unknown failures keep today's honest-generic behavior; never misclassify).
+ *
+ * The matched throw sites, pinned in the installed `@convex-dev/auth@0.0.94`:
+ *
+ * - `retrieveAccount` → `throw new Error(result)` with `result` ∈
+ *   `"InvalidSecret" | "InvalidAccountId" | "TooManyFailedAttempts"`
+ *   (`dist/server/implementation/index.js`; the strings come from
+ *   `mutations/retrieveAccountWithCredentials.js`). Thrown INSIDE the signIn
+ *   action.
+ * - The `Password` provider's own in-action throws: `"Invalid password"`
+ *   (default password requirements at sign-up) and `"Invalid credentials"`
+ *   (`dist/providers/Password.js`).
+ * - `requireEnv` → ``throw new Error(`Missing environment variable \`${name}\``)``
+ *   (`dist/server/utils.js`) and jose's `importPKCS8` PKCS8/private-key parse
+ *   errors — the EC-257 misconfigured-deployment family. These fire inside the
+ *   library's `auth:store` MUTATION (`generateToken`); the backend propagates
+ *   sub-call errors to the calling action UNREDACTED even on prod (redaction is
+ *   client-boundary only — `RedactedJsError` is constructed solely in the
+ *   sync-worker/HTTP-API crates), so the action-seam catch still sees the token.
+ * - `createAccountFromCredentials` → ``Account ${account.id} already exists``
+ *   (`dist/server/implementation/mutations/createAccountFromCredentials.js`),
+ *   also via the store mutation.
+ *
+ * Order matters: the env/signing-key family is checked FIRST (those throws fire
+ * after password validation and must never degrade to a credential code —
+ * mirrors the client ladder, EC-257).
+ */
+export function classifyAuthLibraryError(message: string): StudioAuthErrorCode | null {
+  if (/Missing environment variable|JWT_PRIVATE_KEY|JWKS|PKCS8|private key/i.test(message)) {
+    return 'deployment-misconfigured'
+  }
+  if (/TooManyFailedAttempts/.test(message)) return 'too-many-attempts'
+  if (/already exists/.test(message)) return 'account-exists'
+  if (/InvalidSecret|InvalidAccountId|Invalid credentials|Invalid password/.test(message)) {
+    return 'invalid-credentials'
+  }
+  return null
+}
+
+/**
+ * EC-363 — the coding step for the signIn wrap: return a `ConvexError` whose
+ * `.data` carries a {@link StudioAuthErrorCode} for a recognized library throw,
+ * or the ORIGINAL error untouched for everything else.
+ *
+ * - An error already carrying `.data` (a `ConvexError`, e.g. the invite gate's
+ *   `NOT_INVITED_REASON` crossing the store-mutation boundary) passes through
+ *   unchanged — its data already survives prod redaction. Duck-typed, not
+ *   `instanceof` (dual module instances, EC-357/EC-362).
+ * - Unrecognized errors pass through unchanged: which cases fail and how they
+ *   read today is preserved exactly; when in doubt, the client's honest generic.
+ */
+export function toCodedSignInError(error: unknown): unknown {
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    'data' in error &&
+    (error as { data: unknown }).data !== undefined
+  ) {
+    return error
+  }
+  const message = error instanceof Error ? error.message : typeof error === 'string' ? error : ''
+  const code = classifyAuthLibraryError(message)
+  if (code === null) return error
+  return new ConvexError({ code })
+}
+
 /** The (non-schema-bound) mutation ctx the `convexAuth` callbacks receive. */
 type AuthCallbackCtx = GenericMutationCtx<AnyDataModel>
 
@@ -156,7 +250,7 @@ export async function gateSessionCreation(
  * project-owned `AuthAdapter`, so swapping providers later is one factory call, not UI.
  */
 export function defineStudioAuth(options?: { providers?: ConvexAuthProviders }) {
-  return convexAuth({
+  const api = convexAuth({
     providers: options?.providers ?? [Password],
     callbacks: {
       /** EC-358: reject uninvited account creation BEFORE any row commits. */
@@ -169,4 +263,60 @@ export function defineStudioAuth(options?: { providers?: ConvexAuthProviders })
       },
     },
   })
+
+  // EC-363: wrap the `auth:signIn` ACTION so the library's plain-`Error`
+  // credential/env throws reach the client as `ConvexError`s carrying a stable
+  // code (`.data` survives prod redaction; `.message` does not). The wrap is a
+  // pure delegate — same args validators, same mechanics, same success values;
+  // ONLY the thrown-error shape changes, and only for recognized library throws
+  // (see `toCodedSignInError`). Re-registering is required because the
+  // registered action's `invokeAction` closes over the ORIGINAL handler
+  // (mutating `_handler` after the fact would not take effect).
+  //
+  // `_handler` is set by every `actionGeneric` registration in the installed
+  // convex runtime (`dist/esm/server/impl/registration_impl.js`) but is not in
+  // the public type — hence the structural cast. The loud throw below runs at
+  // module-definition time, so a convex upgrade that drops the seam fails the
+  // functions push visibly instead of silently shipping unwrapped errors.
+  const rawSignInHandler = (
+    api.signIn as unknown as {
+      _handler?: (ctx: unknown, args: unknown) => Promise<unknown>
+    }
+  )._handler
+  if (typeof rawSignInHandler !== 'function') {
+    throw new Error(
+      'defineStudioAuth: convexAuth().signIn no longer exposes `_handler` — the EC-363 ' +
+        'coded-auth-error wrap cannot attach. Check the installed convex runtime.',
+    )
+  }
+  const signIn = actionGeneric({
+    // Mirrors the library's own `signIn` validators exactly (@convex-dev/auth
+    // 0.0.94, `dist/server/implementation/index.js`) so argument validation is
+    // unchanged.
+    args: {
+      provider: v.optional(v.string()),
+      params: v.optional(v.any()),
+      verifier: v.optional(v.string()),
+      refreshToken: v.optional(v.string()),
+      calledBy: v.optional(v.string()),
+    },
+    handler: async (ctx, args) => {
+      try {
+        return await rawSignInHandler(ctx, args)
+      } catch (error) {
+        const coded = toCodedSignInError(error)
+        if (coded !== error) {
+          // Keep the ORIGINAL failure visible in the deployment logs — the
+          // client now only receives the stable code.
+          console.error('auth:signIn failed:', error)
+        }
+        throw coded
+      }
+    },
+    // The delegate preserves the original action's runtime contract; align the
+    // exported type with it so consumers' `convex/auth.ts` re-exports and
+    // codegen see the exact same `signIn` surface as before.
+  }) as unknown as typeof api.signIn
+
+  return { ...api, signIn }
 }

package/convex/users.ts

@@ -4,7 +4,9 @@ import {
   retrieveAccount,
 } from '@convex-dev/auth/server'
 import { makeFunctionReference } from 'convex/server'
-import { v } from 'convex/values'
+import { ConvexError, v } from 'convex/values'
+import { toCodedSignInError } from './auth'
+import type { StudioAuthErrorCode } from './auth'
 import { action, mutation, query } from './functions'
 import type { QueryCtx } from './functions'
 import { requireCapability } from './guard'
@@ -146,6 +148,16 @@ const meRef = makeFunctionReference<'query', Record<string, never>, MeResult | n
  * provider and are NEVER logged or persisted by this code. Self-scoped: it
  * derives the caller from the JWT and cross-checks the retrieved account is the
  * caller's own before modifying.
+ *
+ * EC-377: the provider-call failure path re-throws through the EC-363
+ * `toCodedSignInError` wrap — `@convex-dev/auth` throws its failures as PLAIN
+ * `Error`s (`retrieveAccount` → `"InvalidSecret"` on a wrong CURRENT password),
+ * and a PROD deployment redacts a plain error's `.message` to "Server Error",
+ * so without the wrap the client's honest-generic fallback swallowed the truth.
+ * Recognized throws become `ConvexError({ code })` (`.data` survives prod
+ * redaction; codes ONLY, never the raw message); everything else — including
+ * this action's own `unauthorized: …` guards — passes through UNTOUCHED, so
+ * which cases fail is unchanged.
  */
 export const changePassword = action({
   args: { currentPassword: v.string(), newPassword: v.string() },
@@ -153,21 +165,36 @@ export const changePassword = action({
     const userId = await getAuthUserId(ctx)
     if (userId === null) throw new Error('unauthorized: this function requires an authenticated user')
     // Enforce the provider's default password policy (min length) — the reset
-    // flow validates it, but `modifyAccountCredentials` does not.
-    if (newPassword.length < 8) throw new Error('Password must be at least 8 characters')
+    // flow validates it, but `modifyAccountCredentials` does not. Coded (EC-377):
+    // the credential panel has no client-side length check, so this guard is
+    // user-reachable and must classify truthfully on prod too.
+    if (newPassword.length < 8) {
+      throw new ConvexError({ code: 'weak-password' satisfies StudioAuthErrorCode })
+    }
     const me = await ctx.runQuery(meRef, {})
     if (!me?.email) throw new Error('unauthorized: no account email on file')
-    // Verify the CURRENT password; throws on mismatch (→ invalid-credentials).
-    const { user } = await retrieveAccount(ctx, {
-      provider: 'password',
-      account: { id: me.email, secret: currentPassword },
-    })
-    // Defense in depth: the retrieved account MUST be the caller's own.
-    if (String(user._id) !== String(userId)) throw new Error('unauthorized: account mismatch')
-    await modifyAccountCredentials(ctx, {
-      provider: 'password',
-      account: { id: me.email, secret: newPassword },
-    })
+    try {
+      // Verify the CURRENT password; throws on mismatch (→ invalid-credentials).
+      const { user } = await retrieveAccount(ctx, {
+        provider: 'password',
+        account: { id: me.email, secret: currentPassword },
+      })
+      // Defense in depth: the retrieved account MUST be the caller's own.
+      if (String(user._id) !== String(userId)) throw new Error('unauthorized: account mismatch')
+      await modifyAccountCredentials(ctx, {
+        provider: 'password',
+        account: { id: me.email, secret: newPassword },
+      })
+    } catch (error) {
+      const coded = toCodedSignInError(error)
+      if (coded !== error) {
+        // Keep the ORIGINAL failure visible in the deployment logs — the client
+        // only receives the stable code. (`retrieveAccount` throws bare token
+        // messages; the raw password values never appear in any error.)
+        console.error('users:changePassword failed:', error)
+      }
+      throw coded
+    }
     return null
   },
 })

package/dist/components/ai/ai-chat-panel-lazy.js

@@ -3,9 +3,9 @@ import { Suspense, lazy } from 'react';
 import { Text } from '@elytracms/studio/ui';
 import { translate } from '@elytracms/studio/lib/i18n';
 /**
- * Lazy boundary for the AI chat panel (EC-199, EC-331 bundle discipline). The panel
- * and everything it imports — the creation orchestrator, `applyContentWithShape`, the
- * provider adapters (and the AI SDK behind the Anthropic one via dynamic import) — load
+ * Lazy boundary for the AI chat panel (EC-199, EC-331/EC-334 bundle discipline). The
+ * panel and everything it imports — `useChat` + the AI SDK (`ai` / `@ai-sdk/react`),
+ * the client tool executor, `applyContentWithShape`, the provider adapters — load
  * ONLY when a configured studio actually opens the panel. An unconfigured studio never
  * renders the toggle, never mounts this, and so pulls none of the AI chunk onto the CMS
  * critical path (pinned by the `lib/ai` bundle test). Same pattern as

package/dist/components/ai/ai-chat-panel-lazy.js.map

@@ -1 +1 @@
-{"version":3,"file":"ai-chat-panel-lazy.js","sourceRoot":"","sources":["../../../src/components/ai/ai-chat-panel-lazy.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAEtD;;;;;;;;GAQG;AACH,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAChC,MAAM,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAC9E,CAAA;AAED,SAAS,eAAe;IACtB,OAAO,CACL,gBAAO,SAAS,EAAC,gFAAgF,YAC/F,cAAK,SAAS,EAAC,4CAA4C,YACzD,KAAC,IAAI,IAAC,IAAI,EAAC,IAAI,EAAC,IAAI,EAAC,OAAO,YACzB,SAAS,CAAC,kBAAkB,CAAC,GACzB,GACH,GACA,CACT,CAAA;AACH,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,CACL,KAAC,QAAQ,IAAC,QAAQ,EAAE,KAAC,eAAe,KAAG,YACrC,KAAC,eAAe,KAAG,GACV,CACZ,CAAA;AACH,CAAC","sourcesContent":["import { Suspense, lazy } from 'react'\nimport { Text } from '@elytracms/studio/ui'\nimport { translate } from '@elytracms/studio/lib/i18n'\n\n/**\n * Lazy boundary for the AI chat panel (EC-199, EC-331 bundle discipline). The panel\n * and everything it imports — the creation orchestrator, `applyContentWithShape`, the\n * provider adapters (and the AI SDK behind the Anthropic one via dynamic import) — load\n * ONLY when a configured studio actually opens the panel. An unconfigured studio never\n * renders the toggle, never mounts this, and so pulls none of the AI chunk onto the CMS\n * critical path (pinned by the `lib/ai` bundle test). Same pattern as\n * `version-compare-lazy` / `rich-text/lazy`.\n */\nconst AiChatPanelImpl = lazy(() =>\n  import('./ai-chat-panel').then((module) => ({ default: module.AiChatPanel })),\n)\n\nfunction AiPanelFallback() {\n  return (\n    <aside className=\"flex h-full min-h-0 w-[360px] shrink-0 flex-col border-l border-border bg-card\">\n      <div className=\"grid min-h-0 flex-1 place-items-center p-6\">\n        <Text size=\"sm\" tone=\"muted\">\n          {translate('ai.panel.loading')}\n        </Text>\n      </div>\n    </aside>\n  )\n}\n\nexport function AiChatPanel() {\n  return (\n    <Suspense fallback={<AiPanelFallback />}>\n      <AiChatPanelImpl />\n    </Suspense>\n  )\n}\n"]}
+{"version":3,"file":"ai-chat-panel-lazy.js","sourceRoot":"","sources":["../../../src/components/ai/ai-chat-panel-lazy.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAEtD;;;;;;;;GAQG;AACH,MAAM,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAChC,MAAM,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAC9E,CAAA;AAED,SAAS,eAAe;IACtB,OAAO,CACL,gBAAO,SAAS,EAAC,gFAAgF,YAC/F,cAAK,SAAS,EAAC,4CAA4C,YACzD,KAAC,IAAI,IAAC,IAAI,EAAC,IAAI,EAAC,IAAI,EAAC,OAAO,YACzB,SAAS,CAAC,kBAAkB,CAAC,GACzB,GACH,GACA,CACT,CAAA;AACH,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,CACL,KAAC,QAAQ,IAAC,QAAQ,EAAE,KAAC,eAAe,KAAG,YACrC,KAAC,eAAe,KAAG,GACV,CACZ,CAAA;AACH,CAAC","sourcesContent":["import { Suspense, lazy } from 'react'\nimport { Text } from '@elytracms/studio/ui'\nimport { translate } from '@elytracms/studio/lib/i18n'\n\n/**\n * Lazy boundary for the AI chat panel (EC-199, EC-331/EC-334 bundle discipline). The\n * panel and everything it imports — `useChat` + the AI SDK (`ai` / `@ai-sdk/react`),\n * the client tool executor, `applyContentWithShape`, the provider adapters — load\n * ONLY when a configured studio actually opens the panel. An unconfigured studio never\n * renders the toggle, never mounts this, and so pulls none of the AI chunk onto the CMS\n * critical path (pinned by the `lib/ai` bundle test). Same pattern as\n * `version-compare-lazy` / `rich-text/lazy`.\n */\nconst AiChatPanelImpl = lazy(() =>\n  import('./ai-chat-panel').then((module) => ({ default: module.AiChatPanel })),\n)\n\nfunction AiPanelFallback() {\n  return (\n    <aside className=\"flex h-full min-h-0 w-[360px] shrink-0 flex-col border-l border-border bg-card\">\n      <div className=\"grid min-h-0 flex-1 place-items-center p-6\">\n        <Text size=\"sm\" tone=\"muted\">\n          {translate('ai.panel.loading')}\n        </Text>\n      </div>\n    </aside>\n  )\n}\n\nexport function AiChatPanel() {\n  return (\n    <Suspense fallback={<AiPanelFallback />}>\n      <AiChatPanelImpl />\n    </Suspense>\n  )\n}\n"]}

package/dist/components/ai/ai-chat-panel.d.ts

@@ -1,10 +1 @@
-/**
- * The AI assistant chat panel (EC-199) — the right-hand collapsible surface in the CMS
- * area. It owns the chat state (the pure `chatReducer`), resolves the EC-331 provider
- * from `defineStudio({ ai })`, binds the narrow tools (search/list) to the operations
- * layer with the user's session, runs the creation orchestrator, and applies a
- * reviewed proposal as a DRAFT (operations upsert + a provenance-tagged version
- * snapshot). NEVER a modal (house rule). The whole module sits behind a lazy boundary
- * (`ai-chat-panel-lazy`), so an unconfigured studio pulls none of it — and no AI SDK.
- */
 export declare function AiChatPanel(): import("react").JSX.Element;

package/dist/components/ai/ai-chat-panel.js

@@ -1,39 +1,63 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useMemo, useReducer, useState } from 'react';
-import { X } from 'lucide-react';
+import { useCallback, useMemo, useReducer, useRef, useState } from 'react';
+import { MessageSquarePlus, X } from 'lucide-react';
+import { DefaultChatTransport, lastAssistantMessageIsCompleteWithToolCalls } from 'ai';
+import { useChat } from '@ai-sdk/react';
 import { createCollectionRegistry, resolveDocumentTitle, } from '@elytracms/core/cms-core';
 import { Button, Heading, Row, Spacer, Text } from '@elytracms/studio/ui';
 import { translate } from '@elytracms/studio/lib/i18n';
 import { STUDIO_PROJECT_ROUTE, studioPath, useNavigate } from '@elytracms/studio/router';
 import { resolveDeploymentAi } from '@elytracms/studio/lib/workspace';
 import { getStudioOperations } from '@elytracms/studio/lib/operations';
-import { AiRouteError, chatReducer, initialChatState, resolveAiConfig, resolveKnowledge, runCreateFlow, } from '@elytracms/studio/lib/ai';
+import { DEFAULT_MAX_STEPS, buildChatContext, chatReviewReducer, clearConversation, createChatCandidateStore, createChatToolExecutor, initialChatReviewState, resolveAiConfig, resolveChatTarget, resolveKnowledge, withStepCap, } from '@elytracms/studio/lib/ai';
 import { useCms } from '../cms/cms-store.js';
 import { validateComposition, validateRichTextEmbeds } from '../cms/cms-composition-validators.js';
-import { AssistantTurn, Conversation, ConversationEmpty, PromptInput, ToolStatus, UserTurn, } from './chat-ui.js';
+import { AssistantTurn, ChatErrorNote, Conversation, ConversationEmpty, PromptInput, ToolStatus, UserTurn, WorkingIndicator, describeToolPart, messageText, segmentMessageParts, } from './chat-ui.js';
 import { ProposalCard } from './proposal-card.js';
 import { setAiPanelOpen } from '@elytracms/studio/lib/ai-panel';
 /**
- * The AI assistant chat panel (EC-199) — the right-hand collapsible surface in the CMS
- * area. It owns the chat state (the pure `chatReducer`), resolves the EC-331 provider
- * from `defineStudio({ ai })`, binds the narrow tools (search/list) to the operations
- * layer with the user's session, runs the creation orchestrator, and applies a
- * reviewed proposal as a DRAFT (operations upsert + a provenance-tagged version
- * snapshot). NEVER a modal (house rule). The whole module sits behind a lazy boundary
- * (`ai-chat-panel-lazy`), so an unconfigured studio pulls none of it — and no AI SDK.
+ * The AI assistant chat panel (EC-199, moved onto the SDK's native protocol by
+ * EC-334) — the right-hand collapsible surface in the CMS area. `useChat` +
+ * `DefaultChatTransport` own the conversation against the route's native chat
+ * branch (visible token streaming); `onToolCall` dispatches into the client
+ * executor map (operations reads + terminal engines, all with the user's own
+ * session); `sendAutomaticallyWhen` is the SDK predicate wrapped with the
+ * per-turn step cap. What the SDK does not own lives in the pure review reducer:
+ * full proposals keyed by `toolCallId` (reviewed as a diff, applied as a DRAFT
+ * via operations upsert + a provenance-tagged snapshot — the EC-199 trust
+ * boundary, unmoved) and blocking errors. EC-380: the "new conversation"
+ * affordance clears busy-safely (stop → new chat id + review reset; pending
+ * proposals are discarded with reject semantics).
+ *
+ * NEVER a modal (house rule). The whole module (including `ai` + `@ai-sdk/react`)
+ * sits behind the lazy boundary (`ai-chat-panel-lazy`) — pinned in bundle tests.
  */
+/** Adapt a `RouteHeaders` (static or thunk) to the transport's headers resolvable. */
+function toTransportHeaders(headers) {
+    return async () => {
+        const resolved = typeof headers === 'function' ? await headers() : headers;
+        const record = {};
+        new Headers(resolved ?? {}).forEach((value, key) => {
+            record[key] = value;
+        });
+        return record;
+    };
+}
 export function AiChatPanel() {
     const cms = useCms();
     const navigate = useNavigate();
-    const [state, dispatch] = useReducer(chatReducer, initialChatState);
+    const [review, dispatch] = useReducer(chatReviewReducer, initialChatReviewState);
     const [input, setInput] = useState('');
+    // EC-380: the conversation counter — bumping it mints a fresh `useChat` id
+    // (a brand-new conversation) and a fresh relation-candidate store.
+    const [conversation, setConversation] = useState(1);
     const projectId = cms.projectId;
     const activeLocale = cms.activeLocale;
     // Resolve the AI platform config once (presence + capability gate). The panel only
     // mounts when configured, but a misconfigured provider still fails loud here.
     const resolved = useMemo(() => resolveAiConfig(resolveDeploymentAi()), []);
     const provider = resolved.resolved?.provider ?? null;
-    const knowledgeSources = resolved.resolved?.knowledge ?? [];
+    const knowledgeSources = useMemo(() => resolved.resolved?.knowledge ?? [], [resolved]);
     const maxRepairAttempts = resolved.resolved?.limits?.maxRepairAttempts;
     const ready = provider !== null && resolved.ok && projectId !== undefined;
     const registry = useMemo(() => createCollectionRegistry(cms.collections), [cms.collections]);
@@ -43,7 +67,7 @@ export function AiChatPanel() {
         ...(doc.localized?.[activeLocale] ?? {}),
     }), [activeLocale]);
     /** Operations-backed tool readers — client-side, with the user's own session. */
-    const tools = useMemo(() => {
+    const readers = useMemo(() => {
         const matches = (query, ...fields) => !query || fields.some((f) => f?.toLowerCase().includes(query.toLowerCase()));
         return {
             async searchDocuments({ collection, query }) {
@@ -74,7 +98,7 @@ export function AiChatPanel() {
                     .map((asset) => ({ id: asset.id, title: asset.title ?? asset.filename }))
                     .filter((r) => matches(query, r.title, r.id));
             },
-            // EC-332: the translate flow loads a full document (draft values + localized).
+            // Full document (draft values + localized) — the getDocument/translate tools.
             async getDocument({ collection, id }) {
                 if (projectId === undefined)
                     return null;
@@ -110,53 +134,122 @@ export function AiChatPanel() {
         })
             .filter((item) => item.content.trim().length > 0);
     }, [projectId, cms, localeValues]);
-    const runTurn = useCallback(async (text) => {
-        if (!provider)
-            return;
-        try {
+    // The knowledge snapshot the executors read — refreshed by the body thunk on
+    // every request, so the terminal engines see what the model saw this turn.
+    const knowledgeRef = useRef({ items: [] });
+    // The chat transport target: the configured route provider's endpoint +
+    // session-header thunk (EC-371), re-evaluated per request.
+    const chatTarget = useMemo(() => resolveChatTarget(provider), [provider]);
+    const transport = useMemo(() => new DefaultChatTransport({
+        api: chatTarget.endpoint,
+        headers: toTransportHeaders(chatTarget.headers),
+        // The `body` THUNK — re-evaluated per request (fresh context every turn,
+        // continuations included): collections-catalog summary + client-resolved
+        // knowledge. The route folds these sections into the system prompt; it
+        // resolves no data itself (zero-data-access proxy). EC-378's
+        // current-document block joins via `extraSections`.
+        body: async () => {
             const knowledge = await resolveKnowledge(knowledgeSources, { readCollection });
-            const result = await runCreateFlow({
-                provider,
-                tools,
-                registry,
-                collections: cms.collections,
-                instruction: text,
-                knowledge,
-                locale: activeLocale,
-                localeConfig: cms.localeConfig,
-                mintDocumentId,
-                validateRichTextEmbeds,
-                validateComposition,
-                ...(maxRepairAttempts !== undefined ? { maxRepairAttempts } : {}),
-                onStep: (step) => dispatch({ type: 'step', step }),
-            });
-            dispatch({ type: 'result', result });
-        }
-        catch (error) {
-            const message = error instanceof AiRouteError
-                ? translate('ai.error.route')
-                : translate('ai.error.generic');
-            dispatch({ type: 'fail', message });
-        }
+            knowledgeRef.current = knowledge;
+            return { context: buildChatContext({ collections: cms.collections, knowledge }) };
+        },
+    }), [chatTarget, knowledgeSources, readCollection, cms.collections]);
+    // Per-conversation relation-candidate store (EC-380: replaced on clear, so a
+    // fresh conversation cannot reference the previous one's searched ids).
+    const candidatesRef = useRef({
+        conversation,
+        store: createChatCandidateStore(),
+    });
+    if (candidatesRef.current.conversation !== conversation) {
+        candidatesRef.current = { conversation, store: createChatCandidateStore() };
+    }
+    const candidateStore = candidatesRef.current.store;
+    const executor = useMemo(() => {
+        if (!provider)
+            return null;
+        return createChatToolExecutor({
+            provider,
+            registry,
+            collections: cms.collections,
+            readers,
+            mintDocumentId,
+            candidates: candidateStore,
+            onProposal: (toolCallId, proposal) => dispatch({ type: 'propose', toolCallId, proposal }),
+            knowledge: () => knowledgeRef.current,
+            locale: activeLocale,
+            ...(cms.localeConfig ? { localeConfig: cms.localeConfig } : {}),
+            validateRichTextEmbeds,
+            validateComposition,
+            ...(maxRepairAttempts !== undefined ? { maxRepairAttempts } : {}),
+        });
     }, [
         provider,
-        knowledgeSources,
-        readCollection,
-        tools,
         registry,
         cms.collections,
-        activeLocale,
+        cms.localeConfig,
+        readers,
         mintDocumentId,
+        activeLocale,
         maxRepairAttempts,
+        candidateStore,
     ]);
+    const chat = useChat({
+        // A new conversation is a new chat id — `useChat` recreates its state.
+        id: `elytra-assistant-${conversation}`,
+        transport,
+        onToolCall: async ({ toolCall }) => {
+            if (!executor)
+                return;
+            const outcome = await executor.execute({
+                toolCallId: toolCall.toolCallId,
+                toolName: toolCall.toolName,
+                input: toolCall.input,
+            });
+            // Deliberately NOT awaited: `onToolCall` runs inside the chat's serial
+            // stream job, and `addToolOutput` enqueues on the same executor —
+            // awaiting it here deadlocks the stream (verified against ai@7.0.22).
+            if (outcome.ok) {
+                void chat.addToolOutput({
+                    tool: toolCall.toolName,
+                    toolCallId: toolCall.toolCallId,
+                    output: outcome.output,
+                });
+            }
+            else {
+                void chat.addToolOutput({
+                    state: 'output-error',
+                    tool: toolCall.toolName,
+                    toolCallId: toolCall.toolCallId,
+                    errorText: outcome.errorText,
+                });
+            }
+        },
+        // The SDK predicate wrapped with the per-user-turn step cap: a capped turn
+        // stops cleanly with a visible note — never a silent stall (EC-334).
+        sendAutomaticallyWhen: withStepCap(lastAssistantMessageIsCompleteWithToolCalls, {
+            maxSteps: DEFAULT_MAX_STEPS,
+            onCap: () => dispatch({ type: 'fail', message: translate('ai.error.stepCap', { max: DEFAULT_MAX_STEPS }) }),
+        }),
+        onError: () => dispatch({ type: 'fail', message: translate('ai.error.route') }),
+    });
+    const busy = chat.status === 'submitted' || chat.status === 'streaming';
     const submit = useCallback(() => {
         const text = input.trim();
-        if (text.length === 0 || state.status === 'busy' || !ready)
+        if (text.length === 0 || busy || !ready)
             return;
         setInput('');
-        dispatch({ type: 'submit', text });
-        void runTurn(text);
-    }, [input, state.status, ready, runTurn]);
+        dispatch({ type: 'clear-error' });
+        void chat.sendMessage({ text });
+    }, [input, busy, ready, chat]);
+    // EC-380: clear / new topic — busy-safe (stop first), pending proposals
+    // discarded with reject semantics (the review state resets; nothing was applied).
+    const startNewConversation = useCallback(() => {
+        void clearConversation({ status: chat.status, stop: chat.stop }, () => {
+            dispatch({ type: 'clear' });
+            setInput('');
+            setConversation((current) => current + 1);
+        });
+    }, [chat.status, chat.stop]);
     const applyProposal = useCallback(async (proposal) => {
         if (projectId === undefined)
             return;
@@ -188,7 +281,7 @@ export function AiChatPanel() {
         }
         // Reflect in the session so the new draft shows in the list + is navigable.
         cms.saveDocument(doc);
-        dispatch({ type: 'apply', proposalId: proposal.id });
+        dispatch({ type: 'apply', toolCallId: proposal.id });
     }, [projectId, cms]);
     const openProposal = useCallback((proposal) => {
         if (projectId === undefined)
@@ -198,14 +291,22 @@ export function AiChatPanel() {
             params: { projectId, _splat: studioPath.cmsDocument(proposal.collection, proposal.documentId) },
         });
     }, [navigate, projectId]);
-    return (_jsxs("aside", { className: "flex h-full min-h-0 w-[360px] shrink-0 flex-col border-l border-border bg-card", children: [_jsxs(Row, { gap: "2", align: "center", className: "h-12 shrink-0 border-b border-border px-3", children: [_jsx(Heading, { level: 2, size: "h4", children: translate('ai.panel.title') }), _jsx(Spacer, {}), _jsx(Button, { size: "icon-sm", variant: "ghost", onClick: () => setAiPanelOpen(false), title: translate('ai.panel.close'), "aria-label": translate('ai.panel.close'), children: _jsx(X, {}) })] }), _jsxs(Conversation, { atBottomKey: state.messages, children: [state.messages.length === 0 ? _jsx(ConversationEmpty, {}) : null, state.messages.map((message) => {
-                        if (message.role === 'user')
-                            return _jsx(UserTurn, { text: message.text }, message.id);
-                        if (message.kind === 'text')
-                            return (_jsx(AssistantTurn, { children: _jsx(Text, { size: "sm", className: "whitespace-pre-wrap break-words", children: message.text }) }, message.id));
-                        if (message.kind === 'activity')
-                            return (_jsx(AssistantTurn, { children: _jsx(ToolStatus, { steps: message.steps, active: state.status === 'busy' && state.activityId === message.id }) }, message.id));
-                        return (_jsx(ProposalCard, { proposal: message.proposal, onApply: () => void applyProposal(message.proposal), onDiscard: () => dispatch({ type: 'reject', proposalId: message.proposal.id }), onOpen: () => openProposal(message.proposal) }, message.id));
-                    })] }), ready ? (_jsx(PromptInput, { value: input, onChange: setInput, onSubmit: submit, disabled: state.status === 'busy' })) : (_jsx("div", { className: "border-t border-border p-3", children: _jsx(Text, { size: "xs", tone: "muted", children: translate('ai.panel.unavailable') }) }))] }));
+    const hasProposal = useCallback((toolCallId) => review.proposals[toolCallId] !== undefined, [review.proposals]);
+    const renderAssistantMessage = (message) => {
+        const segments = segmentMessageParts(message.parts, hasProposal);
+        return segments.map((segment, index) => {
+            if (segment.kind === 'text') {
+                return (_jsx(AssistantTurn, { children: _jsx(Text, { size: "sm", className: "whitespace-pre-wrap break-words", children: segment.text }) }, `${message.id}-${index}`));
+            }
+            if (segment.kind === 'tools') {
+                return (_jsx(AssistantTurn, { children: _jsx(ToolStatus, { steps: segment.parts.map(describeToolPart) }) }, `${message.id}-${index}`));
+            }
+            const proposal = review.proposals[segment.toolCallId];
+            if (!proposal)
+                return null;
+            return (_jsx(ProposalCard, { proposal: proposal, onApply: () => void applyProposal(proposal), onDiscard: () => dispatch({ type: 'reject', toolCallId: proposal.id }), onOpen: () => openProposal(proposal) }, segment.toolCallId));
+        });
+    };
+    return (_jsxs("aside", { className: "flex h-full min-h-0 w-[360px] shrink-0 flex-col border-l border-border bg-card", children: [_jsxs(Row, { gap: "2", align: "center", className: "h-12 shrink-0 border-b border-border px-3", children: [_jsx(Heading, { level: 2, size: "h4", children: translate('ai.panel.title') }), _jsx(Spacer, {}), _jsx(Button, { size: "icon-sm", variant: "ghost", onClick: startNewConversation, disabled: chat.messages.length === 0 && review.error === null && !busy, title: translate('ai.panel.newConversation'), "aria-label": translate('ai.panel.newConversation'), children: _jsx(MessageSquarePlus, {}) }), _jsx(Button, { size: "icon-sm", variant: "ghost", onClick: () => setAiPanelOpen(false), title: translate('ai.panel.close'), "aria-label": translate('ai.panel.close'), children: _jsx(X, {}) })] }), _jsxs(Conversation, { atBottomKey: chat.messages, children: [chat.messages.length === 0 ? _jsx(ConversationEmpty, {}) : null, chat.messages.map((message) => message.role === 'user' ? (_jsx(UserTurn, { text: messageText(message) }, message.id)) : (_jsx("div", { className: "contents", children: renderAssistantMessage(message) }, message.id))), chat.status === 'submitted' ? (_jsx(AssistantTurn, { children: _jsx(WorkingIndicator, {}) })) : null, review.error !== null ? (_jsx(AssistantTurn, { children: _jsx(ChatErrorNote, { message: review.error }) })) : null] }), ready ? (_jsx(PromptInput, { value: input, onChange: setInput, onSubmit: submit, disabled: busy })) : (_jsx("div", { className: "border-t border-border p-3", children: _jsx(Text, { size: "xs", tone: "muted", children: translate('ai.panel.unavailable') }) }))] }));
 }
 //# sourceMappingURL=ai-chat-panel.js.map