forgeos 0.1.0-alpha.4 → 0.1.0-alpha.41

package/src/forge/dev/server.ts

@@ -1,4 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
+import {
+  createHmac,
+  timingSafeEqual,
+} from "node:crypto";
+import { createRequire } from "node:module";
 import {
   createServer,
   type IncomingMessage,
@@ -10,6 +15,7 @@ import { pathToFileURL } from "node:url";
 import { createDiagnostic } from "../compiler/diagnostics/create.ts";
 import {
   FORGE_AUTH_DEV_HEADERS_IN_PRODUCTION,
+  FORGE_DEV_DB_RESET,
   FORGE_DEV_INVOKE_FAILED,
   FORGE_DEV_SERVER_ERROR,
   FORGE_POLICY_DENIED,
@@ -22,13 +28,16 @@ import type { TableMapEntry } from "../compiler/data-graph/sql/serialize.ts";
 import type { SqlPlan } from "../compiler/data-graph/sql/types.ts";
 import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
 import { stripDeterministicHeader } from "../compiler/primitives/header.ts";
-import type { DevManifest } from "../compiler/types/dev-manifest.ts";
+import type { DevManifest, DevRoute } from "../compiler/types/dev-manifest.ts";
+import type { Diagnostic } from "../compiler/types/diagnostic.ts";
 import type { RuntimeGraph } from "../compiler/types/runtime-graph.ts";
 import { createDbAdapter } from "../runtime/db/factory.ts";
-import { applyMigrations } from "../runtime/db/migrate.ts";
+import { applyMigrations, getMigrationStatus, resetDatabase } from "../runtime/db/migrate.ts";
 import {
+  disposeRuntimeModuleNamespace,
   listEntries,
   prepareRuntimeEnvironment,
+  refreshRuntimeModuleNamespace,
   runEntry,
 } from "../runtime/executor.ts";
 import { listQueries, runQuery } from "../runtime/query/run-query.ts";
@@ -49,7 +58,7 @@ import { loadWorkflowRegistry } from "../runtime/workflows/registry.ts";
 import { retryWorkflowRun } from "../runtime/workflows/retry-run.ts";
 import { hashStable } from "../compiler/primitives/hash.ts";
 import { canonicalJson } from "../compiler/primitives/serialize.ts";
-import type { DevServerHandle, DevServerOptions, DevServerState } from "./types.ts";
+import type { DevServerHandle, DevServerOptions, DevServerReloadResult, DevServerState } from "./types.ts";
 import { getTelemetrySummary, inspectTrace } from "../runtime/telemetry/flush.ts";
 import { processTelemetryBatch } from "../runtime/telemetry/process.ts";
 import { getRuntimeEnvStore } from "../runtime/context/create-context.ts";
@@ -69,12 +78,47 @@ import type { AgentToolRegistry } from "../compiler/agent-contract/types.ts";
 import { loadLiveQueryRegistry } from "../runtime/live/registry.ts";
 import { createLiveSubscriptionManager } from "../runtime/live/subscription-manager.ts";
 import { createSseResponse } from "../runtime/live/sse.ts";
+import {
+  MemoryWebhookReplayStore,
+  verifyWebhookSignature,
+} from "../runtime/webhooks/security.ts";
 import {
   ensureLiveInvalidationSchema,
   listLiveInvalidations,
 } from "../runtime/live/invalidation-log.ts";
 import { currentReleaseInfo } from "../runtime/release/runtime.ts";
 import { DEFAULT_LIVE_LIMITS } from "../runtime/live/types.ts";
+import {
+  loadExternalServiceGraph,
+  runExternalEntry,
+} from "../runtime/external/bridge.ts";
+
+async function applyDevMigrations(
+  adapter: NonNullable<Awaited<ReturnType<typeof createDbAdapter>>["adapter"]>,
+  sqlPlan: SqlPlan,
+  dbMode: DevServerOptions["db"],
+): Promise<Diagnostic[]> {
+  const shouldAutoReset =
+    (dbMode === "pglite" || dbMode === "memory") &&
+    process.env.FORGE_DEV_AUTO_RESET_DB !== "0";
+
+  if (shouldAutoReset) {
+    const status = await getMigrationStatus(adapter).catch(() => null);
+    const appliedChecksum = status?.applied.at(-1)?.checksum ?? null;
+    if (appliedChecksum && appliedChecksum !== sqlPlan.checksum) {
+      return [
+        createDiagnostic({
+          severity: "warning",
+          code: FORGE_DEV_DB_RESET,
+          message: "local dev database schema changed; reset app tables automatically",
+        }),
+        ...(await resetDatabase(adapter, sqlPlan)),
+      ];
+    }
+  }
+
+  return applyMigrations(adapter, sqlPlan);
+}
 
 interface FetchServer {
   hostname?: string;
@@ -96,7 +140,7 @@ async function readIncomingBody(request: IncomingMessage): Promise<Buffer | unde
 
 async function nodeRequestToFetch(
   request: IncomingMessage,
-  input: { host: string; port: number },
+  input: { host: string; port: number; signal?: AbortSignal },
 ): Promise<Request> {
   const headers = new Headers();
   for (const [name, value] of Object.entries(request.headers)) {
@@ -113,6 +157,7 @@ async function nodeRequestToFetch(
     method: request.method,
     headers,
     body: body ? new Blob([new Uint8Array(body)]) : undefined,
+    signal: input.signal,
     ...(body ? { duplex: "half" as const } : {}),
   };
   return new Request(url, init);
@@ -155,10 +200,13 @@ async function createNodeFetchServer(
 ): Promise<FetchServer> {
   let actualPort = input.port;
   const nodeServer: NodeHttpServer = createServer(async (request, response) => {
+    const controller = new AbortController();
+    response.once("close", () => controller.abort());
     try {
       const fetchRequest = await nodeRequestToFetch(request, {
         host: input.hostname,
         port: actualPort,
+        signal: controller.signal,
       });
       const fetchResponse = await fetchHandler(fetchRequest);
       await writeFetchResponse(response, fetchResponse);
@@ -263,17 +311,274 @@ function htmlResponse(body: string, status = 200): Response {
   });
 }
 
+function redirectResponse(location: string, extraHeaders: Record<string, string> = {}): Response {
+  return new Response(null, {
+    status: 302,
+    headers: {
+      Location: location,
+      "Access-Control-Allow-Origin": "*",
+      ...extraHeaders,
+    },
+  });
+}
+
+function markdownResponse(body: string, status = 200): Response {
+  return new Response(body, {
+    status,
+    headers: {
+      "Content-Type": "text/markdown; charset=utf-8",
+      "Access-Control-Allow-Origin": "*",
+    },
+  });
+}
+
 function corsPreflight(): Response {
+  const allowedHeaders = [
+    "Authorization",
+    "Content-Type",
+    "WorkOS-Signature",
+    "x-forge-user-id",
+    "x-forge-tenant-id",
+    "x-forge-organization-id",
+    "x-forge-organization-membership-id",
+    "x-forge-role",
+    "x-forge-roles",
+    "x-forge-permissions",
+    "x-forge-claims",
+    "x-forge-auth-kind",
+    "x-forge-trace-id",
+  ];
   return new Response(null, {
     status: 204,
     headers: {
       "Access-Control-Allow-Origin": "*",
       "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-      "Access-Control-Allow-Headers": "Authorization, Content-Type, x-forge-user-id, x-forge-tenant-id, x-forge-role",
+      "Access-Control-Allow-Headers": allowedHeaders.join(", "),
     },
   });
 }
 
+function hasWorkOSWebhookEndpoint(workspaceRoot: string): boolean {
+  return existsSync(join(workspaceRoot, `${GENERATED_DIR}/integrations/workos/http-handler.ts`));
+}
+
+function hasWorkOSAuthRoutes(workspaceRoot: string): boolean {
+  return existsSync(join(workspaceRoot, `${GENERATED_DIR}/integrations/workos/auth-routes.ts`));
+}
+
+function hasPublicAuthMd(workspaceRoot: string): boolean {
+  return existsSync(join(workspaceRoot, "public/auth.md"));
+}
+
+function hasPublicAuthMetadata(workspaceRoot: string): boolean {
+  return existsSync(join(workspaceRoot, "public/.well-known/oauth-protected-resource"));
+}
+
+function withGeneratedIntegrationRoutes(workspaceRoot: string, routes: DevRoute[]): DevRoute[] {
+  const next = [...routes];
+  if (
+    hasWorkOSAuthRoutes(workspaceRoot)
+  ) {
+    for (const route of [
+      { method: "GET" as const, path: "/login" },
+      { method: "GET" as const, path: "/callback" },
+      { method: "POST" as const, path: "/logout" },
+      { method: "GET" as const, path: "/session" },
+    ]) {
+      if (!next.some((candidate) => candidate.method === route.method && candidate.path === route.path)) {
+        next.push({ ...route, purpose: "auth" });
+      }
+    }
+  }
+  if (
+    hasPublicAuthMd(workspaceRoot) &&
+    !next.some((route) => route.method === "GET" && route.path === "/auth.md")
+  ) {
+    next.push({
+      method: "GET",
+      path: "/auth.md",
+      purpose: "auth-md",
+    });
+  }
+  if (
+    hasPublicAuthMetadata(workspaceRoot) &&
+    !next.some((route) => route.method === "GET" && route.path === "/.well-known/oauth-protected-resource")
+  ) {
+    next.push({
+      method: "GET",
+      path: "/.well-known/oauth-protected-resource",
+      purpose: "auth-metadata",
+    });
+  }
+  if (
+    hasWorkOSWebhookEndpoint(workspaceRoot) &&
+    !next.some((route) => route.method === "POST" && route.path === "/webhooks/workos")
+  ) {
+    next.push({
+      method: "POST",
+      path: "/webhooks/workos",
+      purpose: "webhook",
+    });
+  }
+  return next.sort((a, b) =>
+    a.path === b.path ? a.method.localeCompare(b.method) : a.path.localeCompare(b.path),
+  );
+}
+
+interface WorkOSDevSession {
+  user: Record<string, unknown>;
+  accessToken: string;
+  refreshToken?: string;
+  organizationId?: string;
+  organizationMembershipId?: string;
+  role?: string;
+  roles?: string[];
+  permissions?: string[];
+  issuedAt: number;
+}
+
+function normalizeLocalRedirect(value: string | null | undefined, fallback = "/"): string {
+  if (!value || !value.startsWith("/") || value.startsWith("//")) {
+    return fallback;
+  }
+  return value;
+}
+
+function workOSDevCookieName(envStore: ReturnType<typeof getRuntimeEnvStore>): string {
+  return envStore.resolve("WORKOS_COOKIE_NAME") || "forgeos_workos_session";
+}
+
+function base64urlJson(value: unknown): string {
+  return Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+}
+
+function decodeBase64urlJson(value: string): unknown {
+  return JSON.parse(Buffer.from(value, "base64url").toString("utf8")) as unknown;
+}
+
+function hmacBase64url(secret: string, payload: string): string {
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+function safeEqualString(left: string, right: string): boolean {
+  const a = Buffer.from(left);
+  const b = Buffer.from(right);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+function encodeWorkOSDevSession(session: WorkOSDevSession, cookiePassword: string): string {
+  const payload = base64urlJson(session);
+  return `${payload}.${hmacBase64url(cookiePassword, payload)}`;
+}
+
+function decodeWorkOSDevSession(value: string | undefined, cookiePassword: string): WorkOSDevSession | null {
+  if (!value) {
+    return null;
+  }
+  const [payload, signature] = value.split(".");
+  if (!payload || !signature || !safeEqualString(signature, hmacBase64url(cookiePassword, payload))) {
+    return null;
+  }
+  return decodeBase64urlJson(payload) as WorkOSDevSession;
+}
+
+function readRequestCookie(request: Request, name: string): string | undefined {
+  return (request.headers.get("cookie") ?? "")
+    .split(";")
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(`${name}=`))
+    ?.slice(name.length + 1);
+}
+
+function workOSDevSessionClaims(session: WorkOSDevSession): Record<string, unknown> {
+  const email = typeof session.user.email === "string" ? session.user.email : undefined;
+  const firstName = typeof session.user.firstName === "string" ? session.user.firstName : undefined;
+  const lastName = typeof session.user.lastName === "string" ? session.user.lastName : undefined;
+  return {
+    sub: String(session.user.id ?? ""),
+    ...(email ? { email } : {}),
+    ...(firstName || lastName ? { name: [firstName, lastName].filter(Boolean).join(" ") } : {}),
+    ...(session.organizationId ? { organization_id: session.organizationId } : {}),
+    ...(session.organizationMembershipId ? { organization_membership_id: session.organizationMembershipId } : {}),
+    ...(session.role ? { role: session.role } : {}),
+    ...(session.roles ? { roles: session.roles } : {}),
+    ...(session.permissions ? { permissions: session.permissions } : {}),
+  };
+}
+
+function createWorkOSDevSessionCookie(
+  envStore: ReturnType<typeof getRuntimeEnvStore>,
+  session: WorkOSDevSession,
+): string {
+  const cookiePassword = envStore.resolve("WORKOS_COOKIE_PASSWORD") ?? "";
+  const cookieName = workOSDevCookieName(envStore);
+  const value = encodeWorkOSDevSession(session, cookiePassword);
+  return `${cookieName}=${value}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=2592000`;
+}
+
+function clearWorkOSDevSessionCookie(envStore: ReturnType<typeof getRuntimeEnvStore>): string {
+  return `${workOSDevCookieName(envStore)}=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0`;
+}
+
+function workOSConfigDiagnostics(envStore: ReturnType<typeof getRuntimeEnvStore>, requireApiKey: boolean): Diagnostic[] {
+  const required = [
+    "WORKOS_CLIENT_ID",
+    "WORKOS_REDIRECT_URI",
+    "WORKOS_COOKIE_PASSWORD",
+    ...(requireApiKey ? ["WORKOS_API_KEY"] : []),
+  ];
+  return required
+    .filter((name) => !envStore.resolve(name))
+    .map((name) =>
+      createDiagnostic({
+        severity: "error",
+        code: FORGE_DEV_SERVER_ERROR,
+        message: `${name} is required for WorkOS AuthKit dev routes`,
+        fixHint: "Run forge add auth workos, copy .env.example to .env.local, and fill WorkOS values.",
+      }),
+    );
+}
+
+function workOSAuthorizationUrl(envStore: ReturnType<typeof getRuntimeEnvStore>, state: string): string {
+  const url = new URL("https://api.workos.com/user_management/authorize");
+  url.searchParams.set("provider", "authkit");
+  url.searchParams.set("client_id", envStore.resolve("WORKOS_CLIENT_ID") ?? "");
+  url.searchParams.set("redirect_uri", envStore.resolve("WORKOS_REDIRECT_URI") ?? "");
+  if (state) {
+    url.searchParams.set("state", state);
+  }
+  return url.toString();
+}
+
+async function authenticateWorkOSCode(workspaceRoot: string, envStore: ReturnType<typeof getRuntimeEnvStore>, code: string) {
+  const req = createRequire(join(workspaceRoot, "package.json"));
+  const localEntry = join(workspaceRoot, "node_modules/@workos-inc/node/index.js");
+  const resolved = existsSync(localEntry) ? localEntry : req.resolve("@workos-inc/node");
+  const workosModule = await import(pathToFileURL(resolved).href) as {
+    createWorkOS?: (options: { apiKey: string; clientId: string }) => unknown;
+    WorkOS?: new (options: { apiKey: string; clientId: string }) => unknown;
+  };
+  const client = workosModule.createWorkOS
+    ? workosModule.createWorkOS({
+        apiKey: envStore.resolve("WORKOS_API_KEY") ?? "",
+        clientId: envStore.resolve("WORKOS_CLIENT_ID") ?? "",
+      })
+    : workosModule.WorkOS
+      ? new workosModule.WorkOS({
+          apiKey: envStore.resolve("WORKOS_API_KEY") ?? "",
+          clientId: envStore.resolve("WORKOS_CLIENT_ID") ?? "",
+        })
+      : null;
+  const userManagement = (client as { userManagement?: { authenticateWithCode?: (input: { code: string; clientId: string }) => Promise<Record<string, unknown>> } } | null)?.userManagement;
+  if (!userManagement?.authenticateWithCode) {
+    throw new Error("@workos-inc/node does not expose userManagement.authenticateWithCode");
+  }
+  return userManagement.authenticateWithCode({
+    code,
+    clientId: envStore.resolve("WORKOS_CLIENT_ID") ?? "",
+  });
+}
+
 function acceptsHtml(request: Request): boolean {
   return (request.headers.get("accept") ?? "").includes("text/html");
 }
@@ -406,6 +711,22 @@ function parseInvokeName(pathname: string, prefix: string): string | null {
   return name.length > 0 ? decodeURIComponent(name) : null;
 }
 
+function parseExternalInvoke(pathname: string): {
+  serviceName: string;
+  kind: "command" | "query";
+  entryName: string;
+} | null {
+  const match = pathname.match(/^\/external\/([^/]+)\/(commands|queries)\/([^/]+)$/);
+  if (!match) {
+    return null;
+  }
+  return {
+    serviceName: decodeURIComponent(match[1]!),
+    kind: match[2] === "commands" ? "command" : "query",
+    entryName: decodeURIComponent(match[3]!),
+  };
+}
+
 function loadAgentToolRegistry(workspaceRoot: string): AgentToolRegistry | null {
   return readGeneratedJson<AgentToolRegistry>(
     workspaceRoot,
@@ -413,6 +734,18 @@ function loadAgentToolRegistry(workspaceRoot: string): AgentToolRegistry | null
   );
 }
 
+async function listDatabaseTables(adapter: NonNullable<DevServerState["adapter"]>): Promise<string[]> {
+  const result = await adapter.query(
+    `SELECT c.relname AS table_name
+     FROM pg_catalog.pg_class c
+     JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = 'public'
+       AND c.relkind IN ('r', 'p')
+     ORDER BY c.relname`,
+  );
+  return result.rows.map((row) => String(row.table_name));
+}
+
 type RuntimeAgentDefinition = {
   provider?: ForgeAiProvider;
   model: string;
@@ -562,6 +895,7 @@ async function buildAiSdkTools(input: {
   telemetry: ReturnType<typeof createTelemetryContext> | ReturnType<typeof createNoopTelemetryContext>;
   env: Record<string, string | undefined>;
   auth: Awaited<ReturnType<typeof authenticateHeaders>>;
+  deltaRecorder?: DevServerOptions["deltaRecorder"];
 }): Promise<Record<string, unknown>> {
   const { tool } = await import("ai");
   return Object.fromEntries(
@@ -612,6 +946,13 @@ async function buildAiSdkTools(input: {
                 latencyMs: Date.now() - startedAt,
                 status: "completed",
               });
+              await input.deltaRecorder?.recordAgentTool({
+                toolName: name,
+                risk: definition.risk ?? "external",
+                status: "completed",
+                traceId: input.traceId,
+                durationMs: Date.now() - startedAt,
+              });
               return output;
             } catch (error) {
               await input.telemetry.capture("forge.ai.tool.failed", {
@@ -624,6 +965,13 @@ async function buildAiSdkTools(input: {
                 status: "failed",
                 error: error instanceof Error ? error.message : String(error),
               });
+              await input.deltaRecorder?.recordAgentTool({
+                toolName: name,
+                risk: definition.risk ?? "external",
+                status: "failed",
+                traceId: input.traceId,
+                durationMs: Date.now() - startedAt,
+              });
               throw error;
             }
           },
@@ -651,6 +999,7 @@ export async function startDevServer(
   options: DevServerOptions,
 ): Promise<DevServerHandle> {
   const workspaceRoot = options.workspaceRoot.replace(/\\/g, "/");
+  const deltaRecorder = options.deltaRecorder;
   const authConfig = loadAuthConfigFromEnv(workspaceRoot, {
     defaultMode: "dev-headers",
   });
@@ -711,7 +1060,7 @@ export async function startDevServer(
     );
 
     if (sqlPlan) {
-      const migrationDiagnostics = await applyMigrations(adapter, sqlPlan);
+      const migrationDiagnostics = await applyDevMigrations(adapter, sqlPlan, dbMode);
       const errors = migrationDiagnostics.filter(
         (diagnostic) => diagnostic.severity === "error",
       );
@@ -731,6 +1080,7 @@ export async function startDevServer(
     mockAi: options.mockAi,
     db: serverState.adapter,
   });
+  refreshRuntimeModuleNamespace("dev-start");
 
   function loadArtifacts(): {
     devManifest: DevManifest;
@@ -764,22 +1114,96 @@ export async function startDevServer(
   }
 
   const initialArtifacts = loadArtifacts();
+  let currentRoutes = withGeneratedIntegrationRoutes(workspaceRoot, devManifest.routes);
+  let currentRuntimeEntryCount = runtimeGraph.entries.length;
+
+  async function reloadGeneratedArtifacts(reason = "manual"): Promise<DevServerReloadResult> {
+    try {
+      refreshRuntimeModuleNamespace(reason);
+      const fresh = loadArtifacts();
+      currentRoutes = withGeneratedIntegrationRoutes(workspaceRoot, fresh.devManifest.routes);
+      currentRuntimeEntryCount = fresh.runtimeGraph.entries.length;
+      const diagnostics: Diagnostic[] = [];
+      let migrated = false;
+
+      if (serverState.adapter) {
+        const sqlPlan = readGeneratedJson<SqlPlan>(
+          workspaceRoot,
+          `${GENERATED_DIR}/sqlPlan.json`,
+        );
+        if (sqlPlan) {
+          migrated = true;
+          diagnostics.push(...(await applyDevMigrations(serverState.adapter, sqlPlan, options.db)));
+        }
+        if (diagnostics.every((diagnostic) => diagnostic.severity !== "error")) {
+          await ensureLiveInvalidationSchema(serverState.adapter);
+        }
+      }
+
+      if (
+        options.worker &&
+        serverState.adapter &&
+        diagnostics.every((diagnostic) => diagnostic.severity !== "error")
+      ) {
+        serverState.outboxWorker?.stop();
+        serverState.outboxWorker = startOutboxWorker(
+          serverState.adapter,
+          workspaceRoot,
+          fresh.tableMap,
+          fresh.runtimeGraph.entries,
+          { mock: options.mock, intervalMs: 2_000, telemetrySinks, workspaceRoot },
+        );
+      }
+
+      return {
+        ok: diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
+        reason,
+        migrated,
+        routes: currentRoutes.length,
+        runtimeEntries: currentRuntimeEntryCount,
+        worker: serverState.outboxWorker?.isRunning() ? "running" : "stopped",
+        diagnostics,
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        reason,
+        migrated: false,
+        routes: currentRoutes.length,
+        runtimeEntries: currentRuntimeEntryCount,
+        worker: serverState.outboxWorker?.isRunning() ? "running" : "stopped",
+        diagnostics: [
+          createDiagnostic({
+            severity: "error",
+            code: FORGE_DEV_SERVER_ERROR,
+            message: error instanceof Error ? error.message : "failed to reload generated artifacts",
+          }),
+        ],
+      };
+    }
+  }
+
   const liveManager = serverState.adapter
     ? createLiveSubscriptionManager({
         workspaceRoot,
         adapter: serverState.adapter,
         loadTableMap: () => loadArtifacts().tableMap,
         enablePolling: true,
+        limits: {
+          ...DEFAULT_LIVE_LIMITS,
+          maxSubscriptionsPerClient: Number(process.env.FORGE_DEV_LIVE_MAX_SUBSCRIPTIONS ?? "250"),
+        },
         pollIntervalMs: Number(process.env.FORGE_LIVE_POLL_INTERVAL_MS ?? "1000"),
       })
     : null;
+  const workosReplayStore = new MemoryWebhookReplayStore();
 
   if (options.worker && serverState.adapter) {
     serverState.outboxWorker = startOutboxWorker(
       serverState.adapter,
       workspaceRoot,
       initialArtifacts.tableMap,
-      runtimeGraph.entries,
+      initialArtifacts.runtimeGraph.entries,
       { mock: options.mock, intervalMs: 2_000, telemetrySinks, workspaceRoot },
     );
   }
@@ -803,6 +1227,7 @@ export async function startDevServer(
           const listed = listEntries(workspaceRoot);
           const queries = listQueries(workspaceRoot);
           const liveQueries = loadLiveQueryRegistry(workspaceRoot);
+          const external = loadExternalServiceGraph(workspaceRoot);
           const entries = [
             ...queries.queries.map((query) => ({
               name: query.name,
@@ -825,10 +1250,18 @@ export async function startDevServer(
                   : `/actions/${entry.name}`,
               method: "POST",
             })),
+            ...(external.graph?.services.flatMap((service) =>
+              service.entries.map((entry) => ({
+                name: `${service.name}.${entry.name}`,
+                kind: `external:${entry.kind}`,
+                path: `/external/${encodeURIComponent(service.name)}/${entry.kind === "command" ? "commands" : "queries"}/${encodeURIComponent(entry.name)}`,
+                method: entry.method ?? "POST",
+              }))
+            ) ?? []),
           ].sort((a, b) =>
             a.path === b.path ? a.kind.localeCompare(b.kind) : a.path.localeCompare(b.path),
           );
-          const routes = currentDevManifest.routes.map((route) => ({
+          const routes = currentRoutes.map((route) => ({
             method: route.method,
             path: route.path,
             purpose: route.purpose,
@@ -846,6 +1279,7 @@ export async function startDevServer(
               ...listed.diagnostics,
               ...queries.diagnostics,
               ...(liveQueries.registry?.diagnostics ?? []),
+              ...external.diagnostics,
             ],
           };
 
@@ -884,6 +1318,16 @@ export async function startDevServer(
           const aiRegistry = loadAiRegistry(workspaceRoot);
           const aiCheck = checkAiProviders(envStore, aiRegistry, secretRegistry);
           const mockAi = isMockAiEnabled({ mockAi: options.mockAi });
+          const productionAuthMode = authConfig.mode === "oidc" || authConfig.mode === "jwt";
+          const missingAuthConfig = [
+            ...(productionAuthMode && !authConfig.issuer ? ["FORGE_AUTH_ISSUER"] : []),
+            ...(productionAuthMode && !authConfig.jwksUri ? ["FORGE_AUTH_JWKS_URI"] : []),
+          ];
+          const workosClientId = envStore.resolve("WORKOS_CLIENT_ID") || envStore.resolve("VITE_WORKOS_CLIENT_ID");
+          const suggestedWorkOSJwksUri = workosClientId
+            ? `https://api.workos.com/sso/jwks/${workosClientId}`
+            : "https://api.workos.com/sso/jwks/<WORKOS_CLIENT_ID>";
+          const authProductionReady = !productionAuthMode || missingAuthConfig.length === 0;
 
           return jsonResponse({
             ok: true,
@@ -912,6 +1356,12 @@ export async function startDevServer(
               audienceConfigured: Boolean(authConfig.audience),
               jwksConfigured: Boolean(authConfig.jwksUri),
               requiresTenant: authConfig.requiresTenant,
+              ready: authProductionReady,
+              productionReady: authProductionReady,
+              missing: missingAuthConfig,
+              ...(missingAuthConfig.includes("FORGE_AUTH_JWKS_URI")
+                ? { suggestedWorkOSJwksUri }
+                : {}),
             },
             env: {
               loadedFiles: envStore.loadedFiles,
@@ -931,6 +1381,268 @@ export async function startDevServer(
           });
         }
 
+        if (["/login", "/callback", "/logout", "/session"].includes(pathname)) {
+          if (!hasWorkOSAuthRoutes(workspaceRoot)) {
+            return jsonResponse(
+              {
+                ok: false,
+                diagnostics: [
+                  createDiagnostic({
+                    severity: "error",
+                    code: FORGE_RUNTIME_NOT_FOUND,
+                    message: "WorkOS AuthKit routes are not installed",
+                    fixHint: "Run forge add auth workos, then forge generate.",
+                  }),
+                ],
+              },
+              404,
+            );
+          }
+
+          const envStore = getRuntimeEnvStore(workspaceRoot);
+
+          if (pathname === "/login") {
+            if (request.method !== "GET") {
+              return jsonResponse({ ok: false, error: "method_not_allowed" }, 405, { Allow: "GET, OPTIONS" });
+            }
+            const diagnostics = workOSConfigDiagnostics(envStore, false);
+            if (diagnostics.length > 0) {
+              return jsonResponse({ ok: false, diagnostics }, 503);
+            }
+            const returnTo = normalizeLocalRedirect(new URL(request.url).searchParams.get("returnTo"));
+            return redirectResponse(workOSAuthorizationUrl(envStore, returnTo));
+          }
+
+          if (pathname === "/callback") {
+            if (request.method !== "GET") {
+              return jsonResponse({ ok: false, error: "method_not_allowed" }, 405, { Allow: "GET, OPTIONS" });
+            }
+            const diagnostics = workOSConfigDiagnostics(envStore, true);
+            if (diagnostics.length > 0) {
+              return jsonResponse({ ok: false, diagnostics }, 503);
+            }
+            const url = new URL(request.url);
+            const code = url.searchParams.get("code");
+            if (!code) {
+              return jsonResponse({ ok: false, error: "missing_code" }, 400);
+            }
+            try {
+              const result = await authenticateWorkOSCode(workspaceRoot, envStore, code);
+              const user = (result.user ?? {}) as Record<string, unknown>;
+              const organization = (result.organization ?? {}) as Record<string, unknown>;
+              const membership = (result.organizationMembership ?? {}) as Record<string, unknown>;
+              const accessToken = typeof result.accessToken === "string" ? result.accessToken : "";
+              const refreshToken = typeof result.refreshToken === "string" ? result.refreshToken : undefined;
+              const session: WorkOSDevSession = {
+                user,
+                accessToken,
+                ...(refreshToken ? { refreshToken } : {}),
+                ...(typeof result.organizationId === "string"
+                  ? { organizationId: result.organizationId }
+                  : typeof organization.id === "string"
+                    ? { organizationId: organization.id }
+                    : {}),
+                ...(typeof result.organizationMembershipId === "string"
+                  ? { organizationMembershipId: result.organizationMembershipId }
+                  : typeof membership.id === "string"
+                    ? { organizationMembershipId: membership.id }
+                    : {}),
+                ...(typeof result.role === "string" ? { role: result.role } : {}),
+                ...(Array.isArray(result.roles)
+                  ? { roles: result.roles.filter((role): role is string => typeof role === "string") }
+                  : {}),
+                ...(Array.isArray(result.permissions)
+                  ? {
+                      permissions: result.permissions.filter(
+                        (permission): permission is string => typeof permission === "string",
+                      ),
+                    }
+                  : {}),
+                issuedAt: Math.floor(Date.now() / 1000),
+              };
+              return redirectResponse(
+                normalizeLocalRedirect(
+                  url.searchParams.get("state"),
+                  normalizeLocalRedirect(envStore.resolve("WORKOS_POST_LOGIN_REDIRECT_URI"), "/"),
+                ),
+                { "Set-Cookie": createWorkOSDevSessionCookie(envStore, session) },
+              );
+            } catch (error) {
+              return jsonResponse(
+                {
+                  ok: false,
+                  diagnostics: [
+                    createDiagnostic({
+                      severity: "error",
+                      code: FORGE_DEV_SERVER_ERROR,
+                      message: error instanceof Error ? error.message : "WorkOS callback failed",
+                      fixHint: "Ensure @workos-inc/node is installed and WorkOS env values are valid.",
+                    }),
+                  ],
+                },
+                500,
+              );
+            }
+          }
+
+          if (pathname === "/logout") {
+            if (request.method !== "POST") {
+              return jsonResponse({ ok: false, error: "method_not_allowed" }, 405, { Allow: "POST, OPTIONS" });
+            }
+            return redirectResponse(
+              normalizeLocalRedirect(envStore.resolve("WORKOS_POST_LOGOUT_REDIRECT_URI"), "/"),
+              { "Set-Cookie": clearWorkOSDevSessionCookie(envStore) },
+            );
+          }
+
+          if (pathname === "/session") {
+            if (request.method !== "GET") {
+              return jsonResponse({ ok: false, error: "method_not_allowed" }, 405, { Allow: "GET, OPTIONS" });
+            }
+            const cookiePassword = envStore.resolve("WORKOS_COOKIE_PASSWORD");
+            if (!cookiePassword) {
+              return jsonResponse({ ok: false, diagnostics: workOSConfigDiagnostics(envStore, false) }, 503);
+            }
+            const session = decodeWorkOSDevSession(
+              readRequestCookie(request, workOSDevCookieName(envStore)),
+              cookiePassword,
+            );
+            return session
+              ? jsonResponse({ ok: true, session: { user: session.user, claims: workOSDevSessionClaims(session) } })
+              : jsonResponse({ ok: false, session: null }, 401);
+          }
+        }
+
+        if ((request.method === "GET" || request.method === "HEAD") && pathname === "/auth.md") {
+          const authMdPath = join(workspaceRoot, "public/auth.md");
+          if (!existsSync(authMdPath)) {
+            return jsonResponse(
+              {
+                ok: false,
+                diagnostics: [
+                  createDiagnostic({
+                    severity: "error",
+                    code: FORGE_RUNTIME_NOT_FOUND,
+                    message: "public/auth.md was not found",
+                    fixHint: "Run forge authmd generate.",
+                  }),
+                ],
+              },
+              404,
+            );
+          }
+          return request.method === "HEAD" ? new Response(null, { status: 200, headers: { "content-type": "text/markdown; charset=utf-8" } }) : markdownResponse(readFileSync(authMdPath, "utf8"));
+        }
+
+        if ((request.method === "GET" || request.method === "HEAD") && pathname === "/.well-known/oauth-protected-resource") {
+          const metadataPath = join(workspaceRoot, "public/.well-known/oauth-protected-resource");
+          if (!existsSync(metadataPath)) {
+            return jsonResponse(
+              {
+                ok: false,
+                diagnostics: [
+                  createDiagnostic({
+                    severity: "error",
+                    code: FORGE_RUNTIME_NOT_FOUND,
+                    message: "public/.well-known/oauth-protected-resource was not found",
+                    fixHint: "Run forge authmd generate.",
+                  }),
+                ],
+              },
+              404,
+            );
+          }
+          return request.method === "HEAD" ? new Response(null, { status: 200, headers: { "content-type": "application/json; charset=utf-8" } }) : jsonResponse(JSON.parse(readFileSync(metadataPath, "utf8")));
+        }
+
+        if (pathname === "/webhooks/workos") {
+          if (!hasWorkOSWebhookEndpoint(workspaceRoot)) {
+            return jsonResponse(
+              {
+                ok: false,
+                diagnostics: [
+                  createDiagnostic({
+                    severity: "error",
+                    code: FORGE_RUNTIME_NOT_FOUND,
+                    message: "WorkOS webhook endpoint is not installed",
+                    fixHint: "Run forge add auth workos, then forge generate.",
+                  }),
+                ],
+              },
+              404,
+            );
+          }
+          if (request.method !== "POST") {
+            return jsonResponse(
+              {
+                ok: false,
+                diagnostics: [
+                  createDiagnostic({
+                    severity: "error",
+                    code: FORGE_DEV_INVOKE_FAILED,
+                    message: "WorkOS webhook endpoint requires POST /webhooks/workos",
+                  }),
+                ],
+                example: {
+                  method: "POST",
+                  path: "/webhooks/workos",
+                  headers: { "WorkOS-Signature": "t=<ms>,v1=<hex>" },
+                },
+              },
+              405,
+              { Allow: "POST, OPTIONS" },
+            );
+          }
+
+          const payload = await request.text();
+          let eventId: string | undefined;
+          let eventType: string | undefined;
+          try {
+            const parsed = JSON.parse(payload) as { id?: unknown; event?: unknown; type?: unknown };
+            eventId = typeof parsed.id === "string" ? parsed.id : undefined;
+            eventType =
+              typeof parsed.event === "string"
+                ? parsed.event
+                : typeof parsed.type === "string"
+                  ? parsed.type
+                  : undefined;
+          } catch {
+            // Signature verification still returns the authoritative failure for malformed bodies.
+          }
+
+          const envStore = getRuntimeEnvStore(workspaceRoot);
+          const secret = envStore.resolve("WORKOS_WEBHOOK_SECRET") ?? "";
+          const verification = await verifyWebhookSignature({
+            provider: "workos",
+            secret,
+            payload,
+            signatureHeader: request.headers.get("WorkOS-Signature"),
+            eventId,
+            replayStore: workosReplayStore,
+          });
+          if (!verification.ok) {
+            return jsonResponse(
+              {
+                ok: false,
+                diagnostics: [
+                  createDiagnostic({
+                    severity: "error",
+                    code: verification.code ?? FORGE_DEV_SERVER_ERROR,
+                    message: verification.reason ?? "WorkOS webhook signature verification failed",
+                  }),
+                ],
+              },
+              401,
+            );
+          }
+          return jsonResponse({
+            ok: true,
+            provider: "workos",
+            eventId: eventId ?? null,
+            event: eventType ?? "unknown",
+          });
+        }
+
         if (request.method === "GET" && pathname === "/live") {
           const liveQueries = loadLiveQueryRegistry(workspaceRoot).liveQueries;
           return jsonResponse({
@@ -1028,6 +1740,13 @@ export async function startDevServer(
               "NaN",
           );
           let subscriptionId: string | null = null;
+          const cleanupSubscription = () => {
+            if (subscriptionId) {
+              liveManager.unsubscribe(subscriptionId);
+              subscriptionId = null;
+            }
+          };
+          request.signal.addEventListener("abort", cleanupSubscription, { once: true });
 
           return createSseResponse(
             async (send, close) => {
@@ -1039,6 +1758,11 @@ export async function startDevServer(
                 send,
               });
               subscriptionId = subscription.id;
+              if (request.signal.aborted) {
+                cleanupSubscription();
+                close();
+                return;
+              }
               const known = loadLiveQueryRegistry(workspaceRoot).liveQueries.some(
                 (liveQuery) => liveQuery.name === name,
               );
@@ -1047,9 +1771,7 @@ export async function startDevServer(
               }
             },
             () => {
-              if (subscriptionId) {
-                liveManager.unsubscribe(subscriptionId);
-              }
+              cleanupSubscription();
             },
             {
               heartbeatIntervalMs: Number(process.env.FORGE_LIVE_HEARTBEAT_MS ?? "15000"),
@@ -1314,6 +2036,7 @@ export async function startDevServer(
               telemetry,
               env: envStore.snapshot(),
               auth,
+              deltaRecorder,
             });
             const { ToolLoopAgent, createAgentUIStreamResponse, hasToolCall, stepCountIs } = await import("ai");
             const stopWhen =
@@ -1485,12 +2208,11 @@ export async function startDevServer(
 
         if (request.method === "GET" && pathname === "/db/tables") {
           if (serverState.adapter) {
-            const result = await serverState.adapter.query(
-              `SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' AND table_type = 'BASE TABLE' ORDER BY table_name`,
-            );
             return jsonResponse({
               ok: true,
-              tables: result.rows.map((row) => String(row.table_name)),
+              tables: serverState.adapter.kind === "memory"
+                ? Object.keys(tableMap).sort()
+                : await listDatabaseTables(serverState.adapter),
             });
           }
 
@@ -1501,6 +2223,15 @@ export async function startDevServer(
         }
 
         if (request.method === "GET") {
+          const externalInvoke = parseExternalInvoke(pathname);
+          if (externalInvoke) {
+            return methodHelpResponse({
+              kind: externalInvoke.kind,
+              name: `${externalInvoke.serviceName}.${externalInvoke.entryName}`,
+              path: `/external/${externalInvoke.serviceName}/${externalInvoke.kind === "command" ? "commands" : "queries"}/${externalInvoke.entryName}`,
+            });
+          }
+
           const queryName = parseInvokeName(pathname, "/queries/");
           if (queryName) {
             return methodHelpResponse({
@@ -1658,6 +2389,43 @@ export async function startDevServer(
             return jsonResponse({ ok: true, ...result });
           }
 
+          const externalInvoke = parseExternalInvoke(pathname);
+          if (externalInvoke) {
+            const args = await parseRequestArgs(request);
+            const auth = await authenticateHeaders(request.headers, authConfig);
+            const result = await runExternalEntry(
+              workspaceRoot,
+              {
+                ...externalInvoke,
+                args,
+                auth,
+                requestHeaders: request.headers,
+              },
+              { adapter: serverState.adapter },
+            );
+            const policyDenied = result.diagnostics.some(
+              (diagnostic) => diagnostic.code === FORGE_POLICY_DENIED,
+            );
+            await deltaRecorder?.recordRuntimeCall({
+              entryName: `${externalInvoke.serviceName}.${externalInvoke.entryName}`,
+              entryKind: externalInvoke.kind,
+              service: externalInvoke.serviceName,
+              result: policyDenied ? "denied" : result.ok ? "success" : "failed",
+              diagnostics: result.diagnostics,
+              traceId: result.traceId,
+            });
+            return jsonResponse(
+              {
+                ok: result.ok,
+                result: result.result,
+                diagnostics: result.diagnostics,
+                traceId: result.traceId,
+              },
+              result.ok ? 200 : policyDenied ? 403 : 400,
+              result.traceId ? { "x-forge-trace-id": result.traceId } : {},
+            );
+          }
+
           let entryName: string | null = null;
           let expectedKind: "command" | "action" | null = null;
           let queryName: string | null = null;
@@ -1707,6 +2475,13 @@ export async function startDevServer(
             const policyDenied = result.diagnostics.some(
               (diagnostic) => diagnostic.code === FORGE_POLICY_DENIED,
             );
+            await deltaRecorder?.recordRuntimeCall({
+              entryName: queryName,
+              entryKind: "query",
+              result: policyDenied ? "denied" : result.ok ? "success" : "failed",
+              diagnostics: result.diagnostics,
+              traceId: result.traceId,
+            });
 
             return jsonResponse(
               {
@@ -1777,6 +2552,13 @@ export async function startDevServer(
             const policyDenied = result.diagnostics.some(
               (diagnostic) => diagnostic.code === FORGE_POLICY_DENIED,
             );
+            await deltaRecorder?.recordRuntimeCall({
+              entryName,
+              entryKind: entry.kind,
+              result: policyDenied ? "denied" : result.ok ? "success" : "failed",
+              diagnostics: result.diagnostics,
+              traceId: result.traceId,
+            });
 
             if (policyDenied) {
               const denied = result.diagnostics.find(
@@ -1862,23 +2644,32 @@ export async function startDevServer(
   const protocol = "http";
   const url = `${protocol}://${host}:${port}`;
 
-  return {
+  const handle: DevServerHandle = {
     host,
     port,
     url,
-    routes: devManifest.routes,
+    routes: currentRoutes,
     state: serverState,
     outboxWorker: serverState.outboxWorker,
+    reload: async (reason?: string) => {
+      const result = await reloadGeneratedArtifacts(reason);
+      handle.routes = currentRoutes;
+      handle.outboxWorker = serverState.outboxWorker;
+      return result;
+    },
     stop: () => {
       serverState.outboxWorker?.stop();
       liveManager?.stop();
       server.stop(true);
       restoreRuntimeEnvironment();
+      disposeRuntimeModuleNamespace();
       const adapter = serverState.adapter;
       serverState.adapter = null;
       void adapter?.close().catch(() => undefined);
     },
   };
+
+  return handle;
 }
 
 export function resolveDevPort(explicit?: number): number {