@personaai/runtime 0.16.2 → 0.17.0

package/dist/index.d.cts

@@ -265,6 +265,70 @@ interface RcpManifestOptions {
      */
     authToken?: string;
 }
+/**
+ * A Twilio webhook request that reached this runtime, after its signature
+ * was verified. `from` is the end user's number (WhatsApp numbers keep the
+ * `whatsapp:` prefix), `body` is the message text on the message channel.
+ */
+interface TwilioChannelRequest {
+    channel: 'voice' | 'whatsapp' | 'sms';
+    from: string;
+    to: string;
+    /** Present on the voice channel. */
+    callSid?: string;
+    /** Present on the message channel. */
+    messageSid?: string;
+    /** Present on the message channel — the inbound text. */
+    body?: string;
+    /** WhatsApp profile name, when Twilio supplies one. */
+    profileName?: string;
+}
+/**
+ * Return value of {@link TwilioChannelOptions.resolveUser}: the developer's
+ * own user id (which becomes the Persona external user id), optionally with
+ * a per-request Agent override. `null` means "not one of my users" — the
+ * runtime then rejects the call / sends no reply.
+ */
+interface TwilioChannelUser {
+    externalUserId: string;
+    agentId?: string;
+    /** Continue an existing thread instead of the per-user default. */
+    threadId?: string;
+}
+type ResolveTwilioChannelUser = (request: TwilioChannelRequest) => TwilioChannelUser | string | null | Promise<TwilioChannelUser | string | null>;
+/**
+ * Bring-your-own-Twilio-number webhooks, served by this runtime:
+ * `POST /channels/twilio/voice` and `POST /channels/twilio/message`.
+ *
+ * Both routes verify Twilio's `X-Twilio-Signature` with YOUR auth token,
+ * resolve the sender to one of your users, and proxy to Persona. Voice
+ * returns TwiML that points Twilio's media stream straight at Persona (your
+ * server never relays audio); messaging returns the Agent's reply as TwiML,
+ * so no message is sent from Persona's own account.
+ */
+interface TwilioChannelOptions {
+    /** Your Twilio Auth Token — used only to verify inbound webhook signatures. */
+    authToken: string;
+    /**
+     * The exact public origin Twilio calls, e.g. `https://app.example.com`.
+     * Twilio signs the full URL, so a proxy/rewrite that changes it breaks
+     * verification — set this when the request's own host headers aren't the
+     * public URL. Omit to derive it from `x-forwarded-proto` / `host`.
+     */
+    publicUrl?: string;
+    /** Maps a Twilio sender to one of your users. Return `null` to ignore the message/call. */
+    resolveUser: ResolveTwilioChannelUser;
+    /** Default Agent for both channels. `resolveUser` may override it per request. */
+    agentId?: string;
+    /** Spoken instead of the Agent's voice when the session cannot start. */
+    voiceFallback?: string;
+    /** Texted instead of the Agent's reply when the turn fails. `''` disables it. */
+    messageFallback?: string;
+}
+interface ChannelsOptions {
+    /** Enables the two Twilio channel routes. Unset by default. */
+    twilio?: TwilioChannelOptions;
+}
 interface CreateRuntimeOptions {
     /** Base URL of the Persona Developer Platform API, e.g. "https://api.persona.hasanraiyan.me". */
     baseUrl: string;
@@ -311,6 +375,12 @@ interface CreateRuntimeOptions {
     restToolsManifest?: RestToolsManifestOptions;
     /** Serves a conformant RCP manifest for any RCP client to discover. See {@link RcpManifestOptions}. Unset by default — the route only exists when this is provided. */
     rcpManifest?: RcpManifestOptions;
+    /**
+     * Bring-your-own-Twilio-number webhook routes (`/channels/twilio/*`). See
+     * {@link ChannelsOptions}. Unset by default — the routes only exist when
+     * this is provided.
+     */
+    channels?: ChannelsOptions;
     /** Log level for the runtime — off by default. Overrides the global level set via `setLogLevel()` from `@personaai/sdk`. */
     logLevel?: LogLevel;
     /** Custom logger instance — when provided, `logLevel` is ignored. */
@@ -337,6 +407,6 @@ declare class RuntimeHttpError extends Error {
     constructor(status: number, code: string, message: string);
 }
 
-declare const RUNTIME_VERSION = "0.16.1";
+declare const RUNTIME_VERSION = "0.17.0";
 
-export { type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, type VoiceSessionCreateContext, type WorkflowNodeContext, createRuntime };
+export { type ChannelsOptions, type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveTwilioChannelUser, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, type TwilioChannelOptions, type TwilioChannelRequest, type TwilioChannelUser, type VoiceSessionCreateContext, type WorkflowNodeContext, createRuntime };

package/dist/index.d.ts

@@ -265,6 +265,70 @@ interface RcpManifestOptions {
      */
     authToken?: string;
 }
+/**
+ * A Twilio webhook request that reached this runtime, after its signature
+ * was verified. `from` is the end user's number (WhatsApp numbers keep the
+ * `whatsapp:` prefix), `body` is the message text on the message channel.
+ */
+interface TwilioChannelRequest {
+    channel: 'voice' | 'whatsapp' | 'sms';
+    from: string;
+    to: string;
+    /** Present on the voice channel. */
+    callSid?: string;
+    /** Present on the message channel. */
+    messageSid?: string;
+    /** Present on the message channel — the inbound text. */
+    body?: string;
+    /** WhatsApp profile name, when Twilio supplies one. */
+    profileName?: string;
+}
+/**
+ * Return value of {@link TwilioChannelOptions.resolveUser}: the developer's
+ * own user id (which becomes the Persona external user id), optionally with
+ * a per-request Agent override. `null` means "not one of my users" — the
+ * runtime then rejects the call / sends no reply.
+ */
+interface TwilioChannelUser {
+    externalUserId: string;
+    agentId?: string;
+    /** Continue an existing thread instead of the per-user default. */
+    threadId?: string;
+}
+type ResolveTwilioChannelUser = (request: TwilioChannelRequest) => TwilioChannelUser | string | null | Promise<TwilioChannelUser | string | null>;
+/**
+ * Bring-your-own-Twilio-number webhooks, served by this runtime:
+ * `POST /channels/twilio/voice` and `POST /channels/twilio/message`.
+ *
+ * Both routes verify Twilio's `X-Twilio-Signature` with YOUR auth token,
+ * resolve the sender to one of your users, and proxy to Persona. Voice
+ * returns TwiML that points Twilio's media stream straight at Persona (your
+ * server never relays audio); messaging returns the Agent's reply as TwiML,
+ * so no message is sent from Persona's own account.
+ */
+interface TwilioChannelOptions {
+    /** Your Twilio Auth Token — used only to verify inbound webhook signatures. */
+    authToken: string;
+    /**
+     * The exact public origin Twilio calls, e.g. `https://app.example.com`.
+     * Twilio signs the full URL, so a proxy/rewrite that changes it breaks
+     * verification — set this when the request's own host headers aren't the
+     * public URL. Omit to derive it from `x-forwarded-proto` / `host`.
+     */
+    publicUrl?: string;
+    /** Maps a Twilio sender to one of your users. Return `null` to ignore the message/call. */
+    resolveUser: ResolveTwilioChannelUser;
+    /** Default Agent for both channels. `resolveUser` may override it per request. */
+    agentId?: string;
+    /** Spoken instead of the Agent's voice when the session cannot start. */
+    voiceFallback?: string;
+    /** Texted instead of the Agent's reply when the turn fails. `''` disables it. */
+    messageFallback?: string;
+}
+interface ChannelsOptions {
+    /** Enables the two Twilio channel routes. Unset by default. */
+    twilio?: TwilioChannelOptions;
+}
 interface CreateRuntimeOptions {
     /** Base URL of the Persona Developer Platform API, e.g. "https://api.persona.hasanraiyan.me". */
     baseUrl: string;
@@ -311,6 +375,12 @@ interface CreateRuntimeOptions {
     restToolsManifest?: RestToolsManifestOptions;
     /** Serves a conformant RCP manifest for any RCP client to discover. See {@link RcpManifestOptions}. Unset by default — the route only exists when this is provided. */
     rcpManifest?: RcpManifestOptions;
+    /**
+     * Bring-your-own-Twilio-number webhook routes (`/channels/twilio/*`). See
+     * {@link ChannelsOptions}. Unset by default — the routes only exist when
+     * this is provided.
+     */
+    channels?: ChannelsOptions;
     /** Log level for the runtime — off by default. Overrides the global level set via `setLogLevel()` from `@personaai/sdk`. */
     logLevel?: LogLevel;
     /** Custom logger instance — when provided, `logLevel` is ignored. */
@@ -337,6 +407,6 @@ declare class RuntimeHttpError extends Error {
     constructor(status: number, code: string, message: string);
 }
 
-declare const RUNTIME_VERSION = "0.16.1";
+declare const RUNTIME_VERSION = "0.17.0";
 
-export { type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, type VoiceSessionCreateContext, type WorkflowNodeContext, createRuntime };
+export { type ChannelsOptions, type CreateRuntimeOptions, type ErrorContext, type FileUploadContext, type MemoryWriteContext, RUNTIME_VERSION, type RcpManifestOptions, type ResolveTwilioChannelUser, type ResolveUser, type RestToolManifestEntry, type RestToolsManifestOptions, type RunContext, type RunResult, type Runtime, type RuntimeBinaryResponse, type RuntimeBufferedResponse, type RuntimeCapabilities, type RuntimeHooks, RuntimeHttpError, type RuntimeMethod, type RuntimeRequest, type RuntimeResponse, type RuntimeStreamResponse, type RuntimeUploadedFile, type ThreadCreateContext, type ToolCallContext, type TwilioChannelOptions, type TwilioChannelRequest, type TwilioChannelUser, type VoiceSessionCreateContext, type WorkflowNodeContext, createRuntime };

package/dist/index.js

@@ -131,7 +131,7 @@ function evictStaleRuns(runs, now, graceMs = DEFAULT_RUN_GRACE_MS, maxTracked =
 }
 
 // src/version.ts
-var RUNTIME_VERSION = "0.16.1";
+var RUNTIME_VERSION = "0.17.0";
 
 // src/routes/health.ts
 var alwaysOnCapabilities = {
@@ -1653,6 +1653,203 @@ var workflowStreamRoute = async (request, ctx) => {
   };
 };
 
+// src/routes/channels.ts
+var SIGNATURE_HEADER = "x-twilio-signature";
+var DEFAULT_VOICE_FALLBACK = "Sorry, this assistant is unavailable right now. Please try again later.";
+var DEFAULT_MESSAGE_FALLBACK = "Sorry, something went wrong while handling your message. Please try again.";
+function firstHeader(value) {
+  return value?.split(",")[0]?.trim() || void 0;
+}
+function resolveSignedUrl(request, publicUrl) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(request.query)) {
+    if (value !== void 0) search.set(key, value);
+  }
+  const query = search.toString();
+  const pathWithQuery = request.path + (query ? `?${query}` : "");
+  if (publicUrl) {
+    return `${publicUrl.replace(/\/+$/, "")}${pathWithQuery}`;
+  }
+  const host = firstHeader(request.headers["x-forwarded-host"]) ?? firstHeader(request.headers.host);
+  const proto = firstHeader(request.headers["x-forwarded-proto"]) ?? "https";
+  if (!host) return null;
+  return `${proto}://${host}${pathWithQuery}`;
+}
+async function computeTwilioSignature(authToken, url, params) {
+  const payload = url + Object.keys(params).sort().map((key2) => `${key2}${params[key2]}`).join("");
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(authToken),
+    { name: "HMAC", hash: "SHA-1" },
+    false,
+    ["sign"]
+  );
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  const bytes = new Uint8Array(signature);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+async function verifyTwilioSignature(request, options) {
+  const provided = request.headers[SIGNATURE_HEADER];
+  if (!provided || !options.authToken) return false;
+  const url = resolveSignedUrl(request, options.publicUrl);
+  if (!url) return false;
+  const expected = await computeTwilioSignature(options.authToken, url, formParams(request));
+  return constantTimeEqual(expected, provided);
+}
+function formParams(request) {
+  const params = {};
+  const body = request.body;
+  if (!body || typeof body !== "object" || Array.isArray(body)) return params;
+  for (const [key, value] of Object.entries(body)) {
+    if (typeof value === "string") params[key] = value;
+    else if (typeof value === "number" || typeof value === "boolean") params[key] = String(value);
+  }
+  return params;
+}
+function escapeXml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function twiml(body) {
+  return {
+    kind: "buffered",
+    status: 200,
+    headers: { "content-type": "text/xml; charset=utf-8" },
+    body: `<?xml version="1.0" encoding="UTF-8"?>${body}`
+  };
+}
+function forbidden(message) {
+  return {
+    kind: "buffered",
+    status: 403,
+    headers: { "content-type": "text/plain; charset=utf-8" },
+    body: message
+  };
+}
+function channelKind(from) {
+  return from.trim().toLowerCase().startsWith("whatsapp:") ? "whatsapp" : "sms";
+}
+function toUser(result) {
+  if (!result) return null;
+  if (typeof result === "string") return result ? { externalUserId: result } : null;
+  if (typeof result.externalUserId !== "string" || !result.externalUserId) return null;
+  return result;
+}
+async function authenticate(request, options, channelRequest) {
+  if (!await verifyTwilioSignature(request, options)) {
+    return { response: forbidden("Invalid Twilio signature") };
+  }
+  let resolved = null;
+  try {
+    resolved = await options.resolveUser(channelRequest);
+  } catch {
+    resolved = null;
+  }
+  const user = toUser(resolved);
+  if (!user) {
+    return {
+      response: channelRequest.channel === "voice" ? twiml("<Response><Reject/></Response>") : twiml("<Response></Response>")
+    };
+  }
+  return { user };
+}
+var twilioVoiceChannel = async (request, ctx) => {
+  const options = ctx.channels?.twilio;
+  if (!options) {
+    throw new RuntimeHttpError(404, "NOT_FOUND", "Twilio voice channel is not configured.");
+  }
+  const params = formParams(request);
+  const channelRequest = {
+    channel: "voice",
+    from: params.From ?? "",
+    to: params.To ?? "",
+    ...params.CallSid ? { callSid: params.CallSid } : {}
+  };
+  const auth = await authenticate(request, options, channelRequest);
+  if ("response" in auth) return auth.response;
+  const agentId = auth.user.agentId ?? options.agentId;
+  const fallback = options.voiceFallback ?? DEFAULT_VOICE_FALLBACK;
+  if (!agentId) {
+    ctx.logger.warn("twilio voice channel has no agent configured", {
+      hasDefault: false,
+      resolverProvided: false
+    });
+    return twiml(`<Response><Say>${escapeXml(fallback)}</Say><Hangup/></Response>`);
+  }
+  try {
+    const session = await ctx.client.voice.createTelephonySession({
+      agentId,
+      externalUserId: auth.user.externalUserId,
+      ...auth.user.threadId ? { threadId: auth.user.threadId } : {},
+      ...channelRequest.from ? { from: channelRequest.from } : {},
+      ...channelRequest.to ? { to: channelRequest.to } : {},
+      ...channelRequest.callSid ? { callSid: channelRequest.callSid } : {}
+    });
+    await ctx.hooks?.onVoiceSessionCreate?.({
+      userId: auth.user.externalUserId,
+      agentId
+    });
+    return twiml(
+      `<Response><Connect><Stream url="${escapeXml(session.streamUrl)}"/></Connect></Response>`
+    );
+  } catch (err) {
+    ctx.logger.error("twilio voice channel failed to start a session", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return twiml(`<Response><Say>${escapeXml(fallback)}</Say><Hangup/></Response>`);
+  }
+};
+var twilioMessageChannel = async (request, ctx) => {
+  const options = ctx.channels?.twilio;
+  if (!options) {
+    throw new RuntimeHttpError(404, "NOT_FOUND", "Twilio messaging channel is not configured.");
+  }
+  const params = formParams(request);
+  const channelRequest = {
+    channel: channelKind(params.From ?? ""),
+    from: params.From ?? "",
+    to: params.To ?? "",
+    ...params.MessageSid ? { messageSid: params.MessageSid } : {},
+    ...params.Body ? { body: params.Body } : {},
+    ...params.ProfileName ? { profileName: params.ProfileName } : {}
+  };
+  const auth = await authenticate(request, options, channelRequest);
+  if ("response" in auth) return auth.response;
+  const agentId = auth.user.agentId ?? options.agentId;
+  const fallback = options.messageFallback === void 0 ? DEFAULT_MESSAGE_FALLBACK : options.messageFallback;
+  if (!agentId) {
+    ctx.logger.warn("twilio message channel has no agent configured");
+    return fallback ? twiml(`<Response><Message>${escapeXml(fallback)}</Message></Response>`) : twiml("<Response></Response>");
+  }
+  const text = channelRequest.body ?? "";
+  if (!text.trim()) {
+    return twiml("<Response></Response>");
+  }
+  try {
+    const result = await ctx.client.messages.generateReply({
+      agentId,
+      externalUserId: auth.user.externalUserId,
+      text,
+      ...auth.user.threadId ? { threadId: auth.user.threadId } : {},
+      ...channelRequest.profileName ? { displayName: channelRequest.profileName } : {}
+    });
+    return twiml(`<Response><Message>${escapeXml(result.reply)}</Message></Response>`);
+  } catch (err) {
+    ctx.logger.error("twilio message channel failed to generate a reply", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return fallback ? twiml(`<Response><Message>${escapeXml(fallback)}</Message></Response>`) : twiml("<Response></Response>");
+  }
+};
+
 // src/runtime.ts
 function resolveCapabilities(capabilities) {
   return {
@@ -1924,6 +2121,22 @@ function createRuntime(options) {
       requiresAuth: false
     });
   }
+  if (options.channels?.twilio) {
+    routes.push(
+      {
+        method: "POST",
+        pattern: ["channels", "twilio", "voice"],
+        handler: twilioVoiceChannel,
+        requiresAuth: false
+      },
+      {
+        method: "POST",
+        pattern: ["channels", "twilio", "message"],
+        handler: twilioMessageChannel,
+        requiresAuth: false
+      }
+    );
+  }
   const mode = resolveMode(options);
   const heartbeatIntervalMs = options.heartbeatIntervalMs ?? 15e3;
   const runGraceMs = options.runGraceMs ?? DEFAULT_RUN_GRACE_MS;
@@ -2091,7 +2304,8 @@ function createRuntime(options) {
         capabilities,
         logger: routeLogger,
         restToolsManifest: options.restToolsManifest,
-        rcpManifest: options.rcpManifest
+        rcpManifest: options.rcpManifest,
+        channels: options.channels
       });
       const durationMs = Date.now() - startMs;
       logger.info("handle succeeded", {