@migor/agentia 0.7.2 → 0.8.0

package/dist/transport/http-shapes.d.ts

@@ -0,0 +1,57 @@
+import type { Trace, SpanError } from '../core/trace.js';
+import type { RunStatus } from '../core/run.js';
+import type { AgentRunResult, AgentStopReason } from '../engine/types.js';
+import type { RunInvocationOptions } from '../engine/spec.js';
+import type { ApprovalDecisions } from './async.js';
+/**
+ * Agentia —— HTTP 宿主的**出入站形状口径**（transport/http.ts 的拆分第一步）。
+ *
+ * 三条边界在这里定形，别处（`http.ts` 的路由分支）只做编排：
+ *   - 入站 `POST /tasks`：body 是不是 `{ input, … }`（`toTaskSubmitBody`）；
+ *   - 入站 `POST /tasks/<id>/approve`：body 是不是
+ *     `{ decisions: { <id>: { approved, reason? } }, decidedBy? }`（`parseApproveBody`）；
+ *   - 出站：run 产物 → HTTP 响应体（`toHttpBody`，JSON 与 SSE 的 `run.end` **共用同一形状**）。
+ *
+ * 三条都是**纯形状判定**：只读参数、只回值，不碰 req/res、不写响应、不抛异常
+ * （形状不合法一律回 `undefined`，由调用方选状态码 —— 400 还是别的，是路由的语义）。
+ * 判定刻意做窄且**全有或全无**：一处不合法就整条拒掉，不做「能救则救」的部分接受 ——
+ * 半接受的审批体比拒掉更危险（缺哪个 tool_use 的决定，只有调用方知道）。
+ */
+/** POST /run 的响应形态 */
+export interface RunHttpResponse {
+    runId: string;
+    status: RunStatus;
+    stopReason: AgentStopReason;
+    finalText: string;
+    /** 结构化结果（R2 起应用可携带；无则为 undefined，字段在场） */
+    typed: unknown;
+    trace: Trace;
+    error: SpanError | undefined;
+}
+/** POST /tasks 的请求体形态 */
+export interface TaskSubmitBody {
+    input: unknown;
+    idempotencyKey?: string;
+    options?: RunInvocationOptions;
+}
+/** 把 app.run 的产物收成 HTTP 响应体（JSON 与 SSE 的 run.end 共用同一形状） */
+export declare function toHttpBody(out: {
+    run: {
+        runId: string;
+        status: RunStatus;
+    };
+    result: AgentRunResult;
+}): RunHttpResponse;
+/**
+ * `POST /tasks` 的 body 形状闸：必须是**纯对象**（`null` / 数组 / 标量都不算）。
+ * 返回**同一个引用**（不是副本）—— 后续 `runner.submit` 拿到的就是请求里那个对象。
+ */
+export declare function toTaskSubmitBody(body: unknown): TaskSubmitBody | undefined;
+/**
+ * 解析 `POST /tasks/<id>/approve` 的 body；形状不合法返回 undefined（调用方回 400）。
+ * `decisions` 必须是纯对象，每个值是 `{ approved: boolean, reason?: string }`。
+ */
+export declare function parseApproveBody(body: unknown): {
+    decisions: ApprovalDecisions;
+    decidedBy?: string;
+} | undefined;

package/dist/transport/http-shapes.js

@@ -0,0 +1,56 @@
+/** 把 app.run 的产物收成 HTTP 响应体（JSON 与 SSE 的 run.end 共用同一形状） */
+export function toHttpBody(out) {
+    return {
+        runId: out.run.runId,
+        // status 取 **run 状态机**的口径（它才知道 awaiting_approval 不是终态），
+        // 不从 stopReason 反推 —— 两者语义不同，反推会把挂起当成失败
+        status: out.run.status,
+        stopReason: out.result.stopReason,
+        finalText: out.result.finalText,
+        typed: out.result.typed,
+        trace: out.result.trace,
+        error: out.result.error,
+    };
+}
+/**
+ * `POST /tasks` 的 body 形状闸：必须是**纯对象**（`null` / 数组 / 标量都不算）。
+ * 返回**同一个引用**（不是副本）—— 后续 `runner.submit` 拿到的就是请求里那个对象。
+ */
+export function toTaskSubmitBody(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return undefined;
+    return body;
+}
+/**
+ * 解析 `POST /tasks/<id>/approve` 的 body；形状不合法返回 undefined（调用方回 400）。
+ * `decisions` 必须是纯对象，每个值是 `{ approved: boolean, reason?: string }`。
+ */
+export function parseApproveBody(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return undefined;
+    const o = body;
+    if (!o.decisions || typeof o.decisions !== 'object' || Array.isArray(o.decisions)) {
+        return undefined;
+    }
+    if (o.decidedBy !== undefined && typeof o.decidedBy !== 'string')
+        return undefined;
+    const decisions = {};
+    for (const [id, d] of Object.entries(o.decisions)) {
+        if (!d || typeof d !== 'object' || Array.isArray(d))
+            return undefined;
+        const v = d;
+        if (typeof v.approved !== 'boolean')
+            return undefined;
+        if (v.reason !== undefined && typeof v.reason !== 'string')
+            return undefined;
+        decisions[id] = {
+            approved: v.approved,
+            ...(v.reason !== undefined ? { reason: v.reason } : {}),
+        };
+    }
+    return {
+        decisions,
+        ...(o.decidedBy !== undefined ? { decidedBy: o.decidedBy } : {}),
+    };
+}
+//# sourceMappingURL=http-shapes.js.map

package/dist/transport/http-shapes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-shapes.js","sourceRoot":"","sources":["../../src/transport/http-shapes.ts"],"names":[],"mappings":"AAwCA,4DAA4D;AAC5D,MAAM,UAAU,UAAU,CAAC,GAG1B;IACC,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK;QACpB,wDAAwD;QACxD,wCAAwC;QACxC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,MAAM;QACtB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,UAAU;QACjC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS;QAC/B,KAAK,EAAG,GAAG,CAAC,MAA8B,CAAC,KAAK;QAChD,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK;QACvB,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK;KACxB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/E,OAAO,IAAsB,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAa;IAEb,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/E,MAAM,CAAC,GAAG,IAAoD,CAAC;IAC/D,IAAI,CAAC,CAAC,CAAC,SAAS,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;QAClF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACnF,MAAM,SAAS,GAAsB,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;QAClD,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;QACtE,MAAM,CAAC,GAAG,CAA6C,CAAC;QACxD,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACtD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC7E,SAAS,CAAC,EAAE,CAAC,GAAG;YACd,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxD,CAAC;IACJ,CAAC;IACD,OAAO;QACL,SAAS;QACT,GAAG,CAAC,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3E,CAAC;AACJ,CAAC"}

package/dist/transport/http.d.ts

@@ -1,10 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { SpanError, Trace } from '../core/trace.js';
-import type { AgentStopReason } from '../engine/types.js';
 import { AsyncRunner } from './async.js';
 import type { AppCallable } from './async.js';
-import type { RunInvocationOptions } from '../engine/spec.js';
-import type { RunStatus } from '../core/run.js';
 /**
  * Agentia —— HTTP 宿主（spec §6.6：换宿主不换语义，roadmap R3）。
  *
@@ -39,23 +35,11 @@ import type { RunStatus } from '../core/run.js';
  * 在飞同步 run 收尾、强制收口仍开着的 SSE 流；`GET /tasks/<id>` 停机中照常可轮询
  * （否则调用方拿不到在飞任务的结果）。
  */
-/** POST /run 的响应形态 */
-export interface RunHttpResponse {
-    runId: string;
-    status: RunStatus;
-    stopReason: AgentStopReason;
-    finalText: string;
-    /** 结构化结果（R2 起应用可携带；无则为 undefined，字段在场） */
-    typed: unknown;
-    trace: Trace;
-    error: SpanError | undefined;
-}
-/** POST /tasks 的请求体形态 */
-export interface TaskSubmitBody {
-    input: unknown;
-    idempotencyKey?: string;
-    options?: RunInvocationOptions;
-}
+/**
+ * 出入站的形状口径（响应体 / 任务提交体 / 审批体）与它们的类型住在
+ * `./http-shapes.js`；这里转出以保持既有 import 路径不变（公开面名字与位置都未变）。
+ */
+export type { RunHttpResponse, TaskSubmitBody } from './http-shapes.js';
 export interface HttpHandlerOptions {
     /** 异步任务宿主；缺省 new AsyncRunner(app)（InMemoryTaskStore） */
     runner?: AsyncRunner;

package/dist/transport/http.js

@@ -1,5 +1,7 @@
 import { parseTraceparent } from '../core/trace.js';
 import { AsyncRunner, TaskApproveError } from './async.js';
+import { parseApproveBody, toHttpBody, toTaskSubmitBody } from './http-shapes.js';
+import { isPreAuthRoute, routeRequest } from './http-route.js';
 import { sseWriter } from './sse.js';
 import { TaskInputError, normalizeMessages } from '../engine/spec.js';
 /**
@@ -44,18 +46,6 @@ function sendPrometheus(res, body) {
     });
     res.end(body);
 }
-/** 把 app.run 的产物收成 HTTP 响应体（JSON 与 SSE 的 run.end 共用同一形状） */
-function toHttpBody(out) {
-    return {
-        runId: out.run.runId,
-        status: out.run.status,
-        stopReason: out.result.stopReason,
-        finalText: out.result.finalText,
-        typed: out.result.typed,
-        trace: out.result.trace,
-        error: out.result.error,
-    };
-}
 /**
  * 读取 body 全文。两道兜底（原实现两者皆无）：
  * - **maxBytes 上限**：超限立即停止累积并 resolve 成哨兵（调用方回 413）——
@@ -212,28 +202,32 @@ export function createHttpHandler(app, opts = {}) {
     const handler = async (req, res) => {
         const method = req.method ?? 'GET';
         const pathname = (req.url ?? '/').split('?')[0];
+        // 路由判定是**纯函数**（见 http-route.ts）：这里只按判定结果去编排。
+        // 顺序陷阱写在那边的头注里，最要命的一条：免鉴权组（/healthz、/metrics）
+        // 连同它们自己的 405 都在鉴权**之前**回，其余一律**先鉴权再判方法/路径**。
+        const route = routeRequest(pathname, method, metricsProvider !== undefined);
         try {
-            // 健康检查：不鉴权（探针带不了凭据）、停机中也回（探针要先能问到才有意义）
-            if (pathname === '/healthz') {
-                if (method !== 'GET') {
-                    methodNotAllowed(res, method, 'GET');
+            // 免鉴权组：健康检查（探针带不了凭据）与指标抓取（抓取端在集群内网），停机中也照回
+            // —— 探针要先能问到才有意义。它们的方法不符（405）同样在鉴权之前。
+            if (isPreAuthRoute(route)) {
+                if (route.kind === 'methodNotAllowed') {
+                    methodNotAllowed(res, method, route.allowed);
                     return;
                 }
-                sendJson(res, 200, {
-                    ok: true,
-                    inFlight: inFlightRuns + runner.inFlight,
-                    uptimeMs: Date.now() - startedAt,
-                    draining,
-                });
-                return;
-            }
-            // 指标：与 /healthz 同档（不鉴权、停机中仍可拉 —— 抓取端在集群内网）
-            if (pathname === '/metrics' && metricsProvider) {
-                if (method !== 'GET') {
-                    methodNotAllowed(res, method, 'GET');
+                if (route.kind === 'healthz') {
+                    sendJson(res, 200, {
+                        ok: true,
+                        inFlight: inFlightRuns + runner.inFlight,
+                        uptimeMs: Date.now() - startedAt,
+                        draining,
+                    });
                     return;
                 }
-                sendPrometheus(res, typeof metricsProvider === 'function' ? metricsProvider() : metricsProvider.render());
+                // 指标：与 /healthz 同档（不鉴权、停机中仍可拉 —— 抓取端在集群内网）。
+                // `?.` 只为让类型收窄（这条分支只在配了 metrics 出口时可达），行为与原来一致。
+                sendPrometheus(res, typeof metricsProvider === 'function'
+                    ? metricsProvider()
+                    : (metricsProvider?.render() ?? ''));
                 return;
             }
             // 鉴权缝：必须在读 body 之前（未通过即断开，body 一个字节都不收）
@@ -246,179 +240,163 @@ export function createHttpHandler(app, opts = {}) {
                     return;
                 }
             }
-            if (pathname === '/run') {
-                if (method !== 'POST') {
-                    methodNotAllowed(res, method, 'POST');
-                    return;
-                }
-                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}，请稍后重试`,
-                    });
+            // 方法与路径已在 routeRequest 里判完，往下只剩编排
+            switch (route.kind) {
+                case 'methodNotAllowed':
+                    methodNotAllowed(res, method, route.allowed);
                     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(),
+                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}，请稍后重试`,
                         });
-                        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);
+                        return;
+                    }
+                    inFlightRuns++;
+                    // 客户端中途断开 → 中止本次 run（省 token）。res 'close' 正常结束也会触发，
+                    // 故以 writableEnded 区分：只有响应还没写完才算「断开」。
+                    const runAc = new AbortController();
+                    const onClose = () => {
+                        if (!res.writableEnded)
                             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 }),
-                                ...(traceContext !== undefined ? { traceContext } : {}),
+                    };
+                    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(),
                             });
-                            sse.event('run.end', toHttpBody(out));
-                        }
-                        catch (e) {
-                            // 流已开（200 与头已发出）→ 只能以 error 事件收尾，不能再改 HTTP 状态码
-                            sse.event('error', { message: errMessage(e) });
-                        }
-                        finally {
-                            openSse.delete(closeSse);
-                            closeSse();
+                            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 }),
+                                    ...(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;
                         }
-                        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--;
                     }
-                    // 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;
-            }
-            if (pathname === '/tasks') {
-                if (method !== 'POST') {
-                    methodNotAllowed(res, method, 'POST');
-                    return;
-                }
-                // 停机中不再接单（含直接 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;
-                if (!body || typeof body !== 'object' || Array.isArray(body)) {
-                    sendJson(res, 400, { error: 'body 需为 { input, idempotencyKey?, options? }' });
                     return;
                 }
-                const submitBody = body;
-                // 入站链路（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) {
+                case 'submit': {
+                    // 停机中不再接单（含直接 drain 了 runner 的情况）；GET /tasks/<id> 不受影响
+                    if (draining || runner.isDraining) {
                         sendShuttingDown(req, res);
                         return;
                     }
-                    sendInternalError(res, e);
-                    return;
-                }
-                sendJson(res, 202, rec);
-                return;
-            }
-            if (pathname.startsWith('/tasks/')) {
-                const rest = pathname.slice('/tasks/'.length);
-                // POST /tasks/<id>/approve（HITL）：审批挂起的任务。drain 期间仍允许 ——
-                // 与 GET 轮询同理由：挂起的任务只有人能推进，停机不该连「批准」也拒掉。
-                if (rest.endsWith('/approve')) {
-                    if (method !== 'POST') {
-                        methodNotAllowed(res, method, 'POST');
+                    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;
                     }
-                    let taskId;
+                    // 入站链路（spec §9.2）：body 显式给的 `options.traceContext` 优先，否则取
+                    // `traceparent` 头。它随 `spec.options` 落进 TaskRecord —— 所以**跨进程续跑**
+                    // 的那次 run（另一个进程 `resumePending` 接着跑）也带得上，关联不断链。
+                    const submitTrace = parseTraceparent(headerValue(req, 'traceparent'));
+                    let rec;
                     try {
-                        taskId = decodeURIComponent(rest.slice(0, -'/approve'.length));
+                        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 {
-                        sendJson(res, 400, { error: 'taskId 不是合法的 URL 编码' });
+                    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;
@@ -443,28 +421,26 @@ export function createHttpHandler(app, opts = {}) {
                     }
                     return;
                 }
-                if (method !== 'GET') {
-                    methodNotAllowed(res, method, 'GET');
+                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;
                 }
-                let taskId;
-                try {
-                    taskId = decodeURIComponent(rest);
-                }
-                catch {
+                case 'badTaskId':
                     // 残缺的 % 转义会抛 URIError —— 是调用方的输入问题（400），不是服务端 500
                     sendJson(res, 400, { error: 'taskId 不是合法的 URL 编码' });
                     return;
-                }
-                const rec = await runner.poll(taskId); // MaybePromise：异步 store 下必须 await
-                if (!rec) {
-                    sendJson(res, 404, { error: `task 不存在: ${taskId}` });
+                // healthz / metrics 已在上面的免鉴权组里 return 掉
+                case 'notFound':
+                default:
+                    sendJson(res, 404, { error: `路径不存在: ${pathname}` });
                     return;
-                }
-                sendJson(res, 200, rec);
-                return;
             }
-            sendJson(res, 404, { error: `路径不存在: ${pathname}` });
         }
         catch (e) {
             sendInternalError(res, e);
@@ -474,38 +450,6 @@ export function createHttpHandler(app, opts = {}) {
     return Object.assign(handler, { drain, runner });
 }
 const PARSE_FAILED = Symbol('parse-failed');
-/**
- * 解析 `POST /tasks/<id>/approve` 的 body；形状不合法返回 undefined（调用方回 400）。
- * `decisions` 必须是纯对象，每个值是 `{ approved: boolean, reason?: string }`。
- */
-function parseApproveBody(body) {
-    if (!body || typeof body !== 'object' || Array.isArray(body))
-        return undefined;
-    const o = body;
-    if (!o.decisions || typeof o.decisions !== 'object' || Array.isArray(o.decisions)) {
-        return undefined;
-    }
-    if (o.decidedBy !== undefined && typeof o.decidedBy !== 'string')
-        return undefined;
-    const decisions = {};
-    for (const [id, d] of Object.entries(o.decisions)) {
-        if (!d || typeof d !== 'object' || Array.isArray(d))
-            return undefined;
-        const v = d;
-        if (typeof v.approved !== 'boolean')
-            return undefined;
-        if (v.reason !== undefined && typeof v.reason !== 'string')
-            return undefined;
-        decisions[id] = {
-            approved: v.approved,
-            ...(v.reason !== undefined ? { reason: v.reason } : {}),
-        };
-    }
-    return {
-        decisions,
-        ...(o.decidedBy !== undefined ? { decidedBy: o.decidedBy } : {}),
-    };
-}
 /** 读取并解析 JSON body；失败时直接回错误响应并返回哨兵（连接已断则无响应可回）。 */
 async function parseJsonBody(req, res, maxBytes) {
     const body = await readBody(req, maxBytes);