@lobu/gateway 3.0.9 → 3.0.13

package/src/permissions/approval-policy.ts

@@ -1,36 +0,0 @@
-/**
- * MCP Tool Approval Policy
- *
- * Uses MCP protocol tool annotations to determine whether a tool call
- * requires explicit user approval (grant) before execution.
- *
- * Per the MCP spec, the default assumption is destructiveHint=true,
- * so tools without annotations require approval (conservative default).
- */
-
-export interface McpToolAnnotations {
-  readOnlyHint?: boolean;
-  destructiveHint?: boolean;
-  idempotentHint?: boolean;
-  openWorldHint?: boolean;
-}
-
-/**
- * Determine if a tool call requires user approval based on its annotations.
- *
- * Returns false (no approval needed) when:
- *   - readOnlyHint is explicitly true
- *   - destructiveHint is explicitly false
- *
- * Returns true (approval required) otherwise, including when:
- *   - No annotations provided (conservative default)
- *   - destructiveHint is true (default per MCP spec)
- */
-export function requiresToolApproval(
-  annotations?: McpToolAnnotations
-): boolean {
-  if (!annotations) return true;
-  if (annotations.readOnlyHint === true) return false;
-  if (annotations.destructiveHint === false) return false;
-  return true;
-}

package/src/permissions/grant-store.ts

@@ -1,219 +0,0 @@
-import { createLogger } from "@lobu/core";
-
-const logger = createLogger("grant-store");
-
-export interface Grant {
-  pattern: string;
-  expiresAt: number | null; // Absolute timestamp (ms). null = never expires.
-  grantedAt: number;
-  denied?: boolean; // true = explicitly deny this pattern
-}
-
-const KEY_PREFIX = "grant:";
-
-/**
- * Unified grant store for URL-pattern permissions.
- *
- * Patterns can be:
- *   - Domain: "api.openai.com", "*.npmjs.org"
- *   - MCP tool: "/mcp/gmail/tools/send_email"
- *   - MCP wildcard: "/mcp/gmail/tools/*"
- *
- * Grants are stored in Redis with TTL matching expiresAt for automatic cleanup.
- */
-export class GrantStore {
-  constructor(private readonly redis: any) {}
-
-  /**
-   * Grant access to a pattern for an agent.
-   * If expiresAt is null, the grant never expires (no Redis TTL).
-   * If denied is true, the grant explicitly denies access.
-   */
-  async grant(
-    agentId: string,
-    pattern: string,
-    expiresAt: number | null,
-    denied?: boolean
-  ): Promise<void> {
-    const key = this.buildKey(agentId, pattern);
-    const value = JSON.stringify({
-      expiresAt,
-      grantedAt: Date.now(),
-      ...(denied && { denied: true }),
-    });
-
-    try {
-      if (expiresAt === null) {
-        await this.redis.set(key, value);
-      } else {
-        const ttlSeconds = Math.max(
-          1,
-          Math.ceil((expiresAt - Date.now()) / 1000)
-        );
-        await this.redis.set(key, value, "EX", ttlSeconds);
-      }
-      logger.info("Granted access", { agentId, pattern, expiresAt });
-    } catch (error) {
-      logger.error("Failed to grant access", { agentId, pattern, error });
-      throw error;
-    }
-  }
-
-  /**
-   * Parse a raw Redis value into its stored object.
-   * Returns null if the value is missing or malformed.
-   */
-  private parseValue(
-    raw: string | null
-  ): { expiresAt: number | null; grantedAt: number; denied?: boolean } | null {
-    if (!raw) return null;
-    try {
-      return JSON.parse(raw);
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Check if an agent has a grant for a pattern.
-   * Checks exact match first, then wildcard parents.
-   * Returns false if the grant has `denied: true`.
-   */
-  async hasGrant(agentId: string, pattern: string): Promise<boolean> {
-    // Exact match
-    const exactKey = this.buildKey(agentId, pattern);
-    try {
-      const parsed = this.parseValue(await this.redis.get(exactKey));
-      if (parsed) return !parsed.denied;
-    } catch (error) {
-      logger.error("Failed to check grant", { agentId, pattern, error });
-      return false;
-    }
-
-    // Wildcard check for MCP tool patterns:
-    // "/mcp/gmail/tools/send_email" is covered by "/mcp/gmail/tools/*"
-    if (pattern.startsWith("/mcp/")) {
-      const lastSlash = pattern.lastIndexOf("/");
-      if (lastSlash > 0) {
-        const wildcardPattern = `${pattern.substring(0, lastSlash)}/*`;
-        const wildcardKey = this.buildKey(agentId, wildcardPattern);
-        try {
-          const parsed = this.parseValue(await this.redis.get(wildcardKey));
-          if (parsed) return !parsed.denied;
-        } catch (error) {
-          logger.error("Failed to check wildcard grant", {
-            agentId,
-            pattern: wildcardPattern,
-            error,
-          });
-        }
-      }
-    }
-
-    // Wildcard check for domain patterns:
-    // "sub.example.com" is covered by "*.example.com"
-    if (!pattern.startsWith("/")) {
-      const parts = pattern.split(".");
-      if (parts.length > 2) {
-        const wildcardDomain = `*.${parts.slice(1).join(".")}`;
-        const wildcardKey = this.buildKey(agentId, wildcardDomain);
-        try {
-          const parsed = this.parseValue(await this.redis.get(wildcardKey));
-          if (parsed) return !parsed.denied;
-        } catch (error) {
-          logger.error("Failed to check wildcard domain grant", {
-            agentId,
-            pattern: wildcardDomain,
-            error,
-          });
-        }
-      }
-    }
-
-    return false;
-  }
-
-  /**
-   * Check if a pattern is explicitly denied for an agent.
-   */
-  async isDenied(agentId: string, pattern: string): Promise<boolean> {
-    const key = this.buildKey(agentId, pattern);
-    try {
-      const parsed = this.parseValue(await this.redis.get(key));
-      return parsed?.denied === true;
-    } catch (error) {
-      logger.error("Failed to check denied grant", {
-        agentId,
-        pattern,
-        error,
-      });
-      return false;
-    }
-  }
-
-  /**
-   * List all active grants for an agent.
-   * Uses Redis SCAN to find matching keys.
-   */
-  async listGrants(agentId: string): Promise<Grant[]> {
-    const prefix = `${KEY_PREFIX}${agentId}:`;
-    const grants: Grant[] = [];
-
-    try {
-      let cursor = "0";
-      do {
-        const [nextCursor, keys] = await this.redis.scan(
-          cursor,
-          "MATCH",
-          `${prefix}*`,
-          "COUNT",
-          100
-        );
-        cursor = nextCursor;
-
-        if (keys.length > 0) {
-          const values = await this.redis.mget(...keys);
-          for (let i = 0; i < keys.length; i++) {
-            const val = values[i];
-            if (!val) continue;
-
-            try {
-              const parsed = JSON.parse(val);
-              const pattern = (keys[i] as string).substring(prefix.length);
-              grants.push({
-                pattern,
-                expiresAt: parsed.expiresAt ?? null,
-                grantedAt: parsed.grantedAt,
-                ...(parsed.denied && { denied: true }),
-              });
-            } catch {
-              // Skip malformed entries
-            }
-          }
-        }
-      } while (cursor !== "0");
-    } catch (error) {
-      logger.error("Failed to list grants", { agentId, error });
-    }
-
-    return grants;
-  }
-
-  /**
-   * Revoke a grant for an agent.
-   */
-  async revoke(agentId: string, pattern: string): Promise<void> {
-    const key = this.buildKey(agentId, pattern);
-    try {
-      await this.redis.del(key);
-      logger.info("Revoked grant", { agentId, pattern });
-    } catch (error) {
-      logger.error("Failed to revoke grant", { agentId, pattern, error });
-      throw error;
-    }
-  }
-
-  private buildKey(agentId: string, pattern: string): string {
-    return `${KEY_PREFIX}${agentId}:${pattern}`;
-  }
-}

package/src/platform/file-handler.ts

@@ -1,66 +0,0 @@
-/**
- * File handler interface for platform-specific file operations.
- */
-
-import type { Readable } from "node:stream";
-
-export interface FileMetadata {
-  id: string;
-  name: string;
-  mimetype?: string;
-  size: number;
-  url: string;
-  downloadUrl?: string;
-  permalink?: string;
-  timestamp?: number;
-}
-
-export interface FileUploadResult {
-  fileId: string;
-  permalink: string;
-  name: string;
-  size: number;
-}
-
-export interface FileUploadOptions {
-  filename: string;
-  channelId: string;
-  threadTs?: string;
-  title?: string;
-  initialComment?: string;
-  sessionKey?: string;
-  /** Send as voice message (ptt) on platforms that support it */
-  voiceMessage?: boolean;
-}
-
-export interface IFileHandler {
-  /**
-   * Download a file by its platform-specific ID.
-   * Each platform implementation handles its own authentication internally.
-   */
-  downloadFile(
-    fileId: string
-  ): Promise<{ stream: Readable; metadata: FileMetadata }>;
-
-  uploadFile(
-    fileStream: Readable,
-    options: FileUploadOptions
-  ): Promise<FileUploadResult>;
-
-  generateFileToken(
-    sessionKey: string,
-    fileId: string,
-    expiresIn?: number
-  ): string;
-
-  validateFileToken(token: string): {
-    valid: boolean;
-    sessionKey?: string;
-    fileId?: string;
-    error?: string;
-  };
-
-  getSessionFiles(sessionKey: string): string[];
-
-  cleanupSession(sessionKey: string): void;
-}

package/src/platform/link-buttons.ts

@@ -1,57 +0,0 @@
-/**
- * Extract settings link buttons from markdown content.
- *
- * Scans for markdown links pointing to `/connect/claim?claim=...` URLs and
- * returns them as structured button data, stripping the link syntax
- * from the content so platforms can render native buttons instead.
- */
-
-const SETTINGS_LINK_RE =
-  /\[([^\]]+)\]\((https?:\/\/[^)]*\/(?:connect\/claim|agent)\?claim=[^)]+)\)/g;
-
-/**
- * Returns true when the URL points to a loopback address that
- * Telegram (and other platforms) reject for inline keyboard buttons.
- */
-function isLocalhostUrl(url: string): boolean {
-  try {
-    const u = new URL(url);
-    return (
-      u.hostname === "localhost" ||
-      u.hostname === "127.0.0.1" ||
-      u.hostname === "::1"
-    );
-  } catch {
-    return true;
-  }
-}
-
-export interface LinkButton {
-  text: string;
-  url: string;
-}
-
-/**
- * Extract `[label](settingsUrl)` markdown links and return them as
- * structured buttons.  The link syntax is replaced with just the label
- * text so the surrounding prose still reads naturally.
- */
-export function extractSettingsLinkButtons(content: string): {
-  processedContent: string;
-  linkButtons: LinkButton[];
-} {
-  const linkButtons: LinkButton[] = [];
-
-  const processedContent = content.replace(
-    SETTINGS_LINK_RE,
-    (_match, text: string, url: string) => {
-      if (!isLocalhostUrl(url)) {
-        linkButtons.push({ text, url });
-      }
-      // Replace the markdown link with just the label text
-      return text;
-    }
-  );
-
-  return { processedContent, linkButtons };
-}

package/src/platform/renderer-utils.ts

@@ -1,44 +0,0 @@
-/**
- * Shared renderer and markdown utilities.
- * Extracts common helpers duplicated across Telegram, WhatsApp, and Slack converters/renderers.
- */
-
-/**
- * Chunk a long message into smaller parts, breaking at natural boundaries.
- */
-export function chunkMessage(text: string, maxLength: number): string[] {
-  if (text.length <= maxLength) {
-    return [text];
-  }
-
-  const chunks: string[] = [];
-  let remaining = text;
-
-  while (remaining.length > 0) {
-    if (remaining.length <= maxLength) {
-      chunks.push(remaining);
-      break;
-    }
-
-    let breakPoint = maxLength;
-
-    const newlineIndex = remaining.lastIndexOf("\n", maxLength);
-    if (newlineIndex > maxLength * 0.5) {
-      breakPoint = newlineIndex + 1;
-    } else {
-      const spaceIndex = remaining.lastIndexOf(" ", maxLength);
-      if (spaceIndex > maxLength * 0.5) {
-        breakPoint = spaceIndex + 1;
-      }
-    }
-
-    chunks.push(remaining.substring(0, breakPoint).trim());
-    remaining = remaining.substring(breakPoint).trim();
-  }
-
-  return chunks.filter((c) => c.length > 0);
-}
-
-export function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/platform/response-renderer.ts

@@ -1,84 +0,0 @@
-/**
- * Response renderer interface for platform-specific message rendering.
- * Each platform implements this interface to handle thread responses
- * in a platform-appropriate way (streaming, buffering, formatting).
- */
-
-import type { ThreadResponsePayload } from "../infrastructure/queue/types";
-
-/**
- * Interface for rendering thread responses to a specific platform.
- * Implementations handle platform-specific concerns like:
- * - Streaming vs buffered messages
- * - Rich formatting (Slack blocks) vs plain text (WhatsApp)
- * - Status indicators (thread status vs typing)
- */
-export interface ResponseRenderer {
-  /**
-   * Handle streaming delta content.
-   * Platforms that support streaming (Slack) update messages in real-time.
-   * Platforms without streaming (WhatsApp) buffer content for later delivery.
-   *
-   * @param payload - The thread response payload containing delta content
-   * @param sessionKey - Unique key for this response session (userId:messageId)
-   * @returns Message ID/timestamp if a message was created/updated, null otherwise
-   */
-  handleDelta?(
-    payload: ThreadResponsePayload,
-    sessionKey: string
-  ): Promise<string | null>;
-
-  /**
-   * Handle completion of response processing.
-   * Called when all content has been processed (processedMessageIds is set).
-   * Should finalize any streams, send buffered content, clear status indicators.
-   *
-   * @param payload - The thread response payload
-   * @param sessionKey - Unique key for this response session
-   */
-  handleCompletion(
-    payload: ThreadResponsePayload,
-    sessionKey: string
-  ): Promise<void>;
-
-  /**
-   * Handle error response.
-   * Display error in platform-appropriate format.
-   *
-   * @param payload - The thread response payload containing error
-   * @param sessionKey - Unique key for this response session
-   */
-  handleError(
-    payload: ThreadResponsePayload,
-    sessionKey: string
-  ): Promise<void>;
-
-  /**
-   * Handle status updates (heartbeat with elapsed time).
-   * Used to show "is running...", progress indicators, etc.
-   *
-   * @param payload - The thread response payload with statusUpdate field
-   */
-  handleStatusUpdate?(payload: ThreadResponsePayload): Promise<void>;
-
-  /**
-   * Handle ephemeral messages (visible only to specific user).
-   * Used for OAuth/auth flows, temporary notifications.
-   *
-   * @param payload - The thread response payload with ephemeral content
-   */
-  handleEphemeral?(payload: ThreadResponsePayload): Promise<void>;
-
-  /**
-   * Stop any active streams for a conversation.
-   * Called when an interaction is created to prevent messages appearing
-   * after the interaction prompt.
-   *
-   * @param userId - User ID
-   * @param conversationId - Conversation identifier
-   */
-  stopStreamForConversation?(
-    userId: string,
-    conversationId: string
-  ): Promise<void>;
-}

package/src/platform/unified-thread-consumer.ts

@@ -1,194 +0,0 @@
-/**
- * Unified thread response consumer.
- * Single consumer that routes responses to platform-specific renderers
- * via the PlatformRegistry, eliminating duplicate queue filtering logic.
- */
-
-import { createChildSpan, createLogger, flushTracing } from "@lobu/core";
-import type { ChatResponseBridge } from "../connections/chat-response-bridge";
-import type {
-  IMessageQueue,
-  QueueJob,
-  ThreadResponsePayload,
-} from "../infrastructure/queue";
-import type { PlatformRegistry } from "../platform";
-import type { ResponseRenderer } from "./response-renderer";
-
-const logger = createLogger("unified-thread-consumer");
-
-/**
- * Unified consumer for thread_response queue.
- * Routes responses to the appropriate platform adapter based on payload.platform field.
- */
-export class UnifiedThreadResponseConsumer {
-  private isRunning = false;
-
-  private chatResponseBridge?: ChatResponseBridge;
-
-  constructor(
-    private queue: IMessageQueue,
-    private platformRegistry: PlatformRegistry
-  ) {}
-
-  setChatResponseBridge(bridge: ChatResponseBridge): void {
-    this.chatResponseBridge = bridge;
-  }
-
-  /**
-   * Start consuming thread_response messages.
-   */
-  async start(): Promise<void> {
-    try {
-      await this.queue.start();
-      await this.queue.createQueue("thread_response");
-
-      await this.queue.work(
-        "thread_response",
-        this.handleThreadResponse.bind(this)
-      );
-
-      this.isRunning = true;
-      logger.debug("Unified thread response consumer started");
-    } catch (error) {
-      logger.error("Failed to start unified thread response consumer:", error);
-      throw error;
-    }
-  }
-
-  /**
-   * Stop the consumer.
-   */
-  async stop(): Promise<void> {
-    this.isRunning = false;
-    await this.queue.stop();
-    logger.info("Unified thread response consumer stopped");
-  }
-
-  /**
-   * Handle a thread response job by routing to the appropriate platform renderer.
-   */
-  private async handleThreadResponse(
-    job: QueueJob<ThreadResponsePayload>
-  ): Promise<void> {
-    const data = job.data;
-
-    if (!data || !data.messageId) {
-      logger.error(`Invalid thread response data: ${JSON.stringify(data)}`);
-      return;
-    }
-
-    // Create child span for response processing (linked to original trace)
-    const traceparent = data.platformMetadata?.traceparent as
-      | string
-      | undefined;
-    const span = createChildSpan("response_delivery", traceparent, {
-      "lobu.message_id": data.messageId,
-      "lobu.user_id": data.userId,
-      "lobu.platform": data.platform || data.teamId || "unknown",
-    });
-
-    try {
-      // Check if this response belongs to a Chat SDK connection — handle before legacy routing
-      if (this.chatResponseBridge?.canHandle(data)) {
-        const sessionKey = `${data.userId}:${data.originalMessageId || data.messageId}`;
-        await this.routeToRenderer(this.chatResponseBridge, data, sessionKey);
-        return;
-      }
-
-      // Use platform field, fall back to teamId
-      const platformName = data.platform || data.teamId;
-      if (!platformName) {
-        logger.warn(
-          `Missing platform in thread response for message ${data.messageId}, skipping`
-        );
-        return;
-      }
-
-      // Get platform adapter from registry
-      const platform = this.platformRegistry.get(platformName);
-      if (!platform) {
-        logger.warn(
-          `No platform adapter registered for: ${platformName}, skipping message ${data.messageId}`
-        );
-        return;
-      }
-
-      // Get renderer from platform
-      const renderer = platform.getResponseRenderer?.();
-      if (!renderer) {
-        logger.warn(
-          `Platform ${platformName} does not provide a response renderer, skipping message ${data.messageId}`
-        );
-        return;
-      }
-
-      // Create session key for tracking
-      const sessionKey = `${data.userId}:${data.originalMessageId || data.messageId}`;
-
-      logger.info(
-        `Processing thread response for platform=${platformName}, message=${data.messageId}, session=${sessionKey}`
-      );
-
-      await this.routeToRenderer(renderer, data, sessionKey);
-    } catch (error) {
-      logger.error(
-        `Error processing thread response for message ${data.messageId}:`,
-        error
-      );
-      throw error;
-    } finally {
-      span?.end();
-      void flushTracing();
-    }
-  }
-
-  /**
-   * Route the payload to the appropriate renderer method.
-   */
-  private async routeToRenderer(
-    renderer: ResponseRenderer,
-    data: ThreadResponsePayload,
-    sessionKey: string
-  ): Promise<void> {
-    // Handle ephemeral messages (OAuth/auth flows)
-    if (data.ephemeral && data.content && renderer.handleEphemeral) {
-      await renderer.handleEphemeral(data);
-      return;
-    }
-
-    // Handle status updates (heartbeat with elapsed time)
-    if (data.statusUpdate && renderer.handleStatusUpdate) {
-      await renderer.handleStatusUpdate(data);
-      return;
-    }
-
-    // Handle streaming delta
-    if (data.delta && renderer.handleDelta) {
-      await renderer.handleDelta(data, sessionKey);
-      // Early return if no error - delta processing is complete
-      if (!data.error) {
-        return;
-      }
-    }
-
-    // Handle error
-    if (data.error) {
-      await renderer.handleError(data, sessionKey);
-      // Also complete session on error
-      await renderer.handleCompletion(data, sessionKey);
-      return;
-    }
-
-    // Handle completion
-    if (data.processedMessageIds?.length) {
-      await renderer.handleCompletion(data, sessionKey);
-    }
-  }
-
-  /**
-   * Check if consumer is healthy.
-   */
-  isHealthy(): boolean {
-    return this.isRunning;
-  }
-}