@animalabs/membrane 0.5.23 → 0.5.25

package/src/providers/mock.ts

@@ -12,6 +12,7 @@ import type {
   ProviderResponse,
   StreamCallbacks,
 } from '../types/provider.js';
+import { abortError } from '../types/errors.js';
 
 export interface MockAdapterConfig {
   /** Default response text when no specific response is configured */
@@ -157,12 +158,15 @@ export class MockAdapter implements ProviderAdapter {
     request: ProviderRequest,
     options?: ProviderRequestOptions
   ): Promise<ProviderResponse> {
+    // Check for abort before starting
+    this.checkAbort(options?.signal);
+
     // Call onRequest callback if provided
     options?.onRequest?.(request);
 
     // Simulate processing delay
     if (this.config.completeDelayMs > 0) {
-      await this.sleep(this.config.completeDelayMs);
+      await this.abortableSleep(this.config.completeDelayMs, options?.signal);
     }
 
     const responseText = this.getResponse(request);
@@ -185,20 +189,28 @@ export class MockAdapter implements ProviderAdapter {
     callbacks: StreamCallbacks,
     options?: ProviderRequestOptions
   ): Promise<ProviderResponse> {
+    // Check for abort before starting
+    this.checkAbort(options?.signal);
+
     // Call onRequest callback if provided
     options?.onRequest?.(request);
 
     const responseText = this.getResponse(request);
+    let streamedText = '';
 
     // Stream the response in chunks
     let offset = 0;
     while (offset < responseText.length) {
+      // Check for abort before each chunk
+      this.checkAbort(options?.signal);
+
       const chunk = responseText.slice(offset, offset + this.config.streamChunkSize);
       callbacks.onChunk(chunk);
+      streamedText += chunk;
       offset += this.config.streamChunkSize;
 
       if (offset < responseText.length && this.config.streamChunkDelayMs > 0) {
-        await this.sleep(this.config.streamChunkDelayMs);
+        await this.abortableSleep(this.config.streamChunkDelayMs, options?.signal);
       }
     }
 
@@ -215,6 +227,39 @@ export class MockAdapter implements ProviderAdapter {
     };
   }
 
+  /**
+   * Check if the abort signal is set and throw if so.
+   */
+  private checkAbort(signal?: AbortSignal): void {
+    if (signal?.aborted) {
+      throw abortError('Request aborted');
+    }
+  }
+
+  /**
+   * Sleep that can be interrupted by an abort signal.
+   */
+  private abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(abortError('Request aborted'));
+        return;
+      }
+
+      const onAbort = () => {
+        clearTimeout(timeout);
+        reject(abortError('Request aborted'));
+      };
+
+      const timeout = setTimeout(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve();
+      }, ms);
+
+      signal?.addEventListener('abort', onAbort, { once: true });
+    });
+  }
+
   private sleep(ms: number): Promise<void> {
     return new Promise(resolve => setTimeout(resolve, ms));
   }

package/src/providers/openai-compatible.ts

@@ -291,8 +291,9 @@ export class OpenAICompatibleAdapter implements ProviderAdapter {
       params.frequency_penalty = request.frequencyPenalty;
     }
 
+    // OpenAI-compatible APIs may limit stop sequences (OpenAI: 4) — truncate to be safe
     if (request.stopSequences && request.stopSequences.length > 0) {
-      params.stop = request.stopSequences;
+      params.stop = request.stopSequences.slice(0, 4);
     }
     
     if (request.tools && request.tools.length > 0) {
@@ -349,16 +350,21 @@ export class OpenAICompatibleAdapter implements ProviderAdapter {
           return toolResults;
         }
         
+        // Skip messages with no usable content (image-only, embed-only messages)
+        if (textParts.length === 0 && toolCalls.length === 0) {
+          return [];
+        }
+
         // Otherwise build normal message
         const result: OpenAIMessage = {
           role: msg.role,
-          content: textParts.join('\n') || null,
+          content: textParts.length > 0 ? textParts.join('\n') : null,
         };
-        
+
         if (toolCalls.length > 0) {
           result.tool_calls = toolCalls;
         }
-        
+
         return [result];
       }
       

package/src/providers/openai.ts

@@ -390,8 +390,9 @@ export class OpenAIAdapter implements ProviderAdapter {
     }
 
     // Reasoning models (o1, o3, o4) don't support stop sequences
+    // OpenAI limits stop sequences to 4 — truncate to fit
     if (request.stopSequences && request.stopSequences.length > 0 && !noStopSupport(model)) {
-      params.stop = request.stopSequences;
+      params.stop = request.stopSequences.slice(0, 4);
     }
     
     if (request.tools && request.tools.length > 0) {
@@ -448,16 +449,21 @@ export class OpenAIAdapter implements ProviderAdapter {
           return toolResults;
         }
         
+        // Skip messages with no usable content (image-only, embed-only messages)
+        if (textParts.length === 0 && toolCalls.length === 0) {
+          return [];
+        }
+
         // Otherwise build normal message
         const result: OpenAIMessage = {
           role: msg.role,
-          content: textParts.join('\n') || null,
+          content: textParts.length > 0 ? textParts.join('\n') : null,
         };
-        
+
         if (toolCalls.length > 0) {
           result.tool_calls = toolCalls;
         }
-        
+
         return [result];
       }
       

package/src/providers/openrouter.ts

@@ -313,8 +313,9 @@ export class OpenRouterAdapter implements ProviderAdapter {
       params.frequency_penalty = request.frequencyPenalty;
     }
 
+    // OpenAI-compatible APIs may limit stop sequences (OpenAI: 4) — truncate to be safe
     if (request.stopSequences && request.stopSequences.length > 0) {
-      params.stop = request.stopSequences;
+      params.stop = request.stopSequences.slice(0, 4);
     }
     
     if (request.tools && request.tools.length > 0) {
@@ -406,17 +407,22 @@ export class OpenRouterAdapter implements ProviderAdapter {
           return toolResults;
         }
         
+        // Skip messages with no usable content (image-only, embed-only messages)
+        if (textParts.length === 0 && toolCalls.length === 0) {
+          return [];
+        }
+
         // Otherwise build normal message
         const result: OpenRouterMessage = {
           role: msg.role,
           // Use content blocks array if caching is in use, otherwise concatenate text
-          content: hasCache ? contentBlocks : (textParts.join('\n') || null),
+          content: hasCache ? contentBlocks : (textParts.length > 0 ? textParts.join('\n') : null),
         };
-        
+
         if (toolCalls.length > 0) {
           result.tool_calls = toolCalls;
         }
-        
+
         return [result];
       }
       

package/src/types/index.ts

@@ -120,6 +120,29 @@ export type {
   BlockDelta,
 } from './streaming.js';
 
+// Yielding Stream
+export type {
+  TokensEvent,
+  StreamBlockEvent,
+  ToolCallsEvent,
+  UsageEvent,
+  CompleteEvent,
+  ErrorEvent,
+  AbortedEvent,
+  StreamEvent,
+  YieldingStream,
+  YieldingStreamOptions,
+} from './yielding-stream.js';
+
+export {
+  isTokensEvent,
+  isToolCallsEvent,
+  isCompleteEvent,
+  isErrorEvent,
+  isAbortedEvent,
+  isTerminalEvent,
+} from './yielding-stream.js';
+
 // Errors
 export type {
   MembraneErrorType,

package/src/types/yielding-stream.ts

@@ -0,0 +1,228 @@
+/**
+ * Yielding stream types for membrane
+ *
+ * This module defines the interface for a streaming API that yields control
+ * back to the caller when tool calls are detected, rather than handling them
+ * internally via callbacks.
+ *
+ * @see agent-framework/docs/yielding-stream-architecture.md
+ */
+
+import type { ContentBlock } from './content.js';
+import type { ToolCall, ToolResult, ToolContext } from './tools.js';
+import type { BasicUsage, NormalizedResponse, StopReason } from './response.js';
+import type { ChunkMeta, BlockEvent } from './streaming.js';
+
+// ============================================================================
+// Stream Events
+// ============================================================================
+
+/**
+ * Token/chunk event - raw text as it arrives from the LLM.
+ */
+export interface TokensEvent {
+  type: 'tokens';
+  content: string;
+  meta: ChunkMeta;
+}
+
+/**
+ * Block event - structural block start/complete notifications.
+ */
+export interface StreamBlockEvent {
+  type: 'block';
+  event: BlockEvent;
+}
+
+/**
+ * Tool calls event - LLM has requested tool execution.
+ * The stream pauses here until results are provided via provideToolResults().
+ */
+export interface ToolCallsEvent {
+  type: 'tool-calls';
+  calls: ToolCall[];
+  context: ToolContext;
+}
+
+/**
+ * Usage update event - token counts updated.
+ */
+export interface UsageEvent {
+  type: 'usage';
+  usage: BasicUsage;
+}
+
+/**
+ * Complete event - inference cycle finished successfully.
+ */
+export interface CompleteEvent {
+  type: 'complete';
+  response: NormalizedResponse;
+}
+
+/**
+ * Error event - something went wrong.
+ */
+export interface ErrorEvent {
+  type: 'error';
+  error: Error;
+}
+
+/**
+ * Aborted event - stream was cancelled.
+ */
+export interface AbortedEvent {
+  type: 'aborted';
+  reason: 'user' | 'timeout' | 'error';
+  partialContent?: ContentBlock[];
+  rawAssistantText?: string;
+  toolCalls?: ToolCall[];
+  toolResults?: ToolResult[];
+}
+
+/**
+ * Union of all stream events.
+ */
+export type StreamEvent =
+  | TokensEvent
+  | StreamBlockEvent
+  | ToolCallsEvent
+  | UsageEvent
+  | CompleteEvent
+  | ErrorEvent
+  | AbortedEvent;
+
+// ============================================================================
+// Yielding Stream Interface
+// ============================================================================
+
+/**
+ * A streaming inference that yields control to the caller for tool execution.
+ *
+ * Usage:
+ * ```typescript
+ * const stream = membrane.streamYielding(request, options);
+ *
+ * for await (const event of stream) {
+ *   switch (event.type) {
+ *     case 'tokens':
+ *       process.stdout.write(event.content);
+ *       break;
+ *     case 'tool-calls':
+ *       const results = await executeTools(event.calls);
+ *       stream.provideToolResults(results);
+ *       break;
+ *     case 'complete':
+ *       console.log('Done:', event.response);
+ *       break;
+ *     case 'error':
+ *       console.error('Error:', event.error);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export interface YieldingStream extends AsyncIterable<StreamEvent> {
+  /**
+   * Provide tool results after receiving a 'tool-calls' event.
+   * The stream will resume and continue generating.
+   *
+   * @param results - Results for the tool calls (must match call IDs)
+   * @throws Error if called when not waiting for tool results
+   */
+  provideToolResults(results: ToolResult[]): void;
+
+  /**
+   * Cancel the stream. Any in-flight requests will be aborted.
+   * The iterator will yield an 'aborted' event and then complete.
+   */
+  cancel(): void;
+
+  /**
+   * Check if the stream is currently waiting for tool results.
+   */
+  readonly isWaitingForTools: boolean;
+
+  /**
+   * Get the IDs of tool calls we're waiting for results for.
+   * Empty if not waiting for tools.
+   */
+  readonly pendingToolCallIds: string[];
+
+  /**
+   * Current tool execution depth (0 = first inference, 1 = after first tool round, etc.)
+   */
+  readonly toolDepth: number;
+}
+
+// ============================================================================
+// Yielding Stream Options
+// ============================================================================
+
+/**
+ * Options for streamYielding().
+ * Simpler than StreamOptions since tool execution is handled externally.
+ */
+export interface YieldingStreamOptions {
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+
+  /** Request timeout (per API call, not total) */
+  timeoutMs?: number;
+
+  /** Request ID for correlation/logging */
+  requestId?: string;
+
+  /** Maximum tool execution depth (default: 10) */
+  maxToolDepth?: number;
+
+  /**
+   * Whether to emit 'tokens' events.
+   * Set to false if you only care about tool calls and final response.
+   * Default: true
+   */
+  emitTokens?: boolean;
+
+  /**
+   * Whether to emit 'block' events.
+   * Default: true
+   */
+  emitBlocks?: boolean;
+
+  /**
+   * Whether to emit 'usage' events.
+   * Default: true
+   */
+  emitUsage?: boolean;
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isTokensEvent(event: StreamEvent): event is TokensEvent {
+  return event.type === 'tokens';
+}
+
+export function isToolCallsEvent(event: StreamEvent): event is ToolCallsEvent {
+  return event.type === 'tool-calls';
+}
+
+export function isCompleteEvent(event: StreamEvent): event is CompleteEvent {
+  return event.type === 'complete';
+}
+
+export function isErrorEvent(event: StreamEvent): event is ErrorEvent {
+  return event.type === 'error';
+}
+
+export function isAbortedEvent(event: StreamEvent): event is AbortedEvent {
+  return event.type === 'aborted';
+}
+
+/**
+ * Check if the stream has terminated (complete, error, or aborted).
+ */
+export function isTerminalEvent(event: StreamEvent): event is CompleteEvent | ErrorEvent | AbortedEvent {
+  return event.type === 'complete' || event.type === 'error' || event.type === 'aborted';
+}