@lensagent/core 0.1.0

package/dist/http/server.js

@@ -0,0 +1,1332 @@
+import { applyPurge } from '../runtime/cleanup.js';
+import Fastify from 'fastify';
+import { digest, expectedRevision, integer, jsonValue, optionalText, record, text } from '../core/codec.js';
+import { LensError, fail } from '../core/domain.js';
+import { ExecutorCallError } from '../adapters/executor.js';
+import { resolveReasoningEffort } from '../runtime/profile.js';
+import { componentIdentity } from '../core/identity.js';
+export function createServer(dependencies) {
+    const app = Fastify({ logger: false, bodyLimit: 4 * 1024 * 1024, requestIdHeader: 'x-correlation-id', ajv: { customOptions: { removeAdditional: false } }, ...(dependencies.https === undefined ? {} : { https: dependencies.https }) });
+    const contexts = new WeakMap();
+    const starts = new WeakMap();
+    const specs = [];
+    app.setErrorHandler((error, request, reply) => {
+        const failure = error instanceof LensError ? error
+            : typeof error === 'object' && error !== null && 'validation' in error ? new LensError('SCHEMA_INVALID', 400, 'The request does not match the Route Schema.', schemaDetails(error))
+                : fastifyRequestError(error) ?? new LensError('INTERNAL_ERROR', 500, 'An internal error occurred.');
+        if (failure.code === 'INTERNAL_ERROR') {
+            dependencies.observability.record('http', 'unhandled', 'failed', 0, {
+                error_name: error instanceof Error ? error.name : typeof error,
+                error_code: typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string' ? error.code : null
+            });
+        }
+        void reply.status(failure.status).send({
+            error: { code: failure.code, message: failure.message, retryable: retryableFailure(failure.status), details: failure.details },
+            correlation_id: request.id
+        });
+    });
+    app.addHook('onRequest', async (request) => {
+        starts.set(request, performance.now());
+        if (!request.url.startsWith('/api/v1/'))
+            return;
+        const readiness = dependencies.ready();
+        if (readiness.mode !== 'full')
+            fail('RUNTIME_NOT_READY', 503, 'Lens Core is not ready.', { blockers: readiness.blockers });
+        const ingress = await dependencies.pair.authorize(request.headers, dependencies.config.current.config.tls.enabled ? 'https' : 'http', request.id);
+        const projectId = resolveProjectId(request, dependencies.defaultProjectId);
+        // Name the Project that was not found. An anonymous 404 here is indistinguishable from a
+        // missing Route, and the id is supplied by the caller in a header, so echoing it back is
+        // the fastest way to see a stale or malformed scope.
+        try {
+            dependencies.store.getProject(projectId);
+        }
+        catch (error) {
+            if (error instanceof LensError && error.code === 'PROJECT_NOT_FOUND') {
+                fail('PROJECT_NOT_FOUND', 404, `Project ${projectId} does not exist.`, { project_id: projectId });
+            }
+            throw error;
+        }
+        dependencies.runtime(projectId);
+        rejectReservedFields(request.body);
+        contexts.set(request, { ingress, projectId });
+    });
+    // Every JSON envelope carries the correlation id. 02a-http-route-schemas.md defines
+    // SuccessEnvelope/ErrorEnvelope as `{ data | error, correlation_id }`, and clients use it
+    // to tie a response back to a request. Injected here rather than in each handler so a new
+    // Route cannot forget it: handlers keep returning plain `{ data }`.
+    app.addHook('preSerialization', async (request, _reply, payload) => {
+        if (typeof payload !== 'object' || payload === null || Array.isArray(payload))
+            return payload;
+        const envelope = payload;
+        if (!('data' in envelope) && !('error' in envelope))
+            return payload;
+        const normalized = 'data' in envelope ? { ...envelope, data: wireShape(envelope.data) } : envelope;
+        if (typeof normalized.correlation_id === 'string')
+            return normalized;
+        return { ...normalized, correlation_id: request.id };
+    });
+    app.addHook('onResponse', (request, reply, done) => {
+        const started = starts.get(request) ?? performance.now();
+        // The caller's requested scope is logged on failures. Without it a 404 on a Project-scoped
+        // Route is indistinguishable from a missing Route, and the scope arrives in a header the
+        // Server cannot otherwise account for after the fact.
+        // The scope can arrive as a header or, for the SSE Route, as a query parameter.
+        const headerScope = request.headers['x-lens-project-id'];
+        const queryScope = request.query.project_id;
+        const scope = typeof headerScope === 'string' ? headerScope : typeof queryScope === 'string' ? queryScope : undefined;
+        dependencies.observability.record('http', routePath(request), reply.statusCode < 400 ? 'success' : 'failed', performance.now() - started, {
+            status: reply.statusCode,
+            ...(reply.statusCode >= 400 && typeof scope === 'string' ? { requested_project_id: scope } : {})
+        });
+        done();
+    });
+    const route = (method, path, handler) => {
+        const normalizedMethod = method.toLowerCase();
+        specs.push({ method: normalizedMethod, path });
+        const bodySchema = requestBody(normalizedMethod, path);
+        app.route({ method, url: path, handler, ...(bodySchema === null ? {} : { schema: { body: bodySchema } }) });
+    };
+    const project = (request) => {
+        const context = contexts.get(request);
+        if (context === undefined)
+            fail('TRUSTED_INGRESS_REQUIRED', 500, 'Trusted ingress is missing.');
+        return context.projectId;
+    };
+    const ingressCommand = (request, operation, payload, missingCode) => {
+        const context = contexts.get(request);
+        if (context === undefined)
+            fail('TRUSTED_INGRESS_REQUIRED', 500, 'Trusted ingress is missing.');
+        const key = idempotencyKey(request, missingCode);
+        return {
+            clientId: context.ingress.clientId,
+            key,
+            operation,
+            digest: digest({ version: 'wire-request-v1', client_id: context.ingress.clientId, project_id: context.projectId, operation, payload })
+        };
+    };
+    route('GET', '/health/live', () => ({ data: { status: 'live', instance_epoch: dependencies.events.instanceEpoch, ...componentSummary() } }));
+    route('GET', '/health/ready', (_request, reply) => {
+        const ready = dependencies.ready();
+        // The identity fields repeat in the failure envelope on purpose. A manager distinguishing an
+        // unhealthy Core from a foreign program on the configured port has only this response to work
+        // from, and readiness failure is exactly when it needs the distinction: without the identity
+        // in the 503 the two look alike, and offering a hard kill on that basis can terminate an
+        // unrelated process. `pid` is what the endpoint-owner lookup verifies against.
+        if (ready.mode !== 'full')
+            return reply.status(503).send({ error: { code: 'RUNTIME_NOT_READY', message: 'Lens Core is not ready.', details: { blockers: ready.blockers, ...componentSummary() } } });
+        return {
+            data: {
+                status: 'ready',
+                ...componentSummary(),
+                state_revision: String(dependencies.store.stateRevision()),
+                metadata_revision: String(metadataRevision(dependencies)),
+                config_digest: dependencies.config.current.digest,
+                pair_digest: dependencies.pair.pairDigest,
+                runtime_contract_digest: dependencies.runtime(dependencies.defaultProjectId).contractDigest(),
+                pending_restart: dependencies.config.current.pendingRestart,
+                access_contract: accessContract(dependencies)
+            }
+        };
+    });
+    /**
+     * Graceful stop as a component control path rather than an OS signal, which is what an external
+     * manager is expected to use on both Windows and macOS.
+     *
+     * Deliberately outside `/api/v1/`, so the `onRequest` hook applies neither the readiness gate
+     * nor the pair whitelist: stopping a Core that is unready is the main case, and the caller is a
+     * process manager, not a paired Lens client.
+     *
+     * That combination is also why the remote address is checked. `listen.host` may be a LAN
+     * address, and an unauthenticated route that ends the process would then be a remote kill
+     * switch reachable by anyone on the network.
+     */
+    route('POST', '/health/shutdown', (request, reply) => {
+        requireLoopback(request);
+        // Acknowledge first, tear down after the response has actually left the socket. The manager
+        // observes Stopped by polling, so a dropped acknowledgement is indistinguishable from a Route
+        // that does not exist, and the reported failure would send it to Force Kill instead.
+        reply.raw.once('finish', () => { dependencies.requestShutdown(); });
+        return reply.status(202).send({ data: { status: 'stopping', ...componentSummary() } });
+    });
+    route('GET', '/api/v1/openapi.json', () => openapi(specs));
+    route('GET', '/api/v1/config', () => ({ data: dependencies.config.document(), meta: configMeta(dependencies) }));
+    route('POST', '/api/v1/config/validate', (request) => {
+        const source = text(body(request).content, 'content', 4 * 1024 * 1024);
+        return { data: dependencies.config.validate(source) };
+    });
+    route('PUT', '/api/v1/config', async (request) => {
+        const input = body(request);
+        await dependencies.config.replace(text(input.content, 'content', 4 * 1024 * 1024), text(input.expected_file_digest, 'expected_file_digest'));
+        return { data: dependencies.config.document(), meta: configMeta(dependencies) };
+    });
+    route('GET', '/api/v1/config/options', (request) => ({ data: configOptions(dependencies, project(request)) }));
+    route('GET', '/api/v1/capabilities', (request) => {
+        // 02A: Page<CapabilityCatalogEntry>. A bare array shares no shape with that, so a client
+        // reading `items` got undefined and `items.length` threw during render. The catalog is not
+        // paginated in practice, so the envelope reports the whole set in one page.
+        return { data: wholePage(dependencies.runtime(project(request)).registry.catalog(), dependencies) };
+    });
+    route('GET', '/api/v1/capabilities/:capability_id', (request) => ({ data: dependencies.runtime(project(request)).registry.get(param(request, 'capability_id')) }));
+    route('GET', '/api/v1/projects', (request) => ({ data: dependencies.store.listProjects(page(request), archiveMode(request)) }));
+    route('GET', '/api/v1/projects/browse', async (request, reply) => ({ data: await dependencies.executor.browse(optionalText(query(request).path, 'path') ?? process.cwd(), clientSignal(request, reply)) }));
+    route('POST', '/api/v1/projects/browse/open', async (request, reply) => ({ data: await dependencies.executor.open(paths(body(request).workspace_paths), text(body(request).path, 'path'), clientSignal(request, reply)) }));
+    route('POST', '/api/v1/projects/choose-folder', async (request, reply) => ({ data: await dependencies.executor.chooseFolder(optionalText(body(request).initial_path, 'initial_path'), clientSignal(request, reply)) }));
+    route('POST', '/api/v1/projects', async (request, reply) => {
+        const input = body(request);
+        const workspacePaths = paths(input.workspace_paths ?? input.paths);
+        const validation = await validateWorkspacePaths(dependencies, workspacePaths, input.create_if_missing === true);
+        return reply.status(201).send({ data: dependencies.store.createProject(text(input.name, 'name', 256), validatedWorkspacePaths(validation)) });
+    });
+    route('GET', '/api/v1/projects/:project_id', (request) => ({ data: dependencies.store.projectDetail(param(request, 'project_id')) }));
+    route('PATCH', '/api/v1/projects/:project_id', (request) => ({ data: dependencies.store.updateProject(param(request, 'project_id'), expectedRevision(body(request).expected_revision), text(body(request).name, 'name', 256)) }));
+    route('POST', '/api/v1/projects/:project_id/archive', (request) => ({ data: dependencies.store.archiveProject(param(request, 'project_id'), expectedRevision(body(request).expected_revision), true) }));
+    route('POST', '/api/v1/projects/:project_id/restore', (request) => ({ data: dependencies.store.archiveProject(param(request, 'project_id'), expectedRevision(body(request).expected_revision), false) }));
+    route('GET', '/api/v1/projects/:project_id/workspaces', (request) => ({ data: wholePage(dependencies.store.listWorkspaces(param(request, 'project_id')), dependencies) }));
+    route('POST', '/api/v1/projects/:project_id/workspaces', async (request, reply) => {
+        const projectId = param(request, 'project_id');
+        const input = body(request);
+        const workspacePaths = paths(input.paths);
+        const validation = await validateWorkspacePaths(dependencies, workspacePaths, input.create_if_missing === true);
+        const workspace = dependencies.store.createWorkspace(projectId, text(input.name, 'name', 256), validatedWorkspacePaths(validation), input.is_default === true);
+        dependencies.refreshProject(projectId);
+        return reply.status(201).send({ data: workspace });
+    });
+    route('GET', '/api/v1/projects/:project_id/workspaces/:workspace_id', (request) => ({ data: dependencies.store.getWorkspace(param(request, 'project_id'), param(request, 'workspace_id')) }));
+    route('PATCH', '/api/v1/projects/:project_id/workspaces/:workspace_id', async (request) => {
+        const projectId = param(request, 'project_id');
+        const input = body(request);
+        const workspacePaths = paths(input.paths);
+        const validation = await validateWorkspacePaths(dependencies, workspacePaths, input.create_if_missing === true);
+        const workspace = dependencies.store.updateWorkspace(projectId, param(request, 'workspace_id'), expectedRevision(input.expected_revision), text(input.name, 'name', 256), validatedWorkspacePaths(validation), input.is_default === true);
+        dependencies.refreshProject(projectId);
+        return { data: workspace };
+    });
+    route('DELETE', '/api/v1/projects/:project_id/workspaces/:workspace_id', (request) => {
+        const projectId = param(request, 'project_id');
+        dependencies.store.deleteWorkspace(projectId, param(request, 'workspace_id'), queryRevision(request));
+        dependencies.refreshProject(projectId);
+        return { data: { ok: true } };
+    });
+    route('GET', '/api/v1/projects/:project_id/tasks', (request) => ({ data: dependencies.store.listTasks(param(request, 'project_id'), page(request), query(request).archived === 'all') }));
+    route('POST', '/api/v1/projects/:project_id/tasks', (request, reply) => reply.status(201).send({ data: dependencies.store.createTask(param(request, 'project_id'), text(body(request).title, 'title', 256)) }));
+    route('GET', '/api/v1/tasks', (request) => ({ data: dependencies.store.listAllTasks(project(request), page(request), query(request).archived === 'all') }));
+    route('POST', '/api/v1/tasks', (request, reply) => reply.status(201).send({ data: dependencies.store.createTask(project(request), text(body(request).title, 'title', 256)) }));
+    route('GET', '/api/v1/tasks/:task_id', (request) => ({ data: dependencies.store.taskDetail(project(request), param(request, 'task_id')) }));
+    route('PATCH', '/api/v1/tasks/:task_id', (request) => ({ data: dependencies.store.updateTask(project(request), param(request, 'task_id'), expectedRevision(body(request).expected_revision), text(body(request).title, 'title', 256)) }));
+    route('POST', '/api/v1/tasks/:task_id/archive', (request) => ({ data: dependencies.store.archiveTask(project(request), param(request, 'task_id'), expectedRevision(body(request).expected_revision), true) }));
+    route('POST', '/api/v1/tasks/:task_id/restore', (request) => ({ data: dependencies.store.archiveTask(project(request), param(request, 'task_id'), expectedRevision(body(request).expected_revision), false) }));
+    route('DELETE', '/api/v1/tasks/:task_id', async (request) => {
+        const purged = dependencies.store.deleteTask(project(request), param(request, 'task_id'), queryRevision(request));
+        await applyPurge(purged, dependencies.artifacts, dependencies.executor);
+        return { data: { ok: true } };
+    });
+    route('GET', '/api/v1/tasks/:task_id/sessions', (request) => ({ data: dependencies.store.listSessions(project(request), param(request, 'task_id'), page(request), query(request).archived === 'all') }));
+    route('POST', '/api/v1/tasks/:task_id/sessions', (request, reply) => {
+        const projectId = project(request);
+        const taskId = param(request, 'task_id');
+        const input = body(request);
+        const title = text(input.title, 'title', 256);
+        const defaults = agentDefaults(dependencies, projectId, 'agent', input);
+        const workspaceId = optionalText(input.workspace_id, 'workspace_id') ?? defaultWorkspaceId(dependencies.store, projectId);
+        const initialPrompt = optionalText(input.initial_prompt, 'initial_prompt');
+        const initialMessage = optionalText(input.initial_message, 'initial_message');
+        const payload = {
+            task_id: taskId,
+            title,
+            workspace_id: workspaceId,
+            model: defaults.model,
+            model_reasoning_effort: defaults.modelReasoningEffort,
+            policy_preset: defaults.policyPreset,
+            initial_prompt: initialPrompt ?? null,
+            initial_message: initialMessage ?? null
+        };
+        const command = ingressCommand(request, 'session.create', payload, 'SESSION_REQUEST_KEY_REQUIRED');
+        const created = dependencies.store.createSessionWithAgent(projectId, {
+            taskId,
+            title,
+            workspaceId,
+            agentName: optionalText(input.agent_name, 'agent_name', 256) ?? title,
+            ...defaults,
+            ...(initialPrompt === undefined ? {} : { initialPrompt }),
+            ...(initialMessage === undefined ? {} : { initialMessage }),
+            ingress: command
+        });
+        const agent = jsonObject(created.agent) ? created.agent : null;
+        if (agent !== null && typeof agent.id === 'string' && created.run !== null)
+            dependencies.runtime(projectId).agents.wake(projectId, agent.id);
+        return reply.status(201).send({ data: created });
+    });
+    route('GET', '/api/v1/tasks/:task_id/agents', (request) => ({ data: wholePage(dependencies.store.listAgents(project(request), 'task_id', param(request, 'task_id')), dependencies) }));
+    route('POST', '/api/v1/tasks/:task_id/agents', (request, reply) => reply.status(201).send({ data: createAgent(dependencies, project(request), param(request, 'task_id'), body(request)) }));
+    route('GET', '/api/v1/sessions/:session_id', (request) => ({ data: dependencies.store.sessionDetail(project(request), param(request, 'session_id')) }));
+    route('PATCH', '/api/v1/sessions/:session_id', (request) => ({ data: dependencies.store.updateSession(project(request), param(request, 'session_id'), expectedRevision(body(request).expected_revision), text(body(request).title, 'title', 256)) }));
+    route('POST', '/api/v1/sessions/:session_id/archive', (request) => ({ data: dependencies.store.archiveSession(project(request), param(request, 'session_id'), expectedRevision(body(request).expected_revision), true) }));
+    route('POST', '/api/v1/sessions/:session_id/restore', (request) => ({ data: dependencies.store.archiveSession(project(request), param(request, 'session_id'), expectedRevision(body(request).expected_revision), false) }));
+    route('GET', '/api/v1/sessions/:session_id/snapshot', (request) => ({ data: dependencies.store.sessionSnapshot(project(request), param(request, 'session_id')) }));
+    route('GET', '/api/v1/sessions/:session_id/timeline', (request) => ({ data: dependencies.store.sessionTimeline(project(request), param(request, 'session_id'), page(request)) }));
+    route('GET', '/api/v1/sessions/:session_id/agents', (request) => ({ data: wholePage(dependencies.store.listAgents(project(request), 'session_id', param(request, 'session_id')), dependencies) }));
+    route('POST', '/api/v1/sessions/:session_id/agents', (request, reply) => {
+        const session = dependencies.store.getSession(project(request), param(request, 'session_id'));
+        return reply.status(201).send({ data: createAgent(dependencies, project(request), stringValue(session.task_id), { ...body(request), session_id: session.id }) });
+    });
+    route('GET', '/api/v1/agents/:agent_id', (request) => ({ data: dependencies.store.agentDetail(project(request), param(request, 'agent_id')) }));
+    route('PATCH', '/api/v1/agents/:agent_id', (request) => {
+        const input = body(request);
+        const current = dependencies.store.getAgent(project(request), param(request, 'agent_id'));
+        return { data: dependencies.store.updateAgent(project(request), param(request, 'agent_id'), expectedRevision(input.expected_revision), {
+                name: optionalText(input.name, 'name', 256) ?? stringValue(current.name),
+                model: optionalText(input.model_reference, 'model_reference') ?? stringValue(current.model),
+                modelReasoningEffort: optionalText(input.model_reasoning_effort, 'model_reasoning_effort') ?? stringValue(current.model_reasoning_effort),
+                policyPreset: optionalText(input.policy_preset, 'policy_preset') ?? stringValue(current.policy_preset)
+            }) };
+    });
+    route('POST', '/api/v1/agents/:agent_id/messages', (request, reply) => {
+        const agentId = param(request, 'agent_id');
+        const content = text(body(request).text, 'text');
+        const command = ingressCommand(request, 'message.create', { agent_id: agentId, content }, 'MESSAGE_REQUEST_KEY_REQUIRED');
+        const created = dependencies.store.enqueueMessage(project(request), agentId, content, undefined, command);
+        dependencies.runtime(project(request)).agents.wake(project(request), agentId);
+        return reply.status(202).send({ data: created });
+    });
+    route('POST', '/api/v1/agents/:agent_id/cancel', (request) => {
+        dependencies.runtime(project(request)).agents.cancel(project(request), param(request, 'agent_id'));
+        return { data: { ok: true } };
+    });
+    route('POST', '/api/v1/agents/:agent_id/retry', (request, reply) => {
+        const agentId = param(request, 'agent_id');
+        const run = dependencies.store.retryAgent(project(request), agentId);
+        dependencies.runtime(project(request)).agents.wake(project(request), agentId);
+        return reply.status(202).send({ data: run });
+    });
+    route('GET', '/api/v1/messages/:message_id', (request) => ({ data: dependencies.store.getMessage(project(request), param(request, 'message_id')) }));
+    route('GET', '/api/v1/pending-messages/:pending_message_id', (request) => ({ data: dependencies.store.getPending(project(request), param(request, 'pending_message_id')) }));
+    route('GET', '/api/v1/agents/:agent_id/pending-messages', (request) => ({ data: dependencies.store.listPending(project(request), param(request, 'agent_id'), page(request)) }));
+    route('PATCH', '/api/v1/pending-messages/:pending_message_id', (request) => ({ data: dependencies.store.updatePending(project(request), param(request, 'pending_message_id'), expectedRevision(body(request).expected_revision), text(body(request).text, 'text')) }));
+    route('DELETE', '/api/v1/pending-messages/:pending_message_id', (request) => {
+        dependencies.store.deletePending(project(request), param(request, 'pending_message_id'), queryRevision(request));
+        return { data: { ok: true } };
+    });
+    route('POST', '/api/v1/agents/:agent_id/pending-messages/reorder', (request) => ({ data: dependencies.store.reorderPending(project(request), param(request, 'agent_id'), strings(body(request).ids, 'ids')) }));
+    route('GET', '/api/v1/agents/:agent_id/capabilities', (request) => ({ data: dependencies.store.listCapabilities(project(request), param(request, 'agent_id')) }));
+    route('POST', '/api/v1/agents/:agent_id/capabilities/refresh', (request) => ({ data: refreshCapabilities(dependencies, project(request), param(request, 'agent_id')) }));
+    route('POST', '/api/v1/agents/:agent_id/capabilities/load', (request) => ({ data: dependencies.store.setCapabilityLoaded(project(request), param(request, 'agent_id'), text(body(request).capability_id, 'capability_id'), true) }));
+    route('POST', '/api/v1/agents/:agent_id/capabilities/unload', (request) => ({ data: dependencies.store.setCapabilityLoaded(project(request), param(request, 'agent_id'), text(body(request).capability_id, 'capability_id'), false) }));
+    route('GET', '/api/v1/agents/:agent_id/capabilities/:capability_id', (request) => ({ data: { assignment: dependencies.store.getCapabilityAssignment(project(request), param(request, 'agent_id'), param(request, 'capability_id')), definition: dependencies.runtime(project(request)).registry.get(param(request, 'capability_id')) } }));
+    route('GET', '/api/v1/agents/:agent_id/runs', (request) => ({ data: dependencies.store.listRuns(project(request), param(request, 'agent_id'), page(request)) }));
+    route('GET', '/api/v1/runs/:run_id', (request) => ({ data: dependencies.store.runDetail(project(request), param(request, 'run_id')) }));
+    route('GET', '/api/v1/runs/:run_id/steps', (request) => ({ data: dependencies.store.listSteps(project(request), param(request, 'run_id'), page(request)) }));
+    route('GET', '/api/v1/runs/:run_id/timeline', (request) => ({ data: dependencies.store.runTimeline(project(request), param(request, 'run_id'), page(request)) }));
+    route('GET', '/api/v1/steps/:step_id', (request) => ({ data: dependencies.store.getStep(project(request), param(request, 'step_id')) }));
+    route('GET', '/api/v1/steps/:step_id/output', (request) => ({ data: dependencies.store.stepOutput(project(request), param(request, 'step_id')) }));
+    route('GET', '/api/v1/steps/:step_id/goal', (request) => {
+        const runId = stringValue(dependencies.store.getStep(project(request), param(request, 'step_id')).run_id);
+        return { data: dependencies.store.getRunGoal(project(request), runId) };
+    });
+    route('GET', '/api/v1/agents/:agent_id/model-attempts', (request) => ({ data: dependencies.store.listAttempts(project(request), 'agent_id', param(request, 'agent_id'), page(request)) }));
+    route('GET', '/api/v1/steps/:step_id/model-attempts', (request) => ({ data: dependencies.store.listAttempts(project(request), 'step_id', param(request, 'step_id'), page(request)) }));
+    route('GET', '/api/v1/model-attempts/:attempt_id', (request) => ({ data: dependencies.store.getAttempt(project(request), param(request, 'attempt_id')) }));
+    route('GET', '/api/v1/steps/:step_id/partitions', (request) => ({ data: dependencies.store.listPartitions(project(request), param(request, 'step_id'), page(request)) }));
+    route('GET', '/api/v1/steps/:step_id/calls', (request) => ({ data: dependencies.store.listCalls(project(request), page(request), { stepId: param(request, 'step_id') }) }));
+    route('GET', '/api/v1/agents/:agent_id/context', (request) => ({ data: dependencies.store.listContext(project(request), param(request, 'agent_id'), page(request), pageDirection(request)) }));
+    route('GET', '/api/v1/context/:context_item_id', (request) => ({ data: dependencies.store.getContextItem(project(request), param(request, 'context_item_id')) }));
+    route('PATCH', '/api/v1/context/:context_item_id', (request) => ({ data: dependencies.store.updateContextItem(project(request), param(request, 'context_item_id'), expectedRevision(body(request).expected_revision), text(body(request).body_text, 'body_text')) }));
+    route('GET', '/api/v1/agents/:agent_id/context/override-targets', (request) => ({ data: dependencies.store.contextSource(project(request), param(request, 'agent_id')).items }));
+    route('GET', '/api/v1/agents/:agent_id/context-overrides', (request) => ({ data: dependencies.store.listOverrides(project(request), param(request, 'agent_id'), page(request)) }));
+    route('POST', '/api/v1/context-overrides', (request, reply) => reply.status(201).send({ data: dependencies.store.createOverride(project(request), text(body(request).agent_id, 'agent_id'), text(body(request).target_kind, 'target_kind'), text(body(request).target_id, 'target_id'), text(body(request).instructions, 'instructions')) }));
+    route('GET', '/api/v1/context-overrides/:context_override_id', (request) => ({ data: dependencies.store.getOverride(project(request), param(request, 'context_override_id')) }));
+    route('PUT', '/api/v1/context-overrides/:context_override_id', (request) => ({ data: dependencies.store.updateOverride(project(request), param(request, 'context_override_id'), expectedRevision(body(request).expected_revision), text(body(request).instructions, 'instructions')) }));
+    route('DELETE', '/api/v1/context-overrides/:context_override_id', (request) => {
+        dependencies.store.deleteOverride(project(request), param(request, 'context_override_id'), queryRevision(request));
+        return { data: { ok: true } };
+    });
+    route('POST', '/api/v1/agents/:agent_id/context/visibility', (request) => ({ data: dependencies.store.setContextVisibility(project(request), param(request, 'agent_id'), strings(body(request).turn_group_ids, 'turn_group_ids'), body(request).visible === true, expectedRevision(body(request).expected_context_revision)) }));
+    route('POST', '/api/v1/agents/:agent_id/context/reorder', (request) => ({ data: dependencies.store.reorderContext(project(request), param(request, 'agent_id'), strings(body(request).ordered_turn_group_ids, 'ordered_turn_group_ids'), expectedRevision(body(request).expected_context_revision)) }));
+    route('POST', '/api/v1/agents/:agent_id/context/projection/reset', (request) => ({ data: dependencies.store.resetProjection(project(request), param(request, 'agent_id'), expectedRevision(body(request).expected_context_revision), body(request).stages === undefined ? undefined : strings(body(request).stages, 'stages')) }));
+    route('POST', '/api/v1/agents/:agent_id/context/preview', (request) => {
+        const agent = dependencies.store.getAgent(project(request), param(request, 'agent_id'));
+        const model = dependencies.models.resolve(stringValue(agent.model));
+        const prepared = dependencies.runtime(project(request)).context.prepare(project(request), param(request, 'agent_id'), dependencies.config.current.config, model.contextWindowTokens, model.profile);
+        if (prepared.sourceRevision !== expectedRevision(body(request).expected_context_revision))
+            fail('REVISION_CONFLICT', 409, 'The Context changed before preview.');
+        return { data: prepared };
+    });
+    route('POST', '/api/v1/agents/:agent_id/context/compact', async (request, reply) => ({ data: await dependencies.runtime(project(request)).agents.compact(project(request), param(request, 'agent_id'), expectedRevision(body(request).expected_context_revision), optionalText(body(request).pivot_turn_group_id, 'pivot_turn_group_id'), clientSignal(request, reply)) }));
+    route('POST', '/api/v1/agents/:agent_id/context/fork', (request, reply) => {
+        const projectId = project(request);
+        const source = dependencies.store.getAgent(projectId, param(request, 'agent_id'));
+        const input = body(request);
+        const model = optionalText(input.model_reference, 'model_reference') ?? stringValue(source.model);
+        const effort = optionalText(input.model_reasoning_effort, 'model_reasoning_effort') ?? stringValue(source.model_reasoning_effort);
+        resolveReasoningEffort(dependencies.models.resolve(model).profile, effort);
+        return reply.status(201).send({ data: dependencies.store.createContextFork(projectId, param(request, 'agent_id'), {
+                throughTurnGroupId: text(input.through_turn_group_id, 'through_turn_group_id'),
+                expectedContextRevision: expectedRevision(input.expected_context_revision),
+                name: text(input.name, 'name', 256),
+                model,
+                modelReasoningEffort: effort
+            }) });
+    });
+    route('GET', '/api/v1/agents/:agent_id/context/turn-groups', (request) => ({ data: dependencies.store.listTurnGroups(project(request), param(request, 'agent_id'), page(request)) }));
+    route('GET', '/api/v1/agents/:agent_id/context/projection/decisions', (request) => ({ data: dependencies.store.listProjectionDecisions(project(request), param(request, 'agent_id'), page(request)) }));
+    route('GET', '/api/v1/calls', (request) => ({ data: dependencies.store.listCalls(project(request), page(request), { ...(typeof query(request).state === 'string' ? { state: query(request).state } : {}) }) }));
+    route('POST', '/api/v1/calls', (request, reply) => {
+        const input = body(request);
+        const capabilityId = text(input.capability_id, 'capability_id');
+        const workspaceId = text(input.workspace_id, 'workspace_id');
+        const argumentsValue = jsonValue(input.arguments ?? {});
+        const command = ingressCommand(request, 'call.create', {
+            capability_id: capabilityId,
+            workspace_id: workspaceId,
+            agent_id: typeof input.agent_id === 'string' ? input.agent_id : null,
+            arguments: argumentsValue
+        }, 'DIRECT_REQUEST_KEY_REQUIRED');
+        const replay = dependencies.store.ingressReplay(command);
+        if (replay !== null)
+            return reply.status(202).send({ data: replay });
+        const effect = dependencies.runtime(project(request)).registry.effect(capabilityId, argumentsValue);
+        const call = dependencies.store.createCall(project(request), {
+            workspaceId,
+            ...(typeof input.agent_id === 'string' ? { agentId: input.agent_id } : {}),
+            source: 'user',
+            capabilityId,
+            arguments: argumentsValue,
+            effect,
+            state: 'QUEUED',
+            ingress: command
+        });
+        dependencies.runtime(project(request)).calls.dispatch(project(request), stringValue(call.id));
+        // `createCall` answers the Runtime's flat row; CALL-02 is documented to answer a `CallSummary`.
+        return reply.status(202).send({ data: dependencies.store.callSummary(project(request), stringValue(call.id)) });
+    });
+    route('GET', '/api/v1/calls/:call_id', (request) => ({ data: dependencies.store.callDetail(project(request), param(request, 'call_id')) }));
+    // 02A `CallDecisionResponse` carries a `CallSummary`; the Store and the Runtime both answer the
+    // flat Runtime row, so the projection happens here, at the wire boundary.
+    const decisionResponse = (request, decision) => ({
+        call: dependencies.store.callSummary(project(request), stringValue(decision.call.id)),
+        result: decision.result
+    });
+    for (const decision of ['approve', 'reject', 'cancel']) {
+        route('POST', `/api/v1/calls/:call_id/${decision}`, (request) => {
+            const callId = param(request, 'call_id');
+            const revision = expectedRevision(body(request).expected_revision);
+            if (decision === 'cancel') {
+                return { data: decisionResponse(request, dependencies.runtime(project(request)).calls.cancel(project(request), callId, revision)) };
+            }
+            const result = dependencies.store.decideCall(project(request), callId, decision, revision);
+            if (result.call.state === 'QUEUED')
+                dependencies.runtime(project(request)).calls.dispatch(project(request), callId);
+            return { data: decisionResponse(request, result) };
+        });
+    }
+    route('POST', '/api/v1/calls/:call_id/answer', (request) => {
+        const callId = param(request, 'call_id');
+        const result = dependencies.store.answerCall(project(request), callId, expectedRevision(body(request).expected_revision), jsonValue(body(request).answer));
+        if (result.call.state === 'QUEUED')
+            dependencies.runtime(project(request)).calls.dispatch(project(request), callId);
+        return { data: decisionResponse(request, result) };
+    });
+    route('GET', '/api/v1/results/:result_id', (request) => ({ data: dependencies.store.resultDocument(project(request), param(request, 'result_id')) }));
+    route('POST', '/api/v1/results/:result_id/include', (request, reply) => reply.status(201).send({ data: dependencies.store.includeResult(project(request), param(request, 'result_id'), text(body(request).agent_id, 'agent_id'), expectedRevision(body(request).expected_context_revision)) }));
+    route('GET', '/api/v1/artifacts', (request) => ({ data: dependencies.store.listArtifacts(project(request), page(request)) }));
+    route('GET', '/api/v1/artifacts/:artifact_id/metadata', (request) => ({ data: dependencies.store.getArtifact(project(request), param(request, 'artifact_id')) }));
+    route('GET', '/api/v1/artifacts/:artifact_id', async (request, reply) => {
+        const artifact = dependencies.store.getArtifact(project(request), param(request, 'artifact_id'));
+        const bytes = await dependencies.artifacts.read(artifact);
+        const range = byteRange(request.headers.range, bytes.byteLength);
+        reply.type(stringValue(artifact.media_type))
+            .header('accept-ranges', 'bytes')
+            .header('etag', `"${stringValue(artifact.sha256)}"`);
+        if (range === null)
+            return reply.header('content-length', bytes.byteLength).send(bytes);
+        const content = bytes.subarray(range.start, range.end + 1);
+        return reply.status(206)
+            .header('content-length', content.byteLength)
+            .header('content-range', `bytes ${range.start}-${range.end}/${bytes.byteLength}`)
+            .send(content);
+    });
+    route('POST', '/api/v1/context-items/batch', (request) => ({ data: batchRead(request, 'context_item_ids', (id) => dependencies.store.getContextItem(project(request), id), dependencies) }));
+    route('POST', '/api/v1/messages/batch', (request) => ({ data: batchRead(request, 'message_ids', (id) => dependencies.store.getMessage(project(request), id), dependencies) }));
+    route('POST', '/api/v1/results/batch', (request) => ({ data: batchRead(request, 'result_ids', (id) => dependencies.store.resultDocument(project(request), id), dependencies) }));
+    route('POST', '/api/v1/calls/batch', (request) => ({ data: batchRead(request, 'call_ids', (id) => dependencies.store.callDetail(project(request), id), dependencies) }));
+    // What revert_call would do to these Calls, without doing it. POST because the input is a set of
+    // Call ids; it writes nothing. The answer is a preview: any later write can invalidate it, and the
+    // revert re-checks for itself, so it must not be treated as a promise that the revert will succeed.
+    route('POST', '/api/v1/calls/revert-preview', async (request) => {
+        const projectId = project(request);
+        const callIds = [...new Set(strings(body(request).call_ids, 'call_ids'))];
+        if (callIds.length === 0)
+            fail('INVALID_INPUT', 400, 'call_ids must not be empty.');
+        const workspaceIds = new Set(callIds.map((callId) => {
+            const value = dependencies.store.getCall(projectId, callId).workspace_id;
+            if (typeof value !== 'string')
+                fail('DATABASE_CORRUPT', 503, 'A Call is missing its Workspace.');
+            return value;
+        }));
+        // The Executor keys history by (workspace_id, call_id), so one request covers one Workspace.
+        // Rejecting here turns what would otherwise look like missing history into a clear error.
+        if (workspaceIds.size > 1)
+            fail('INVALID_INPUT', 400, 'call_ids must all belong to one Workspace.');
+        const workspaceId = [...workspaceIds][0] ?? '';
+        const paths = dependencies.store.projectWorkspacePaths(projectId, workspaceId);
+        return { data: await dependencies.executor.describeCallHistory(workspaceId, callIds, paths, false) };
+    });
+    route('POST', '/api/v1/agents/:agent_id/subagents', async (request, reply) => {
+        const projectId = project(request);
+        const parentId = param(request, 'agent_id');
+        const input = body(request);
+        const defaults = agentDefaults(dependencies, projectId, 'subagent', input);
+        const message = optionalText(input.message ?? input.initial_message, 'message');
+        const command = ingressCommand(request, 'subagent.create', {
+            parent_agent_id: parentId,
+            name: text(input.name, 'name', 256),
+            model: defaults.model,
+            model_reasoning_effort: defaults.modelReasoningEffort,
+            policy_preset: defaults.policyPreset,
+            message: message ?? null
+        }, 'IDEMPOTENCY_KEY_INVALID');
+        const forkContext = input.fork_context;
+        if (forkContext !== 'full' && forkContext !== 'compact' && forkContext !== 'none')
+            fail('INVALID_INPUT', 400, 'fork_context is required.');
+        const created = await dependencies.runtime(projectId).agents.createSubagent(projectId, {
+            parentAgentId: parentId,
+            name: text(input.name, 'name', 256),
+            forkContext,
+            model: defaults.model,
+            modelReasoningEffort: defaults.modelReasoningEffort,
+            ...(typeof input.initial_prompt === 'string' ? { initialPrompt: input.initial_prompt } : {}),
+            ...(message === undefined ? {} : { initialMessage: message }),
+            ingress: command
+        }, clientSignal(request, reply));
+        return reply.status(201).send({ data: created });
+    });
+    route('POST', '/api/v1/agents/:agent_id/subagent-messages', (request, reply) => {
+        const projectId = project(request);
+        const parentId = param(request, 'agent_id');
+        const input = body(request);
+        const target = text(input.target_agent_id, 'target_agent_id');
+        const content = text(input.message, 'message');
+        const command = ingressCommand(request, 'subagent.message', { parent_agent_id: parentId, target_agent_id: target, content }, 'IDEMPOTENCY_KEY_INVALID');
+        const result = dependencies.store.enqueueSubagentMessage(projectId, parentId, target, content, command);
+        dependencies.runtime(projectId).agents.wake(projectId, target);
+        return reply.status(202).send({ data: result });
+    });
+    route('POST', '/api/v1/agents/:agent_id/subagent-broadcasts', (request, reply) => {
+        const projectId = project(request);
+        const parentId = param(request, 'agent_id');
+        const content = text(body(request).message, 'message');
+        const command = ingressCommand(request, 'subagent.broadcast', { parent_agent_id: parentId, content }, 'IDEMPOTENCY_KEY_INVALID');
+        const created = dependencies.store.broadcastSubagentMessage(projectId, parentId, content, command);
+        const parent = dependencies.store.getAgent(projectId, parentId);
+        for (const target of dependencies.store.listAgents(projectId, 'task_id', stringValue(parent.task_id))) {
+            if (target.parent_agent_id === parentId)
+                dependencies.runtime(projectId).agents.wake(projectId, stringValue(target.id));
+        }
+        return reply.status(202).send({ data: created });
+    });
+    route('GET', '/api/v1/snapshot', (request) => {
+        const projectId = project(request);
+        const snapshot = dependencies.store.snapshot(projectId, dependencies.config.current.config.snapshot.maxRuntimeEntities);
+        return {
+            data: {
+                instance_epoch: dependencies.events.instanceEpoch,
+                state_revision: String(dependencies.store.stateRevision()),
+                generated_at: new Date().toISOString(),
+                ...runtimeMeta(dependencies, projectId),
+                ...snapshot
+            },
+            meta: runtimeMeta(dependencies, projectId)
+        };
+    });
+    route('GET', '/api/v1/events', async (request, reply) => streamEvents(dependencies, contexts.get(request), reply, request));
+    route('GET', '/api/v1/runtime/diagnostics', () => ({ data: { readiness: dependencies.ready(), config: configMeta(dependencies), state_revision: dependencies.store.stateRevision(), storage: dependencies.store.storageStats() } }));
+    // The three diagnostic windows are documented as RuntimeRecordWindow<T>, not bare arrays.
+    // They are bounded in-process buffers with no replay, so `next_sequence` is the highest
+    // sequence returned and `has_more` reports whether the window filled the requested limit.
+    route('GET', '/api/v1/runtime/logs', (request) => ({ data: recordWindow(dependencies.observability.logs(page(request).limit), page(request).limit) }));
+    route('GET', '/api/v1/runtime/agent-ops', (request) => ({ data: recordWindow(dependencies.observability.agentOps(page(request).limit), page(request).limit) }));
+    route('GET', '/api/v1/runtime/traces', (request) => ({ data: recordWindow(dependencies.observability.traces(page(request).limit), page(request).limit) }));
+    route('GET', '/api/v1/runtime/metrics', (_request, reply) => reply.type('text/plain; version=0.0.4').send(dependencies.observability.metrics()));
+    route('GET', '/api/v1/runtime/operations', (request) => ({ data: { calls: dependencies.store.listCalls(project(request), { limit: dependencies.config.current.config.snapshot.pageSizeMax }, { state: 'RUNNING' }) } }));
+    route('POST', '/api/v1/runtime/maintenance/run', async (request) => {
+        const purged = dependencies.store.purgeArchived(project(request), optionalText(body(request).before, 'before') ?? new Date().toISOString());
+        const files = await applyPurge(purged, dependencies.artifacts, dependencies.executor);
+        // purged_calls is an instruction for applyPurge, not part of the Route response.
+        return { data: { purged_tasks: purged.purged_tasks, orphaned_artifact_paths: purged.orphaned_artifact_paths, files } };
+    });
+    route('GET', '/api/v1/runtime/storage', () => ({ data: dependencies.store.storageStats() }));
+    app.setNotFoundHandler((_request, reply) => reply.status(404).send({ error: { code: 'ROUTE_NOT_FOUND', message: 'The requested Route does not exist.', details: {} } }));
+    return app;
+}
+function createAgent(dependencies, projectId, taskId, input) {
+    const roleName = input.parent_agent_id === undefined ? 'agent' : 'subagent';
+    const defaults = agentDefaults(dependencies, projectId, roleName, input);
+    const sessionId = typeof input.session_id === 'string'
+        ? input.session_id
+        : stringValue(dependencies.store.listSessions(projectId, taskId, { limit: 1 }).items[0]?.id ?? dependencies.store.createSession(projectId, taskId, 'Session').id);
+    return dependencies.store.createAgent(projectId, {
+        taskId,
+        sessionId,
+        workspaceId: optionalText(input.workspace_id, 'workspace_id') ?? defaultWorkspaceId(dependencies.store, projectId),
+        ...(typeof input.parent_agent_id === 'string' ? { parentAgentId: input.parent_agent_id } : {}),
+        name: text(input.name, 'name', 256),
+        ...defaults
+    });
+}
+function agentDefaults(dependencies, projectId, roleName, input) {
+    const role = dependencies.config.current.config.roles[roleName];
+    if (role.model === null || role.modelReasoningEffort === null || role.policyPreset === null) {
+        fail('CONFIG_INVALID', 503, `Role ${roleName} requires model, modelReasoningEffort and policyPreset.`);
+    }
+    const model = typeof input.model_reference === 'string' ? input.model_reference : typeof input.model === 'string' ? input.model : role.model;
+    const modelReasoningEffort = typeof input.model_reasoning_effort === 'string' ? input.model_reasoning_effort : role.modelReasoningEffort;
+    const policyPreset = typeof input.policy_preset === 'string' ? input.policy_preset : role.policyPreset;
+    const preset = dependencies.config.current.config.policyPresets[policyPreset];
+    if (preset === undefined)
+        fail('POLICY_PRESET_MISSING', 409, 'The selected Policy preset does not exist.');
+    const resolved = dependencies.models.resolve(model);
+    resolveReasoningEffort(resolved.profile, modelReasoningEffort);
+    const registry = dependencies.runtime(projectId).registry;
+    const capabilityIds = [...new Set([
+            ...registry.list().filter((definition) => definition.defaultAssignment === 'all_new_agents').map((definition) => definition.id),
+            ...role.capabilities
+        ])];
+    return {
+        model,
+        modelReasoningEffort,
+        policyPreset,
+        capabilities: Object.fromEntries(capabilityIds.map((capabilityId) => {
+            const definition = registry.get(capabilityId);
+            return [capabilityId, preset.capabilities[capabilityId] ?? (definition.effect === 'read_only' ? 'read_only' : 'ask')];
+        })),
+        loadedCapabilities: capabilityIds.filter((capabilityId) => registry.get(capabilityId).loadMode === 'eager')
+    };
+}
+function defaultWorkspaceId(store, projectId) {
+    const workspaces = store.listWorkspaces(projectId);
+    const workspace = workspaces.find((entry) => entry.is_default === true) ?? workspaces[0];
+    if (workspace === undefined)
+        fail('WORKSPACE_NOT_FOUND', 404, 'The Project has no Workspace.');
+    return stringValue(workspace.id);
+}
+function refreshCapabilities(dependencies, projectId, agentId) {
+    const agent = dependencies.store.getAgent(projectId, agentId);
+    const role = agent.parent_agent_id === null ? dependencies.config.current.config.roles.agent : dependencies.config.current.config.roles.subagent;
+    const presetName = stringValue(agent.policy_preset);
+    const policies = dependencies.config.current.config.policyPresets[presetName]?.capabilities ?? {};
+    const current = dependencies.store.listCapabilities(projectId, agentId);
+    const registry = dependencies.runtime(projectId).registry;
+    const capabilityIds = [...new Set([
+            ...registry.list().filter((definition) => definition.defaultAssignment === 'all_new_agents').map((definition) => definition.id),
+            ...role.capabilities
+        ])];
+    const capabilities = Object.fromEntries(capabilityIds.map((capabilityId) => {
+        const definition = registry.get(capabilityId);
+        const existing = current.find((entry) => entry.capability_id === capabilityId);
+        const existingPolicy = typeof existing?.policy === 'string' ? existing.policy : undefined;
+        return [capabilityId, policies[capabilityId] ?? existingPolicy ?? (definition.effect === 'read_only' ? 'read_only' : 'ask')];
+    }));
+    const loaded = Object.keys(capabilities).filter((capabilityId) => {
+        const existing = current.find((entry) => entry.capability_id === capabilityId);
+        return existing?.loaded === true || registry.get(capabilityId).loadMode === 'eager';
+    });
+    return dependencies.store.replaceCapabilities(projectId, agentId, capabilities, loaded);
+}
+async function streamEvents(dependencies, context, reply, request) {
+    if (context === undefined)
+        fail('TRUSTED_INGRESS_REQUIRED', 500, 'Trusted ingress is missing.');
+    const subscription = dependencies.events.subscribe(context.ingress.clientId, context.projectId);
+    reply.hijack();
+    reply.raw.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache, no-transform', connection: 'keep-alive' });
+    const controller = new AbortController();
+    request.raw.once('close', () => controller.abort());
+    let sequence = 0;
+    /**
+     * Writes one SSE frame. `kind` and `occurred_at` go in the JSON body, not only in the
+     * `event:` line: RuntimeEventBase (07 分册) defines them as part of the wire envelope, and
+     * a consumer reading the body cannot dispatch on an event name it never sees. Transport
+     * framing and payload have to agree.
+     */
+    const send = (kind, data) => {
+        sequence += 1;
+        const envelope = {
+            kind,
+            sequence,
+            subscription_id: subscription.id,
+            instance_epoch: dependencies.events.instanceEpoch,
+            occurred_at: new Date().toISOString()
+        };
+        const value = jsonObject(data) ? { ...envelope, ...data, kind, sequence } : { data, ...envelope };
+        reply.raw.write(`id: ${sequence}\nevent: ${kind}\ndata: ${JSON.stringify(value)}\n\n`);
+    };
+    // Handshake and keepalive are notices carrying a `code`, not event kinds of their own.
+    send('runtime.notice', {
+        code: 'subscription.ready',
+        subscription_id: subscription.id,
+        instance_epoch: dependencies.events.instanceEpoch,
+        state_revision: String(dependencies.store.stateRevision()),
+        ...runtimeMeta(dependencies, context.projectId)
+    });
+    const heartbeat = setInterval(() => send('runtime.notice', { code: 'heartbeat', state_revision: String(dependencies.store.stateRevision()), ...runtimeMeta(dependencies, context.projectId) }), dependencies.config.current.config.sse.heartbeatIntervalMs);
+    try {
+        for (;;) {
+            const event = await subscription.next(controller.signal);
+            if (event === null)
+                break;
+            send(event.type, {
+                event_id: event.id,
+                project_id: event.projectId,
+                state_revision: String(event.stateRevision),
+                metadata_revision: String(event.metadataRevision),
+                occurred_at: event.occurredAt,
+                ...(jsonObject(event.payload) ? event.payload : { payload: event.payload })
+            });
+        }
+    }
+    finally {
+        clearInterval(heartbeat);
+        subscription.close();
+        reply.raw.end();
+    }
+}
+function runtimeMeta(dependencies, projectId) {
+    return {
+        metadata_revision: String(metadataRevision(dependencies)),
+        config_digest: dependencies.config.current.digest,
+        pair_digest: dependencies.pair.pairDigest,
+        runtime_contract_digest: dependencies.runtime(projectId).contractDigest(),
+        access_contract: accessContract(dependencies)
+    };
+}
+/**
+ * 02A `AccessContractSummary`. `mode` reports the listener reach, which is what a client needs in
+ * order to explain why a request was refused: the pair file gates every non-health Route, so a
+ * loopback-only listener and a LAN listener refuse different callers.
+ */
+function accessContract(dependencies) {
+    const host = dependencies.config.current.config.listen.host;
+    const loopback = host === '127.0.0.1' || host === '::1' || host === 'localhost';
+    return {
+        provider: 'core',
+        mode: loopback ? 'loopback' : 'lan',
+        compatibility_deviations: []
+    };
+}
+/**
+ * Component identity for the Health Routes: which program answered, which independent software
+ * version it is, which integer protocol versions it speaks and which OS process serves the port.
+ *
+ * All four come from process-wide facts, so they are read here rather than threaded through
+ * `Dependencies`. `protocols` is compared by strict equality against the adjacent component and is
+ * unrelated to `runtime_contract_digest`, which stays a runtime synchronization value.
+ */
+function componentSummary() {
+    const identity = componentIdentity();
+    return {
+        component: identity.component,
+        software_version: identity.softwareVersion,
+        protocols: { ...identity.protocols },
+        pid: process.pid
+    };
+}
+function requireLoopback(request) {
+    // The raw socket address, not `request.ip`: the latter honours forwarded headers under
+    // `trustProxy`, and a caller-supplied header must never be able to satisfy the one check
+    // standing between a LAN listener and process termination.
+    if (!loopbackAddress(request.socket.remoteAddress)) {
+        fail('SHUTDOWN_FORBIDDEN', 403, 'Shutdown may only be requested from the local machine.');
+    }
+}
+function loopbackAddress(address) {
+    // Absent for a non-IP socket. Refusing is the safe answer: the caller cannot be shown to be local.
+    if (address === undefined)
+        return false;
+    // A dual-stack listener reports an IPv4 peer as `::ffff:127.0.0.1`.
+    const normalized = address.startsWith('::ffff:') ? address.slice('::ffff:'.length) : address;
+    return normalized === '::1' || /^127\./.test(normalized);
+}
+/**
+ * CORE-15. 02A defines this as the catalog a client needs to offer model, reasoning-effort,
+ * Runtime Role and Policy choices: `models`, `model_profiles`, `roles`, `policy_presets` and
+ * `effect_scope_descriptions`, plus the digest and catalog revision it was derived from.
+ *
+ * The previous implementation returned three flat string arrays (`providers`, `policy_presets`,
+ * `capabilities`) instead, which shares only a field *name* with the contract and none of its
+ * shape. A client reading `roles` or `models` got `undefined`, and calling `.find` on it threw
+ * during render.
+ *
+ * Every value is derived from the validated config document, so this adds no new source of
+ * truth. Reasoning efforts follow the same rule the config validator applies: a Model Harness
+ * Profile constrains them when one is attached, otherwise the full ladder is allowed.
+ */
+const EFFORT_LADDER = ['none', 'minimal', 'low', 'medium', 'high'];
+const EFFECT_SCOPE_DESCRIPTIONS = {
+    read_only: 'Reads Workspace state without changing it.',
+    workspace_write: 'Creates or modifies files inside the Workspace.',
+    external: 'Reaches a network or another external system.',
+    full: 'Runs an arbitrary command with the account\'s own permissions. Not sandboxed.'
+};
+const POLICY_VALUE_DESCRIPTIONS = {
+    read_only: 'Allowed when the Capability only reads.',
+    workspace_write: 'Allowed to write inside the Workspace.',
+    external: 'Allowed to reach external systems.',
+    ask: 'Requires explicit approval for each Call.',
+    auto_approve: 'Approved automatically after Policy review.',
+    full_access: 'Allowed without Workspace containment.'
+};
+function configOptions(dependencies, projectId) {
+    const config = dependencies.config.current.config;
+    const profiles = config.modelHarnessProfiles ?? {};
+    const efforts = (harnessProfile) => harnessProfile === undefined
+        ? EFFORT_LADDER
+        : profiles[harnessProfile]?.effort.allowed ?? [];
+    const models = Object.entries(config.providers).flatMap(([providerId, provider]) => Object.entries(provider.models).map(([modelId, model]) => {
+        const allowed = efforts(model.harnessProfile);
+        return {
+            model_reference: `${providerId}/${modelId}`,
+            allowed_reasoning_efforts: allowed,
+            default_reasoning_effort: model.harnessProfile === undefined
+                ? 'medium'
+                : profiles[model.harnessProfile]?.effort.default ?? allowed[0] ?? 'medium',
+            harness_profile_id: model.harnessProfile ?? '',
+            harness_profile_version: model.harnessProfile === undefined ? 0 : profiles[model.harnessProfile]?.version ?? 0,
+            context_window_tokens: model.contextWindowTokens,
+            usage_reliable: model.usageReliable ?? null,
+            cache_supported: model.cacheSupported ?? null
+        };
+    }));
+    return {
+        config_digest: dependencies.config.current.digest,
+        catalog_revision: String(metadataRevision(dependencies)),
+        models,
+        model_profiles: Object.entries(profiles).map(([id, profile]) => ({
+            id,
+            version: profile.version,
+            allowed_reasoning_efforts: profile.effort.allowed,
+            default_reasoning_effort: profile.effort.default,
+            reasoning_state_round_trip: profile.semantics.reasoningStateRoundTrip,
+            thinking_continuation: profile.semantics.thinkingContinuation,
+            structured_output: profile.semantics.structuredOutput,
+            cache_enabled_by_default: profile.cache.enabledByDefault
+        })),
+        roles: Object.entries(config.roles).map(([role, value]) => ({
+            role,
+            default_model_reference: value.model ?? '',
+            default_reasoning_effort: value.modelReasoningEffort ?? '',
+            fallback_model_references: value.providerRouting.fallback,
+            policy_preset: value.policyPreset
+        })),
+        policy_presets: Object.entries(config.policyPresets).map(([name, preset]) => ({
+            name,
+            values: preset.capabilities,
+            value_descriptions: POLICY_VALUE_DESCRIPTIONS
+        })),
+        effect_scope_descriptions: EFFECT_SCOPE_DESCRIPTIONS,
+        // Retained alongside the contract fields: existing callers read these, and dropping them
+        // would trade one breakage for another.
+        providers: Object.keys(config.providers),
+        capabilities: dependencies.runtime(projectId).registry.list().map((entry) => entry.id)
+    };
+}
+/**
+ * Fastify's validation output, reduced to the fields a client can act on. Without this a schema
+ * rejection reported only that the request did not match, which gave no way to tell which field
+ * was at fault -- the reason a documented-but-unlisted property looked like a client bug.
+ */
+function schemaDetails(error) {
+    const validation = 'validation' in error ? error.validation : undefined;
+    if (!Array.isArray(validation))
+        return {};
+    return {
+        issues: validation.slice(0, 10).map((issue) => {
+            const entry = typeof issue === 'object' && issue !== null ? issue : {};
+            return {
+                path: typeof entry.instancePath === 'string' && entry.instancePath.length > 0 ? entry.instancePath : '/',
+                rule: typeof entry.keyword === 'string' ? entry.keyword : 'unknown',
+                message: typeof entry.message === 'string' ? entry.message : 'The value is not valid.',
+                ...(typeof entry.params === 'object' && entry.params !== null
+                    ? { property: entry.params.additionalProperty ?? null }
+                    : {})
+            };
+        })
+    };
+}
+/**
+ * Workspace path validation lives in the Executor, which is the only component that may resolve a
+ * path. A refusal is the client's problem (`WORKSPACE_PATH_INVALID`, 422, permanent); only a
+ * failure to answer is the Executor's (`EXECUTOR_UNAVAILABLE`, 503, retryable). Collapsing both
+ * into the latter told the user to retry a path that would always be rejected, and hid the reason.
+ */
+async function validateWorkspacePaths(dependencies, workspacePaths, createIfMissing) {
+    try {
+        return await dependencies.executor.validatePaths(workspacePaths, undefined, createIfMissing);
+    }
+    catch (error) {
+        if (error instanceof ExecutorCallError && error.refused) {
+            fail('WORKSPACE_PATH_INVALID', 422, error.message, { workspace_paths: [...workspacePaths] });
+        }
+        fail('EXECUTOR_UNAVAILABLE', 503, 'Executor could not validate the Workspace paths.');
+    }
+}
+/**
+ * Wraps a collection the Store returns whole in the documented `Page<T>` envelope. These
+ * collections are bounded by their parent (a Project's Workspaces, a Task's Agents), so there is
+ * no cursor to hand out; the shape still has to match, because clients read `items`.
+ */
+function wholePage(items, dependencies) {
+    return {
+        items: items,
+        next_cursor: null,
+        collection_revision: String(dependencies.store.stateRevision())
+    };
+}
+/** 02A `ProjectPageQuery.archive`. An unrecognised value falls back to the documented default. */
+function archiveMode(request) {
+    const value = query(request).archive;
+    return value === 'archived' || value === 'all' ? value : 'active';
+}
+/** 02A `ContextPageQuery.direction`; anything unrecognised falls back to ordinal order. */
+function pageDirection(request) {
+    return query(request).direction === 'backward' ? 'backward' : 'forward';
+}
+/** The documented id field for a batch read Route, which names the entity rather than using `ids`. */
+function batchIdField(path) {
+    if (path === '/api/v1/context-items/batch')
+        return 'context_item_ids';
+    if (path === '/api/v1/messages/batch')
+        return 'message_ids';
+    if (path === '/api/v1/results/batch')
+        return 'result_ids';
+    return 'call_ids';
+}
+/**
+ * 02A `BatchReadResponse<T>`. An id that does not resolve belongs in `missing_ids` rather than
+ * failing the whole batch: the caller asked about a set, and one deleted member should not cost it
+ * the rest.
+ */
+function batchRead(request, field, read, dependencies) {
+    const items = [];
+    const missing = [];
+    for (const id of strings(body(request)[field], field)) {
+        try {
+            items.push(read(id));
+        }
+        catch (error) {
+            if (error instanceof LensError && error.status === 404)
+                missing.push(id);
+            else
+                throw error;
+        }
+    }
+    return {
+        items,
+        missing_ids: missing,
+        state_revision: String(dependencies.store.stateRevision()),
+        generated_at: new Date().toISOString()
+    };
+}
+function recordWindow(items, limit) {
+    return {
+        items: items,
+        next_sequence: items.at(-1)?.sequence ?? null,
+        has_more: items.length >= limit
+    };
+}
+function configMeta(dependencies) {
+    return {
+        config_digest: dependencies.config.current.digest,
+        file_digest: dependencies.config.current.fileDigest,
+        metadata_revision: String(metadataRevision(dependencies)),
+        pending_restart: dependencies.config.current.pendingRestart,
+        error: dependencies.config.current.error
+    };
+}
+function metadataRevision(dependencies) {
+    return dependencies.config.current.metadataRevision + dependencies.pair.metadataRevision;
+}
+function openapi(specs) {
+    const paths = {};
+    for (const spec of specs) {
+        const path = spec.path.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+        const current = paths[path];
+        const operations = {};
+        if (current !== undefined && jsonObject(current))
+            Object.assign(operations, current);
+        const body = requestBody(spec.method, spec.path);
+        paths[path] = {
+            ...operations,
+            [spec.method]: {
+                operationId: operationId(spec.method, spec.path),
+                parameters: parameters(spec.method, spec.path),
+                ...(body === null ? {} : { requestBody: { required: true, content: { 'application/json': { schema: body } } } }),
+                responses: responses(spec.method, spec.path)
+            }
+        };
+    }
+    return {
+        openapi: '3.1.0',
+        info: { title: 'Lens Core API', version: '1.0.0' },
+        paths,
+        components: {
+            schemas: {
+                Success: {
+                    type: 'object',
+                    required: ['data'],
+                    properties: { data: {}, meta: { type: 'object', additionalProperties: true } },
+                    additionalProperties: false
+                },
+                Error: {
+                    type: 'object',
+                    required: ['error'],
+                    properties: {
+                        error: {
+                            type: 'object',
+                            required: ['code', 'message', 'details'],
+                            properties: { code: { type: 'string' }, message: { type: 'string' }, details: {} },
+                            additionalProperties: false
+                        },
+                        request_id: { type: 'string' }
+                    },
+                    additionalProperties: false
+                }
+            }
+        }
+    };
+}
+const stringSchema = { type: 'string', minLength: 1 };
+const revisionSchema = { type: 'integer', minimum: 0 };
+const stringArraySchema = { type: 'array', minItems: 1, items: stringSchema };
+const booleanSchema = { type: 'boolean' };
+function requestBody(method, path) {
+    if (method === 'get' || method === 'delete')
+        return null;
+    // Takes no body, and gets no body schema either, so a bodyless `POST` from a process manager is
+    // not rejected before it reaches the handler.
+    if (path === '/health/shutdown')
+        return null;
+    if (path === '/api/v1/config/validate')
+        return objectSchema({ content: { type: 'string', minLength: 1 } }, ['content']);
+    if (path === '/api/v1/config')
+        return objectSchema({ content: { type: 'string', minLength: 1 }, expected_file_digest: stringSchema }, ['content', 'expected_file_digest']);
+    if (path === '/api/v1/projects')
+        return objectSchema({ name: stringSchema, workspace_paths: stringArraySchema, create_if_missing: booleanSchema }, ['name', 'workspace_paths']);
+    if (path === '/api/v1/projects/:project_id')
+        return objectSchema({ name: stringSchema, expected_revision: revisionSchema }, ['name', 'expected_revision']);
+    if (path === '/api/v1/projects/browse/open')
+        return objectSchema({ workspace_paths: stringArraySchema, path: stringSchema }, ['workspace_paths', 'path']);
+    if (path === '/api/v1/projects/choose-folder')
+        return objectSchema({ initial_path: stringSchema });
+    if (path === '/api/v1/calls/revert-preview')
+        return objectSchema({ call_ids: stringArraySchema }, ['call_ids']);
+    if (/\/projects\/:project_id\/workspaces(?:\/:workspace_id)?$/.test(path))
+        return objectSchema({ name: stringSchema, paths: stringArraySchema, is_default: booleanSchema, create_if_missing: booleanSchema, expected_revision: revisionSchema }, method === 'patch' ? ['name', 'paths', 'expected_revision'] : ['name', 'paths']);
+    if (path.endsWith('/archive') || path.endsWith('/restore'))
+        return objectSchema({ expected_revision: revisionSchema }, ['expected_revision']);
+    if (path === '/api/v1/tasks' || path === '/api/v1/projects/:project_id/tasks')
+        return objectSchema({ title: stringSchema }, ['title']);
+    if (path === '/api/v1/tasks/:task_id')
+        return objectSchema({ title: stringSchema, expected_revision: revisionSchema }, ['title', 'expected_revision']);
+    if (path === '/api/v1/tasks/:task_id/sessions')
+        return objectSchema({
+            title: stringSchema,
+            workspace_id: stringSchema,
+            agent_name: stringSchema,
+            model_reference: stringSchema,
+            model_reasoning_effort: stringSchema,
+            policy_preset: stringSchema,
+            initial_prompt: { type: 'string' },
+            initial_message: { type: 'string' }
+        }, ['title']);
+    if (path === '/api/v1/sessions/:session_id')
+        return objectSchema({ title: stringSchema, expected_revision: revisionSchema }, ['title', 'expected_revision']);
+    if (path === '/api/v1/tasks/:task_id/agents' || path === '/api/v1/sessions/:session_id/agents')
+        return agentBody();
+    if (path === '/api/v1/agents/:agent_id')
+        return objectSchema({ name: stringSchema, model_reference: stringSchema, model_reasoning_effort: stringSchema, policy_preset: stringSchema, expected_revision: revisionSchema }, ['expected_revision']);
+    if (path === '/api/v1/agents/:agent_id/messages')
+        return objectSchema({ text: stringSchema }, ['text']);
+    if (path === '/api/v1/agents/:agent_id/cancel' || path.endsWith('/retry') || path.endsWith('/capabilities/refresh'))
+        return null;
+    if (path === '/api/v1/pending-messages/:pending_message_id')
+        return objectSchema({ text: stringSchema, expected_revision: revisionSchema }, ['text', 'expected_revision']);
+    if (path.endsWith('/pending-messages/reorder'))
+        return objectSchema({ ids: stringArraySchema }, ['ids']);
+    if (path.endsWith('/capabilities/load') || path.endsWith('/capabilities/unload'))
+        return objectSchema({ capability_id: stringSchema }, ['capability_id']);
+    if (path === '/api/v1/context/:context_item_id')
+        return objectSchema({ body_text: stringSchema, expected_revision: revisionSchema }, ['body_text', 'expected_revision']);
+    if (path === '/api/v1/context-overrides')
+        return objectSchema({ agent_id: stringSchema, target_kind: { enum: ['agent', 'message', 'result', 'artifact'] }, target_id: stringSchema, instructions: stringSchema }, ['agent_id', 'target_kind', 'target_id', 'instructions']);
+    if (path === '/api/v1/context-overrides/:context_override_id')
+        return objectSchema({ instructions: stringSchema, expected_revision: revisionSchema }, ['instructions', 'expected_revision']);
+    if (path.endsWith('/context/visibility'))
+        return objectSchema({ turn_group_ids: stringArraySchema, visible: { type: 'boolean' }, expected_context_revision: revisionSchema }, ['turn_group_ids', 'visible', 'expected_context_revision']);
+    if (path.endsWith('/context/reorder'))
+        return objectSchema({ ordered_turn_group_ids: stringArraySchema, expected_context_revision: revisionSchema }, ['ordered_turn_group_ids', 'expected_context_revision']);
+    if (path.endsWith('/context/projection/reset'))
+        return objectSchema({
+            expected_context_revision: revisionSchema,
+            stages: { type: 'array', minItems: 1, uniqueItems: true, items: { type: 'string', enum: ['tool_result_budget', 'snip', 'microcompact', 'context_collapse'] } }
+        }, ['expected_context_revision']);
+    if (path.endsWith('/context/preview'))
+        return objectSchema({ expected_context_revision: revisionSchema }, ['expected_context_revision']);
+    if (path.endsWith('/context/compact'))
+        return objectSchema({ expected_context_revision: revisionSchema, pivot_turn_group_id: stringSchema }, ['expected_context_revision']);
+    if (path.endsWith('/context/fork'))
+        return objectSchema({
+            through_turn_group_id: stringSchema,
+            expected_context_revision: revisionSchema,
+            name: stringSchema,
+            model_reference: stringSchema,
+            model_reasoning_effort: stringSchema
+        }, ['through_turn_group_id', 'expected_context_revision', 'name']);
+    if (path === '/api/v1/calls')
+        return objectSchema({ workspace_id: stringSchema, agent_id: stringSchema, capability_id: stringSchema, arguments: {} }, ['workspace_id', 'capability_id']);
+    if (/\/calls\/:call_id\/(?:approve|reject|cancel)$/.test(path))
+        return objectSchema({ expected_revision: revisionSchema }, ['expected_revision']);
+    if (path.endsWith('/calls/:call_id/answer'))
+        return objectSchema({ expected_revision: revisionSchema, answer: {} }, ['expected_revision', 'answer']);
+    if (path.endsWith('/results/:result_id/include'))
+        return objectSchema({ agent_id: stringSchema, expected_context_revision: revisionSchema }, ['agent_id', 'expected_context_revision']);
+    if (path.endsWith('/batch')) {
+        const field = batchIdField(path);
+        return objectSchema({ [field]: stringArraySchema }, [field]);
+    }
+    if (path.endsWith('/subagents'))
+        return objectSchema({
+            name: stringSchema,
+            fork_context: { type: 'string', enum: ['full', 'compact', 'none'] },
+            model_reference: stringSchema,
+            model_reasoning_effort: stringSchema,
+            initial_prompt: { type: 'string' },
+            initial_message: { type: 'string' },
+            message: { type: 'string' }
+        }, ['name', 'fork_context']);
+    if (path.endsWith('/subagent-messages'))
+        return objectSchema({ target_agent_id: stringSchema, message: stringSchema }, ['target_agent_id', 'message']);
+    if (path.endsWith('/subagent-broadcasts'))
+        return objectSchema({ message: stringSchema }, ['message']);
+    if (path.endsWith('/runtime/maintenance/run'))
+        return objectSchema({ before: stringSchema });
+    return objectSchema({});
+}
+function agentBody() {
+    return objectSchema({
+        name: stringSchema,
+        workspace_id: stringSchema,
+        model_reference: stringSchema,
+        model_reasoning_effort: stringSchema,
+        policy_preset: stringSchema,
+        message: { type: 'string' }
+    }, ['name']);
+}
+function objectSchema(properties, required = []) {
+    return { type: 'object', properties, required, additionalProperties: false };
+}
+function parameters(method, path) {
+    const result = [];
+    for (const match of path.matchAll(/:([a-zA-Z0-9_]+)/g)) {
+        result.push({ name: match[1] ?? '', in: 'path', required: true, schema: stringSchema });
+    }
+    if (path.startsWith('/api/v1/')) {
+        result.push({ name: 'X-Lens-Client-Kind', in: 'header', required: true, schema: { type: 'string', enum: ['native', 'browser'] } }, { name: 'X-Lens-Client-Mac', in: 'header', required: false, schema: stringSchema }, { name: 'X-Lens-Hardware-Id', in: 'header', required: false, schema: stringSchema }, { name: 'X-Lens-Browser-Fingerprint', in: 'header', required: false, schema: stringSchema }, { name: 'X-Lens-Project-Id', in: 'header', required: false, schema: stringSchema });
+    }
+    if (method === 'get' && (/\/tasks$|\/sessions$|\/runs$|\/steps$|\/calls$|\/artifacts$|\/context$|\/timeline$|\/model-attempts$|\/partitions$|\/turn-groups$|\/decisions$|\/logs$|\/traces$|\/agent-ops$/.test(path))) {
+        result.push({ name: 'cursor', in: 'query', required: false, schema: stringSchema }, { name: 'limit', in: 'query', required: false, schema: { type: 'integer', minimum: 1, maximum: 500 } });
+    }
+    if (method === 'delete')
+        result.push({ name: 'expected_revision', in: 'query', required: true, schema: revisionSchema });
+    if (idempotentRoute(method, path))
+        result.push({ name: 'Idempotency-Key', in: 'header', required: true, schema: { type: 'string', pattern: '^[A-Za-z0-9._:-]{1,128}$' } });
+    return result;
+}
+function idempotentRoute(method, path) {
+    return method === 'post' && (path === '/api/v1/tasks/:task_id/sessions'
+        || path === '/api/v1/agents/:agent_id/messages'
+        || path === '/api/v1/calls'
+        || path.endsWith('/subagents')
+        || path.endsWith('/subagent-messages')
+        || path.endsWith('/subagent-broadcasts'));
+}
+function responses(method, path) {
+    if (path === '/api/v1/events')
+        return { '200': { description: 'Server-sent RuntimeEvent stream', content: { 'text/event-stream': { schema: { type: 'string' } } } }, ...errorResponses() };
+    if (path.endsWith('/runtime/metrics'))
+        return { '200': { description: 'Prometheus metrics', content: { 'text/plain': { schema: { type: 'string' } } } }, ...errorResponses() };
+    if (path === '/api/v1/artifacts/:artifact_id') {
+        const content = { 'application/octet-stream': { schema: { type: 'string', contentEncoding: 'binary' } } };
+        return {
+            '200': { description: 'Artifact bytes', content },
+            '206': { description: 'Artifact byte range', content },
+            ...errorResponses()
+        };
+    }
+    const status = method === 'post' && (/\/projects$|\/workspaces$|\/tasks$|\/sessions$|\/agents$|\/subagents$|\/context-overrides$|\/context\/fork$|\/results\/:result_id\/include$/.test(path)) ? '201'
+        : method === 'post' && (path === '/health/shutdown' || path.endsWith('/messages') || path === '/api/v1/calls' || path.endsWith('/subagent-messages') || path.endsWith('/subagent-broadcasts')) ? '202'
+            : '200';
+    return { [status]: { description: 'Success', content: { 'application/json': { schema: { '$ref': '#/components/schemas/Success' } } } }, ...errorResponses() };
+}
+function errorResponses() {
+    const response = { description: 'Error', content: { 'application/json': { schema: { '$ref': '#/components/schemas/Error' } } } };
+    return Object.fromEntries(['400', '403', '404', '409', '413', '416', '422', '428', '500', '502', '503'].map((status) => [status, response]));
+}
+function operationId(method, path) {
+    return `${method}_${path.replace(/^\/api\/v1\//, '').replace(/^\//, '').replace(/[:/.-]+/g, '_') || 'root'}`;
+}
+function fastifyRequestError(error) {
+    if (typeof error !== 'object' || error === null || !('statusCode' in error))
+        return null;
+    const status = error.statusCode;
+    if (typeof status !== 'number' || status < 400 || status >= 500)
+        return null;
+    const code = 'code' in error && typeof error.code === 'string' ? error.code : 'INVALID_REQUEST';
+    return new LensError(code, status, 'The request could not be parsed.');
+}
+function clientSignal(request, reply) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const dispose = () => {
+        request.raw.off('aborted', abort);
+        reply.raw.off('close', abort);
+    };
+    request.raw.once('aborted', abort);
+    reply.raw.once('close', abort);
+    reply.raw.once('finish', dispose);
+    return controller.signal;
+}
+function byteRange(value, size) {
+    if (value === undefined)
+        return null;
+    if (Array.isArray(value))
+        fail('RANGE_NOT_SATISFIABLE', 416, 'Only one byte range is supported.', { size });
+    const match = /^bytes=(\d*)-(\d*)$/.exec(value);
+    if (match === null || (match[1] === '' && match[2] === ''))
+        fail('RANGE_NOT_SATISFIABLE', 416, 'The byte range is invalid.', { size });
+    const first = match[1] === '' ? null : Number(match[1]);
+    const last = match[2] === '' ? null : Number(match[2]);
+    if ((first !== null && !Number.isSafeInteger(first)) || (last !== null && !Number.isSafeInteger(last)) || (first === null && last === 0) || size === 0) {
+        fail('RANGE_NOT_SATISFIABLE', 416, 'The byte range is invalid.', { size });
+    }
+    if (first === null)
+        return { start: Math.max(0, size - (last ?? 0)), end: size - 1 };
+    if (first >= size || (last !== null && last < first))
+        fail('RANGE_NOT_SATISFIABLE', 416, 'The byte range is outside the Artifact.', { size });
+    return { start: first, end: last === null ? size - 1 : Math.min(last, size - 1) };
+}
+function resolveProjectId(request, fallback) {
+    const params = request.params;
+    const queryValue = request.query;
+    const header = request.headers['x-lens-project-id'];
+    const value = params.project_id ?? queryValue.project_id ?? (Array.isArray(header) ? header[0] : header) ?? fallback;
+    return text(value, 'project_id');
+}
+/**
+ * Compatibility layer between the Store's row shape and the documented wire contract.
+ *
+ * 02A defines pagination as `next_cursor`/`collection_revision` and every entity summary as
+ * `<entity>_id` (`ProjectSummary.project_id` and so on). The Store hands back raw SQLite rows,
+ * whose primary key column is `id`, and the page helper emits camelCase, so responses have
+ * never matched those schemas. A client written against the documents reads `project_id`,
+ * gets `undefined`, and sends `X-Lens-Project-Id: undefined` — which 404s every subsequent
+ * request.
+ *
+ * This normalises at the response boundary so all Routes are covered at once. It is a shim:
+ * the durable fix is for each Route to return its documented field names, or for the Store to
+ * map rows to wire records. Both `id` and `<entity>_id` are emitted so existing readers of
+ * `id` keep working.
+ *
+ * Free-form subtrees are left byte-identical. Capability `inputSchema`/`outputSchema` are JSON
+ * Schema, and Call input, Result content, error details and model payloads are caller or model
+ * data; renaming keys inside them would corrupt meaning rather than translate it.
+ */
+const OPAQUE_KEYS = new Set([
+    'inputSchema', 'outputSchema', 'input_schema', 'output_schema',
+    'input', 'content', 'details', 'payload', 'preparation', 'usage', 'metadata',
+    'answer', 'prompt', 'arguments', 'structured', 'document', 'config'
+]);
+// Core mints identifiers as `<entity>_<uuid>`, so the documented field name is derivable from
+// the value itself rather than from a per-Route table.
+const PREFIXED_ID = /^([a-z][a-z0-9]*)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+function wireShape(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => wireShape(entry));
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const source = value;
+    const result = {};
+    for (const [key, entry] of Object.entries(source)) {
+        const name = key === 'nextCursor' ? 'next_cursor' : key === 'collectionRevision' ? 'collection_revision' : key;
+        result[name] = OPAQUE_KEYS.has(key) ? entry : wireShape(entry);
+    }
+    if (typeof source.id === 'string') {
+        const prefix = PREFIXED_ID.exec(source.id)?.[1];
+        if (prefix !== undefined && !(`${prefix}_id` in result))
+            result[`${prefix}_id`] = source.id;
+    }
+    return result;
+}
+// Transient conditions the caller may retry unchanged: not-ready, timeouts, upstream
+// failures and rate limits. A 4xx is the caller's own request and is not retryable.
+function retryableFailure(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+function routePath(request) {
+    return request.routeOptions.url ?? request.url.split('?')[0] ?? 'unknown';
+}
+function idempotencyKey(request, missingCode) {
+    const value = request.headers['idempotency-key'];
+    if (value === undefined)
+        fail(missingCode, 428, 'Idempotency-Key is required.');
+    if (typeof value !== 'string' || !/^[A-Za-z0-9._:-]{1,128}$/.test(value)) {
+        fail('IDEMPOTENCY_KEY_INVALID', 400, 'Idempotency-Key is invalid.');
+    }
+    return value;
+}
+function body(request) {
+    return record(request.body, 'body');
+}
+function query(request) {
+    return request.query;
+}
+function queryRevision(request) {
+    const value = query(request).expected_revision;
+    return expectedRevision(typeof value === 'string' ? Number(value) : value);
+}
+function param(request, name) {
+    return text(request.params[name], name, 256);
+}
+function page(request) {
+    const values = query(request);
+    const cursor = optionalText(values.cursor, 'cursor', 4096);
+    const rawLimit = values.limit === undefined ? 100 : typeof values.limit === 'string' ? Number(values.limit) : values.limit;
+    const limit = Math.min(integer(rawLimit, 'limit', 1), 500);
+    return { ...(cursor === undefined ? {} : { cursor }), limit };
+}
+function paths(value) {
+    return strings(value, 'paths');
+}
+function validatedWorkspacePaths(value) {
+    if (!jsonObject(value))
+        fail('WORKSPACE_INVALID', 400, 'Executor rejected the Workspace paths.');
+    return strings(value.resolved_paths, 'resolved_paths');
+}
+function strings(value, field) {
+    if (!Array.isArray(value) || value.length === 0 || value.some((entry) => typeof entry !== 'string' || entry.length === 0))
+        fail('INVALID_INPUT', 400, `${field} must be a non-empty string array.`);
+    return value;
+}
+function stringValue(value) {
+    if (typeof value !== 'string')
+        fail('DATABASE_CORRUPT', 503, 'A stored string field is invalid.');
+    return value;
+}
+function rejectReservedFields(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return;
+    for (const key of ['source', 'role', 'authority', 'client_id']) {
+        if (key in value)
+            fail('RESERVED_FIELD', 400, `Request field ${key} is reserved.`);
+    }
+}
+function jsonObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}