@teamlearners/clawops 0.22.0 → 0.24.0

package/dist/agent/index.d.cts

@@ -1,68 +1,8 @@
-import { z } from 'zod';
+import { F as FunctionTool, S as Session, B as BuiltinTool, C as CallSession, a as STT, L as LLM, T as TTS, b as ToolRegistry, c as SessionTelemetry, d as SpeechEvent, e as ConversationMessage, f as LLMChunk } from '../base-Z-uZdd27.cjs';
+export { g as CallDirection, h as CallStatus, O as OpenAIToolDefinition, i as ToolCallRequest, j as functionTool, z as zodToToolParams } from '../base-Z-uZdd27.cjs';
 import { Logger } from 'pino';
 export { Logger } from 'pino';
-
-/**
- * Tool registry for function-calling in voice agent pipelines.
- * Uses Zod schemas for parameter validation.
- */
-
-interface FunctionTool {
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-    required: string[];
-    handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
-}
-interface OpenAIToolDefinition {
-    type: 'function';
-    function: {
-        name: string;
-        description: string;
-        parameters: {
-            type: 'object';
-            properties: Record<string, unknown>;
-            required: string[];
-        };
-    };
-}
-/**
- * Decorator / identity function for marking a function as a tool handler.
- * In TypeScript, this simply returns the function as-is. Use with ToolRegistry.register().
- */
-declare function functionTool<T extends (...args: unknown[]) => unknown>(fn: T): T;
-declare class ToolRegistry {
-    private _tools;
-    private _mcpTools;
-    /** Register a function tool. */
-    register(tool: FunctionTool): void;
-    /** Register tools discovered from MCP servers. */
-    registerMcpTools(tools: FunctionTool[]): void;
-    /** Clear all MCP-registered tools. */
-    clearMcpTools(): void;
-    /**
-     * Create a fork (shallow copy) of this registry.
-     * Useful for per-session tool isolation.
-     */
-    fork(): ToolRegistry;
-    /** Check if a tool is registered. */
-    has(name: string): boolean;
-    /** Get a tool by name. */
-    get(name: string): FunctionTool | undefined;
-    /** Convert all registered tools to OpenAI function-calling format. */
-    toOpenAITools(): OpenAIToolDefinition[];
-    /** Call a tool by name with the given arguments. */
-    call(name: string, args: Record<string, unknown>): Promise<unknown>;
-    /** Get the number of registered tools (including MCP). */
-    get size(): number;
-}
-/**
- * Helper to convert a Zod object schema into a JSON Schema properties + required list.
- */
-declare function zodToToolParams(schema: z.ZodObject<z.ZodRawShape>): {
-    parameters: Record<string, unknown>;
-    required: string[];
-};
+import 'zod';
 
 /**
  * MCP (Model Context Protocol) client for discovering and calling tools.
@@ -128,268 +68,6 @@ 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.
- */
-
-type CallDirection = 'inbound' | 'outbound';
-type CallStatus = 'ringing' | 'active' | 'ended';
-/**
- * Session event handler: receives (call, ...args) like the Python SDK.
- * For example, 'transcript' events pass (call, role, text).
- */
-type SessionEventHandler = (...args: any[]) => void | Promise<void>;
-interface SendAudioFn {
-    (audio: Buffer): void;
-}
-interface ClearAudioFn {
-    (): void;
-}
-interface HangupFn {
-    (): void | Promise<void>;
-}
-interface SendDtmfFn {
-    (digit: string): Promise<void>;
-}
-interface TransferFn {
-    (params: Record<string, unknown>): Promise<Record<string, unknown>>;
-}
-declare class CallSession {
-    readonly callId: string;
-    readonly fromNumber: string;
-    readonly toNumber: string;
-    readonly accountId: string;
-    readonly direction: CallDirection;
-    readonly startTime: Date;
-    readonly metadata: Record<string, unknown>;
-    private _status;
-    private _sendAudioFn;
-    private _clearAudioFn;
-    private _hangupFn;
-    /** @internal */ _sendDtmfFn: SendDtmfFn | null;
-    /** @internal */ _transferFn: TransferFn | null;
-    /** @internal */ _isTransportConnected: (() => boolean) | null;
-    private _dtmfCollectorActive;
-    private _dtmfResolvers;
-    private _dtmfBuffer;
-    private _log;
-    private _handlers;
-    private _endedPromise;
-    private _resolveEnded;
-    private _metrics;
-    private _firstResponseSent;
-    constructor(options: {
-        callId: string;
-        fromNumber: string;
-        toNumber: string;
-        accountId: string;
-        direction: CallDirection;
-        metadata?: Record<string, unknown>;
-    });
-    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. */
-    sendAudio(audio: Buffer): void;
-    /** Clear any queued outbound audio. */
-    clearAudio(): 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>;
-    /**
-     * Transfer the call to a phone number or SIP endpoint.
-     *
-     * destinationType='pstn' (default): `to` is a phone number dialed via carrier.
-     * destinationType='sip': `to` is a SIP URI (e.g. `sip:user@host`) connected
-     * directly to a SIP endpoint without going through the PSTN carrier.
-     */
-    transfer(to: string, options?: {
-        destinationType?: 'pstn' | 'sip';
-        mode?: 'blind' | 'warm';
-        afterTransfer?: 'terminate' | 'return';
-        holdMedia?: string;
-        whisper?: string;
-        context?: Record<string, unknown>;
-        callerId?: string;
-        timeout?: number;
-    }): Promise<Record<string, unknown>>;
-    /** Register an event handler. */
-    on(event: string, handler: SessionEventHandler): void;
-    /** Wait for the call to end. */
-    wait(): Promise<void>;
-    /** Mark the session as ended (called internally). */
-    _markEnded(): void;
-    /** Emit an event to registered handlers. Matches Python SDK: _emit(event, ...args) */
-    _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",
-    /** 통화 전환 도구. 현재 통화를 다른 번호로 전환합니다. */
-    TRANSFER_CALL = "transfer_call",
-    /** 모든 내장 도구를 활성화합니다. (기본값) */
-    ALL = "all",
-    /** 모든 내장 도구를 비활성화합니다. */
-    NONE = "none"
-}
-
-/**
- * Base interfaces for the voice agent pipeline.
- */
-
-/** Speech recognition event. */
-interface SpeechEvent {
-    type: 'interim' | 'final';
-    transcript: string;
-}
-/** Conversation message for LLM context. */
-interface ConversationMessage {
-    role: 'system' | 'user' | 'assistant' | 'tool';
-    content: string;
-    name?: string;
-    tool_call_id?: string;
-}
-/** Tool call request from an LLM. */
-interface ToolCallRequest {
-    id: string;
-    name: string;
-    arguments: string;
-}
-/** LLM response chunk (for streaming). */
-interface LLMChunk {
-    type: 'text' | 'tool_call' | 'done';
-    text?: string;
-    toolCall?: ToolCallRequest;
-}
-/**
- * Session interface for realtime (speech-to-speech) providers.
- * Implementations: OpenAIRealtime, GeminiRealtime
- */
-interface Session {
-    /** Start the realtime session with the call session and tools. Thin wrapper over prewarm + attach. */
-    start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
-    /**
-     * Open LLM connection (and session.update + optional greeting trigger) without a CallSession.
-     *
-     * Audio deltas produced during the prewarm window accumulate in an internal BufferingCall.
-     * attach() then replaces the BufferingCall with the real CallSession and flushes the buffer.
-     *
-     * Tools may optionally be injected here (alternative to calling setToolRegistry separately);
-     * the Session is free to ignore the argument if tools are already set.
-     */
-    prewarm(tools?: ToolRegistry): Promise<void>;
-    /** Attach a real CallSession to a prewarmed session and flush any buffered audio. */
-    attach(callSession: CallSession): Promise<void>;
-    /** Feed raw audio into the session. */
-    feedAudio(audio: Buffer, timestamp?: number): 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;
-    /** Return session telemetry for reporting. */
-    getTelemetry?(): SessionTelemetry | null;
-}
-/**
- * Speech-to-Text provider interface.
- */
-interface STT {
-    /**
-     * Transcribe audio. Returns an async generator of speech events.
-     * The generator yields interim results and a final result.
-     */
-    transcribe(audioStream: AsyncIterable<Buffer>, options?: {
-        language?: string;
-        sampleRate?: number;
-    }): AsyncGenerator<SpeechEvent>;
-}
-/**
- * LLM (Large Language Model) provider interface.
- */
-interface LLM {
-    /**
-     * Generate a response from the LLM.
-     * Returns an async generator of response chunks.
-     */
-    generate(messages: ConversationMessage[], options?: {
-        tools?: ToolRegistry;
-        temperature?: number;
-        maxTokens?: number;
-    }): AsyncGenerator<LLMChunk>;
-}
-/**
- * Text-to-Speech provider interface.
- */
-interface TTS {
-    /**
-     * Synthesize text to audio.
-     * Returns an async generator of PCM16 audio chunks.
-     */
-    synthesize(text: string | AsyncIterable<string>, options?: {
-        voice?: string;
-        sampleRate?: number;
-    }): AsyncGenerator<Buffer>;
-}
-
 /**
  * Tracing configuration for OpenTelemetry integration.
  */
@@ -465,6 +143,13 @@ interface ClawOpsAgentOptions {
      * Python SDK 의 `prewarm_enabled` 과 mirror.
      */
     prewarmEnabled?: boolean;
+    /**
+     * 이 에이전트의 모든 발신에 적용되는 AMD(machineDetection) default.
+     * `'Enable'`=감지 후 `AnsweredBy` 통보(통화 계속), `'Hangup'`=음성사서함 감지 시 자동 종료.
+     * `call(to, { machineDetection })` 로 호출별 override 가능.
+     * 우선순위: 호출 인자 > 인스턴스 default > 비활성. Python SDK 의 `machine_detection` 과 mirror.
+     */
+    machineDetection?: 'Enable' | 'Hangup';
 }
 declare class ClawOpsAgent {
     private _apiKey;
@@ -496,6 +181,8 @@ declare class ClawOpsAgent {
     /** prewarm 세션이 실제 CallSession 에 attach 완료된 callId. attached 이후의 stop() 은 정상 종료 경로가 책임진다. */
     private _prewarmAttached;
     private _prewarmEnabled;
+    /** 모든 발신에 적용되는 AMD default. call() 인자로 호출별 override 가능. */
+    private _machineDetection?;
     constructor(options: ClawOpsAgentOptions);
     private static _validateGain;
     /**
@@ -529,6 +216,8 @@ declare class ClawOpsAgent {
      *
      * @param options.machineDetection 자동응답기/음성사서함 감지(AMD).
      *   `'Enable'`=감지 후 `AnsweredBy` 통보(통화 계속), `'Hangup'`=음성사서함 감지 시 자동 종료.
+     *   미지정 시 인스턴스 default(생성자의 `machineDetection`)를 따른다.
+     *   우선순위: 호출 인자 > 인스턴스 default > 비활성.
      */
     call(to: string, options?: {
         timeout?: number;
@@ -1327,4 +1016,4 @@ declare function createAgentLogger(userLogger?: Logger): Logger;
  */
 declare function createPipelineLogger(parent: Logger): Logger;
 
-export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BUILTIN_TOOL_NAMES, BuiltinTool, type CallDirection, CallSession, type CallStatus, ClawOpsAgent, type ClawOpsAgentOptions, type ControlEvent, ControlWebSocket, type ControlWsOptions, type ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, type DtmfEvent, 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, type MediaEvent, type MediaStartEvent, MediaWebSocket, 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, type ToolConfig, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, buildControlWsUrl, createAgentLogger, createPipelineLogger, executeBuiltinTool, functionTool, getBuiltinToolSchemas, getTracingConfig, isBuiltinTool, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16, zodToToolParams };
+export { type AgentEventType, AnthropicLLM, type AnthropicLLMOptions, AudioRecorder, BUILTIN_TOOL_NAMES, BuiltinTool, CallSession, ClawOpsAgent, type ClawOpsAgentOptions, type ControlEvent, ControlWebSocket, type ControlWsOptions, ConversationMessage, DECODE_TABLE, DeepSeekLLM, type DeepSeekLLMOptions, DeepgramSTT, type DeepgramSTTOptions, type DtmfEvent, ElevenLabsTTS, type ElevenLabsTTSOptions, FireworksLLM, type FireworksLLMOptions, FunctionTool, GeminiLLM, type GeminiLLMOptions, GeminiRealtime, type GeminiRealtimeOptions, GroqLLM, type GroqLLMOptions, LLM, LLMChunk, MCPClient, type MCPServerConfig, type MCPServerHTTP, type MCPServerStdio, type MediaEvent, type MediaStartEvent, MediaWebSocket, MistralLLM, type MistralLLMOptions, OllamaLLM, type OllamaLLMOptions, OpenAICompatLLM, type OpenAICompatLLMOptions, OpenAILLM, type OpenAILLMOptions, OpenAIRealtime, type OpenAIRealtimeOptions, PerplexityLLM, type PerplexityLLMOptions, PipelineSession, type PipelineSessionOptions, STT, Session, SpeechEvent, TTS, TogetherLLM, type TogetherLLMOptions, type ToolConfig, ToolRegistry, type TracingConfig, XaiLLM, type XaiLLMOptions, buildControlWsUrl, createAgentLogger, createPipelineLogger, executeBuiltinTool, getBuiltinToolSchemas, getTracingConfig, isBuiltinTool, mcpServerHTTP, mcpServerStdio, pcm16ToUlaw, resamplePcm16, resetTracingConfig, setTracingConfig, ulawToPcm16 };