@migor/agentia 0.9.4 → 0.9.5

package/dist/transport/http.js

@@ -1,13 +1,15 @@
-import { parseTraceparent } from '../core/trace.js';
-import { AsyncRunner, TaskApproveError, TaskStreamError } from './async.js';
-import { parseApproveBody, toHttpBody, toTaskSubmitBody } from './http-shapes.js';
+import { AsyncRunner } from './async.js';
+import { handleRoute } from './http-endpoints.js';
+import { errMessage, sendInternalError, sendJson } from './http-io.js';
 import { isPreAuthRoute, routeRequest } from './http-route.js';
-import { sseWriter } from './sse.js';
-import { TaskInputError, normalizeMessages } from '../engine/spec.js';
 import { zeroClauseOf } from '../core/limits.js';
 /**
  * 鉴权钩子可抛出的异常：显式携带 HTTP 状态与响应体。
  * 钩子抛别的错误一律按 401 处理（设计 F4：与「工具抛错即 is_error」的既有风格一致）。
+ *
+ * 它**刻意留在本文件**（而不是随应答原语去 `http-io.ts`）：`HttpException` 是**宿主契约**
+ * 的一部分（公开导出、鉴权钩子的抛出类型），而 `http-io.ts` 是零内部依赖的原语层 ——
+ * 搬过去会让原语层反向依赖宿主，只为了让 `sendUnauthorized` 能 `instanceof` 一下。
  */
 export class HttpException extends Error {
     status;
@@ -23,86 +25,6 @@ export class HttpException extends Error {
 const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 /** POST /run 并发上限缺省值：32 —— 够单机跑满，又不至于让上游被单宿主打爆 */
 const DEFAULT_MAX_CONCURRENT_RUNS = 32;
-/** 503 建议重试间隔（秒）：同步 run 通常秒级，给 1s 足够错峰 */
-const RETRY_AFTER_SECONDS = '1';
-function sendJson(res, status, body) {
-    const payload = JSON.stringify(body);
-    res.writeHead(status, {
-        'content-type': 'application/json; charset=utf-8',
-        'content-length': Buffer.byteLength(payload),
-    });
-    res.end(payload);
-}
-/** 405 统一响应（方法不符）：文案与其余错误一致用中文，并带 Allow 头。 */
-function methodNotAllowed(res, method, allowed) {
-    res.setHeader('allow', allowed);
-    sendJson(res, 405, { error: `方法 ${method} 不被允许，请用 ${allowed}` });
-}
-/** Prometheus 文本响应（G4）：抓取端按 text/plain; version=0.0.4 解析 */
-function sendPrometheus(res, body) {
-    res.writeHead(200, {
-        'content-type': 'text/plain; version=0.0.4; charset=utf-8',
-        'content-length': Buffer.byteLength(body),
-        'cache-control': 'no-store',
-    });
-    res.end(body);
-}
-/**
- * 读取 body 全文。两道兜底（原实现两者皆无）：
- * - **maxBytes 上限**：超限立即停止累积并 resolve 成哨兵（调用方回 413）——
- *   否则一个未鉴权的大 body 就能把宿主内存打满；
- * - **close 兜底**：客户端中途断开时既不会有 `end` 也不会有 `error`（Node 发 `aborted`/`close`），
- *   Promise 永不 settle → 每个半截请求漏一个 handler 与一份 buffer。
- */
-function readBody(req, maxBytes) {
-    return new Promise((resolve) => {
-        const chunks = [];
-        let size = 0;
-        let done = false;
-        const cleanup = () => {
-            req.off('data', onData);
-            req.off('end', onEnd);
-            req.off('error', onAbort);
-            req.off('close', onAbort);
-        };
-        const finish = (r) => {
-            if (done)
-                return; // end 之后仍会来一次 close
-            done = true;
-            cleanup();
-            resolve(r);
-        };
-        const onData = (c) => {
-            size += c.length;
-            if (size > maxBytes) {
-                finish({ ok: false, reason: 'too-large' });
-                return;
-            }
-            chunks.push(c);
-        };
-        const onEnd = () => finish({ ok: true, raw: Buffer.concat(chunks).toString('utf8') });
-        const onAbort = () => finish({ ok: false, reason: 'aborted' });
-        req.on('data', onData);
-        req.on('end', onEnd);
-        req.on('error', onAbort);
-        req.on('close', onAbort);
-    });
-}
-function errMessage(e) {
-    return e instanceof Error ? e.message : String(e);
-}
-/**
- * 轮询等待条件成立，直到 deadline（`Infinity` = 一直等）。返回是否等到了。
- * 用于 drain 里等同步 run 收尾 —— 事件驱动没有「在飞数变 0」的回调，轮询足够。
- */
-async function waitUntil(cond, deadline) {
-    while (!cond()) {
-        if (Date.now() >= deadline)
-            return false;
-        await new Promise((r) => setTimeout(r, 5));
-    }
-    return true;
-}
 /**
  * 鉴权未通过（B1）。`HttpException` 按其 status/body 回；其它错误回 401 通用文案，
  * 原文只进日志（除非 exposeErrors）。
@@ -110,6 +32,9 @@ async function waitUntil(cond, deadline) {
  * **连接处理**：这里在读到 body 之前就回了响应，请求体没被消费 —— 连接不能复用，
  * 否则残留字节会被当成下一个请求（与 413 同理）。故 `req.complete` 为假时显式
  * `connection: close`，让客户端尽早停止上传（这也正是「省资源」的落点）。
+ *
+ * 留在这里而不是随其余应答原语去 `http-io.ts`：它是**唯一** `instanceof HttpException`
+ * 的落点，而 `HttpException` 是宿主契约（见其类注释）。
  */
 function sendUnauthorized(req, res, e, exposeErrors) {
     // 在读到 body 之前就回了响应：请求体没被消费 → 连接不能复用
@@ -127,21 +52,17 @@ function sendUnauthorized(req, res, e, exposeErrors) {
     console.error('[agentia:http] 鉴权钩子异常:', e);
     sendJson(res, 401, { error: '未通过鉴权' });
 }
-/** 503：停机中不再接单（在读 body 之前就拒，省一次传输） */
-function sendShuttingDown(req, res) {
-    // 同 sendUnauthorized：body 未消费 → 连接不可复用
-    if (!req.complete)
-        res.setHeader('connection', 'close');
-    res.setHeader('retry-after', RETRY_AFTER_SECONDS);
-    sendJson(res, 503, { error: '服务正在优雅停机，不再接受新任务' });
-}
 /**
- * 读单个请求头。Node 对重复头给数组（`traceparent` 语义上只该有一个）——
- * 取第一个即可，多余的忽略。
+ * 轮询等待条件成立，直到 deadline（`Infinity` = 一直等）。返回是否等到了。
+ * 用于 drain 里等同步 run 收尾 —— 事件驱动没有「在飞数变 0」的回调，轮询足够。
  */
-function headerValue(req, name) {
-    const v = req.headers[name];
-    return Array.isArray(v) ? v[0] : v;
+async function waitUntil(cond, deadline) {
+    while (!cond()) {
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((r) => setTimeout(r, 5));
+    }
+    return true;
 }
 export function createHttpHandler(app, opts = {}) {
     const runner = opts.runner ?? new AsyncRunner(app);
@@ -162,29 +83,45 @@ export function createHttpHandler(app, opts = {}) {
         // NaN 会让 `inFlightRuns >= maxConcurrentRuns` 恒 false（闸门静默失效）；
         // 0 / 负数则全部 503 —— 都是配置错误，宁可在构造期响亮失败。
         // Infinity 合法（`Infinity > 0` 成立）：无上限（见选项注释）。
-        throw new Error(`maxConcurrentRuns 必须为正数（Infinity = 无上限），收到 ${opts.maxConcurrentRuns}`);
+        throw new Error(`maxConcurrentRuns 必须为正数（${zeroClauseOf('HttpHandlerOptions.maxConcurrentRuns')}），收到 ${opts.maxConcurrentRuns}`);
     }
     const exposeErrors = opts.exposeErrors ?? false;
     const sseMaxBufferedBytes = opts.sseMaxBufferedBytes;
     const authenticate = opts.authenticate;
-    const metricsProvider = opts.metrics;
+    const metrics = opts.metrics;
     const startedAt = Date.now();
-    let inFlightRuns = 0;
-    let draining = false;
-    /** 仍开着的 SSE 流的收口函数 —— drain 时强制 close，否则长连会把进程吊住 */
-    const openSse = new Set();
-    const sendInternalError = (res, e) => {
-        if (exposeErrors) {
-            sendJson(res, 500, { error: errMessage(e) });
-            return;
+    /**
+     * 宿主级可变状态：**一处创建、按引用共享**（HTTP 路径上的每一方拿到的都是这一个对象）。
+     * 拆成对象而不是三个闭包变量，是为了让它能交给 `http-endpoints.ts` 的端点表 ——
+     * 而「只此一份」这条不变量同时被 `drain()`（读在飞数、置停机态、收 SSE）与
+     * `/healthz`（读同一份）依赖：复制即失效。见 `HttpState`。
+     */
+    const state = {
+        inFlightRuns: 0,
+        draining: false,
+        openSse: new Set(),
+    };
+    /**
+     * 强制收口全部仍开着的 SSE 流，返回**切掉了几条在飞的 run**
+     * （只关旁观者的长连不计 —— 判据在 `OpenSseHandle.cutsRun` 上，别在这里重新推导）。
+     */
+    const closeStreams = () => {
+        let cutRuns = 0;
+        for (const s of [...state.openSse]) {
+            if (s.cutsRun)
+                cutRuns++;
+            s.close();
         }
-        // 细节只进服务端日志，响应里不回内部拓扑
-        console.error('[agentia:http] 请求处理异常:', e);
-        sendJson(res, 500, { error: '内部错误' });
+        return cutRuns;
     };
-    /** 优雅停机（B2）：拒新单 → 等异步任务与在飞同步 run → 强制收口 SSE。 */
+    /**
+     * 优雅停机（B2）：拒新单 → 等异步任务与在飞同步 run → 强制收口 SSE。
+     *
+     * ⚠️ `timeoutMs` 缺省 0 = **对在飞工作**一直等；**活连接（SSE）不享受无限窗口** ——
+     * 没有 deadline 时先把它们收口再等，否则等待没有终点（见下面那段顺序陷阱的注）。
+     */
     const drain = async (drainOpts = {}) => {
-        draining = true; // 先拒新单，再等存量
+        state.draining = true; // 先拒新单，再等存量
         const timeoutMs = drainOpts.timeoutMs ?? 0;
         const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : Number.POSITIVE_INFINITY;
         // 异步任务：排在 waitQueue 里的也一并等（它们的记录在 store 里，超时未跑完则下次启动续跑）。
@@ -202,14 +139,28 @@ export function createHttpHandler(app, opts = {}) {
             const left = deadline - Date.now();
             tasksDrained = left > 0 ? await runner.drain({ timeoutMs: left }) : false;
         }
-        // 同步 /run（含 SSE 流）也在 inFlightRuns 里计数 —— 同样给到 deadline
-        const runsDrained = inFlightRuns === 0 || (await waitUntil(() => inFlightRuns === 0, deadline));
-        // 收口：超时仍挂着的 SSE 流强制关闭。closeSse 会同时 abort 对应 run
-        // （stopReason='aborted'）——只 close 不 abort 的话，res.end() 让 writableEnded
-        // 同步变 true，onClose 守卫永不触发，run 会在后台继续烧 token（实测复现）。
-        for (const close of [...openSse])
-            close();
-        return tasksDrained && runsDrained;
+        // 同步 /run（含 SSE 流）也在 inFlightRuns 里计数 —— 同样给到 deadline。
+        //
+        // ⚠️ 顺序陷阱（2026-09-28 修）：SSE 的**强制收口必须先于这次等待**地做出判断。
+        // 此前收口排在等待**之后** ⇒ 若某条 SSE 的 run 自己不结束（客户端不断线 + 长跑），
+        // `waitUntil(..., Infinity)`（`timeoutMs` 缺省 0 = 一直等）永不返回，而**唯一**能结束
+        // 它的机制（收口 = 关流 + abort 对应 run）排在等待后面 ⇒ 死锁：`drain()` 既不返回也不报
+        // false，SIGTERM 的容器只能在宽限期后被强杀（正是本函数上面那段注释要避免的事）。
+        //
+        // 为什么只在「无 deadline」时提前：**「一直等」承诺的是「等在飞工作自己收尾」**，而活连接
+        // （SSE）没有「自己收尾」的义务，不该给它无限窗口。有 deadline 时保持既有优雅：先给流到
+        // deadline 的窗口自己收尾，到点再硬收（那条路径行为逐字不变）。
+        const unbounded = deadline === Number.POSITIVE_INFINITY;
+        const cutEarly = unbounded ? closeStreams() : 0;
+        const runsDrained = state.inFlightRuns === 0 || (await waitUntil(() => state.inFlightRuns === 0, deadline));
+        // 收口：仍挂着的 SSE 流强制关闭。closeSse 会同时 abort 对应 run（stopReason='aborted'）
+        // ——只 close 不 abort 的话，res.end() 让 writableEnded 同步变 true，onClose 守卫永不触发，
+        // run 会在后台继续烧 token（实测复现）。
+        closeStreams();
+        // ⚠️ 返回值如实分两种收口（`OpenSseHandle.cutsRun`）：**切过在飞的 run** ⇒ 不算排空干净
+        // （工作是被 abort 收尾的，回 true 等于把「切了」说成「等干净了」）；只关掉旁观者的长连
+        // （`/tasks/<id>/stream`）⇒ 不损失任何工作，不参与这个判断（记成 false 是另一种说错话）。
+        return tasksDrained && runsDrained && cutEarly === 0;
     };
     const handler = async (req, res) => {
         const method = req.method ?? 'GET';
@@ -217,33 +168,30 @@ export function createHttpHandler(app, opts = {}) {
         // 路由判定是**纯函数**（见 http-route.ts）：这里只按判定结果去编排。
         // 顺序陷阱写在那边的头注里，最要命的一条：免鉴权组（/healthz、/metrics）
         // 连同它们自己的 405 都在鉴权**之前**回，其余一律**先鉴权再判方法/路径**。
-        const route = routeRequest(pathname, method, metricsProvider !== undefined);
+        const route = routeRequest(pathname, method, metrics !== undefined);
+        // 一个请求一份 ctx：`state` 按引用共享，其余是构造期已解析好的值（不再有 `?? 缺省`）
+        const ctx = {
+            req,
+            res,
+            pathname,
+            method,
+            route,
+            app,
+            runner,
+            state,
+            maxBodyBytes,
+            maxConcurrentRuns,
+            sseMaxBufferedBytes,
+            exposeErrors,
+            startedAt,
+            metrics,
+        };
         try {
-            // 免鉴权组：健康检查（探针带不了凭据）与指标抓取（抓取端在集群内网），停机中也照回
-            // —— 探针要先能问到才有意义。它们的方法不符（405）同样在鉴权之前。
-            if (isPreAuthRoute(route)) {
-                if (route.kind === 'methodNotAllowed') {
-                    methodNotAllowed(res, method, route.allowed);
-                    return;
-                }
-                if (route.kind === 'healthz') {
-                    sendJson(res, 200, {
-                        ok: true,
-                        inFlight: inFlightRuns + runner.inFlight,
-                        uptimeMs: Date.now() - startedAt,
-                        draining,
-                    });
-                    return;
-                }
-                // 指标：与 /healthz 同档（不鉴权、停机中仍可拉 —— 抓取端在集群内网）。
-                // `?.` 只为让类型收窄（这条分支只在配了 metrics 出口时可达），行为与原来一致。
-                sendPrometheus(res, typeof metricsProvider === 'function'
-                    ? metricsProvider()
-                    : (metricsProvider?.render() ?? ''));
-                return;
-            }
-            // 鉴权缝：必须在读 body 之前（未通过即断开，body 一个字节都不收）
-            if (authenticate) {
+            // 鉴权缝：必须在读 body 之前（未通过即断开，body 一个字节都不收）。
+            // 写成**否定条件**（「不是免鉴权组才过闸」）而不是「先 if (免鉴权组) { 一大段应答 }」：
+            // 这样 `handler` 里只剩「谁被豁免」这一处判据可读，而被豁免者**回什么**在端点表里 ——
+            // 豁免名单只有一份真源（`http-route.ts` 的 `isPreAuthRoute`）。
+            if (!isPreAuthRoute(route) && authenticate) {
                 try {
                     await authenticate(req);
                 }
@@ -252,340 +200,14 @@ export function createHttpHandler(app, opts = {}) {
                     return;
                 }
             }
-            // 方法与路径已在 routeRequest 里判完，往下只剩编排
-            switch (route.kind) {
-                case 'methodNotAllowed':
-                    methodNotAllowed(res, method, route.allowed);
-                    return;
-                case 'run': {
-                    if (draining) {
-                        sendShuttingDown(req, res);
-                        return;
-                    }
-                    const input = await parseJsonBody(req, res, maxBodyBytes);
-                    if (input === PARSE_FAILED)
-                        return;
-                    let messages;
-                    try {
-                        messages = normalizeMessages(input);
-                    }
-                    catch (e) {
-                        sendJson(res, 400, { error: errMessage(e) });
-                        return;
-                    }
-                    // 并发闸门：body 已读完（连接可复用），只是暂时不给跑 —— 回 503 让调用方退避重试
-                    if (inFlightRuns >= maxConcurrentRuns) {
-                        res.setHeader('retry-after', RETRY_AFTER_SECONDS);
-                        sendJson(res, 503, {
-                            error: `并发 run 已达上限 ${maxConcurrentRuns}，请稍后重试`,
-                        });
-                        return;
-                    }
-                    inFlightRuns++;
-                    // 客户端中途断开 → 中止本次 run（省 token）。res 'close' 正常结束也会触发，
-                    // 故以 writableEnded 区分：只有响应还没写完才算「断开」。
-                    const runAc = new AbortController();
-                    const onClose = () => {
-                        if (!res.writableEnded)
-                            runAc.abort();
-                    };
-                    res.once('close', onClose);
-                    // 内容协商：`Accept: text/event-stream` → SSE 逐帧下发；否则一元 JSON（旧行为逐字不变）
-                    const wantsSse = String(req.headers.accept ?? '').includes('text/event-stream');
-                    // 入站链路（spec §9.2）：W3C `traceparent` 头 → run 根的 links。
-                    // 畸形/缺头一律静默当作「没有上游上下文」（parseTraceparent 统一判定）——
-                    // 链路是观测行为，不该因为一个坏头把业务请求打成 400。
-                    const traceContext = parseTraceparent(headerValue(req, 'traceparent'));
-                    try {
-                        if (wantsSse) {
-                            const sse = sseWriter(res, {
-                                maxBufferedBytes: sseMaxBufferedBytes,
-                                // 下游积压超限 → 收口并中止本次 run（见 sseWriter 的背压说明）
-                                onBackpressure: () => runAc.abort(),
-                            });
-                            const heartbeat = setInterval(() => sse.comment('ping'), 15_000);
-                            heartbeat.unref?.();
-                            // 登记收口函数：drain 时强制关闭（SSE 是长连，不关会把进程吊住）。
-                            // 收口必须同时 abort 对应 run：sse.close() → res.end() 后 writableEnded 同步
-                            // 变 true，上面的 onClose 守卫（`!writableEnded`）在 close 事件时不成立，
-                            // 只 close 不 abort 会让 run 在后台继续烧 token（与背压收口路径的
-                            // onBackpressure → abort 对齐；run 已正常结束时 abort 是无害 no-op）。
-                            const closeSse = () => {
-                                clearInterval(heartbeat);
-                                runAc.abort();
-                                sse.close();
-                            };
-                            openSse.add(closeSse);
-                            try {
-                                // rethrow:false —— 与 AsyncRunner 对齐：硬失败也以 run.end 下发（status/error 字段）
-                                const out = await app.run(messages, {
-                                    rethrow: false,
-                                    signal: runAc.signal,
-                                    onText: (delta) => sse.event('text.delta', { text: delta }),
-                                    // 增量记账出口（F3 当初判「架构代价大、后置」的那半）：既有三帧
-                                    //（text.delta / run.end / error）逐字不变，这里只**追加**一族帧 ——
-                                    // 不认识 `trace.event` 的老客户端行为零变化。
-                                    // 帧名取一族（body 里的 type 区分）而不是每类型一帧：将来加新事件类型时，
-                                    // 老客户端只是漏掉一种 type，而不是漏掉一种**帧名**（后者更隐蔽）。
-                                    onTraceEvent: (e) => sse.event('trace.event', e),
-                                    ...(traceContext !== undefined ? { traceContext } : {}),
-                                });
-                                sse.event('run.end', toHttpBody(out));
-                            }
-                            catch (e) {
-                                // 流已开（200 与头已发出）→ 只能以 error 事件收尾，不能再改 HTTP 状态码
-                                sse.event('error', { message: errMessage(e) });
-                            }
-                            finally {
-                                openSse.delete(closeSse);
-                                closeSse();
-                            }
-                            return;
-                        }
-                        // rethrow:false —— 与 AsyncRunner 对齐：硬失败也以 status/error 字段返回 200
-                        const out = await app.run(messages, {
-                            rethrow: false,
-                            signal: runAc.signal,
-                            ...(traceContext !== undefined ? { traceContext } : {}),
-                        });
-                        sendJson(res, 200, toHttpBody(out));
-                    }
-                    finally {
-                        res.off('close', onClose);
-                        inFlightRuns--;
-                    }
-                    return;
-                }
-                case 'submit': {
-                    // 停机中不再接单（含直接 drain 了 runner 的情况）；GET /tasks/<id> 不受影响
-                    if (draining || runner.isDraining) {
-                        sendShuttingDown(req, res);
-                        return;
-                    }
-                    const body = await parseJsonBody(req, res, maxBodyBytes);
-                    if (body === PARSE_FAILED)
-                        return;
-                    const submitBody = toTaskSubmitBody(body);
-                    if (!submitBody) {
-                        sendJson(res, 400, { error: 'body 需为 { input, idempotencyKey?, options? }' });
-                        return;
-                    }
-                    // 入站链路（spec §9.2）：body 显式给的 `options.traceContext` 优先，否则取
-                    // `traceparent` 头。它随 `spec.options` 落进 TaskRecord —— 所以**跨进程续跑**
-                    // 的那次 run（另一个进程 `resumePending` 接着跑）也带得上，关联不断链。
-                    const submitTrace = parseTraceparent(headerValue(req, 'traceparent'));
-                    let rec;
-                    try {
-                        rec = runner.submit(submitBody.input, {
-                            ...(submitBody.idempotencyKey !== undefined
-                                ? { idempotencyKey: submitBody.idempotencyKey }
-                                : {}),
-                            options: submitBody.options?.traceContext !== undefined
-                                ? submitBody.options
-                                : {
-                                    ...submitBody.options,
-                                    ...(submitTrace !== undefined ? { traceContext: submitTrace } : {}),
-                                },
-                            source: 'http',
-                        });
-                    }
-                    catch (e) {
-                        // `submit` 是同步的：入参校验失败与 store 落库故障从同一个 catch 出去。
-                        // 前者是调用方的错（400 + 原因），后者是服务端的错 —— 必须走与 500 路径同一套
-                        // `exposeErrors` 策略，否则一次磁盘/Redis 故障会被报成「你参数写错了」，
-                        // 并把内部错误消息原样回给调用方（500/401 路径都不这么干）。
-                        if (e instanceof TaskInputError) {
-                            sendJson(res, 400, { error: errMessage(e) });
-                            return;
-                        }
-                        // 上面的停机闸门与 `submit` 之间隔着一次 `await parseJsonBody`：读 body 期间
-                        // drain 可能刚开始，此时 submit 抛「正在优雅停机」。这是 503 而不是 500 ——
-                        // 调用方应该退避重试，跟闸门本身回的是同一句话。
-                        if (runner.isDraining) {
-                            sendShuttingDown(req, res);
-                            return;
-                        }
-                        sendInternalError(res, e);
-                        return;
-                    }
-                    sendJson(res, 202, rec);
-                    return;
-                }
-                // POST /tasks/<id>/approve（HITL）：审批挂起的任务。drain 期间仍允许 ——
-                // 与 GET 轮询同理由：挂起的任务只有人能推进，停机不该连「批准」也拒掉。
-                case 'approve': {
-                    const taskId = route.taskId;
-                    const body = await parseJsonBody(req, res, maxBodyBytes);
-                    if (body === PARSE_FAILED)
-                        return;
-                    const parsed = parseApproveBody(body);
-                    if (!parsed) {
-                        sendJson(res, 400, {
-                            error: 'body 需为 { decisions: { <tool_use_id>: { approved: boolean, reason?: string } }, decidedBy?: string }',
-                        });
-                        return;
-                    }
-                    try {
-                        const rec = await runner.approve(taskId, parsed.decisions, parsed.decidedBy !== undefined ? { decidedBy: parsed.decidedBy } : {});
-                        sendJson(res, 200, rec);
-                    }
-                    catch (e) {
-                        // 404（任务不存在）/ 409（状态不对）是调用方语义；其余按内部错误处理
-                        if (e instanceof TaskApproveError) {
-                            sendJson(res, e.status, { error: errMessage(e) });
-                            return;
-                        }
-                        sendInternalError(res, e);
-                    }
-                    return;
-                }
-                case 'poll': {
-                    const taskId = route.taskId;
-                    const rec = await runner.poll(taskId); // MaybePromise：异步 store 下必须 await
-                    if (!rec) {
-                        sendJson(res, 404, { error: `task 不存在: ${taskId}` });
-                        return;
-                    }
-                    sendJson(res, 200, rec);
-                    return;
-                }
-                case 'taskStream': {
-                    const taskId = route.taskId;
-                    // 先查一次记录：任务不存在要回 **404**，而 SSE 一旦写出响应头状态码就定死 200 了
-                    //（见 sse.ts 的语义约束），所以「存不存在」必须在建流之前问。
-                    const known = await runner.poll(taskId);
-                    if (!known) {
-                        sendJson(res, 404, { error: `task 不存在: ${taskId}` });
-                        return;
-                    }
-                    // 续订锚点：SSE 标准头 `Last-Event-ID` 优先，其次 `?from=`（非 EventSource 的客户端用）
-                    const fromRaw = headerValue(req, 'last-event-id') ??
-                        new URL(req.url ?? '/', 'http://localhost').searchParams.get('from');
-                    const from = fromRaw === null || fromRaw === undefined ? undefined : Number(fromRaw);
-                    let unsubscribe = () => { };
-                    let finished = false;
-                    let heartbeat;
-                    const closeStream = () => {
-                        if (finished)
-                            return;
-                        finished = true;
-                        if (heartbeat)
-                            clearInterval(heartbeat);
-                        unsubscribe();
-                        openSse.delete(closeStream);
-                        sse.close();
-                    };
-                    const sse = sseWriter(res, {
-                        maxBufferedBytes: sseMaxBufferedBytes,
-                        // ⚠️ 背压**不 abort 任务**：这条流的读者是**旁观者**，任务不该因为看的人慢而变慢。
-                        //（对比 /run 的 SSE：那里的下游就是 run 的所有者，背压等于「别继续烧 token 了」。）
-                        onBackpressure: () => closeStream(),
-                    });
-                    heartbeat = setInterval(() => sse.comment('ping'), 15_000);
-                    heartbeat.unref?.();
-                    // 登记收口函数：drain 时强制关闭（SSE 是长连，不关会把进程吊住）
-                    openSse.add(closeStream);
-                    // 客户端断开 ⇒ 退订（不退订订阅者会一直挂在 runner 的表里）
-                    res.once('close', () => {
-                        if (!res.writableEnded)
-                            closeStream();
-                    });
-                    const write = (frame) => {
-                        if (finished)
-                            return;
-                        switch (frame.type) {
-                            case 'trace':
-                                // 帧名一族 + SSE `id:` 给流序号 ⇒ 断线重连带 Last-Event-ID 就能续上
-                                sse.event('trace.event', frame.event, String(frame.index));
-                                return;
-                            case 'truncated':
-                                sse.event('stream.truncated', { droppedBefore: frame.droppedBefore });
-                                return;
-                            case 'unavailable':
-                                sse.event('stream.unavailable', { reason: frame.reason });
-                                return;
-                            case 'closed':
-                                // 流级收尾（任务未终态，见 TaskStreamFrame）：帧先发出去再关连接 ——
-                                // 客户端据此知道「没有更多帧了，去轮询」，而不是对着断线猜
-                                sse.event('stream.closed', { reason: frame.reason });
-                                closeStream();
-                                return;
-                            case 'end':
-                                sse.event('task.end', frame.record);
-                                closeStream();
-                                return;
-                            default: {
-                                // 编译期穷尽性断言：`TaskStreamFrame` 新增成员时这里会编译失败，
-                                // 而不是被静默丢掉 —— 静默丢帧的客户端只会对着流干等，最后靠超时猜。
-                                const _never = frame;
-                                void _never;
-                            }
-                        }
-                    };
-                    try {
-                        const off = await runner.streamTask(taskId, write, from !== undefined ? { from } : {});
-                        // 重放阶段就可能已收口（终态任务）：那时 finished 为真，别再登记退订
-                        if (finished)
-                            off();
-                        else
-                            unsubscribe = off;
-                    }
-                    catch (e) {
-                        if (e instanceof TaskStreamError) {
-                            // 理论上不可达（上面已查过存在性），但保留这条：状态码还没写出去就还能回 404
-                            if (!res.headersSent) {
-                                sendJson(res, e.status, { error: errMessage(e) });
-                            }
-                            else {
-                                sse.event('error', { message: errMessage(e) });
-                                closeStream();
-                            }
-                            return;
-                        }
-                        sse.event('error', { message: errMessage(e) });
-                        closeStream();
-                    }
-                    return;
-                }
-                case 'badTaskId':
-                    // 残缺的 % 转义会抛 URIError —— 是调用方的输入问题（400），不是服务端 500
-                    sendJson(res, 400, { error: 'taskId 不是合法的 URL 编码' });
-                    return;
-                // healthz / metrics 已在上面的免鉴权组里 return 掉，落到这里的只剩 'notFound'。
-                // 编译期穷尽性断言：`HttpRoute` 新增 kind 时这里会编译失败 —— 而不是被静默吞成 404。
-                default: {
-                    const residual = route.kind;
-                    void residual;
-                    sendJson(res, 404, { error: `路径不存在: ${pathname}` });
-                    return;
-                }
-            }
+            // 至此路由已定、鉴权已过 —— 剩下的全是「走到这条路上做什么」，在 http-endpoints.ts
+            await handleRoute(route, ctx);
         }
         catch (e) {
-            sendInternalError(res, e);
+            sendInternalError(res, e, exposeErrors);
         }
     };
     // 把停机控制面挂在 handler 上（不破坏 (req, res) 的调用形状）
     return Object.assign(handler, { drain, runner });
 }
-const PARSE_FAILED = Symbol('parse-failed');
-/** 读取并解析 JSON body；失败时直接回错误响应并返回哨兵（连接已断则无响应可回）。 */
-async function parseJsonBody(req, res, maxBytes) {
-    const body = await readBody(req, maxBytes);
-    if (!body.ok) {
-        if (body.reason === 'too-large') {
-            // body 未读完就回响应：连接不能复用，否则残留字节会被当成下一个请求
-            res.setHeader('connection', 'close');
-            sendJson(res, 413, { error: `请求 body 超过上限 ${maxBytes} 字节` });
-        }
-        return PARSE_FAILED; // aborted：客户端已走，写了也没人收
-    }
-    try {
-        return body.raw ? JSON.parse(body.raw) : undefined;
-    }
-    catch {
-        sendJson(res, 400, { error: '请求 body 不是合法 JSON' });
-        return PARSE_FAILED;
-    }
-}
 //# sourceMappingURL=http.js.map