@bliggy/chat-runtime 0.0.0-stage → 0.3.0

package/src/pendingActions.js

@@ -0,0 +1,37 @@
+'use strict';
+
+// Select from an already authorized queue without executing or changing it.
+// Callers own confirmation interpretation, atomic claiming, authorization at
+// execution time, and receipts. A warning requires explicit approval; a general
+// confirmation cannot override it. Existing ids and action objects are retained.
+function selectPendingActions(actions, { decision, actionId = null } = {}) {
+  if (!Array.isArray(actions)) throw new TypeError('actions must be an array');
+  const unchanged = reason => ({ selected: [], remaining: [...actions], reason });
+  if (actions.length === 0) return unchanged('empty');
+  if (!['confirm', 'confirm_including_flagged', 'cancel'].includes(decision)) {
+    return unchanged('unconfirmed');
+  }
+
+  if (actionId !== null && actionId !== undefined) {
+    const index = actions.findIndex(action => String(action.id) === String(actionId));
+    if (index === -1) return unchanged('not_found');
+    return {
+      selected: [actions[index]],
+      remaining: actions.filter((_, actionIndex) => actionIndex !== index),
+      reason: null
+    };
+  }
+
+  if (decision === 'cancel' || decision === 'confirm_including_flagged') {
+    return { selected: [...actions], remaining: [], reason: null };
+  }
+
+  const selected = [];
+  const remaining = [];
+  for (const action of actions) {
+    (action.warning ? remaining : selected).push(action);
+  }
+  return { selected, remaining, reason: selected.length === 0 ? 'all_flagged' : null };
+}
+
+module.exports = { selectPendingActions };

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