@vellumai/assistant 0.6.5 → 0.7.0

package/node_modules/@vellumai/gateway-client/src/http-delivery.ts

@@ -0,0 +1,422 @@
+/**
+ * HTTP delivery client for assistant-to-gateway channel replies.
+ *
+ * Handles both direct callback delivery and managed outbound delivery
+ * (platform-routed phone/SMS channels) with retry/idempotency semantics.
+ */
+
+import { createHash } from "node:crypto";
+
+import type {
+  ChannelDeliveryResult,
+  ChannelReplyPayload,
+  Logger,
+} from "./types.js";
+import { noopLogger } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+/**
+ * Error thrown when the gateway returns a non-OK response for channel delivery.
+ * Carries the optional `userMessage` field from the gateway so callers can
+ * surface actionable error text to end-users.
+ */
+export class ChannelDeliveryError extends Error {
+  readonly statusCode: number;
+  /** A user-facing error message from the gateway, if available. */
+  readonly userMessage?: string;
+
+  constructor(statusCode: number, body: string, userMessage?: string) {
+    super(`Channel reply delivery failed (${statusCode}): ${body}`);
+    this.name = "ChannelDeliveryError";
+    this.statusCode = statusCode;
+    this.userMessage = userMessage;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DELIVERY_TIMEOUT_MS = 30_000;
+const MANAGED_OUTBOUND_SEND_PATH =
+  "/v1/internal/managed-gateway/outbound-send/";
+const MANAGED_CALLBACK_TOKEN_HEADER = "X-Managed-Gateway-Callback-Token";
+const MANAGED_IDEMPOTENCY_HEADER = "X-Idempotency-Key";
+const MANAGED_OUTBOUND_MAX_ATTEMPTS = 3;
+const MANAGED_OUTBOUND_RETRY_BASE_MS = 150;
+
+// ---------------------------------------------------------------------------
+// Internal types
+// ---------------------------------------------------------------------------
+
+interface ManagedOutboundCallbackContext {
+  requestUrl: string;
+  routeId: string;
+  assistantId: string;
+  sourceChannel: "phone";
+  sourceUpdateId?: string;
+  callbackToken?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Managed callback URL parsing
+// ---------------------------------------------------------------------------
+
+function parseManagedOutboundCallback(
+  callbackUrl: string,
+): ManagedOutboundCallbackContext | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(callbackUrl);
+  } catch {
+    return null;
+  }
+
+  const normalizedPath = parsed.pathname.endsWith("/")
+    ? parsed.pathname
+    : `${parsed.pathname}/`;
+  if (normalizedPath !== MANAGED_OUTBOUND_SEND_PATH) {
+    return null;
+  }
+
+  const routeId = parsed.searchParams.get("route_id")?.trim();
+  const assistantId = parsed.searchParams.get("assistant_id")?.trim();
+  const sourceChannel = parsed.searchParams.get("source_channel")?.trim();
+
+  if (!routeId || !assistantId || sourceChannel !== "phone") {
+    throw new Error(
+      "Managed outbound callback URL is missing required route_id, assistant_id, or source_channel.",
+    );
+  }
+
+  const sourceUpdateId = parsed.searchParams.get("source_update_id")?.trim();
+  const callbackToken = parsed.searchParams.get("callback_token")?.trim();
+
+  parsed.searchParams.delete("route_id");
+  parsed.searchParams.delete("assistant_id");
+  parsed.searchParams.delete("source_channel");
+  parsed.searchParams.delete("source_update_id");
+  parsed.searchParams.delete("callback_token");
+
+  return {
+    requestUrl: parsed.toString(),
+    routeId,
+    assistantId,
+    sourceChannel,
+    sourceUpdateId,
+    callbackToken,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Idempotency key generation
+// ---------------------------------------------------------------------------
+
+function buildManagedOutboundRequestId(
+  callback: ManagedOutboundCallbackContext,
+  payload: ChannelReplyPayload,
+  normalizedText: string,
+): string {
+  const bodyMaterial = JSON.stringify({
+    callback: {
+      routeId: callback.routeId,
+      assistantId: callback.assistantId,
+      sourceChannel: callback.sourceChannel,
+      sourceUpdateId: callback.sourceUpdateId ?? null,
+    },
+    payload: {
+      chatId: payload.chatId,
+      text: normalizedText,
+      assistantId: payload.assistantId ?? null,
+      chatAction: payload.chatAction ?? null,
+      hasAttachments:
+        Array.isArray(payload.attachments) && payload.attachments.length > 0,
+      approvalRequestId: payload.approval?.requestId ?? null,
+      approvalActions:
+        payload.approval?.actions.map((action) => action.id) ?? null,
+    },
+  });
+
+  const digest = createHash("sha256")
+    .update(bodyMaterial)
+    .digest("hex")
+    .slice(0, 40);
+  return `mgw-send-${digest}`;
+}
+
+// ---------------------------------------------------------------------------
+// Sleep helper
+// ---------------------------------------------------------------------------
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Managed outbound delivery (with retry)
+// ---------------------------------------------------------------------------
+
+async function deliverManagedOutboundReply(
+  callback: ManagedOutboundCallbackContext,
+  payload: ChannelReplyPayload,
+  bearerToken: string | undefined,
+  log: Logger,
+): Promise<void> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (callback.callbackToken) {
+    headers[MANAGED_CALLBACK_TOKEN_HEADER] = callback.callbackToken;
+  } else if (bearerToken) {
+    headers.Authorization = `Bearer ${bearerToken}`;
+  }
+
+  const hasAttachments =
+    Array.isArray(payload.attachments) && payload.attachments.length > 0;
+  const text = payload.approval?.plainTextFallback ?? payload.text;
+  const normalizedText =
+    typeof text === "string" && text.trim().length > 0 ? text : "";
+  if (!normalizedText) {
+    throw new Error(
+      "Managed outbound delivery requires text or plainTextFallback.",
+    );
+  }
+
+  const requestId = buildManagedOutboundRequestId(
+    callback,
+    payload,
+    normalizedText,
+  );
+  headers[MANAGED_IDEMPOTENCY_HEADER] = requestId;
+
+  const requestBody = JSON.stringify({
+    route_id: callback.routeId,
+    assistant_id: callback.assistantId,
+    normalized_send: {
+      version: "v1",
+      sourceChannel: callback.sourceChannel,
+      message: {
+        to: payload.chatId,
+        content: normalizedText,
+        externalMessageId: requestId,
+      },
+      source: {
+        requestId: requestId,
+      },
+      raw: {
+        chatId: payload.chatId,
+        text: payload.text ?? null,
+        assistantId: payload.assistantId ?? null,
+        chatAction: payload.chatAction ?? null,
+        hasAttachments,
+        sourceUpdateId: callback.sourceUpdateId ?? null,
+      },
+    },
+  });
+
+  for (let attempt = 1; attempt <= MANAGED_OUTBOUND_MAX_ATTEMPTS; attempt++) {
+    let response: Response;
+    try {
+      response = await fetch(callback.requestUrl, {
+        method: "POST",
+        headers,
+        body: requestBody,
+        signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+      });
+    } catch (error) {
+      if (attempt < MANAGED_OUTBOUND_MAX_ATTEMPTS) {
+        const retryDelayMs = MANAGED_OUTBOUND_RETRY_BASE_MS * attempt;
+        log.warn(
+          {
+            callbackUrl: callback.requestUrl,
+            routeId: callback.routeId,
+            requestId,
+            chatId: payload.chatId,
+            attempt,
+            retryDelayMs,
+            error: error instanceof Error ? error.message : String(error),
+          },
+          "Managed outbound delivery attempt failed before response; retrying",
+        );
+        await sleep(retryDelayMs);
+        continue;
+      }
+      throw error;
+    }
+
+    if (response.ok) {
+      log.info(
+        {
+          routeId: callback.routeId,
+          assistantId: callback.assistantId,
+          sourceChannel: callback.sourceChannel,
+          requestId,
+          chatId: payload.chatId,
+          attempt,
+        },
+        "Managed outbound delivery accepted",
+      );
+      return;
+    }
+
+    const responseBody = await response.text().catch(() => "<unreadable>");
+    if (
+      response.status >= 500 &&
+      response.status < 600 &&
+      attempt < MANAGED_OUTBOUND_MAX_ATTEMPTS
+    ) {
+      const retryDelayMs = MANAGED_OUTBOUND_RETRY_BASE_MS * attempt;
+      log.warn(
+        {
+          callbackUrl: callback.requestUrl,
+          routeId: callback.routeId,
+          requestId,
+          chatId: payload.chatId,
+          attempt,
+          status: response.status,
+          responseBody,
+          retryDelayMs,
+        },
+        "Managed outbound delivery got retriable upstream response; retrying",
+      );
+      await sleep(retryDelayMs);
+      continue;
+    }
+
+    log.error(
+      {
+        status: response.status,
+        body: responseBody,
+        callbackUrl: callback.requestUrl,
+        routeId: callback.routeId,
+        requestId,
+        chatId: payload.chatId,
+        attempt,
+      },
+      "Managed outbound delivery failed",
+    );
+    throw new Error(
+      `Managed outbound delivery failed (${response.status}): ${responseBody}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Deliver a channel reply to the gateway via its callback URL.
+ *
+ * Automatically detects managed outbound callbacks (platform-routed phone/SMS)
+ * and applies retry/idempotency semantics for those. Direct callbacks are sent
+ * as a single POST request.
+ */
+export async function deliverChannelReply(
+  callbackUrl: string,
+  payload: ChannelReplyPayload,
+  bearerToken?: string,
+  log: Logger = noopLogger,
+): Promise<ChannelDeliveryResult> {
+  const managedCallback = parseManagedOutboundCallback(callbackUrl);
+  if (managedCallback) {
+    await deliverManagedOutboundReply(managedCallback, payload, bearerToken, log);
+    return { ok: true };
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (bearerToken) {
+    headers["Authorization"] = `Bearer ${bearerToken}`;
+  }
+
+  const response = await fetch(callbackUrl, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(payload),
+    signal: AbortSignal.timeout(DELIVERY_TIMEOUT_MS),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "<unreadable>");
+
+    let userMessage: string | undefined;
+    try {
+      const parsed = JSON.parse(body) as { userMessage?: string };
+      if (typeof parsed.userMessage === "string") {
+        userMessage = parsed.userMessage;
+      }
+    } catch {
+      // Body wasn't JSON — that's fine, userMessage stays undefined.
+    }
+
+    log.error(
+      {
+        status: response.status,
+        body,
+        callbackUrl,
+        chatId: payload.chatId,
+        ...(userMessage && { userMessage }),
+      },
+      "Channel reply delivery failed",
+    );
+    if (userMessage) {
+      log.warn(
+        { chatId: payload.chatId, userMessage },
+        "Gateway returned actionable error for user",
+      );
+    }
+    throw new ChannelDeliveryError(response.status, body, userMessage);
+  }
+
+  const result: ChannelDeliveryResult = { ok: true };
+  try {
+    const responseBody = (await response.json()) as Record<string, unknown>;
+    if (typeof responseBody.ts === "string") {
+      result.ts = responseBody.ts;
+    }
+  } catch {
+    // Response may not be JSON for non-Slack channels; that's fine.
+  }
+
+  if (payload.chatAction) {
+    log.debug(
+      { chatId: payload.chatId, callbackUrl, chatAction: payload.chatAction },
+      "Channel action delivered",
+    );
+  } else {
+    log.info(
+      { chatId: payload.chatId, callbackUrl },
+      "Channel reply delivered",
+    );
+  }
+
+  return result;
+}
+
+/**
+ * Deliver an approval prompt (text + inline keyboard metadata) to the
+ * gateway so it can render the approval UI in the channel.
+ */
+export async function deliverApprovalPrompt(
+  callbackUrl: string,
+  chatId: string,
+  text: string,
+  approval: NonNullable<ChannelReplyPayload["approval"]>,
+  assistantId?: string,
+  bearerToken?: string,
+  log: Logger = noopLogger,
+): Promise<ChannelDeliveryResult> {
+  return deliverChannelReply(
+    callbackUrl,
+    { chatId, text, approval, assistantId },
+    bearerToken,
+    log,
+  );
+}

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * @vellumai/gateway-client
+ *
+ * Shared client package for assistant-to-gateway communication. Provides
+ * HTTP delivery, trust-rule CRUD, and Unix-socket IPC helpers that the
+ * assistant daemon uses to interact with the gateway service.
+ *
+ * This package is intentionally free of imports from `assistant/` or
+ * `gateway/` so both sides can depend on it without circular references.
+ */
+
+export {
+  ChannelDeliveryError,
+  deliverApprovalPrompt,
+  deliverChannelReply,
+} from "./http-delivery.js";
+
+export {
+  ipcCall,
+  PersistentIpcClient,
+} from "./ipc-client.js";
+
+export type {
+  ApprovalActionOption,
+  ApprovalUIMetadata,
+  AttachmentMetadata,
+  ChannelDeliveryResult,
+  ChannelReplyPayload,
+  IpcRequest,
+  IpcResponse,
+  Logger,
+  PermissionRequestDetails,
+} from "./types.js";
+
+export { noopLogger } from "./types.js";