@spinabot/brigade 0.1.0

package/dist/core/provider-quirks.js

@@ -0,0 +1,285 @@
+/**
+ * Provider-specific message-shape transforms.
+ *
+ * Each provider has at least one quirk that breaks an otherwise-valid Pi
+ * message before the API accepts it. The fixes here are surgical: each
+ * transform is a pure function over `AgentMessage[]`, gated on the active
+ * model so we don't pessimize providers that don't need them.
+ *
+ * Wired via `buildAgent`'s `transformContext` chain. The chain runs every
+ * LLM call so the fixes apply to BOTH initial requests and resumed sessions.
+ *
+ * Quirks handled:
+ *   - dropAnthropicThinkingBlocks   — strip stale thinking blocks in history
+ *   - sanitizeMistralToolCallIds    — rewrite IDs to Mistral's 9-char format
+ *   - downgradeOpenAIResponsesPairs — drop thinking when paired with toolCall
+ *   - decodeXaiToolCallArgs (hook)  — decode HTML entities in xAI tool args
+ */
+/* ─────────────────────────── 1. Strip stale thinking blocks ─────────────────────────── */
+/**
+ * Strip `thinking` content blocks from assistant messages in history.
+ * Always-on defensive cleanup with one nuance:
+ *
+ *   - When the ACTIVE model is Anthropic-compatible, the LATEST assistant
+ *     message keeps its thinking block — Anthropic uses the signature for
+ *     prompt-cache continuity on the next turn.
+ *   - For every other active model (Gemini, OpenAI, Mistral, etc.) we strip
+ *     ALL thinking blocks. They have no continuity reason to keep them and
+ *     would otherwise reject `{type:"thinking"}` as an unknown content type.
+ *
+ * Why the nuance matters: the bug Brigade had before this fix was that a
+ * /model switch from Anthropic → Gemini left history full of Anthropic
+ * thinking blocks. With the OLD provider-conditional gate (only fires when
+ * active model is Anthropic), Gemini received them. With this new shape
+ * the strip happens for every NON-Anthropic active model, including the
+ * mid-conversation switch case.
+ *
+ * `activeModel` is optional — passing `undefined` means "I don't know the
+ * provider; strip everything to be safe." That's the correct default if
+ * the caller can't reach session.model for any reason.
+ *
+ * The cross-provider strip (vs. unconditional Anthropic-shaped strip) is
+ * what makes mid-conversation /model switches work cleanly.
+ */
+export function dropAnthropicThinkingBlocks(messages, activeModel) {
+    if (!Array.isArray(messages) || messages.length === 0)
+        return messages;
+    // Only preserve the latest assistant's thinking when the active model is
+    // Anthropic-flavored (cache continuity matters). For any other model
+    // — including no model at all — strip every thinking block.
+    const preserveLatestIdx = isAnthropicLikeModel(activeModel)
+        ? findLastAssistantIndex(messages)
+        : -1;
+    let touched = false;
+    const out = messages.map((msg, i) => {
+        const m = msg;
+        if (m?.role !== "assistant" || !Array.isArray(m.content))
+            return msg;
+        if (i === preserveLatestIdx)
+            return msg; // preserve the last one for Anthropic cache
+        const filtered = m.content.filter((b) => b?.type !== "thinking");
+        if (filtered.length === m.content.length)
+            return msg; // nothing changed
+        touched = true;
+        // Anthropic rejects an assistant message with EMPTY content too.
+        // Replace with a single empty text block if dropping thinking left
+        // the message bare.
+        const content = filtered.length > 0 ? filtered : [{ type: "text", text: "" }];
+        return { ...m, content };
+    });
+    return touched ? out : messages;
+}
+function findLastAssistantIndex(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m?.role === "assistant" && Array.isArray(m.content))
+            return i;
+    }
+    return -1;
+}
+/** Whether the active model is Anthropic-flavored (direct, Bedrock, Vertex, OpenRouter→Anthropic). */
+export function isAnthropicLikeModel(model) {
+    if (!model)
+        return false;
+    const provider = (model.provider ?? "").toLowerCase();
+    const api = (model.api ?? "").toLowerCase();
+    if (provider === "anthropic")
+        return true;
+    if (api === "anthropic-messages")
+        return true;
+    if (provider === "openrouter" && /claude|anthropic/i.test(model.id ?? ""))
+        return true;
+    if (provider === "bedrock" || provider === "vertex")
+        return /claude|anthropic/i.test(model.id ?? "");
+    return false;
+}
+/* ─────────────────────────── 2. Mistral tool-call ID format ─────────────────────────── */
+/**
+ * Mistral's tool-call API requires IDs matching `[a-zA-Z0-9]{9}` exactly.
+ * Pi/Anthropic emit `toolu_01a2b3c...` (longer, with underscores); OpenAI
+ * emits `call_xyz...`. Mistral rejects both.
+ *
+ * The fix: rewrite IDs in BOTH the assistant's `toolCall` blocks AND the
+ * matching `toolResult` messages, keeping the mapping consistent within
+ * a single transformContext pass.
+ *
+ * The 9-char ID is generated deterministically from the original ID so the
+ * mapping is stable across re-sends — same input, same output.
+ */
+export function sanitizeMistralToolCallIds(messages) {
+    if (!Array.isArray(messages) || messages.length === 0)
+        return messages;
+    const idMap = new Map();
+    const mapId = (orig) => {
+        const cached = idMap.get(orig);
+        if (cached)
+            return cached;
+        // Deterministic 9-char id derived from the original. Hash → base36 → pad/slice.
+        let h = 0;
+        for (let i = 0; i < orig.length; i++) {
+            h = ((h << 5) - h + orig.charCodeAt(i)) | 0;
+        }
+        const positive = h < 0 ? h + 0x80000000 : h;
+        const id = positive.toString(36).padStart(9, "0").slice(-9);
+        idMap.set(orig, id);
+        return id;
+    };
+    const valid = /^[a-zA-Z0-9]{9}$/;
+    let touched = false;
+    const out = messages.map((msg) => {
+        const m = msg;
+        // toolResult messages carry the id at the message level.
+        if (m?.role === "toolResult" && typeof m.toolCallId === "string" && !valid.test(m.toolCallId)) {
+            touched = true;
+            return { ...m, toolCallId: mapId(m.toolCallId) };
+        }
+        // Assistant messages may carry toolCall blocks with ids inside content.
+        if (m?.role === "assistant" && Array.isArray(m.content)) {
+            let blockTouched = false;
+            const newContent = m.content.map((block) => {
+                if (block?.type === "toolCall" && typeof block.id === "string" && !valid.test(block.id)) {
+                    blockTouched = true;
+                    return { ...block, id: mapId(block.id) };
+                }
+                return block;
+            });
+            if (blockTouched) {
+                touched = true;
+                return { ...m, content: newContent };
+            }
+        }
+        return msg;
+    });
+    return touched ? out : messages;
+}
+/** Whether the active model is Mistral. */
+export function isMistralModel(model) {
+    if (!model)
+        return false;
+    const provider = (model.provider ?? "").toLowerCase();
+    if (provider === "mistral" || provider === "mistralai")
+        return true;
+    if (provider === "openrouter" && /mistral|mixtral|codestral/i.test(model.id ?? ""))
+        return true;
+    return false;
+}
+/* ─────────────────────────── 3. OpenAI Responses API downgrade ─────────────────────────── */
+/**
+ * OpenAI's Responses API rejects assistant messages that contain BOTH a
+ * reasoning block AND a function_call (tool_call) in the same message.
+ *
+ * The full fix is to strip the reasoning signature from the toolCall id
+ * (the `fc_` prefix that pairs it with the reasoning) so OpenAI accepts
+ * the call alone.
+ *
+ * Simpler approximation here: when a message has BOTH thinking AND toolCall,
+ * drop the thinking block (the reasoning is gone, but the tool call lives).
+ * This costs cache continuity but unblocks the call. Acceptable trade for v1.
+ */
+export function downgradeOpenAIResponsesReasoningPairs(messages) {
+    if (!Array.isArray(messages) || messages.length === 0)
+        return messages;
+    let touched = false;
+    const out = messages.map((msg) => {
+        const m = msg;
+        if (m?.role !== "assistant" || !Array.isArray(m.content))
+            return msg;
+        const hasThinking = m.content.some((b) => b?.type === "thinking");
+        const hasToolCall = m.content.some((b) => b?.type === "toolCall");
+        if (!hasThinking || !hasToolCall)
+            return msg;
+        touched = true;
+        const filtered = m.content.filter((b) => b?.type !== "thinking");
+        const content = filtered.length > 0 ? filtered : [{ type: "text", text: "" }];
+        return { ...m, content };
+    });
+    return touched ? out : messages;
+}
+/** Whether the active model uses OpenAI's Responses API. */
+export function isOpenAIResponsesModel(model) {
+    if (!model)
+        return false;
+    const api = (model.api ?? "").toLowerCase();
+    if (api === "openai-responses" || api === "responses")
+        return true;
+    // Models whose ids hint at the Responses API (o1, o3 reasoning models route through it).
+    const provider = (model.provider ?? "").toLowerCase();
+    if (provider === "openai" && /^o[13](?:-|$)/i.test(model.id ?? ""))
+        return true;
+    return false;
+}
+/* ─────────────────────────── 4. xAI tool-call argument decode ─────────────────────────── */
+/**
+ * xAI / Grok occasionally returns tool-call argument JSON where string values
+ * are HTML-entity-encoded (`&quot;` for `"`, `&amp;` for `&`, etc.). Pi parses
+ * the JSON OK but the args object then has unusable strings — `path:
+ * "&#x2F;tmp&#x2F;file.txt"` instead of `path: "/tmp/file.txt"`.
+ *
+ * The cleanest fix is to decode at the stream level, but Brigade has no
+ * streamFn hook in v1 (we don't fork Pi's auth wrapper), so we fix at
+ * `beforeToolCall` instead: walk the args, decode every string recursively,
+ * hand the cleaned args to Pi for execution.
+ *
+ * This is a function FACTORY because beforeToolCall hooks need to be wired
+ * via `buildAgent`'s `beforeToolCall` option. The default unknownToolGuard
+ * already runs there; this composes with it by mutating `ctx.toolCall.arguments`
+ * in place before the guard sees it.
+ */
+const HTML_ENTITY_MAP = {
+    "&quot;": '"',
+    "&amp;": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&#39;": "'",
+    "&apos;": "'",
+    "&nbsp;": " ",
+};
+const HTML_NUMERIC_HEX = /&#x([0-9a-fA-F]+);/g;
+const HTML_NUMERIC_DEC = /&#(\d+);/g;
+const HTML_NAMED = /&(?:quot|amp|lt|gt|apos|nbsp|#39);/g;
+/**
+ * Decode HTML entities from a single string. Only fires when the input
+ * actually contains entities — the no-entity fast path returns the input
+ * unchanged with no allocations.
+ */
+export function decodeHtmlEntities(s) {
+    if (typeof s !== "string" || s.indexOf("&") < 0)
+        return s;
+    let out = s.replace(HTML_NAMED, (m) => HTML_ENTITY_MAP[m] ?? m);
+    out = out.replace(HTML_NUMERIC_HEX, (_m, hex) => {
+        const code = parseInt(hex, 16);
+        return Number.isFinite(code) && code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : _m;
+    });
+    out = out.replace(HTML_NUMERIC_DEC, (_m, dec) => {
+        const code = parseInt(dec, 10);
+        return Number.isFinite(code) && code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : _m;
+    });
+    return out;
+}
+/** Recursively decode every string value in a tool-args object. */
+export function decodeXaiToolCallArgs(args) {
+    if (typeof args === "string")
+        return decodeHtmlEntities(args);
+    if (Array.isArray(args))
+        return args.map((v) => decodeXaiToolCallArgs(v));
+    if (args && typeof args === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(args)) {
+            out[k] = decodeXaiToolCallArgs(v);
+        }
+        return out;
+    }
+    return args;
+}
+/** Whether the active model is xAI / Grok (or routed via OpenRouter to Grok). */
+export function isXaiModel(model) {
+    if (!model)
+        return false;
+    const provider = (model.provider ?? "").toLowerCase();
+    if (provider === "xai" || provider === "x-ai")
+        return true;
+    if (provider === "openrouter" && /grok|xai|x-ai/i.test(model.id ?? ""))
+        return true;
+    return false;
+}
+//# sourceMappingURL=provider-quirks.js.map