@firstlovecenter/ai-chat 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# 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.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.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/server/index.cjs

@@ -146,11 +146,19 @@ var ClaudeToolProvider = class {
     patchVertexBuildRequestSync(this.client);
   }
   async runTurn(input) {
-    const system = input.system.map((b) => ({
-      type: "text",
-      text: b.text,
-      ...b.cached ? { cache_control: { type: "ephemeral" } } : {}
-    }));
+    let cacheMarkersUsed = 0;
+    const MAX_CACHE_MARKERS = 4;
+    const system = input.system.map((b) => {
+      if (b.cached && cacheMarkersUsed < MAX_CACHE_MARKERS) {
+        cacheMarkersUsed++;
+        return {
+          type: "text",
+          text: b.text,
+          cache_control: { type: "ephemeral" }
+        };
+      }
+      return { type: "text", text: b.text };
+    });
     const messages = toAnthropicMessages(input.messages);
     const response = await this.client.messages.create({
       model: this.modelId,
@@ -1393,6 +1401,16 @@ function configureAiChat(opts) {
   ];
   const getProvider = (id) => toolProviders2.find((p) => p.id === id) ?? getToolProvider(id);
   const chatInterfaces = opts.chatInterfaces ?? BUILTIN_CHAT_INTERFACE_IDS.map((id) => ({ id }));
+  const tools = opts.rolePrompt ? {
+    tools: opts.tools.tools,
+    async buildSystemBlocks(ctx) {
+      const inner = await opts.tools.buildSystemBlocks(ctx);
+      const rolePrompt = opts.rolePrompt;
+      const role = typeof rolePrompt === "function" ? await rolePrompt(ctx) : rolePrompt;
+      if (!role || !role.trim()) return inner;
+      return [{ text: role, cached: true }, ...inner];
+    }
+  } : opts.tools;
   const runAgentBound = async ({
     question,
     ctx,
@@ -1415,11 +1433,11 @@ function configureAiChat(opts) {
       modelIds: opts.vertex.modelIds,
       location: location ?? settings.gcpLocation
     });
-    const systemBlocks = await opts.tools.buildSystemBlocks(ctx);
+    const systemBlocks = await tools.buildSystemBlocks(ctx);
     const input = {
       question,
       ctx,
-      tools: opts.tools.tools,
+      tools: tools.tools,
       systemBlocks,
       provider,
       maxToolTurns,
@@ -1435,7 +1453,7 @@ function configureAiChat(opts) {
     persistence: opts.persistence,
     auth: opts.auth,
     scope: opts.scope,
-    tools: opts.tools,
+    tools,
     vertex: opts.vertex,
     logger: opts.logger,
     resolveNarratorId: opts.resolveNarratorId,