forgeos 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/forge/dev/server.ts

@@ -6,9 +6,11 @@ import {
   type ServerResponse,
 } from "node:http";
 import { join } from "node:path";
+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,12 +24,15 @@ 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 { 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";
@@ -48,7 +53,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";
@@ -59,9 +64,12 @@ import {
 import { checkAiProviders, loadAiRegistry } from "../runtime/ai/check.ts";
 import { isMockAiEnabled } from "../runtime/ai/state.ts";
 import { createAiContext } from "../runtime/ai/context.ts";
+import type { ForgeAiProvider, ForgeAiToolDefinition } from "../runtime/ai/types.ts";
+import { resolveLanguageModel } from "../runtime/ai/providers.ts";
 import { createRuntimeSecretsBundle } from "../runtime/secrets/runtime-bundle.ts";
-import { createNoopTelemetryContext } from "../runtime/telemetry/context.ts";
+import { createNoopTelemetryContext, createTelemetryContext } from "../runtime/telemetry/context.ts";
 import { generateTraceId } from "../runtime/telemetry/correlation.ts";
+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";
@@ -71,6 +79,37 @@ import {
 } 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;
@@ -92,7 +131,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)) {
@@ -109,6 +148,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);
@@ -151,10 +191,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);
@@ -402,6 +445,276 @@ 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,
+    `${GENERATED_DIR}/agentTools.json`,
+  );
+}
+
+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;
+  instructions: string;
+  tools?: Record<string, ForgeAiToolDefinition> | string[];
+  stopWhen?: { kind: "stepCount"; maxSteps: number } | { kind: "toolCall"; toolName: string };
+  maxSteps?: number;
+};
+
+async function loadNamedAgentDefinition(
+  workspaceRoot: string,
+  name: string | undefined,
+): Promise<RuntimeAgentDefinition | null> {
+  if (!name) {
+    return null;
+  }
+  const registry = loadAiRegistry(workspaceRoot);
+  const metadata = registry?.agents.find((agent) => agent.name === name);
+  if (!metadata) {
+    throw new Error(`unknown Forge AI agent '${name}'`);
+  }
+
+  const mod = (await import(pathToFileURL(join(workspaceRoot, metadata.file)).href)) as Record<
+    string,
+    unknown
+  >;
+  const definition = mod[metadata.name];
+  if (!definition || typeof definition !== "object") {
+    throw new Error(`Forge AI agent '${name}' was not exported from ${metadata.file}`);
+  }
+
+  const agent = definition as Partial<RuntimeAgentDefinition>;
+  if (!agent.model || !agent.instructions) {
+    throw new Error(`Forge AI agent '${name}' is missing model or instructions`);
+  }
+  return {
+    provider: agent.provider ?? metadata.provider,
+    model: agent.model,
+    instructions: agent.instructions,
+    tools: agent.tools,
+    stopWhen:
+      agent.stopWhen ??
+      (metadata.stopWhen.kind === "default" ? undefined : metadata.stopWhen),
+    maxSteps: agent.maxSteps,
+  };
+}
+
+function explicitAgentTools(
+  definition: RuntimeAgentDefinition | null,
+): Record<string, ForgeAiToolDefinition> {
+  if (!definition?.tools || Array.isArray(definition.tools)) {
+    return {};
+  }
+  return Object.fromEntries(
+    Object.entries(definition.tools).filter(([, toolDefinition]) =>
+      Boolean(
+        toolDefinition &&
+          typeof toolDefinition === "object" &&
+          "handler" in toolDefinition &&
+          "inputSchema" in toolDefinition,
+      ),
+    ),
+  );
+}
+
+function buildAutoAgentTools(input: {
+  workspaceRoot: string;
+  registry: AgentToolRegistry | null;
+  selected?: string[];
+  adapter: DevServerState["adapter"];
+  tableMap: Record<string, TableMapEntry>;
+  auth: Awaited<ReturnType<typeof authenticateHeaders>>;
+  liveManager?: ReturnType<typeof createLiveSubscriptionManager> | null;
+  json: boolean;
+  mock: boolean;
+}): Record<string, ForgeAiToolDefinition> {
+  const selected = new Set(input.selected ?? []);
+  const includeAll = selected.size === 0;
+  const tools: Record<string, ForgeAiToolDefinition> = {};
+  for (const toolInfo of input.registry?.autoTools ?? []) {
+    if (!includeAll && !selected.has(toolInfo.name) && !selected.has(toolInfo.sourceName)) {
+      continue;
+    }
+    tools[toolInfo.name] = {
+      description: `${toolInfo.readOnly ? "Read" : "Execute"} Forge ${toolInfo.sourceKind} '${toolInfo.sourceName}'. Policy: ${toolInfo.policy ?? "none"}.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          args: {
+            type: "object",
+            additionalProperties: true,
+          },
+        },
+        additionalProperties: true,
+      },
+      risk: toolInfo.readOnly ? "read" : "write",
+      needsApproval: !toolInfo.readOnly,
+      handler: async (_ctx, rawInput) => {
+        const objectInput =
+          rawInput && typeof rawInput === "object" && !Array.isArray(rawInput)
+            ? rawInput as { args?: unknown }
+            : {};
+        const args = objectInput.args ?? rawInput ?? {};
+        if (!input.adapter) {
+          throw new Error("database not connected");
+        }
+        if (toolInfo.sourceKind === "query" || toolInfo.sourceKind === "liveQuery") {
+          const result = await runQuery(
+            input.workspaceRoot,
+            toolInfo.sourceName,
+            { args, auth: input.auth },
+            {
+              adapter: input.adapter,
+              tableMap: input.tableMap,
+            },
+          );
+          if (!result.ok) {
+            throw new Error(result.diagnostics.map((diagnostic) => diagnostic.message).join("; "));
+          }
+          return { result: result.result, traceId: result.traceId };
+        }
+        const result = await runEntry(input.workspaceRoot, toolInfo.sourceName, {
+          json: input.json,
+          mock: input.mock,
+          args,
+          db: input.adapter,
+          auth: input.auth,
+          liveManager: input.liveManager ?? undefined,
+        });
+        if (!result.ok) {
+          throw new Error(result.diagnostics.map((diagnostic) => diagnostic.message).join("; "));
+        }
+        return { result: result.result, traceId: result.traceId };
+      },
+    };
+  }
+  return tools;
+}
+
+async function buildAiSdkTools(input: {
+  tools: Record<string, ForgeAiToolDefinition>;
+  provider: ForgeAiProvider;
+  model: string;
+  purpose?: string;
+  traceId: string;
+  secrets: ReturnType<typeof createRuntimeSecretsBundle>["secrets"];
+  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(
+    Object.entries(input.tools).map(([name, definition]) => {
+      const needsApproval = definition.needsApproval;
+      return [
+        name,
+        tool({
+          description: definition.description,
+          inputSchema: definition.inputSchema as never,
+          ...(definition.outputSchema ? { outputSchema: definition.outputSchema as never } : {}),
+          ...(definition.strict !== undefined ? { strict: definition.strict } : {}),
+          ...(needsApproval !== undefined
+            ? {
+                needsApproval:
+                  typeof needsApproval === "function"
+                    ? async ({ args }: { args: unknown }) =>
+                        Boolean(await needsApproval(args as never))
+                    : needsApproval,
+              }
+            : {}),
+          execute: async (args: unknown) => {
+            const startedAt = Date.now();
+            await input.telemetry.capture("forge.ai.tool.started", {
+              traceId: input.traceId,
+              provider: input.provider,
+              model: input.model,
+              purpose: input.purpose,
+              tool: name,
+              risk: definition.risk ?? "external",
+            });
+            try {
+              const output = await definition.handler(
+                {
+                  secrets: input.secrets,
+                  env: input.env,
+                  telemetry: input.telemetry,
+                  auth: input.auth,
+                },
+                args as never,
+              );
+              await input.telemetry.capture("forge.ai.tool.completed", {
+                traceId: input.traceId,
+                provider: input.provider,
+                model: input.model,
+                purpose: input.purpose,
+                tool: name,
+                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", {
+                traceId: input.traceId,
+                provider: input.provider,
+                model: input.model,
+                purpose: input.purpose,
+                tool: name,
+                latencyMs: Date.now() - startedAt,
+                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;
+            }
+          },
+        } as never),
+      ];
+    }),
+  );
+}
+
 async function parseRequestArgs(request: Request): Promise<unknown> {
   const contentType = request.headers.get("content-type") ?? "";
   if (!contentType.includes("application/json")) {
@@ -420,6 +733,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",
   });
@@ -480,7 +794,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",
       );
@@ -500,6 +814,7 @@ export async function startDevServer(
     mockAi: options.mockAi,
     db: serverState.adapter,
   });
+  refreshRuntimeModuleNamespace("dev-start");
 
   function loadArtifacts(): {
     devManifest: DevManifest;
@@ -533,12 +848,85 @@ export async function startDevServer(
   }
 
   const initialArtifacts = loadArtifacts();
+  let currentRoutes = devManifest.routes;
+  let currentRuntimeEntryCount = runtimeGraph.entries.length;
+
+  async function reloadGeneratedArtifacts(reason = "manual"): Promise<DevServerReloadResult> {
+    try {
+      refreshRuntimeModuleNamespace(reason);
+      const fresh = loadArtifacts();
+      currentRoutes = 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;
@@ -548,7 +936,7 @@ export async function startDevServer(
       serverState.adapter,
       workspaceRoot,
       initialArtifacts.tableMap,
-      runtimeGraph.entries,
+      initialArtifacts.runtimeGraph.entries,
       { mock: options.mock, intervalMs: 2_000, telemetrySinks, workspaceRoot },
     );
   }
@@ -572,6 +960,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,
@@ -594,6 +983,14 @@ 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),
           );
@@ -615,6 +1012,7 @@ export async function startDevServer(
               ...listed.diagnostics,
               ...queries.diagnostics,
               ...(liveQueries.registry?.diagnostics ?? []),
+              ...external.diagnostics,
             ],
           };
 
@@ -797,6 +1195,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) => {
@@ -808,6 +1213,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,
               );
@@ -816,9 +1226,7 @@ export async function startDevServer(
               }
             },
             () => {
-              if (subscriptionId) {
-                liveManager.unsubscribe(subscriptionId);
-              }
+              cleanupSubscription();
             },
             {
               heartbeatIntervalMs: Number(process.env.FORGE_LIVE_HEARTBEAT_MS ?? "15000"),
@@ -877,6 +1285,283 @@ export async function startDevServer(
           }
         }
 
+        if (request.method === "POST" && pathname === "/ai/agents/run") {
+          const body = (await request.json().catch(() => ({}))) as {
+            agent?: string;
+            provider?: string;
+            model?: string;
+            instructions?: string;
+            prompt?: string;
+            purpose?: string;
+            maxSteps?: number;
+            tools?: string[];
+          };
+          if (!body.prompt) {
+            return jsonResponse(
+              {
+                ok: false,
+                diagnostics: [
+                  createDiagnostic({
+                    severity: "error",
+                    code: FORGE_DEV_INVOKE_FAILED,
+                    message: "POST /ai/agents/run requires a prompt",
+                    fixHint: "Send JSON like {\"prompt\":\"...\",\"instructions\":\"...\",\"tools\":[\"forge_query_listTickets\"]}.",
+                  }),
+                ],
+              },
+              400,
+            );
+          }
+          const auth = await authenticateHeaders(request.headers, authConfig);
+          const envStore = getRuntimeEnvStore(workspaceRoot);
+          const secretRegistry = loadSecretRegistry(workspaceRoot);
+          const bundle = createRuntimeSecretsBundle({
+            store: envStore,
+            registry: secretRegistry,
+            envSchema: null,
+            runtimeKind: "server",
+          });
+          const traceId = generateTraceId();
+          const telemetry = serverState.adapter
+            ? createTelemetryContext({
+                adapter: serverState.adapter,
+                traceId,
+                runtime: { kind: "endpoint", name: "ai.agent.run" },
+                bufferInTransaction: false,
+                workspaceRoot,
+                sinks: telemetrySinks,
+              })
+            : createNoopTelemetryContext(traceId);
+          const ai = createAiContext({
+            secrets: bundle.secrets,
+            telemetry,
+            runtimeKind: "endpoint",
+            mockAi: isMockAiEnabled({ mockAi: options.mockAi }),
+            envelope: { traceId, tenantId: auth.kind === "user" || auth.kind === "system" ? auth.tenantId : undefined },
+            toolContext: {
+              env: envStore.snapshot(),
+              auth,
+            },
+          });
+          try {
+            const namedAgent = await loadNamedAgentDefinition(workspaceRoot, body.agent);
+            const tools = {
+              ...explicitAgentTools(namedAgent),
+              ...buildAutoAgentTools({
+                workspaceRoot,
+                registry: loadAgentToolRegistry(workspaceRoot),
+                selected: body.tools,
+                adapter: serverState.adapter,
+                tableMap,
+                auth,
+                liveManager,
+                json: options.json,
+                mock: options.mock,
+              }),
+            };
+            const result = await ai.runAgent({
+              provider: (body.provider ?? namedAgent?.provider ?? "gateway") as ForgeAiProvider,
+              model: body.model ?? namedAgent?.model ?? "openai/gpt-5.4",
+              instructions:
+                body.instructions ??
+                namedAgent?.instructions ??
+                "You are a ForgeOS app agent. Use available Forge tools when useful.",
+              prompt: body.prompt,
+              purpose: body.purpose ?? "dev_agent_run",
+              stopWhen: namedAgent?.stopWhen,
+              maxSteps: body.maxSteps ?? namedAgent?.maxSteps,
+              tools,
+            });
+            return jsonResponse(
+              {
+                ok: true,
+                result,
+                traceId,
+                tools: Object.keys(tools).sort(),
+              },
+              200,
+              { "x-forge-trace-id": traceId },
+            );
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return jsonResponse(
+              {
+                ok: false,
+                traceId,
+                diagnostics: [
+                  createDiagnostic({
+                    severity: "error",
+                    code: FORGE_DEV_INVOKE_FAILED,
+                    message,
+                    fixHint: `Inspect with forge ai trace ${traceId} --json or GET /telemetry/traces/${traceId}.`,
+                  }),
+                ],
+              },
+              400,
+              { "x-forge-trace-id": traceId },
+            );
+          }
+        }
+
+        if (request.method === "POST" && pathname === "/ai/agents/chat") {
+          const body = (await request.json().catch(() => ({}))) as {
+            agent?: string;
+            provider?: string;
+            model?: string;
+            instructions?: string;
+            purpose?: string;
+            maxSteps?: number;
+            tools?: string[];
+            messages?: unknown[];
+          };
+          if (!Array.isArray(body.messages)) {
+            return jsonResponse(
+              {
+                ok: false,
+                diagnostics: [
+                  createDiagnostic({
+                    severity: "error",
+                    code: FORGE_DEV_INVOKE_FAILED,
+                    message: "POST /ai/agents/chat requires AI SDK UI messages",
+                    fixHint: "Use @ai-sdk/react useChat with DefaultChatTransport({ api: `${forgeUrl}/ai/agents/chat` }).",
+                  }),
+                ],
+              },
+              400,
+            );
+          }
+
+          const purpose = body.purpose ?? "dev_agent_chat";
+          const auth = await authenticateHeaders(request.headers, authConfig);
+          const envStore = getRuntimeEnvStore(workspaceRoot);
+          const secretRegistry = loadSecretRegistry(workspaceRoot);
+          const bundle = createRuntimeSecretsBundle({
+            store: envStore,
+            registry: secretRegistry,
+            envSchema: null,
+            runtimeKind: "server",
+          });
+          const traceId = generateTraceId();
+          const telemetry = serverState.adapter
+            ? createTelemetryContext({
+                adapter: serverState.adapter,
+                traceId,
+                runtime: { kind: "endpoint", name: "ai.agent.chat" },
+                bufferInTransaction: false,
+                workspaceRoot,
+                sinks: telemetrySinks,
+              })
+            : createNoopTelemetryContext(traceId);
+          let provider = (body.provider ?? "gateway") as ForgeAiProvider;
+          let model = body.model ?? "openai/gpt-5.4";
+
+          try {
+            const namedAgent = await loadNamedAgentDefinition(workspaceRoot, body.agent);
+            provider = (body.provider ?? namedAgent?.provider ?? "gateway") as ForgeAiProvider;
+            model = body.model ?? namedAgent?.model ?? "openai/gpt-5.4";
+            await telemetry.capture("forge.ai.agent.started", {
+              traceId,
+              provider,
+              model,
+              purpose,
+              mode: "stream",
+            });
+            const languageModel = await resolveLanguageModel(provider, model, bundle.secrets);
+            const forgeTools = {
+              ...explicitAgentTools(namedAgent),
+              ...buildAutoAgentTools({
+                workspaceRoot,
+                registry: loadAgentToolRegistry(workspaceRoot),
+                selected: body.tools,
+                adapter: serverState.adapter,
+                tableMap,
+                auth,
+                liveManager,
+                json: options.json,
+                mock: options.mock,
+              }),
+            };
+            const tools = await buildAiSdkTools({
+              tools: forgeTools,
+              provider,
+              model,
+              purpose,
+              traceId,
+              secrets: bundle.secrets,
+              telemetry,
+              env: envStore.snapshot(),
+              auth,
+              deltaRecorder,
+            });
+            const { ToolLoopAgent, createAgentUIStreamResponse, hasToolCall, stepCountIs } = await import("ai");
+            const stopWhen =
+              namedAgent?.stopWhen?.kind === "toolCall"
+                ? (hasToolCall(namedAgent.stopWhen.toolName) as never)
+                : namedAgent?.stopWhen?.kind === "stepCount"
+                  ? (stepCountIs(body.maxSteps ?? namedAgent.stopWhen.maxSteps) as never)
+                  : (stepCountIs(body.maxSteps ?? namedAgent?.maxSteps ?? 20) as never);
+            const agent = new ToolLoopAgent({
+              model: languageModel as never,
+              instructions:
+                body.instructions ??
+                namedAgent?.instructions ??
+                "You are a ForgeOS app agent. Use available Forge tools when useful.",
+              tools: tools as never,
+              stopWhen,
+            });
+            const response = await createAgentUIStreamResponse({
+              agent: agent as never,
+              uiMessages: body.messages,
+              onStepFinish: async () => {
+                await telemetry.capture("forge.ai.agent.step.completed", {
+                  traceId,
+                  provider,
+                  model,
+                  purpose,
+                });
+              },
+              headers: {
+                "Access-Control-Allow-Origin": "*",
+                "x-forge-trace-id": traceId,
+              },
+            });
+            await telemetry.capture("forge.ai.agent.completed", {
+              traceId,
+              provider,
+              model,
+              purpose,
+              status: "streaming",
+            });
+            return response;
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            await telemetry.capture("forge.ai.agent.failed", {
+              traceId,
+              provider,
+              model,
+              purpose,
+              status: "failed",
+              error: message,
+            });
+            return jsonResponse(
+              {
+                ok: false,
+                traceId,
+                diagnostics: [
+                  createDiagnostic({
+                    severity: "error",
+                    code: FORGE_DEV_INVOKE_FAILED,
+                    message,
+                    fixHint: `Inspect with forge ai trace ${traceId} --json or GET /telemetry/traces/${traceId}.`,
+                  }),
+                ],
+              },
+              400,
+              { "x-forge-trace-id": traceId },
+            );
+          }
+        }
+
         if (request.method === "GET" && pathname === "/telemetry") {
           if (!serverState.adapter) {
             return jsonResponse({
@@ -978,12 +1663,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),
             });
           }
 
@@ -994,6 +1678,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({
@@ -1151,6 +1844,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;
@@ -1200,6 +1930,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(
               {
@@ -1270,6 +2007,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(
@@ -1355,23 +2099,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 {