@teamlearners/clawops 0.5.1 → 0.5.4

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';
 /**
@@ -142,7 +147,10 @@ interface ClearAudioFn {
     (): void;
 }
 interface HangupFn {
-    (): void;
+    (): void | Promise<void>;
+}
+interface SendDtmfFn {
+    (digit: string): Promise<void>;
 }
 declare class CallSession {
     readonly callId: string;
@@ -156,6 +164,12 @@ declare class CallSession {
     private _sendAudioFn;
     private _clearAudioFn;
     private _hangupFn;
+    /** @internal */ _sendDtmfFn: SendDtmfFn | null;
+    /** @internal */ _isTransportConnected: (() => boolean) | null;
+    private _dtmfCollectorActive;
+    private _dtmfResolvers;
+    private _dtmfBuffer;
+    private _log;
     private _handlers;
     private _endedPromise;
     private _resolveEnded;
@@ -167,16 +181,28 @@ 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). */
-    _bindTransport(send: SendAudioFn, clear: ClearAudioFn, hangup: HangupFn): void;
+    _bindTransport(send: SendAudioFn, clear: ClearAudioFn, hangup: HangupFn, sendDtmf?: SendDtmfFn, isConnected?: () => boolean): void;
     /** Send PCM16 or ulaw audio to the caller. */
     sendAudio(audio: Buffer): void;
     /** Clear any queued outbound audio. */
     clearAudio(): void;
-    /** Hang up the call. */
-    hangup(): void;
+    /** Hang up the call, waiting for pending audio to finish. */
+    hangup(): Promise<void>;
+    /** @internal Route a received DTMF digit to an active collector or buffer. */
+    _routeDtmf(digit: string): void;
+    /** Collect DTMF digits from the caller. */
+    collectDtmf(options: {
+        maxDigits: number;
+        finishOnKey?: string;
+        timeout?: number;
+        secure?: boolean;
+    }): Promise<string>;
+    /** Send a sequence of DTMF digits. */
+    sendDtmfSequence(digits: string): Promise<void>;
     /** Register an event handler. */
     on(event: string, handler: SessionEventHandler): void;
     /** Wait for the call to end. */
@@ -187,6 +213,22 @@ declare class CallSession {
     _emit(event: string, ...args: any[]): void;
 }
 
+/**
+ * Built-in tool definitions and selection constants.
+ */
+declare enum BuiltinTool {
+    /** 전화 종료 도구. AI가 대화 완료 시 통화를 종료합니다. */
+    HANG_UP = "hang_up",
+    /** DTMF 수집 도구. 사용자의 키패드 입력을 수집합니다. */
+    COLLECT_DTMF = "collect_dtmf",
+    /** DTMF 전송 도구. ARS 탐색이나 내선번호 입력에 사용합니다. */
+    SEND_DTMF = "send_dtmf",
+    /** 모든 내장 도구를 활성화합니다. (기본값) */
+    ALL = "all",
+    /** 모든 내장 도구를 비활성화합니다. */
+    NONE = "none"
+}
+
 /**
  * Base interfaces for the voice agent pipeline.
  */
@@ -224,8 +266,12 @@ interface Session {
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     /** Feed raw audio into the session. */
     feedAudio(audio: Buffer): void;
+    /** Feed DTMF digits into the LLM context and trigger a response. */
+    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.
@@ -293,7 +339,7 @@ declare function resetTracingConfig(): void;
  * ClawOpsAgent - main agent class for handling voice calls.
  */
 
-type AgentEventType = 'call_start' | 'call_end' | 'call_failed' | 'transcript';
+type AgentEventType = 'call_start' | 'call_end' | 'call_failed' | 'transcript' | 'dtmf';
 type AgentEventHandler = (...args: any[]) => void | Promise<void>;
 interface ClawOpsAgentOptions {
     /** ClawOps API key. Falls back to CLAWOPS_API_KEY env var. */
@@ -314,6 +360,12 @@ interface ClawOpsAgentOptions {
     mcpServers?: Array<MCPServerStdio | MCPServerHTTP>;
     /** Tracing configuration. */
     tracing?: TracingConfig;
+    /** 활성화할 내장 도구. Default: BuiltinTool.ALL */
+    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;
@@ -328,6 +380,15 @@ declare class ClawOpsAgent {
     private _recording;
     private _recordingPath;
     private _activeSessions;
+    private _builtinTools;
+    private _passiveDtmfDebounceMs;
+    private _passiveDtmfBuffer;
+    private _passiveDtmfTimer;
+    private _passiveDtmfCallId;
+    private _callSessions;
+    private _log;
+    private _pipelineLog;
+    private _isPipelineSession;
     constructor(options: ClawOpsAgentOptions);
     /**
      * Register a function tool.
@@ -366,6 +427,7 @@ declare class ClawOpsAgent {
     private _handleOutboundReady;
     private _handleRinging;
     private _handleFailed;
+    private _onDtmfEvent;
     private _startCallSession;
 }
 
@@ -396,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;
@@ -436,6 +500,10 @@ 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;
     private _tools;
@@ -445,12 +513,15 @@ declare class OpenAIRealtime implements Session {
     private _responseStartTs;
     private _sentAudioChunks;
     private _audioRemainder;
+    private _responseInProgress;
+    private _onResponseDone;
     constructor(options?: OpenAIRealtimeOptions);
     /** Inject per-call ToolRegistry. */
     setToolRegistry(registry: ToolRegistry): void;
     /** Inject per-call AudioRecorder. */
     setRecorder(recorder: AudioRecorder): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
+    feedDtmf(digits: string): Promise<void>;
     feedAudio(audio: Buffer): void;
     stop(): Promise<void>;
     private _sendSessionUpdate;
@@ -458,6 +529,7 @@ declare class OpenAIRealtime implements Session {
     private _handleAudioDelta;
     private _handleTruncation;
     private _handleToolCall;
+    private _waitForResponseDone;
     private _send;
 }
 
@@ -496,13 +568,19 @@ declare class GeminiRealtime implements Session {
     private _closed;
     private _sentAudioChunks;
     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>;
     stop(): Promise<void>;
     private _buildToolSchemas;
     private _handleMessage;
@@ -556,16 +634,22 @@ declare class PipelineSession implements Session {
     private _audioBuffer;
     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>;
     stop(): Promise<void>;
     private _runSttLoop;
     private _createAudioStream;
     private _generateGreeting;
     private _handleUserSpeech;
+    private _buildEffectiveTools;
     private _respond;
     private _handleToolCall;
     private _synthesizeAndSend;
@@ -597,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;
@@ -626,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;
@@ -872,4 +960,23 @@ declare class XaiLLM implements LLM {
     }): AsyncGenerator<LLMChunk>;
 }
 
-export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, 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';
 /**
@@ -142,7 +147,10 @@ interface ClearAudioFn {
     (): void;
 }
 interface HangupFn {
-    (): void;
+    (): void | Promise<void>;
+}
+interface SendDtmfFn {
+    (digit: string): Promise<void>;
 }
 declare class CallSession {
     readonly callId: string;
@@ -156,6 +164,12 @@ declare class CallSession {
     private _sendAudioFn;
     private _clearAudioFn;
     private _hangupFn;
+    /** @internal */ _sendDtmfFn: SendDtmfFn | null;
+    /** @internal */ _isTransportConnected: (() => boolean) | null;
+    private _dtmfCollectorActive;
+    private _dtmfResolvers;
+    private _dtmfBuffer;
+    private _log;
     private _handlers;
     private _endedPromise;
     private _resolveEnded;
@@ -167,16 +181,28 @@ 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). */
-    _bindTransport(send: SendAudioFn, clear: ClearAudioFn, hangup: HangupFn): void;
+    _bindTransport(send: SendAudioFn, clear: ClearAudioFn, hangup: HangupFn, sendDtmf?: SendDtmfFn, isConnected?: () => boolean): void;
     /** Send PCM16 or ulaw audio to the caller. */
     sendAudio(audio: Buffer): void;
     /** Clear any queued outbound audio. */
     clearAudio(): void;
-    /** Hang up the call. */
-    hangup(): void;
+    /** Hang up the call, waiting for pending audio to finish. */
+    hangup(): Promise<void>;
+    /** @internal Route a received DTMF digit to an active collector or buffer. */
+    _routeDtmf(digit: string): void;
+    /** Collect DTMF digits from the caller. */
+    collectDtmf(options: {
+        maxDigits: number;
+        finishOnKey?: string;
+        timeout?: number;
+        secure?: boolean;
+    }): Promise<string>;
+    /** Send a sequence of DTMF digits. */
+    sendDtmfSequence(digits: string): Promise<void>;
     /** Register an event handler. */
     on(event: string, handler: SessionEventHandler): void;
     /** Wait for the call to end. */
@@ -187,6 +213,22 @@ declare class CallSession {
     _emit(event: string, ...args: any[]): void;
 }
 
+/**
+ * Built-in tool definitions and selection constants.
+ */
+declare enum BuiltinTool {
+    /** 전화 종료 도구. AI가 대화 완료 시 통화를 종료합니다. */
+    HANG_UP = "hang_up",
+    /** DTMF 수집 도구. 사용자의 키패드 입력을 수집합니다. */
+    COLLECT_DTMF = "collect_dtmf",
+    /** DTMF 전송 도구. ARS 탐색이나 내선번호 입력에 사용합니다. */
+    SEND_DTMF = "send_dtmf",
+    /** 모든 내장 도구를 활성화합니다. (기본값) */
+    ALL = "all",
+    /** 모든 내장 도구를 비활성화합니다. */
+    NONE = "none"
+}
+
 /**
  * Base interfaces for the voice agent pipeline.
  */
@@ -224,8 +266,12 @@ interface Session {
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     /** Feed raw audio into the session. */
     feedAudio(audio: Buffer): void;
+    /** Feed DTMF digits into the LLM context and trigger a response. */
+    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.
@@ -293,7 +339,7 @@ declare function resetTracingConfig(): void;
  * ClawOpsAgent - main agent class for handling voice calls.
  */
 
-type AgentEventType = 'call_start' | 'call_end' | 'call_failed' | 'transcript';
+type AgentEventType = 'call_start' | 'call_end' | 'call_failed' | 'transcript' | 'dtmf';
 type AgentEventHandler = (...args: any[]) => void | Promise<void>;
 interface ClawOpsAgentOptions {
     /** ClawOps API key. Falls back to CLAWOPS_API_KEY env var. */
@@ -314,6 +360,12 @@ interface ClawOpsAgentOptions {
     mcpServers?: Array<MCPServerStdio | MCPServerHTTP>;
     /** Tracing configuration. */
     tracing?: TracingConfig;
+    /** 활성화할 내장 도구. Default: BuiltinTool.ALL */
+    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;
@@ -328,6 +380,15 @@ declare class ClawOpsAgent {
     private _recording;
     private _recordingPath;
     private _activeSessions;
+    private _builtinTools;
+    private _passiveDtmfDebounceMs;
+    private _passiveDtmfBuffer;
+    private _passiveDtmfTimer;
+    private _passiveDtmfCallId;
+    private _callSessions;
+    private _log;
+    private _pipelineLog;
+    private _isPipelineSession;
     constructor(options: ClawOpsAgentOptions);
     /**
      * Register a function tool.
@@ -366,6 +427,7 @@ declare class ClawOpsAgent {
     private _handleOutboundReady;
     private _handleRinging;
     private _handleFailed;
+    private _onDtmfEvent;
     private _startCallSession;
 }
 
@@ -396,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;
@@ -436,6 +500,10 @@ 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;
     private _tools;
@@ -445,12 +513,15 @@ declare class OpenAIRealtime implements Session {
     private _responseStartTs;
     private _sentAudioChunks;
     private _audioRemainder;
+    private _responseInProgress;
+    private _onResponseDone;
     constructor(options?: OpenAIRealtimeOptions);
     /** Inject per-call ToolRegistry. */
     setToolRegistry(registry: ToolRegistry): void;
     /** Inject per-call AudioRecorder. */
     setRecorder(recorder: AudioRecorder): void;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
+    feedDtmf(digits: string): Promise<void>;
     feedAudio(audio: Buffer): void;
     stop(): Promise<void>;
     private _sendSessionUpdate;
@@ -458,6 +529,7 @@ declare class OpenAIRealtime implements Session {
     private _handleAudioDelta;
     private _handleTruncation;
     private _handleToolCall;
+    private _waitForResponseDone;
     private _send;
 }
 
@@ -496,13 +568,19 @@ declare class GeminiRealtime implements Session {
     private _closed;
     private _sentAudioChunks;
     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>;
     stop(): Promise<void>;
     private _buildToolSchemas;
     private _handleMessage;
@@ -556,16 +634,22 @@ declare class PipelineSession implements Session {
     private _audioBuffer;
     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>;
     stop(): Promise<void>;
     private _runSttLoop;
     private _createAudioStream;
     private _generateGreeting;
     private _handleUserSpeech;
+    private _buildEffectiveTools;
     private _respond;
     private _handleToolCall;
     private _synthesizeAndSend;
@@ -597,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;
@@ -626,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;
@@ -872,4 +960,23 @@ declare class XaiLLM implements LLM {
     }): AsyncGenerator<LLMChunk>;
 }
 
-export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, 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 };