@animalabs/membrane 0.5.24 → 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

@@ -350,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

@@ -449,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

@@ -407,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';
+}

package/src/yielding-stream.ts

@@ -0,0 +1,271 @@
+/**
+ * YieldingStream implementation
+ *
+ * Provides an async iterator interface for streaming inference that yields
+ * control back to the caller for tool execution.
+ */
+
+import type {
+  StreamEvent,
+  YieldingStream,
+  YieldingStreamOptions,
+  ToolCallsEvent,
+} from './types/yielding-stream.js';
+import type { ToolResult } from './types/tools.js';
+
+// ============================================================================
+// Internal State Types
+// ============================================================================
+
+type StreamState =
+  | { status: 'idle' }
+  | { status: 'streaming' }
+  | { status: 'waiting_for_tools'; pendingCallIds: string[] }
+  | { status: 'done' }
+  | { status: 'error'; error: Error };
+
+interface PendingToolResults {
+  resolve: (results: ToolResult[]) => void;
+  reject: (error: Error) => void;
+}
+
+// ============================================================================
+// YieldingStreamImpl
+// ============================================================================
+
+/**
+ * Implementation of the YieldingStream interface.
+ *
+ * This class manages:
+ * - An event queue for yielding events to the consumer
+ * - A promise-based handshake for tool results
+ * - Cancellation via AbortController
+ * - State tracking for debugging and validation
+ */
+export class YieldingStreamImpl implements YieldingStream {
+  private state: StreamState = { status: 'idle' };
+  private eventQueue: StreamEvent[] = [];
+  private pendingToolResults: PendingToolResults | null = null;
+  private abortController: AbortController;
+  private _toolDepth = 0;
+
+  // Promise/resolver for the async iterator to wait on new events
+  private eventWaiter: {
+    resolve: () => void;
+    promise: Promise<void>;
+  } | null = null;
+
+  // Flag indicating the stream producer is done
+  private producerDone = false;
+
+  constructor(
+    private readonly options: YieldingStreamOptions,
+    private readonly runInference: (stream: YieldingStreamImpl) => Promise<void>
+  ) {
+    this.abortController = new AbortController();
+
+    // Link external signal if provided
+    if (options.signal) {
+      options.signal.addEventListener('abort', () => {
+        this.cancel();
+      });
+    }
+  }
+
+  // ============================================================================
+  // Public Interface
+  // ============================================================================
+
+  get isWaitingForTools(): boolean {
+    return this.state.status === 'waiting_for_tools';
+  }
+
+  get pendingToolCallIds(): string[] {
+    if (this.state.status === 'waiting_for_tools') {
+      return this.state.pendingCallIds;
+    }
+    return [];
+  }
+
+  get toolDepth(): number {
+    return this._toolDepth;
+  }
+
+  /**
+   * Get the abort signal for use in internal operations.
+   */
+  get signal(): AbortSignal {
+    return this.abortController.signal;
+  }
+
+  provideToolResults(results: ToolResult[]): void {
+    if (this.state.status !== 'waiting_for_tools') {
+      throw new Error(
+        `Cannot provide tool results: stream is not waiting for tools (status: ${this.state.status})`
+      );
+    }
+
+    if (!this.pendingToolResults) {
+      throw new Error('Internal error: no pending tool results promise');
+    }
+
+    // Validate that results match pending call IDs
+    const pendingIds = new Set(this.state.pendingCallIds);
+    const providedIds = new Set(results.map((r) => r.toolUseId));
+
+    for (const id of pendingIds) {
+      if (!providedIds.has(id)) {
+        throw new Error(`Missing tool result for call ID: ${id}`);
+      }
+    }
+
+    // Resolve the promise and transition state
+    this.pendingToolResults.resolve(results);
+    this.pendingToolResults = null;
+    this.state = { status: 'streaming' };
+    this._toolDepth++;
+  }
+
+  cancel(): void {
+    if (this.state.status === 'done' || this.state.status === 'error') {
+      return; // Already terminated
+    }
+
+    this.abortController.abort();
+
+    // If waiting for tools, reject the pending promise
+    if (this.pendingToolResults) {
+      this.pendingToolResults.reject(new Error('Stream cancelled'));
+      this.pendingToolResults = null;
+    }
+
+    // Emit aborted event and wake the iterator so it can deliver it
+    this.emit({ type: 'aborted', reason: 'user' });
+    this.producerDone = true;
+    this.state = { status: 'done' };
+  }
+
+  // ============================================================================
+  // Async Iterator Implementation
+  // ============================================================================
+
+  [Symbol.asyncIterator](): AsyncIterator<StreamEvent> {
+    // Start the inference loop when iteration begins
+    this.startInference();
+
+    return {
+      next: async (): Promise<IteratorResult<StreamEvent>> => {
+        while (true) {
+          // Check for queued events
+          const event = this.eventQueue.shift();
+          if (event) {
+            // Check if this is a terminal event
+            if (
+              event.type === 'complete' ||
+              event.type === 'error' ||
+              event.type === 'aborted'
+            ) {
+              this.state = { status: 'done' };
+            }
+            return { value: event, done: false };
+          }
+
+          // If producer is done and queue is empty, we're done
+          if (this.producerDone) {
+            return { value: undefined as unknown as StreamEvent, done: true };
+          }
+
+          // Wait for more events
+          await this.waitForEvent();
+        }
+      },
+    };
+  }
+
+  // ============================================================================
+  // Internal Methods (called by the inference loop)
+  // ============================================================================
+
+  /**
+   * Push an event to be yielded to the consumer.
+   */
+  emit(event: StreamEvent): void {
+    this.eventQueue.push(event);
+    this.notifyEventWaiter();
+  }
+
+  /**
+   * Request tool execution and wait for results.
+   * Called by the inference loop when tool calls are detected.
+   */
+  async requestToolExecution(event: ToolCallsEvent): Promise<ToolResult[]> {
+    // Emit the tool calls event
+    this.emit(event);
+
+    // Transition to waiting state
+    this.state = {
+      status: 'waiting_for_tools',
+      pendingCallIds: event.calls.map((c) => c.id),
+    };
+
+    // Create a promise that will be resolved by provideToolResults()
+    return new Promise<ToolResult[]>((resolve, reject) => {
+      this.pendingToolResults = { resolve, reject };
+    });
+  }
+
+  /**
+   * Mark the producer as done (inference loop finished).
+   */
+  markDone(): void {
+    this.producerDone = true;
+    this.notifyEventWaiter();
+  }
+
+  /**
+   * Check if the stream has been cancelled.
+   */
+  get isCancelled(): boolean {
+    return this.abortController.signal.aborted;
+  }
+
+  // ============================================================================
+  // Private Helpers
+  // ============================================================================
+
+  private startInference(): void {
+    if (this.state.status !== 'idle') {
+      return; // Already started
+    }
+
+    this.state = { status: 'streaming' };
+
+    // Run the inference loop in the background
+    this.runInference(this)
+      .then(() => {
+        this.markDone();
+      })
+      .catch((error) => {
+        this.emit({ type: 'error', error });
+        this.markDone();
+      });
+  }
+
+  private waitForEvent(): Promise<void> {
+    if (!this.eventWaiter) {
+      let resolve: () => void;
+      const promise = new Promise<void>((r) => {
+        resolve = r;
+      });
+      this.eventWaiter = { resolve: resolve!, promise };
+    }
+    return this.eventWaiter.promise;
+  }
+
+  private notifyEventWaiter(): void {
+    if (this.eventWaiter) {
+      this.eventWaiter.resolve();
+      this.eventWaiter = null;
+    }
+  }
+}