@spinabot/brigade 0.1.0

package/dist/core/provider-payload-mutators.js

@@ -0,0 +1,517 @@
+/**
+ * Provider-payload mutators — fire INSIDE Pi's `onPayload` hook to mutate
+ * the assembled provider-specific JSON right before it ships over HTTP.
+ *
+ * Pi's wrapping order is:
+ *   session.prompt → Pi's auth wrapper → provider adapter → buildPayload
+ *      → options.onPayload?.(payload, model)         ← we hook here
+ *      → HTTP request
+ *
+ * We wrap `session.agent.streamFn` (preserving Pi's existing auth wrapper)
+ * to inject our own `onPayload` callback. The callback delegates to any
+ * caller-supplied `onPayload` first, then walks the provider mutators in
+ * order. Each mutator is a pure-ish function gated on the active model;
+ * no-ops when the provider doesn't match.
+ *
+ * Three provider quirks are handled here:
+ *   - OpenRouter Anthropic prompt-cache hints (cost win on long sessions)
+ *   - Google Gemini thinking-config payload reformat (Pi's level → Google's enum)
+ *   - SiliconFlow / Minimax thinking-mode normalization
+ *
+ * NOT a replacement for Pi's auth wrapper — strictly additive. The wrapped
+ * streamFn calls `originalStreamFn(model, context, options)` underneath.
+ */
+import { BRIGADE_CACHE_BOUNDARY } from "./system-prompt.js";
+/* ─────────────────────────── 1. Anthropic system-prompt cache hints ─────────────────────────── */
+/**
+ * Apply Anthropic prompt-cache markers to the system field. Three cases:
+ *
+ *   A. SYSTEM PROMPT CONTAINS BRIGADE_CACHE_BOUNDARY MARKER
+ *      Split the system text at the marker into two `{ type: "text" }`
+ *      blocks. Apply `cache_control: { type: "ephemeral" }` to the FIRST
+ *      block only (the static prefix). The SECOND block (dynamic suffix —
+ *      runtime info, model id, etc.) gets no marker, so it doesn't break
+ *      the cache when it varies per turn.
+ *
+ *   B. NO MARKER, SYSTEM IS A STRING
+ *      Convert to a single text block WITH cache_control. Whole prompt is
+ *      cached. (This is the legacy behavior of `applyOpenRouterAnthropicCacheHints`.)
+ *
+ *   C. NO MARKER, SYSTEM IS ALREADY AN ARRAY
+ *      Mark the last text block with cache_control. (Same legacy behavior.)
+ *
+ * Then mark the LAST USER MESSAGE'S last content block with cache_control
+ * — this is the second of Anthropic's up-to-4 breakpoints (we use 2: system
+ * prefix + last user message).
+ *
+ * Only fires when `isAnthropicFlavored(model)` — direct Anthropic, OpenRouter
+ * routing to Claude, Anthropic-compat APIs (Bedrock, Vertex, Minimax). For
+ * non-Anthropic providers, see `stripCacheBoundaryFromPayload` below — the
+ * marker is stripped so the model never sees it.
+ *
+ * Replaces the older `applyOpenRouterAnthropicCacheHints`. The new version
+ * handles the boundary marker (which is what enables the static-vs-dynamic
+ * split that gives us the 5-10× cost win on multi-turn).
+ */
+export function applyAnthropicSystemCacheHints(payload, model) {
+    if (!isAnthropicFlavored(model))
+        return;
+    if (!payload || typeof payload !== "object")
+        return;
+    const p = payload;
+    const cacheMarker = { type: "ephemeral" };
+    // Mark the system field — string → array, array → split or mark last.
+    applyCacheToSystem(p, cacheMarker);
+    // Mark the last user message — second cache breakpoint.
+    applyCacheToLastUserMessage(p, cacheMarker);
+}
+function applyCacheToSystem(payload, cacheMarker) {
+    // Pi may pass system as either a top-level `system` string/array OR as
+    // a `messages` entry with role: "system". We handle both shapes.
+    if (typeof payload.system === "string") {
+        payload.system = splitOrWrap(payload.system, cacheMarker);
+        return;
+    }
+    if (Array.isArray(payload.system)) {
+        payload.system = applyCacheToBlocks(payload.system, cacheMarker);
+        return;
+    }
+    // Fallback: mutate the messages array's system role entry.
+    const messages = payload.messages;
+    if (!Array.isArray(messages))
+        return;
+    for (const msg of messages) {
+        if (msg?.role !== "system" && msg?.role !== "developer")
+            continue;
+        if (typeof msg.content === "string") {
+            msg.content = splitOrWrap(msg.content, cacheMarker);
+        }
+        else if (Array.isArray(msg.content)) {
+            msg.content = applyCacheToBlocks(msg.content, cacheMarker);
+        }
+    }
+}
+/**
+ * Convert a system-prompt STRING into one or two `{type:"text"}` blocks.
+ * If the string contains the BRIGADE_CACHE_BOUNDARY marker, split into:
+ *   - block 1: stable prefix WITH cache_control
+ *   - block 2: dynamic suffix WITHOUT cache_control (changes per turn)
+ * Otherwise wrap the whole string in a single block with cache_control.
+ */
+function splitOrWrap(text, cacheMarker) {
+    const idx = text.indexOf(BRIGADE_CACHE_BOUNDARY);
+    if (idx === -1) {
+        return [{ type: "text", text, cache_control: cacheMarker }];
+    }
+    const stablePrefix = text.slice(0, idx).replace(/\s+$/, "");
+    const dynamicSuffix = text.slice(idx + BRIGADE_CACHE_BOUNDARY.length).replace(/^\s+/, "");
+    const blocks = [];
+    if (stablePrefix.length > 0) {
+        blocks.push({ type: "text", text: stablePrefix, cache_control: cacheMarker });
+    }
+    if (dynamicSuffix.length > 0) {
+        blocks.push({ type: "text", text: dynamicSuffix });
+    }
+    // If both halves trim to empty (degenerate input — caller passed a system
+    // prompt that's nothing but whitespace + a marker), return a single empty
+    // block WITHOUT cache_control. Anthropic rejects empty cache blocks
+    // (`{type:"text", text:"", cache_control:...}`) but accepts an empty
+    // non-cached block. Conservative fallback so the request still flies.
+    return blocks.length > 0 ? blocks : [{ type: "text", text: "" }];
+}
+/**
+ * Walk an existing array of system blocks looking for the boundary marker.
+ * If a text block contains it, split that block in place. If no block
+ * contains it, mark the LAST non-thinking block with cache_control (legacy
+ * behavior — caches the whole prefix up to that point).
+ */
+function applyCacheToBlocks(blocks, cacheMarker) {
+    let foundBoundary = false;
+    const result = [];
+    for (const block of blocks) {
+        if (!foundBoundary &&
+            block &&
+            typeof block === "object" &&
+            block.type === "text" &&
+            typeof block.text === "string" &&
+            block.text.includes(BRIGADE_CACHE_BOUNDARY)) {
+            // Split this block at the boundary marker. Spread the source block's
+            // other fields (e.g. citations, custom keys) FIRST, then the new
+            // block's fields, then explicitly drop any inherited `cache_control`
+            // so the dynamic-suffix block (which `splitOrWrap` deliberately
+            // emits without cache_control) doesn't accidentally re-inherit one
+            // from the source. If the source block had `cache_control` already,
+            // silently letting it through would mark the suffix as cached even
+            // though it changes per turn — guaranteed cache miss every turn.
+            const split = splitOrWrap(block.text, cacheMarker);
+            for (const newBlock of split) {
+                const merged = { ...block, ...newBlock };
+                if (newBlock.cache_control === undefined) {
+                    delete merged.cache_control;
+                }
+                result.push(merged);
+            }
+            foundBoundary = true;
+        }
+        else {
+            result.push(block);
+        }
+    }
+    // No boundary marker anywhere — mark the LAST non-thinking block.
+    if (!foundBoundary) {
+        for (let i = result.length - 1; i >= 0; i--) {
+            const block = result[i];
+            if (block && typeof block === "object" && block.type !== "thinking") {
+                if (block.cache_control === undefined) {
+                    block.cache_control = cacheMarker;
+                }
+                break;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Apply cache_control to the LAST content block of the LAST user message.
+ * This is the second of Anthropic's 2 cache breakpoints (system + last
+ * user).
+ *
+ * IMPORTANT — Anthropic caps the request at 4 cache breakpoints total. Pi
+ * persists user messages across turns, so any cache_control we attached on
+ * a PREVIOUS turn is still on the older user/tool_result blocks. Without
+ * the sweep below, breakpoints accumulate turn-over-turn (turn N adds one
+ * to a new user msg; turn N+1 adds another while the old one is still set;
+ * etc.) and quickly exceed the cap → Anthropic 400. Best practice is "only
+ * the last user message holds the live breakpoint" — so we clear every
+ * older user-side breakpoint before applying the new one.
+ *
+ * Only applies if the message is a user message (skip if last message
+ * happens to be assistant — shouldn't happen in a healthy conversation
+ * but guard anyway).
+ */
+function applyCacheToLastUserMessage(payload, cacheMarker) {
+    const messages = payload.messages;
+    if (!Array.isArray(messages) || messages.length === 0)
+        return;
+    // Sweep: clear cache_control from EVERY user/tool_result block in EVERY
+    // message except the last one. We restrict the sweep to user-side roles
+    // because Pi may set cache_control on assistant-emitted blocks for its
+    // own reasons (rare, but not ours to clobber).
+    for (let i = 0; i < messages.length - 1; i++) {
+        const msg = messages[i];
+        if (!msg || typeof msg !== "object")
+            continue;
+        if (msg.role !== "user")
+            continue;
+        const content = msg.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const block of content) {
+            if (block &&
+                typeof block === "object" &&
+                (block.type === "text" ||
+                    block.type === "image" ||
+                    block.type === "tool_result") &&
+                block.cache_control !== undefined) {
+                delete block.cache_control;
+            }
+        }
+    }
+    const last = messages[messages.length - 1];
+    if (!last || typeof last !== "object" || last.role !== "user")
+        return;
+    if (Array.isArray(last.content) && last.content.length > 0) {
+        const lastBlock = last.content[last.content.length - 1];
+        if (lastBlock &&
+            typeof lastBlock === "object" &&
+            (lastBlock.type === "text" ||
+                lastBlock.type === "image" ||
+                lastBlock.type === "tool_result")) {
+            if (lastBlock.cache_control === undefined) {
+                lastBlock.cache_control = cacheMarker;
+            }
+        }
+    }
+    else if (typeof last.content === "string") {
+        // Convert string to array form so we can attach cache_control.
+        last.content = [
+            { type: "text", text: last.content, cache_control: cacheMarker },
+        ];
+    }
+}
+/**
+ * Whether the model is Anthropic-flavored — direct Anthropic, OpenRouter→
+ * Claude, or any provider whose API field is `anthropic-messages`. Used to
+ * gate `applyAnthropicSystemCacheHints`.
+ */
+export function isAnthropicFlavored(model) {
+    if (!model)
+        return false;
+    const api = (model.api ?? "").toLowerCase();
+    if (api === "anthropic" || api === "anthropic-messages")
+        return true;
+    const provider = (model.provider ?? "").toLowerCase();
+    if (provider === "anthropic")
+        return true;
+    if (provider === "minimax" && api === "anthropic-messages")
+        return true;
+    if (provider === "openrouter" && /(?:^|\/)(?:anthropic|claude)/i.test(model.id ?? "")) {
+        return true;
+    }
+    if (provider === "bedrock" || provider === "vertex") {
+        return /claude|anthropic/i.test(model.id ?? "");
+    }
+    return false;
+}
+/**
+ * Backwards-compat aliases. The old names (`isOpenRouterAnthropic`,
+ * `applyOpenRouterAnthropicCacheHints`) are too narrow now that the cache
+ * mutator handles direct Anthropic + Bedrock + Vertex + Minimax too. Kept
+ * exported under the old names so test files and any external callers
+ * continue to compile during the transition.
+ *
+ * @deprecated use `isAnthropicFlavored` / `applyAnthropicSystemCacheHints`.
+ */
+export const isOpenRouterAnthropic = isAnthropicFlavored;
+export const applyOpenRouterAnthropicCacheHints = applyAnthropicSystemCacheHints;
+/**
+ * Strip the BRIGADE_CACHE_BOUNDARY marker from any system field.
+ * Universal pre-pass — runs for ALL providers (Anthropic too) so the
+ * marker never escapes Brigade. For Anthropic, the marker has already
+ * been used by `applyAnthropicSystemCacheHints` to split the prompt;
+ * stripping leftovers is defensive in case the splitter missed one
+ * (multiple markers, marker in array form Pi assembled differently, etc).
+ *
+ * For non-Anthropic providers, this is the ONLY thing that touches the
+ * system field — strip the marker, leave the prompt as a single string
+ * the model can read.
+ */
+export function stripCacheBoundaryFromPayload(payload) {
+    if (!payload || typeof payload !== "object")
+        return;
+    const p = payload;
+    if (typeof p.system === "string") {
+        p.system = p.system.split(BRIGADE_CACHE_BOUNDARY).join("\n").trim();
+    }
+    else if (Array.isArray(p.system)) {
+        for (const block of p.system) {
+            if (block && typeof block === "object" && typeof block.text === "string") {
+                block.text = block.text.split(BRIGADE_CACHE_BOUNDARY).join("\n").trim();
+            }
+        }
+    }
+    const messages = p.messages;
+    if (Array.isArray(messages)) {
+        for (const msg of messages) {
+            if (msg?.role !== "system" && msg?.role !== "developer")
+                continue;
+            if (typeof msg.content === "string") {
+                msg.content = msg.content.split(BRIGADE_CACHE_BOUNDARY).join("\n").trim();
+            }
+            else if (Array.isArray(msg.content)) {
+                for (const block of msg.content) {
+                    if (block && typeof block === "object" && typeof block.text === "string") {
+                        block.text = block.text.split(BRIGADE_CACHE_BOUNDARY).join("\n").trim();
+                    }
+                }
+            }
+        }
+    }
+}
+/* ─────────────────────────── 2. Google Gemini thinking payload ─────────────────────────── */
+/**
+ * Gemini's GenerateContent API expects thinking config under
+ * `config.thinkingConfig.thinkingLevel` with values from a fixed enum:
+ * "MINIMAL" | "LOW" | "MEDIUM" | "HIGH". Pi's ThinkingLevel uses lowercase
+ * "minimal" | "low" | "medium" | "high" | "xhigh" (xhigh is Pi-only).
+ *
+ * The fix: write the uppercased value AND drop `xhigh` (which Gemini
+ * rejects as unknown).
+ *
+ * This is purely a payload-shape concern — Pi's adapter already builds the
+ * `config.thinkingConfig` object; we just normalize the level string.
+ */
+export function sanitizeGeminiThinkingPayload(payload, model) {
+    if (!isGoogleGeminiModel(model))
+        return;
+    if (!payload || typeof payload !== "object")
+        return;
+    const cfg = payload.config;
+    if (!cfg || typeof cfg !== "object")
+        return;
+    const tc = cfg.thinkingConfig;
+    if (!tc || typeof tc !== "object")
+        return;
+    const raw = tc.thinkingLevel ?? tc.thinking_level;
+    if (typeof raw !== "string")
+        return;
+    const mapped = mapPiThinkingToGemini(raw);
+    if (mapped === undefined) {
+        // Unknown level → drop the config entirely so Gemini uses its default
+        // instead of rejecting an invalid enum.
+        delete cfg.thinkingConfig;
+        return;
+    }
+    tc.thinkingLevel = mapped;
+    // Some Gemini variants want it under thinking_level (snake_case). Set both
+    // when one was supplied, so we don't silently lose the value if Pi later
+    // switches naming.
+    if ("thinking_level" in tc)
+        tc.thinking_level = mapped;
+}
+function mapPiThinkingToGemini(level) {
+    switch (level.toLowerCase()) {
+        case "off":
+            return undefined; // Gemini has no "off" — drop the config
+        case "minimal":
+            return "MINIMAL";
+        case "low":
+            return "LOW";
+        case "medium":
+            return "MEDIUM";
+        case "high":
+        case "xhigh": // xhigh isn't supported; bucket it as HIGH
+            return "HIGH";
+        default:
+            return undefined;
+    }
+}
+export function isGoogleGeminiModel(model) {
+    if (!model)
+        return false;
+    const api = (model.api ?? "").toLowerCase();
+    if (api === "google-generative-ai" || api === "google-gemini" || api === "google")
+        return true;
+    const provider = (model.provider ?? "").toLowerCase();
+    if (provider === "google" || provider === "gemini" || provider === "google-vertex" || provider === "vertex") {
+        return true;
+    }
+    if (provider === "openrouter" && /gemini|google/i.test(model.id ?? ""))
+        return true;
+    return false;
+}
+/* ─────────────────────────── 3. SiliconFlow thinking-off normalization ─────────────────────────── */
+/**
+ * SiliconFlow rejects `thinking: "off"` (Pi's value for "no reasoning") and
+ * wants `thinking: null` instead — this mutator does the swap.
+ *
+ * Pi sets `thinking: "off"` automatically when `session.thinkingLevel === "off"`
+ * for OpenAI-compatible providers; SiliconFlow shares the OpenAI shape
+ * but is stricter about this one field.
+ */
+export function normalizeSiliconFlowThinking(payload, model) {
+    if (!isSiliconFlowModel(model))
+        return;
+    if (!payload || typeof payload !== "object")
+        return;
+    const p = payload;
+    if (p.thinking === "off") {
+        p.thinking = null;
+    }
+}
+export function isSiliconFlowModel(model) {
+    if (!model)
+        return false;
+    const provider = (model.provider ?? "").toLowerCase();
+    if (provider === "siliconflow" || provider === "silicon-flow")
+        return true;
+    const baseUrl = model.baseUrl ?? "";
+    if (typeof baseUrl === "string" && /siliconflow/i.test(baseUrl))
+        return true;
+    return false;
+}
+/* ─────────────────────────── 4. Minimax force-disable thinking ─────────────────────────── */
+/**
+ * Minimax exposes an Anthropic-shaped Messages endpoint but ALWAYS streams
+ * reasoning back as visible deltas — even when the user wants thinking
+ * suppressed. The fix is to inject `thinking: { type: "disabled" }` into
+ * the payload when it's missing, so Minimax stops emitting reasoning deltas.
+ *
+ * Only applies when the underlying API is Anthropic Messages AND the
+ * provider is Minimax. Other Anthropic-compatible endpoints don't need this.
+ */
+export function disableMinimaxThinking(payload, model) {
+    if (!isMinimaxAnthropicModel(model))
+        return;
+    if (!payload || typeof payload !== "object")
+        return;
+    const p = payload;
+    // Don't overwrite an explicit thinking config the user set elsewhere.
+    if (p.thinking === undefined) {
+        p.thinking = { type: "disabled" };
+    }
+}
+export function isMinimaxAnthropicModel(model) {
+    if (!model)
+        return false;
+    const api = (model.api ?? "").toLowerCase();
+    if (api !== "anthropic-messages" && api !== "anthropic")
+        return false;
+    const provider = (model.provider ?? "").toLowerCase();
+    return provider === "minimax" || provider === "minimax-portal";
+}
+/* ─────────────────────────── composition ─────────────────────────── */
+/**
+ * Run every applicable mutator against the payload. Each mutator self-gates
+ * on the active model — no-ops when the provider doesn't match — so calling
+ * `applyAll` for every request is cheap.
+ *
+ * Order matters:
+ *   1. Anthropic system-prompt cache hints — splits at the boundary marker
+ *      and applies cache_control. Must run BEFORE the universal strip
+ *      (otherwise the boundary is gone before we can split on it).
+ *   2. Universal boundary strip — removes any leftover marker so it never
+ *      reaches the model regardless of provider. Idempotent for Anthropic
+ *      (the splitter already removed it for matched cases); load-bearing
+ *      for non-Anthropic.
+ *   3. Provider-specific mutators (Gemini thinking, SiliconFlow, Minimax) —
+ *      operate on fields other than `system`, no ordering interaction with
+ *      the cache work above.
+ *
+ * Mutates `payload` in place. Returns nothing (caller hands `payload` back
+ * to Pi unchanged-by-reference; the in-place mutation is what Pi sends).
+ */
+export function applyAllPayloadMutations(payload, model) {
+    if (!model || !payload)
+        return;
+    applyAnthropicSystemCacheHints(payload, model);
+    stripCacheBoundaryFromPayload(payload);
+    sanitizeGeminiThinkingPayload(payload, model);
+    normalizeSiliconFlowThinking(payload, model);
+    disableMinimaxThinking(payload, model);
+}
+/**
+ * Wrap `session.agent.streamFn` so every request gets `applyAllPayloadMutations`
+ * fired against its assembled payload.
+ *
+ * SAFE TO CALL ONCE per session — preserves Pi's existing auth-aware streamFn
+ * by composing on top of it. Calling more than once would stack wrappers
+ * and fire mutations multiple times (idempotent for our current mutators
+ * but wasteful); buildAgent calls it exactly once after createAgentSession.
+ *
+ * If a caller (test, future feature) supplies its OWN `onPayload` in
+ * StreamOptions, we run THEIRS first and then our mutators on whatever
+ * they returned (or the original if they returned undefined). This keeps
+ * caller hooks composable.
+ */
+export function wrapStreamFnWithPayloadMutations(session) {
+    const original = session.agent.streamFn;
+    if (!original)
+        return;
+    const wrapped = (model, context, options) => {
+        const userOnPayload = options?.onPayload;
+        const augmented = {
+            ...(options ?? {}),
+            onPayload: async (payload, m) => {
+                // User's hook gets first crack at mutating / replacing.
+                const userResult = userOnPayload ? await userOnPayload(payload, m) : undefined;
+                const next = userResult !== undefined ? userResult : payload;
+                applyAllPayloadMutations(next, m);
+                return next;
+            },
+        };
+        return original(model, context, augmented);
+    };
+    session.agent.streamFn = wrapped;
+}
+//# sourceMappingURL=provider-payload-mutators.js.map