@animalabs/membrane 0.5.51 → 0.5.53

package/dist/formatters/native.js

@@ -0,0 +1,346 @@
+/**
+ * Native Formatter
+ *
+ * Pass-through formatter that converts messages to standard user/assistant
+ * format without prefill. Uses native API tool calling.
+ *
+ * Supports two participant modes:
+ * - 'simple': Strict two-party (Human/Assistant), no names in content
+ * - 'multiuser': Multiple participants, names prefixed to content
+ */
+import { normalizeToolPairs } from './normalize-tool-pairs.js';
+// ============================================================================
+// Pass-through Stream Parser
+// ============================================================================
+/**
+ * Simple pass-through parser that doesn't do XML tracking.
+ * Just accumulates content and emits text chunks.
+ */
+class PassthroughParser {
+    accumulated = '';
+    blockIndex = 0;
+    blockStarted = false;
+    processChunk(chunk) {
+        this.accumulated += chunk;
+        const meta = {
+            type: 'text',
+            visible: true,
+            blockIndex: this.blockIndex,
+        };
+        const emissions = [];
+        const blockEvents = [];
+        // Emit block_start on first chunk
+        if (!this.blockStarted) {
+            const startEvent = {
+                event: 'block_start',
+                index: this.blockIndex,
+                block: { type: 'text' },
+            };
+            emissions.push({ kind: 'blockEvent', event: startEvent });
+            blockEvents.push(startEvent);
+            this.blockStarted = true;
+        }
+        emissions.push({ kind: 'content', text: chunk, meta });
+        return { emissions, content: [{ text: chunk, meta }], blockEvents };
+    }
+    flush() {
+        const emissions = [];
+        const blockEvents = [];
+        if (this.blockStarted) {
+            const completeEvent = {
+                event: 'block_complete',
+                index: this.blockIndex,
+                block: { type: 'text', content: this.accumulated },
+            };
+            emissions.push({ kind: 'blockEvent', event: completeEvent });
+            blockEvents.push(completeEvent);
+            this.blockStarted = false;
+        }
+        return { emissions, content: [], blockEvents };
+    }
+    getAccumulated() {
+        return this.accumulated;
+    }
+    reset() {
+        this.accumulated = '';
+        this.blockIndex = 0;
+        this.blockStarted = false;
+    }
+    push(content) {
+        this.accumulated += content;
+    }
+    getCurrentBlockType() {
+        return 'text';
+    }
+    getBlockIndex() {
+        return this.blockIndex;
+    }
+    incrementBlockIndex() {
+        this.blockIndex++;
+    }
+    isInsideBlock() {
+        // Pass-through mode never has nested blocks
+        return false;
+    }
+    getDepths() {
+        return { functionCalls: 0, functionResults: 0, thinking: 0 };
+    }
+    resetForNewIteration() {
+        // No special reset needed for pass-through mode
+    }
+}
+// ============================================================================
+// Native Formatter
+// ============================================================================
+export class NativeFormatter {
+    name = 'native';
+    usesPrefill = false;
+    config;
+    constructor(config = {}) {
+        this.config = {
+            nameFormat: config.nameFormat ?? '{name}: ',
+            unsupportedMedia: config.unsupportedMedia ?? 'error',
+            warnOnStrip: config.warnOnStrip ?? true,
+        };
+    }
+    // ==========================================================================
+    // REQUEST BUILDING
+    // ==========================================================================
+    buildMessages(messages, options) {
+        const { participantMode, assistantParticipant, humanParticipant, tools, systemPrompt, promptCaching = false, cacheTtl, hasCacheMarker, contextPrefix, additionalStopSequences, } = options;
+        // Build cache_control object if prompt caching is enabled
+        const cacheControl = promptCaching
+            ? { type: 'ephemeral', ...(cacheTtl ? { ttl: cacheTtl } : {}) }
+            : undefined;
+        const providerMessages = [];
+        // Add context prefix as first assistant message (for simulacrum seeding)
+        if (contextPrefix) {
+            const prefixBlock = { type: 'text', text: contextPrefix };
+            if (promptCaching && cacheControl) {
+                prefixBlock.cache_control = cacheControl;
+            }
+            providerMessages.push({
+                role: 'assistant',
+                content: [prefixBlock],
+            });
+        }
+        // Validate simple mode participants
+        if (participantMode === 'simple' && !humanParticipant) {
+            throw new Error('NativeFormatter in simple mode requires humanParticipant option');
+        }
+        for (let i = 0; i < messages.length; i++) {
+            const message = messages[i];
+            if (!message)
+                continue;
+            // Determine role
+            const isAssistant = message.participant === assistantParticipant;
+            // Validate participant in simple mode
+            if (participantMode === 'simple') {
+                if (!isAssistant && message.participant !== humanParticipant) {
+                    throw new Error(`NativeFormatter in simple mode only supports "${humanParticipant}" and "${assistantParticipant}". ` +
+                        `Got: "${message.participant}". Use participantMode: 'multiuser' for multiple participants.`);
+                }
+            }
+            const role = isAssistant ? 'assistant' : 'user';
+            // Convert content
+            const content = this.convertContent(message.content, message.participant, {
+                includeNames: participantMode === 'multiuser' && !isAssistant,
+            });
+            if (content.length === 0) {
+                continue; // Skip empty messages
+            }
+            // hasCacheMarker: cache boundary is BEFORE this message — tag previous message's last block
+            if (hasCacheMarker && hasCacheMarker(message, i) && cacheControl && providerMessages.length > 0) {
+                const prevMsg = providerMessages[providerMessages.length - 1];
+                const prevContent = Array.isArray(prevMsg.content) ? prevMsg.content : [];
+                if (prevContent.length > 0) {
+                    prevContent[prevContent.length - 1].cache_control = cacheControl;
+                }
+            }
+            providerMessages.push({ role, content });
+            // cacheBreakpoint: cache up to and INCLUDING this message — tag last block
+            if (message.cacheBreakpoint && cacheControl && content.length > 0) {
+                content[content.length - 1].cache_control = cacheControl;
+            }
+        }
+        // Tool-pair normalizer: wire-boundary safety net for Anthropic's
+        // structural rules on tool cycles. See `normalize-tool-pairs.ts`
+        // for the full rationale. Runs BEFORE mergeConsecutiveRoles so the
+        // merge sees role-correct envelopes.
+        const normalized = normalizeToolPairs(providerMessages, {
+            pendingToolCallIds: options.pendingToolCallIds,
+            onEvent: options.onNormalize,
+        });
+        // Merge consecutive same-role messages (API requires alternating)
+        const mergedMessages = this.mergeConsecutiveRoles(normalized.messages);
+        // Build system content with optional cache control
+        let systemContent;
+        if (typeof systemPrompt === 'string') {
+            if (cacheControl) {
+                // Must use array format for cache_control support
+                systemContent = [{ type: 'text', text: systemPrompt, cache_control: cacheControl }];
+            }
+            else {
+                systemContent = systemPrompt;
+            }
+        }
+        else if (Array.isArray(systemPrompt)) {
+            if (cacheControl && systemPrompt.length > 0) {
+                // Add cache_control to the last system block
+                systemContent = systemPrompt.map((block, idx) => {
+                    if (idx === systemPrompt.length - 1) {
+                        return { ...block, cache_control: cacheControl };
+                    }
+                    return block;
+                });
+            }
+            else {
+                systemContent = systemPrompt;
+            }
+        }
+        // Native tools
+        const nativeTools = tools?.length ? this.convertToNativeTools(tools) : undefined;
+        return {
+            messages: mergedMessages,
+            systemContent,
+            stopSequences: additionalStopSequences ?? [],
+            nativeTools,
+            ready: normalized.ready,
+        };
+    }
+    formatToolResults(results) {
+        // Native mode uses API tool_result blocks, not string formatting
+        // This method is mainly for prefill modes
+        return JSON.stringify(results.map(r => ({
+            tool_use_id: r.toolUseId,
+            content: r.content,
+            is_error: r.isError,
+        })));
+    }
+    // ==========================================================================
+    // RESPONSE PARSING
+    // ==========================================================================
+    createStreamParser() {
+        return new PassthroughParser();
+    }
+    parseToolCalls(content) {
+        // Native mode gets tool calls from API response, not from content parsing
+        // Return empty - tool calls come through the native API response
+        return [];
+    }
+    hasToolUse(content) {
+        // Native mode determines tool use from API stop_reason, not content
+        return false;
+    }
+    parseContentBlocks(content) {
+        // Native mode - content is plain text
+        if (!content.trim()) {
+            return [];
+        }
+        return [{ type: 'text', text: content }];
+    }
+    // ==========================================================================
+    // PRIVATE HELPERS
+    // ==========================================================================
+    convertContent(content, participant, options) {
+        const result = [];
+        let hasUnsupportedMedia = false;
+        for (const block of content) {
+            if (block.type === 'text') {
+                let text = block.text;
+                if (options.includeNames) {
+                    const prefix = this.config.nameFormat.replace('{name}', participant);
+                    text = prefix + text;
+                }
+                const textBlock = { type: 'text', text };
+                if (block.cache_control) {
+                    textBlock.cache_control = block.cache_control;
+                }
+                result.push(textBlock);
+            }
+            else if (block.type === 'image') {
+                if (block.source.type === 'base64') {
+                    const imageBlock = {
+                        type: 'image',
+                        source: {
+                            type: 'base64',
+                            media_type: block.source.mediaType,
+                            data: block.source.data,
+                        },
+                    };
+                    // Preserve sourceUrl for providers that use URL-as-text (Gemini 3.x)
+                    if (block.sourceUrl) {
+                        imageBlock.sourceUrl = block.sourceUrl;
+                    }
+                    result.push(imageBlock);
+                }
+            }
+            else if (block.type === 'tool_use') {
+                result.push({
+                    type: 'tool_use',
+                    id: block.id,
+                    name: block.name,
+                    input: block.input,
+                });
+            }
+            else if (block.type === 'tool_result') {
+                result.push({
+                    type: 'tool_result',
+                    tool_use_id: block.toolUseId,
+                    content: block.content,
+                    is_error: block.isError,
+                });
+            }
+            else if (block.type === 'thinking') {
+                result.push({
+                    type: 'thinking',
+                    thinking: block.thinking,
+                });
+            }
+            else if (block.type === 'document' || block.type === 'audio') {
+                hasUnsupportedMedia = true;
+            }
+        }
+        if (hasUnsupportedMedia) {
+            if (this.config.unsupportedMedia === 'error') {
+                throw new Error(`NativeFormatter: unsupported media type in content. Configure unsupportedMedia: 'strip' to ignore.`);
+            }
+            else if (this.config.warnOnStrip) {
+                console.warn(`[NativeFormatter] Stripped unsupported media from message`);
+            }
+        }
+        return result;
+    }
+    mergeConsecutiveRoles(messages) {
+        if (messages.length === 0)
+            return [];
+        const merged = [];
+        let current = messages[0];
+        for (let i = 1; i < messages.length; i++) {
+            const next = messages[i];
+            if (next.role === current.role) {
+                // Merge content arrays
+                const currentContent = Array.isArray(current.content) ? current.content : [current.content];
+                const nextContent = Array.isArray(next.content) ? next.content : [next.content];
+                current = {
+                    role: current.role,
+                    content: [...currentContent, ...nextContent],
+                };
+            }
+            else {
+                merged.push(current);
+                current = next;
+            }
+        }
+        merged.push(current);
+        return merged;
+    }
+    convertToNativeTools(tools) {
+        return tools.map(tool => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.inputSchema,
+        }));
+    }
+}
+//# sourceMappingURL=native.js.map

package/dist/formatters/native.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.js","sourceRoot":"","sources":["../../src/formatters/native.ts"],"names":[],"mappings":"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"}

package/dist/formatters/normalize-tool-pairs.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Tool-Pair Normalizer
+ *
+ * Anthropic's API enforces structural rules on tool cycles that any of
+ * Membrane's upstreams can accidentally violate:
+ *
+ *   - `tool_use` blocks must live in assistant-role messages.
+ *   - `tool_result` blocks must live in user-role messages.
+ *   - Every `tool_use` must be matched by its `tool_result` in the very
+ *     next user-role message.
+ *   - `thinking` blocks must live in assistant turns.
+ *
+ * When these are violated, the API returns 400 (e.g. `tool_use blocks can
+ * only be in assistant messages`). This module is the wire-boundary safety
+ * net: every formatter funnels through `normalizeToolPairs` before its
+ * output is shipped, so producer-side bugs cannot leak the same 400 family
+ * (compression-bug 5/6/7/8/9, agent-framework #37, 2026-05-22 miner stall).
+ *
+ * Algorithm overview (six phases): reclassify blocks by required role,
+ * reflow into role-correct envelopes, hoist matching tool_results across
+ * the assistant→user boundary, evict interlopers wedged between use and
+ * result, synthesize `[pending]` results for trailing orphans (or signal
+ * not-ready when the id is in the caller-supplied pending set), validate.
+ */
+import type { ProviderMessage as LooseProviderMessage } from './types.js';
+import type { NormalizeEvent } from './types.js';
+/**
+ * Block shape used internally and exposed for callers that want to
+ * build inputs without the full Anthropic SDK types. The required
+ * `type` discriminator names the kind of block; any block whose `type`
+ * matches a strict-role entry in `requiredRoleOf` is re-roled to its
+ * required role during normalization. Unrecognized `tool_*` or
+ * `thinking*` types fall through as `inherit` — see the one-shot
+ * warning below.
+ */
+export type ProviderBlock = Record<string, unknown> & {
+    type: string;
+};
+export interface NormalizeOptions {
+    /** See `BuildOptions.pendingToolCallIds`. */
+    pendingToolCallIds?: ReadonlySet<string>;
+    /** See `BuildOptions.onNormalize`. */
+    onEvent?: (event: NormalizeEvent) => void;
+}
+export interface NormalizeResult {
+    /**
+     * Normalized messages, structurally compatible with the loose
+     * `ProviderMessage` from `./types.js`. Block contents are
+     * `ProviderBlock[]` at runtime; the loose type is preserved at the
+     * public boundary so callers wired against `./types.js` don't need
+     * to cast.
+     */
+    messages: LooseProviderMessage[];
+    /**
+     * `false` iff a trailing unmatched tool_use's id was in
+     * `pendingToolCallIds`. Caller should wait for the in-flight result
+     * to land and retry instead of shipping the request.
+     */
+    ready: boolean;
+}
+export declare class MembraneNormalizerError extends Error {
+    readonly input: ReadonlyArray<LooseProviderMessage>;
+    readonly output: ReadonlyArray<LooseProviderMessage>;
+    constructor(message: string, input: ReadonlyArray<LooseProviderMessage>, output: ReadonlyArray<LooseProviderMessage>);
+}
+/**
+ * Normalize a sequence of provider messages so the output is API-valid
+ * with respect to Anthropic's tool-cycle structural rules.
+ *
+ * This function does NOT merge consecutive same-role envelopes — that
+ * remains the caller's responsibility (NativeFormatter.mergeConsecutiveRoles)
+ * so existing cache-control / breakpoint logic continues to work.
+ */
+export declare function normalizeToolPairs(input: ReadonlyArray<LooseProviderMessage>, options?: NormalizeOptions): NormalizeResult;
+//# sourceMappingURL=normalize-tool-pairs.d.ts.map

package/dist/formatters/normalize-tool-pairs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-tool-pairs.d.ts","sourceRoot":"","sources":["../../src/formatters/normalize-tool-pairs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,IAAI,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACzC,sCAAsC;IACtC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;aAG9B,KAAK,EAAE,aAAa,CAAC,oBAAoB,CAAC;aAC1C,MAAM,EAAE,aAAa,CAAC,oBAAoB,CAAC;gBAF3D,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,aAAa,CAAC,oBAAoB,CAAC,EAC1C,MAAM,EAAE,aAAa,CAAC,oBAAoB,CAAC;CAK9D;AAMD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,aAAa,CAAC,oBAAoB,CAAC,EAC1C,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CA+DjB"}