nexus-agentd 0.1.0 → 0.1.6

package/dist/server.js

@@ -1,41 +1,229 @@
-import { timingSafeEqual } from 'node:crypto';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
 import http from 'node:http';
-import { SessionNotFoundError } from './session.js';
-export function createAgentdServer(config, sessions) {
-    return http.createServer((request, response) => {
-        void handleRequest(config, sessions, request, response).catch((error) => {
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { ArtifactStoreError, contentDisposition, GatewayArtifactStore, mediaTypeForName } from './artifact-store.js';
+import { AdminSessionStore } from './auth.js';
+import { ControlPlaneError } from './control-plane.js';
+import { RunNotFoundError, SessionNotFoundError, SessionRequestError } from './session.js';
+import { redirectToAgentdWebUi, writeAgentdWebUi } from './webui/index.js';
+import { WorkspaceFileError, WorkspaceFiles } from './workspace-files.js';
+const ADMIN_COOKIE = 'agent_nexus_admin';
+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 artifactStore = new GatewayArtifactStore(config.artifactStoragePath || path.resolve('.nexus-agentd-artifacts'), config.artifactTtlMs || 24 * 60 * 60 * 1000, config.maxArtifactBytes || 512 * 1024 * 1024, config.maxArtifactStorageBytes || 4 * 1024 * 1024 * 1024, config.maxPublishedArtifacts || 4096, config.maxConcurrentArtifactPublishes || 4);
+    const workspaceFiles = new WorkspaceFiles(() => controlPlane?.snapshot().workspaceRoots || config.workspaceRoots, config.maxArtifactBytes || 512 * 1024 * 1024);
+    artifactStore.startCleanup(config.cleanupIntervalMs);
+    let sseConnections = 0;
+    const server = http.createServer((request, response) => {
+        const requestId = randomUUID();
+        response.setHeader('X-Request-Id', requestId);
+        void handleRequest({
+            config,
+            sessions,
+            controlPlane,
+            adminSessions,
+            loginLimiter,
+            apiLimiter,
+            artifactStore,
+            workspaceFiles,
+            request,
+            response,
+            acquireSse() {
+                if (sseConnections >= (config.maxSseConnections || 128))
+                    return false;
+                sseConnections += 1;
+                return true;
+            },
+            releaseSse() {
+                sseConnections = Math.max(0, sseConnections - 1);
+            }
+        }).catch((error) => {
             if (response.headersSent) {
                 response.destroy(error instanceof Error ? error : undefined);
                 return;
             }
-            const status = error instanceof SessionNotFoundError
-                ? 404
-                : error instanceof RequestError
-                    ? error.status
-                    : 500;
+            const status = errorStatus(error);
+            if (status >= 500) {
+                console.error(JSON.stringify({
+                    level: 'error',
+                    event: 'http_request_failed',
+                    requestId,
+                    method: request.method,
+                    path: safePath(request.url),
+                    message: errorMessage(error),
+                    stack: error instanceof Error ? error.stack : undefined
+                }));
+            }
             writeJson(response, status, {
-                error: error instanceof Error ? error.message : String(error)
+                error: status >= 500 ? 'Internal server error' : errorMessage(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();
+        artifactStore.stopCleanup();
+    });
+    return server;
 }
-async function handleRequest(config, sessions, request, response) {
+async function handleRequest(context) {
+    const { config, sessions, controlPlane, adminSessions, loginLimiter, apiLimiter, artifactStore, workspaceFiles, request, response } = context;
     const url = new URL(request.url || '/', 'http://localhost');
+    if (url.pathname === '/' && request.method === 'GET') {
+        redirectToAgentdWebUi(response);
+        return;
+    }
+    if ((url.pathname === '/ui' || url.pathname === '/ui/') && request.method === 'GET') {
+        writeAgentdWebUi(response);
+        return;
+    }
+    const artifactMatch = url.pathname.match(/^\/v1\/artifacts\/([a-f0-9]{64})\/(\d+)\/([^/]+)$/);
+    if (artifactMatch && request.method === 'GET') {
+        const artifact = await artifactStore.open(artifactMatch[1], artifactMatch[2], decodePathSegment(artifactMatch[3]));
+        await streamDownload(response, artifact.handle, artifact.name, artifact.size, artifact.mediaType);
+        return;
+    }
     if (url.pathname === '/health' && request.method === 'GET') {
-        writeJson(response, 200, { ok: true });
+        writeJson(response, 200, {
+            ok: true,
+            initialized: isInitialized(config, controlPlane),
+            adminSetupRequired: needsAdminSetup(config, controlPlane)
+        });
+        return;
+    }
+    if (url.pathname === '/v1/bootstrap/status' && request.method === 'GET') {
+        writeJson(response, 200, {
+            initialized: isInitialized(config, controlPlane),
+            adminSetupRequired: needsAdminSetup(config, controlPlane)
+        });
+        return;
+    }
+    if (url.pathname === '/v1/bootstrap/initialize' && request.method === 'POST') {
+        if (!controlPlane)
+            throw new RequestError(404, 'Control plane is unavailable');
+        assertJsonContentType(request);
+        assertTrustedOrigin(request, true);
+        const body = await readJsonBody(request, config.maxRequestBytes);
+        assertOnlyKeys(body, ['password', 'confirmPassword']);
+        writeJson(response, 201, await controlPlane.initializeAdminPassword(requiredRawString(body.password, 'password'), requiredRawString(body.confirmPassword, 'confirmPassword')));
+        return;
+    }
+    if (url.pathname === '/v1/admin/auth/status' && request.method === 'GET') {
+        const id = cookieValue(request, ADMIN_COOKIE);
+        writeJson(response, 200, {
+            authenticated: Boolean(id && adminSessions.has(id)),
+            adminSetupRequired: needsAdminSetup(config, controlPlane)
+        });
+        return;
+    }
+    if (url.pathname === '/v1/admin/auth/login' && request.method === 'POST') {
+        if (!controlPlane)
+            throw new RequestError(404, 'Control plane is unavailable');
+        if (needsAdminSetup(config, controlPlane)) {
+            throw new RequestError(428, 'Console setup is required');
+        }
+        assertJsonContentType(request);
+        assertTrustedOrigin(request, true);
+        const rateKey = remoteKey(request);
+        loginLimiter.assertAllowed(rateKey);
+        const body = await readJsonBody(request, config.maxRequestBytes);
+        assertOnlyKeys(body, ['password']);
+        const password = requiredRawString(body.password, 'password');
+        if (!(await controlPlane.verifyAdminPassword(password))) {
+            loginLimiter.failure(rateKey);
+            throw new RequestError(401, 'Invalid Console Password');
+        }
+        loginLimiter.success(rateKey);
+        const sessionId = adminSessions.create();
+        response.setHeader('Set-Cookie', adminCookie(sessionId, config.adminSessionTtlMs || 12 * 60 * 60 * 1000, config));
+        writeJson(response, 200, { authenticated: true });
         return;
     }
-    authenticate(request, config.authToken);
+    if (url.pathname === '/v1/admin/auth/logout' && request.method === 'POST') {
+        assertTrustedOrigin(request, true);
+        const id = cookieValue(request, ADMIN_COOKIE);
+        if (id)
+            adminSessions.delete(id);
+        response.setHeader('Set-Cookie', clearAdminCookie(config));
+        writeJson(response, 200, { authenticated: false });
+        return;
+    }
+    if (!isInitialized(config, controlPlane)) {
+        throw new RequestError(428, 'Gateway setup is required');
+    }
+    if (url.pathname.startsWith('/v1/admin/')) {
+        if (!controlPlane)
+            throw new RequestError(404, 'Control plane is unavailable');
+        authenticateAdmin(request, adminSessions);
+        if (isMutating(request.method))
+            assertTrustedOrigin(request, true);
+        await handleAdminRoute(context, url);
+        return;
+    }
+    const principal = authenticateApiKey(request, config, controlPlane, apiLimiter);
     if (url.pathname === '/v1/agents' && request.method === 'GET') {
-        writeJson(response, 200, { agents: await sessions.listAgents() });
+        const ids = principal.scope.allAgents
+            ? undefined
+            : new Set(principal.scope.agentIds);
+        writeJson(response, 200, {
+            agents: await sessions.listAgents(ids, url.searchParams.get('refresh') === '1')
+        });
         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');
-        const workspace = requiredString(body.workspace, 'workspace');
-        writeJson(response, 201, await sessions.create(agentId, workspace));
+        assertAgentScope(principal, agentId);
+        writeJson(response, 201, await materializeSessionArtifacts(await sessions.create(agentId, optionalString(body.workspace), principal.id), artifactStore));
+        return;
+    }
+    const filesMatch = url.pathname.match(/^\/v1\/sessions\/([^/]+)\/files(?:\/(content|publish))?$/);
+    if (filesMatch) {
+        const sessionId = decodePathSegment(filesMatch[1]);
+        const session = ownedSession(sessions, sessionId, principal);
+        const root = await workspaceFiles.sessionRoot(session.workspace);
+        const action = filesMatch[2];
+        if (!action && request.method === 'GET') {
+            writeJson(response, 200, await workspaceFiles.list(root, url.searchParams.get('path') || ''));
+            return;
+        }
+        if (action === 'content' && request.method === 'GET') {
+            const file = await workspaceFiles.open(root, requiredQuery(url, 'path'));
+            await streamDownload(response, file.handle, file.name, file.size, mediaTypeForName(file.name));
+            return;
+        }
+        if (action === 'publish' && request.method === 'POST') {
+            assertJsonContentType(request);
+            const body = await readJsonBody(request, config.maxRequestBytes);
+            assertOnlyKeys(body, ['paths']);
+            const paths = requiredStringArray(body.paths, 'paths');
+            if (paths.length > 32)
+                throw new RequestError(400, 'paths must contain at most 32 values');
+            const result = await publishWorkspaceFiles(workspaceFiles, artifactStore, root, paths);
+            writeJson(response, result.errors.length ? 207 : 201, result);
+            return;
+        }
+        throw new RequestError(405, 'Method not allowed');
+    }
+    const attachmentMatch = url.pathname.match(/^\/v1\/sessions\/([^/]+)\/attachments$/);
+    if (attachmentMatch && request.method === 'POST') {
+        const sessionId = decodeURIComponent(attachmentMatch[1]);
+        const session = sessions.get(sessionId);
+        if (!sessions.owns(sessionId, principal.id)) {
+            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));
         return;
     }
     const match = url.pathname.match(/^\/v1\/sessions\/([^/]+)(?:\/(message|cancel|events))?$/);
@@ -43,33 +231,276 @@ async function handleRequest(config, sessions, request, response) {
         throw new RequestError(404, 'Route not found');
     const sessionId = decodeURIComponent(match[1]);
     const action = match[2];
+    const session = sessions.get(sessionId);
+    if (!sessions.owns(sessionId, principal.id)) {
+        throw new RequestError(404, 'Session not found');
+    }
+    assertAgentScope(principal, session.agentId);
     if (!action && request.method === 'GET') {
-        writeJson(response, 200, sessions.get(sessionId));
+        writeJson(response, 200, await materializeSessionArtifacts(session, artifactStore));
         return;
     }
     if (action === 'message' && request.method === 'POST') {
+        assertJsonContentType(request);
         const body = await readJsonBody(request, config.maxRequestBytes);
-        assertOnlyKeys(body, ['message']);
-        writeJson(response, 202, await sessions.message(sessionId, requiredString(body.message, 'message')));
+        assertOnlyKeys(body, ['message', 'attachments']);
+        writeJson(response, 202, await materializeSessionArtifacts(await sessions.message(sessionId, requiredMessage(body.message), optionalAttachmentIds(body.attachments)), artifactStore));
         return;
     }
     if (action === 'cancel' && request.method === 'POST') {
-        if (Number(request.headers['content-length'] || 0) > 0) {
-            const body = await readJsonBody(request, config.maxRequestBytes);
-            assertOnlyKeys(body, []);
-        }
-        writeJson(response, 200, await sessions.cancel(sessionId));
+        await assertEmptyJsonBody(request, config.maxRequestBytes);
+        writeJson(response, 200, await materializeSessionArtifacts(await sessions.cancel(sessionId), artifactStore));
         return;
     }
     if (action === 'events' && request.method === 'GET') {
-        streamEvents(request, response, sessions, sessionId, url.searchParams.get('after') ||
-            stringHeader(request.headers['last-event-id']));
+        if (!context.acquireSse()) {
+            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);
         return;
     }
     throw new RequestError(405, 'Method not allowed');
 }
-function streamEvents(request, response, sessions, sessionId, after) {
-    sessions.get(sessionId);
+async function handleAdminRoute(context, url) {
+    const { config, sessions, controlPlane, adminSessions, artifactStore, workspaceFiles, request, response } = context;
+    if (!controlPlane)
+        throw new RequestError(404, 'Control plane is unavailable');
+    if (url.pathname === '/v1/admin/files/roots' && request.method === 'GET') {
+        writeJson(response, 200, { roots: await workspaceFiles.roots() });
+        return;
+    }
+    if (url.pathname === '/v1/admin/files' && request.method === 'GET') {
+        const root = await workspaceFiles.adminRoot(requiredQuery(url, 'root'));
+        writeJson(response, 200, await workspaceFiles.list(root, url.searchParams.get('path') || ''));
+        return;
+    }
+    if (url.pathname === '/v1/admin/files/content') {
+        const root = await workspaceFiles.adminRoot(requiredQuery(url, 'root'));
+        const filePath = requiredQuery(url, 'path');
+        if (request.method === 'GET') {
+            const file = await workspaceFiles.open(root, filePath);
+            await streamDownload(response, file.handle, file.name, file.size, mediaTypeForName(file.name));
+            return;
+        }
+        if (request.method === 'PUT') {
+            const declared = optionalContentLength(request);
+            writeJson(response, 201, await workspaceFiles.write(root, filePath, request, declared));
+            return;
+        }
+        if (request.method === 'DELETE') {
+            await assertEmptyJsonBody(request, config.maxRequestBytes);
+            writeJson(response, 200, await workspaceFiles.remove(root, filePath));
+            return;
+        }
+        throw new RequestError(405, 'Method not allowed');
+    }
+    if (url.pathname === '/v1/admin/files/directory' && request.method === 'POST') {
+        assertJsonContentType(request);
+        const body = await readJsonBody(request, config.maxRequestBytes);
+        assertOnlyKeys(body, ['root', 'path']);
+        const root = await workspaceFiles.adminRoot(requiredString(body.root, 'root'));
+        writeJson(response, 201, await workspaceFiles.createDirectory(root, requiredString(body.path, 'path')));
+        return;
+    }
+    if (url.pathname === '/v1/admin/files/move' && request.method === 'POST') {
+        assertJsonContentType(request);
+        const body = await readJsonBody(request, config.maxRequestBytes);
+        assertOnlyKeys(body, ['root', 'path', 'destination']);
+        const root = await workspaceFiles.adminRoot(requiredString(body.root, 'root'));
+        writeJson(response, 200, await workspaceFiles.move(root, requiredString(body.path, 'path'), requiredString(body.destination, 'destination')));
+        return;
+    }
+    if (url.pathname === '/v1/admin/files/publish' && request.method === 'POST') {
+        assertJsonContentType(request);
+        const body = await readJsonBody(request, config.maxRequestBytes);
+        assertOnlyKeys(body, ['root', 'paths']);
+        const root = await workspaceFiles.adminRoot(requiredString(body.root, 'root'));
+        const paths = requiredStringArray(body.paths, 'paths');
+        if (paths.length > 32)
+            throw new RequestError(400, 'paths must contain at most 32 values');
+        const result = await publishWorkspaceFiles(workspaceFiles, artifactStore, root, paths);
+        writeJson(response, result.errors.length ? 207 : 201, result);
+        return;
+    }
+    if (url.pathname === '/v1/admin/overview' && request.method === 'GET') {
+        const agents = await sessions.listAgents(undefined, url.searchParams.get('refresh') === '1');
+        writeJson(response, 200, { agents, sessions: sessions.count() });
+        return;
+    }
+    if (url.pathname === '/v1/admin/config' && request.method === 'GET') {
+        writeJson(response, 200, controlPlane.snapshot());
+        return;
+    }
+    if (url.pathname === '/v1/admin/agents' && request.method === 'GET') {
+        writeJson(response, 200, {
+            agents: await sessions.listAgents(undefined, url.searchParams.get('refresh') === '1'),
+            config: controlPlane.snapshot().agents
+        });
+        return;
+    }
+    if (url.pathname === '/v1/admin/runs' && request.method === 'GET') {
+        const state = optionalRunState(url.searchParams.get('state'));
+        writeJson(response, 200, sessions.listRuns({
+            agentId: cleanQuery(url.searchParams.get('agentId')),
+            sessionId: cleanQuery(url.searchParams.get('sessionId')),
+            state,
+            query: cleanQuery(url.searchParams.get('q')),
+            limit: boundedLimit(url.searchParams.get('limit'))
+        }));
+        return;
+    }
+    const runMatch = url.pathname.match(/^\/v1\/admin\/runs\/([^/]+)$/);
+    if (runMatch && request.method === 'GET') {
+        writeJson(response, 200, sessions.getRun(decodeURIComponent(runMatch[1])));
+        return;
+    }
+    if (url.pathname === '/v1/admin/config/workspace-roots' && request.method === 'PUT') {
+        assertJsonContentType(request);
+        const body = await readJsonBody(request, config.maxRequestBytes);
+        assertOnlyKeys(body, ['workspaceRoots']);
+        writeJson(response, 200, await controlPlane.putWorkspaceRoots(requiredStringArray(body.workspaceRoots, 'workspaceRoots')));
+        return;
+    }
+    if (url.pathname === '/v1/admin/config/runtime' && request.method === 'PUT') {
+        assertJsonContentType(request);
+        const body = await readJsonBody(request, config.maxRequestBytes);
+        assertOnlyKeys(body, ['sessionTtlMs', 'promptTimeoutMs', 'cleanupIntervalMs']);
+        writeJson(response, 200, await controlPlane.putRuntimeSettings(readRuntimeSettingsUpdate(body)));
+        return;
+    }
+    if (url.pathname === '/v1/admin/password' && request.method === 'PUT') {
+        assertJsonContentType(request);
+        const body = await readJsonBody(request, config.maxRequestBytes);
+        assertOnlyKeys(body, ['currentPassword', 'newPassword', 'confirmPassword']);
+        const result = await controlPlane.changeAdminPassword(requiredRawString(body.currentPassword, 'currentPassword'), requiredRawString(body.newPassword, 'newPassword'), requiredRawString(body.confirmPassword, 'confirmPassword'));
+        adminSessions.clear();
+        response.setHeader('Set-Cookie', clearAdminCookie(config));
+        writeJson(response, 200, result);
+        return;
+    }
+    if (url.pathname === '/v1/admin/api-keys') {
+        if (request.method === 'GET') {
+            writeJson(response, 200, { apiKeys: controlPlane.listApiKeys() });
+            return;
+        }
+        if (request.method === 'POST') {
+            assertJsonContentType(request);
+            const body = await readJsonBody(request, config.maxRequestBytes);
+            assertOnlyKeys(body, ['name', 'scope', 'customSecret']);
+            writeJson(response, 201, await controlPlane.createApiKey(requiredString(body.name, 'name'), readApiKeyScope(body.scope), optionalRawString(body.customSecret, 'customSecret')));
+            return;
+        }
+    }
+    const keyMatch = url.pathname.match(/^\/v1\/admin\/api-keys\/([^/]+)(?:\/(reveal|regenerate))?$/);
+    if (keyMatch) {
+        const id = keyMatch[1];
+        const action = keyMatch[2];
+        if (action === 'reveal' && request.method === 'POST') {
+            await assertEmptyJsonBody(request, config.maxRequestBytes);
+            writeJson(response, 200, controlPlane.revealApiKey(id));
+            return;
+        }
+        if (action === 'regenerate' && request.method === 'POST') {
+            await assertEmptyJsonBody(request, config.maxRequestBytes);
+            writeJson(response, 200, await controlPlane.regenerateApiKey(id));
+            return;
+        }
+        if (!action && request.method === 'PATCH') {
+            assertJsonContentType(request);
+            const body = await readJsonBody(request, config.maxRequestBytes);
+            writeJson(response, 200, await controlPlane.updateApiKey(id, readApiKeyUpdate(body)));
+            return;
+        }
+        if (!action && request.method === 'DELETE') {
+            await assertEmptyJsonBody(request, config.maxRequestBytes);
+            writeJson(response, 200, await controlPlane.deleteApiKey(id));
+            return;
+        }
+        throw new RequestError(405, 'Method not allowed');
+    }
+    const agentMatch = url.pathname.match(/^\/v1\/admin\/agents\/([^/]+)$/);
+    if (agentMatch) {
+        if (request.method === 'PUT') {
+            assertJsonContentType(request);
+            const body = await readJsonBody(request, config.maxRequestBytes);
+            writeJson(response, 200, await controlPlane.putAgent(agentMatch[1], readAgentUpdate(body)));
+            return;
+        }
+        if (request.method === 'DELETE') {
+            await assertEmptyJsonBody(request, config.maxRequestBytes);
+            writeJson(response, 200, await controlPlane.deleteAgent(agentMatch[1]));
+            return;
+        }
+        throw new RequestError(405, 'Method not allowed');
+    }
+    throw new RequestError(404, 'Route not found');
+}
+function readAgentUpdate(body) {
+    assertOnlyKeys(body, [
+        'protocol',
+        'driver',
+        'name',
+        'description',
+        'enabled',
+        'workspace',
+        'permissionPolicy',
+        'permissionTimeoutMs',
+        'agentCardUrl',
+        'agentUrl',
+        'preferredTransport',
+        'authType',
+        'authValue',
+        'authHeaderName',
+        'timeoutMs'
+    ]);
+    return {
+        protocol: requiredString(body.protocol, 'protocol'),
+        driver: optionalString(body.driver),
+        name: optionalString(body.name),
+        description: optionalString(body.description),
+        enabled: optionalBoolean(body.enabled, 'enabled'),
+        workspace: optionalString(body.workspace),
+        permissionPolicy: optionalString(body.permissionPolicy),
+        permissionTimeoutMs: optionalNumber(body.permissionTimeoutMs, 'permissionTimeoutMs'),
+        agentCardUrl: optionalString(body.agentCardUrl),
+        agentUrl: optionalString(body.agentUrl),
+        preferredTransport: optionalString(body.preferredTransport),
+        authType: optionalString(body.authType),
+        authValue: optionalRawString(body.authValue, 'authValue'),
+        authHeaderName: optionalString(body.authHeaderName),
+        timeoutMs: optionalNumber(body.timeoutMs, 'timeoutMs')
+    };
+}
+function readRuntimeSettingsUpdate(body) {
+    return {
+        sessionTtlMs: requiredInteger(body.sessionTtlMs, 'sessionTtlMs'),
+        promptTimeoutMs: requiredInteger(body.promptTimeoutMs, 'promptTimeoutMs'),
+        cleanupIntervalMs: requiredInteger(body.cleanupIntervalMs, 'cleanupIntervalMs')
+    };
+}
+function readApiKeyUpdate(body) {
+    assertOnlyKeys(body, ['name', 'enabled', 'scope']);
+    return {
+        name: optionalString(body.name),
+        enabled: optionalBoolean(body.enabled, 'enabled'),
+        scope: body.scope === undefined ? undefined : readApiKeyScope(body.scope)
+    };
+}
+function readApiKeyScope(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new RequestError(400, 'scope must be an object');
+    }
+    const scope = value;
+    assertOnlyKeys(scope, ['allAgents', 'agentIds']);
+    if (typeof scope.allAgents !== 'boolean') {
+        throw new RequestError(400, 'scope.allAgents must be boolean');
+    }
+    return {
+        allAgents: scope.allAgents,
+        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',
@@ -77,14 +508,22 @@ function streamEvents(request, response, sessions, sessionId, after) {
         'X-Accel-Buffering': 'no'
     });
     response.flushHeaders?.();
-    for (const event of sessions.eventsAfter(sessionId, after)) {
+    for (const event of sessions.eventsAfter(sessionId, after))
         writeEvent(response, event);
-    }
     const unsubscribe = sessions.subscribe(sessionId, (event) => writeEvent(response, event));
-    const heartbeat = setInterval(() => response.write(': heartbeat\n\n'), 15_000);
+    const heartbeat = setInterval(() => {
+        if (!response.destroyed && !response.writableEnded)
+            response.write(': heartbeat\n\n');
+    }, 15_000);
+    heartbeat.unref?.();
+    let closed = false;
     const close = () => {
+        if (closed)
+            return;
+        closed = true;
         clearInterval(heartbeat);
         unsubscribe();
+        release();
     };
     request.once('close', close);
     response.once('close', close);
@@ -96,17 +535,87 @@ function writeEvent(response, event) {
     response.write(`event: ${event.type}\n`);
     response.write(`data: ${JSON.stringify(event)}\n\n`);
 }
-function authenticate(request, expected) {
+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 ')) {
-        throw new RequestError(401, 'Bearer token is required');
+        limiter.failure(rateKey);
+        throw new RequestError(401, 'Bearer API Key is required');
     }
-    const actual = value.slice(7);
-    const left = Buffer.from(actual);
-    const right = Buffer.from(expected);
-    if (left.length !== right.length || !timingSafeEqual(left, right)) {
-        throw new RequestError(401, 'Invalid Bearer token');
+    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']);
@@ -133,8 +642,24 @@ async function readJsonBody(request, maxBytes) {
         return parsed;
     }
     catch (error) {
-        throw new RequestError(400, `Invalid JSON body: ${error instanceof Error ? error.message : String(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);
@@ -149,15 +674,329 @@ function requiredString(value, name) {
         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 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 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 requiredQuery(url, name) {
+    const value = url.searchParams.get(name)?.trim();
+    if (!value)
+        throw new RequestError(400, `${name} is required`);
+    return value;
+}
+function optionalContentLength(request) {
+    const raw = stringHeader(request.headers['content-length']);
+    if (!raw)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RequestError(400, 'Content-Length is invalid');
+    }
+    return value;
+}
+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 safePath(value) {
+    try {
+        return new URL(value || '/', 'http://localhost').pathname;
+    }
+    catch {
+        return '/invalid-url';
+    }
+}
+function decodePathSegment(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        throw new RequestError(400, 'URL path is invalid');
+    }
+}
+function ownedSession(sessions, sessionId, principal) {
+    const session = sessions.get(sessionId);
+    if (!sessions.owns(sessionId, principal.id)) {
+        throw new RequestError(404, 'Session not found');
+    }
+    assertAgentScope(principal, session.agentId);
+    return session;
+}
+async function streamDownload(response, handle, name, size, mediaType) {
+    try {
+        response.writeHead(200, {
+            'Content-Type': mediaType,
+            'Content-Length': size,
+            'Content-Disposition': contentDisposition(name),
+            'Cache-Control': 'no-store',
+            'X-Content-Type-Options': 'nosniff'
+        });
+        await pipeline(handle.createReadStream({ autoClose: false }), response);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+async function publishWorkspaceFiles(workspaceFiles, artifactStore, root, paths) {
+    const files = [];
+    const errors = [];
+    let firstFailure;
+    for (const value of paths) {
+        let file;
+        try {
+            file = await workspaceFiles.publishable(root, value);
+            files.push(await artifactStore.publishHandle(file.handle, file.name));
+        }
+        catch (error) {
+            if (!(error instanceof WorkspaceFileError) && !(error instanceof ArtifactStoreError)) {
+                throw error;
+            }
+            firstFailure ||= { status: error.status, message: error.message };
+            errors.push({ path: value, error: error.message });
+        }
+        finally {
+            await file?.handle.close().catch(() => undefined);
+        }
+    }
+    if (!files.length && firstFailure) {
+        throw new RequestError(firstFailure.status, firstFailure.message);
+    }
+    return { files, errors };
+}
+async function materializeSessionArtifacts(session, store) {
+    const artifacts = await Promise.all(session.artifacts.map(async (artifact, index) => {
+        if (!artifact.bytesBase64)
+            return artifact;
+        let bytes;
+        try {
+            bytes = decodeArtifactBase64(artifact.bytesBase64);
+        }
+        catch (error) {
+            return omittedArtifact(artifact, errorMessage(error));
+        }
+        try {
+            const published = await store.publishBytes(bytes, artifact.filename || artifact.name || `artifact-${artifact.id || randomUUID()}`, artifact.mediaType, `${session.id}:${artifact.id || index}`);
+            return {
+                ...artifact,
+                name: artifact.name || published.name,
+                filename: artifact.filename || published.name,
+                url: published.url,
+                bytesBase64: undefined,
+                metadata: {
+                    ...artifact.metadata,
+                    publishedArtifactId: published.id,
+                    size: published.size,
+                    sha256: published.sha256,
+                    expiresAt: published.expiresAt
+                }
+            };
+        }
+        catch (error) {
+            if (error instanceof ArtifactStoreError && error.status === 413) {
+                return omittedArtifact(artifact, error.message);
+            }
+            throw error;
+        }
+    }));
+    return { ...session, artifacts };
+}
+function decodeArtifactBase64(value) {
+    const normalized = value.replace(/\s/g, '');
+    if (!normalized ||
+        normalized.length % 4 === 1 ||
+        !/^[A-Za-z0-9+/]*={0,2}$/.test(normalized)) {
+        throw new Error('Artifact contains invalid Base64 data');
+    }
+    const bytes = Buffer.from(normalized, 'base64');
+    if (bytes.toString('base64').replace(/=+$/, '') !== normalized.replace(/=+$/, '')) {
+        throw new Error('Artifact contains invalid Base64 data');
+    }
+    return bytes;
+}
+function omittedArtifact(artifact, reason) {
+    return {
+        ...artifact,
+        bytesBase64: undefined,
+        description: [artifact.description, `[binary artifact omitted: ${reason}]`]
+            .filter(Boolean)
+            .join('\n')
+    };
+}
+function errorStatus(error) {
+    if (error instanceof RunNotFoundError)
+        return 404;
+    if (error instanceof SessionNotFoundError)
+        return 404;
+    if (error instanceof SessionRequestError)
+        return error.status;
+    if (error instanceof ControlPlaneError)
+        return error.status;
+    if (error instanceof ArtifactStoreError)
+        return error.status;
+    if (error instanceof WorkspaceFileError)
+        return error.status;
+    if (error instanceof RequestError)
+        return error.status;
+    return 500;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function writeJson(response, status, value) {
     const body = `${JSON.stringify(value)}\n`;
     response.writeHead(status, {
         'Content-Type': 'application/json; charset=utf-8',
         'Content-Length': Buffer.byteLength(body),
-        'Cache-Control': 'no-store'
+        'Cache-Control': 'no-store',
+        'X-Content-Type-Options': 'nosniff'
     });
     response.end(body);
 }
@@ -168,3 +1007,34 @@ class RequestError extends Error {
         this.status = status;
     }
 }
+class FailureRateLimiter {
+    maximum;
+    windowMs;
+    blockMs;
+    entries = new Map();
+    constructor(maximum, windowMs, blockMs) {
+        this.maximum = maximum;
+        this.windowMs = windowMs;
+        this.blockMs = blockMs;
+    }
+    assertAllowed(key) {
+        const entry = this.entries.get(key);
+        if (entry?.blockedUntil && entry.blockedUntil > Date.now()) {
+            throw new RequestError(429, 'Too many authentication attempts');
+        }
+    }
+    failure(key) {
+        const now = Date.now();
+        const previous = this.entries.get(key);
+        const entry = !previous || now - previous.windowStartedAt >= this.windowMs
+            ? { count: 0, windowStartedAt: now, blockedUntil: 0 }
+            : previous;
+        entry.count += 1;
+        if (entry.count >= this.maximum)
+            entry.blockedUntil = now + this.blockMs;
+        this.entries.set(key, entry);
+    }
+    success(key) {
+        this.entries.delete(key);
+    }
+}