experimental-ash 0.12.1 → 0.14.0

package/dist/src/public/channels/twilio/api.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Minimal Twilio REST API wrapper used by the Twilio channel.
+ *
+ * Requests use Twilio's normal `application/x-www-form-urlencoded`
+ * body encoding and HTTP Basic auth. No Twilio SDK dependency is
+ * required or exposed through Ash public APIs.
+ */
+import { type TwilioAuthToken } from "#public/channels/twilio/verify.js";
+/** Twilio Account SID, materialized directly or from an async secret provider. */
+export type TwilioAccountSid = string | (() => string | Promise<string>);
+/** Fetch implementation override used by tests or non-standard runtimes. */
+export type TwilioFetch = typeof fetch;
+/** Credentials required for Twilio REST API calls and webhook verification. */
+export interface TwilioCredentials {
+    readonly accountSid?: TwilioAccountSid;
+    readonly authToken?: TwilioAuthToken;
+}
+/** Shared Twilio REST API options. */
+export interface TwilioApiOptions {
+    readonly credentials?: TwilioCredentials;
+    readonly apiBaseUrl?: string;
+    readonly fetch?: TwilioFetch;
+}
+/** Raw Twilio REST API response body. */
+export interface TwilioApiResponse {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly body: unknown;
+}
+/** Parameters for creating an outbound Twilio message. */
+export interface TwilioSendMessageInput extends TwilioApiOptions {
+    readonly to: string;
+    readonly body: string;
+    readonly from?: string;
+    readonly messagingServiceSid?: string;
+    readonly statusCallbackUrl?: string;
+}
+/** Parameters for updating a live Twilio call with new TwiML. */
+export interface TwilioUpdateCallInput extends TwilioApiOptions {
+    readonly callSid: string;
+    readonly twiml: string;
+}
+/** Resolves a Twilio Account SID, falling back to `TWILIO_ACCOUNT_SID`. */
+export declare function resolveTwilioAccountSid(accountSid?: TwilioAccountSid): Promise<string>;
+/**
+ * Calls Twilio's REST API with Basic auth and form-encoded body fields.
+ *
+ * `path` is relative to `https://api.twilio.com` by default and may be
+ * pointed elsewhere through `apiBaseUrl` for tests or proxies.
+ */
+export declare function callTwilioApi(input: {
+    readonly credentials?: TwilioCredentials;
+    readonly apiBaseUrl?: string;
+    readonly fetch?: TwilioFetch;
+    readonly path: string;
+    readonly body: Readonly<Record<string, string | number | boolean | undefined | null>>;
+}): Promise<TwilioApiResponse>;
+/** Sends an outbound SMS/MMS-style message via Twilio's Messages resource. */
+export declare function sendTwilioMessage(input: TwilioSendMessageInput): Promise<TwilioApiResponse>;
+/** Updates a live Twilio call by posting replacement TwiML to the Calls resource. */
+export declare function updateTwilioCall(input: TwilioUpdateCallInput): Promise<TwilioApiResponse>;

package/dist/src/public/channels/twilio/api.js

@@ -0,0 +1,92 @@
+/**
+ * Minimal Twilio REST API wrapper used by the Twilio channel.
+ *
+ * Requests use Twilio's normal `application/x-www-form-urlencoded`
+ * body encoding and HTTP Basic auth. No Twilio SDK dependency is
+ * required or exposed through Ash public APIs.
+ */
+import { resolveTwilioAuthToken } from "#public/channels/twilio/verify.js";
+/** Resolves a Twilio Account SID, falling back to `TWILIO_ACCOUNT_SID`. */
+export async function resolveTwilioAccountSid(accountSid) {
+    const source = accountSid ?? process.env.TWILIO_ACCOUNT_SID;
+    if (!source)
+        throw new Error("TWILIO_ACCOUNT_SID is required.");
+    return typeof source === "function" ? await source() : source;
+}
+/**
+ * Calls Twilio's REST API with Basic auth and form-encoded body fields.
+ *
+ * `path` is relative to `https://api.twilio.com` by default and may be
+ * pointed elsewhere through `apiBaseUrl` for tests or proxies.
+ */
+export async function callTwilioApi(input) {
+    const accountSid = await resolveTwilioAccountSid(input.credentials?.accountSid);
+    const authToken = await resolveTwilioAuthToken(input.credentials?.authToken);
+    const apiFetch = input.fetch ?? fetch;
+    const url = `${input.apiBaseUrl ?? "https://api.twilio.com"}${input.path}`;
+    const body = encodeForm(input.body);
+    const response = await apiFetch(url, {
+        method: "POST",
+        headers: {
+            authorization: `Basic ${Buffer.from(`${accountSid}:${authToken}`).toString("base64")}`,
+            "content-type": "application/x-www-form-urlencoded;charset=UTF-8",
+        },
+        body,
+    });
+    return {
+        status: response.status,
+        ok: response.ok,
+        body: await parseResponseBody(response),
+    };
+}
+/** Sends an outbound SMS/MMS-style message via Twilio's Messages resource. */
+export async function sendTwilioMessage(input) {
+    if (!input.from && !input.messagingServiceSid) {
+        throw new Error("twilioChannel: sending a message requires from or messagingServiceSid.");
+    }
+    const accountSid = await resolveTwilioAccountSid(input.credentials?.accountSid);
+    return callTwilioApi({
+        apiBaseUrl: input.apiBaseUrl,
+        credentials: input.credentials,
+        fetch: input.fetch,
+        path: `/2010-04-01/Accounts/${encodeURIComponent(accountSid)}/Messages.json`,
+        body: {
+            Body: input.body,
+            From: input.from,
+            MessagingServiceSid: input.messagingServiceSid,
+            StatusCallback: input.statusCallbackUrl,
+            To: input.to,
+        },
+    });
+}
+/** Updates a live Twilio call by posting replacement TwiML to the Calls resource. */
+export async function updateTwilioCall(input) {
+    const accountSid = await resolveTwilioAccountSid(input.credentials?.accountSid);
+    return callTwilioApi({
+        apiBaseUrl: input.apiBaseUrl,
+        credentials: input.credentials,
+        fetch: input.fetch,
+        path: `/2010-04-01/Accounts/${encodeURIComponent(accountSid)}/Calls/${encodeURIComponent(input.callSid)}.json`,
+        body: { Twiml: input.twiml },
+    });
+}
+function encodeForm(body) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(body)) {
+        if (value === undefined || value === null)
+            continue;
+        params.set(key, String(value));
+    }
+    return params;
+}
+async function parseResponseBody(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/src/public/channels/twilio/defaults.d.ts

@@ -0,0 +1,17 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { TwilioTextMessage, TwilioVoiceCall, TwilioVoiceTranscription } from "#public/channels/twilio/inbound.js";
+import type { TwilioChannelEvents, TwilioContext, TwilioInboundResult, TwilioVoiceResult } from "#public/channels/twilio/twilioChannel.js";
+/** Default phone-number auth projection for Twilio webhook actors. */
+export declare function defaultTwilioAuth(input: {
+    readonly from: string;
+    readonly to?: string;
+    readonly channel: "text" | "voice";
+}): SessionAuthContext;
+/** Default inbound text hook: dispatch with Twilio phone-number auth. */
+export declare function defaultOnText(_ctx: TwilioContext, message: TwilioTextMessage): TwilioInboundResult;
+/** Default inbound voice hook: accept the call with configured voice defaults. */
+export declare function defaultOnVoice(_ctx: TwilioContext, _call: TwilioVoiceCall): TwilioVoiceResult;
+/** Default inbound voice hook: dispatch with Twilio phone-number auth. */
+export declare function defaultOnVoiceTranscription(_ctx: TwilioContext, transcription: TwilioVoiceTranscription): TwilioInboundResult;
+/** Built-in Twilio event handlers for text delivery and terminal errors. */
+export declare const defaultEvents: TwilioChannelEvents;

package/dist/src/public/channels/twilio/defaults.js

@@ -0,0 +1,69 @@
+import { extractErrorId, formatErrorHint } from "#internal/logging.js";
+/** Default phone-number auth projection for Twilio webhook actors. */
+export function defaultTwilioAuth(input) {
+    const attributes = {
+        channel: input.channel,
+        from: input.from,
+    };
+    if (input.to !== undefined)
+        attributes.to = input.to;
+    return {
+        attributes,
+        authenticator: "twilio-webhook",
+        issuer: "twilio",
+        principalId: `twilio:${input.from}`,
+        principalType: "user",
+    };
+}
+/** Default inbound text hook: dispatch with Twilio phone-number auth. */
+export function defaultOnText(_ctx, message) {
+    return {
+        auth: defaultTwilioAuth({
+            channel: "text",
+            from: message.from,
+            to: message.to,
+        }),
+    };
+}
+/** Default inbound voice hook: accept the call with configured voice defaults. */
+export function defaultOnVoice(_ctx, _call) {
+    return {};
+}
+/** Default inbound voice hook: dispatch with Twilio phone-number auth. */
+export function defaultOnVoiceTranscription(_ctx, transcription) {
+    return {
+        auth: defaultTwilioAuth({
+            channel: "voice",
+            from: transcription.from,
+            to: transcription.to,
+        }),
+    };
+}
+/** Built-in Twilio event handlers for text delivery and terminal errors. */
+export const defaultEvents = {
+    async "message.completed"(event, ctx) {
+        if (event.finishReason === "tool-calls" || !event.message)
+            return;
+        await ctx.twilio.sendMessage(event.message);
+    },
+    async "turn.failed"(event, ctx) {
+        const hint = formatErrorHint(event);
+        const errorId = extractErrorId(event.details);
+        await ctx.twilio.sendMessage([
+            `I hit an error while handling your request${hint}.`,
+            "",
+            "Please try again, rephrase, or reach out if it keeps failing.",
+            ...(errorId ? ["", `Error id: ${errorId}`] : []),
+        ].join("\n"));
+    },
+    async "session.failed"(event, ctx) {
+        const hint = formatErrorHint(event);
+        const errorId = extractErrorId(event.details);
+        await ctx.twilio.sendMessage([
+            `This session could not recover from an error${hint}.`,
+            "",
+            "Start a new message to continue.",
+            ...(errorId ? ["", `Error id: ${errorId}`] : []),
+        ].join("\n"));
+    },
+};

package/dist/src/public/channels/twilio/inbound.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Twilio inbound webhook parsing and prompt shaping.
+ *
+ * The channel owns these small data shapes instead of exposing raw
+ * Twilio webhook payloads as the public API surface.
+ */
+import type { UserContent } from "ai";
+/** Channel-owned representation of one inbound Twilio text message. */
+export interface TwilioTextMessage {
+    readonly from: string;
+    readonly to: string | undefined;
+    readonly body: string;
+    readonly messageSid: string | undefined;
+    readonly accountSid: string | undefined;
+    readonly raw: URLSearchParams;
+}
+/** Channel-owned representation of one inbound Twilio voice call. */
+export interface TwilioVoiceCall {
+    readonly from: string;
+    readonly to: string | undefined;
+    readonly callSid: string | undefined;
+    readonly accountSid: string | undefined;
+    readonly raw: URLSearchParams;
+}
+/** Channel-owned representation of one inbound Twilio voice transcription. */
+export interface TwilioVoiceTranscription {
+    readonly from: string;
+    readonly to: string | undefined;
+    readonly callSid: string | undefined;
+    readonly text: string;
+    readonly confidence: number | undefined;
+    readonly transcriptionSid: string | undefined;
+    readonly raw: URLSearchParams;
+}
+/** Inbound identity and response guidance rendered into the model-visible `<twilio_context>` block. */
+export interface TwilioInboundContext {
+    readonly from: string;
+    readonly to?: string;
+    readonly messageSid?: string;
+    readonly callSid?: string;
+    readonly channel: "text" | "voice";
+}
+/** Parses Twilio's incoming-message webhook fields. */
+export declare function parseTwilioTextMessage(params: URLSearchParams): TwilioTextMessage | null;
+/** Parses Twilio's incoming-call webhook fields. */
+export declare function parseTwilioVoiceCall(params: URLSearchParams): TwilioVoiceCall | null;
+/**
+ * Parses Twilio voice transcription fields.
+ *
+ * Supports `<Gather input="speech">` (`SpeechResult`), recording
+ * transcription callbacks (`TranscriptionText`), and real-time
+ * transcription callbacks (`TranscriptionData` JSON). Real-time partial
+ * results are ignored until Twilio marks them final.
+ */
+export declare function parseTwilioVoiceTranscription(params: URLSearchParams): TwilioVoiceTranscription | null;
+/** Renders a deterministic `<twilio_context>` block for the model. */
+export declare function formatTwilioContextBlock(context: TwilioInboundContext): string;
+/** Prepends a `<twilio_context>` block to the inbound turn message. */
+export declare function prependTwilioContext(message: string | UserContent, context: TwilioInboundContext): string | UserContent;

package/dist/src/public/channels/twilio/inbound.js

@@ -0,0 +1,123 @@
+/**
+ * Twilio inbound webhook parsing and prompt shaping.
+ *
+ * The channel owns these small data shapes instead of exposing raw
+ * Twilio webhook payloads as the public API surface.
+ */
+const TWILIO_SMS_RESPONSE_INSTRUCTIONS = "Reply for SMS in plain text. Keep the response concise and avoid Markdown formatting, " +
+    "tables, headings, code fences, and long lists. Ask at most one short follow-up question " +
+    "when more information is needed.";
+/** Parses Twilio's incoming-message webhook fields. */
+export function parseTwilioTextMessage(params) {
+    const from = requiredParam(params, "From");
+    const body = requiredParam(params, "Body");
+    if (!from || !body)
+        return null;
+    return {
+        accountSid: optionalParam(params, "AccountSid"),
+        body,
+        from,
+        messageSid: optionalParam(params, "MessageSid") ?? optionalParam(params, "SmsMessageSid"),
+        raw: params,
+        to: optionalParam(params, "To"),
+    };
+}
+/** Parses Twilio's incoming-call webhook fields. */
+export function parseTwilioVoiceCall(params) {
+    const from = requiredParam(params, "From") ?? requiredParam(params, "Caller");
+    if (!from)
+        return null;
+    return {
+        accountSid: optionalParam(params, "AccountSid"),
+        callSid: optionalParam(params, "CallSid"),
+        from,
+        raw: params,
+        to: optionalParam(params, "To") ?? optionalParam(params, "Called"),
+    };
+}
+/**
+ * Parses Twilio voice transcription fields.
+ *
+ * Supports `<Gather input="speech">` (`SpeechResult`), recording
+ * transcription callbacks (`TranscriptionText`), and real-time
+ * transcription callbacks (`TranscriptionData` JSON). Real-time partial
+ * results are ignored until Twilio marks them final.
+ */
+export function parseTwilioVoiceTranscription(params) {
+    const from = requiredParam(params, "From") ?? requiredParam(params, "Caller");
+    if (!from)
+        return null;
+    const parsedData = parseTranscriptionData(optionalParam(params, "TranscriptionData"));
+    const final = optionalParam(params, "Final");
+    if (final === "false")
+        return null;
+    const text = optionalParam(params, "SpeechResult") ??
+        optionalParam(params, "TranscriptionText") ??
+        parsedData?.transcript ??
+        "";
+    if (!text.trim())
+        return null;
+    return {
+        callSid: optionalParam(params, "CallSid"),
+        confidence: parseConfidence(optionalParam(params, "Confidence") ?? parsedData?.confidence),
+        from,
+        raw: params,
+        text,
+        to: optionalParam(params, "To") ?? optionalParam(params, "Called"),
+        transcriptionSid: optionalParam(params, "TranscriptionSid"),
+    };
+}
+/** Renders a deterministic `<twilio_context>` block for the model. */
+export function formatTwilioContextBlock(context) {
+    const lines = [
+        "<twilio_context>",
+        `channel: ${context.channel}`,
+        "response_medium: sms",
+        `response_instructions: ${TWILIO_SMS_RESPONSE_INSTRUCTIONS}`,
+        `from: ${context.from}`,
+        ...(context.to ? [`to: ${context.to}`] : []),
+        ...(context.messageSid ? [`message_sid: ${context.messageSid}`] : []),
+        ...(context.callSid ? [`call_sid: ${context.callSid}`] : []),
+        "</twilio_context>",
+    ];
+    return lines.join("\n");
+}
+/** Prepends a `<twilio_context>` block to the inbound turn message. */
+export function prependTwilioContext(message, context) {
+    const block = formatTwilioContextBlock(context);
+    if (typeof message === "string") {
+        return message.length > 0 ? `${block}\n\n${message}` : block;
+    }
+    const contextPart = { type: "text", text: block };
+    return [contextPart, ...message];
+}
+function requiredParam(params, name) {
+    const value = params.get(name);
+    return value && value.trim().length > 0 ? value : null;
+}
+function optionalParam(params, name) {
+    const value = params.get(name);
+    return value === null || value.length === 0 ? undefined : value;
+}
+function parseTranscriptionData(value) {
+    if (!value)
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return {
+            confidence: typeof parsed.confidence === "number" || typeof parsed.confidence === "string"
+                ? String(parsed.confidence)
+                : undefined,
+            transcript: typeof parsed.transcript === "string" ? parsed.transcript : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function parseConfidence(value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}

package/dist/src/public/channels/twilio/index.d.ts

@@ -0,0 +1,5 @@
+export { twilioChannel, type TwilioAllowFrom, type TwilioChannel, type TwilioChannelConfig, type TwilioChannelCredentials, type TwilioChannelEvents, type TwilioChannelState, type TwilioContext, type TwilioEventContext, type TwilioHandle, type TwilioInboundResult, type TwilioInboundResultOrPromise, type TwilioMessagingConfig, type TwilioReceiveArgs, type TwilioSendMessageOptions, type TwilioVoiceConfig, type TwilioVoiceResult, type TwilioVoiceResultOrPromise, } from "#public/channels/twilio/twilioChannel.js";
+export { callTwilioApi, resolveTwilioAccountSid, sendTwilioMessage, updateTwilioCall, type TwilioAccountSid, type TwilioApiOptions, type TwilioApiResponse, type TwilioCredentials, type TwilioFetch, type TwilioSendMessageInput, type TwilioUpdateCallInput, } from "#public/channels/twilio/api.js";
+export type { TwilioInboundContext, TwilioTextMessage, TwilioVoiceCall, TwilioVoiceTranscription, } from "#public/channels/twilio/inbound.js";
+export { emptyTwilioResponse, escapeXml, gatherSpeechTwilioResponse, sayTwilioResponse, twimlResponse, type TwilioGatherTwimlOptions, } from "#public/channels/twilio/twiml.js";
+export { buildTwilioSignatureBase, resolveTwilioAuthToken, signTwilioRequest, verifyTwilioRequest, type TwilioAuthToken, type TwilioVerifiedRequest, type TwilioVerifyOptions, type TwilioWebhookUrl, } from "#public/channels/twilio/verify.js";

package/dist/src/public/channels/twilio/index.js

@@ -0,0 +1,4 @@
+export { twilioChannel, } from "#public/channels/twilio/twilioChannel.js";
+export { callTwilioApi, resolveTwilioAccountSid, sendTwilioMessage, updateTwilioCall, } from "#public/channels/twilio/api.js";
+export { emptyTwilioResponse, escapeXml, gatherSpeechTwilioResponse, sayTwilioResponse, twimlResponse, } from "#public/channels/twilio/twiml.js";
+export { buildTwilioSignatureBase, resolveTwilioAuthToken, signTwilioRequest, verifyTwilioRequest, } from "#public/channels/twilio/verify.js";

package/dist/src/public/channels/twilio/twilioChannel.d.ts

@@ -0,0 +1,179 @@
+import type { SessionAuthContext } from "#channel/types.js";
+import type { HandleMessageStreamEvent } from "#protocol/message.js";
+import { type TwilioApiOptions, type TwilioApiResponse, type TwilioCredentials } from "#public/channels/twilio/api.js";
+import { type TwilioTextMessage, type TwilioVoiceCall, type TwilioVoiceTranscription } from "#public/channels/twilio/inbound.js";
+import { type TwilioAuthToken, type TwilioWebhookUrl } from "#public/channels/twilio/verify.js";
+import { type Channel } from "#public/definitions/defineChannel.js";
+type EventData<T extends HandleMessageStreamEvent["type"]> = Extract<HandleMessageStreamEvent, {
+    type: T;
+}> extends {
+    data: infer D;
+} ? D : undefined;
+/** Pre-dispatch Twilio context passed to inbound text and voice hooks. */
+export interface TwilioContext {
+    readonly twilio: TwilioHandle;
+}
+/** Event-handler Twilio context, including mutable per-phone channel state. */
+export interface TwilioEventContext extends TwilioContext {
+    state: TwilioChannelState;
+}
+/** JSON-serializable state for the phone-number conversation. */
+export interface TwilioChannelState {
+    /** Caller / sender phone number. */
+    from: string | null;
+    /** Twilio number or sender that received the latest session-starting webhook. */
+    to: string | null;
+    /** Most recent inbound SMS SID when this session was started by text. */
+    lastMessageSid?: string | null;
+    /** Most recent inbound Call SID when this session was started by voice. */
+    lastCallSid?: string | null;
+}
+/** Twilio channel credentials. `authToken` also verifies inbound webhook signatures. */
+export interface TwilioChannelCredentials extends TwilioCredentials {
+    readonly authToken?: TwilioAuthToken;
+}
+/** Arguments accepted by `receive(twilio, args)` for proactive phone-number sessions. */
+export interface TwilioReceiveArgs {
+    readonly phoneNumber: string;
+    /** Twilio sender included in the phone-pair continuation token. */
+    readonly from?: string;
+}
+/** Result of an inbound Twilio text or transcription hook. Return `null` to drop the webhook. */
+export type TwilioInboundResult = {
+    auth: SessionAuthContext | null;
+} | null;
+/** Sync or async {@link TwilioInboundResult}. */
+export type TwilioInboundResultOrPromise = TwilioInboundResult | Promise<TwilioInboundResult>;
+/** Phone-number allow list for inbound Twilio webhook triggers. `"*"` allows every sender. */
+export type TwilioAllowFrom = string | readonly string[] | (() => string | readonly string[] | Promise<string | readonly string[]>);
+/**
+ * Result of an inbound Twilio voice hook. Return `null` to reject the call.
+ * Any result other than `null` accepts the call and can override the answering TwiML.
+ */
+export interface TwilioVoiceResult {
+    /** Prompt spoken before Twilio starts speech recognition. */
+    readonly prompt?: string;
+    /** BCP 47 language used for speech recognition and the nested `<Say>` prompt. */
+    readonly language?: string;
+    /** Twilio `<Say voice>` used for the prompt, e.g. `Polly.Joanna-Neural`. */
+    readonly voice?: string;
+    /** Twilio `<Gather speechModel>` used for speech recognition. */
+    readonly speechModel?: string;
+    /** Twilio `<Gather timeout>` in seconds. */
+    readonly timeoutSeconds?: number;
+    /** Twilio `<Gather speechTimeout>`, such as `"auto"` or a second count string. */
+    readonly speechTimeout?: string;
+    /** Twilio `<Gather hints>` for expected words or phrases. */
+    readonly hints?: string | readonly string[];
+    /** Twilio `<Gather profanityFilter>` toggle. */
+    readonly profanityFilter?: boolean;
+}
+/** Sync or async {@link TwilioVoiceResult}. */
+export type TwilioVoiceResultOrPromise = TwilioVoiceResult | null | undefined | Promise<TwilioVoiceResult | null | undefined>;
+type TwilioEventHandler<T extends HandleMessageStreamEvent["type"]> = (data: EventData<T>, ctx: TwilioEventContext) => void | Promise<void>;
+/** Event handlers supported by `twilioChannel({ events })`. */
+export interface TwilioChannelEvents {
+    readonly "turn.started"?: TwilioEventHandler<"turn.started">;
+    readonly "actions.requested"?: TwilioEventHandler<"actions.requested">;
+    readonly "action.result"?: TwilioEventHandler<"action.result">;
+    readonly "message.completed"?: TwilioEventHandler<"message.completed">;
+    readonly "message.appended"?: TwilioEventHandler<"message.appended">;
+    readonly "input.requested"?: TwilioEventHandler<"input.requested">;
+    readonly "turn.failed"?: TwilioEventHandler<"turn.failed">;
+    readonly "turn.completed"?: TwilioEventHandler<"turn.completed">;
+    readonly "session.failed"?: TwilioEventHandler<"session.failed">;
+    readonly "session.completed"?: TwilioEventHandler<"session.completed">;
+    readonly "session.waiting"?: TwilioEventHandler<"session.waiting">;
+    readonly "connection.authorization_required"?: TwilioEventHandler<"connection.authorization_required">;
+    readonly "connection.authorization_pending"?: TwilioEventHandler<"connection.authorization_pending">;
+    readonly "connection.authorization_completed"?: TwilioEventHandler<"connection.authorization_completed">;
+}
+/** SMS/Messaging defaults for Twilio outbound replies. */
+export interface TwilioMessagingConfig {
+    /** Sender phone number. Defaults to the inbound `To` number when available. */
+    readonly from?: string;
+    /** Messaging Service SID. Used instead of `from` when supplied. */
+    readonly messagingServiceSid?: string;
+    /** Optional Twilio status callback URL for outbound messages. */
+    readonly statusCallbackUrl?: string;
+}
+/** Voice webhook defaults for accepting calls and gathering speech. */
+export interface TwilioVoiceConfig {
+    /** Prompt spoken when a caller reaches the voice route. */
+    readonly prompt?: string;
+    /** Twilio `<Say voice>` used for the prompt, e.g. `Polly.Joanna-Neural`. */
+    readonly voice?: string;
+    /** Spoken acknowledgement after a transcription webhook is accepted. */
+    readonly acknowledgement?: string;
+    /** BCP 47 language used for speech recognition and the nested `<Say>` prompt. */
+    readonly language?: string;
+    /** Twilio `<Gather speechModel>` used for speech recognition. */
+    readonly speechModel?: string;
+    /** Twilio `<Gather timeout>` in seconds. */
+    readonly timeoutSeconds?: number;
+    /** Twilio `<Gather speechTimeout>`, such as `"auto"` or a second count string. */
+    readonly speechTimeout?: string;
+    /** Twilio `<Gather hints>` for expected words or phrases. */
+    readonly hints?: string | readonly string[];
+    /** Twilio `<Gather profanityFilter>` toggle. */
+    readonly profanityFilter?: boolean;
+}
+/** Configuration for {@link twilioChannel}. */
+export interface TwilioChannelConfig {
+    readonly credentials?: TwilioChannelCredentials;
+    /**
+     * Base route for Twilio webhooks. Defaults to `/ash/v1/twilio` and
+     * mounts `/messages`, `/voice`, and `/voice/transcription` below it.
+     */
+    readonly route?: string;
+    /**
+     * Public URL Twilio used for signing. Set this when proxies or local
+     * tunnels make `request.url` differ from the configured webhook URL.
+     */
+    readonly webhookUrl?: TwilioWebhookUrl;
+    /** Public base URL used to render absolute voice `<Gather action>` URLs. */
+    readonly publicBaseUrl?: string | ((request: Request) => string | Promise<string>);
+    /**
+     * Exact caller/sender numbers allowed to reach inbound hooks, or `"*"` to
+     * allow every verified Twilio sender. Resolvers run on each inbound webhook.
+     */
+    readonly allowFrom: TwilioAllowFrom;
+    readonly messaging?: TwilioMessagingConfig;
+    readonly voice?: TwilioVoiceConfig;
+    readonly api?: Omit<TwilioApiOptions, "credentials">;
+    /** Inbound text hook. Defaults to phone-number auth and dispatch. */
+    onText?(ctx: TwilioContext, message: TwilioTextMessage): TwilioInboundResultOrPromise;
+    /** Inbound voice hook. Return `null` to reject the call before gathering speech. */
+    onVoice?(ctx: TwilioContext, call: TwilioVoiceCall): TwilioVoiceResultOrPromise;
+    /** Inbound voice transcription hook. Defaults to phone-number auth and dispatch. */
+    onVoiceTranscription?(ctx: TwilioContext, transcription: TwilioVoiceTranscription): TwilioInboundResultOrPromise;
+    readonly events?: TwilioChannelEvents;
+}
+/** Low-level Twilio handle exposed to hooks and event handlers. */
+export interface TwilioHandle {
+    /** Caller / sender phone number bound to this conversation. */
+    readonly from: string;
+    /** Twilio receiver / sender number for replies, when known. */
+    readonly to: string | undefined;
+    /** Most recent call SID, when the session started from a voice transcription. */
+    readonly callSid: string | undefined;
+    /** Raw Twilio REST API escape hatch. */
+    request(path: string, body: Readonly<Record<string, string | number | boolean | undefined | null>>): Promise<TwilioApiResponse>;
+    /** Sends a text message to this conversation's phone number by default. */
+    sendMessage(message: string, options?: TwilioSendMessageOptions): Promise<TwilioApiResponse>;
+    /** Updates a live call with replacement TwiML. */
+    updateCall(callSid: string, twiml: string): Promise<TwilioApiResponse>;
+}
+/** Per-call overrides for {@link TwilioHandle.sendMessage}. */
+export interface TwilioSendMessageOptions {
+    readonly to?: string;
+    readonly from?: string;
+    readonly messagingServiceSid?: string;
+    readonly statusCallbackUrl?: string;
+}
+/** Concrete return type of {@link twilioChannel}. */
+export interface TwilioChannel extends Channel<TwilioChannelState> {
+}
+/** Twilio channel factory for SMS and speech-transcribed inbound calls. */
+export declare function twilioChannel(config: TwilioChannelConfig): TwilioChannel;
+export {};