@animalabs/membrane 0.1.0

package/src/types/response.ts

@@ -0,0 +1,223 @@
+/**
+ * Response types for membrane
+ */
+
+import type { ContentBlock } from './content.js';
+import type { ToolCall, ToolResult } from './tools.js';
+
+// ============================================================================
+// Stop Reason
+// ============================================================================
+
+export type StopReason =
+  | 'end_turn'       // Natural completion
+  | 'max_tokens'     // Hit token limit
+  | 'stop_sequence'  // Hit stop sequence
+  | 'tool_use'       // Stopped for tool use
+  | 'refusal'        // Content refused by safety
+  | 'abort';         // Request was aborted
+
+// ============================================================================
+// Usage Information
+// ============================================================================
+
+export interface BasicUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface DetailedUsage extends BasicUsage {
+  /** Tokens used for cache creation */
+  cacheCreationTokens?: number;
+  
+  /** Tokens read from cache */
+  cacheReadTokens?: number;
+  
+  /** Tokens used for thinking/reasoning */
+  thinkingTokens?: number;
+  
+  /** Estimated cost breakdown */
+  estimatedCost?: CostBreakdown;
+}
+
+export interface CostBreakdown {
+  input: number;
+  output: number;
+  cacheWrite?: number;
+  cacheRead?: number;
+  total: number;
+  currency: string;
+}
+
+// ============================================================================
+// Stop Information
+// ============================================================================
+
+export interface StopInfo {
+  reason: StopReason;
+  
+  /** Which stop sequence triggered (if stop_sequence) */
+  triggeredSequence?: string;
+  
+  /** Whether output was truncated */
+  wasTruncated: boolean;
+}
+
+// ============================================================================
+// Model Information
+// ============================================================================
+
+export interface ModelInfo {
+  /** Model ID that was requested */
+  requested: string;
+  
+  /** Model ID that actually ran (may differ due to routing/fallback) */
+  actual: string;
+  
+  /** Provider that served the request */
+  provider: string;
+}
+
+// ============================================================================
+// Timing Information
+// ============================================================================
+
+export interface TimingInfo {
+  /** Total request duration */
+  totalDurationMs: number;
+  
+  /** Time to first token (streaming only) */
+  timeToFirstTokenMs?: number;
+  
+  /** Tokens per second (streaming only) */
+  tokensPerSecond?: number;
+  
+  /** Number of retry attempts */
+  attempts: number;
+  
+  /** Delay between retries */
+  retryDelaysMs?: number[];
+}
+
+// ============================================================================
+// Cache Information
+// ============================================================================
+
+export interface CacheInfo {
+  /** Number of cache markers in request */
+  markersInRequest: number;
+  
+  /** Tokens created in cache */
+  tokensCreated: number;
+  
+  /** Tokens read from cache */
+  tokensRead: number;
+  
+  /** Cache hit ratio (0-1) */
+  hitRatio: number;
+}
+
+// ============================================================================
+// Response Details
+// ============================================================================
+
+export interface ResponseDetails {
+  stop: StopInfo;
+  usage: DetailedUsage;
+  timing: TimingInfo;
+  model: ModelInfo;
+  cache: CacheInfo;
+}
+
+// ============================================================================
+// Raw Access
+// ============================================================================
+
+export interface RawAccess {
+  /** Exact request body sent to provider */
+  request: unknown;
+  
+  /** Exact response received from provider */
+  response: unknown;
+  
+  /** Response headers */
+  headers?: Record<string, string>;
+}
+
+// ============================================================================
+// Normalized Response
+// ============================================================================
+
+export interface NormalizedResponse {
+  /** Response content blocks (parsed/structured) */
+  content: ContentBlock[];
+
+  /**
+   * Raw assistant output text including all XML.
+   * Use this for building subsequent turn context (verbatim prefill).
+   */
+  rawAssistantText: string;
+
+  /**
+   * Tool calls extracted from the response.
+   * Convenience accessor - these are also in content as tool_use blocks.
+   */
+  toolCalls: ToolCall[];
+
+  /**
+   * Tool results that were executed during this response.
+   * Empty if no tools were called or tool execution was disabled.
+   */
+  toolResults: ToolResult[];
+
+  /** Why generation stopped */
+  stopReason: StopReason;
+
+  /** Basic usage (always available) */
+  usage: BasicUsage;
+
+  /** Detailed response information */
+  details: ResponseDetails;
+
+  /** Raw request/response for debugging */
+  raw: RawAccess;
+}
+
+// ============================================================================
+// Aborted Response
+// ============================================================================
+
+export interface AbortedResponse {
+  aborted: true;
+
+  /** Content received before abort */
+  partialContent?: ContentBlock[];
+
+  /** Tokens consumed before abort */
+  partialUsage?: BasicUsage;
+
+  /** Why it was aborted */
+  reason: 'user' | 'timeout' | 'error';
+
+  /**
+   * Raw assistant text accumulated before abort.
+   * Use for displaying partial output or as prefill to continue.
+   */
+  rawAssistantText?: string;
+
+  /**
+   * Tool calls that were executed before abort.
+   */
+  toolCalls?: ToolCall[];
+
+  /**
+   * Tool results received before abort.
+   */
+  toolResults?: ToolResult[];
+}
+
+export function isAbortedResponse(
+  response: NormalizedResponse | AbortedResponse
+): response is AbortedResponse {
+  return 'aborted' in response && response.aborted === true;
+}

package/src/types/streaming.ts

@@ -0,0 +1,231 @@
+/**
+ * Streaming types for membrane
+ */
+
+import type { ContentBlock } from './content.js';
+import type { ToolCall, ToolResult, ToolContext } from './tools.js';
+import type { BasicUsage } from './response.js';
+
+// ============================================================================
+// Membrane Block Types (logical content regions, not API types)
+// ============================================================================
+
+/**
+ * Membrane block types - logical content regions at the context level.
+ * These are abstract structures, not tied to any wire format.
+ */
+export type MembraneBlockType = 'text' | 'thinking' | 'tool_call' | 'tool_result';
+
+/**
+ * Membrane block - a logical content region with full content.
+ * Used in block_complete events.
+ */
+export interface MembraneBlock {
+  type: MembraneBlockType;
+  content?: string;           // Full content (for text, thinking, tool_result)
+  toolId?: string;            // For tool_call / tool_result
+  toolName?: string;          // For tool_call
+  input?: Record<string, unknown>;  // For tool_call (parsed parameters)
+  isError?: boolean;          // For tool_result
+}
+
+// ============================================================================
+// Chunk Metadata
+// ============================================================================
+
+/**
+ * Chunk type - alias for MembraneBlockType for clarity in chunk contexts
+ */
+export type ChunkType = MembraneBlockType;
+
+/**
+ * Metadata about a streaming chunk.
+ * Provides context about which block the chunk belongs to and its visibility.
+ */
+export interface ChunkMeta {
+  /** Which membrane block type this chunk belongs to */
+  type: ChunkType;
+
+  /** Convenience flag for TTS/display filtering - false for thinking/tool content */
+  visible: boolean;
+
+  /** Which content block this belongs to (0-indexed) */
+  blockIndex: number;
+
+  /** Tool nesting depth (for nested tool calls) */
+  depth?: number;
+
+  /** For tool_call chunks - which part of the tool call is streaming */
+  toolCallPart?: 'name' | 'id' | 'input';
+
+  /** Tool use ID (for tool_call / tool_result chunks) */
+  toolId?: string;
+
+  /** Tool name (for tool_call chunks, once known) */
+  toolName?: string;
+}
+
+// ============================================================================
+// Block Events
+// ============================================================================
+
+/**
+ * Block start event - signals a new block is starting.
+ * Fired before any onChunk calls for that block.
+ */
+export interface BlockStartEvent {
+  event: 'block_start';
+  index: number;
+  block: { type: MembraneBlockType };
+}
+
+/**
+ * Block complete event - signals a block is done.
+ * Includes full accumulated content. Fired after all onChunk calls for that block.
+ */
+export interface BlockCompleteEvent {
+  event: 'block_complete';
+  index: number;
+  block: MembraneBlock;
+}
+
+/**
+ * Block event - either start or complete.
+ * Note: No block_delta - streaming content is provided via onChunk with metadata.
+ */
+export type BlockEvent = BlockStartEvent | BlockCompleteEvent;
+
+/**
+ * @deprecated Use BlockEvent instead. BlockDelta is no longer used;
+ * streaming content is provided via onChunk with ChunkMeta.
+ */
+export type BlockDelta =
+  | { type: 'text'; text: string }
+  | { type: 'thinking'; thinking: string }
+  | { type: 'tool_input'; partialJson: string };
+
+// ============================================================================
+// Stream State
+// ============================================================================
+
+export interface StreamState {
+  /** Accumulated text output */
+  accumulated: string;
+  
+  /** Current content blocks (updated during stream) */
+  contentBlocks: ContentBlock[];
+  
+  /** Current tool execution depth */
+  toolDepth: number;
+  
+  /** Tool calls executed so far */
+  toolCallsExecuted: ToolCall[];
+  
+  /** Tokens generated so far (estimate) */
+  tokensGenerated: number;
+  
+  /** Abort function */
+  abort: () => void;
+}
+
+// ============================================================================
+// Stream Callbacks
+// ============================================================================
+
+/**
+ * Callback for text chunks - called immediately as tokens arrive.
+ * Includes metadata about block type, visibility, and position.
+ */
+export type OnChunkCallback = (chunk: string, meta: ChunkMeta) => void;
+
+/**
+ * @deprecated Use onBlock + onChunk with ChunkMeta instead.
+ * This callback is superseded by:
+ * - onBlock for structured block_start/block_complete events
+ * - onChunk with ChunkMeta for streaming content with block context
+ */
+export type OnContentBlockCallback = (index: number, block: ContentBlock) => void;
+
+/**
+ * Callback for tool execution
+ * Return tool results to continue; throw to abort
+ */
+export type OnToolCallsCallback = (
+  calls: ToolCall[],
+  context: ToolContext
+) => Promise<ToolResult[]>;
+
+/**
+ * Callback for pre-tool content notification
+ * Called with content that appeared before tool calls
+ */
+export type OnPreToolContentCallback = (content: string) => Promise<void> | void;
+
+/**
+ * Callback for usage updates during streaming
+ */
+export type OnUsageCallback = (usage: BasicUsage) => void;
+
+/**
+ * Callback for structured block events during streaming.
+ * Provides parsed block information as it's detected.
+ */
+export type OnBlockCallback = (event: BlockEvent) => void;
+
+// ============================================================================
+// Stream Options
+// ============================================================================
+
+export interface StreamOptions {
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+  
+  /** Request timeout */
+  timeoutMs?: number;
+  
+  /** Request ID for correlation */
+  requestId?: string;
+  
+  // ---- Callbacks ----
+  
+  /** Called immediately for each text chunk */
+  onChunk?: OnChunkCallback;
+  
+  /** Called when content blocks update (thinking, images) */
+  onContentBlockUpdate?: OnContentBlockCallback;
+  
+  /** Called when tool calls are detected; return results to continue */
+  onToolCalls?: OnToolCallsCallback;
+  
+  /** Called with content before tool calls (for UI preview) */
+  onPreToolContent?: OnPreToolContentCallback;
+  
+  /** Called with usage updates */
+  onUsage?: OnUsageCallback;
+
+  /** Called for structured block events (thinking, tool_use, tool_result) */
+  onBlock?: OnBlockCallback;
+
+  // ---- Tool Loop Config ----
+
+  /** Maximum tool execution depth (default: 10) */
+  maxToolDepth?: number;
+
+  /** Timeout for each tool execution */
+  toolTimeoutMs?: number;
+}
+
+// ============================================================================
+// Non-Streaming Options
+// ============================================================================
+
+export interface CompleteOptions {
+  /** Abort signal for cancellation */
+  signal?: AbortSignal;
+  
+  /** Request timeout */
+  timeoutMs?: number;
+  
+  /** Request ID for correlation */
+  requestId?: string;
+}

package/src/types/tools.ts

@@ -0,0 +1,92 @@
+/**
+ * Tool definition and execution types
+ */
+
+// ============================================================================
+// Tool Definition
+// ============================================================================
+
+export interface ToolParameter {
+  type: string;
+  description?: string;
+  enum?: string[];
+  items?: ToolParameter;
+  properties?: Record<string, ToolParameter>;
+  required?: string[];
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, ToolParameter>;
+    required?: string[];
+  };
+}
+
+// ============================================================================
+// Tool Execution
+// ============================================================================
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  input: Record<string, unknown>;
+}
+
+export interface ToolResult {
+  toolUseId: string;
+  /**
+   * Result content - can be string or structured content blocks (for images).
+   * For XML mode, images are noted in text. For native mode, passed as content blocks.
+   */
+  content: string | ToolResultContentBlock[];
+  isError?: boolean;
+}
+
+/**
+ * Content block types allowed in tool results
+ */
+export type ToolResultContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'image'; source: { type: 'base64'; data: string; mediaType: string } };
+
+// ============================================================================
+// Tool Context (passed to execution callback)
+// ============================================================================
+
+export interface ToolContext {
+  /** The raw text that contained the tool calls */
+  rawText: string;
+  
+  /** Text before the tool calls (already streamed to user) */
+  preamble: string;
+  
+  /** Current depth in tool execution loop */
+  depth: number;
+  
+  /** Previous tool results in this execution chain */
+  previousResults: ToolResult[];
+  
+  /** Accumulated output so far */
+  accumulated: string;
+}
+
+// ============================================================================
+// Tool Parsing
+// ============================================================================
+
+export interface ParsedToolCalls {
+  /** Parsed tool calls */
+  calls: ToolCall[];
+  
+  /** Text before the tool calls block */
+  beforeText: string;
+  
+  /** Text after the tool calls block */
+  afterText: string;
+  
+  /** The full matched tool calls XML block */
+  fullMatch: string;
+}

package/src/utils/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Utility exports
+ */
+
+export {
+  parseToolCalls,
+  formatToolResults,
+  formatToolResult,
+  formatToolDefinitions,
+  getToolInstructions,
+  hasUnclosedToolBlock,
+  endsWithPartialToolBlock,
+  unescapeXml,
+  type ToolDefinitionForPrompt,
+} from './tool-parser.js';