@contractspec/integration.runtime 2.9.0 → 3.0.0

package/dist/channel/service.js

@@ -0,0 +1,287 @@
+// @bun
+// src/channel/policy.ts
+var DEFAULT_MESSAGING_POLICY_CONFIG = {
+  autoResolveMinConfidence: 0.85,
+  assistMinConfidence: 0.65,
+  blockedSignals: [
+    "ignore previous instructions",
+    "reveal secret",
+    "api key",
+    "password",
+    "token",
+    "drop table",
+    "delete repository"
+  ],
+  highRiskSignals: [
+    "refund",
+    "delete account",
+    "cancel subscription",
+    "permission",
+    "admin access",
+    "wire transfer",
+    "bank account"
+  ],
+  mediumRiskSignals: [
+    "urgent",
+    "legal",
+    "compliance",
+    "frustrated",
+    "escalate",
+    "outage"
+  ],
+  safeAckTemplate: "Thanks for your message. We received it and are preparing the next step."
+};
+
+class MessagingPolicyEngine {
+  config;
+  constructor(config) {
+    this.config = {
+      ...DEFAULT_MESSAGING_POLICY_CONFIG,
+      ...config ?? {}
+    };
+  }
+  evaluate(input) {
+    const text = (input.event.message?.text ?? "").toLowerCase();
+    if (containsAny(text, this.config.blockedSignals)) {
+      return {
+        confidence: 0.2,
+        riskTier: "blocked",
+        verdict: "blocked",
+        reasons: ["blocked_signal_detected"],
+        responseText: this.config.safeAckTemplate,
+        requiresApproval: true
+      };
+    }
+    if (containsAny(text, this.config.highRiskSignals)) {
+      return {
+        confidence: 0.55,
+        riskTier: "high",
+        verdict: "assist",
+        reasons: ["high_risk_topic_detected"],
+        responseText: this.config.safeAckTemplate,
+        requiresApproval: true
+      };
+    }
+    const mediumRiskDetected = containsAny(text, this.config.mediumRiskSignals);
+    const confidence = mediumRiskDetected ? 0.74 : 0.92;
+    const riskTier = mediumRiskDetected ? "medium" : "low";
+    if (confidence >= this.config.autoResolveMinConfidence && riskTier === "low") {
+      return {
+        confidence,
+        riskTier,
+        verdict: "autonomous",
+        reasons: ["low_risk_high_confidence"],
+        responseText: this.defaultResponseText(input.event),
+        requiresApproval: false
+      };
+    }
+    if (confidence >= this.config.assistMinConfidence) {
+      return {
+        confidence,
+        riskTier,
+        verdict: "assist",
+        reasons: ["needs_human_review"],
+        responseText: this.config.safeAckTemplate,
+        requiresApproval: true
+      };
+    }
+    return {
+      confidence,
+      riskTier: "blocked",
+      verdict: "blocked",
+      reasons: ["low_confidence"],
+      responseText: this.config.safeAckTemplate,
+      requiresApproval: true
+    };
+  }
+  defaultResponseText(event) {
+    if (!event.message?.text) {
+      return this.config.safeAckTemplate;
+    }
+    return `Acknowledged: ${event.message.text.slice(0, 240)}`;
+  }
+}
+function containsAny(text, candidates) {
+  return candidates.some((candidate) => text.includes(candidate));
+}
+
+// src/channel/service.ts
+import { createHash, randomUUID } from "crypto";
+class ChannelRuntimeService {
+  store;
+  policy;
+  asyncProcessing;
+  processInBackground;
+  modelName;
+  promptVersion;
+  policyVersion;
+  telemetry;
+  constructor(store, options = {}) {
+    this.store = store;
+    this.policy = options.policy ?? new MessagingPolicyEngine;
+    this.asyncProcessing = options.asyncProcessing ?? true;
+    this.processInBackground = options.processInBackground ?? ((task) => {
+      setTimeout(() => {
+        task();
+      }, 0);
+    });
+    this.modelName = options.modelName ?? "policy-heuristics-v1";
+    this.promptVersion = options.promptVersion ?? "channel-runtime.v1";
+    this.policyVersion = options.policyVersion ?? "messaging-policy.v1";
+    this.telemetry = options.telemetry;
+  }
+  async ingest(event) {
+    const startedAtMs = Date.now();
+    const claim = await this.store.claimEventReceipt({
+      workspaceId: event.workspaceId,
+      providerKey: event.providerKey,
+      externalEventId: event.externalEventId,
+      eventType: event.eventType,
+      signatureValid: event.signatureValid,
+      payloadHash: event.rawPayload ? sha256(event.rawPayload) : undefined,
+      traceId: event.traceId
+    });
+    if (claim.duplicate) {
+      this.telemetry?.record({
+        stage: "ingest",
+        status: "duplicate",
+        workspaceId: event.workspaceId,
+        providerKey: event.providerKey,
+        receiptId: claim.receiptId,
+        traceId: event.traceId,
+        latencyMs: Date.now() - startedAtMs
+      });
+      return {
+        status: "duplicate",
+        receiptId: claim.receiptId
+      };
+    }
+    this.telemetry?.record({
+      stage: "ingest",
+      status: "accepted",
+      workspaceId: event.workspaceId,
+      providerKey: event.providerKey,
+      receiptId: claim.receiptId,
+      traceId: event.traceId,
+      latencyMs: Date.now() - startedAtMs
+    });
+    const task = async () => {
+      await this.processAcceptedEvent(claim.receiptId, event);
+    };
+    if (this.asyncProcessing) {
+      this.processInBackground(task);
+    } else {
+      await task();
+    }
+    return {
+      status: "accepted",
+      receiptId: claim.receiptId
+    };
+  }
+  async processAcceptedEvent(receiptId, event) {
+    try {
+      await this.store.updateReceiptStatus(receiptId, "processing");
+      const thread = await this.store.upsertThread({
+        workspaceId: event.workspaceId,
+        providerKey: event.providerKey,
+        externalThreadId: event.thread.externalThreadId,
+        externalChannelId: event.thread.externalChannelId,
+        externalUserId: event.thread.externalUserId,
+        occurredAt: event.occurredAt
+      });
+      const policyDecision = this.policy.evaluate({ event });
+      this.telemetry?.record({
+        stage: "decision",
+        status: "processed",
+        workspaceId: event.workspaceId,
+        providerKey: event.providerKey,
+        receiptId,
+        traceId: event.traceId,
+        metadata: {
+          verdict: policyDecision.verdict,
+          riskTier: policyDecision.riskTier,
+          confidence: policyDecision.confidence
+        }
+      });
+      const decision = await this.store.saveDecision({
+        receiptId,
+        threadId: thread.id,
+        policyMode: policyDecision.verdict === "autonomous" ? "autonomous" : "assist",
+        riskTier: policyDecision.riskTier,
+        confidence: policyDecision.confidence,
+        modelName: this.modelName,
+        promptVersion: this.promptVersion,
+        policyVersion: this.policyVersion,
+        actionPlan: {
+          verdict: policyDecision.verdict,
+          reasons: policyDecision.reasons
+        },
+        requiresApproval: policyDecision.requiresApproval
+      });
+      if (policyDecision.verdict === "autonomous") {
+        await this.store.enqueueOutboxAction({
+          workspaceId: event.workspaceId,
+          providerKey: event.providerKey,
+          decisionId: decision.id,
+          threadId: thread.id,
+          actionType: "reply",
+          idempotencyKey: buildOutboxIdempotencyKey(event, policyDecision.responseText),
+          target: {
+            externalThreadId: event.thread.externalThreadId,
+            externalChannelId: event.thread.externalChannelId,
+            externalUserId: event.thread.externalUserId
+          },
+          payload: {
+            id: randomUUID(),
+            text: policyDecision.responseText
+          }
+        });
+        this.telemetry?.record({
+          stage: "outbox",
+          status: "accepted",
+          workspaceId: event.workspaceId,
+          providerKey: event.providerKey,
+          receiptId,
+          traceId: event.traceId,
+          metadata: {
+            actionType: "reply"
+          }
+        });
+      }
+      await this.store.updateReceiptStatus(receiptId, "processed");
+      this.telemetry?.record({
+        stage: "ingest",
+        status: "processed",
+        workspaceId: event.workspaceId,
+        providerKey: event.providerKey,
+        receiptId,
+        traceId: event.traceId
+      });
+    } catch (error) {
+      await this.store.updateReceiptStatus(receiptId, "failed", {
+        code: "PROCESSING_FAILED",
+        message: error instanceof Error ? error.message : String(error)
+      });
+      this.telemetry?.record({
+        stage: "ingest",
+        status: "failed",
+        workspaceId: event.workspaceId,
+        providerKey: event.providerKey,
+        receiptId,
+        traceId: event.traceId,
+        metadata: {
+          errorCode: "PROCESSING_FAILED"
+        }
+      });
+    }
+  }
+}
+function buildOutboxIdempotencyKey(event, responseText) {
+  return sha256(`${event.workspaceId}:${event.providerKey}:${event.externalEventId}:reply:${responseText}`);
+}
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+export {
+  ChannelRuntimeService
+};

package/dist/channel/service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/channel/slack.d.ts

@@ -0,0 +1,42 @@
+import type { ChannelInboundEvent } from './types';
+export interface SlackWebhookEnvelope {
+    type: string;
+    team_id?: string;
+    api_app_id?: string;
+    event_id?: string;
+    event_time?: number;
+    challenge?: string;
+    event?: {
+        type?: string;
+        user?: string;
+        text?: string;
+        ts?: string;
+        thread_ts?: string;
+        channel?: string;
+        subtype?: string;
+        bot_id?: string;
+    };
+}
+export interface SlackSignatureVerificationInput {
+    signingSecret: string;
+    requestTimestamp: string | null;
+    requestSignature: string | null;
+    rawBody: string;
+    nowMs?: number;
+    toleranceSeconds?: number;
+}
+export interface SignatureVerificationResult {
+    valid: boolean;
+    reason?: string;
+}
+export declare function verifySlackSignature(input: SlackSignatureVerificationInput): SignatureVerificationResult;
+export declare function parseSlackWebhookPayload(rawBody: string): SlackWebhookEnvelope;
+export declare function isSlackUrlVerificationPayload(payload: SlackWebhookEnvelope): boolean;
+export interface NormalizeSlackEventInput {
+    workspaceId: string;
+    payload: SlackWebhookEnvelope;
+    signatureValid: boolean;
+    traceId?: string;
+    rawBody?: string;
+}
+export declare function normalizeSlackInboundEvent(input: NormalizeSlackEventInput): ChannelInboundEvent | null;

package/dist/channel/slack.js

@@ -0,0 +1,82 @@
+// @bun
+// src/channel/slack.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifySlackSignature(input) {
+  if (!input.requestTimestamp || !input.requestSignature) {
+    return { valid: false, reason: "missing_signature_headers" };
+  }
+  const timestamp = Number.parseInt(input.requestTimestamp, 10);
+  if (!Number.isFinite(timestamp)) {
+    return { valid: false, reason: "invalid_timestamp" };
+  }
+  const nowMs = input.nowMs ?? Date.now();
+  const toleranceMs = (input.toleranceSeconds ?? 300) * 1000;
+  if (Math.abs(nowMs - timestamp * 1000) > toleranceMs) {
+    return { valid: false, reason: "timestamp_out_of_range" };
+  }
+  const base = `v0:${input.requestTimestamp}:${input.rawBody}`;
+  const expected = `v0=${createHmac("sha256", input.signingSecret).update(base).digest("hex")}`;
+  const receivedBuffer = Buffer.from(input.requestSignature, "utf8");
+  const expectedBuffer = Buffer.from(expected, "utf8");
+  if (receivedBuffer.length !== expectedBuffer.length) {
+    return { valid: false, reason: "signature_length_mismatch" };
+  }
+  const valid = timingSafeEqual(receivedBuffer, expectedBuffer);
+  return valid ? { valid: true } : { valid: false, reason: "signature_mismatch" };
+}
+function parseSlackWebhookPayload(rawBody) {
+  const parsed = JSON.parse(rawBody);
+  return parsed;
+}
+function isSlackUrlVerificationPayload(payload) {
+  return payload.type === "url_verification";
+}
+function normalizeSlackInboundEvent(input) {
+  if (input.payload.type !== "event_callback") {
+    return null;
+  }
+  const event = input.payload.event;
+  if (!event?.type) {
+    return null;
+  }
+  if (event.subtype === "bot_message" || event.bot_id) {
+    return null;
+  }
+  const externalEventId = input.payload.event_id ?? event.ts;
+  if (!externalEventId) {
+    return null;
+  }
+  const threadId = event.thread_ts ?? event.ts ?? externalEventId;
+  if (!threadId) {
+    return null;
+  }
+  return {
+    workspaceId: input.workspaceId,
+    providerKey: "messaging.slack",
+    externalEventId,
+    eventType: `slack.${event.type}`,
+    occurredAt: input.payload.event_time ? new Date(input.payload.event_time * 1000) : new Date,
+    signatureValid: input.signatureValid,
+    traceId: input.traceId,
+    rawPayload: input.rawBody,
+    thread: {
+      externalThreadId: threadId,
+      externalChannelId: event.channel,
+      externalUserId: event.user
+    },
+    message: event.text ? {
+      text: event.text,
+      externalMessageId: event.ts
+    } : undefined,
+    metadata: {
+      slackEventType: event.type,
+      slackTeamId: input.payload.team_id ?? input.workspaceId
+    }
+  };
+}
+export {
+  verifySlackSignature,
+  parseSlackWebhookPayload,
+  normalizeSlackInboundEvent,
+  isSlackUrlVerificationPayload
+};

package/dist/channel/slack.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/channel/store.d.ts

@@ -0,0 +1,83 @@
+import type { ChannelDecisionRecord, ChannelDeliveryAttemptRecord, ChannelEventReceiptRecord, ChannelOutboxActionRecord, ChannelThreadRecord } from './types';
+export interface ClaimEventReceiptInput {
+    workspaceId: string;
+    providerKey: string;
+    externalEventId: string;
+    eventType: string;
+    signatureValid: boolean;
+    payloadHash?: string;
+    traceId?: string;
+}
+export interface ClaimEventReceiptResult {
+    receiptId: string;
+    duplicate: boolean;
+}
+export interface UpsertThreadInput {
+    workspaceId: string;
+    providerKey: string;
+    externalThreadId: string;
+    externalChannelId?: string;
+    externalUserId?: string;
+    state?: Record<string, unknown>;
+    occurredAt?: Date;
+}
+export interface SaveDecisionInput {
+    receiptId: string;
+    threadId: string;
+    policyMode: 'suggest' | 'assist' | 'autonomous';
+    riskTier: 'low' | 'medium' | 'high' | 'blocked';
+    confidence: number;
+    modelName: string;
+    promptVersion: string;
+    policyVersion: string;
+    toolTrace?: Record<string, unknown>[];
+    actionPlan: Record<string, unknown>;
+    requiresApproval: boolean;
+}
+export interface EnqueueOutboxActionInput {
+    workspaceId: string;
+    providerKey: string;
+    decisionId: string;
+    threadId: string;
+    actionType: string;
+    idempotencyKey: string;
+    target: Record<string, unknown>;
+    payload: Record<string, unknown>;
+}
+export interface EnqueueOutboxActionResult {
+    actionId: string;
+    duplicate: boolean;
+}
+export interface RecordDeliveryAttemptInput {
+    actionId: string;
+    attempt: number;
+    responseStatus?: number;
+    responseBody?: string;
+    latencyMs?: number;
+}
+export interface MarkOutboxRetryInput {
+    actionId: string;
+    nextAttemptAt: Date;
+    lastErrorCode: string;
+    lastErrorMessage: string;
+}
+export interface MarkOutboxDeadLetterInput {
+    actionId: string;
+    lastErrorCode: string;
+    lastErrorMessage: string;
+}
+export interface ChannelRuntimeStore {
+    claimEventReceipt(input: ClaimEventReceiptInput): Promise<ClaimEventReceiptResult>;
+    updateReceiptStatus(receiptId: string, status: ChannelEventReceiptRecord['status'], error?: {
+        code: string;
+        message: string;
+    }): Promise<void>;
+    upsertThread(input: UpsertThreadInput): Promise<ChannelThreadRecord>;
+    saveDecision(input: SaveDecisionInput): Promise<ChannelDecisionRecord>;
+    enqueueOutboxAction(input: EnqueueOutboxActionInput): Promise<EnqueueOutboxActionResult>;
+    claimPendingOutboxActions(limit: number, now?: Date): Promise<ChannelOutboxActionRecord[]>;
+    recordDeliveryAttempt(input: RecordDeliveryAttemptInput): Promise<ChannelDeliveryAttemptRecord>;
+    markOutboxSent(actionId: string, providerMessageId?: string): Promise<void>;
+    markOutboxRetry(input: MarkOutboxRetryInput): Promise<void>;
+    markOutboxDeadLetter(input: MarkOutboxDeadLetterInput): Promise<void>;
+}

package/dist/channel/store.js

@@ -0,0 +1 @@
+// @bun

package/dist/channel/telemetry.d.ts

@@ -0,0 +1,17 @@
+export type ChannelTelemetryStage = 'ingest' | 'decision' | 'outbox' | 'dispatch';
+export type ChannelTelemetryStatus = 'accepted' | 'duplicate' | 'processed' | 'failed' | 'sent' | 'retry' | 'dead_letter';
+export interface ChannelTelemetryEvent {
+    stage: ChannelTelemetryStage;
+    status: ChannelTelemetryStatus;
+    workspaceId?: string;
+    providerKey?: string;
+    receiptId?: string;
+    actionId?: string;
+    traceId?: string;
+    latencyMs?: number;
+    attempt?: number;
+    metadata?: Record<string, string | number | boolean>;
+}
+export interface ChannelTelemetryEmitter {
+    record(event: ChannelTelemetryEvent): Promise<void> | void;
+}

package/dist/channel/telemetry.js

@@ -0,0 +1 @@
+// @bun

package/dist/channel/types.d.ts

@@ -0,0 +1,111 @@
+export type ChannelProviderKey = 'messaging.slack' | 'messaging.github' | 'messaging.whatsapp.meta' | 'messaging.whatsapp.twilio' | (string & {});
+export interface ChannelThreadRef {
+    externalThreadId: string;
+    externalChannelId?: string;
+    externalUserId?: string;
+}
+export interface InboundMessage {
+    text: string;
+    externalMessageId?: string;
+}
+export interface ChannelInboundEvent {
+    workspaceId: string;
+    providerKey: ChannelProviderKey;
+    externalEventId: string;
+    eventType: string;
+    occurredAt: Date;
+    signatureValid: boolean;
+    traceId?: string;
+    thread: ChannelThreadRef;
+    message?: InboundMessage;
+    metadata?: Record<string, string>;
+    rawPayload?: string;
+}
+export type ChannelRiskTier = 'low' | 'medium' | 'high' | 'blocked';
+export type ChannelPolicyVerdict = 'autonomous' | 'assist' | 'blocked';
+export interface ChannelPolicyDecision {
+    confidence: number;
+    riskTier: ChannelRiskTier;
+    verdict: ChannelPolicyVerdict;
+    reasons: string[];
+    responseText: string;
+    requiresApproval: boolean;
+}
+export interface ChannelEventReceiptRecord {
+    id: string;
+    workspaceId: string;
+    providerKey: string;
+    externalEventId: string;
+    eventType: string;
+    status: 'accepted' | 'processing' | 'processed' | 'duplicate' | 'failed' | 'rejected';
+    signatureValid: boolean;
+    payloadHash?: string;
+    traceId?: string;
+    firstSeenAt: Date;
+    lastSeenAt: Date;
+    processedAt?: Date;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface ChannelThreadRecord {
+    id: string;
+    workspaceId: string;
+    providerKey: string;
+    externalThreadId: string;
+    externalChannelId?: string;
+    externalUserId?: string;
+    state: Record<string, unknown>;
+    lastProviderEventAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface ChannelDecisionRecord {
+    id: string;
+    receiptId: string;
+    threadId: string;
+    policyMode: 'suggest' | 'assist' | 'autonomous';
+    riskTier: ChannelRiskTier;
+    confidence: number;
+    modelName: string;
+    promptVersion: string;
+    policyVersion: string;
+    toolTrace: Record<string, unknown>[];
+    actionPlan: Record<string, unknown>;
+    requiresApproval: boolean;
+    approvedBy?: string;
+    approvedAt?: Date;
+    createdAt: Date;
+}
+export interface ChannelOutboxActionRecord {
+    id: string;
+    workspaceId: string;
+    providerKey: string;
+    decisionId: string;
+    threadId: string;
+    actionType: string;
+    idempotencyKey: string;
+    target: Record<string, unknown>;
+    payload: Record<string, unknown>;
+    status: 'pending' | 'sending' | 'sent' | 'retryable' | 'failed' | 'dead_letter' | 'cancelled';
+    attemptCount: number;
+    nextAttemptAt: Date;
+    providerMessageId?: string;
+    lastErrorCode?: string;
+    lastErrorMessage?: string;
+    createdAt: Date;
+    updatedAt: Date;
+    sentAt?: Date;
+}
+export interface ChannelDeliveryAttemptRecord {
+    id: number;
+    actionId: string;
+    attempt: number;
+    responseStatus?: number;
+    responseBody?: string;
+    latencyMs?: number;
+    createdAt: Date;
+}
+export interface ChannelIngestResult {
+    status: 'accepted' | 'duplicate';
+    receiptId: string;
+}

package/dist/channel/types.js

@@ -0,0 +1 @@
+// @bun

package/dist/channel/whatsapp-meta.d.ts

@@ -0,0 +1,55 @@
+import type { ChannelInboundEvent } from './types';
+export interface MetaWhatsappWebhookPayload {
+    object?: string;
+    entry?: {
+        id?: string;
+        changes?: {
+            field?: string;
+            value?: {
+                metadata?: {
+                    phone_number_id?: string;
+                    display_phone_number?: string;
+                };
+                contacts?: {
+                    wa_id?: string;
+                    profile?: {
+                        name?: string;
+                    };
+                }[];
+                messages?: {
+                    id?: string;
+                    from?: string;
+                    timestamp?: string;
+                    type?: string;
+                    text?: {
+                        body?: string;
+                    };
+                }[];
+                statuses?: {
+                    id?: string;
+                    recipient_id?: string;
+                    status?: string;
+                    timestamp?: string;
+                }[];
+            };
+        }[];
+    }[];
+}
+export interface MetaSignatureVerificationInput {
+    appSecret: string;
+    signatureHeader: string | null;
+    rawBody: string;
+}
+export interface MetaSignatureVerificationResult {
+    valid: boolean;
+    reason?: string;
+}
+export declare function verifyMetaSignature(input: MetaSignatureVerificationInput): MetaSignatureVerificationResult;
+export declare function parseMetaWebhookPayload(rawBody: string): MetaWhatsappWebhookPayload;
+export declare function normalizeMetaWhatsappInboundEvents(input: {
+    workspaceId: string;
+    payload: MetaWhatsappWebhookPayload;
+    signatureValid: boolean;
+    traceId?: string;
+    rawBody?: string;
+}): ChannelInboundEvent[];