experimental-ash 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # experimental-ash
 
+## 0.14.0
+
+### Minor Changes
+
+- b87f0fb: Add a new twilio channel to manage incoming sms and voice messages
+
 ## 0.13.0
 
 ### Minor Changes

package/dist/docs/public/channels/README.md

@@ -230,6 +230,29 @@ dispatch for app mentions, direct messages, and interactions.
 For a Slack app backed by Vercel Connect, see [Slack channel setup](./slack.md) to create the Connect client
 and channel file.
 
+## Twilio Channels
+
+Twilio channels are authored with `twilioChannel()`:
+
+```ts
+import { twilioChannel } from "experimental-ash/channels/twilio";
+
+export default twilioChannel({
+  allowFrom: "+15551234567",
+});
+```
+
+The channel verifies `X-Twilio-Signature` itself, accepts inbound SMS at
+`/ash/v1/twilio/messages`, answers phone calls at `/ash/v1/twilio/voice`, and dispatches speech
+transcripts posted to `/ash/v1/twilio/voice/transcription`. The raw continuation token is the
+caller/sender phone number plus the Twilio receiver (`From:To`), so texts and call transcripts for
+the same phone-number pair resume the same Ash session without collapsing conversations that use
+different Twilio numbers. `allowFrom` accepts a single phone number, a list, or a zero-argument
+resolver when the allowed phone numbers come from dynamic state. Use `allowFrom: "*"` only when the
+`onText` and `onVoice` hooks perform their own incoming-number checks.
+
+See [Twilio channel setup](./twilio.md) for webhook URLs, environment variables, and overrides.
+
 ## File Uploads
 
 `send()` accepts `string | UserContent`. To include file attachments,

package/dist/docs/public/channels/twilio.md

@@ -0,0 +1,179 @@
+---
+title: "Twilio channel setup"
+description: "Create a Twilio-backed Ash channel for SMS and speech-transcribed phone calls."
+---
+
+# Twilio Channel Setup
+
+The Twilio channel accepts inbound SMS webhooks and inbound voice calls. Voice calls are answered
+with TwiML `<Gather input="speech">`; the Twilio speech transcript is then delivered to the same
+Ash session model as SMS. The raw continuation token is the caller/sender phone number plus the
+Twilio receiver: `From:To`.
+
+## Add The Channel
+
+Create `agent/channels/twilio.ts`:
+
+```ts
+import { twilioChannel } from "experimental-ash/channels/twilio";
+
+export default twilioChannel({
+  allowFrom: "+15551234567",
+  messaging: {
+    from: "+15557654321",
+  },
+});
+```
+
+Set the Twilio credentials Ash needs to verify incoming webhooks and send default SMS replies:
+
+```bash
+TWILIO_ACCOUNT_SID=AC...
+TWILIO_AUTH_TOKEN=...
+```
+
+You can also provide the same values in channel config:
+
+```ts
+export default twilioChannel({
+  allowFrom: "+15551234567",
+  credentials: {
+    accountSid: "AC...",
+    authToken: "...",
+  },
+  messaging: {
+    from: "+15557654321",
+  },
+});
+```
+
+`TWILIO_AUTH_TOKEN` (or `credentials.authToken`) is required for inbound webhook signature
+verification. `TWILIO_ACCOUNT_SID` and the auth token are required when the default
+`"message.completed"` handler sends replies through Twilio's Messages API. Inbound SMS replies can
+use the webhook's `To` number as the outbound sender; proactive sessions and custom deployments
+should set `messaging.from` or `messaging.messagingServiceSid` so Ash knows which Twilio sender to
+use.
+
+By default, the channel mounts:
+
+- `POST /ash/v1/twilio/messages` for Messaging webhooks
+- `POST /ash/v1/twilio/voice` for inbound call webhooks
+- `POST /ash/v1/twilio/voice/transcription` for speech transcript callbacks
+
+Point your Twilio phone number's Messaging webhook at `/messages` and Voice webhook at `/voice`.
+Use the exact public URL Twilio will call, including the same route prefix you configure in Ash.
+
+## Configuration
+
+`allowFrom` is required. Use it to limit who can reach inbound hooks. It can be a single phone
+number, a static list, or a resolver that runs for each inbound webhook:
+
+```ts
+import { twilioChannel } from "experimental-ash/channels/twilio";
+
+export default twilioChannel({
+  allowFrom: "+15551234567",
+});
+```
+
+```ts
+export default twilioChannel({
+  allowFrom: ["+15551234567", "+15557654321"],
+});
+```
+
+```ts
+export default twilioChannel({
+  allowFrom: async () => await loadAllowedPhoneNumbers(),
+});
+```
+
+You can pass `allowFrom: "*"` to allow every verified Twilio sender, but this is dangerous for
+public phone numbers. When you use `"*"`, check the incoming number in `onText` and `onVoice` before
+accepting or dispatching:
+
+```ts
+export default twilioChannel({
+  allowFrom: "*",
+  async onText(ctx, message) {
+    if (!(await isAllowedPhoneNumber(message.from, message.to))) return null;
+    return {
+      auth: {
+        principalId: message.from,
+        principalType: "user",
+        authenticator: "twilio",
+        attributes: { to: message.to ?? "" },
+      },
+    };
+  },
+  async onVoice(ctx, call) {
+    if (!(await isAllowedPhoneNumber(call.from, call.to))) return null;
+    return {
+      language: "en-US",
+      prompt: "How can I help?",
+      speechModel: "phone_call",
+      voice: "Polly.Joanna-Neural",
+    };
+  },
+});
+```
+
+Override outbound sender/API defaults as needed:
+
+```ts
+export default twilioChannel({
+  allowFrom: ["+15551234567"],
+  credentials: {
+    accountSid: process.env.TWILIO_ACCOUNT_SID,
+    authToken: process.env.TWILIO_AUTH_TOKEN,
+  },
+  messaging: {
+    from: "+15557654321",
+    // or messagingServiceSid: "MG...",
+  },
+  api: {
+    apiBaseUrl: "https://api.twilio.com",
+  },
+});
+```
+
+If a proxy or tunnel changes the URL Ash sees, set `webhookUrl` so signature verification uses the
+exact URL configured in Twilio. For voice, set `publicBaseUrl` when TwiML needs absolute callback
+URLs from a different public origin.
+
+For a successful production setup, make sure the deployed app has either environment variables or
+channel options for:
+
+- Inbound verification: `TWILIO_AUTH_TOKEN` or `credentials.authToken`
+- Default outbound SMS: `TWILIO_ACCOUNT_SID` or `credentials.accountSid`, plus the auth token
+- Outbound sender: the inbound webhook `To` number, `messaging.from`, or
+  `messaging.messagingServiceSid`
+- Voice transcript callbacks behind a proxy/tunnel: `publicBaseUrl` if Ash cannot derive the
+  public callback URL from the request, and `webhookUrl` if signature verification must use a
+  different public URL than `request.url`
+
+## Hooks
+
+`onText` and `onVoiceTranscription` decide whether to dispatch and what auth to use. Return
+`{ auth }` to dispatch or `null` to drop the webhook. `onVoice` runs when a call arrives; return
+`null` to reject the call. Any other result accepts it, and an object can override the spoken
+prompt, language, Twilio `<Say voice>`, and speech-recognition options.
+
+```ts
+export default twilioChannel({
+  allowFrom: ["+15551234567"],
+  onText(ctx, message) {
+    return {
+      auth: {
+        principalId: message.from,
+        principalType: "user",
+        authenticator: "twilio",
+        attributes: { to: message.to ?? "" },
+      },
+    };
+  },
+});
+```
+
+The default `"message.completed"` event handler sends the agent's response as an SMS through
+Twilio's Messages API. Replace `events["message.completed"]` if you want custom delivery.

package/dist/docs/public/typescript-api.md

@@ -84,6 +84,25 @@ Channel and Slack types exported from `experimental-ash/channels/slack`:
 - `Card`, `Button`, `Actions`, `Section`, `Modal`, `Table`, etc. - card builders re-exported for
   rendering Slack messages
 
+Channel and Twilio types exported from `experimental-ash/channels/twilio`:
+
+- `twilioChannel` - Twilio channel factory for SMS and speech-transcribed voice webhooks
+- `TwilioChannelConfig` - config type for routes, credentials, allow-listing, outbound messaging,
+  voice prompts, API overrides, and event handlers
+- `TwilioAllowFrom` - single-number, static-list, or dynamic phone-number policy used by
+  `allowFrom`
+- `TwilioContext` - pre-dispatch context for `onText`, `onVoice`, and `onVoiceTranscription`
+  (`twilio`)
+- `TwilioEventContext` - event-handler context (`twilio`, plus mutable `state`)
+- `TwilioHandle` - Twilio handle with `from`, `to`, `callSid`, `request()`, `sendMessage()`, and
+  `updateCall()`
+- `TwilioTextMessage` - parsed inbound SMS payload (`from`, `to`, `body`, `messageSid`, ...)
+- `TwilioVoiceCall` - parsed inbound call payload passed to `onVoice`
+- `TwilioVoiceResult` - call-answering options returned by `onVoice`
+- `TwilioVoiceTranscription` - parsed voice transcript payload (`from`, `to`, `callSid`, `text`,
+  `confidence`, ...)
+- `verifyTwilioRequest`, `signTwilioRequest` - Ash-owned Twilio webhook signature helpers
+
 Channel types exported from `experimental-ash/channels`:
 
 - `defineChannel` - channel primitive with `routes`, `state`, `context()`, and event handlers

package/dist/src/internal/application/package.js

@@ -6,7 +6,7 @@ import { ASH_PACKAGE_NAME } from "#package-name.js";
 let cachedPackageInfo;
 // The package build stamps the published version into `dist` so bundled
 // deployments can still report package metadata without resolving package.json.
-const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.13.0";
+const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.14.0";
 const BUNDLED_FALLBACK_PACKAGE_VERSION_PLACEHOLDER = "__ASH_PACKAGE_VERSION_PLACEHOLDER__";
 const WORKFLOW_MODULE_ALIASES = {
     "workflow/api": "src/compiled/@workflow/core/runtime.js",

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;
+}