nexus-agentd 0.2.6 → 0.3.1

package/dist/server.js

@@ -1,18 +1,73 @@
-import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import http from 'node:http';
 import { AdminSessionStore } from './auth.js';
+import { streamSessionEvents } from './server/connection.js';
+import { DiagnosticConcurrencyError, DiagnosticRunner } from './server/diagnostics.js';
+import { ADMIN_COOKIE, adminCookie, assertAgentScope, assertConsoleHost, assertTrustedOrigin, authenticateAdmin, authenticateApiKey, clearAdminCookie, cookieValue, isInitialized, isMutating, needsAdminSetup, remoteKey, stringHeader } from './server/auth-policy.js';
+import { GatewayMetrics } from './server/metrics.js';
+import { QuotaExceededError, QuotaManager } from './server/quota.js';
+import { RequestError, assertEmptyJsonBody, assertJsonContentType, assertOnlyKeys, boundedLimit, cleanQuery, decodeHeader, normalizePublishPaths, normalizedMediaType, optionalAttachmentIds, optionalBoolean, optionalNumber, optionalPendingAction, optionalRawString, optionalRunState, optionalString, readBytesBody, readJsonBody, requiredInteger, requiredMessage, requiredRawString, requiredString, requiredStringArray } from './server/validation.js';
 import { ControlPlaneError } from './control-plane.js';
 import { RunNotFoundError, SessionNotFoundError, SessionRequestError } from './session.js';
 import { redirectToAgentdWebUi, writeAgentdWebUi, writeAgentdWebUiModule } from './webui/index.js';
-const ADMIN_COOKIE = 'agent_nexus_admin';
+export { QuotaExceededError, QuotaManager, quotaLimitsFromConfig } from './server/quota.js';
+export { DiagnosticRunner, DiagnosticConcurrencyError } from './server/diagnostics.js';
+export { GatewayMetrics } from './server/metrics.js';
 export function createAgentdServer(config, sessions, controlPlane) {
     const adminSessions = new AdminSessionStore(config.adminSessionTtlMs || 12 * 60 * 60 * 1000);
     const loginLimiter = new FailureRateLimiter(8, 60_000, 5 * 60_000);
     const apiLimiter = new FailureRateLimiter(30, 60_000, 60_000);
+    const setupLimiter = new FailureRateLimiter(8, 60_000, 60_000);
+    const revealLimiter = new FailureRateLimiter(20, 60_000, 60_000);
+    const quota = new QuotaManager(config);
+    const metrics = new GatewayMetrics();
+    const diagnostics = new DiagnosticRunner(2);
     let sseConnections = 0;
+    const sessionReservations = new Map();
+    const uploadReservations = new Map();
+    const runReservations = new Map();
+    // SessionManager emits terminal run transitions independently of HTTP
+    // requests. Release the per-key running slot at that boundary so an
+    // asynchronous completion cannot strand a quota reservation until the
+    // next poll.
+    const releaseRunReservationById = (sessionId) => {
+        const release = runReservations.get(sessionId);
+        if (release)
+            release();
+        else
+            quota.finishRun(sessionId);
+    };
+    const releaseSessionReservationsById = (sessionId) => {
+        const releaseSession = sessionReservations.get(sessionId);
+        if (releaseSession) {
+            sessionReservations.delete(sessionId);
+            releaseSession();
+        }
+        const releaseUpload = uploadReservations.get(sessionId);
+        if (releaseUpload) {
+            uploadReservations.delete(sessionId);
+            releaseUpload();
+        }
+        releaseRunReservationById(sessionId);
+    };
+    const subscribeLifecycle = sessions.subscribeLifecycle;
+    const unsubscribeLifecycle = typeof subscribeLifecycle === 'function'
+        ? subscribeLifecycle.call(sessions, (event) => {
+            if (event.type === 'run_updated' && event.state && isTerminalState(event.state)) {
+                releaseRunReservationById(event.sessionId);
+            }
+            if (event.type === 'session_closed') {
+                releaseSessionReservationsById(event.sessionId);
+            }
+        })
+        : undefined;
     const server = http.createServer((request, response) => {
         const requestId = randomUUID();
+        metrics.requestStarted();
         response.setHeader('X-Request-Id', requestId);
+        response.once('finish', () => {
+            metrics.responseFinished(response.statusCode, response.statusCode === 429);
+        });
         void handleRequest({
             config,
             sessions,
@@ -20,23 +75,39 @@ export function createAgentdServer(config, sessions, controlPlane) {
             adminSessions,
             loginLimiter,
             apiLimiter,
+            setupLimiter,
+            revealLimiter,
+            quota,
+            metrics,
+            diagnostics,
+            sessionReservations,
+            uploadReservations,
+            runReservations,
+            currentSse: () => sseConnections,
             request,
             response,
-            acquireSse() {
-                if (sseConnections >= (config.maxSseConnections || 128))
-                    return false;
+            acquireSse(keyId) {
+                if (sseConnections >= (config.maxSseConnections || 128)) {
+                    throw new QuotaExceededError('sse', config.maxSseConnections || 128, sseConnections, 1_000);
+                }
+                const releaseQuota = quota.reserveSse(keyId);
                 sseConnections += 1;
-                return true;
+                return () => {
+                    releaseQuota();
+                    sseConnections = Math.max(0, sseConnections - 1);
+                };
             },
-            releaseSse() {
-                sseConnections = Math.max(0, sseConnections - 1);
-            }
         }).catch((error) => {
             if (response.headersSent) {
                 response.destroy(error instanceof Error ? error : undefined);
                 return;
             }
             const status = errorStatus(error);
+            if (error instanceof QuotaExceededError || error instanceof DiagnosticConcurrencyError) {
+                const retryAfterMs = error.retryAfterMs;
+                response.setHeader('Retry-After', String(Math.max(1, Math.ceil(retryAfterMs / 1000))));
+                response.setHeader('X-Quota-Type', error instanceof QuotaExceededError ? error.quota : 'diagnostics');
+            }
             if (status >= 500) {
                 console.error(JSON.stringify({
                     level: 'error',
@@ -48,22 +119,32 @@ export function createAgentdServer(config, sessions, controlPlane) {
                     stack: error instanceof Error ? error.stack : undefined
                 }));
             }
-            writeJson(response, status, {
-                error: status >= 500 ? 'Internal server error' : errorMessage(error),
-                requestId
-            });
+            writeError(response, status, error, requestId);
         });
     });
     server.requestTimeout = config.requestTimeoutMs || 30_000;
     server.headersTimeout = Math.min(server.requestTimeout, 20_000);
     server.keepAliveTimeout = 5_000;
     server.maxConnections = config.maxConnections || 256;
-    server.once('close', () => adminSessions.clear());
+    server.once('close', () => {
+        unsubscribeLifecycle?.();
+        for (const sessionId of new Set([
+            ...sessionReservations.keys(),
+            ...uploadReservations.keys(),
+            ...runReservations.keys()
+        ])) {
+            releaseSessionReservationsById(sessionId);
+        }
+        adminSessions.clear();
+    });
     return server;
 }
 async function handleRequest(context) {
     const { config, sessions, controlPlane, adminSessions, loginLimiter, apiLimiter, request, response } = context;
     const url = new URL(request.url || '/', 'http://localhost');
+    if (url.pathname === '/' || url.pathname.startsWith('/ui') || url.pathname.startsWith('/v1/admin/') || url.pathname.startsWith('/v1/bootstrap/')) {
+        assertConsoleHost(request, config);
+    }
     if (url.pathname === '/' && request.method === 'GET') {
         redirectToAgentdWebUi(response);
         return;
@@ -95,9 +176,17 @@ async function handleRequest(context) {
         if (!controlPlane)
             throw new RequestError(404, 'Control plane is unavailable');
         assertJsonContentType(request);
-        assertTrustedOrigin(request, true);
+        assertTrustedOrigin(request, config);
+        if (!needsAdminSetup(config, controlPlane))
+            throw new RequestError(409, 'Console setup is already complete');
+        const rateKey = remoteKey(request);
+        context.setupLimiter.assertAllowed(rateKey);
         const body = await readJsonBody(request, config.maxRequestBytes);
-        assertOnlyKeys(body, ['password', 'confirmPassword']);
+        assertOnlyKeys(body, ['password', 'confirmPassword', 'setupToken']);
+        if (!controlPlane.verifySetupToken(optionalRawString(body.setupToken, 'setupToken') || '')) {
+            context.setupLimiter.failure(rateKey);
+            throw new RequestError(403, 'Invalid setup token');
+        }
         writeJson(response, 201, await controlPlane.initializeAdminPassword(requiredRawString(body.password, 'password'), requiredRawString(body.confirmPassword, 'confirmPassword')));
         return;
     }
@@ -116,14 +205,16 @@ async function handleRequest(context) {
             throw new RequestError(428, 'Console setup is required');
         }
         assertJsonContentType(request);
-        assertTrustedOrigin(request, true);
+        assertTrustedOrigin(request, config);
         const rateKey = remoteKey(request);
         loginLimiter.assertAllowed(rateKey);
         const body = await readJsonBody(request, config.maxRequestBytes);
         assertOnlyKeys(body, ['password']);
         const password = requiredRawString(body.password, 'password');
+        // Reserve the attempt before asynchronous scrypt, including concurrent requests.
+        loginLimiter.assertAllowed(rateKey);
+        loginLimiter.failure(rateKey);
         if (!(await controlPlane.verifyAdminPassword(password))) {
-            loginLimiter.failure(rateKey);
             throw new RequestError(401, 'Invalid Console Password');
         }
         loginLimiter.success(rateKey);
@@ -133,7 +224,7 @@ async function handleRequest(context) {
         return;
     }
     if (url.pathname === '/v1/admin/auth/logout' && request.method === 'POST') {
-        assertTrustedOrigin(request, true);
+        assertTrustedOrigin(request, config);
         const id = cookieValue(request, ADMIN_COOKIE);
         if (id)
             adminSessions.delete(id);
@@ -149,7 +240,7 @@ async function handleRequest(context) {
             throw new RequestError(404, 'Control plane is unavailable');
         authenticateAdmin(request, adminSessions);
         if (isMutating(request.method))
-            assertTrustedOrigin(request, true);
+            assertTrustedOrigin(request, config);
         await handleAdminRoute(context, url);
         return;
     }
@@ -167,13 +258,34 @@ async function handleRequest(context) {
         });
         return;
     }
+    const dataArtifactMatch = url.pathname.match(/^\/v1\/runs\/([^/]+)\/artifacts\/([^/]+)$/);
+    if (dataArtifactMatch && request.method === 'GET') {
+        const runId = decodeURIComponent(dataArtifactMatch[1]);
+        const artifactId = decodeURIComponent(dataArtifactMatch[2]);
+        const run = await getRunForDataPlane(sessions, runId, principal.id);
+        assertAgentScope(principal, run.agentId);
+        await writeRunArtifact(response, sessions, run, artifactId);
+        return;
+    }
     if (url.pathname === '/v1/sessions' && request.method === 'POST') {
         assertJsonContentType(request);
         const body = await readJsonBody(request, config.maxRequestBytes);
         assertOnlyKeys(body, ['agentId', 'workspace']);
         const agentId = requiredString(body.agentId, 'agentId');
         assertAgentScope(principal, agentId);
-        writeJson(response, 201, await sessions.create(agentId, optionalString(body.workspace), principal.id));
+        // Reserve before the asynchronous startup path.  The reservation is
+        // retained until the session is explicitly closed so a key cannot
+        // fill the process with terminal-but-held sessions.
+        const releaseSession = context.quota.reserveSession(principal.id);
+        try {
+            const created = await sessions.create(agentId, optionalString(body.workspace), principal.id);
+            context.sessionReservations.set(created.id, releaseSession);
+            writeJson(response, 201, created);
+        }
+        catch (error) {
+            releaseSession();
+            throw error;
+        }
         return;
     }
     const attachmentMatch = url.pathname.match(/^\/v1\/sessions\/([^/]+)\/attachments$/);
@@ -184,8 +296,35 @@ async function handleRequest(context) {
             throw new RequestError(404, 'Session not found');
         }
         assertAgentScope(principal, session.agentId);
-        const bytes = await readBytesBody(request, config.maxAttachmentBytes || 32 * 1024 * 1024);
-        writeJson(response, 201, sessions.addInputAttachment(sessionId, decodeHeader(request.headers['x-nexus-file-name']) || 'attachment', normalizedMediaType(request.headers['content-type']), bytes));
+        const declared = Number(request.headers['content-length']);
+        // When a length is supplied, reject before consuming the body. This
+        // keeps a rejected upload from needlessly buffering a request and
+        // makes quota failures deterministic under concurrent uploads.
+        const preflightUpload = Number.isFinite(declared) && declared > 0
+            ? context.quota.reserveUpload(principal.id, declared)
+            : undefined;
+        let releaseUpload;
+        try {
+            const bytes = await readBytesBody(request, config.maxAttachmentBytes || 32 * 1024 * 1024);
+            preflightUpload?.();
+            releaseUpload = context.quota.reserveUpload(principal.id, bytes.length);
+            const attachment = sessions.addInputAttachment(sessionId, decodeHeader(request.headers['x-nexus-file-name']) || 'attachment', normalizedMediaType(request.headers['content-type']), bytes);
+            const previous = context.uploadReservations.get(sessionId);
+            if (previous) {
+                // Compose releases so closing the session returns the entire
+                // retained upload budget exactly once.
+                context.uploadReservations.set(sessionId, composeReleases(previous, releaseUpload));
+            }
+            else {
+                context.uploadReservations.set(sessionId, releaseUpload);
+            }
+            writeJson(response, 201, attachment);
+        }
+        catch (error) {
+            preflightUpload?.();
+            releaseUpload?.();
+            throw error;
+        }
         return;
     }
     const resolveMatch = url.pathname.match(/^\/v1\/sessions\/([^/]+)\/requests\/([^/]+)\/resolve$/);
@@ -203,7 +342,7 @@ async function handleRequest(context) {
         const resolution = {
             requestId,
             message: optionalString(body.message),
-            optionId: optionalString(body.optionId),
+            optionId: optionalRawString(body.optionId, 'optionId'),
             action: optionalPendingAction(body.action)
         };
         if (!resolution.message &&
@@ -211,7 +350,17 @@ async function handleRequest(context) {
             !resolution.action) {
             throw new RequestError(400, 'A pending response is required');
         }
-        writeJson(response, 202, await sessions.resolvePending(sessionId, resolution, optionalAttachmentIds(body.attachments)));
+        const releaseRun = reserveRunIfNeeded(context, principal.id, sessionId, session.state);
+        try {
+            const updated = await sessions.resolvePending(sessionId, resolution, optionalAttachmentIds(body.attachments));
+            if (isTerminalState(updated.state))
+                releaseRunReservation(context, sessionId);
+            writeJson(response, 202, updated);
+        }
+        catch (error) {
+            releaseRun?.();
+            throw error;
+        }
         return;
     }
     const publishMatch = url.pathname.match(/^\/v1\/sessions\/([^/]+)\/artifacts\/publish$/);
@@ -243,37 +392,54 @@ async function handleRequest(context) {
         throw new RequestError(404, 'Session not found');
     }
     assertAgentScope(principal, session.agentId);
+    reconcileRunReservation(context, principal.id, sessionId, session.state);
     if (!action && request.method === 'GET') {
         writeJson(response, 200, session);
         return;
     }
     if (!action && request.method === 'DELETE') {
-        writeJson(response, 200, await sessions.close(sessionId));
+        const closed = await sessions.close(sessionId);
+        releaseSessionReservations(context, sessionId);
+        releaseRunReservation(context, sessionId);
+        writeJson(response, 200, closed);
         return;
     }
     if (action === 'message' && request.method === 'POST') {
         assertJsonContentType(request);
         const body = await readJsonBody(request, config.maxRequestBytes);
         assertOnlyKeys(body, ['message', 'attachments']);
-        writeJson(response, 202, await sessions.message(sessionId, requiredMessage(body.message), optionalAttachmentIds(body.attachments)));
+        const releaseRun = reserveRunIfNeeded(context, principal.id, sessionId, session.state);
+        try {
+            const updated = await sessions.message(sessionId, requiredMessage(body.message), optionalAttachmentIds(body.attachments));
+            if (isTerminalState(updated.state))
+                releaseRunReservation(context, sessionId);
+            writeJson(response, 202, updated);
+        }
+        catch (error) {
+            releaseRun?.();
+            throw error;
+        }
         return;
     }
     if (action === 'cancel' && request.method === 'POST') {
         await assertEmptyJsonBody(request, config.maxRequestBytes);
-        writeJson(response, 200, await sessions.cancel(sessionId));
+        const canceled = await sessions.cancel(sessionId);
+        releaseRunReservation(context, sessionId);
+        writeJson(response, 200, canceled);
         return;
     }
     if (action === 'events' && request.method === 'GET') {
-        if (!context.acquireSse()) {
+        const releaseSse = context.acquireSse(principal.id);
+        if (!releaseSse) {
             throw new RequestError(429, 'SSE connection capacity has been reached');
         }
-        streamEvents(request, response, sessions, sessionId, url.searchParams.get('after') || stringHeader(request.headers['last-event-id']), context.releaseSse);
+        streamSessionEvents(request, response, sessions, sessionId, url.searchParams.get('after') ?? (stringHeader(request.headers['last-event-id']) || undefined), releaseSse, (close) => controlPlane?.watchApiKey(principal.id, stringHeader(request.headers.authorization).slice(7), session.agentId, close) || (() => { }));
         return;
     }
     throw new RequestError(405, 'Method not allowed');
 }
 async function handleAdminRoute(context, url) {
-    const { config, sessions, controlPlane, adminSessions, request, response } = context;
+    const { config, sessions, controlPlane, adminSessions, request, response, metrics, diagnostics } = context;
     if (!controlPlane)
         throw new RequestError(404, 'Control plane is unavailable');
     if (url.pathname === '/v1/admin/overview' && request.method === 'GET') {
@@ -281,6 +447,36 @@ async function handleAdminRoute(context, url) {
         writeJson(response, 200, { agents, sessions: sessions.count() });
         return;
     }
+    if (url.pathname === '/v1/admin/metrics' && request.method === 'GET') {
+        const all = sessions.listRuns({ limit: 1 });
+        const actionStates = new Set(['failed', 'input_required', 'permission_required']);
+        const recent = new Map();
+        for (const state of actionStates) {
+            for (const run of sessions.listRuns({ state: state, limit: 5 }).runs) {
+                recent.set(run.id, run);
+            }
+        }
+        const recentRuns = Array.from(recent.values())
+            .sort((left, right) => right.updatedAt - left.updatedAt)
+            .slice(0, 5);
+        const baseStats = all.stats || { active: 0, completed: 0, failed: 0 };
+        const runStats = {
+            active: Number(baseStats.active) || 0,
+            completed: Number(baseStats.completed) || 0,
+            failed: Number(baseStats.failed) || 0,
+            total: Number(all.total) || 0
+        };
+        writeJson(response, 200, await metrics.snapshot({
+            sessions: sessions.count(),
+            currentSse: currentSseCount(context),
+            runs: runStats,
+            recentRuns,
+            storagePath: config.workspaceRoots[0],
+            storageMetrics: sessions.getStorageMetrics?.(),
+            quotas: context.quota
+        }));
+        return;
+    }
     if (url.pathname === '/v1/admin/config' && request.method === 'GET') {
         writeJson(response, 200, controlPlane.snapshot());
         return;
@@ -299,13 +495,93 @@ async function handleAdminRoute(context, url) {
             sessionId: cleanQuery(url.searchParams.get('sessionId')),
             state,
             query: cleanQuery(url.searchParams.get('q')),
+            offset: boundedOffset(url.searchParams.get('offset')),
+            limit: boundedLimit(url.searchParams.get('limit'))
+        }));
+        return;
+    }
+    const runActionMatch = url.pathname.match(/^\/v1\/admin\/runs\/([^/]+)\/(cancel|retry|respond)$/);
+    if (runActionMatch) {
+        await handleAdminRunAction(context, decodeURIComponent(runActionMatch[1]), runActionMatch[2]);
+        return;
+    }
+    if (url.pathname === '/v1/admin/artifacts' && request.method === 'GET') {
+        writeJson(response, 200, sessions.listArtifacts({
+            agentId: cleanQuery(url.searchParams.get('agentId')),
+            kind: cleanQuery(url.searchParams.get('kind')),
+            query: cleanQuery(url.searchParams.get('q')),
+            offset: boundedOffset(url.searchParams.get('offset')),
             limit: boundedLimit(url.searchParams.get('limit'))
         }));
         return;
     }
+    const adminArtifactMatch = url.pathname.match(/^\/v1\/admin\/runs\/([^/]+)\/artifacts\/([^/]+)$/);
+    if (adminArtifactMatch && request.method === 'GET') {
+        const run = sessions.getRun(decodeURIComponent(adminArtifactMatch[1]));
+        await writeRunArtifact(response, sessions, run, decodeURIComponent(adminArtifactMatch[2]));
+        return;
+    }
+    if (adminArtifactMatch && request.method === 'DELETE') {
+        await assertEmptyJsonBody(request, config.maxRequestBytes);
+        const runId = decodeURIComponent(adminArtifactMatch[1]);
+        const artifactId = decodeURIComponent(adminArtifactMatch[2]);
+        const run = sessions.getRun(runId);
+        if (!isTerminalState(run.state)) {
+            throw new RequestError(409, 'Artifacts of active runs cannot be deleted; cancel the task first');
+        }
+        const deleted = await sessions.removeRunArtifact(runId, artifactId);
+        if (!deleted)
+            throw new RequestError(404, 'Agent Nexus artifact not found');
+        console.info(JSON.stringify({
+            level: 'info',
+            event: 'admin_artifact_deleted',
+            runId,
+            artifactId,
+            agentId: run.agentId,
+            requestId: String(response.getHeader('X-Request-Id') || '')
+        }));
+        writeJson(response, 200, { deleted: true, runId, artifactId });
+        return;
+    }
     const runMatch = url.pathname.match(/^\/v1\/admin\/runs\/([^/]+)$/);
-    if (runMatch && request.method === 'GET') {
-        writeJson(response, 200, sessions.getRun(decodeURIComponent(runMatch[1])));
+    if (runMatch && (request.method === 'GET' || request.method === 'DELETE')) {
+        const runId = decodeURIComponent(runMatch[1]);
+        if (request.method === 'DELETE') {
+            await assertEmptyJsonBody(request, config.maxRequestBytes);
+            const detail = sessions.getRun(runId);
+            if (!isTerminalState(detail.state)) {
+                throw new RequestError(409, 'Active runs cannot be deleted; cancel the task first');
+            }
+            const deleted = sessions.deleteRun(runId);
+            if (!deleted)
+                throw new RequestError(404, 'Agent Nexus run not found');
+            console.info(JSON.stringify({
+                level: 'info',
+                event: 'admin_run_record_deleted',
+                runId,
+                sessionId: detail.sessionId,
+                agentId: detail.agentId,
+                state: detail.state,
+                requestId: String(response.getHeader('X-Request-Id') || '')
+            }));
+            writeJson(response, 200, { deleted: true, id: runId });
+            return;
+        }
+        const detail = sessions.getRun(runId);
+        writeJson(response, 200, {
+            ...detail,
+            controls: buildRunControls(sessions, detail)
+        });
+        return;
+    }
+    const diagnosticMatch = url.pathname.match(/^\/v1\/admin\/agents\/([^/]+)\/diagnostics$/);
+    if (diagnosticMatch && request.method === 'POST') {
+        await assertEmptyJsonBody(request, config.maxRequestBytes);
+        const agentId = decodeURIComponent(diagnosticMatch[1]);
+        const configured = controlPlane.snapshot().agents.find((agent) => agent.id === agentId);
+        const workspace = configured?.workspace;
+        const result = await diagnostics.run(sessions, agentId, workspace, configured);
+        writeJson(response, result.status === 'busy' ? 429 : 200, result);
         return;
     }
     if (url.pathname === '/v1/admin/config/workspace-roots' && request.method === 'PUT') {
@@ -351,7 +627,12 @@ async function handleAdminRoute(context, url) {
         const action = keyMatch[2];
         if (action === 'reveal' && request.method === 'POST') {
             await assertEmptyJsonBody(request, config.maxRequestBytes);
-            writeJson(response, 200, controlPlane.revealApiKey(id));
+            const rateKey = remoteKey(request);
+            context.revealLimiter.assertAllowed(rateKey);
+            context.revealLimiter.failure(rateKey);
+            const result = controlPlane.revealApiKey(id);
+            console.info(JSON.stringify({ level: 'info', event: 'api_key_revealed', keyId: id, requestId: response.getHeader('X-Request-Id'), remoteAddress: rateKey }));
+            writeJson(response, 200, result);
             return;
         }
         if (action === 'regenerate' && request.method === 'POST') {
@@ -389,6 +670,382 @@ async function handleAdminRoute(context, url) {
     }
     throw new RequestError(404, 'Route not found');
 }
+async function handleAdminRunAction(context, runId, action) {
+    const { config, sessions, request, response } = context;
+    const requestId = String(response.getHeader('X-Request-Id') || '');
+    let detail;
+    let sessionId = '';
+    let agentId = '';
+    let ownerKeyId;
+    try {
+        if (request.method !== 'POST')
+            throw new RequestError(405, 'Method not allowed');
+        detail = sessions.getRun(runId);
+        sessionId = detail.sessionId;
+        agentId = detail.agentId;
+        ownerKeyId = runOwnerKeyId(sessions, runId);
+        const controls = buildRunControls(sessions, detail);
+        if (action === 'cancel' && !controls.canCancel) {
+            throw new RequestError(409, controls.unavailableReason || 'Run cannot be canceled');
+        }
+        if (action === 'retry' && !controls.canRetry) {
+            throw new RequestError(409, controls.unavailableReason || 'Run cannot be retried');
+        }
+        if (action === 'cancel' || action === 'retry') {
+            await assertEmptyJsonBody(request, config.maxRequestBytes);
+        }
+        let input;
+        if (action === 'respond')
+            input = await readAdminRunResponse(request, config.maxRequestBytes);
+        // AdminRunManager calls this factory only after its synchronous retry
+        // deduplication gate accepts a genuinely new retry. This keeps a
+        // completed duplicate from consuming either session or run quota.
+        const reserveRetry = action === 'retry'
+            ? (keyId) => reserveAdminRetry(context, keyId)
+            : undefined;
+        const result = await invokeRunAction(sessions, action, runId, sessionId, input, reserveRetry);
+        const resultRunId = action === 'retry'
+            ? actionResultString(result, 'runId') || actionResultRecord(result, 'run')?.id || runId
+            : runId;
+        const resultSessionId = action === 'retry'
+            ? actionResultString(result, 'sessionId') || actionResultRecord(result, 'session')?.id || ''
+            : sessionId;
+        if (!resultSessionId && action === 'retry') {
+            throw new RequestError(502, 'Retry did not return a session');
+        }
+        const state = actionResultString(result, 'state') ||
+            actionResultRecord(result, 'session')?.state ||
+            actionResultRecord(result, 'run')?.state;
+        if (action === 'cancel' || state === 'canceled')
+            releaseRunReservation(context, sessionId);
+        if (action === 'retry' && state && isTerminalState(state) && resultSessionId) {
+            releaseRunReservation(context, resultSessionId);
+        }
+        auditAdminRunAction({
+            action,
+            runId,
+            sessionId,
+            agentId,
+            keyId: ownerKeyId,
+            requestId,
+            result: 'accepted'
+        });
+        if (action === 'retry') {
+            writeJson(response, 202, { runId: resultRunId, sessionId: resultSessionId });
+        }
+        else {
+            writeJson(response, 202, {
+                runId,
+                sessionId,
+                ...(state ? { state } : {}),
+                result: 'accepted'
+            });
+        }
+    }
+    catch (error) {
+        auditAdminRunAction({
+            action,
+            runId,
+            sessionId,
+            agentId,
+            keyId: ownerKeyId,
+            requestId,
+            result: 'failed'
+        });
+        throw error;
+    }
+}
+async function readAdminRunResponse(request, maxBytes) {
+    assertJsonContentType(request);
+    const body = await readJsonBody(request, maxBytes);
+    assertOnlyKeys(body, ['requestId', 'message', 'optionId', 'action']);
+    const result = {
+        requestId: requiredString(body.requestId, 'requestId'),
+        message: optionalRawString(body.message, 'message'),
+        optionId: optionalRawString(body.optionId, 'optionId'),
+        action: optionalPendingAction(body.action)
+    };
+    if (!result.message?.trim() && !result.optionId && !result.action) {
+        throw new RequestError(400, 'A pending response is required');
+    }
+    return result;
+}
+async function invokeRunAction(sessions, action, runId, sessionId, input, reserveRetry) {
+    const target = sessions;
+    const candidates = action === 'cancel'
+        ? ['cancelRun', 'cancelByRunId']
+        : action === 'retry'
+            ? ['retryRun', 'retryByRunId']
+            : ['respondRun', 'respondByRunId'];
+    for (const name of candidates) {
+        if (typeof target[name] !== 'function')
+            continue;
+        if (action === 'respond')
+            return target[name].call(sessions, runId, input);
+        if (action === 'retry')
+            return target[name].call(sessions, runId, reserveRetry);
+        return target[name].call(sessions, runId);
+    }
+    // Cancellation and pending responses can be safely delegated through the
+    // existing SessionManager methods. Retry intentionally has no fallback:
+    // reconstructing a prompt here could duplicate a run or lose attachments.
+    if (action === 'cancel' && typeof target.cancel === 'function') {
+        return target.cancel.call(sessions, sessionId);
+    }
+    if (action === 'respond' && typeof target.resolvePending === 'function') {
+        return target.resolvePending.call(sessions, sessionId, input);
+    }
+    throw new RequestError(409, `Run ${action} is unavailable`);
+}
+function buildRunControls(sessions, detail) {
+    const target = sessions;
+    if (typeof target.getRunControls === 'function') {
+        try {
+            return structuredClone(target.getRunControls(detail.id));
+        }
+        catch {
+            // Fall through to the compatibility calculation for embedders
+            // that expose getRunControls only for newer run records.
+        }
+    }
+    let session;
+    try {
+        session = sessions.get(detail.sessionId);
+    }
+    catch {
+        session = undefined;
+    }
+    const active = isActiveState(detail.state);
+    const canCancel = active && (typeof target.cancelRun === 'function' ||
+        typeof target.cancelByRunId === 'function' ||
+        typeof target.cancel === 'function');
+    const canRetry = (detail.state === 'failed' || detail.state === 'canceled') && (typeof target.retryRun === 'function' || typeof target.retryByRunId === 'function');
+    const pendingRequest = session?.pendingRequest || detail.pendingRequest;
+    const unavailableReason = !session && active
+        ? 'Session is no longer available'
+        : active && !canCancel
+            ? 'Cancellation is unavailable'
+            : (detail.state === 'failed' || detail.state === 'canceled') && !canRetry
+                ? 'Retry is unavailable'
+                : undefined;
+    return {
+        canCancel,
+        canRetry,
+        canDelete: !active,
+        ...(pendingRequest ? { pendingRequest: structuredClone(pendingRequest) } : {}),
+        ...(unavailableReason ? { unavailableReason } : {})
+    };
+}
+function runOwnerKeyId(sessions, runId) {
+    const target = sessions;
+    for (const name of ['getRunOwnerKeyId', 'runOwnerKeyId', 'ownerKeyForRun']) {
+        if (typeof target[name] !== 'function')
+            continue;
+        const value = target[name].call(sessions, runId);
+        if (typeof value === 'string' && value)
+            return value;
+    }
+    return undefined;
+}
+function actionResultString(value, key) {
+    return isRecord(value) && typeof value[key] === 'string' ? value[key] : undefined;
+}
+function actionResultRecord(value, key) {
+    return isRecord(value) && isRecord(value[key]) ? value[key] : undefined;
+}
+function auditAdminRunAction(input) {
+    console.info(JSON.stringify({
+        level: 'info',
+        event: 'admin_run_action',
+        ...input,
+        ...(input.sessionId ? {} : { sessionId: undefined }),
+        ...(input.agentId ? {} : { agentId: undefined }),
+        ...(input.keyId ? {} : { keyId: undefined })
+    }));
+}
+async function getRunForDataPlane(sessions, runId, ownerKeyId) {
+    const target = sessions;
+    for (const name of ['getRunForOwner', 'getRunOwnedBy']) {
+        if (typeof target[name] !== 'function')
+            continue;
+        const result = await target[name].call(sessions, runId, ownerKeyId);
+        if (!result)
+            throw new RequestError(404, 'Run not found');
+        return result;
+    }
+    if (typeof target.ownsRun === 'function') {
+        const owned = await target.ownsRun.call(sessions, runId, ownerKeyId);
+        if (!owned)
+            throw new RequestError(404, 'Run not found');
+    }
+    const run = sessions.getRun(runId);
+    if (typeof target.ownsRun !== 'function') {
+        // Before the worker adds a direct RunStore wrapper, use the original
+        // Session ownership check. It deliberately fails closed for persisted
+        // runs whose in-memory Session has already been evicted.
+        try {
+            if (!sessions.owns(run.sessionId, ownerKeyId))
+                throw new Error();
+        }
+        catch {
+            throw new RequestError(404, 'Run not found');
+        }
+    }
+    return run;
+}
+async function writeRunArtifact(response, sessions, run, artifactId) {
+    const artifact = Array.isArray(run.artifacts)
+        ? run.artifacts.find((value) => value?.id === artifactId)
+        : undefined;
+    if (!artifact)
+        throw new RequestError(404, 'Artifact not found');
+    const payload = await resolveArtifactPayload(sessions, run.id, artifactId);
+    if (!payload)
+        throw new RequestError(404, 'Artifact bytes are unavailable');
+    const filename = safeDownloadFilename(payload.filename || artifact.filename || artifact.name || artifactId);
+    const mediaType = cleanMediaType(payload.mediaType || artifact.mediaType);
+    response.writeHead(200, {
+        'Content-Type': mediaType,
+        'Content-Length': payload.bytes.length,
+        'Content-Disposition': contentDisposition(filename),
+        'Cache-Control': 'no-store',
+        'X-Content-Type-Options': 'nosniff'
+    });
+    response.end(payload.bytes);
+}
+async function resolveArtifactPayload(sessions, runId, artifactId) {
+    return sessions.readRunArtifact(runId, artifactId);
+}
+function safeDownloadFilename(value) {
+    const text = String(value || 'artifact')
+        .replace(/[<>:"/\\|?*\u0000-\u001f\u007f]/g, '_')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 180);
+    return text || 'artifact';
+}
+function contentDisposition(filename) {
+    const fallback = filename.replace(/[^A-Za-z0-9._-]/g, '_') || 'artifact';
+    return `attachment; filename="${fallback.replace(/"/g, '_')}"; filename*=UTF-8''${encodeURIComponent(filename)}`;
+}
+function cleanMediaType(value) {
+    const text = typeof value === 'string' ? value.split(';', 1)[0].trim().toLowerCase() : '';
+    return /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/.test(text)
+        ? text
+        : 'application/octet-stream';
+}
+function currentSseCount(context) {
+    return context.currentSse();
+}
+function reserveRunIfNeeded(context, keyId, sessionId, state) {
+    if (isTerminalState(state)) {
+        releaseRunReservation(context, sessionId);
+        return undefined;
+    }
+    if (context.runReservations.has(sessionId))
+        return undefined;
+    const releaseQuota = context.quota.reserveRunningRun(keyId, sessionId);
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        if (context.runReservations.get(sessionId) === release)
+            context.runReservations.delete(sessionId);
+        releaseQuota();
+    };
+    context.runReservations.set(sessionId, release);
+    return release;
+}
+function reconcileRunReservation(context, keyId, sessionId, state) {
+    if (isTerminalState(state)) {
+        releaseRunReservation(context, sessionId);
+        context.quota.finishRun(sessionId, keyId);
+    }
+}
+function releaseRunReservation(context, sessionId) {
+    const release = context.runReservations.get(sessionId);
+    if (release)
+        release();
+    else
+        context.quota.finishRun(sessionId);
+}
+function releaseSessionReservations(context, sessionId) {
+    const releaseSession = context.sessionReservations.get(sessionId);
+    if (releaseSession) {
+        context.sessionReservations.delete(sessionId);
+        releaseSession();
+    }
+    const releaseUpload = context.uploadReservations.get(sessionId);
+    if (releaseUpload) {
+        context.uploadReservations.delete(sessionId);
+        releaseUpload();
+    }
+}
+function reserveAdminRetry(context, keyId) {
+    const releaseSessionQuota = context.quota.reserveSession(keyId);
+    let releaseRunQuota;
+    try {
+        releaseRunQuota = context.quota.reserveRunningRun(keyId);
+    }
+    catch (error) {
+        releaseSessionQuota();
+        throw error;
+    }
+    let sessionId;
+    let sessionReleased = false;
+    let runReleased = false;
+    const releaseSession = () => {
+        if (sessionReleased)
+            return;
+        sessionReleased = true;
+        if (sessionId && context.sessionReservations.get(sessionId) === releaseSession) {
+            context.sessionReservations.delete(sessionId);
+        }
+        releaseSessionQuota();
+    };
+    const releaseRun = () => {
+        if (runReleased)
+            return;
+        runReleased = true;
+        if (sessionId && context.runReservations.get(sessionId) === releaseRun) {
+            context.runReservations.delete(sessionId);
+        }
+        releaseRunQuota?.();
+    };
+    return {
+        bind(id) {
+            if (sessionId)
+                return;
+            sessionId = id;
+            context.sessionReservations.set(id, releaseSession);
+            context.runReservations.set(id, releaseRun);
+        },
+        release() {
+            releaseSession();
+            releaseRun();
+        }
+    };
+}
+function composeReleases(left, right) {
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        left();
+        right();
+    };
+}
+function isActiveState(state) {
+    return state === 'running' || state === 'input_required' || state === 'permission_required';
+}
+function isTerminalState(state) {
+    return state === 'completed' || state === 'failed' || state === 'canceled';
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
 function readAgentUpdate(body) {
     assertOnlyKeys(body, [
         'protocol',
@@ -405,7 +1062,9 @@ function readAgentUpdate(body) {
         'authType',
         'authValue',
         'authHeaderName',
-        'timeoutMs'
+        'timeoutMs',
+        'taskTimeoutMs',
+        'streamIdleTimeoutMs'
     ]);
     return {
         protocol: requiredString(body.protocol, 'protocol'),
@@ -422,7 +1081,9 @@ function readAgentUpdate(body) {
         authType: optionalString(body.authType),
         authValue: optionalRawString(body.authValue, 'authValue'),
         authHeaderName: optionalString(body.authHeaderName),
-        timeoutMs: optionalNumber(body.timeoutMs, 'timeoutMs')
+        timeoutMs: optionalNumber(body.timeoutMs, 'timeoutMs'),
+        taskTimeoutMs: body.taskTimeoutMs === null ? null : optionalNumber(body.taskTimeoutMs, 'taskTimeoutMs'),
+        streamIdleTimeoutMs: body.streamIdleTimeoutMs === null ? null : optionalNumber(body.streamIdleTimeoutMs, 'streamIdleTimeoutMs')
     };
 }
 function readRuntimeSettingsUpdate(body) {
@@ -454,384 +1115,12 @@ function readApiKeyScope(value) {
         agentIds: requiredStringArray(scope.agentIds ?? [], 'scope.agentIds', true)
     };
 }
-function streamEvents(request, response, sessions, sessionId, after, release) {
-    response.writeHead(200, {
-        'Content-Type': 'text/event-stream; charset=utf-8',
-        'Cache-Control': 'no-cache, no-transform',
-        Connection: 'keep-alive',
-        'X-Accel-Buffering': 'no'
-    });
-    response.flushHeaders?.();
-    for (const event of sessions.eventsAfter(sessionId, after))
-        writeEvent(response, event);
-    const unsubscribe = sessions.subscribe(sessionId, (event) => writeEvent(response, event));
-    // Give idle SSE clients ~90 s to react before Node's default socket timeout
-    // trips. Combined with the writableEnded check inside the heartbeat this
-    // guarantees stuck keep-alive sessions eventually release their slot even
-    // if the peer never sends a FIN.
-    const idleMs = 90_000;
-    request.socket.setTimeout?.(idleMs);
-    let closed = false;
-    const close = () => {
-        if (closed)
-            return;
-        closed = true;
-        clearInterval(heartbeat);
-        unsubscribe();
-        // Ensure both ends of the socket are actually torn down so the SSE
-        // slot returns to the pool even when the peer stops reading without
-        // closing the TCP connection cleanly.
-        try {
-            if (!response.writableEnded)
-                response.end();
-        }
-        catch { }
-        try {
-            request.socket.destroy();
-        }
-        catch { }
-        release();
-    };
-    const heartbeat = setInterval(() => {
-        if (response.destroyed || response.writableEnded) {
-            close();
-            return;
-        }
-        try {
-            response.write(': heartbeat\n\n');
-        }
-        catch {
-            close();
-        }
-    }, 15_000);
-    heartbeat.unref?.();
-    request.once('close', close);
-    response.once('close', close);
-    request.socket.once('timeout', close);
-    request.socket.once('error', close);
-}
-function writeEvent(response, event) {
-    if (response.destroyed || response.writableEnded)
-        return;
-    response.write(`id: ${event.id}\n`);
-    response.write(`event: ${event.type}\n`);
-    response.write(`data: ${JSON.stringify(event)}\n\n`);
-}
-function authenticateAdmin(request, sessions) {
-    const id = cookieValue(request, ADMIN_COOKIE);
-    if (!id || !sessions.has(id))
-        throw new RequestError(401, 'Admin session is required');
-}
-function authenticateApiKey(request, config, controlPlane, limiter) {
-    const rateKey = remoteKey(request);
-    limiter.assertAllowed(rateKey);
-    const value = stringHeader(request.headers.authorization);
-    if (!value.startsWith('Bearer ')) {
-        limiter.failure(rateKey);
-        throw new RequestError(401, 'Bearer API Key is required');
-    }
-    const secret = value.slice(7);
-    const authenticate = controlPlane?.authenticateApiKey;
-    const principal = (typeof authenticate === 'function'
-        ? authenticate.call(controlPlane, secret)
-        : undefined) || fallbackApiKey(config, secret);
-    if (!principal) {
-        limiter.failure(rateKey);
-        throw new RequestError(401, 'Invalid API Key');
-    }
-    limiter.success(rateKey);
-    return principal;
-}
-function fallbackApiKey(config, secret) {
-    for (const key of config.apiKeys || []) {
-        if (key.enabled && safeEqual(key.secret, secret)) {
-            return { id: key.id, scope: structuredClone(key.scope) };
-        }
-    }
-    if (config.authToken && safeEqual(config.authToken, secret)) {
-        return { id: 'legacy', scope: { allAgents: true, agentIds: [] } };
-    }
-    return undefined;
-}
-function assertAgentScope(principal, agentId) {
-    if (!principal.scope.allAgents && !principal.scope.agentIds.includes(agentId)) {
-        throw new RequestError(403, 'API Key is not authorized for this agent');
-    }
-}
-function isInitialized(config, controlPlane) {
-    return controlPlane?.isInitialized() ?? config.initialized;
-}
-function needsAdminSetup(config, controlPlane) {
-    const value = controlPlane?.needsAdminSetup;
-    return typeof value === 'function' ? value.call(controlPlane) : !config.adminPasswordHash;
-}
-function assertTrustedOrigin(request, required) {
-    const origin = stringHeader(request.headers.origin);
-    if (!origin) {
-        if (required)
-            throw new RequestError(403, 'Same-origin request is required');
-        return;
-    }
-    let originHost = '';
-    try {
-        originHost = new URL(origin).host;
-    }
-    catch {
-        throw new RequestError(403, 'Request origin is invalid');
-    }
-    if (!originHost || originHost !== stringHeader(request.headers.host)) {
-        throw new RequestError(403, 'Cross-origin admin request is not allowed');
-    }
-}
-function assertJsonContentType(request) {
-    const contentType = stringHeader(request.headers['content-type'])
-        .split(';', 1)[0]
-        .trim()
-        .toLowerCase();
-    if (contentType !== 'application/json') {
-        throw new RequestError(415, 'Request requires application/json');
-    }
-}
-async function assertEmptyJsonBody(request, maxBytes) {
-    if (Number(request.headers['content-length'] || 0) <= 0)
-        return;
-    assertJsonContentType(request);
-    const body = await readJsonBody(request, maxBytes);
-    assertOnlyKeys(body, []);
-}
-async function readJsonBody(request, maxBytes) {
-    const declared = Number(request.headers['content-length']);
-    if (Number.isFinite(declared) && declared > maxBytes) {
-        throw new RequestError(413, 'Request body is too large');
-    }
-    const chunks = [];
-    let total = 0;
-    for await (const value of request) {
-        const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
-        total += chunk.length;
-        if (total > maxBytes)
-            throw new RequestError(413, 'Request body is too large');
-        chunks.push(chunk);
-    }
-    const raw = Buffer.concat(chunks).toString('utf8');
-    if (!raw.trim())
-        return {};
-    try {
-        const parsed = JSON.parse(raw);
-        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            throw new Error('body must be an object');
-        }
-        return parsed;
-    }
-    catch (error) {
-        throw new RequestError(400, `Invalid JSON body: ${errorMessage(error)}`);
-    }
-}
-async function readBytesBody(request, maxBytes) {
-    const declared = Number(request.headers['content-length']);
-    if (Number.isFinite(declared) && declared > maxBytes) {
-        throw new RequestError(413, 'Request body is too large');
-    }
-    const chunks = [];
-    let total = 0;
-    for await (const value of request) {
-        const chunk = Buffer.isBuffer(value) ? value : Buffer.from(value);
-        total += chunk.length;
-        if (total > maxBytes)
-            throw new RequestError(413, 'Request body is too large');
-        chunks.push(chunk);
-    }
-    return Buffer.concat(chunks);
-}
-function assertOnlyKeys(body, allowed) {
-    const accepted = new Set(allowed);
-    const unknown = Object.keys(body).filter((key) => !accepted.has(key));
-    if (unknown.length) {
-        throw new RequestError(400, `Unsupported request fields: ${unknown.join(', ')}`);
-    }
-}
-function requiredString(value, name) {
-    const text = typeof value === 'string' ? value.trim() : '';
-    if (!text)
-        throw new RequestError(400, `${name} is required`);
-    return text;
-}
-function requiredRawString(value, name) {
-    if (typeof value !== 'string' || !value)
-        throw new RequestError(400, `${name} is required`);
-    return value;
-}
-function requiredMessage(value) {
-    if (typeof value !== 'string' || !value.trim()) {
-        throw new RequestError(400, 'message is required');
-    }
-    return value;
-}
-function requiredInteger(value, name) {
-    if (typeof value !== 'number' || !Number.isInteger(value)) {
-        throw new RequestError(400, `${name} must be an integer`);
-    }
-    return value;
-}
-function optionalAttachmentIds(value) {
-    if (value === undefined)
-        return [];
-    if (!Array.isArray(value) || value.length > 16) {
-        throw new RequestError(400, 'attachments must be an array with at most 16 ids');
-    }
-    return value.map((item) => requiredString(item, 'attachments'));
-}
-function normalizePublishPaths(body) {
-    const bodyPaths = body.paths;
-    if (bodyPaths !== undefined) {
-        if (!Array.isArray(bodyPaths) || bodyPaths.length === 0) {
-            throw new RequestError(400, 'paths must be a non-empty array of strings');
-        }
-        if (bodyPaths.length > 32) {
-            throw new RequestError(400, 'paths accepts at most 32 entries');
-        }
-        return bodyPaths.map((item) => requiredString(item, 'paths'));
-    }
-    return [requiredString(body.path, 'path')];
-}
-function normalizedMediaType(value) {
-    const mediaType = stringHeader(value).split(';', 1)[0].trim().toLowerCase();
-    return mediaType || undefined;
-}
-function decodeHeader(value) {
-    const raw = stringHeader(value);
-    if (!raw)
-        return '';
-    try {
-        return decodeURIComponent(raw);
-    }
-    catch {
-        return raw;
-    }
-}
-function cleanQuery(value) {
-    const text = String(value || '').trim();
-    return text || undefined;
-}
-function boundedLimit(value) {
-    if (!value)
-        return undefined;
-    const number = Number(value);
-    if (!Number.isInteger(number) || number < 1 || number > 200) {
-        throw new RequestError(400, 'limit must be an integer between 1 and 200');
-    }
-    return number;
-}
-function optionalRunState(value) {
-    if (!value)
-        return undefined;
-    const states = new Set([
-        'created',
-        'running',
-        'input_required',
-        'permission_required',
-        'completed',
-        'failed',
-        'canceled'
-    ]);
-    if (!states.has(value))
-        throw new RequestError(400, 'Invalid run state');
-    return value;
-}
-function optionalRawString(value, name) {
-    if (value === undefined || value === null || value === '')
-        return undefined;
-    if (typeof value !== 'string')
-        throw new RequestError(400, `${name} must be a string`);
-    return value;
-}
-function optionalString(value) {
-    if (value === undefined || value === null)
-        return undefined;
-    if (typeof value !== 'string')
-        throw new RequestError(400, 'Expected a string');
-    return value.trim() || undefined;
-}
-function optionalPendingAction(value) {
-    if (value === undefined || value === null || value === '')
-        return undefined;
-    if (value === 'accept' || value === 'decline' || value === 'cancel') {
-        return value;
-    }
-    throw new RequestError(400, 'action must be accept, decline, or cancel');
-}
-function optionalBoolean(value, name) {
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== 'boolean')
-        throw new RequestError(400, `${name} must be boolean`);
-    return value;
-}
-function optionalNumber(value, name) {
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== 'number' || !Number.isInteger(value)) {
-        throw new RequestError(400, `${name} must be an integer`);
-    }
-    return value;
-}
-function requiredStringArray(value, name, allowEmpty = false) {
-    if (!Array.isArray(value))
-        throw new RequestError(400, `${name} must be an array of strings`);
-    const result = value.map((item) => {
-        if (typeof item !== 'string' || !item.trim()) {
-            throw new RequestError(400, `${name} must contain non-empty strings`);
-        }
-        return item.trim();
-    });
-    if (!allowEmpty && !result.length) {
-        throw new RequestError(400, `${name} must contain at least one value`);
-    }
-    return result;
-}
-function cookieValue(request, name) {
-    const cookie = stringHeader(request.headers.cookie);
-    for (const part of cookie.split(';')) {
-        const index = part.indexOf('=');
-        if (index < 0 || part.slice(0, index).trim() !== name)
-            continue;
-        return part.slice(index + 1).trim();
-    }
-    return '';
-}
-function adminCookie(value, ttlMs, config) {
-    return [
-        `${ADMIN_COOKIE}=${value}`,
-        'Path=/',
-        'HttpOnly',
-        'SameSite=Strict',
-        `Max-Age=${Math.floor(ttlMs / 1000)}`,
-        ...(config.secureAdminCookies ? ['Secure'] : [])
-    ].join('; ');
-}
-function clearAdminCookie(config) {
-    return [
-        `${ADMIN_COOKIE}=`,
-        'Path=/',
-        'HttpOnly',
-        'SameSite=Strict',
-        'Max-Age=0',
-        ...(config.secureAdminCookies ? ['Secure'] : [])
-    ].join('; ');
-}
-function isMutating(method) {
-    return method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE';
-}
-function remoteKey(request) {
-    return request.socket.remoteAddress || 'unknown';
-}
-function stringHeader(value) {
-    return Array.isArray(value) ? value[0] || '' : value || '';
-}
-function safeEqual(left, right) {
-    const a = Buffer.from(left);
-    const b = Buffer.from(right);
-    return a.length === b.length && timingSafeEqual(a, b);
+function boundedOffset(value) {
+    if (value === null)
+        return 0;
+    if (!/^\d{1,9}$/.test(value))
+        throw new RequestError(400, 'offset must be a non-negative integer');
+    return Number(value);
 }
 function safePath(value) {
     try {
@@ -852,6 +1141,8 @@ function errorStatus(error) {
         return error.status;
     if (error instanceof RequestError)
         return error.status;
+    if (error instanceof QuotaExceededError || error instanceof DiagnosticConcurrencyError)
+        return 429;
     return 500;
 }
 function errorMessage(error) {
@@ -867,12 +1158,31 @@ function writeJson(response, status, value) {
     });
     response.end(body);
 }
-class RequestError extends Error {
-    status;
-    constructor(status, message) {
-        super(message);
-        this.status = status;
+function writeError(response, status, error, requestId) {
+    if (error instanceof QuotaExceededError) {
+        writeJson(response, status, {
+            error: 'Quota exceeded',
+            quota: error.quota,
+            limit: error.limit,
+            current: error.current,
+            retryAfterMs: error.retryAfterMs,
+            requestId
+        });
+        return;
+    }
+    if (error instanceof DiagnosticConcurrencyError) {
+        writeJson(response, status, {
+            error: 'Diagnostic capacity has been reached',
+            quota: 'diagnostics',
+            retryAfterMs: error.retryAfterMs,
+            requestId
+        });
+        return;
     }
+    writeJson(response, status, {
+        error: status >= 500 ? 'Internal server error' : errorMessage(error),
+        requestId
+    });
 }
 class FailureRateLimiter {
     maximum;
@@ -892,6 +1202,14 @@ class FailureRateLimiter {
     }
     failure(key) {
         const now = Date.now();
+        // Bound untrusted remote-address cardinality and evict expired failures.
+        for (const [id, item] of this.entries) {
+            if (item.blockedUntil <= now && now - item.windowStartedAt >= this.windowMs)
+                this.entries.delete(id);
+        }
+        if (!this.entries.has(key) && this.entries.size >= 4096) {
+            throw new RequestError(429, 'Too many authentication attempts');
+        }
         const previous = this.entries.get(key);
         const entry = !previous || now - previous.windowStartedAt >= this.windowMs
             ? { count: 0, windowStartedAt: now, blockedUntil: 0 }