@teamlearners/clawops 0.5.5 → 0.6.0

package/dist/agent/index.d.cts

@@ -128,6 +128,36 @@ declare function mcpServerHTTP(options: {
     headers?: Record<string, string>;
 }): MCPServerHTTP;
 
+interface ProviderInfo {
+    provider: string;
+    model: string;
+}
+interface SessionTelemetry {
+    sessionType: string;
+    llm: ProviderInfo | null;
+    stt: ProviderInfo | null;
+    tts: ProviderInfo | null;
+    voice: string | null;
+    language: string;
+    greetingEnabled: boolean;
+    recordingEnabled: boolean;
+    toolCount: number;
+    mcpServerCount: number;
+    builtinTools: string[];
+}
+interface CallMetrics {
+    firstResponseMs: number | null;
+    turnCount: number;
+    toolCallCount: number;
+    toolErrorCount: number;
+    bargeInCount: number;
+    endReason: string | null;
+    errors: Array<{
+        type: string;
+        message: string;
+    }>;
+}
+
 /**
  * CallSession represents an active phone call and provides methods to
  * send audio, hang up, and listen for lifecycle events.
@@ -173,6 +203,8 @@ declare class CallSession {
     private _handlers;
     private _endedPromise;
     private _resolveEnded;
+    private _metrics;
+    private _firstResponseSent;
     constructor(options: {
         callId: string;
         fromNumber: string;
@@ -184,6 +216,13 @@ declare class CallSession {
     setLogger(logger: Logger): void;
     get status(): CallStatus;
     get duration(): number;
+    get metrics(): Readonly<CallMetrics>;
+    recordFirstResponse(): void;
+    recordTurn(): void;
+    recordToolCall(): void;
+    recordToolError(err: Error): void;
+    recordBargeIn(): void;
+    recordEndReason(reason: string): void;
     /** Bind transport functions (called internally by the agent). */
     _bindTransport(send: SendAudioFn, clear: ClearAudioFn, hangup: HangupFn, sendDtmf?: SendDtmfFn, isConnected?: () => boolean): void;
     /** Send PCM16 or ulaw audio to the caller. */
@@ -272,6 +311,8 @@ interface Session {
     stop(): Promise<void>;
     /** Set the logger instance for this session. */
     setLogger?(logger: Logger): void;
+    /** Return session telemetry for reporting. */
+    getTelemetry?(): SessionTelemetry | null;
 }
 /**
  * Speech-to-Text provider interface.
@@ -470,6 +511,73 @@ declare class AudioRecorder {
     stop(): void;
 }
 
+/**
+ * PipelineSession orchestrates STT -> LLM -> TTS for a voice call.
+ */
+
+interface PipelineSessionOptions {
+    stt: STT;
+    llm: LLM;
+    tts: TTS;
+    /** System prompt for the LLM. */
+    systemPrompt?: string;
+    /** Send initial greeting. Default: true */
+    greeting?: boolean;
+    /** Language code. Default: 'ko' */
+    language?: string;
+    /** Tool registry for function calling. */
+    toolRegistry?: ToolRegistry;
+    /** Audio recorder for the session. */
+    recorder?: AudioRecorder;
+    /** LLM temperature. */
+    temperature?: number;
+    /** Max tokens for LLM generation. */
+    maxTokens?: number;
+    /** Sample rate for audio. Default: 8000 */
+    sampleRate?: number;
+    /** Whether to interrupt TTS when user starts speaking. Default: true */
+    interruptOnSpeech?: boolean;
+}
+declare class PipelineSession implements Session {
+    private _stt;
+    private _llm;
+    private _tts;
+    private _systemPrompt;
+    private _greeting;
+    private _language;
+    private _temperature;
+    private _maxTokens;
+    private _sampleRate;
+    private _interruptOnSpeech;
+    private _callSession;
+    private _tools;
+    private _recorder;
+    private _conversation;
+    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;
+    getTelemetry(): SessionTelemetry;
+    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;
+}
+
 /**
  * OpenAI Realtime API session (speech-to-speech).
  *
@@ -487,8 +595,13 @@ interface OpenAIRealtimeOptions {
     voice?: string;
     /** Language code (BCP 47). Default: 'ko' */
     language?: string;
-    /** VAD eagerness: 'low', 'medium', 'high'. Default: 'high' */
-    eagerness?: string;
+    /**
+     * Turn detection configuration. Default: semantic_vad with eagerness 'medium'.
+     * - `{ type: 'semantic_vad', eagerness?: 'low'|'medium'|'high'|'auto', interrupt_response?: boolean }`
+     * - `{ type: 'server_vad', threshold?: number, silence_duration_ms?: number, prefix_padding_ms?: number }`
+     * - `null` to disable turn detection
+     */
+    turnDetection?: Record<string, unknown> | null;
     /** Send initial greeting. Default: true */
     greeting?: boolean;
 }
@@ -498,21 +611,21 @@ declare class OpenAIRealtime implements Session {
     private _model;
     private _voice;
     private _language;
-    private _eagerness;
+    private _turnDetection;
     private _greeting;
     private _log;
     private _builtinTools;
     setLogger(logger: Logger): void;
     setBuiltinTools(tools: Set<BuiltinTool>): void;
+    getTelemetry(): SessionTelemetry;
     private _ws;
     private _call;
     private _tools;
     private _recorder;
     private _closed;
-    private _lastAssistantItem;
-    private _responseStartTs;
-    private _sentAudioChunks;
-    private _audioRemainder;
+    private _playback;
+    private _latestMediaTs;
+    private _pendingToolCalls;
     private _responseInProgress;
     private _onResponseDone;
     constructor(options?: OpenAIRealtimeOptions);
@@ -578,6 +691,7 @@ declare class GeminiRealtime implements Session {
     setRecorder(recorder: AudioRecorder): void;
     setBuiltinTools(tools: Set<BuiltinTool>): void;
     setLogger(logger: Logger): void;
+    getTelemetry(): SessionTelemetry;
     start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
     feedAudio(audio: Buffer): void;
     feedDtmf(digits: string): Promise<void>;
@@ -589,72 +703,6 @@ declare class GeminiRealtime implements Session {
     private _handleToolCall;
 }
 
-/**
- * PipelineSession orchestrates STT -> LLM -> TTS for a voice call.
- */
-
-interface PipelineSessionOptions {
-    stt: STT;
-    llm: LLM;
-    tts: TTS;
-    /** System prompt for the LLM. */
-    systemPrompt?: string;
-    /** Send initial greeting. Default: true */
-    greeting?: boolean;
-    /** Language code. Default: 'ko' */
-    language?: string;
-    /** Tool registry for function calling. */
-    toolRegistry?: ToolRegistry;
-    /** Audio recorder for the session. */
-    recorder?: AudioRecorder;
-    /** LLM temperature. */
-    temperature?: number;
-    /** Max tokens for LLM generation. */
-    maxTokens?: number;
-    /** Sample rate for audio. Default: 8000 */
-    sampleRate?: number;
-    /** Whether to interrupt TTS when user starts speaking. Default: true */
-    interruptOnSpeech?: boolean;
-}
-declare class PipelineSession implements Session {
-    private _stt;
-    private _llm;
-    private _tts;
-    private _systemPrompt;
-    private _greeting;
-    private _language;
-    private _temperature;
-    private _maxTokens;
-    private _sampleRate;
-    private _interruptOnSpeech;
-    private _callSession;
-    private _tools;
-    private _recorder;
-    private _conversation;
-    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;
-}
-
 /**
  * Deepgram STT (Speech-to-Text) provider.
  */
@@ -682,6 +730,8 @@ interface DeepgramSTTOptions {
 declare class DeepgramSTT implements STT {
     private _options;
     private _log;
+    get provider(): string;
+    get model(): string;
     setLogger(logger: Logger): void;
     constructor(options?: DeepgramSTTOptions);
     transcribe(audioStream: AsyncIterable<Buffer>, options?: {
@@ -713,6 +763,9 @@ interface ElevenLabsTTSOptions {
 declare class ElevenLabsTTS implements TTS {
     private _options;
     private _log;
+    get provider(): string;
+    get model(): string;
+    get voiceId(): string;
     setLogger(logger: Logger): void;
     constructor(options?: ElevenLabsTTSOptions);
     synthesize(text: string | AsyncIterable<string>, options?: {
@@ -739,6 +792,8 @@ interface OpenAILLMOptions {
 }
 declare class OpenAILLM implements LLM {
     private _options;
+    get provider(): string;
+    get model(): string;
     constructor(options?: OpenAILLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -763,6 +818,8 @@ interface AnthropicLLMOptions {
 }
 declare class AnthropicLLM implements LLM {
     private _options;
+    get provider(): string;
+    get model(): string;
     constructor(options?: AnthropicLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -787,6 +844,8 @@ interface GeminiLLMOptions {
 }
 declare class GeminiLLM implements LLM {
     private _options;
+    get provider(): string;
+    get model(): string;
     constructor(options?: GeminiLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -815,6 +874,8 @@ interface OpenAICompatLLMOptions {
 }
 declare class OpenAICompatLLM implements LLM {
     private _options;
+    get provider(): string;
+    get model(): string;
     constructor(options: OpenAICompatLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -840,6 +901,8 @@ interface OllamaLLMOptions {
 }
 declare class OllamaLLM implements LLM {
     private _inner;
+    get provider(): string;
+    get model(): string;
     constructor(options?: OllamaLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -856,6 +919,8 @@ interface MistralLLMOptions {
 }
 declare class MistralLLM implements LLM {
     private _inner;
+    get provider(): string;
+    get model(): string;
     constructor(options?: MistralLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -872,6 +937,8 @@ interface GroqLLMOptions {
 }
 declare class GroqLLM implements LLM {
     private _inner;
+    get provider(): string;
+    get model(): string;
     constructor(options?: GroqLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -888,6 +955,8 @@ interface PerplexityLLMOptions {
 }
 declare class PerplexityLLM implements LLM {
     private _inner;
+    get provider(): string;
+    get model(): string;
     constructor(options?: PerplexityLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -904,6 +973,8 @@ interface TogetherLLMOptions {
 }
 declare class TogetherLLM implements LLM {
     private _inner;
+    get provider(): string;
+    get model(): string;
     constructor(options?: TogetherLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -920,6 +991,8 @@ interface FireworksLLMOptions {
 }
 declare class FireworksLLM implements LLM {
     private _inner;
+    get provider(): string;
+    get model(): string;
     constructor(options?: FireworksLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -936,6 +1009,8 @@ interface DeepSeekLLMOptions {
 }
 declare class DeepSeekLLM implements LLM {
     private _inner;
+    get provider(): string;
+    get model(): string;
     constructor(options?: DeepSeekLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -952,6 +1027,8 @@ interface XaiLLMOptions {
 }
 declare class XaiLLM implements LLM {
     private _inner;
+    get provider(): string;
+    get model(): string;
     constructor(options?: XaiLLMOptions);
     generate(messages: ConversationMessage[], options?: {
         tools?: ToolRegistry;
@@ -960,6 +1037,27 @@ declare class XaiLLM implements LLM {
     }): AsyncGenerator<LLMChunk>;
 }
 
+/**
+ * Built-in tool 스키마 정의, 포맷 변환, 실행 헬퍼.
+ *
+ * 모든 세션(PipelineSession, OpenAIRealtime, GeminiRealtime)이 공통으로 사용하는
+ * 내장 도구 스키마를 한 곳에서 관리한다.
+ */
+
+declare const BUILTIN_TOOL_NAMES: Set<string>;
+/**
+ * 활성화된 builtin tool 스키마를 요청한 포맷으로 반환.
+ */
+declare function getBuiltinToolSchemas(builtinTools: Set<BuiltinTool> | null, fmt: 'chat' | 'realtime' | 'gemini'): Array<Record<string, unknown>>;
+/**
+ * Builtin tool을 실행하고 결과 문자열을 반환한다.
+ *
+ * `funcName`이 builtin tool이 아니면 `null`을 반환한다.
+ * `hang_up`의 경우 빈 문자열 `""`을 반환한다 (호출자가 종료 처리).
+ */
+declare function isBuiltinTool(name: string): boolean;
+declare function executeBuiltinTool(funcName: string, args: Record<string, unknown>, call: CallSession): Promise<string | null>;
+
 /**
  * Logger factory for the ClawOps agent module.
  *
@@ -979,4 +1077,4 @@ declare function createAgentLogger(userLogger?: Logger): Logger;
  */
 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 };
+export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BUILTIN_TOOL_NAMES, 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, type ToolCallRequest, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, createAgentLogger, createPipelineLogger, executeBuiltinTool, functionTool, getBuiltinToolSchemas, getTracingConfig, isBuiltinTool, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };