@personaai/runtime 0.16.2 → 0.17.0

package/dist/index.cjs

@@ -159,7 +159,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 = {
@@ -1681,6 +1681,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 {
@@ -1952,6 +2149,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;
@@ -2119,7 +2332,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", {