@bliggy/chat-runtime 0.0.0-stage → 0.3.1

package/src/runtime.js

@@ -0,0 +1,525 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const TURN_STATUSES = Object.freeze([
+  'received',
+  'authenticated',
+  'processing',
+  'awaiting_confirmation',
+  'executing',
+  'completed',
+  'cancelled',
+  'rejected',
+  'failed',
+  'expired'
+]);
+
+const TURN_TRANSITIONS = Object.freeze({
+  received: ['authenticated', 'rejected', 'failed'],
+  authenticated: ['processing', 'rejected', 'failed'],
+  processing: ['awaiting_confirmation', 'completed', 'failed'],
+  awaiting_confirmation: ['executing', 'cancelled', 'expired'],
+  executing: ['completed', 'cancelled', 'failed'],
+  completed: [],
+  cancelled: [],
+  rejected: [],
+  failed: [],
+  expired: []
+});
+
+class ChannelRuntimeError extends Error {
+  constructor(message, { code = 'CHANNEL_RUNTIME_ERROR', statusCode = 500 } = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+}
+
+class EnvelopeValidationError extends ChannelRuntimeError {
+  constructor(message) {
+    super(message, { code: 'INVALID_CHANNEL_ENVELOPE', statusCode: 400 });
+  }
+}
+
+class SecurityError extends ChannelRuntimeError {
+  constructor(message = 'Channel request could not be authenticated') {
+    super(message, { code: 'CHANNEL_AUTHENTICATION_FAILED', statusCode: 401 });
+  }
+}
+
+class RateLimitError extends ChannelRuntimeError {
+  constructor(message = 'Channel rate limit exceeded') {
+    super(message, { code: 'CHANNEL_RATE_LIMITED', statusCode: 429 });
+  }
+}
+
+function parseDecision(message) {
+  const normalized = typeof message === 'string' ? message.trim().toLowerCase() : '';
+  if (['confirm', 'approve', 'yes'].includes(normalized)) return 'confirm';
+  if (['cancel', 'reject', 'no'].includes(normalized)) return 'cancel';
+  return null;
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map(key => [key, stableValue(value[key])]));
+}
+
+function actionSignature(action) {
+  return JSON.stringify(stableValue(action));
+}
+
+function actionIdempotencyKey(turn, action, index) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify([turn.id, index, stableValue(action)]))
+    .digest('hex');
+}
+
+function validateEnvelope(channel, envelope, maxTextLength) {
+  if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) {
+    throw new EnvelopeValidationError('Channel adapter must return an envelope object');
+  }
+  if (envelope.channel !== channel) {
+    throw new EnvelopeValidationError(`Envelope channel must be ${channel}`);
+  }
+  for (const key of ['sourceKey', 'threadKey']) {
+    if (typeof envelope[key] !== 'string' || envelope[key].trim() === '') {
+      throw new EnvelopeValidationError(`${key} is required`);
+    }
+  }
+  if (typeof envelope.text !== 'string') {
+    throw new EnvelopeValidationError('text must be a string');
+  }
+  if (envelope.text.length > maxTextLength) {
+    throw new EnvelopeValidationError(`text exceeds the ${maxTextLength} character limit`);
+  }
+}
+
+function validatePrincipal(resolution) {
+  if (!resolution || typeof resolution !== 'object') {
+    throw new SecurityError('Channel actor could not be resolved');
+  }
+  for (const key of ['tenantKey', 'actorKey']) {
+    if (typeof resolution[key] !== 'string' || resolution[key].trim() === '') {
+      throw new SecurityError('Channel actor could not be resolved');
+    }
+  }
+  if (!resolution.principal) throw new SecurityError('Channel actor could not be resolved');
+}
+
+function sanitizeAuthentication(authentication) {
+  if (!authentication || typeof authentication !== 'object') return null;
+  const { allowed, method, provider, accountKey, reason } = authentication;
+  return { allowed: !!allowed, method, provider, accountKey, reason };
+}
+
+function classifyActions(actions, authorization) {
+  const approved = new Set((authorization?.approved || []).map(actionSignature));
+  const pending = new Set(
+    (authorization?.requiresConfirmation || authorization?.requiresConfirm || []).map(actionSignature)
+  );
+  const rejected = new Map((authorization?.rejected || []).map(item => {
+    const { reason = 'Action rejected by policy', ...actionWithoutReason } = item;
+    return [actionSignature(item.action || actionWithoutReason), reason];
+  }));
+
+  return actions.map(action => {
+    const signature = actionSignature(action);
+    if (rejected.has(signature)) return { action, decision: 'reject', reason: rejected.get(signature) };
+    if (pending.has(signature)) return { action, decision: 'confirm' };
+    if (approved.has(signature)) return { action, decision: 'approve' };
+    return { action, decision: 'reject', reason: 'Action was not classified by policy' };
+  });
+}
+
+function defaultRender({ plan, results, pendingActions, decision }) {
+  let content = plan?.content || plan?.summary || '';
+  if (decision === 'cancel') content ||= 'The pending action was cancelled.';
+  if (decision === 'confirm') content ||= 'The pending action was confirmed.';
+  if (pendingActions.length > 0) {
+    content = `${content}${content ? '\n\n' : ''}Would you like me to go ahead with these actions?`;
+  }
+  return { content, results, pendingActions };
+}
+
+class ChannelRuntime {
+  constructor({
+    adapters,
+    turnStore,
+    resolvePrincipal,
+    plan,
+    authorize,
+    execute,
+    render = defaultRender,
+    rateLimit = null,
+    parseConfirmation = parseDecision,
+    confirmationTtlMs = 24 * 60 * 60 * 1000,
+    maxTextLength = 50_000,
+    maxActions = 25,
+    now = () => new Date(),
+    onSecurityEvent = () => {},
+    onError = () => {}
+  }) {
+    if (!adapters || typeof adapters !== 'object') throw new TypeError('adapters are required');
+    for (const method of ['claim', 'transition', 'getPending', 'claimPending']) {
+      if (typeof turnStore?.[method] !== 'function') throw new TypeError(`turnStore.${method} is required`);
+    }
+    for (const [name, value] of Object.entries({ resolvePrincipal, plan, authorize, execute, render })) {
+      if (typeof value !== 'function') throw new TypeError(`${name} must be a function`);
+    }
+    if (typeof now !== 'function') throw new TypeError('now must be a function');
+    for (const [name, value] of Object.entries({ confirmationTtlMs, maxTextLength, maxActions })) {
+      if (!Number.isInteger(value) || value < 1) throw new TypeError(`${name} must be a positive integer`);
+    }
+
+    this.adapters = adapters;
+    this.turnStore = turnStore;
+    this.resolvePrincipal = resolvePrincipal;
+    this.plan = plan;
+    this.authorize = authorize;
+    this.execute = execute;
+    this.render = render;
+    this.rateLimit = rateLimit;
+    this.parseConfirmation = parseConfirmation;
+    this.confirmationTtlMs = confirmationTtlMs;
+    this.maxTextLength = maxTextLength;
+    this.maxActions = maxActions;
+    this.now = now;
+    this.onSecurityEvent = onSecurityEvent;
+    this.onError = onError;
+  }
+
+  async handle({ channel, payload, context = {}, emit = () => {} }) {
+    const adapter = this.adapters[channel];
+    if (!adapter || typeof adapter.normalize !== 'function' || typeof adapter.authenticate !== 'function') {
+      throw new EnvelopeValidationError(`Unsupported channel: ${channel}`);
+    }
+
+    const envelope = await adapter.normalize(payload, context);
+    validateEnvelope(channel, envelope, this.maxTextLength);
+
+    const authentication = await adapter.authenticate(envelope, context);
+    if (!authentication?.allowed) {
+      await this.onSecurityEvent({
+        channel,
+        sourceKey: envelope.sourceKey,
+        threadKey: envelope.threadKey,
+        sender: envelope.sender,
+        provider: authentication?.provider,
+        method: authentication?.method,
+        reason: authentication?.reason
+      });
+      throw new SecurityError();
+    }
+
+    const resolution = await this.resolvePrincipal({ envelope, authentication, context });
+    validatePrincipal(resolution);
+    const scope = {
+      tenantKey: resolution.tenantKey,
+      actorKey: resolution.actorKey,
+      channel,
+      threadKey: envelope.threadKey
+    };
+    const storeContext = { principal: resolution.principal, context };
+
+    if (this.rateLimit) {
+      const access = await this.rateLimit({
+        ...scope,
+        envelope,
+        principal: resolution.principal,
+        context
+      });
+      if (!access?.allowed) throw new RateLimitError(access?.reason);
+    }
+
+    const claimed = await this.turnStore.claim({
+      ...scope,
+      sourceKey: envelope.sourceKey,
+      status: 'received',
+      input: envelope,
+      security: sanitizeAuthentication(authentication)
+    }, storeContext);
+    if (!claimed.created) {
+      return await this._result(adapter, claimed.turn, envelope, context, true);
+    }
+
+    let turn = claimed.turn;
+    try {
+      turn = await this.turnStore.transition(turn, 'authenticated', {}, storeContext);
+      await emit({ type: 'turn', status: turn.status, turnId: turn.id });
+
+      // Read without claiming: interpretation can be asynchronous or inconclusive.
+      // The later atomic claim must still match this exact scoped action snapshot.
+      const pendingTurn = await this.turnStore.getPending(scope, storeContext);
+      const interpreted = await this.parseConfirmation(envelope.text, {
+        channel, envelope, context, principal: resolution.principal,
+        pendingTurn: pendingTurn ? structuredClone(pendingTurn) : null
+      });
+      const decision = [null, undefined, 'confirm', 'cancel'].includes(interpreted)
+        ? interpreted : 'clarify';
+      if (decision === 'clarify') {
+        turn = await this.turnStore.transition(turn, 'processing', {}, storeContext);
+        const output = await this.render({
+          channel, envelope, results: [], pendingActions: [], decision,
+          plan: { content: 'Please tell me whether you want to go ahead with the pending actions, or what you would like to change.' },
+          context
+        });
+        turn = await this.turnStore.transition(turn, 'completed', { output, results: [] }, storeContext);
+        return await this._result(adapter, turn, envelope, context, false);
+      }
+      if (decision) {
+        return await this._handleDecision({
+          adapter,
+          context,
+          decision,
+          emit,
+          envelope,
+          principal: resolution.principal,
+          scope,
+          storeContext,
+          pendingTurn,
+          turn
+        });
+      }
+
+      turn = await this.turnStore.transition(turn, 'processing', {}, storeContext);
+      await emit({ type: 'turn', status: turn.status, turnId: turn.id });
+      const plan = await this.plan({
+        principal: resolution.principal,
+        envelope,
+        turn,
+        emit,
+        context
+      });
+      const actions = Array.isArray(plan?.actions) ? plan.actions : [];
+      if (actions.length > this.maxActions) {
+        throw new ChannelRuntimeError('Plan contains too many actions', {
+          code: 'CHANNEL_ACTION_LIMIT_EXCEEDED',
+          statusCode: 400
+        });
+      }
+      const authorization = await this.authorize({
+        principal: resolution.principal,
+        envelope,
+        turn,
+        plan,
+        actions,
+        confirmed: false,
+        context
+      });
+      const classified = classifyActions(actions, authorization);
+      const approved = classified.filter(item => item.decision === 'approve').map(item => item.action);
+      const pendingActions = classified.filter(item => item.decision === 'confirm').map(item => item.action);
+      const results = classified
+        .filter(item => item.decision === 'reject')
+        .map(item => ({ action: item.action, status: 'rejected', message: item.reason }));
+      results.push(...await this._executeActions(
+        resolution.principal,
+        turn,
+        approved,
+        envelope,
+        emit,
+        context
+      ));
+
+      const output = await this.render({
+        channel,
+        envelope,
+        plan,
+        results,
+        pendingActions,
+        decision: null,
+        context
+      });
+      turn = await this.turnStore.transition(
+        turn,
+        pendingActions.length > 0 ? 'awaiting_confirmation' : 'completed',
+        {
+          plan,
+          output,
+          pendingActions,
+          results,
+          ...(pendingActions.length > 0
+            ? { expiresAt: new Date(this.now().getTime() + this.confirmationTtlMs).toISOString() }
+            : {})
+        },
+        storeContext
+      );
+      await emit({ type: 'turn', status: turn.status, turnId: turn.id });
+      return await this._result(adapter, turn, envelope, context, false);
+    } catch (error) {
+      await this.onError(error, { turn, envelope, scope });
+      if (TURN_TRANSITIONS[turn.status]?.includes('failed')) {
+        turn = await this.turnStore.transition(turn, 'failed', {
+          lastError: error.code || 'CHANNEL_PROCESSING_FAILED'
+        }, storeContext);
+      }
+      throw error;
+    }
+  }
+
+  async _handleDecision({
+    adapter,
+    context,
+    decision,
+    emit,
+    envelope,
+    principal,
+    scope,
+    storeContext,
+    pendingTurn,
+    turn
+  }) {
+    turn = await this.turnStore.transition(turn, 'processing', {}, storeContext);
+    const pending = pendingTurn && await this.turnStore.claimPending({
+      ...scope, turnId: pendingTurn.id, pendingActions: pendingTurn.pendingActions
+    }, storeContext);
+    if (!pending) {
+      const output = await this.render({
+        channel: envelope.channel,
+        envelope,
+        plan: { content: 'There are no pending actions for this conversation.' },
+        results: [],
+        pendingActions: [],
+        decision,
+        context
+      });
+      turn = await this.turnStore.transition(turn, 'completed', { output, results: [] }, storeContext);
+      return await this._result(adapter, turn, envelope, context, false);
+    }
+
+    if (pending.id !== pendingTurn.id ||
+        pending.tenantKey !== scope.tenantKey || pending.actorKey !== scope.actorKey ||
+        pending.channel !== scope.channel || pending.threadKey !== scope.threadKey ||
+        pending.status !== 'executing' || pending.sourceKey === envelope.sourceKey ||
+        !(new Date(pending.expiresAt) > this.now()) ||
+        actionSignature(pending.pendingActions) !== actionSignature(pendingTurn.pendingActions)) {
+      throw new SecurityError('Pending action changed before confirmation');
+    }
+
+    if (decision === 'cancel') {
+      await this.turnStore.transition(pending, 'cancelled', {}, storeContext);
+      const output = await this.render({
+        channel: envelope.channel,
+        envelope,
+        plan: { content: 'The pending action was cancelled.' },
+        results: [],
+        pendingActions: [],
+        decision,
+        context
+      });
+      turn = await this.turnStore.transition(turn, 'completed', {
+        output,
+        results: [],
+        resolvedTurnId: pending.id
+      }, storeContext);
+      return await this._result(adapter, turn, envelope, context, false);
+    }
+
+    try {
+      const pendingActions = pending.pendingActions || [];
+      const authorization = await this.authorize({
+        principal,
+        envelope,
+        turn: pending,
+        plan: pending.plan,
+        actions: pendingActions,
+        confirmed: true,
+        context
+      });
+      const classified = classifyActions(pendingActions, authorization);
+      const executable = classified
+        .filter(item => item.decision !== 'reject')
+        .map(item => item.action);
+      const results = classified
+        .filter(item => item.decision === 'reject')
+        .map(item => ({ action: item.action, status: 'rejected', message: item.reason }));
+      results.push(...await this._executeActions(
+        principal,
+        pending,
+        executable,
+        envelope,
+        emit,
+        context,
+        { decision: 'confirm', turnId: pending.id, sourceKey: envelope.sourceKey }
+      ));
+
+      const output = await this.render({
+        channel: envelope.channel,
+        envelope,
+        plan: pending.plan,
+        results,
+        pendingActions: [],
+        decision,
+        context
+      });
+      await this.turnStore.transition(
+        pending,
+        'completed',
+        { output, results, pendingActions: [] },
+        storeContext
+      );
+      turn = await this.turnStore.transition(turn, 'completed', {
+        output,
+        results,
+        resolvedTurnId: pending.id
+      }, storeContext);
+      await emit({ type: 'turn', status: turn.status, turnId: turn.id });
+      return await this._result(adapter, turn, envelope, context, false);
+    } catch (error) {
+      await this.turnStore.transition(pending, 'failed', {
+        lastError: error.code || 'CHANNEL_CONFIRMATION_FAILED'
+      }, storeContext);
+      throw error;
+    }
+  }
+
+  async _executeActions(principal, turn, actions, envelope, emit, context, confirmation = null) {
+    const results = [];
+    for (let index = 0; index < actions.length; index++) {
+      const action = actions[index];
+      await emit({ type: 'action', status: 'executing', action, turnId: turn.id });
+      try {
+        const execution = await this.execute({
+          principal,
+          action,
+          envelope,
+          turn,
+          context,
+          confirmation,
+          idempotencyKey: actionIdempotencyKey(turn, action, index)
+        });
+        const succeeded = !execution || !['error', 'failed', 'rejected'].includes(execution.status);
+        results.push(succeeded
+          ? { action, status: 'succeeded', result: execution?.result ?? execution }
+          : { action, status: 'failed', message: execution.message || 'Action failed' });
+      } catch (error) {
+        await this.onError(error, { turn, envelope, action });
+        results.push({ action, status: 'failed', message: 'Action failed' });
+      }
+      await emit({ type: 'action', ...results.at(-1), turnId: turn.id });
+    }
+    return results;
+  }
+
+  async _result(adapter, turn, envelope, context, duplicate) {
+    const response = typeof adapter.format === 'function'
+      ? await adapter.format(turn.output || {}, { envelope, turn, context, duplicate })
+      : turn.output;
+    return { turn, output: turn.output || null, response, duplicate };
+  }
+}
+
+module.exports = {
+  ChannelRuntime,
+  ChannelRuntimeError,
+  EnvelopeValidationError,
+  SecurityError,
+  RateLimitError,
+  TURN_STATUSES,
+  TURN_TRANSITIONS,
+  parseDecision
+};

package/src/twilio.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const crypto = require('crypto');
+const { EnvelopeValidationError } = require('./runtime');
+
+function loadTwilio(injected) {
+  if (injected) return injected;
+  return require('twilio');
+}
+
+function signatureFrom(context) {
+  const headers = context.headers || {};
+  const key = Object.keys(headers).find(name => name.toLowerCase() === 'x-twilio-signature');
+  return key ? headers[key] : null;
+}
+
+function addTurnKey(url, turnKey) {
+  const parsed = new URL(url);
+  parsed.searchParams.set('turnKey', turnKey);
+  return parsed.toString();
+}
+
+function nextVoiceTurnKey(turn) {
+  if (!turn?.id) throw new EnvelopeValidationError('Voice response requires a persisted turn');
+  return crypto.createHash('sha256').update(String(turn.id)).digest('hex').slice(0, 32);
+}
+
+function voiceInput(body) {
+  if (typeof body.SpeechResult === 'string') return body.SpeechResult;
+  if (typeof body.Digits === 'string') return body.Digits;
+  return '';
+}
+
+function createTwilioChannels({
+  authToken,
+  accountSid = null,
+  twilio: injectedTwilio = null,
+  client: injectedClient = null,
+  messagingServiceSid = null,
+  smsFrom = null,
+  voiceFrom = null,
+  voiceActionUrl = null,
+  voice = 'Polly.Joanna',
+  language = 'en-US',
+  gatherPrompt = 'How else can I help?'
+} = {}) {
+  if (typeof authToken !== 'string' || authToken === '') {
+    throw new TypeError('Twilio authToken is required');
+  }
+  const twilio = loadTwilio(injectedTwilio);
+
+  async function authenticate(envelope, context) {
+    const signature = signatureFrom(context);
+    const url = context.url;
+    if (!signature || typeof url !== 'string' || url === '') {
+      return { allowed: false, provider: 'twilio', reason: 'Missing Twilio signature context' };
+    }
+    const allowed = twilio.validateRequest(authToken, signature, url, context.params || {});
+    return {
+      allowed,
+      method: 'twilio-signature',
+      provider: 'twilio',
+      accountKey: envelope.providerAccountKey,
+      ...(allowed ? {} : { reason: 'Invalid Twilio signature' })
+    };
+  }
+
+  const sms = {
+    async normalize(payload) {
+      const mediaCount = Number.parseInt(payload?.NumMedia || '0', 10) || 0;
+      const attachments = Array.from({ length: mediaCount }, (_, index) => ({
+        url: payload[`MediaUrl${index}`],
+        contentType: payload[`MediaContentType${index}`] || null
+      }));
+      return {
+        channel: 'sms',
+        sourceKey: payload?.MessageSid || payload?.SmsSid || '',
+        threadKey: payload?.From && payload?.To ? `${payload.From}:${payload.To}` : '',
+        sender: payload?.From || null,
+        recipient: payload?.To || null,
+        text: payload?.Body || '',
+        attachments,
+        providerAccountKey: payload?.AccountSid || null,
+        metadata: {
+          messagingServiceSid: payload?.MessagingServiceSid || null,
+          numSegments: payload?.NumSegments || null
+        }
+      };
+    },
+    authenticate,
+    async format(output) {
+      const response = new twilio.twiml.MessagingResponse();
+      response.message(output.content || '');
+      return { contentType: 'text/xml', body: response.toString() };
+    }
+  };
+
+  const voiceChannel = {
+    async normalize(payload, context) {
+      const text = voiceInput(payload || {});
+      const turnKey = context.turnKey || payload?.EventSid || payload?.SequenceNumber;
+      if (text && !turnKey) {
+        throw new EnvelopeValidationError('Twilio Voice speech callbacks require a turnKey');
+      }
+      return {
+        channel: 'voice',
+        sourceKey: payload?.CallSid ? `${payload.CallSid}:${turnKey || 'initial'}` : '',
+        threadKey: payload?.CallSid || '',
+        sender: payload?.From || null,
+        recipient: payload?.To || null,
+        text,
+        attachments: [],
+        providerAccountKey: payload?.AccountSid || null,
+        metadata: {
+          callStatus: payload?.CallStatus || null,
+          confidence: payload?.Confidence ?? null
+        }
+      };
+    },
+    authenticate,
+    async format(output, { envelope, turn, context }) {
+      const response = new twilio.twiml.VoiceResponse();
+      if (output.content) response.say({ voice, language }, output.content);
+      if (output.endConversation) {
+        response.hangup();
+      } else {
+        const baseActionUrl = typeof voiceActionUrl === 'function'
+          ? await voiceActionUrl({ envelope, context })
+          : voiceActionUrl;
+        if (!baseActionUrl) throw new EnvelopeValidationError('voiceActionUrl is required');
+        const gather = response.gather({
+          input: 'speech dtmf',
+          action: addTurnKey(baseActionUrl, nextVoiceTurnKey(turn)),
+          method: 'POST',
+          actionOnEmptyResult: true,
+          speechTimeout: 'auto'
+        });
+        gather.say({ voice, language }, gatherPrompt);
+      }
+      return { contentType: 'text/xml', body: response.toString() };
+    }
+  };
+
+  function getClient() {
+    if (injectedClient) return injectedClient;
+    if (!accountSid) throw new TypeError('Twilio accountSid is required for outbound calls');
+    return twilio(accountSid, authToken);
+  }
+
+  async function sendSms({ to, body, from = smsFrom, statusCallback = null }) {
+    if (!to || !body) throw new TypeError('SMS to and body are required');
+    if (!from && !messagingServiceSid) {
+      throw new TypeError('smsFrom or messagingServiceSid is required');
+    }
+    return await getClient().messages.create({
+      to,
+      body,
+      ...(messagingServiceSid ? { messagingServiceSid } : { from }),
+      ...(statusCallback ? { statusCallback } : {})
+    });
+  }
+
+  async function startCall({ to, url, from = voiceFrom, statusCallback = null }) {
+    if (!to || !from || !url) throw new TypeError('Voice to, from, and url are required');
+    return await getClient().calls.create({
+      to,
+      from,
+      url,
+      ...(statusCallback ? { statusCallback } : {})
+    });
+  }
+
+  return { sms, voice: voiceChannel, sendSms, startCall };
+}
+
+module.exports = { createTwilioChannels };