@firstlovecenter/ai-chat 0.1.1 → 0.2.1

package/dist/server/index.d.cts

@@ -453,6 +453,36 @@ type ConfigureAiChatOpts<S = unknown> = {
      *   - `onSessionEnd`     — cleanup (always-runs, never throws out).
      */
     hooks?: AgentCustomHooks$1<S>;
+    /**
+     * Persona / role given to the AI as the very first cached system block
+     * on every turn. Use this to give the assistant a consistent voice and
+     * domain perspective across all conversations in your app.
+     *
+     * Accepts:
+     *   - a `string` for a static org-wide role, or
+     *   - a `(ctx) => string | Promise<string>` function for per-request
+     *     variation (different role per scope, per locale, per A/B cohort).
+     *
+     * Token economics: the role text is sent on every turn (Vertex APIs
+     * are stateless), but it is marked `cached: true`. On Claude that
+     * becomes an ephemeral `cache_control` marker — first turn pays ~1.25×
+     * for the cache write; subsequent turns within ~5 min pay ~0.1× for
+     * cache reads. On Gemini the hint is informational; Vertex auto-caches
+     * stable prefixes regardless. For a typical 200–500 token role, the
+     * per-turn marginal cost after the first is negligible. The package
+     * caps total `cache_control` markers at Anthropic's 4-per-request
+     * limit; if the host already marks 4 blocks cached, the extras
+     * (including this one if last) silently drop the cache hint rather
+     * than reject the request.
+     *
+     * Example (static):
+     *   rolePrompt: `You are the head pastor of First Love Center, a
+     *   multinational church operating across multiple countries. Frame
+     *   answers from the perspective of advancing the gospel through
+     *   sustainable growth, financial discipline, compliance, and church
+     *   planting. Be direct, pastoral, and action-oriented.`
+     */
+    rolePrompt?: string | ((ctx: ToolContext<S>) => string | Promise<string>);
 };
 type AiChatRuntime<S = unknown> = {
     /**

package/dist/server/index.d.ts

@@ -453,6 +453,36 @@ type ConfigureAiChatOpts<S = unknown> = {
      *   - `onSessionEnd`     — cleanup (always-runs, never throws out).
      */
     hooks?: AgentCustomHooks$1<S>;
+    /**
+     * Persona / role given to the AI as the very first cached system block
+     * on every turn. Use this to give the assistant a consistent voice and
+     * domain perspective across all conversations in your app.
+     *
+     * Accepts:
+     *   - a `string` for a static org-wide role, or
+     *   - a `(ctx) => string | Promise<string>` function for per-request
+     *     variation (different role per scope, per locale, per A/B cohort).
+     *
+     * Token economics: the role text is sent on every turn (Vertex APIs
+     * are stateless), but it is marked `cached: true`. On Claude that
+     * becomes an ephemeral `cache_control` marker — first turn pays ~1.25×
+     * for the cache write; subsequent turns within ~5 min pay ~0.1× for
+     * cache reads. On Gemini the hint is informational; Vertex auto-caches
+     * stable prefixes regardless. For a typical 200–500 token role, the
+     * per-turn marginal cost after the first is negligible. The package
+     * caps total `cache_control` markers at Anthropic's 4-per-request
+     * limit; if the host already marks 4 blocks cached, the extras
+     * (including this one if last) silently drop the cache hint rather
+     * than reject the request.
+     *
+     * Example (static):
+     *   rolePrompt: `You are the head pastor of First Love Center, a
+     *   multinational church operating across multiple countries. Frame
+     *   answers from the perspective of advancing the gospel through
+     *   sustainable growth, financial discipline, compliance, and church
+     *   planting. Be direct, pastoral, and action-oriented.`
+     */
+    rolePrompt?: string | ((ctx: ToolContext<S>) => string | Promise<string>);
 };
 type AiChatRuntime<S = unknown> = {
     /**

package/dist/server/index.js

@@ -144,11 +144,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,
@@ -1391,6 +1399,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,
@@ -1413,11 +1431,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,
@@ -1433,7 +1451,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,