@spekoai/sdk 0.4.0 → 0.4.2

package/dist/lib/types/index.d.ts

@@ -2,8 +2,10 @@
 export interface SpekoClientOptions {
     /** API key for authentication. */
     apiKey: string;
-    /** Base URL of the Speko API. Defaults to https://api.speko.ai */
+    /** Base URL of the Speko API. Defaults to https://api.speko.dev */
     baseUrl?: string;
+    /** Alias for {@link SpekoClientOptions.baseUrl}. If both are set, `baseUrl` wins. */
+    baseURL?: string;
     /** Request timeout in milliseconds. Defaults to 30000. */
     timeout?: number;
 }
@@ -117,9 +119,9 @@ export type TranscribeStreamEvent = {
     text: string;
     isFinal: boolean;
     confidence: number;
-} | TranscribeResult & {
+} | (TranscribeResult & {
     type: 'done';
-} | {
+}) | {
     type: 'error';
     error: string;
     code: string;
@@ -127,6 +129,15 @@ export type TranscribeStreamEvent = {
 export interface SynthesizeOptions extends RoutingIntent {
     /** Optional voice override. Otherwise the SDK uses each provider's default. */
     voice?: string;
+    /**
+     * Optional upstream model name to use for synthesis (e.g.
+     * `eleven_multilingual_v2`, `sonic-2`, `gpt-4o-mini-tts`,
+     * `qwen3-tts-flash`). When omitted, the router picks the best-ranked
+     * model for the chosen provider. When set, applies to the primary
+     * candidate only — failover candidates still use the selector's model
+     * so a model intended for provider A isn't sent to provider B.
+     */
+    model?: string;
     speed?: number;
     constraints?: PipelineConstraints;
 }
@@ -147,6 +158,36 @@ export interface SynthesizeStreamResult extends AsyncIterable<Uint8Array> {
     failoverCount: number;
     scoresRunId: string | null;
 }
+export interface VoiceCatalogEntry {
+    /** Routing-key vendor (matches `allowedProviders.tts` entries). */
+    vendor: string;
+    /** Voice id passed through to the provider's TTS API. */
+    id: string;
+    /** Human-readable label. */
+    name: string;
+}
+export interface VoicesProviderEntry {
+    key: string;
+    name: string;
+    models: readonly string[];
+    /**
+     * `true` when the provider's voice library is account-scoped and must
+     * be fetched live from the provider (currently only ElevenLabs).
+     */
+    voicesFetchedLive: boolean;
+}
+export interface VoicesListResult {
+    voices: readonly VoiceCatalogEntry[];
+    providers: readonly VoicesProviderEntry[];
+}
+export interface VoicesListParams {
+    /**
+     * Filter to a single provider's voices. Accepts either the routing key
+     * (`cartesia`, `xai`, `alibaba`, `openai`, `inworld`, `elevenlabs`) or the
+     * catalog suffix form (`xai-tts`, `alibaba-tts`, `openai-tts`).
+     */
+    provider?: string;
+}
 /**
  * One LLM-emitted tool invocation. `args` is a JSON-encoded string (LLMs may
  * stream partial JSON; the proxy guarantees a complete, parseable string).
@@ -177,14 +218,15 @@ export interface ChatMessage {
  * Speko's server-side execution: the proxy POSTs a Standard-Webhooks-
  * signed request to your URL, folds the result back into the next
  * provider turn, and only returns to you when the model emits final
- * text or hands back an inline tool call. `builtin` reserves a slot
- * for managed tools (e.g. `search_knowledge_base`) — handlers ship in
- * a follow-on release.
+ * text or hands back an inline tool call. `builtin` runs Speko-managed
+ * primitives (e.g. `search_knowledge_base`, `transfer_call`, `end_call`).
+ * `integration` runs an
+ * org-installed Speko app action such as Google Calendar or Slack.
  */
-export type ChatToolExecutionMode = 'inline' | 'webhook' | 'builtin';
+export type ChatToolExecutionMode = 'inline' | 'webhook' | 'builtin' | 'integration';
 /**
  * Source-of-execution config. Required when `executionMode` is
- * `webhook` or `builtin`. Mirrors the SpekoTool `source` shape inside
+ * `webhook`, `builtin`, or `integration`. Mirrors the SpekoTool `source` shape inside
  * `@spekoai/tool-execution`.
  */
 export type ChatToolSource = {
@@ -196,10 +238,20 @@ export type ChatToolSource = {
     secretRef: string;
     headers?: Record<string, string>;
     timeoutMs?: number;
+    /** `async` returns `asyncAck` immediately while Speko dispatches the webhook in the background. */
+    responseMode?: 'sync' | 'async';
+    /** LLM-facing acknowledgement used when `responseMode` is `async`. */
+    asyncAck?: string;
 } | {
     kind: 'builtin';
     name: string;
     config?: unknown;
+} | {
+    kind: 'integration';
+    installationId: string;
+    appKey: string;
+    actionKey: string;
+    config?: unknown;
 };
 /**
  * Tool definition exposed to the LLM. `parameters` is a JSON Schema (draft-7)
@@ -208,8 +260,8 @@ export type ChatToolSource = {
  *
  * `executionMode` and `source` are optional and back-compat: omitting
  * both preserves the v0.3 inline behavior. Set `executionMode: 'webhook'`
- * with a matching `source: { kind: 'webhook', ... }` to opt into
- * server-managed execution.
+ * with a matching `source: { kind: 'webhook', ... }` or
+ * `source: { kind: 'integration', ... }` to opt into server-managed execution.
  */
 export interface ChatTool {
     name: string;
@@ -225,12 +277,20 @@ export type ChatToolChoice = 'auto' | 'none' | 'required' | {
         name: string;
     };
 };
+export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
 export interface CompleteParams {
     messages: ChatMessage[];
     intent: RoutingIntent;
+    /**
+     * Optional voice/session identifier forwarded as `x-session-id` for
+     * server-executed tools. The value is intentionally carried out-of-band
+     * so `/v1/complete` request bodies stay provider-shaped.
+     */
+    sessionId?: string;
     systemPrompt?: string;
     temperature?: number;
     maxTokens?: number;
+    reasoningEffort?: ReasoningEffort;
     constraints?: PipelineConstraints;
     tools?: ChatTool[];
     toolChoice?: ChatToolChoice;
@@ -282,7 +342,7 @@ export type CompleteStreamEvent = {
     error: string;
     code: string;
 };
-export type RealtimeProvider = 'openai' | 'google' | 'xai' | 'inworld';
+export type RealtimeProvider = 'openai' | 'google' | 'xai' | 'inworld' | 'alibaba';
 export interface RealtimeToolSpec {
     name: string;
     description: string;
@@ -306,6 +366,10 @@ export interface RealtimeConnectParams {
  * as `audio` frames; text control messages come through typed variants.
  */
 export type RealtimeFrame = {
+    type: 'ready';
+    inputSampleRate: 16000 | 24000;
+    outputSampleRate: 16000 | 24000;
+} | {
     type: 'audio';
     pcm: Uint8Array;
     sampleRate: number;
@@ -323,6 +387,14 @@ export type RealtimeFrame = {
     type: 'usage';
     inputAudioTokens: number;
     outputAudioTokens: number;
+} | {
+    type: 'interruption';
+    at: 'user' | 'assistant';
+} | {
+    type: 'server_tool_call';
+    id: string;
+    name: string;
+    status: 'started' | 'completed' | 'failed';
 } | {
     type: 'error';
     code: string;
@@ -336,6 +408,8 @@ export type RealtimeEventHandler = (frame: RealtimeFrame) => void;
 export interface RealtimeSessionHandle {
     readonly sessionId: string;
     readonly expiresAt: string;
+    readonly inputSampleRate: 16000 | 24000;
+    readonly outputSampleRate: 16000 | 24000;
     /** Send a PCM16 audio chunk up to the model. */
     sendAudio(pcm: Uint8Array): void;
     /** Signal user-turn boundary / commit the input buffer. */
@@ -354,13 +428,17 @@ export interface VoiceDialParams {
     to: string;
     /** Caller ID. Falls back to the org default if omitted server-side. */
     from?: string;
+    /** Persisted assistant to run for this call. When supplied, `intent` can be omitted. */
+    agentId?: string;
     /** Routing intent — language is required, optimizeFor optional. */
-    intent: RoutingIntent;
+    intent?: RoutingIntent;
     constraints?: PipelineConstraints;
     /** TTS voice id passed through to the picked TTS provider. */
     voice?: string;
     /** Agent system prompt. */
     systemPrompt?: string;
+    /** Optional first utterance. `null` is not accepted by phone dial; omit to use the agent default. */
+    firstMessage?: string;
     llm?: {
         temperature?: number;
         maxTokens?: number;
@@ -369,6 +447,17 @@ export interface VoiceDialParams {
         sampleRate?: number;
         speed?: number;
     };
+    sttOptions?: {
+        keywords?: string[];
+    };
+    /** Optional per-call SIP routing hints. Carrier AMD requires trunk/provider support. */
+    telephony?: {
+        region?: string;
+        amd?: {
+            mode?: 'agent' | 'carrier' | 'disabled';
+            timeoutSeconds?: number;
+        };
+    };
     /** Free-form metadata round-tripped to your webhooks. */
     metadata?: Record<string, unknown>;
 }
@@ -376,42 +465,89 @@ export interface VoiceDialResult {
     sessionId: string;
     callControlId: string;
     roomName: string;
-    /** 'dialing' on a real call, 'dialing-stub' if Telnyx isn't configured. */
+    /** 'dialing' on a real call, 'dialing-stub' if managed telephony isn't configured. */
     status: 'dialing' | 'dialing-stub';
     to: string;
     from: string;
 }
 export type PhoneNumberDirection = 'inbound' | 'outbound' | 'both';
+export type PhoneNumberSource = 'managed' | 'sip_trunk';
+export type PhoneNumberSmsAssignmentStatus = 'FAILED_ASSIGNMENT' | 'PENDING_ASSIGNMENT' | 'ASSIGNED' | 'PENDING_UNASSIGNMENT' | 'FAILED_UNASSIGNMENT';
+export interface PhoneNumberSetupStatus {
+    status: 'ready' | 'action_required' | 'suspended';
+    inboundReady: boolean;
+    outboundReady: boolean;
+    agentReady: boolean;
+    forwardingRequired: boolean;
+    sipConnectionReady: boolean;
+    issues: string[];
+}
 export interface PhoneNumberRow {
     id: string;
     organizationId: string;
     e164: string;
+    source: PhoneNumberSource;
+    /** Platform-neutral resource id for a platform-managed number. */
+    providerResourceId: string | null;
+    /** @deprecated Use `providerResourceId`. */
     telnyxPhoneNumberId: string | null;
+    /** @deprecated LiveKit trunk IDs are internal and no longer exposed. */
+    sipTrunkId: string | null;
+    sipConnectionInstallationId: string | null;
+    sipProviderName: string | null;
     direction: PhoneNumberDirection;
     dispatchMetadataTemplate: Record<string, unknown> | null;
     label: string | null;
+    sms10dlcProfileId: string | null;
+    smsCampaignId: string | null;
+    smsAssignmentStatus: PhoneNumberSmsAssignmentStatus | null;
+    smsAssignmentUpdatedAt: string | null;
     /**
      * 1:1 link to a persisted agent. When set, inbound calls hydrate
      * pipeline config from the agent row instead of (or alongside) the
      * dispatch_metadata_template.
      */
     agentId: string | null;
+    setupStatus: PhoneNumberSetupStatus;
+    nextChargeAt: string;
+    lastChargedAt: string | null;
+    suspendedAt: string | null;
     createdAt: string;
     updatedAt: string;
 }
 export interface PhoneNumberCreateParams {
     e164: string;
     direction?: PhoneNumberDirection;
-    /** LiveKit dispatch metadata template (variables `{{var}}` resolved at dial). */
+    /** Dispatch metadata template (variables `{{var}}` resolved at dial). */
     dispatchMetadataTemplate?: Record<string, unknown>;
     label?: string;
     /** 1:1 link to an agent in the same org. */
     agentId?: string;
 }
-export interface PhoneNumberUpdateParams {
+export type PhoneNumberImportSipTrunkParams = {
+    e164: string;
+    /** Optional provider/account label for display. */
+    sipProviderName?: string;
     direction?: PhoneNumberDirection;
+    /** Dispatch metadata template (variables `{{var}}` resolved at dial). */
     dispatchMetadataTemplate?: Record<string, unknown>;
     label?: string;
+    /** 1:1 link to an agent in the same org. */
+    agentId?: string;
+} & ({
+    /** Installed SIP connection integration id. Preferred for productized SIP connections. */
+    sipConnectionInstallationId: string;
+    /** Legacy LiveKit outbound trunk id. Ignored when `sipConnectionInstallationId` is present. */
+    sipTrunkId?: string;
+} | {
+    /** Legacy LiveKit outbound trunk id. Use `sipConnectionInstallationId` for new integrations. */
+    sipTrunkId: string;
+    sipConnectionInstallationId?: string;
+});
+export interface PhoneNumberUpdateParams {
+    direction?: PhoneNumberDirection;
+    dispatchMetadataTemplate?: Record<string, unknown> | null;
+    label?: string | null;
     /** Pass `null` to unlink, a string to relink. */
     agentId?: string | null;
 }
@@ -432,9 +568,75 @@ export interface PhoneNumberSearchParams {
     areaCode?: string;
     /** Optional locality filter, e.g. "San Francisco". */
     locality?: string;
-    /** Max results — Telnyx caps at 50. Default 10. */
+    /** Max results. Default 10. */
     limit?: number;
 }
+export type PhoneNumberKybStatus = 'missing' | 'draft' | 'submitted' | 'approved' | 'rejected' | 'revoked';
+export type PhoneNumberKybSubmissionStatus = Exclude<PhoneNumberKybStatus, 'missing'>;
+export type PhoneNumberKybSlackNotificationStatus = 'not_queued' | 'queued' | 'enqueue_failed';
+export interface PhoneNumberKybBusinessProfile {
+    legalName: string;
+    displayName: string;
+    entityType: string;
+    country: string;
+    registrationId?: string;
+    website: string;
+    address: {
+        street: string;
+        city: string;
+        state: string;
+        postalCode: string;
+        country: string;
+    };
+    useCase: string;
+    expectedUsage: string;
+}
+export interface PhoneNumberKybAuthorizedRepresentative {
+    name: string;
+    title: string;
+    email: string;
+    phone?: string;
+}
+export interface PhoneNumberKybDraftParams {
+    businessProfile: PhoneNumberKybBusinessProfile;
+    authorizedRepresentative: PhoneNumberKybAuthorizedRepresentative;
+    attestationAccepted?: boolean;
+}
+export interface PhoneNumberKybSubmitParams {
+    businessProfile: PhoneNumberKybBusinessProfile;
+    authorizedRepresentative: PhoneNumberKybAuthorizedRepresentative;
+    attestationAccepted: true;
+}
+export interface PhoneNumberKybSubmission {
+    id: string;
+    organizationId: string;
+    status: PhoneNumberKybSubmissionStatus;
+    businessProfile: PhoneNumberKybBusinessProfile | null;
+    authorizedRepresentative: PhoneNumberKybAuthorizedRepresentative | null;
+    attestationAccepted: boolean;
+    attestedAt: string | null;
+    submittedByUserId: string | null;
+    submittedByEmail: string | null;
+    submittedByApiKeyId: string | null;
+    submittedAt: string | null;
+    reviewerUserId: string | null;
+    reviewerEmail: string | null;
+    reviewedAt: string | null;
+    rejectionReason: string | null;
+    slackNotificationStatus: PhoneNumberKybSlackNotificationStatus;
+    slackNotificationJobId: string | null;
+    slackNotificationError: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PhoneNumberKybOverview {
+    status: PhoneNumberKybStatus;
+    submission: PhoneNumberKybSubmission | null;
+    prefill: {
+        businessProfile: PhoneNumberKybBusinessProfile;
+        authorizedRepresentative: PhoneNumberKybAuthorizedRepresentative;
+    } | null;
+}
 /**
  * Routing intent for an agent's voice pipeline. Narrower than the
  * top-level {@link RoutingIntent} — the agents API specifically
@@ -462,6 +664,71 @@ export interface AgentSttOptions {
     /** Vocabulary keywords forwarded to whichever STT provider the router picks. */
     keywords?: string[];
 }
+/**
+ * Built-in ambience clip ids supported by the hosted worker. Custom clip
+ * uploads are intentionally not yet supported — pinning to the built-ins
+ * keeps the v1 API simple and lets the worker map straight to the
+ * `BuiltinAudioClip` enum.
+ */
+export type AgentAmbientClip = 'office-ambience' | 'keyboard-typing' | 'keyboard-typing2';
+/**
+ * Per-agent background audio. Today only ambient (continuous loop) is
+ * supported. The ambience plays on a separate media track mixed
+ * server-side, so it reaches both browser (WebRTC) and phone (SIP) callers
+ * without any client-side change.
+ */
+export interface AgentBackgroundAudio {
+    ambient?: {
+        clip: AgentAmbientClip;
+        /** Linear gain in [0, 1]. Defaults to 1.0 (clip's natural level). */
+        volume?: number;
+    };
+}
+export interface AgentSpeechNormalization {
+    pronunciationDictionary?: Record<string, string>;
+    textReplacements?: Record<string, string>;
+}
+export interface AgentLifecycleWebhookCreate {
+    url: string;
+    /** Deprecated. Lifecycle webhooks use the org-level signing secret from API keys. */
+    secret?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    responseMode?: 'sync' | 'async';
+    asyncAck?: string;
+}
+export interface AgentLifecycleWebhookUpdate {
+    url: string;
+    /** Deprecated. Lifecycle webhooks use the org-level signing secret from API keys. */
+    secret?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    responseMode?: 'sync' | 'async';
+    asyncAck?: string;
+}
+export interface AgentLifecycleWebhookSerialized {
+    url: string;
+    secretRef: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    responseMode?: 'sync' | 'async';
+    asyncAck?: string;
+}
+export interface AgentWebhooksSerialized {
+    preCall?: AgentLifecycleWebhookSerialized;
+    postCall?: AgentLifecycleWebhookSerialized;
+    status?: AgentLifecycleWebhookSerialized;
+}
+export interface AgentWebhooksCreate {
+    preCall?: AgentLifecycleWebhookCreate;
+    postCall?: AgentLifecycleWebhookCreate;
+    status?: AgentLifecycleWebhookCreate;
+}
+export interface AgentWebhooksUpdate {
+    preCall?: AgentLifecycleWebhookUpdate | null;
+    postCall?: AgentLifecycleWebhookUpdate | null;
+    status?: AgentLifecycleWebhookUpdate | null;
+}
 export interface AgentRow {
     id: string;
     organizationId: string;
@@ -472,6 +739,9 @@ export interface AgentRow {
     llmOptions: AgentLlmOptions | null;
     stackPreferences: AgentStackPreferences | null;
     sttOptions: AgentSttOptions | null;
+    backgroundAudio: AgentBackgroundAudio | null;
+    speechNormalization: AgentSpeechNormalization | null;
+    webhooks: AgentWebhooksSerialized | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -483,8 +753,252 @@ export interface AgentCreateParams {
     llmOptions?: AgentLlmOptions;
     stackPreferences?: AgentStackPreferences;
     sttOptions?: AgentSttOptions;
+    backgroundAudio?: AgentBackgroundAudio;
+    speechNormalization?: AgentSpeechNormalization;
+    webhooks?: AgentWebhooksCreate;
+}
+export type AgentUpdateParams = Partial<Omit<AgentCreateParams, 'webhooks'>> & {
+    webhooks?: AgentWebhooksUpdate | null;
+};
+export interface CallTranscriptEntry {
+    id: string;
+    index: number;
+    source: 'user' | 'agent' | 'system';
+    text: string;
+    started_at: string;
+    ended_at: string | null;
+    provider: string | null;
+    model: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface CallCostLine {
+    provider: string;
+    metric: string;
+    quantity: number;
+    keySource: KeySource;
+    costMicroUsd: string;
+}
+export interface CallReport {
+    session_id: string;
+    organization_id: string;
+    summary: string;
+    outcome: string;
+    structured_data: Record<string, unknown>;
+    transcript: {
+        entries: CallTranscriptEntry[];
+    };
+    cost_micro_usd: string;
+    cost_breakdown: CallCostLine[];
+    artifacts: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    scheduled_callback: ScheduledCallback | Record<string, unknown> | null;
+    analysis_status: 'heuristic' | 'completed' | 'failed';
+    analysis_provider: string | null;
+    analysis_model: string | null;
+    analysis_error: string | null;
+    analysis_completed_at: string | null;
+    post_call_webhook_status: 'not_configured' | 'pending' | 'delivered' | 'failed';
+    post_call_webhook_attempts: number;
+    post_call_webhook_next_retry_at: string | null;
+    post_call_webhook_delivered_at: string | null;
+    post_call_webhook_error: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export type ScheduledCallbackStatus = 'scheduled' | 'dispatching' | 'dispatched' | 'cancelled' | 'failed';
+export interface ScheduledCallback {
+    id: string;
+    organization_id: string;
+    source_session_id: string | null;
+    created_session_id: string | null;
+    agent_id: string | null;
+    phone_number_id: string | null;
+    to_number: string;
+    from_number: string | null;
+    scheduled_at: string;
+    status: ScheduledCallbackStatus;
+    reason: string | null;
+    instructions: string | null;
+    summary: string | null;
+    pipeline_config: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    failure_cause: string | null;
+    attempted_at: string | null;
+    dispatched_at: string | null;
+    cancelled_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ScheduledCallbacksListParams {
+    status?: ScheduledCallbackStatus;
+    sourceSessionId?: string;
+    limit?: number;
+}
+export interface CancelScheduledCallbackParams {
+    reason?: string;
+}
+export interface FinalizeCallReportParams {
+    forceAnalysis?: boolean;
+    retryWebhook?: boolean;
+}
+export interface FinalizeCallReportResult {
+    session_id: string;
+    summary: string;
+    outcome: string;
+    cost_micro_usd: string;
+    webhook: unknown;
+}
+export interface CallRecording {
+    url: string;
+}
+export interface CallEvent {
+    id: string;
+    session_id: string | null;
+    organization_id: string;
+    provider: 'livekit' | 'telnyx' | 'speko' | string;
+    event_type: string;
+    status: string | null;
+    failure_cause: string | null;
+    sip_status_code: number | null;
+    sip_status: string | null;
+    occurred_at: string;
+    payload: Record<string, unknown>;
+    created_at: string;
+}
+export interface CallTransfer {
+    id: string;
+    session_id: string;
+    organization_id: string;
+    kind: 'blind' | 'warm';
+    status: 'requested' | 'screening' | 'bridging' | 'completed' | 'failed' | 'cancelled';
+    transfer_to: string;
+    from_room_name: string | null;
+    consultation_room_name: string | null;
+    caller_participant_identity: string | null;
+    recipient_participant_identity: string | null;
+    outbound_trunk_id: string | null;
+    screening_prompt: string | null;
+    summary: string | null;
+    failure_cause: string | null;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+}
+export interface CallTransferResponse extends CallTransfer {
+    routing_attempts?: (CallTransfer | null)[];
+    next_transfer?: CallTransfer | null;
+    fallback?: WarmTransferFallbackResult | null;
+}
+export interface CallDetail {
+    id: string;
+    call_id: string;
+    resource_uri: string;
+    agent_id: string | null;
+    status: string;
+    kind: string;
+    room_name: string | null;
+    language: string;
+    pipeline_config: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+    ended_at: string | null;
+    duration_seconds: number | null;
+    recording_status: string | null;
+    recording_duration_ms: number | null;
+    recording_resource_uri: string;
+    report: CallReport | null;
+    transfers: CallTransfer[];
+    transcript: {
+        entries: CallTranscriptEntry[];
+    };
+    span_tree: Record<string, unknown>;
+}
+export interface BlindTransferParams {
+    to: string;
+    participantIdentity?: string;
+    playDialtone?: boolean;
+    ringingTimeout?: number;
+    headers?: Record<string, string>;
+}
+export interface WarmTransferDestination {
+    to: string;
+    label?: string;
+    outboundTrunkId?: string;
+    screeningPrompt?: string;
+    summary?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface WarmTransferFallback {
+    strategy?: 'return_to_assistant' | 'take_message' | 'end_call';
+    message?: string;
+    takeMessagePrompt?: string;
+    holdAudioUrl?: string;
+}
+export interface WarmTransferVoicemailDetection {
+    mode?: 'agent' | 'amd' | 'disabled';
+    enabled?: boolean;
+    timeoutSeconds?: number;
+}
+export interface WarmTransferFallbackResult {
+    action: 'return_to_assistant' | 'take_message' | 'end_call';
+    message: string;
+    take_message_prompt: string | null;
+    hold_audio_url: string | null;
+    voicemail_detected: boolean;
+}
+export interface WarmTransferParams {
+    to?: string;
+    destinations?: WarmTransferDestination[];
+    from?: string;
+    participantIdentity?: string;
+    outboundTrunkId?: string;
+    screeningPrompt?: string;
+    summary?: string;
+    ringingTimeout?: number;
+    waitUntilAnswered?: boolean;
+    fallback?: WarmTransferFallback;
+    voicemailDetection?: WarmTransferVoicemailDetection;
+    metadata?: Record<string, unknown>;
+}
+export interface CompleteWarmTransferParams {
+    recipientParticipantIdentity?: string;
+    summary?: string;
+}
+export interface CancelWarmTransferParams {
+    reason?: string;
+    summary?: string;
+    tryNext?: boolean;
+    voicemailDetected?: boolean;
+}
+export interface AgentCallListParams {
+    /** Max rows. Default 50, server-capped at 100. */
+    limit?: number;
+    /** ISO timestamp returned as `next_cursor` from the previous page. */
+    cursor?: string;
+    /** ISO timestamp lower bound for calls to include. */
+    since?: string;
+}
+export interface AgentCallListEntry {
+    id: string;
+    call_id: string;
+    resource_uri: string;
+    agent_id: string;
+    status: string;
+    kind: string;
+    room_name: string | null;
+    language: string;
+    created_at: string;
+    ended_at: string | null;
+    duration_seconds: number | null;
+    recording_status: string | null;
+}
+export interface AgentCallListPage {
+    calls: AgentCallListEntry[];
+    entries: AgentCallListEntry[];
+    next_cursor: string | null;
 }
-export type AgentUpdateParams = Partial<AgentCreateParams>;
 export interface AgentToolSourceInline {
     kind: 'inline';
 }
@@ -518,8 +1032,35 @@ export interface AgentToolSourceBuiltin {
     name: string;
     config?: unknown;
 }
-export type AgentToolSourceCreate = AgentToolSourceInline | AgentToolSourceWebhookCreate | AgentToolSourceBuiltin;
-export type AgentToolSourceSerialized = AgentToolSourceInline | AgentToolSourceWebhookSerialized | AgentToolSourceBuiltin;
+/**
+ * Integration source — binds the tool to an org-installed Speko app action
+ * (e.g. Google Calendar `create_event`). Speko resolves the installation and
+ * runs the action server-side at completion time. The shape is identical on
+ * create and in the serialized row (there is no secret to strip).
+ */
+export interface AgentToolSourceIntegration {
+    kind: 'integration';
+    installationId: string;
+    appKey: string;
+    actionKey: string;
+    config?: unknown;
+}
+/**
+ * Webhook source as sent to {@link AgentTools.update}. Unlike the create
+ * shape, `secret` is optional: omit it to keep the existing encrypted secret
+ * untouched, or supply a new one to rotate it.
+ */
+export interface AgentToolSourceWebhookUpdate {
+    kind: 'webhook';
+    url: string;
+    /** Plaintext shared secret. Omit to keep the existing stored secret; supply to rotate. */
+    secret?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+export type AgentToolSourceCreate = AgentToolSourceInline | AgentToolSourceWebhookCreate | AgentToolSourceBuiltin | AgentToolSourceIntegration;
+export type AgentToolSourceSerialized = AgentToolSourceInline | AgentToolSourceWebhookSerialized | AgentToolSourceBuiltin | AgentToolSourceIntegration;
+export type AgentToolSourceUpdate = AgentToolSourceInline | AgentToolSourceWebhookUpdate | AgentToolSourceBuiltin | AgentToolSourceIntegration;
 export interface AgentToolRow {
     id: string;
     agentId: string;
@@ -539,7 +1080,7 @@ export interface AgentToolCreateParams {
 export interface AgentToolUpdateParams {
     description?: string;
     parameters?: Record<string, unknown>;
-    source?: AgentToolSourceCreate;
+    source?: AgentToolSourceUpdate;
 }
 export interface KnowledgeBaseRow {
     id: string;