open-managed-agents 0.1.0

package/dist/src/control-plane/app.js

@@ -0,0 +1,907 @@
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createAdminAuth, loadAdminKey } from "./admin/auth.js";
+import { log, parseBooleanFlag, setLogEventHook } from "./logging.js";
+import { loadMetricsToken, registerObservabilityRoutes, sha256Token, storageFreeBytes, } from "./observability/routes.js";
+import { createControlPlaneMetrics, modelProviderMetricLabel, registerProcessGauges, } from "./observability/instruments.js";
+import { CONSOLE_MOUNT, registerConsoleRoutes, } from "./console/static.js";
+import { CONSOLE_ADMIN_COOKIE, CONSOLE_WORKSPACE_COOKIE, createConsoleSessionAuth, } from "./console/auth.js";
+import { registerOpenApiRoutes, } from "./openapi/routes.js";
+import { adminRoutes } from "./admin/routes.js";
+import { DefaultAdminService } from "./admin/service.js";
+import { agentsRoutes } from "./agents/routes.js";
+import { DefaultAgentService } from "./agents/service.js";
+import { SqliteAgentStore } from "./agents/store.js";
+import { environmentsRoutes } from "./environments/routes.js";
+import { DefaultEnvironmentService } from "./environments/service.js";
+import { SqliteEnvironmentStore } from "./environments/store.js";
+import { sessionEventsRoutes } from "./events/routes.js";
+import { DefaultSessionEventsService } from "./events/service.js";
+import { SessionEventBroadcaster } from "./events/broadcaster.js";
+import { EventStore } from "./events/store.js";
+import { filesRoutes } from "./files/routes.js";
+import { DefaultFileService } from "./files/service.js";
+import { InMemoryFileStorage } from "./files/store.js";
+import { skillsRoutes } from "./skills/routes.js";
+import { DefaultSkillsService } from "./skills/service.js";
+import { InMemorySkillsStore } from "./skills/store.js";
+import { createBestEffortSessionOutputCoordinator } from "./deployment-session-output-coordinator.js";
+import { createBestEffortRuntimeEventCoordinator } from "./deployment-runtime-event-coordinator.js";
+import { createDeploymentPiSessionRunner, parseDeploymentRuntimeConfigFromEnv, } from "./deployment-runtime-config.js";
+import { createDeploymentStoresFromEnv, } from "./deployment-storage.js";
+import { ApiError, authenticationFailed, ensureApiError, requestTooLarge, requestId, toApiErrorBody, } from "./errors.js";
+import { parseJsonBody } from "./http.js";
+import { DEFAULT_WORKSPACE_ID } from "./workspace.js";
+import { createAdmissionLimits, parseAdmissionLimitsFromEnv, } from "./admission.js";
+import { secretsRoutes } from "./secrets/routes.js";
+import { DefaultSecretsService } from "./secrets/service.js";
+import { sessionsRoutes } from "./sessions/routes.js";
+import { DefaultSessionService } from "./sessions/service.js";
+import { SqliteSessionStore } from "./sessions/store.js";
+import { vaultsRoutes } from "./vaults/routes.js";
+import { DefaultVaultService } from "./vaults/service.js";
+import { SqliteVaultStore } from "./vaults/store.js";
+import { createFileMountResolver, createSkillSnapshotsProvider, createSessionEgressBundleResolver, createStoreBackedAgentRevisionProvider, createStoreBackedCustomToolsProvider, } from "./wiring.js";
+import { createStoreBackedBuiltinToolAccessResolver } from "./sessions/pi/tool-permissions.js";
+import { createStoreBackedMcpCredentialResolver, createStoreBackedMcpServersProvider, createStoreBackedMcpToolAccessResolver, } from "./sessions/pi/mcp/bridge.js";
+import { createDefaultMcpRuntime } from "./sessions/pi/mcp/runtime.js";
+import { PINNED_PI_MODEL_RUNTIME_VERSION, createPiModelCatalog, } from "./models/catalog.js";
+import { modelCatalogRoutes } from "./models/routes.js";
+import { DefaultModelCatalogService, } from "./models/service.js";
+import { parseModelDeploymentConfigFromEnv, } from "./models/deployment-config.js";
+import { createOmaAuthStorageBackend } from "./models/auth-storage-backend.js";
+import { DEFAULT_MCP_OPERATION_TIMEOUT_MS } from "./sessions/pi/mcp/client.js";
+import { createOauthRefreshTicker } from "./vaults/oauth-refresh-ticker.js";
+import { translatePiEvent } from "./sessions/pi/translator.js";
+import { FILES_API_BETA, MANAGED_AGENTS_BETA, SKILLS_API_BETA, } from "./api-constants.js";
+export { FILES_API_BETA, MANAGED_AGENTS_BETA, SKILLS_API_BETA } from "./api-constants.js";
+export const MAX_REQUEST_BODY_BYTES = 1_048_576;
+// 0113 D5: exactly two values; unset stays disabled for the currently allowed
+// rollout tiers but warns loudly; anything else fails construction.
+export function parseDeploymentAuthMode(env, opts = {}) {
+    const raw = env.OMA_AUTH_MODE;
+    if (raw === undefined) {
+        (opts.warn ?? ((message) => log.warn("auth_mode_disabled", { detail: message })))("OMA_AUTH_MODE is unset; workspace authentication is DISABLED and all requests resolve to wrk_default. Set OMA_AUTH_MODE=api-key for any deployment beyond trusted single-node.");
+        return "disabled";
+    }
+    const mode = raw.trim();
+    if (mode === "api-key" || mode === "disabled") {
+        return mode;
+    }
+    throw new Error(`Unsupported OMA_AUTH_MODE: ${JSON.stringify(raw)} (expected "api-key" or "disabled")`);
+}
+export function createControlPlaneApp(services) {
+    if (services.admin && !services.auth) {
+        throw new Error("Admin API requires workspace authentication to be enabled");
+    }
+    const app = new Hono();
+    const defaultBodyLimit = bodyLimit({
+        maxSize: MAX_REQUEST_BODY_BYTES,
+        onError: (c) => {
+            const err = requestTooLarge();
+            return withAdminNoStore(c.req.path, jsonError(toApiErrorBody(err, c.get("requestId")), err.status));
+        },
+    });
+    // Metrics middleware registers FIRST: a first-registered middleware that
+    // awaits next() sees the FINAL response status — including onError-,
+    // notFound-, and bodyLimit-produced responses (verified against Hono's
+    // compose(); the context is mutated in place). Plan 0121 §2.
+    const observedMetrics = services.observability?.metrics;
+    if (observedMetrics !== undefined) {
+        app.use("*", async (c, next) => {
+            const startedAt = performance.now();
+            await next();
+            const route_class = routeClassForPath(c.req.path);
+            observedMetrics.httpRequests.inc({
+                route_class,
+                method: c.req.method,
+                status: String(c.res.status),
+            });
+            observedMetrics.httpDuration.observe((performance.now() - startedAt) / 1000, { route_class });
+        });
+    }
+    app.use("*", async (c, next) => {
+        const reqId = requestId();
+        c.header("request-id", reqId);
+        c.set("requestId", reqId);
+        await next();
+    });
+    // Auth before the beta gate, scoped to known Managed Agents prefixes, per
+    // the 0113 hosted probe: unknown paths 404 without touching auth; known
+    // paths 401 before beta/version are examined.
+    if (services.auth) {
+        const auth = services.auth;
+        app.use("*", async (c, next) => {
+            if (!isManagedAgentsRoute(c.req.path)) {
+                await next();
+                return;
+            }
+            const key = c.req.header("x-api-key");
+            const workspaceCookie = getCookie(c, CONSOLE_WORKSPACE_COOKIE);
+            const usedConsoleCookie = key === undefined && workspaceCookie !== undefined;
+            const workspaceId = key !== undefined
+                ? auth.authenticate(key)
+                : workspaceCookie === undefined
+                    ? undefined
+                    : services.consoleSessionAuth?.service.authenticateWorkspace(workspaceCookie);
+            if (workspaceId === undefined) {
+                const err = authenticationFailed();
+                return jsonError(toApiErrorBody(err, c.get("requestId")), err.status);
+            }
+            if (usedConsoleCookie && isUnsafeMethod(c.req.method) && !sameOriginForCookieWrite(c)) {
+                return c.text("Forbidden\n", 403);
+            }
+            c.set("workspaceId", workspaceId);
+            await next();
+        });
+    }
+    if (services.admin) {
+        const adminAuth = services.admin.auth;
+        app.use("*", async (c, next) => {
+            if (!isAdminRoute(c.req.path)) {
+                await next();
+                return;
+            }
+            c.header("cache-control", "no-store");
+            const key = c.req.header("x-admin-key");
+            const adminCookie = getCookie(c, CONSOLE_ADMIN_COOKIE);
+            const usedConsoleCookie = key === undefined && adminCookie !== undefined;
+            const authenticated = key !== undefined
+                ? adminAuth.verify(key)
+                : adminCookie === undefined
+                    ? false
+                    : services.consoleSessionAuth?.service.authenticateAdmin(adminCookie) === true;
+            if (!authenticated) {
+                const err = authenticationFailed();
+                const response = jsonError(toApiErrorBody(err, c.get("requestId")), err.status);
+                response.headers.set("cache-control", "no-store");
+                return response;
+            }
+            if (usedConsoleCookie && isUnsafeMethod(c.req.method) && !sameOriginForCookieWrite(c)) {
+                return withAdminNoStore(c.req.path, c.text("Forbidden\n", 403));
+            }
+            await next();
+        });
+    }
+    app.use("*", async (c, next) => {
+        const betaFeatures = parseBetaFeatures(c.req.header("anthropic-beta"));
+        if (isManagedAgentsRoute(c.req.path) && !hasRequiredBeta(c.req.path, betaFeatures)) {
+            const err = new ApiError(404, "not_found_error", "not found");
+            return jsonError(toApiErrorBody(err, c.get("requestId")), err.status);
+        }
+        await next();
+    });
+    app.use("*", async (c, next) => {
+        if (c.req.method === "POST" && (c.req.path === "/v1/files" || c.req.path === "/v1/skills" || /^\/v1\/skills\/[^/]+\/versions$/.test(c.req.path))) {
+            await next();
+            return;
+        }
+        return defaultBodyLimit(c, next);
+    });
+    if (services.consoleSessionAuth) {
+        registerConsoleSessionRoutes(app, services);
+    }
+    if (services.openapi) {
+        registerOpenApiRoutes(app, services.openapi);
+    }
+    if (services.models) {
+        app.route("/v1/model-catalog", modelCatalogRoutes(services.models));
+    }
+    app.route("/v1/agents", agentsRoutes(services.agents));
+    app.route("/v1/environments", environmentsRoutes(services.environments, services.environmentNetworking));
+    app.route("/v1/files", filesRoutes(services.files ?? new DefaultFileService(new InMemoryFileStorage()), services.admission));
+    app.route("/v1/skills", skillsRoutes(services.skills ?? new DefaultSkillsService(new InMemorySkillsStore()), services.admission));
+    app.route("/v1/secrets", secretsRoutes(services.secrets ?? new DefaultSecretsService(undefined)));
+    if (services.vaults) {
+        app.route("/v1/vaults", vaultsRoutes(services.vaults, services.mcp));
+    }
+    app.route("/v1/sessions", sessionsRoutes(services.sessions, services.sessionEvents));
+    app.route("/v1/sessions/:sessionId/events", sessionEventsRoutes(services.sessionEvents, services.admission));
+    if (services.admin) {
+        app.route("/admin", adminRoutes(services.admin.service));
+    }
+    if (services.console) {
+        app.get("/", (c) => c.redirect("/console/", 302));
+        registerConsoleRoutes(app, services.console);
+    }
+    if (services.observability) {
+        registerObservabilityRoutes(app, {
+            health: services.observability.health,
+            ...(services.observability.metrics === undefined
+                ? {}
+                : {
+                    metrics: {
+                        registry: services.observability.metrics.registry,
+                        ...(services.observability.metricsTokenSha256 === undefined
+                            ? {}
+                            : { tokenSha256: services.observability.metricsTokenSha256 }),
+                    },
+                }),
+        });
+    }
+    app.notFound((c) => {
+        const err = new ApiError(404, "not_found_error", "Route not found");
+        return withAdminNoStore(c.req.path, jsonError(toApiErrorBody(err, c.get("requestId")), err.status));
+    });
+    app.onError((error, c) => {
+        const err = ensureApiError(error);
+        if (err.status >= 500) {
+            // 0121 C1: 5xx responses were invisible in logs before this line.
+            log.error("request_failed", {
+                requestId: c.get("requestId"),
+                routeClass: routeClassForPath(c.req.path),
+                status: err.status,
+                error,
+            });
+        }
+        return withAdminNoStore(c.req.path, jsonError(toApiErrorBody(err, c.get("requestId")), err.status, err.retryAfterSeconds));
+    });
+    return app;
+}
+function registerConsoleSessionRoutes(app, services) {
+    const consoleAuth = services.consoleSessionAuth;
+    app.get("/console/auth/status", (c) => {
+        c.header("cache-control", "no-store");
+        const workspaceToken = getCookie(c, CONSOLE_WORKSPACE_COOKIE);
+        const adminToken = getCookie(c, CONSOLE_ADMIN_COOKIE);
+        const workspaceId = workspaceToken === undefined
+            ? undefined
+            : consoleAuth.service.authenticateWorkspace(workspaceToken);
+        return c.json({
+            auth_required: services.auth !== undefined,
+            workspace: workspaceId === undefined && services.auth === undefined
+                ? consoleWorkspace(DEFAULT_WORKSPACE_ID, consoleAuth.service)
+                : workspaceId === undefined
+                    ? null
+                    : {
+                        id: workspaceId,
+                        name: consoleAuth.service.workspaceName(workspaceId) ?? workspaceId,
+                    },
+            admin: adminToken !== undefined && consoleAuth.service.authenticateAdmin(adminToken),
+        });
+    });
+    app.post("/console/auth/workspace", async (c) => {
+        if (!sameOriginForCookieWrite(c) || services.auth === undefined)
+            return c.text("Not found\n", 404);
+        const session = consoleAuth.service.createWorkspaceSession(stringField(await parseJsonBody(c.req), "api_key"));
+        if (session === undefined)
+            return consoleAuthenticationFailed(c);
+        setConsoleCookie(c, CONSOLE_WORKSPACE_COOKIE, session.token, consoleAuth.secureCookies, 30 * 24 * 60 * 60);
+        c.header("cache-control", "no-store");
+        return c.json({ workspace: consoleWorkspace(session.workspaceId, consoleAuth.service) });
+    });
+    app.post("/console/auth/admin", async (c) => {
+        if (!sameOriginForCookieWrite(c) || services.admin === undefined)
+            return c.text("Not found\n", 404);
+        const token = consoleAuth.service.createAdminSession(stringField(await parseJsonBody(c.req), "admin_key"));
+        if (token === undefined)
+            return consoleAuthenticationFailed(c);
+        setConsoleCookie(c, CONSOLE_ADMIN_COOKIE, token, consoleAuth.secureCookies, 8 * 60 * 60);
+        c.header("cache-control", "no-store");
+        return c.json({ admin: true });
+    });
+    app.post("/console/auth/select-workspace", async (c) => {
+        if (!sameOriginForCookieWrite(c))
+            return c.text("Forbidden\n", 403);
+        const adminToken = getCookie(c, CONSOLE_ADMIN_COOKIE);
+        if (adminToken === undefined)
+            return consoleAuthenticationFailed(c);
+        const workspaceId = stringField(await parseJsonBody(c.req), "workspace_id");
+        const token = consoleAuth.service.selectWorkspace(adminToken, workspaceId);
+        if (token === undefined)
+            return consoleAuthenticationFailed(c);
+        setConsoleCookie(c, CONSOLE_WORKSPACE_COOKIE, token, consoleAuth.secureCookies, 30 * 24 * 60 * 60);
+        c.header("cache-control", "no-store");
+        return c.json({ workspace: consoleWorkspace(workspaceId, consoleAuth.service) });
+    });
+    app.post("/console/auth/logout", (c) => {
+        if (!sameOriginForCookieWrite(c))
+            return c.text("Forbidden\n", 403);
+        const workspaceToken = getCookie(c, CONSOLE_WORKSPACE_COOKIE);
+        const adminToken = getCookie(c, CONSOLE_ADMIN_COOKIE);
+        if (workspaceToken !== undefined)
+            consoleAuth.service.revokeWorkspaceSession(workspaceToken);
+        if (adminToken !== undefined)
+            consoleAuth.service.revokeAdminSession(adminToken);
+        deleteConsoleCookie(c, CONSOLE_WORKSPACE_COOKIE, consoleAuth.secureCookies);
+        deleteConsoleCookie(c, CONSOLE_ADMIN_COOKIE, consoleAuth.secureCookies);
+        c.header("cache-control", "no-store");
+        return c.body(null, 204);
+    });
+}
+function consoleWorkspace(workspaceId, auth) {
+    return { id: workspaceId, name: auth.workspaceName(workspaceId) ?? workspaceId };
+}
+function stringField(body, name) {
+    if (typeof body !== "object" || body === null ||
+        typeof body[name] !== "string" ||
+        body[name].trim().length === 0) {
+        throw new ApiError(400, "invalid_request_error", `\`${name}\` must be a non-empty string`);
+    }
+    return body[name].trim();
+}
+function consoleAuthenticationFailed(c) {
+    c.header("cache-control", "no-store");
+    const err = authenticationFailed();
+    const response = jsonError(toApiErrorBody(err, c.get("requestId")), err.status);
+    response.headers.set("cache-control", "no-store");
+    return response;
+}
+function setConsoleCookie(c, name, token, secure, maxAge) {
+    setCookie(c, name, token, { httpOnly: true, maxAge, path: "/", sameSite: "Strict", secure });
+}
+function deleteConsoleCookie(c, name, secure) {
+    deleteCookie(c, name, { httpOnly: true, path: "/", sameSite: "Strict", secure });
+}
+function isUnsafeMethod(method) {
+    return method !== "GET" && method !== "HEAD" && method !== "OPTIONS";
+}
+function sameOriginForCookieWrite(c) {
+    const origin = c.req.header("origin");
+    if (origin === undefined)
+        return false;
+    try {
+        return new URL(origin).origin === new URL(c.req.url).origin;
+    }
+    catch {
+        return false;
+    }
+}
+export function createDeploymentControlPlaneApp(env = process.env, opts = {}) {
+    return createDeploymentControlPlane(env, opts, { backgroundWorkers: false }).app;
+}
+// Same wiring as createDeploymentControlPlaneApp, but hands back the stores
+// so a caller that owns the process lifecycle (the appliance entrypoint,
+// tests that boot twice against one OMA_HOME) can close them and release the
+// .oma.lock instead of leaking them until process exit.
+export function createDeploymentControlPlane(env = process.env, opts = {}, internal = {}) {
+    const runtimeConfig = parseDeploymentRuntimeConfigFromEnv(env);
+    const modelConfig = parseModelDeploymentConfigFromEnv(env);
+    const authMode = parseDeploymentAuthMode(env);
+    const adminKey = loadAdminKey(env);
+    // Parsed before any store opens so a malformed flag can't leak a store.
+    const tlsTerminated = parseBooleanFlag(env.OMA_TLS_TERMINATED, "OMA_TLS_TERMINATED");
+    const allowInsecureTransport = parseBooleanFlag(env.OMA_ALLOW_INSECURE_TRANSPORT, "OMA_ALLOW_INSECURE_TRANSPORT");
+    // 0121 §3.2 exposure matrix, resolved HERE from the configured bind host —
+    // the same source of truth as the transport gate below — and passed down
+    // as data. Never inferred per-request from headers or socket info. The
+    // `?? "1"` is load-bearing: a bare parse would default the flag OFF.
+    const metricsEnabled = parseBooleanFlag(env.OMA_METRICS ?? "1", "OMA_METRICS");
+    // Token is loaded only when the kill switch is on: OMA_METRICS=0 must be
+    // able to recover a deployment whose metrics-secret config is broken
+    // (missing token file, both variants set) — C2 review, Codex P2.
+    const metricsToken = metricsEnabled ? loadMetricsToken(env) : undefined;
+    const metricsServed = metricsEnabled && (metricsToken !== undefined || isLoopbackHost(env.OMA_HOST));
+    const metrics = metricsServed ? createControlPlaneMetrics() : undefined;
+    const admission = createAdmissionLimits(parseAdmissionLimitsFromEnv(env), metrics === undefined
+        ? undefined
+        : (limit, status) => metrics.admissionRejections.inc({ limit, status }));
+    const stores = createDeploymentStoresFromEnv(env);
+    if (authMode === "api-key" && stores.mode !== "durable") {
+        stores.close();
+        throw new Error("OMA_AUTH_MODE=api-key requires durable deployment storage: set OMA_SQLITE_PATH and OMA_FILE_STORAGE_ROOT. " +
+            "In-memory stores are per-process, so no API key could ever be provisioned and every request would fail with 401.");
+    }
+    // A configured master key means this deployment handles real credentials
+    // (secret values + credentialed egress). Without api-key auth every route —
+    // including POST/DELETE /v1/secrets — resolves to wrk_default unauthenticated,
+    // so anyone who can reach the port could overwrite the credentials the egress
+    // proxy injects. Refuse to boot that combination rather than warn (mirrors
+    // the api-key-requires-durable guard above); an operator who genuinely wants
+    // keyless secrets must not get there by forgetting OMA_AUTH_MODE.
+    if (stores.secrets !== undefined && authMode !== "api-key") {
+        stores.close();
+        throw new Error("A secrets master key (OMA_MASTER_KEY/OMA_MASTER_KEY_FILE) requires OMA_AUTH_MODE=api-key: " +
+            "without it the /v1/secrets API is unauthenticated and resolves to wrk_default, so anyone " +
+            "reaching the server could read metadata and overwrite the credentials used for egress injection.");
+    }
+    if (adminKey !== undefined && stores.mode !== "durable") {
+        stores.close();
+        throw new Error("OMA_ADMIN_KEY/OMA_ADMIN_KEY_FILE requires durable deployment storage: set OMA_SQLITE_PATH and OMA_FILE_STORAGE_ROOT. " +
+            "In-memory admin management would not survive restart.");
+    }
+    if (adminKey !== undefined && authMode !== "api-key") {
+        stores.close();
+        throw new Error("OMA_ADMIN_KEY/OMA_ADMIN_KEY_FILE requires OMA_AUTH_MODE=api-key: " +
+            "the admin API mints workspace keys for /v1 routes, so workspace authentication must be enabled.");
+    }
+    // 0120 §3.2 (extended after implementation review): every credentialed
+    // request — the admin key and each workspace x-api-key — travels in the
+    // clear over a plaintext non-loopback bind. Refuse that combination at
+    // boot unless the operator asserts a TLS front (OMA_TLS_TERMINATED=1 — an
+    // explicit assertion; X-Forwarded-Proto from the request is
+    // attacker-suppliable and deliberately not trusted) or consciously opts
+    // into plaintext (OMA_ALLOW_INSECURE_TRANSPORT=1, e.g. a Docker bind
+    // published only on the host's loopback). Auth-disabled deployments carry
+    // no credentials, so they are not gated.
+    if (authMode === "api-key" &&
+        !isLoopbackHost(env.OMA_HOST) &&
+        !tlsTerminated &&
+        !allowInsecureTransport) {
+        stores.close();
+        throw new Error(`API-key authentication on a non-loopback bind (OMA_HOST=${JSON.stringify(env.OMA_HOST)}) without TLS would send ` +
+            "every API key — and the admin key, if set — in cleartext. Either front the appliance with TLS and set " +
+            "OMA_TLS_TERMINATED=1, bind to loopback (unset OMA_HOST), or set OMA_ALLOW_INSECURE_TRANSPORT=1 if the " +
+            "plaintext exposure is intentional (e.g. a container port published only on the host's loopback).");
+    }
+    const broadcaster = new SessionEventBroadcaster(stores.events);
+    let wakeOauthTicker = () => undefined;
+    const vaultService = new DefaultVaultService(stores.vaults, {
+        onSchedulingChanged: () => wakeOauthTicker(),
+        ...(opts.testMcp?.allowInsecureTokenEndpoint === undefined
+            ? {}
+            : {
+                allowInsecureTokenEndpoint: opts.testMcp.allowInsecureTokenEndpoint,
+            }),
+    });
+    const sandboxProviderName = runtimeConfig.sandboxProviderSelection?.type ?? "none";
+    if (metrics !== undefined) {
+        // Turn outcomes/durations at the single post-commit chokepoint (plan
+        // 0121 §2): the store observer fires after the outermost events-store
+        // transaction releases, covering every apply path. archived/deleted are
+        // session lifecycle, not turn outcomes — their map entries are dropped
+        // without observation, so the map cannot grow unbounded.
+        const turnAcceptedAtMs = new Map();
+        stores.events.setRuntimeChangesObserver((changes) => {
+            for (const turn of changes.acceptedTurns ?? []) {
+                turnAcceptedAtMs.set(turn.turnId, performance.now());
+            }
+            for (const closure of changes.closedTurns ?? []) {
+                const acceptedAt = turnAcceptedAtMs.get(closure.turnId);
+                turnAcceptedAtMs.delete(closure.turnId);
+                const outcome = TURN_OUTCOME_BY_REASON[closure.reason];
+                if (outcome === undefined)
+                    continue;
+                metrics.turnsTotal.inc({ outcome });
+                if (outcome === "completed" && acceptedAt !== undefined) {
+                    metrics.turnDuration.observe((performance.now() - acceptedAt) / 1000);
+                }
+            }
+        });
+        registerProcessGauges(metrics.registry);
+        metrics.registry.gauge("oma_sessions_active", "Unarchived sessions (scrape-time count; served by idx_sessions_live).", () => stores.sessions.countAllActive());
+        metrics.registry.gauge("oma_runtime_turns_pending", "Pending runtime turns awaiting completion (scrape-time count).", () => stores.events.countAllPendingRuntimeTurns());
+        metrics.registry.gauge("oma_sse_streams_active", "Open SSE event streams.", () => admission.sseStreams.totalInFlight);
+        setLogEventHook((level) => metrics.logEvents.inc({ level }));
+    }
+    const mcpRuntime = runtimeConfig.mcp !== undefined || opts.runner?.mcp === undefined
+        ? createDefaultMcpRuntime(stores.vaults, opts.testMcp?.fetch, {
+            onScheduled: () => wakeOauthTicker(),
+        })
+        : undefined;
+    let modelCatalog;
+    try {
+        modelCatalog = opts.runner?.modelCatalog ?? createPiModelCatalog({
+            allowedProviders: modelConfig.allowedProviders,
+            defaultModel: modelConfig.defaultModel,
+            authBackend: createOmaAuthStorageBackend(modelConfig.authPath),
+            authPath: modelConfig.authPath,
+            modelsPath: modelConfig.modelsPath,
+            allowModelAuthCommands: modelConfig.allowModelAuthCommands,
+        });
+    }
+    catch (error) {
+        stores.close();
+        throw error;
+    }
+    const registeredModels = modelCatalog.list();
+    const readyModelCount = registeredModels.filter((model) => modelCatalog.hasConfiguredAuth(model)).length;
+    log.info("model_catalog_loaded", {
+        piVersion: PINNED_PI_MODEL_RUNTIME_VERSION,
+        providers: [...modelCatalog.allowedProviders],
+        defaultProvider: modelCatalog.defaultModel.provider,
+        defaultModel: modelCatalog.defaultModel.id,
+        registeredModelCount: registeredModels.length,
+        readyModelCount,
+        missingCredentialModelCount: registeredModels.length - readyModelCount,
+    });
+    for (const detail of modelCatalog.securityReport.warnings) {
+        log.warn("model_config_warning", { detail });
+    }
+    const modelAvailability = {
+        resolve(model) {
+            if (!modelCatalog.allowedProviders.has(model.provider)) {
+                metrics?.modelAdmissionFailures.inc({
+                    reason: "provider_disabled",
+                    provider: modelProviderMetricLabel(model.provider),
+                });
+                throw new ApiError(400, "invalid_request_error", `Model provider ${model.provider} is not enabled on this deployment`);
+            }
+            const resolved = modelCatalog.resolve(model);
+            if (!resolved) {
+                metrics?.modelAdmissionFailures.inc({
+                    reason: "model_unavailable",
+                    provider: modelProviderMetricLabel(model.provider),
+                });
+                throw new ApiError(400, "invalid_request_error", `Model ${model.provider}/${model.id} is not available on this deployment`);
+            }
+            return resolved;
+        },
+        assertAvailable(model) {
+            this.resolve(model);
+        },
+        assertReady(model) {
+            const resolved = this.resolve(model);
+            if (!modelCatalog.hasConfiguredAuth(resolved)) {
+                metrics?.modelAdmissionFailures.inc({
+                    reason: "credentials_missing",
+                    provider: modelProviderMetricLabel(model.provider),
+                });
+                throw new ApiError(400, "invalid_request_error", `Credentials for model provider ${model.provider} are not configured on this deployment`);
+            }
+        },
+    };
+    const runner = createDeploymentPiSessionRunner(runtimeConfig, {
+        ...opts.runner,
+        modelCatalog,
+        agentRevision: createStoreBackedAgentRevisionProvider({
+            sessions: stores.sessions,
+            agents: stores.agents,
+        }),
+        ...(metrics === undefined
+            ? {}
+            : {
+                onSandboxEvent: (event) => {
+                    if (event === "error") {
+                        metrics.sandboxProviderErrors.inc({ provider: sandboxProviderName });
+                    }
+                    else {
+                        metrics.sandboxes.inc({ event, provider: sandboxProviderName });
+                    }
+                },
+                onSandboxesReaped: (count) => metrics.sandboxes.inc({ event: "reaped", provider: sandboxProviderName }, count),
+            }),
+        resolveEgressBundle: opts.runner?.resolveEgressBundle ??
+            createSessionEgressBundleResolver({
+                sessions: stores.sessions,
+                environments: stores.environments,
+                ...(stores.secrets === undefined ? {} : { secrets: stores.secrets }),
+            }),
+        fileMountResolver: createFileMountResolver(stores.sessions, stores.files),
+        skills: createSkillSnapshotsProvider(stores.sessions),
+        customTools: opts.runner?.customTools ??
+            createStoreBackedCustomToolsProvider({
+                sessions: stores.sessions,
+                agents: stores.agents,
+            }),
+        builtinToolAccess: createStoreBackedBuiltinToolAccessResolver({
+            sessions: stores.sessions,
+            agents: stores.agents,
+        }),
+        // Plan 0122 §4.6: always wired (disabled agents still get their
+        // exhausted session.error), dialing gated by OMA_ENABLE_MCP.
+        mcp: opts.runner?.mcp ?? {
+            enabled: runtimeConfig.mcp !== undefined,
+            fetch: mcpRuntime.fetch,
+            servers: createStoreBackedMcpServersProvider({
+                sessions: stores.sessions,
+                agents: stores.agents,
+            }),
+            credentials: createStoreBackedMcpCredentialResolver({
+                sessions: stores.sessions,
+                vaults: vaultService,
+                refresh: mcpRuntime.refreshCoordinator,
+            }),
+            access: createStoreBackedMcpToolAccessResolver({
+                sessions: stores.sessions,
+                agents: stores.agents,
+            }),
+            ...(runtimeConfig.mcp?.operationTimeoutMs === undefined
+                ? {}
+                : { operationTimeoutMs: runtimeConfig.mcp.operationTimeoutMs }),
+            ...(metrics === undefined
+                ? {}
+                : {
+                    onToolCall: (outcome) => metrics.mcpToolCalls.inc({ outcome }),
+                    onConnection: (event) => metrics.mcpConnections.inc({ event }),
+                }),
+        },
+    });
+    const runtime = { runner, translate: translatePiEvent };
+    const sessionEvents = new DefaultSessionEventsService(stores.events, stores.sessions, broadcaster, {
+        ...runtime,
+        sessionOutputCoordinator: stores.sessionOutputCoordinator,
+        runtimeEventCoordinator: stores.runtimeEventCoordinator,
+    }, {
+        ...(admission.maxPendingRuntimeTurnsPerWorkspace === undefined
+            ? {}
+            : {
+                maxPendingRuntimeTurnsPerWorkspace: admission.maxPendingRuntimeTurnsPerWorkspace,
+            }),
+        ...(metrics === undefined
+            ? {}
+            : {
+                onAdmissionRejected: () => metrics.admissionRejections.inc({ limit: "turns", status: "429" }),
+            }),
+    });
+    sessionEvents.recoverAllAbandonedRuntimeTurns();
+    const consoleRoot = bundledConsoleRoot();
+    const openapiRoot = bundledOpenApiDocsRoot();
+    const adminAuth = adminKey === undefined ? undefined : createAdminAuth(adminKey);
+    const consoleSessionAuth = createConsoleSessionAuth({
+        workspaces: stores.workspaces,
+        ...(adminAuth === undefined ? {} : { admin: adminAuth }),
+    });
+    const app = createControlPlaneApp({
+        ...(adminKey === undefined
+            ? {}
+            : {
+                admin: {
+                    service: new DefaultAdminService(stores.workspaces, stores.vaults),
+                    auth: adminAuth,
+                },
+            }),
+        // Secret-free static content, so it serves whenever the dir shipped —
+        // deliberately not coupled to admin being enabled (0120 §3.1): a
+        // read-only /v1 browser is useful without an admin key.
+        ...(consoleRoot === undefined ? {} : { console: { root: consoleRoot } }),
+        consoleSessionAuth: {
+            service: consoleSessionAuth,
+            secureCookies: tlsTerminated,
+        },
+        ...(openapiRoot === undefined ? {} : { openapi: { root: openapiRoot } }),
+        ...(authMode === "api-key"
+            ? {
+                auth: {
+                    authenticate: (key) => stores.workspaces.authenticate(key),
+                },
+            }
+            : {}),
+        agents: new DefaultAgentService(stores.agents, stores.skills, modelAvailability),
+        environments: new DefaultEnvironmentService(stores.environments, stores.sessions),
+        environmentNetworking: environmentNetworkingCapability(runtimeConfig),
+        files: new DefaultFileService(stores.files),
+        skills: new DefaultSkillsService(stores.skills),
+        secrets: new DefaultSecretsService(stores.secrets),
+        vaults: vaultService,
+        ...(runtimeConfig.mcp === undefined
+            ? {}
+            : {
+                mcp: {
+                    fetch: mcpRuntime.fetch,
+                    refresh: mcpRuntime.refreshCoordinator,
+                    operationTimeoutMs: runtimeConfig.mcp.operationTimeoutMs ??
+                        DEFAULT_MCP_OPERATION_TIMEOUT_MS,
+                },
+            }),
+        sessions: new DefaultSessionService(stores.sessions, stores.agents, stores.environments, stores.files, {
+            assertDeletable: sessionEvents.assertSessionDeletable.bind(sessionEvents),
+            runtime: runner,
+            modelAvailability,
+            skills: stores.skills,
+            egressCapability: {
+                canHonorNetworking: runtimeConfig.egress !== undefined,
+                hasSecretsStore: stores.secrets !== undefined,
+            },
+            vaults: vaultService,
+            deleteSessionRows: stores.sessionCoordinator.deleteSessionRows,
+            idempotencyLedger: stores.events,
+            createSessionRowsWithIdempotency: stores.sessions.createAndCompleteIdempotency.bind(stores.sessions),
+            ...(admission.maxActiveSessionsPerWorkspace === undefined
+                ? {}
+                : {
+                    maxActiveSessionsPerWorkspace: admission.maxActiveSessionsPerWorkspace,
+                }),
+            ...(metrics === undefined
+                ? {}
+                : {
+                    onAdmissionRejected: () => metrics.admissionRejections.inc({
+                        limit: "sessions",
+                        status: "429",
+                    }),
+                }),
+        }),
+        sessionEvents,
+        models: new DefaultModelCatalogService(modelCatalog),
+        admission,
+        observability: {
+            health: {
+                storage: stores.mode === "durable"
+                    ? () => {
+                        stores.sessions.countAllActive();
+                        // A configured object root that cannot be statfs'd (deleted,
+                        // unmounted, permission-broken) is a FAILED check, not a
+                        // silently-omitted field — C2 review, Codex-adv MEDIUM.
+                        const free = env.OMA_FILE_STORAGE_ROOT === undefined
+                            ? undefined
+                            : storageFreeBytes(env.OMA_FILE_STORAGE_ROOT);
+                        if (env.OMA_FILE_STORAGE_ROOT !== undefined && free === undefined) {
+                            return { status: "failed" };
+                        }
+                        return {
+                            status: "ok",
+                            ...(free === undefined ? {} : { free_bytes: free }),
+                        };
+                    }
+                    : // In-memory reports its mode rather than lying about durability.
+                        () => ({ status: "ok", mode: "in-memory" }),
+                runtime: () => {
+                    stores.events.countAllPendingRuntimeTurns();
+                    return { status: "ok" };
+                },
+            },
+            ...(metrics === undefined ? {} : { metrics }),
+            ...(metricsToken === undefined
+                ? {}
+                : { metricsTokenSha256: sha256Token(metricsToken) }),
+        },
+    });
+    const oauthTicker = runtimeConfig.mcp !== undefined && internal.backgroundWorkers !== false
+        ? createOauthRefreshTicker({
+            store: stores.vaults,
+            refresh: mcpRuntime.refreshCoordinator,
+            onError: (error) => log.error("oauth_refresh_ticker_error", { error }),
+        })
+        : undefined;
+    wakeOauthTicker = () => oauthTicker?.wake();
+    let closePromise;
+    return {
+        app,
+        stores,
+        authMode,
+        close() {
+            closePromise ??= (async () => {
+                await oauthTicker?.close();
+                stores.close();
+            })();
+            return closePromise;
+        },
+    };
+}
+// undefined = the appliance's 127.0.0.1 default. Everything not provably
+// loopback (0.0.0.0, ::, LAN addresses, hostnames) counts as non-loopback —
+// the safe direction for a check that gates a root credential.
+export function isLoopbackHost(host) {
+    if (host === undefined)
+        return true;
+    const h = host.trim().toLowerCase();
+    if (h === "localhost" || h === "::1" || h === "[::1]")
+        return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+}
+// App-root-relative so the same derivation works from a checkout
+// (<repo>/ui/…) and inside the Docker image (/app/ui/…, COPY ui ./ui).
+function bundledConsoleRoot() {
+    const root = fileURLToPath(new URL("../../ui/managed-agents-console", import.meta.url));
+    return existsSync(join(root, "index.html")) ? root : undefined;
+}
+function bundledOpenApiDocsRoot() {
+    const root = fileURLToPath(new URL("../../ui/openapi-docs", import.meta.url));
+    return existsSync(join(root, "index.html")) ? root : undefined;
+}
+export function createInMemoryControlPlaneApp(opts = {}) {
+    const agentStore = SqliteAgentStore.open(":memory:");
+    const environmentStore = SqliteEnvironmentStore.open(":memory:");
+    const sessionStore = SqliteSessionStore.open(":memory:");
+    const vaultStore = SqliteVaultStore.open(":memory:");
+    const eventStore = EventStore.open(":memory:");
+    const fileStorage = new InMemoryFileStorage();
+    const skillsStore = new InMemorySkillsStore();
+    const sessionOutputCoordinator = createBestEffortSessionOutputCoordinator({
+        sessions: sessionStore,
+        events: eventStore,
+        files: fileStorage,
+    });
+    const runtimeEventCoordinator = createBestEffortRuntimeEventCoordinator({
+        sessions: sessionStore,
+        events: eventStore,
+    });
+    const broadcaster = new SessionEventBroadcaster(eventStore);
+    const vaultService = new DefaultVaultService(vaultStore);
+    const sessionEvents = new DefaultSessionEventsService(eventStore, sessionStore, broadcaster, opts.runtime
+        ? { ...opts.runtime, sessionOutputCoordinator, runtimeEventCoordinator }
+        : undefined);
+    const openapiRoot = bundledOpenApiDocsRoot();
+    return createControlPlaneApp({
+        ...(openapiRoot === undefined ? {} : { openapi: { root: openapiRoot } }),
+        agents: new DefaultAgentService(agentStore, skillsStore),
+        environments: new DefaultEnvironmentService(environmentStore, sessionStore),
+        ...(opts.environmentNetworking === undefined
+            ? {}
+            : { environmentNetworking: opts.environmentNetworking }),
+        files: new DefaultFileService(fileStorage),
+        skills: new DefaultSkillsService(skillsStore),
+        vaults: vaultService,
+        sessions: new DefaultSessionService(sessionStore, agentStore, environmentStore, fileStorage, {
+            assertDeletable: sessionEvents.assertSessionDeletable.bind(sessionEvents),
+            ...(opts.runtime?.runner ? { runtime: opts.runtime.runner } : {}),
+            skills: skillsStore,
+            vaults: vaultService,
+            idempotencyLedger: eventStore,
+            createSessionRowsWithIdempotency: sessionStore.createAndCompleteIdempotency.bind(sessionStore),
+        }),
+        sessionEvents,
+    });
+}
+export function parseBetaFeatures(header) {
+    return new Set((header ?? "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0));
+}
+function environmentNetworkingCapability(runtimeConfig) {
+    const provider = runtimeConfig.sandboxProviderSelection?.type ?? null;
+    if (runtimeConfig.egress !== undefined) {
+        return { provider, egress_supported: true, reason: null };
+    }
+    const reason = provider === "docker-local"
+        ? "Docker-local is configured without the OMA egress sidecar. Restart through `oma up` to use networked presets."
+        : provider === null || provider === "none"
+            ? "No sandbox provider with egress support is configured."
+            : `Environment allowlists are not supported by ${provider}.`;
+    return { provider, egress_supported: false, reason };
+}
+function isManagedAgentsRoute(path) {
+    // Keep this in sync with the Managed Agents route registrations above.
+    return [
+        "/v1/agents",
+        "/v1/environments",
+        "/v1/files",
+        "/v1/skills",
+        // Secrets MUST be auth-gated: leaving it off this list would skip the
+        // auth middleware and fall back to wrk_default (plan 0117e-2).
+        "/v1/secrets",
+        // Vault credentials also carry secret metadata and must not silently bind
+        // to wrk_default if someone forgets the auth prefix registration.
+        "/v1/vaults",
+        "/v1/sessions",
+        "/v1/model-catalog",
+    ].some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+}
+function isAdminRoute(path) {
+    return path === "/admin" || path.startsWith("/admin/");
+}
+// Turn close reasons → metric outcomes (plan 0121 §3.2): archived/deleted
+// are session lifecycle, not turn outcomes, and are deliberately unmapped.
+const TURN_OUTCOME_BY_REASON = {
+    completed: "completed",
+    interrupted: "interrupted",
+    terminalized: "abandoned",
+};
+export function routeClassForPath(path) {
+    if (isManagedAgentsRoute(path))
+        return "v1";
+    if (isAdminRoute(path))
+        return "admin";
+    if (path === CONSOLE_MOUNT || path.startsWith(`${CONSOLE_MOUNT}/`))
+        return "console";
+    if (path === "/health")
+        return "health";
+    if (path === "/metrics")
+        return "metrics";
+    return "other";
+}
+function withAdminNoStore(path, response) {
+    if (isAdminRoute(path)) {
+        response.headers.set("cache-control", "no-store");
+    }
+    return response;
+}
+function hasRequiredBeta(path, betaFeatures) {
+    if (betaFeatures.has(MANAGED_AGENTS_BETA)) {
+        return true;
+    }
+    if (path === "/v1/files" || path.startsWith("/v1/files/")) {
+        return betaFeatures.has(FILES_API_BETA);
+    }
+    if (path === "/v1/skills" || path.startsWith("/v1/skills/")) {
+        return betaFeatures.has(SKILLS_API_BETA);
+    }
+    return false;
+}
+function jsonError(body, status, retryAfterSeconds) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            "content-type": "application/json; charset=UTF-8",
+            "request-id": body.request_id,
+            ...(retryAfterSeconds === undefined
+                ? {}
+                : { "retry-after": String(retryAfterSeconds) }),
+        },
+    });
+}