@koreaaitel/sdk 0.0.0-stage → 0.62.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +943 -2
  3. package/dist/agent/index.cjs +5512 -0
  4. package/dist/agent/index.cjs.map +1 -0
  5. package/dist/agent/index.d.cts +1574 -0
  6. package/dist/agent/index.d.ts +1574 -0
  7. package/dist/agent/index.js +5402 -0
  8. package/dist/agent/index.js.map +1 -0
  9. package/dist/agent/livekit/index.cjs +675 -0
  10. package/dist/agent/livekit/index.cjs.map +1 -0
  11. package/dist/agent/livekit/index.d.cts +165 -0
  12. package/dist/agent/livekit/index.d.ts +165 -0
  13. package/dist/agent/livekit/index.js +669 -0
  14. package/dist/agent/livekit/index.js.map +1 -0
  15. package/dist/chunk-35XJNMFU.js +10 -0
  16. package/dist/chunk-35XJNMFU.js.map +1 -0
  17. package/dist/chunk-3QH5DUA2.js +6 -0
  18. package/dist/chunk-3QH5DUA2.js.map +1 -0
  19. package/dist/chunk-5ZH3XGLJ.cjs +1134 -0
  20. package/dist/chunk-5ZH3XGLJ.cjs.map +1 -0
  21. package/dist/chunk-B3QB5WPI.cjs +202 -0
  22. package/dist/chunk-B3QB5WPI.cjs.map +1 -0
  23. package/dist/chunk-DO6A7FLM.js +1103 -0
  24. package/dist/chunk-DO6A7FLM.js.map +1 -0
  25. package/dist/chunk-LLPMUDNE.cjs +16 -0
  26. package/dist/chunk-LLPMUDNE.cjs.map +1 -0
  27. package/dist/chunk-LPQFS6AS.cjs +8 -0
  28. package/dist/chunk-LPQFS6AS.cjs.map +1 -0
  29. package/dist/chunk-T4ZQXFTN.js +181 -0
  30. package/dist/chunk-T4ZQXFTN.js.map +1 -0
  31. package/dist/client-CrTIZPmY.d.cts +3074 -0
  32. package/dist/client-DJApW4Uf.d.ts +3074 -0
  33. package/dist/error-D1uHhe6r.d.cts +205 -0
  34. package/dist/error-D1uHhe6r.d.ts +205 -0
  35. package/dist/index.cjs +1741 -0
  36. package/dist/index.cjs.map +1 -0
  37. package/dist/index.d.cts +22 -0
  38. package/dist/index.d.ts +22 -0
  39. package/dist/index.js +1638 -0
  40. package/dist/index.js.map +1 -0
  41. package/dist/media-profile-DZCqLJKa.d.cts +492 -0
  42. package/dist/media-profile-DZCqLJKa.d.ts +492 -0
  43. package/dist/solapi/index.cjs +684 -0
  44. package/dist/solapi/index.cjs.map +1 -0
  45. package/dist/solapi/index.d.cts +282 -0
  46. package/dist/solapi/index.d.ts +282 -0
  47. package/dist/solapi/index.js +673 -0
  48. package/dist/solapi/index.js.map +1 -0
  49. package/package.json +121 -4
@@ -0,0 +1,492 @@
1
+ import { Logger } from 'pino';
2
+ import { z } from 'zod';
3
+
4
+ /**
5
+ * Tool registry for function-calling in voice agent pipelines.
6
+ * Uses Zod schemas for parameter validation.
7
+ */
8
+
9
+ /**
10
+ * 도구 선언의 `behavior`(Gemini Live). BLOCKING=결과를 받을 때까지 모델이 기다림,
11
+ * NON_BLOCKING=도구가 도는 동안 모델이 계속 대화.
12
+ */
13
+ type ToolBehavior = 'BLOCKING' | 'NON_BLOCKING';
14
+ /**
15
+ * NON_BLOCKING 도구 결과를 모델이 어떻게 다룰지(Gemini Live `FunctionResponse.scheduling`).
16
+ * SILENT=말하지 않고 기억만, WHEN_IDLE=지금 말을 마친 뒤 전달(서버 기본값), INTERRUPT=즉시 끼어들어 전달.
17
+ */
18
+ type ToolScheduling = 'SILENT' | 'WHEN_IDLE' | 'INTERRUPT';
19
+ /** Gemini Live 에서만 쓰이는 도구별 옵션. 다른 세션은 무시한다. */
20
+ interface ToolOptions {
21
+ /** 함수 선언 `behavior`. 생략하면 세션 기본값(모델별). */
22
+ behavior?: ToolBehavior;
23
+ /** NON_BLOCKING 결과의 `scheduling`. 생략하면 세션 기본값, 그것도 없으면 서버 기본값(WHEN_IDLE). */
24
+ scheduling?: ToolScheduling;
25
+ }
26
+ interface FunctionTool extends ToolOptions {
27
+ name: string;
28
+ description: string;
29
+ parameters: Record<string, unknown>;
30
+ required: string[];
31
+ handler: (args: Record<string, unknown>) => unknown | Promise<unknown>;
32
+ }
33
+ interface OpenAIToolDefinition {
34
+ type: 'function';
35
+ function: {
36
+ name: string;
37
+ description: string;
38
+ parameters: {
39
+ type: 'object';
40
+ properties: Record<string, unknown>;
41
+ required: string[];
42
+ };
43
+ };
44
+ }
45
+ /**
46
+ * Decorator / identity function for marking a function as a tool handler.
47
+ * In TypeScript, this simply returns the function as-is. Use with ToolRegistry.register().
48
+ */
49
+ declare function functionTool<T extends (...args: unknown[]) => unknown>(fn: T): T;
50
+ declare class ToolRegistry {
51
+ private _tools;
52
+ private _mcpTools;
53
+ /** Register a function tool. */
54
+ register(tool: FunctionTool): void;
55
+ /** Register tools discovered from MCP servers. */
56
+ registerMcpTools(tools: FunctionTool[]): void;
57
+ /** Clear all MCP-registered tools. */
58
+ clearMcpTools(): void;
59
+ /**
60
+ * Create a fork (shallow copy) of this registry.
61
+ * Useful for per-session tool isolation.
62
+ */
63
+ fork(): ToolRegistry;
64
+ /** Check if a tool is registered. */
65
+ has(name: string): boolean;
66
+ /** Get a tool by name. */
67
+ get(name: string): FunctionTool | undefined;
68
+ /** Convert all registered tools to OpenAI function-calling format. */
69
+ toOpenAITools(): OpenAIToolDefinition[];
70
+ /** Call a tool by name with the given arguments. */
71
+ call(name: string, args: Record<string, unknown>): Promise<unknown>;
72
+ /** Get the number of registered tools (including MCP). */
73
+ get size(): number;
74
+ }
75
+ /**
76
+ * Helper to convert a Zod object schema into a JSON Schema properties + required list.
77
+ */
78
+ declare function zodToToolParams(schema: z.ZodObject<z.ZodRawShape>): {
79
+ parameters: Record<string, unknown>;
80
+ required: string[];
81
+ };
82
+
83
+ interface ProviderInfo {
84
+ provider: string;
85
+ model: string;
86
+ }
87
+ interface SessionTelemetry {
88
+ sessionType: string;
89
+ llm: ProviderInfo | null;
90
+ stt: ProviderInfo | null;
91
+ tts: ProviderInfo | null;
92
+ voice: string | null;
93
+ language: string;
94
+ greetingEnabled: boolean;
95
+ recordingEnabled: boolean;
96
+ toolCount: number;
97
+ mcpServerCount: number;
98
+ builtinTools: string[];
99
+ }
100
+ interface CallMetrics {
101
+ firstResponseMs: number | null;
102
+ turnCount: number;
103
+ toolCallCount: number;
104
+ toolErrorCount: number;
105
+ bargeInCount: number;
106
+ endReason: string | null;
107
+ errors: Array<{
108
+ type: string;
109
+ message: string;
110
+ }>;
111
+ }
112
+
113
+ /**
114
+ * CallSession represents an active phone call and provides methods to
115
+ * send audio, hang up, and listen for lifecycle events.
116
+ */
117
+
118
+ type CallDirection = 'inbound' | 'outbound';
119
+ type CallStatus = 'ringing' | 'active' | 'ended';
120
+ /**
121
+ * Session event handler: receives (call, ...args) like the Python SDK.
122
+ * For example, 'transcript' events pass (call, role, text).
123
+ */
124
+ type SessionEventHandler = (...args: any[]) => void | Promise<void>;
125
+ interface SendAudioFn {
126
+ (audio: Buffer): void;
127
+ }
128
+ interface ClearAudioFn {
129
+ (): void;
130
+ }
131
+ interface HangupFn {
132
+ (): void | Promise<void>;
133
+ }
134
+ interface SendDtmfFn {
135
+ (digit: string): Promise<void>;
136
+ }
137
+ interface TransferFn {
138
+ (params: Record<string, unknown>): Promise<Record<string, unknown>>;
139
+ }
140
+ /**
141
+ * `collectDtmf` 가 이미 돌고 있는데 또 불렸다.
142
+ *
143
+ * 실시간 모델은 도구를 **중복으로 호출한다** — 앞 호출이 아직 자리를 기다리는 동안 같은
144
+ * 도구를 한 번 더 낸다(2026-09-03 실통화에서 관측). 이걸 맨 `Error` 로 던지면 도구 래퍼가
145
+ * `"Error: ..."` 로 감싸 모델에게 돌려주고, 모델은 뭔가 고장난 줄 알고 **그 뒤로 도구를
146
+ * 다시 부르지 않는다.** 그러면 발신자가 누르는 키는 아무도 받지 않는다.
147
+ *
148
+ * `Error` 를 상속하므로 기존에 이걸 잡던 코드는 그대로 돈다. 도구 경로만 이 타입을 따로
149
+ * 잡아 "고장"이 아니라 "기다리라"는 뜻으로 옮긴다.
150
+ */
151
+ declare class DtmfCollectorBusyError extends Error {
152
+ constructor(message?: string);
153
+ }
154
+ /** `CallSession.transfer` 의 옵션. */
155
+ interface TransferOptions {
156
+ destinationType?: 'pstn' | 'sip';
157
+ mode?: 'blind' | 'warm';
158
+ afterTransfer?: 'terminate' | 'return';
159
+ holdMedia?: string;
160
+ whisper?: string;
161
+ context?: Record<string, unknown>;
162
+ callerId?: string;
163
+ callerIdMode?: 'account' | 'original';
164
+ timeout?: number;
165
+ /**
166
+ * 전환이 연결되지 않았을 때(무응답·통화중·대상 실패) **발신자에게** 들려주고 끊을 문장.
167
+ * 주지 않으면 종전대로 아무 말 없이 끊긴다.
168
+ *
169
+ * ⚠️ `afterTransfer: 'return'` 에서는 재생되지 않는다 — 그 모드는 에이전트가 통화를
170
+ * 이어받으므로 무엇을 말할지는 당신 코드가 정한다. 다만 이어받을 채널이 사라져
171
+ * 서버가 `terminate` 로 내려앉힌 통화에서는 재생된다(그게 발신자가 무음에 남는 경우다).
172
+ */
173
+ failureMessage?: string;
174
+ /** 위 문장을 읽을 음성. `<Say voice>` 와 같은 표기(`cartesia:<id>`). 생략하면 기본 음성. */
175
+ failureVoice?: string;
176
+ }
177
+ declare class CallSession {
178
+ readonly callId: string;
179
+ readonly fromNumber: string;
180
+ readonly toNumber: string;
181
+ readonly accountId: string;
182
+ readonly direction: CallDirection;
183
+ /**
184
+ * 수신 통화에서 발신자가 번호 표시제한(`*23#` 등)을 걸고 건 통화면 `true`.
185
+ * 번호는 `fromNumber` 에 그대로 전달되고, 표시제한 여부만 이 값으로 알 수 있다.
186
+ * 통신사가 표시제한 여부를 보내지 않은 통화와 발신 통화는 `false`.
187
+ */
188
+ readonly callerIdRestricted: boolean;
189
+ /**
190
+ * 착신전환으로 들어온 수신 통화에서 발신자가 **원래 건 번호**. 착신전환을 실행한 통신사가
191
+ * 전환 정보를 함께 보내온 경우에만 값이 있고, 직접 걸려온 통화와 발신 통화는 `null`.
192
+ */
193
+ readonly forwardedFrom: string | null;
194
+ readonly startTime: Date;
195
+ readonly metadata: Record<string, unknown>;
196
+ private _status;
197
+ private _endedStatus;
198
+ private _endedDuration;
199
+ private _sendAudioFn;
200
+ private _clearAudioFn;
201
+ private _hangupFn;
202
+ /** @internal */ _sendDtmfFn: SendDtmfFn | null;
203
+ /** @internal */ _transferFn: TransferFn | null;
204
+ /** @internal control 연결이 끊기면 풀리는 대기. 전환 결과를 기다리는 도구가 쓴다. */
205
+ _transferConnectionLost: (() => {
206
+ promise: Promise<void>;
207
+ cancel: () => void;
208
+ }) | null;
209
+ /** @internal */ _isTransportConnected: (() => boolean) | null;
210
+ /**
211
+ * @internal Media WS playout 마커 훅. LiveKit(`ClawOpsAudioOutput`)이 재생 완료
212
+ * 판정(mark echo)과 barge-in 절단 위치 계산에 쓴다. 다른 세션 타입은 읽지 않는다.
213
+ * prewarm 중(BufferingCall)에는 바인딩되지 않아 null 이다.
214
+ */
215
+ /** @internal */ _sendMark: ((name: string) => void) | null;
216
+ /** @internal */ _waitForMark: ((name: string, timeoutMs: number) => Promise<void>) | null;
217
+ /** @internal */ _flushTransport: (() => Promise<void>) | null;
218
+ /**
219
+ * @internal 지금까지 보낸 오디오가 다 재생될 때까지 기다린다(`MediaWebSocket.waitPlayedOut`).
220
+ * `collectDtmf` 가 안내 재생이 끝난 뒤부터 대기를 세는 데 쓴다. 없으면 바로 센다(종전 동작).
221
+ */
222
+ /** @internal */ _waitPlayedOut: ((timeoutMs: number, signal?: AbortSignal) => Promise<boolean>) | null;
223
+ /**
224
+ * @internal 키패드 자동 전달(=collectDtmf 가 안 걸린 입력)의 버퍼. 통화별로 들고 있어야
225
+ * 동시 통화의 키가 서로 섞이지 않는다. 확정·전달은 ClawOpsAgent 가 한다 — 규칙이 에이전트 설정이라서다.
226
+ */
227
+ /** @internal */ _passiveDtmfBuffer: string[];
228
+ /** @internal */ _passiveDtmfTimer: ReturnType<typeof setTimeout> | null;
229
+ /** @internal 버퍼에 남은 키를 대기 없이 확정하는 함수. collectDtmf 가 열릴 때 부른다. */
230
+ /** @internal */ _passiveDtmfConfirmNow: (() => void) | null;
231
+ /** @internal 한 통화의 자동 전달은 차례로 보낸다. */
232
+ /** @internal */ _passiveDtmfFeedChain: Promise<void>;
233
+ private _dtmfCollectorActive;
234
+ private _dtmfResolvers;
235
+ private _dtmfBuffer;
236
+ private _log;
237
+ private _handlers;
238
+ private _endedPromise;
239
+ private _resolveEnded;
240
+ private _metrics;
241
+ private _firstResponseSent;
242
+ constructor(options: {
243
+ callId: string;
244
+ fromNumber: string;
245
+ toNumber: string;
246
+ accountId: string;
247
+ direction: CallDirection;
248
+ callerIdRestricted?: boolean;
249
+ forwardedFrom?: string | null;
250
+ metadata?: Record<string, unknown>;
251
+ });
252
+ setLogger(logger: Logger): void;
253
+ get status(): CallStatus;
254
+ /**
255
+ * 서버가 통보한 최종 종료 상태. 통화가 끝나기 전에는 null.
256
+ *
257
+ * `completed`(성사) / `no-answer`(벨은 울렸으나 무응답) / `busy`(통화중) /
258
+ * `rejected`(수신 거절) / `canceled`(응답 전 발신 측 취소) / `failed`(시스템·망 오류).
259
+ * `status` 는 SDK 내부 수명주기(ringing→active→ended)이므로 통화 성사 여부는
260
+ * 이 값이나 `call_failed` 이벤트로 판단한다.
261
+ */
262
+ get endedStatus(): string | null;
263
+ /**
264
+ * 서버가 확정한 통화 시간(초). 통화가 끝나기 전에는 `null`.
265
+ *
266
+ * ⚠️ `duration` 과 다르다 — 그쪽은 SDK 가 로컬 시계로 재는 **경과 시간**이라 통화 중에도
267
+ * 읽히고, 세션이 붙기 전후의 오차를 포함한다. 기록·정산에 쓸 값은 이쪽이다.
268
+ */
269
+ get endedDuration(): number | null;
270
+ get duration(): number;
271
+ /** @internal 서버가 통보한 통화 시간을 확정한다. */
272
+ _setEndedDuration(seconds: number): void;
273
+ get metrics(): Readonly<CallMetrics>;
274
+ recordFirstResponse(): void;
275
+ recordTurn(): void;
276
+ recordToolCall(): void;
277
+ recordToolError(err: Error): void;
278
+ recordBargeIn(): void;
279
+ recordEndReason(reason: string): void;
280
+ /** Bind transport functions (called internally by the agent). */
281
+ _bindTransport(send: SendAudioFn, clear: ClearAudioFn, hangup: HangupFn, sendDtmf?: SendDtmfFn, isConnected?: () => boolean): void;
282
+ /**
283
+ * Send G.711 μ-law audio (8kHz, mono) to the caller.
284
+ *
285
+ * NOT PCM16. The transport applies μ-law gain and forwards the bytes as-is,
286
+ * so PCM16 input is reinterpreted as μ-law and plays as noise. Convert first.
287
+ */
288
+ sendAudio(audio: Buffer): void;
289
+ /** Clear any queued outbound audio. */
290
+ clearAudio(): void;
291
+ /** Hang up the call, waiting for pending audio to finish. */
292
+ hangup(): Promise<void>;
293
+ /** @internal 수집 중인 collectDtmf 에 키를 넘긴다.
294
+ *
295
+ * ClawOpsAgent 는 수집이 열려 있을 때만 부른다. 구간 밖 키는 모델에 자동 전달되므로 여기까지
296
+ * 오면 같은 키가 두 경로로 간다 — 동의 때 누른 `1` 이 다음 수집의 첫 자리가 돼 「1534」 가 나왔다. */
297
+ _routeDtmf(digit: string): void;
298
+ /**
299
+ * Collect DTMF digits from the caller.
300
+ *
301
+ * `timeout` 은 **자리 사이** 대기다(inter-digit). `<Gather>` 를 비롯한 IVR 관행과 같은
302
+ * 의미이고, 자리가 들어올 때마다 다시 시작한다.
303
+ *
304
+ * 대기는 **안내 음성이 다 재생된 뒤**부터 센다(Twilio `<Gather>` 와 같다). 모델은 안내 텍스트를
305
+ * 다 만든 순간 이 도구를 부르지만 발신자 쪽에선 음성이 아직 10초 넘게 남아 있을 수 있다 — 그때부터
306
+ * 세면 누를 틈도 없이 빈 값으로 끝난다. 재생 중에 누른 첫 키는 그대로 받고(안내는 ClawOpsAgent 가
307
+ * 끊는다), 그 순간부터 센다.
308
+ *
309
+ * 수집이 열린 **뒤에** 누른 키만 받는다. 그 전에 누른 키는 모델에 자동 전달된다.
310
+ *
311
+ * `maxWait` 는 그 관행이 만드는 최악을 막는 **전체 상한**이다(기본 30초). 자리마다
312
+ * 리셋되는 타이머만 있으면 수집 하나가 최대 `maxDigits × timeout` 동안 산다 —
313
+ * 11자리·5초면 **55초**이고, 그동안 모델은 이 도구에 붙들려 아무 말도 못 한다.
314
+ * 이것도 재생이 끝난 뒤부터 센다 — 「발신자가 누를 수 있게 된 뒤 최대 몇 초」라는 뜻이다. 재생 끝
315
+ * 대기 자체도 `maxWait`(null 이면 60초)로 묶이므로 최악은 그 둘의 합이다. `null` 을 주면 상한 없이
316
+ * 종전대로 돈다.
317
+ *
318
+ * ⚠️ **수집값을 로그에 쓰지 않는다.** 키패드로 받는 값은 카드번호·주민번호일 수 있고,
319
+ * 실제로 그런 구성이 있다. `secure` 와 무관하게 **자릿수만** 남긴다 — 이 옵션은 호환을
320
+ * 위해 남아 있을 뿐 로깅을 좌우하지 않는다.
321
+ */
322
+ collectDtmf(options: {
323
+ maxDigits: number;
324
+ finishOnKey?: string;
325
+ timeout?: number;
326
+ secure?: boolean;
327
+ maxWait?: number | null;
328
+ }): Promise<string>;
329
+ /** Send a sequence of DTMF digits. */
330
+ sendDtmfSequence(digits: string): Promise<void>;
331
+ /**
332
+ * Transfer the call to a phone number or SIP endpoint.
333
+ *
334
+ * destinationType='pstn' (default): `to` is a phone number dialed via carrier.
335
+ * destinationType='sip': `to` is a SIP URI (e.g. `sip:user@host`) connected
336
+ * directly to a SIP endpoint without going through the PSTN carrier. Requires the
337
+ * account to have an active `sip_trunk` add-on; otherwise the transfer fails and
338
+ * the call continues with the AI (result `{ status: 'failed', ... }`).
339
+ *
340
+ * 전환받는 쪽에 표시되는 발신번호는 기본이 **계정 보유번호**(인바운드면 착신 070)다.
341
+ *
342
+ * `callerIdMode: 'original'` 은 인바운드 통화의 **발신자 번호를 표시하려는 선호**다.
343
+ * 표시할 수 없는 통화(KCT 직결 인입이 아니거나 국내 번호로 정규화되지 않는 발신번호)면
344
+ * 조용히 계정 보유번호로 내려앉고 **전환은 그대로 성사된다**. 바뀌는 것은 받는 쪽 표시뿐이라
345
+ * (통화 자체는 계정 번호에서 넘기는 전환이다) 받는 장비에 따라 계정 번호가 보일 수 있다.
346
+ *
347
+ * `callerId` 는 번호를 직접 주는 **지시**라 성격이 다르다. 허용 범위(계정 보유번호 또는
348
+ * KCT 직결 인입 통화의 발신자)를 벗어나면 전환 자체가 실패한다. 둘 다 주면 `callerId` 가
349
+ * 이기고 `callerIdMode` 는 무시된다 — 우선순위 판단은 서버가 한다.
350
+ */
351
+ transfer(to: string, options?: TransferOptions): Promise<Record<string, unknown>>;
352
+ /** Register an event handler. */
353
+ on(event: string, handler: SessionEventHandler): void;
354
+ /** Wait for the call to end. */
355
+ wait(): Promise<void>;
356
+ /**
357
+ * Mark the session as ended (called internally).
358
+ *
359
+ * @param status 서버가 통보한 최종 상태(completed/no-answer/busy/rejected/canceled/
360
+ * failed). 주어지면 `endedStatus` 로 확정한다 — 상대가 받지 않은 통화를 성사된 통화와
361
+ * 구분하기 위함이다. 생략하면 미디어 세션 정리 경로에서의 호출이므로, 아직 종료 전일
362
+ * 때만 'completed' 로 채우고 이미 확정된 서버 상태는 덮어쓰지 않는다.
363
+ */
364
+ _markEnded(status?: string): void;
365
+ /** Emit an event to registered handlers. Matches Python SDK: _emit(event, ...args) */
366
+ _emit(event: string, ...args: any[]): void;
367
+ }
368
+
369
+ /**
370
+ * Built-in tool definitions and selection constants.
371
+ */
372
+ declare enum BuiltinTool {
373
+ /** 전화 종료 도구. AI가 대화 완료 시 통화를 종료합니다. */
374
+ HANG_UP = "hang_up",
375
+ /** DTMF 수집 도구. 사용자의 키패드 입력을 수집합니다. */
376
+ COLLECT_DTMF = "collect_dtmf",
377
+ /** DTMF 전송 도구. ARS 탐색이나 내선번호 입력에 사용합니다. */
378
+ SEND_DTMF = "send_dtmf",
379
+ /** 통화 전환 도구. 현재 통화를 다른 번호로 전환합니다. */
380
+ TRANSFER_CALL = "transfer_call",
381
+ /** 모든 내장 도구를 활성화합니다. (기본값) */
382
+ ALL = "all",
383
+ /** 모든 내장 도구를 비활성화합니다. */
384
+ NONE = "none"
385
+ }
386
+
387
+ /**
388
+ * Base interfaces for the voice agent pipeline.
389
+ */
390
+
391
+ /** Speech recognition event. */
392
+ interface SpeechEvent {
393
+ type: 'interim' | 'final';
394
+ transcript: string;
395
+ }
396
+ /** Conversation message for LLM context. */
397
+ interface ConversationMessage {
398
+ role: 'system' | 'user' | 'assistant' | 'tool';
399
+ content: string;
400
+ name?: string;
401
+ tool_call_id?: string;
402
+ }
403
+ /** Tool call request from an LLM. */
404
+ interface ToolCallRequest {
405
+ id: string;
406
+ name: string;
407
+ arguments: string;
408
+ }
409
+ /** LLM response chunk (for streaming). */
410
+ interface LLMChunk {
411
+ type: 'text' | 'tool_call' | 'done';
412
+ text?: string;
413
+ toolCall?: ToolCallRequest;
414
+ }
415
+ /**
416
+ * Session interface for realtime (speech-to-speech) providers.
417
+ * Implementations: OpenAIRealtime, GeminiRealtime
418
+ */
419
+ interface Session {
420
+ /** Start the realtime session with the call session and tools. Thin wrapper over prewarm + attach. */
421
+ start(callSession: CallSession, tools?: ToolRegistry): Promise<void>;
422
+ /**
423
+ * Open LLM connection (and session.update + optional greeting trigger) without a CallSession.
424
+ *
425
+ * Audio deltas produced during the prewarm window accumulate in an internal BufferingCall.
426
+ * attach() then replaces the BufferingCall with the real CallSession and flushes the buffer.
427
+ *
428
+ * Tools may optionally be injected here (alternative to calling setToolRegistry separately);
429
+ * the Session is free to ignore the argument if tools are already set.
430
+ */
431
+ prewarm(tools?: ToolRegistry): Promise<void>;
432
+ /** Attach a real CallSession to a prewarmed session and flush any buffered audio. */
433
+ attach(callSession: CallSession): Promise<void>;
434
+ /** Feed raw audio into the session. */
435
+ feedAudio(audio: Buffer, timestamp?: number): void;
436
+ /** Feed DTMF digits into the LLM context and trigger a response. */
437
+ feedDtmf?(digits: string): Promise<void>;
438
+ /** Stop the session. */
439
+ stop(): Promise<void>;
440
+ /** Set the logger instance for this session. */
441
+ setLogger?(logger: Logger): void;
442
+ /** Return session telemetry for reporting. */
443
+ getTelemetry?(): SessionTelemetry | null;
444
+ }
445
+ /**
446
+ * Speech-to-Text provider interface.
447
+ */
448
+ interface STT {
449
+ /**
450
+ * Transcribe audio. Returns an async generator of speech events.
451
+ * The generator yields interim results and a final result.
452
+ */
453
+ transcribe(audioStream: AsyncIterable<Buffer>, options?: {
454
+ language?: string;
455
+ sampleRate?: number;
456
+ }): AsyncGenerator<SpeechEvent>;
457
+ }
458
+ /**
459
+ * LLM (Large Language Model) provider interface.
460
+ */
461
+ interface LLM {
462
+ /**
463
+ * Generate a response from the LLM.
464
+ * Returns an async generator of response chunks.
465
+ */
466
+ generate(messages: ConversationMessage[], options?: {
467
+ tools?: ToolRegistry;
468
+ temperature?: number;
469
+ maxTokens?: number;
470
+ }): AsyncGenerator<LLMChunk>;
471
+ }
472
+ /**
473
+ * Text-to-Speech provider interface.
474
+ */
475
+ interface TTS {
476
+ /**
477
+ * Synthesize text to audio.
478
+ * Returns an async generator of PCM16 audio chunks.
479
+ */
480
+ synthesize(text: string | AsyncIterable<string>, options?: {
481
+ voice?: string;
482
+ sampleRate?: number;
483
+ }): AsyncGenerator<Buffer>;
484
+ }
485
+
486
+ /** Select before prewarm; PCM is signed 16-bit little-endian mono, not RTP L16. */
487
+ declare enum MediaProfile {
488
+ MULAW_8000 = "mulaw_8000",
489
+ PCM_S16LE_16000 = "pcm_s16le_16000"
490
+ }
491
+
492
+ export { BuiltinTool as B, CallSession as C, DtmfCollectorBusyError as D, type FunctionTool as F, type LLM as L, MediaProfile as M, type OpenAIToolDefinition as O, type Session as S, type TransferOptions as T, type ToolOptions as a, type STT as b, type TTS as c, ToolRegistry as d, type SessionTelemetry as e, type ToolBehavior as f, type ToolScheduling as g, type SpeechEvent as h, type ConversationMessage as i, type LLMChunk as j, type CallDirection as k, type CallStatus as l, type ToolCallRequest as m, functionTool as n, zodToToolParams as z };