@animalabs/membrane 0.5.37 → 0.5.38

package/src/membrane.ts

@@ -203,14 +203,19 @@ export class Membrane {
     if (request.toolMode && request.toolMode !== 'auto') {
       return request.toolMode;
     }
-    
-    // Auto mode: choose based on provider
-    // OpenRouter and OpenAI-compatible APIs use native tools
-    // Anthropic direct with prefill mode uses XML tools
+
+    // Auto mode: choose based on formatter
+    // NativeFormatter → native tools via API
+    // AnthropicXmlFormatter (default) → XML tools in prefill
+    if (this.formatter.name === 'native') {
+      return 'native';
+    }
+
+    // Also handle known native-tool providers regardless of formatter
     if (this.adapter.name === 'openrouter') {
       return 'native';
     }
-    
+
     // Default to XML for prefill compatibility
     return 'xml';
   }
@@ -837,14 +842,17 @@ export class Membrane {
             });
           }
 
-          // Add assistant message with tool use and user message with tool results
+          // Add assistant message with tool use and user message with tool results.
+          // Use the request's participant name so role mapping is consistent.
+          const asstName = request.assistantParticipant
+            ?? this.config.assistantParticipant ?? 'Claude';
           messages.push({
-            participant: 'Claude',
+            participant: asstName,
             content: responseBlocks,
           });
 
           messages.push({
-            participant: 'User',
+            participant: asstName === 'Claude' ? 'User' : 'user',
             content: results.map(r => ({
               type: 'tool_result' as const,
               toolUseId: r.toolUseId,
@@ -923,8 +931,11 @@ export class Membrane {
     // Convert messages to provider format
     const providerMessages: any[] = [];
     
+    const assistantName = request.assistantParticipant
+      ?? this.config.assistantParticipant ?? 'Claude';
+
     for (const msg of messages) {
-      const isAssistant = msg.participant === 'Claude';
+      const isAssistant = msg.participant === assistantName;
       const role = isAssistant ? 'assistant' : 'user';
       
       // Convert content blocks
@@ -940,7 +951,7 @@ export class Membrane {
           content.push({
             type: 'tool_use',
             id: block.id,
-            name: block.name,
+            name: sanitizeToolName(block.name),
             input: block.input,
           });
         } else if (block.type === 'tool_result') {
@@ -972,9 +983,11 @@ export class Membrane {
       providerMessages.push({ role, content });
     }
     
-    // Convert tools to provider format
+    // Convert tools to provider format.
+    // Native tool names must match ^[a-zA-Z0-9_-]{1,128}$ — sanitize colons
+    // from the module:tool namespace convention. Reversed in parseProviderContent.
     const tools = request.tools?.map(tool => ({
-      name: tool.name,
+      name: sanitizeToolName(tool.name),
       description: tool.description,
       input_schema: tool.inputSchema,
     }));
@@ -1017,7 +1030,7 @@ export class Membrane {
           blocks.push({
             type: 'tool_use',
             id: item.id,
-            name: item.name,
+            name: unsanitizeToolName(item.name),
             input: item.input,
           });
         } else if (item.type === 'thinking') {
@@ -1071,7 +1084,7 @@ export class Membrane {
     // Use formatter's buildMessages for all request building
     const buildResult = activeFormatter.buildMessages(request.messages, {
       participantMode: 'multiuser',
-      assistantParticipant: this.config.assistantParticipant ?? 'Claude',
+      assistantParticipant: request.assistantParticipant ?? this.config.assistantParticipant ?? 'Claude',
       tools: request.tools,
       thinking: request.config.thinking,
       systemPrompt: request.system,
@@ -1107,7 +1120,7 @@ export class Membrane {
   private async streamOnce(
     request: any,
     callbacks: { onChunk: (chunk: string) => void; onContentBlock?: (index: number, block: unknown) => void },
-    options: { signal?: AbortSignal; timeoutMs?: number; onRequest?: (rawRequest: unknown) => void }
+    options: { signal?: AbortSignal; timeoutMs?: number; idleTimeoutMs?: number; onRequest?: (rawRequest: unknown) => void }
   ) {
     return await this.adapter.stream(request, callbacks, options);
   }
@@ -1693,6 +1706,7 @@ export class Membrane {
           {
             signal: stream.signal,
             timeoutMs: options.timeoutMs,
+            idleTimeoutMs: options.idleTimeoutMs,
             onRequest: (req: unknown) => { rawRequest = req; },
           }
         );
@@ -2070,6 +2084,7 @@ export class Membrane {
           {
             signal: stream.signal,
             timeoutMs: options.timeoutMs,
+            idleTimeoutMs: options.idleTimeoutMs,
             onRequest: (req: unknown) => { rawRequest = req; },
           }
         );
@@ -2135,14 +2150,16 @@ export class Membrane {
             });
           }
 
-          // Add messages for next iteration
+          // Add messages for next iteration — use the request's participant names
+          const assistantName = request.assistantParticipant
+            ?? this.config.assistantParticipant ?? 'Claude';
           messages.push({
-            participant: 'Claude',
+            participant: assistantName,
             content: responseBlocks,
           });
 
           messages.push({
-            participant: 'User',
+            participant: assistantName === 'Claude' ? 'User' : 'user',
             content: results.map(r => ({
               type: 'tool_result' as const,
               toolUseId: r.toolUseId,
@@ -2212,3 +2229,15 @@ export class Membrane {
     }
   }
 }
+
+// Native tool names must match ^[a-zA-Z0-9_-]{1,128}$.
+// The framework uses module:tool namespacing, so we round-trip colons
+// through an escape encoding for the API wire format.
+// Lossless: escape underscores first (_u), then encode colons (_c).
+function sanitizeToolName(name: string): string {
+  return name.replace(/_/g, '_u').replace(/:/g, '_c');
+}
+
+function unsanitizeToolName(name: string): string {
+  return name.replace(/_c/g, ':').replace(/_u/g, '_');
+}

package/src/providers/anthropic.ts

@@ -85,38 +85,151 @@ export class AnthropicAdapter implements ProviderAdapter {
     const fullRequest = { ...anthropicRequest, stream: true };
     options?.onRequest?.(fullRequest);
 
+    // Idle timeout: abort if no SSE event arrives within the deadline.
+    // The SDK's timeout only covers the initial HTTP response headers;
+    // once streaming starts, a silently dropped connection waits forever.
+    const idleMs = options?.idleTimeoutMs ?? 120_000;
+    const idleAbort = new AbortController();
+    let idleTimer: ReturnType<typeof setTimeout> | null = null;
+    let idleTimedOut = false;
+
+    // Link caller's signal so external cancellation still works
+    const onExternalAbort = () => idleAbort.abort();
+    if (options?.signal) {
+      if (options.signal.aborted) { idleAbort.abort(); }
+      else { options.signal.addEventListener('abort', onExternalAbort, { once: true }); }
+    }
+
+    const resetIdleTimer = () => {
+      if (idleTimer) clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => { idleTimedOut = true; idleAbort.abort(); }, idleMs);
+    };
+
+    resetIdleTimer();
+
     try {
       const stream = await this.client.messages.stream(anthropicRequest, {
-        signal: options?.signal,
+        signal: idleAbort.signal,
       });
 
-      let accumulated = '';
-      const contentBlocks: unknown[] = [];
+      // Accumulate response metadata from SSE events directly, so we can
+      // skip finalMessage() and its variable-latency connection teardown.
+      let model = '';
+      let inputTokens = 0;
+      let outputTokens = 0;
+      let cacheCreationTokens: number | undefined;
+      let cacheReadTokens: number | undefined;
+      let stopReason: string = 'end_turn';
+      let stopSequence: string | undefined;
+
+      // Content block tracking — finalized on content_block_stop
+      const contentBlocks: Record<string, unknown>[] = [];
       let currentBlockIndex = -1;
+      let currentBlockContent = '';
+      let currentBlockInputJson = '';
 
       for await (const event of stream) {
-        if (event.type === 'content_block_start') {
+        resetIdleTimer();
+        if (event.type === 'message_start') {
+          model = event.message.model;
+          const usage = event.message.usage as unknown as Record<string, number>;
+          inputTokens = usage.input_tokens ?? 0;
+          cacheCreationTokens = usage.cache_creation_input_tokens;
+          cacheReadTokens = usage.cache_read_input_tokens;
+
+        } else if (event.type === 'content_block_start') {
           currentBlockIndex = event.index;
-          contentBlocks[currentBlockIndex] = event.content_block;
+          currentBlockContent = '';
+          currentBlockInputJson = '';
+          contentBlocks[currentBlockIndex] = { ...event.content_block };
           callbacks.onContentBlock?.(currentBlockIndex, event.content_block);
+
         } else if (event.type === 'content_block_delta') {
           if (event.delta.type === 'text_delta') {
             const chunk = event.delta.text;
-            accumulated += chunk;
+            currentBlockContent += chunk;
             callbacks.onChunk(chunk);
           } else if (event.delta.type === 'thinking_delta') {
-            // Handle thinking delta
+            currentBlockContent += event.delta.thinking;
             callbacks.onChunk(event.delta.thinking);
+          } else if ((event.delta as { type: string }).type === 'input_json_delta') {
+            currentBlockInputJson += (event.delta as { partial_json: string }).partial_json;
           }
+
         } else if (event.type === 'content_block_stop') {
-          callbacks.onContentBlock?.(currentBlockIndex, contentBlocks[currentBlockIndex]);
+          // Finalize block — use event.index for defensive correctness
+          const blockIdx = (event as { index: number }).index;
+          const block = contentBlocks[blockIdx];
+          if (block) {
+            if (block.type === 'text') {
+              block.text = currentBlockContent;
+            } else if (block.type === 'thinking') {
+              block.thinking = currentBlockContent;
+            } else if (block.type === 'tool_use' && currentBlockInputJson) {
+              try { block.input = JSON.parse(currentBlockInputJson); } catch { /* partial JSON */ }
+            }
+          }
+          callbacks.onContentBlock?.(blockIdx, contentBlocks[blockIdx]);
+
+        } else if (event.type === 'message_delta') {
+          // All content blocks are finalized by the time message_delta arrives.
+          // Capture final metadata and exit — message_stop and the SSE connection
+          // teardown after it add only variable latency with no useful data.
+          const delta = event.delta as { stop_reason?: string; stop_sequence?: string };
+          stopReason = delta.stop_reason ?? 'end_turn';
+          stopSequence = delta.stop_sequence ?? undefined;
+          outputTokens = (event.usage as { output_tokens: number }).output_tokens ?? 0;
+          break;
         }
       }
 
-      const finalMessage = await stream.finalMessage();
-      return this.parseResponse(finalMessage, fullRequest);
+      // Clean up idle timer and external signal listener
+      if (idleTimer) clearTimeout(idleTimer);
+      options?.signal?.removeEventListener('abort', onExternalAbort);
+
+      // Force-close the HTTP connection so we don't block on SSE drain
+      try { stream.controller.abort(); } catch { /* already closed */ }
+
+      return {
+        content: contentBlocks,
+        stopReason,
+        stopSequence,
+        usage: {
+          inputTokens,
+          outputTokens,
+          cacheCreationTokens,
+          cacheReadTokens,
+        },
+        model,
+        rawRequest: fullRequest,
+        raw: {
+          content: contentBlocks,
+          stop_reason: stopReason,
+          stop_sequence: stopSequence ?? null,
+          model,
+          usage: {
+            input_tokens: inputTokens,
+            output_tokens: outputTokens,
+            cache_creation_input_tokens: cacheCreationTokens,
+            cache_read_input_tokens: cacheReadTokens,
+          },
+        },
+      };
 
     } catch (error) {
+      // Clean up timer on error path too
+      if (idleTimer) clearTimeout(idleTimer);
+      options?.signal?.removeEventListener('abort', onExternalAbort);
+
+      if (idleTimedOut && error instanceof Error && error.name === 'AbortError') {
+        throw new MembraneError({
+          type: 'timeout',
+          message: `SSE stream idle timeout — no events received within ${idleMs}ms`,
+          retryable: true,
+          rawError: error,
+          rawRequest: fullRequest,
+        });
+      }
       throw this.handleError(error, fullRequest);
     }
   }

package/src/providers/bedrock.ts

@@ -332,10 +332,26 @@ export class BedrockAdapter implements ProviderAdapter {
   }
 
   private buildRequest(request: ProviderRequest): BedrockMessageRequest {
+    // Strip provider-specific fields (e.g., sourceUrl for Gemini) from image blocks
+    // before sending to Bedrock/Anthropic, which rejects extra inputs
+    const sanitizedMessages = (request.messages as any[]).map((msg: any) => {
+      if (!Array.isArray(msg.content)) return msg;
+      return {
+        ...msg,
+        content: msg.content.map((block: any) => {
+          if (block.type === 'image' && block.sourceUrl !== undefined) {
+            const { sourceUrl, ...rest } = block;
+            return rest;
+          }
+          return block;
+        }),
+      };
+    });
+
     const params: BedrockMessageRequest = {
       anthropic_version: this.anthropicVersion,
       max_tokens: request.maxTokens || this.defaultMaxTokens,
-      messages: request.messages as BedrockMessageRequest['messages'],
+      messages: sanitizedMessages as BedrockMessageRequest['messages'],
     };
 
     // Handle system prompt

package/src/types/provider.ts

@@ -228,6 +228,8 @@ export interface ProviderRequest {
 export interface ProviderRequestOptions {
   signal?: AbortSignal;
   timeoutMs?: number;
+  /** Abort if no SSE event arrives within this many ms (default: 120000) */
+  idleTimeoutMs?: number;
   /** Called with the raw API request body right before fetch */
   onRequest?: (rawRequest: unknown) => void;
 }

package/src/types/request.ts

@@ -154,6 +154,13 @@ export interface NormalizedRequest {
    */
   prefillUserMessage?: string;
 
+  /**
+   * Participant name that maps to the 'assistant' role.
+   * Messages with this participant are formatted as assistant turns.
+   * Default: 'Claude'
+   */
+  assistantParticipant?: string;
+
   /** Provider-specific parameters (pass-through) */
   providerParams?: Record<string, unknown>;
 }

package/src/types/tools.ts

@@ -20,7 +20,7 @@ export interface ToolDefinition {
   description: string;
   inputSchema: {
     type: 'object';
-    properties: Record<string, ToolParameter>;
+    properties?: Record<string, ToolParameter>;
     required?: string[];
   };
 }

package/src/types/yielding-stream.ts

@@ -170,6 +170,9 @@ export interface YieldingStreamOptions {
   /** Request timeout (per API call, not total) */
   timeoutMs?: number;
 
+  /** Abort if no SSE event arrives within this many ms (default: 120000) */
+  idleTimeoutMs?: number;
+
   /** Request ID for correlation/logging */
   requestId?: string;
 

package/src/yielding-stream.ts

@@ -246,7 +246,9 @@ export class YieldingStreamImpl implements YieldingStream {
         this.markDone();
       })
       .catch((error) => {
-        this.emit({ type: 'error', error });
+        if (!this.isCancelled) {
+          this.emit({ type: 'error', error });
+        }
         this.markDone();
       });
   }