@lobu/gateway 2.8.0 → 3.0.6

package/src/routes/internal/schedule.ts

@@ -0,0 +1,226 @@
+/**
+ * Internal Schedule Routes
+ *
+ * Worker-facing endpoints for scheduling reminders.
+ * Used by custom MCP tools (ScheduleReminder, CancelReminder, ListReminders).
+ */
+
+import { createLogger } from "@lobu/core";
+import { Hono } from "hono";
+import type { ScheduledWakeupService } from "../../orchestration/scheduled-wakeup";
+import { authenticateWorker } from "./middleware";
+import type { WorkerContext } from "./types";
+
+const logger = createLogger("internal-schedule-routes");
+
+/**
+ * Create internal schedule routes (Hono)
+ */
+export function createScheduleRoutes(
+  scheduledWakeupService: ScheduledWakeupService
+): Hono<WorkerContext> {
+  const router = new Hono<WorkerContext>();
+
+  /**
+   * Schedule a reminder (one-time or recurring)
+   * POST /internal/schedule
+   *
+   * Body: {
+   *   task: string (required)
+   *   delayMinutes?: number (one-time, 1-1440)
+   *   cron?: string (recurring, e.g., "0,30 * * * *")
+   *   maxIterations?: number (for recurring, default 10, max 100)
+   *   context?: object (optional)
+   * }
+   */
+  router.post("/internal/schedule", authenticateWorker, async (c) => {
+    try {
+      const worker = c.get("worker");
+      const { delayMinutes, cron, maxIterations, task, context } =
+        await c.req.json();
+
+      // Validate task
+      if (!task || typeof task !== "string") {
+        return c.json({ error: "task is required and must be a string" }, 400);
+      }
+
+      if (task.length > 2000) {
+        return c.json({ error: "task must be 2000 characters or less" }, 400);
+      }
+
+      // Validate: must have either delayMinutes OR cron
+      if (delayMinutes && cron) {
+        return c.json(
+          {
+            error:
+              "Cannot specify both delayMinutes and cron - use one or the other",
+          },
+          400
+        );
+      }
+
+      if (!delayMinutes && !cron) {
+        return c.json(
+          { error: "Must specify either delayMinutes or cron" },
+          400
+        );
+      }
+
+      // Validate delayMinutes if provided
+      if (
+        delayMinutes !== undefined &&
+        (typeof delayMinutes !== "number" || delayMinutes < 1)
+      ) {
+        return c.json({ error: "delayMinutes must be a positive number" }, 400);
+      }
+
+      // Validate cron if provided
+      if (cron !== undefined && typeof cron !== "string") {
+        return c.json({ error: "cron must be a string" }, 400);
+      }
+
+      // Validate maxIterations if provided
+      if (
+        maxIterations !== undefined &&
+        (typeof maxIterations !== "number" || maxIterations < 1)
+      ) {
+        return c.json(
+          { error: "maxIterations must be a positive number" },
+          400
+        );
+      }
+
+      logger.info(
+        {
+          deploymentName: worker.deploymentName,
+          delayMinutes,
+          cron,
+          maxIterations,
+          taskLength: task.length,
+        },
+        "Scheduling reminder"
+      );
+
+      const schedule = await scheduledWakeupService.schedule({
+        deploymentName: worker.deploymentName,
+        conversationId: worker.conversationId,
+        channelId: worker.channelId,
+        userId: worker.userId,
+        agentId: worker.agentId || worker.channelId, // Fallback to channelId if no agentId
+        teamId: worker.teamId || "default",
+        platform: worker.platform || "unknown",
+        delayMinutes,
+        cron,
+        maxIterations,
+        task,
+        context,
+      });
+
+      const recurringInfo = schedule.isRecurring
+        ? ` (recurring: ${schedule.cron}, max ${schedule.maxIterations} iterations)`
+        : "";
+
+      return c.json({
+        scheduleId: schedule.id,
+        scheduledFor: schedule.triggerAt,
+        isRecurring: schedule.isRecurring,
+        cron: schedule.cron,
+        maxIterations: schedule.maxIterations,
+        message: `Reminder scheduled for ${new Date(schedule.triggerAt).toLocaleString()}${recurringInfo}`,
+      });
+    } catch (error) {
+      logger.error("Failed to schedule reminder:", error);
+      return c.json({ error: "Failed to schedule reminder" }, 400);
+    }
+  });
+
+  /**
+   * Cancel a scheduled reminder
+   * DELETE /internal/schedule/:scheduleId
+   */
+  router.delete(
+    "/internal/schedule/:scheduleId",
+    authenticateWorker,
+    async (c) => {
+      try {
+        const worker = c.get("worker");
+        const scheduleId = c.req.param("scheduleId");
+
+        if (!scheduleId) {
+          return c.json({ error: "scheduleId is required" }, 400);
+        }
+
+        logger.info(
+          {
+            deploymentName: worker.deploymentName,
+            scheduleId,
+          },
+          "Cancelling reminder"
+        );
+
+        const success = await scheduledWakeupService.cancel(
+          scheduleId,
+          worker.deploymentName
+        );
+
+        if (!success) {
+          return c.json({
+            success: false,
+            message: "Schedule not found or already triggered",
+          });
+        }
+
+        return c.json({
+          success: true,
+          message: "Reminder cancelled successfully",
+        });
+      } catch (error) {
+        logger.error("Failed to cancel reminder:", error);
+        return c.json({ error: "Failed to cancel reminder" }, 400);
+      }
+    }
+  );
+
+  /**
+   * List pending reminders
+   * GET /internal/schedule
+   */
+  router.get("/internal/schedule", authenticateWorker, async (c) => {
+    try {
+      const worker = c.get("worker");
+
+      const schedules = await scheduledWakeupService.listPending(
+        worker.deploymentName
+      );
+
+      const reminders = schedules.map((s) => {
+        const now = Date.now();
+        const triggerTime = new Date(s.triggerAt).getTime();
+        const minutesRemaining = Math.max(
+          0,
+          Math.round((triggerTime - now) / 60000)
+        );
+
+        return {
+          scheduleId: s.id,
+          task: s.task,
+          scheduledFor: s.triggerAt,
+          minutesRemaining,
+          // Recurring info
+          isRecurring: s.isRecurring,
+          cron: s.cron,
+          iteration: s.iteration,
+          maxIterations: s.maxIterations,
+        };
+      });
+
+      return c.json({ reminders });
+    } catch (error) {
+      logger.error("Failed to list reminders:", error);
+      return c.json({ error: "Failed to list reminders" }, 500);
+    }
+  });
+
+  logger.debug("Internal schedule routes registered");
+  return router;
+}

package/src/routes/internal/types.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared types for internal worker-facing routes.
+ */
+
+/**
+ * Hono context type for routes authenticated via worker JWT tokens.
+ * Covers all fields used across internal route handlers.
+ */
+export type WorkerContext = {
+  Variables: {
+    worker: {
+      userId: string;
+      conversationId: string;
+      channelId: string;
+      teamId?: string;
+      agentId?: string;
+      deploymentName: string;
+      platform?: string;
+      connectionId?: string;
+    };
+  };
+};

package/src/routes/openapi-auto.ts

@@ -0,0 +1,239 @@
+import type { OpenAPIHono, RouteConfig } from "@hono/zod-openapi";
+import { z } from "@hono/zod-openapi";
+
+type OpenApiDefinition =
+  | { type: "route"; route: { method: string; path: string } }
+  | { type: string; route?: { method: string; path: string } };
+
+// Internal route prefixes - worker-facing, excluded from public docs
+const INTERNAL_PREFIXES = [
+  "/api/proxy",
+  "/api/internal",
+  "/internal",
+  "/worker",
+  "/mcp",
+];
+
+// Routes excluded from docs entirely: HTML pages, OAuth redirects/callbacks,
+// platform webhooks, system probes, and infra endpoints
+const EXCLUDED_ROUTES = [
+  "/", // Landing page
+  "/api/v1/auth/{provider}/login", // OAuth redirect (browser-only)
+  "/api/v1/reload", // Dev-only config reload, not a public API
+  "/slack/install", // Slack app install
+  "/slack/oauth_callback", // Slack OAuth callback
+];
+
+const EXCLUDED_PREFIXES = [
+  "/health", // K8s liveness probe
+  "/ready", // K8s readiness probe
+  "/metrics", // Prometheus scraping
+  "/api/telegram", // Telegram webhook
+  "/api/v1/webhooks", // Chat SDK connection webhooks
+  "/slack/", // Slack events
+  "/connect/oauth", // OAuth session bootstrap
+];
+
+function isInternalRoute(path: string): boolean {
+  return INTERNAL_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+
+function isExcludedRoute(path: string): boolean {
+  if (EXCLUDED_ROUTES.includes(path)) return true;
+  return EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+
+function normalizePath(path: string): string {
+  let normalized = path.replace(/:([A-Za-z0-9_]+)(?:\{[^}]+\})?/g, "{$1}");
+  normalized = normalized.replace(/\/\*/g, "/{wildcard}");
+  normalized = normalized.replace(/\*/g, "{wildcard}");
+  // Collapse double slashes from sub-router mounting (e.g. app.route("", router))
+  normalized = normalized.replace(/\/\/+/g, "/");
+  return normalized;
+}
+
+function extractPathParams(path: string): string[] {
+  const params: string[] = [];
+  for (const match of path.matchAll(/\{([^}]+)\}/g)) {
+    if (match[1]) {
+      params.push(match[1]);
+    }
+  }
+  return params;
+}
+
+/**
+ * Derive an API documentation tag from the route path.
+ */
+function deriveTag(path: string): string {
+  // Messages — sending and streaming
+  if (
+    path.includes("/messages") ||
+    path.includes("/events") ||
+    path.includes("/interactions")
+  ) {
+    return "Messages";
+  }
+
+  // Agents — CRUD and status
+  if (
+    path.startsWith("/api/v1/agents") &&
+    !path.includes("/config") &&
+    !path.includes("/channels") &&
+    !path.includes("/history") &&
+    !path.includes("/schedules")
+  ) {
+    return "Agents";
+  }
+
+  // Configuration — providers, packages, domain grants
+  if (path.includes("/config")) {
+    return "Configuration";
+  }
+
+  // Channels — platform bindings
+  if (path.includes("/channels")) {
+    return "Channels";
+  }
+
+  // Schedules — wakeups and reminders
+  if (path.includes("/schedules")) {
+    return "Schedules";
+  }
+
+  // History — session messages and stats
+  if (path.includes("/history")) {
+    return "History";
+  }
+
+  // Auth — API keys, OAuth, device code
+  if (path.startsWith("/api/v1/auth/")) {
+    return "Auth";
+  }
+
+  // Integrations — skills and MCP servers
+  if (path.startsWith("/api/v1/integrations")) {
+    return "Integrations";
+  }
+
+  // Session — OAuth/bootstrap endpoints
+  if (path.startsWith("/connect")) {
+    return "Session";
+  }
+
+  return "Other";
+}
+
+/**
+ * Human-readable summaries for auto-registered routes.
+ * Key format: "method /path" (lowercase method, normalized path).
+ */
+const ROUTE_SUMMARIES: Record<string, string> = {
+  // Agents
+  "post /api/v1/agents": "Create agent",
+  "get /api/v1/agents": "List user agents",
+  "patch /api/v1/agents/{agentId}": "Update agent metadata",
+  "delete /api/v1/agents/{agentId}": "Delete agent",
+
+  // Configuration
+  "get /api/v1/agents/{agentId}/config/providers/catalog":
+    "List provider catalog",
+  "get /api/v1/agents/{agentId}/config/grants": "List domain grants",
+
+  // History
+  "get /api/v1/agents/{agentId}/history/status": "Get agent connection status",
+  "get /api/v1/agents/{agentId}/history/session/messages":
+    "Get session messages",
+  "get /api/v1/agents/{agentId}/history/session/stats": "Get session stats",
+
+  // Channels
+  "get /api/v1/agents/{agentId}/channels": "List channel bindings",
+  "post /api/v1/agents/{agentId}/channels": "Bind agent to channel",
+  "delete /api/v1/agents/{agentId}/channels/{platform}/{channelId}":
+    "Unbind agent from channel",
+};
+
+/**
+ * Register OpenAPI paths for routes not already defined via app.openapi.
+ * Internal routes (worker-facing), webhooks, system probes, and OAuth callbacks
+ * are excluded from the public docs.
+ */
+export function registerAutoOpenApiRoutes(app: OpenAPIHono): void {
+  const registered = new Set<string>();
+  const definitions = app.openAPIRegistry
+    .definitions as unknown as OpenApiDefinition[];
+
+  // Collect all Hono route paths for matching against OpenAPI relative paths
+  const honoRoutePaths = new Set<string>();
+  for (const route of app.routes) {
+    if (route.method.toLowerCase() !== "all") {
+      honoRoutePaths.add(normalizePath(route.path));
+    }
+  }
+
+  for (const def of definitions) {
+    if (def.type === "route" && def.route) {
+      // Normalize the definition path in-place to fix double-slash artifacts
+      def.route.path = normalizePath(def.route.path);
+      const method = def.route.method.toLowerCase();
+      const defPath = def.route.path;
+      registered.add(`${method} ${defPath}`);
+
+      // Sub-routers register OpenAPI defs with relative paths (e.g., "/{provider}/code").
+      // Match these against Hono's full mounted paths to prevent duplicate stubs.
+      if (!defPath.startsWith("/api/")) {
+        for (const fullPath of honoRoutePaths) {
+          if (fullPath.endsWith(defPath)) {
+            registered.add(`${method} ${fullPath}`);
+          }
+        }
+      }
+    }
+  }
+
+  for (const route of app.routes) {
+    const method = route.method.toLowerCase();
+    if (method === "all") {
+      continue;
+    }
+
+    const path = normalizePath(route.path);
+    const key = `${method} ${path}`;
+
+    if (registered.has(key)) {
+      continue;
+    }
+
+    // Skip internal routes - they shouldn't be in public docs
+    if (isInternalRoute(path)) {
+      continue;
+    }
+
+    // Skip excluded routes (HTML pages, OAuth callbacks, webhooks, probes)
+    if (isExcludedRoute(path)) {
+      continue;
+    }
+
+    const params = extractPathParams(path);
+    const paramsSchema =
+      params.length > 0
+        ? z.object(
+            Object.fromEntries(params.map((param) => [param, z.string()]))
+          )
+        : undefined;
+
+    const routeConfig: RouteConfig = {
+      method: method as RouteConfig["method"],
+      path,
+      tags: [deriveTag(path)],
+      summary: ROUTE_SUMMARIES[key] || `${method.toUpperCase()} ${path}`,
+      request: paramsSchema ? { params: paramsSchema } : undefined,
+      responses: {
+        200: { description: "OK" },
+      },
+    };
+
+    app.openAPIRegistry.registerPath(routeConfig);
+    registered.add(key);
+  }
+}

package/src/routes/public/agent-access.ts

@@ -0,0 +1,23 @@
+import type { AgentConfigStore } from "@lobu/core";
+import type { SettingsTokenPayload } from "../../auth/settings/token-service";
+import type { UserAgentsStore } from "../../auth/user-agents-store";
+import {
+  resolveSettingsLookupUserId,
+  verifyOwnedAgentAccess,
+} from "../shared/agent-ownership";
+
+export interface AgentAccessConfig {
+  userAgentsStore: UserAgentsStore;
+  agentMetadataStore: Pick<AgentConfigStore, "getMetadata">;
+}
+
+export async function verifyAgentAccess(
+  session: SettingsTokenPayload,
+  agentId: string,
+  config: AgentAccessConfig
+): Promise<boolean> {
+  const result = await verifyOwnedAgentAccess(session, agentId, config);
+  return result.authorized;
+}
+
+export { resolveSettingsLookupUserId };