@teamlearners/clawops 0.5.3 → 0.5.5

package/dist/agent/index.d.cts

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { Logger } from 'pino';
+export { Logger } from 'pino';
 
 /**
  * Tool registry for function-calling in voice agent pipelines.
@@ -74,6 +76,8 @@ interface MCPServerConfig {
 declare class MCPClient {
     private _servers;
     private _clients;
+    private _log;
+    setLogger(logger: Logger): void;
     /** Add an MCP server configuration. */
     addServer(name: string, config: MCPServerConfig & Record<string, unknown>): void;
     /** Connect to all configured MCP servers and discover tools. */
@@ -128,6 +132,7 @@ declare function mcpServerHTTP(options: {
  * CallSession represents an active phone call and provides methods to
  * send audio, hang up, and listen for lifecycle events.
  */
+
 type CallDirection = 'inbound' | 'outbound';
 type CallStatus = 'ringing' | 'active' | 'ended';
 /**
@@ -164,6 +169,7 @@ declare class CallSession {
     private _dtmfCollectorActive;
     private _dtmfResolvers;
     private _dtmfBuffer;
+    private _log;
     private _handlers;
     private _endedPromise;
     private _resolveEnded;
@@ -175,6 +181,7 @@ declare class CallSession {
         direction: CallDirection;
         metadata?: Record<string, unknown>;
     });
+    setLogger(logger: Logger): void;
     get status(): CallStatus;
     get duration(): number;
     /** Bind transport functions (called internally by the agent). */
@@ -263,6 +270,8 @@ interface Session {
     feedDtmf?(digits: string): Promise<void>;
     /** Stop the session. */
     stop(): Promise<void>;
+    /** Set the logger instance for this session. */
+    setLogger?(logger: Logger): void;
 }
 /**
  * Speech-to-Text provider interface.
@@ -355,6 +364,8 @@ interface ClawOpsAgentOptions {
     builtinTools?: BuiltinTool | BuiltinTool[];
     /** Debounce time (ms) for passive DTMF accumulation. Default: 500 */
     passiveDtmfDebounceMs?: number;
+    /** Custom pino logger instance. If omitted, a default logger is created. */
+    logger?: Logger;
 }
 declare class ClawOpsAgent {
     private _apiKey;
@@ -375,6 +386,9 @@ declare class ClawOpsAgent {
     private _passiveDtmfTimer;
     private _passiveDtmfCallId;
     private _callSessions;
+    private _log;
+    private _pipelineLog;
+    private _isPipelineSession;
     constructor(options: ClawOpsAgentOptions);
     /**
      * Register a function tool.
@@ -444,6 +458,8 @@ declare class AudioRecorder {
     private _mixWritten;
     private _startTime;
     private _started;
+    private _log;
+    setLogger(logger: Logger): void;
     constructor(recordingPath: string, callId: string);
     start(): void;
     private _expectedBytes;
@@ -484,7 +500,9 @@ declare class OpenAIRealtime implements Session {
     private _language;
     private _eagerness;
     private _greeting;
+    private _log;
     private _builtinTools;
+    setLogger(logger: Logger): void;
     setBuiltinTools(tools: Set<BuiltinTool>): void;
     private _ws;
     private _call;
@@ -552,12 +570,14 @@ declare class GeminiRealtime implements Session {
     private _audioRemainder;
     private _builtinTools;
     private _toolCallInProgress;
+    private _log;
     constructor(options?: GeminiRealtimeOptions);
     /** Inject per-call ToolRegistry. */
     setToolRegistry(registry: ToolRegistry): void;
     /** Inject per-call AudioRecorder. */
     setRecorder(recorder: AudioRecorder): void;
     setBuiltinTools(tools: Set<BuiltinTool>): void;
+    setLogger(logger: Logger): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
     feedDtmf(digits: string): Promise<void>;
@@ -615,10 +635,12 @@ declare class PipelineSession implements Session {
     private _running;
     private _speaking;
     private _builtinTools;
+    private _log;
     constructor(options: PipelineSessionOptions);
     setToolRegistry(registry: ToolRegistry): void;
     setRecorder(recorder: AudioRecorder): void;
     setBuiltinTools(tools: Set<BuiltinTool>): void;
+    setLogger(logger: Logger): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
     feedDtmf(digits: string): Promise<void>;
@@ -659,6 +681,8 @@ interface DeepgramSTTOptions {
 }
 declare class DeepgramSTT implements STT {
     private _options;
+    private _log;
+    setLogger(logger: Logger): void;
     constructor(options?: DeepgramSTTOptions);
     transcribe(audioStream: AsyncIterable<Buffer>, options?: {
         language?: string;
@@ -688,6 +712,8 @@ interface ElevenLabsTTSOptions {
 }
 declare class ElevenLabsTTS implements TTS {
     private _options;
+    private _log;
+    setLogger(logger: Logger): void;
     constructor(options?: ElevenLabsTTSOptions);
     synthesize(text: string | AsyncIterable<string>, options?: {
         voice?: string;
@@ -934,4 +960,23 @@ declare class XaiLLM implements LLM {
     }): AsyncGenerator<LLMChunk>;
 }
 
-export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, ElevenLabsTTS, type ElevenLabsTTSOptions, FireworksLLM, type FireworksLLMOptions, type FunctionTool, GeminiLLM, type GeminiLLMOptions, GeminiRealtime, type GeminiRealtimeOptions, GroqLLM, type GroqLLMOptions, type LLM, type LLMChunk, MCPClient, type MCPServerConfig, type MCPServerHTTP, type MCPServerStdio, MistralLLM, type MistralLLMOptions, OllamaLLM, type OllamaLLMOptions, OpenAICompatLLM, type OpenAICompatLLMOptions, OpenAILLM, type OpenAILLMOptions, OpenAIRealtime, type OpenAIRealtimeOptions, type OpenAIToolDefinition, PerplexityLLM, type PerplexityLLMOptions, PipelineSession, type PipelineSessionOptions, type STT, type Session, type SpeechEvent, type TTS, TogetherLLM, type TogetherLLMOptions, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, functionTool, getTracingConfig, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };
+/**
+ * Logger factory for the ClawOps agent module.
+ *
+ * Provides a 2-level hierarchy matching the Python SDK:
+ * - clawops.agent        (core: agent, session, control-ws, media-ws, recorder, mcp, realtime)
+ * - clawops.agent.pipeline (pipeline: pipeline-session, stt, tts)
+ */
+
+/**
+ * Create or return an agent-level logger.
+ * If no user logger is provided, returns the default pino instance.
+ */
+declare function createAgentLogger(userLogger?: Logger): Logger;
+/**
+ * Create a pipeline child logger from a parent agent logger.
+ * Adds `{ module: 'pipeline' }` to all log entries.
+ */
+declare function createPipelineLogger(parent: Logger): Logger;
+
+export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, ElevenLabsTTS, type ElevenLabsTTSOptions, FireworksLLM, type FireworksLLMOptions, type FunctionTool, GeminiLLM, type GeminiLLMOptions, GeminiRealtime, type GeminiRealtimeOptions, GroqLLM, type GroqLLMOptions, type LLM, type LLMChunk, MCPClient, type MCPServerConfig, type MCPServerHTTP, type MCPServerStdio, MistralLLM, type MistralLLMOptions, OllamaLLM, type OllamaLLMOptions, OpenAICompatLLM, type OpenAICompatLLMOptions, OpenAILLM, type OpenAILLMOptions, OpenAIRealtime, type OpenAIRealtimeOptions, type OpenAIToolDefinition, PerplexityLLM, type PerplexityLLMOptions, PipelineSession, type PipelineSessionOptions, type STT, type Session, type SpeechEvent, type TTS, TogetherLLM, type TogetherLLMOptions, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, createAgentLogger, createPipelineLogger, functionTool, getTracingConfig, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };

package/dist/agent/index.d.ts

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { Logger } from 'pino';
+export { Logger } from 'pino';
 
 /**
  * Tool registry for function-calling in voice agent pipelines.
@@ -74,6 +76,8 @@ interface MCPServerConfig {
 declare class MCPClient {
     private _servers;
     private _clients;
+    private _log;
+    setLogger(logger: Logger): void;
     /** Add an MCP server configuration. */
     addServer(name: string, config: MCPServerConfig & Record<string, unknown>): void;
     /** Connect to all configured MCP servers and discover tools. */
@@ -128,6 +132,7 @@ declare function mcpServerHTTP(options: {
  * CallSession represents an active phone call and provides methods to
  * send audio, hang up, and listen for lifecycle events.
  */
+
 type CallDirection = 'inbound' | 'outbound';
 type CallStatus = 'ringing' | 'active' | 'ended';
 /**
@@ -164,6 +169,7 @@ declare class CallSession {
     private _dtmfCollectorActive;
     private _dtmfResolvers;
     private _dtmfBuffer;
+    private _log;
     private _handlers;
     private _endedPromise;
     private _resolveEnded;
@@ -175,6 +181,7 @@ declare class CallSession {
         direction: CallDirection;
         metadata?: Record<string, unknown>;
     });
+    setLogger(logger: Logger): void;
     get status(): CallStatus;
     get duration(): number;
     /** Bind transport functions (called internally by the agent). */
@@ -263,6 +270,8 @@ interface Session {
     feedDtmf?(digits: string): Promise<void>;
     /** Stop the session. */
     stop(): Promise<void>;
+    /** Set the logger instance for this session. */
+    setLogger?(logger: Logger): void;
 }
 /**
  * Speech-to-Text provider interface.
@@ -355,6 +364,8 @@ interface ClawOpsAgentOptions {
     builtinTools?: BuiltinTool | BuiltinTool[];
     /** Debounce time (ms) for passive DTMF accumulation. Default: 500 */
     passiveDtmfDebounceMs?: number;
+    /** Custom pino logger instance. If omitted, a default logger is created. */
+    logger?: Logger;
 }
 declare class ClawOpsAgent {
     private _apiKey;
@@ -375,6 +386,9 @@ declare class ClawOpsAgent {
     private _passiveDtmfTimer;
     private _passiveDtmfCallId;
     private _callSessions;
+    private _log;
+    private _pipelineLog;
+    private _isPipelineSession;
     constructor(options: ClawOpsAgentOptions);
     /**
      * Register a function tool.
@@ -444,6 +458,8 @@ declare class AudioRecorder {
     private _mixWritten;
     private _startTime;
     private _started;
+    private _log;
+    setLogger(logger: Logger): void;
     constructor(recordingPath: string, callId: string);
     start(): void;
     private _expectedBytes;
@@ -484,7 +500,9 @@ declare class OpenAIRealtime implements Session {
     private _language;
     private _eagerness;
     private _greeting;
+    private _log;
     private _builtinTools;
+    setLogger(logger: Logger): void;
     setBuiltinTools(tools: Set<BuiltinTool>): void;
     private _ws;
     private _call;
@@ -552,12 +570,14 @@ declare class GeminiRealtime implements Session {
     private _audioRemainder;
     private _builtinTools;
     private _toolCallInProgress;
+    private _log;
     constructor(options?: GeminiRealtimeOptions);
     /** Inject per-call ToolRegistry. */
     setToolRegistry(registry: ToolRegistry): void;
     /** Inject per-call AudioRecorder. */
     setRecorder(recorder: AudioRecorder): void;
     setBuiltinTools(tools: Set<BuiltinTool>): void;
+    setLogger(logger: Logger): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
     feedDtmf(digits: string): Promise<void>;
@@ -615,10 +635,12 @@ declare class PipelineSession implements Session {
     private _running;
     private _speaking;
     private _builtinTools;
+    private _log;
     constructor(options: PipelineSessionOptions);
     setToolRegistry(registry: ToolRegistry): void;
     setRecorder(recorder: AudioRecorder): void;
     setBuiltinTools(tools: Set<BuiltinTool>): void;
+    setLogger(logger: Logger): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
     feedDtmf(digits: string): Promise<void>;
@@ -659,6 +681,8 @@ interface DeepgramSTTOptions {
 }
 declare class DeepgramSTT implements STT {
     private _options;
+    private _log;
+    setLogger(logger: Logger): void;
     constructor(options?: DeepgramSTTOptions);
     transcribe(audioStream: AsyncIterable<Buffer>, options?: {
         language?: string;
@@ -688,6 +712,8 @@ interface ElevenLabsTTSOptions {
 }
 declare class ElevenLabsTTS implements TTS {
     private _options;
+    private _log;
+    setLogger(logger: Logger): void;
     constructor(options?: ElevenLabsTTSOptions);
     synthesize(text: string | AsyncIterable<string>, options?: {
         voice?: string;
@@ -934,4 +960,23 @@ declare class XaiLLM implements LLM {
     }): AsyncGenerator<LLMChunk>;
 }
 
-export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, ElevenLabsTTS, type ElevenLabsTTSOptions, FireworksLLM, type FireworksLLMOptions, type FunctionTool, GeminiLLM, type GeminiLLMOptions, GeminiRealtime, type GeminiRealtimeOptions, GroqLLM, type GroqLLMOptions, type LLM, type LLMChunk, MCPClient, type MCPServerConfig, type MCPServerHTTP, type MCPServerStdio, MistralLLM, type MistralLLMOptions, OllamaLLM, type OllamaLLMOptions, OpenAICompatLLM, type OpenAICompatLLMOptions, OpenAILLM, type OpenAILLMOptions, OpenAIRealtime, type OpenAIRealtimeOptions, type OpenAIToolDefinition, PerplexityLLM, type PerplexityLLMOptions, PipelineSession, type PipelineSessionOptions, type STT, type Session, type SpeechEvent, type TTS, TogetherLLM, type TogetherLLMOptions, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, functionTool, getTracingConfig, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };
+/**
+ * Logger factory for the ClawOps agent module.
+ *
+ * Provides a 2-level hierarchy matching the Python SDK:
+ * - clawops.agent        (core: agent, session, control-ws, media-ws, recorder, mcp, realtime)
+ * - clawops.agent.pipeline (pipeline: pipeline-session, stt, tts)
+ */
+
+/**
+ * Create or return an agent-level logger.
+ * If no user logger is provided, returns the default pino instance.
+ */
+declare function createAgentLogger(userLogger?: Logger): Logger;
+/**
+ * Create a pipeline child logger from a parent agent logger.
+ * Adds `{ module: 'pipeline' }` to all log entries.
+ */
+declare function createPipelineLogger(parent: Logger): Logger;
+
+export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, ElevenLabsTTS, type ElevenLabsTTSOptions, FireworksLLM, type FireworksLLMOptions, type FunctionTool, GeminiLLM, type GeminiLLMOptions, GeminiRealtime, type GeminiRealtimeOptions, GroqLLM, type GroqLLMOptions, type LLM, type LLMChunk, MCPClient, type MCPServerConfig, type MCPServerHTTP, type MCPServerStdio, MistralLLM, type MistralLLMOptions, OllamaLLM, type OllamaLLMOptions, OpenAICompatLLM, type OpenAICompatLLMOptions, OpenAILLM, type OpenAILLMOptions, OpenAIRealtime, type OpenAIRealtimeOptions, type OpenAIToolDefinition, PerplexityLLM, type PerplexityLLMOptions, PipelineSession, type PipelineSessionOptions, type STT, type Session, type SpeechEvent, type TTS, TogetherLLM, type TogetherLLMOptions, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, createAgentLogger, createPipelineLogger, functionTool, getTracingConfig, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };