@firstlovecenter/ai-chat 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to `@firstlovecenter/ai-chat` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.2] — 2026-05-08
+
+### Added
+
+- **Live elapsed counter while the agent is thinking** — the inline thinking indicator now shows `Thinking… (Xs)` with a live ticker that advances every second. Suppresses sub-second values (no flicker on instant responses).
+- **Final duration after the action buttons** — once the agent marks a turn done, the wall-clock duration appears to the right of the Copy / Retry buttons (`5s`, `1m`, `2m 30s` style). Restored history (sessions loaded from the DB) shows nothing here since durations weren't persisted.
+
+The new `AnswerState.startedAt` and `AnswerState.durationMs` fields are stamped at submit-time and on every `done: true` flip respectively. Format helper `formatDuration(ms)` produces `Xs`, `Xm`, or `Xm Ys`.
+
+## [0.2.1] — 2026-05-08
+
+### Fixed
+
+- **Chat "Thinking…" indicator visibility** — the spinning indicator was being rendered at the bottom of the thread, below the input pill, where users had to scroll to see it. The thinking state now shows the animated spinner inline next to the AI sparkle avatar where the response will appear, and the redundant bottom indicator is removed. Closes a UX bug reported during initial smoke-testing of `<AiChat />` from the package.
+
+## [0.2.0] — 2026-05-08
+
+### Added
+
+- **`ConfigureAiChatOpts.rolePrompt`** — host-supplied persona prepended to the system blocks on every turn. Accepts a `string` for a static org-wide role or a `(ctx) => string | Promise<string>` function for per-request variation (e.g. different role per scope, locale, or A/B cohort). The role text is marked `cached: true` so it benefits from Anthropic's ephemeral prompt cache and Vertex's automatic prefix cache. Sent every turn (stateless API), but with caching the marginal cost after the first turn rounds to zero for typical 200–500 token roles.
+
+### Fixed
+
+- **Cache marker cap (Claude provider)** — Anthropic limits `cache_control` markers to 4 per request. The provider now silently keeps the marker on the first 4 cached system blocks and drops the hint from any beyond, rather than letting the request fail. This guards against the natural growth of cached blocks once `rolePrompt` is in use (`role` + `system` + `schema` + `semantic-layer` + `scope-summary` would have been 5).
+
+## [0.1.1] — 2026-05-08
+
+### Fixed
+
+- **`AGENT_NO_PRESENT` fallback** — when the model emits text but never calls `present()` (common for advisory questions like "what should we do to increase X?"), the agent loop now wraps the model's text as a single-block `paragraph_brief` `PresentPayload` instead of failing hard. The user always gets a usable answer; the genuine dead end (no tools AND no text) still surfaces the error. The `SELF_VERIFY_REQUIRED` gate is unaffected — it still fires only when the model explicitly calls `present()` with `raw_numbers` it might have hallucinated.
+
+## [0.1.0] — 2026-05-08
+
+Initial public release on npm under `@firstlovecenter/ai-chat`.
+
+### Added
+
+- **`configureAiChat({...})` runtime factory** — single entry point that wires the package's agent loop, narrators, providers, and three route factories with host-supplied ports. Returns `{ runAgent, routes, registries }`.
+- **Six injected ports**:
+  - `PersistencePort` — domain-shaped CRUD for `chat_sessions`, `chat_messages`, `ai_settings`.
+  - `AuthPort<S>` — `requireAuth(req)` + `isSuperAdmin(scope)`.
+  - `ScopePort<S>` — `resolveScopeLabel` + `buildScopeSummary` (UI chip + system-prompt context).
+  - `ToolsPort` — host's tool registry + `buildSystemBlocks(ctx)`.
+  - `VertexPort` — `projectId`, `defaultLocation`, `auth: GoogleAuth` (host constructs; package never reads `process.env.GCP_*`), `modelIds`.
+  - `LoggerPort` — optional structured logging.
+- **Three reference persistence adapters** behind the same `PersistencePort` contract:
+  - `createDrizzlePersistence(db)` — drizzle-orm MySQL (canonical table objects shipped from `@firstlovecenter/ai-chat/server/drizzle`).
+  - `createPrismaPersistence(prisma)` — Prisma client (schema fragment shipped at `prisma/chat-models.prisma` for hosts to paste).
+  - `createMemoryPersistence()` — in-memory adapter for the package's own contract tests (internal-only).
+- **Three route factories** returning Next-compatible handlers:
+  - `agentCustom` — POST SSE handler (Custom chat protocol).
+  - `chatSessions` — list/POST + detail GET/PATCH/DELETE.
+  - `adminSettings` — GET/PATCH for `tool_provider`, `gcp_location`, `chat_interface` (validated against registries).
+- **Lifecycle hooks** consumed by route factories so consuming hosts can plumb in project-specific concerns without forking:
+  - `RouteHooks<S>` (all routes): `onRequest` (before auth — shutdown gating returns 503), `onAuthenticated` (after auth — rate limiting returns 429).
+  - `AgentCustomHooks<S>` (SSE route only): adds `generateSessionId` (per-request session id used for `ToolContext.sessionId` and downstream resources like SQL view names), `onSessionStart` (per-request setup, e.g. `CREATE VIEW`), `onSessionEnd` (always-runs cleanup with `cause: 'complete' | 'error' | 'abort'`).
+- **Two registries** the host's settings UI maps over:
+  - `toolProviders` — built-in `claude` + `gemini` Vertex AI adapters; extensible via `extraToolProviders`.
+  - `chatInterfaces` — `custom` (this package's UI) + `vercel` (placeholder for the Vercel AI SDK build, landing in v0.x).
+- **Custom chat UI** — `AiChat` and `AnswerBlocks` exported from `@firstlovecenter/ai-chat/ui`. Logic lifted byte-for-byte from the original FLC implementation; only host-coupled imports were rewritten.
+- **MIT license**, public `publishConfig`, peer-deps marked optional for `drizzle-orm` and `@prisma/client` so a host installing only one ORM never pulls the other.
+
+### Subpath exports
+
+- `@firstlovecenter/ai-chat/server`         — runtime factory, agent loop, ports, registries, types.
+- `@firstlovecenter/ai-chat/server/drizzle` — drizzle adapter + canonical table objects.
+- `@firstlovecenter/ai-chat/server/prisma`  — prisma adapter + schema fragment string.
+- `@firstlovecenter/ai-chat/ui`             — `AiChat`, `AnswerBlocks`, registries.
+
+### Build
+
+- Dual ESM + CJS output via `tsup` with full `.d.ts` (and `.d.cts`) generation.
+- UI bundle gets a post-build `'use client';` directive injection (tsup otherwise strips module-level directives during bundling, breaking RSC consumers that import the UI from a server file).
+
+[0.2.2]: https://github.com/firstlovecenter/flc-ai-chat/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/firstlovecenter/flc-ai-chat/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/firstlovecenter/flc-ai-chat/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/firstlovecenter/flc-ai-chat/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/firstlovecenter/flc-ai-chat/releases/tag/v0.1.0

package/dist/ui/index.cjs

@@ -544,6 +544,14 @@ function AiLineChart({
     ))
   ] }) }) });
 }
+function formatDuration(ms) {
+  if (ms < 0) ms = 0;
+  const totalSec = Math.round(ms / 1e3);
+  if (totalSec < 60) return `${totalSec}s`;
+  const m = Math.floor(totalSec / 60);
+  const s = totalSec % 60;
+  return s === 0 ? `${m}m` : `${m}m ${s}s`;
+}
 var PROVIDER_LABELS = {
   claude: "Claude",
   grok: "Grok",
@@ -718,7 +726,7 @@ function AiChat({
       }
       setAnswers((prev) => [
         ...prev,
-        { question: trimmed, blocks: [], done: false }
+        { question: trimmed, blocks: [], done: false, startedAt: Date.now() }
       ]);
       const ac = new AbortController();
       abortRef.current = ac;
@@ -739,6 +747,7 @@ function AiChat({
           (prev) => updateLast(prev, (a) => ({
             ...a,
             done: true,
+            durationMs: a.startedAt != null ? Date.now() - a.startedAt : void 0,
             error: { code: "NETWORK", message }
           }))
         );
@@ -750,6 +759,7 @@ function AiChat({
           (prev) => updateLast(prev, (a) => ({
             ...a,
             done: true,
+            durationMs: a.startedAt != null ? Date.now() - a.startedAt : void 0,
             error: { code: "NO_BODY", message: "No response stream." }
           }))
         );
@@ -776,6 +786,7 @@ function AiChat({
           (prev) => updateLast(prev, (a) => ({
             ...a,
             done: true,
+            durationMs: a.startedAt != null ? Date.now() - a.startedAt : void 0,
             error: { code: "STREAM", message }
           }))
         );
@@ -808,7 +819,7 @@ function AiChat({
     /* @__PURE__ */ jsxRuntime.jsxs(
       "aside",
       {
-        "aria-hidden": !sidebarOpen,
+        inert: !sidebarOpen,
         className: cn(
           "absolute inset-y-0 left-0 z-20 flex w-72 max-w-[85vw] flex-col border-r border-border bg-sidebar text-sidebar-foreground shadow-lg transition-transform duration-200 ease-out",
           sidebarOpen ? "translate-x-0" : "-translate-x-full"
@@ -940,22 +951,16 @@ function AiChat({
           ] }) : heroVisible ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex h-full flex-col items-center justify-center text-center", children: [
             /* @__PURE__ */ jsxRuntime.jsx("h1", { className: "text-2xl font-medium tracking-tight text-foreground sm:text-3xl", children: greeting }),
             /* @__PURE__ */ jsxRuntime.jsx("p", { className: "mt-2 text-2xl font-light tracking-tight text-muted-foreground sm:text-3xl", children: "What's on your mind?" })
-          ] }) : /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "mx-auto flex w-full max-w-3xl flex-col gap-6", children: [
-            answers.map((a, idx) => /* @__PURE__ */ jsxRuntime.jsx(
-              AnswerView,
-              {
-                answer: a,
-                onRetry: () => void submit(a.question),
-                forwardRef: idx === answers.length - 1 ? lastAnswerRef : void 0,
-                isLast: idx === answers.length - 1
-              },
-              idx
-            )),
-            pending && /* @__PURE__ */ jsxRuntime.jsxs("p", { className: "text-sm text-muted-foreground", children: [
-              /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Loader2, { className: "mr-1 inline size-3.5 animate-spin" }),
-              "Thinking\u2026"
-            ] })
-          ] })
+          ] }) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: "mx-auto flex w-full max-w-3xl flex-col gap-6", children: answers.map((a, idx) => /* @__PURE__ */ jsxRuntime.jsx(
+            AnswerView,
+            {
+              answer: a,
+              onRetry: () => void submit(a.question),
+              forwardRef: idx === answers.length - 1 ? lastAnswerRef : void 0,
+              isLast: idx === answers.length - 1
+            },
+            idx
+          )) })
         }
       ),
       /* @__PURE__ */ jsxRuntime.jsx("div", { className: "shrink-0 px-4 pb-4 pt-2", children: /* @__PURE__ */ jsxRuntime.jsxs(
@@ -1080,6 +1085,14 @@ function AnswerView({
   }, [answer.blocks, answer.error]);
   const showActions = answer.done && (answer.blocks.length > 0 || answer.error != null);
   const isThinking = !answer.done && answer.blocks.length === 0 && !answer.error;
+  const [, forceTick] = React.useState(0);
+  React.useEffect(() => {
+    if (answer.done || answer.startedAt == null) return;
+    const id = window.setInterval(() => forceTick((n) => n + 1), 1e3);
+    return () => window.clearInterval(id);
+  }, [answer.done, answer.startedAt]);
+  const liveElapsed = answer.startedAt != null ? Date.now() - answer.startedAt : null;
+  const finalDuration = answer.durationMs;
   return /* @__PURE__ */ jsxRuntime.jsxs(
     "div",
     {
@@ -1096,7 +1109,15 @@ function AnswerView({
         /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex justify-end", children: /* @__PURE__ */ jsxRuntime.jsx(UserChip, { text: answer.question }) }),
         isThinking ? /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-3", children: [
           /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex size-7 shrink-0 items-center justify-center rounded-full bg-primary/10 text-primary", children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Sparkles, { className: "size-4" }) }),
-          /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-sm text-muted-foreground", children: "Thinking\u2026" })
+          /* @__PURE__ */ jsxRuntime.jsxs("p", { className: "flex items-center text-sm text-muted-foreground", children: [
+            /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Loader2, { className: "mr-1 inline size-3.5 animate-spin" }),
+            "Thinking\u2026",
+            liveElapsed != null && liveElapsed >= 1e3 && /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "ml-1 tabular-nums", children: [
+              "(",
+              formatDuration(liveElapsed),
+              ")"
+            ] })
+          ] })
         ] }) : /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-start gap-3", children: [
           /* @__PURE__ */ jsxRuntime.jsx("div", { className: "mt-0.5 flex size-7 shrink-0 items-center justify-center rounded-full bg-primary/10 text-primary", children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Sparkles, { className: "size-4" }) }),
           /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-3", children: [
@@ -1128,6 +1149,14 @@ function AnswerView({
                   className: "inline-flex size-8 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground",
                   children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.RotateCcw, { className: "size-4" })
                 }
+              ),
+              finalDuration != null && finalDuration >= 1e3 && /* @__PURE__ */ jsxRuntime.jsx(
+                "span",
+                {
+                  className: "ml-1 text-xs text-muted-foreground tabular-nums",
+                  title: "Time taken to generate this response",
+                  children: formatDuration(finalDuration)
+                }
               )
             ] })
           ] })
@@ -1333,7 +1362,13 @@ function handleEvent(raw, setAnswers) {
       })
     );
   } else if (event === "done") {
-    setAnswers((prev) => updateLast(prev, (a) => ({ ...a, done: true })));
+    setAnswers(
+      (prev) => updateLast(prev, (a) => ({
+        ...a,
+        done: true,
+        durationMs: a.startedAt != null ? Date.now() - a.startedAt : void 0
+      }))
+    );
   } else if (event === "error") {
     setAnswers(
       (prev) => updateLast(prev, (a) => ({