@migor/agentia 0.2.1 → 0.2.2

package/dist/transport/async.js

@@ -0,0 +1,415 @@
+import { randomUUID } from 'node:crypto';
+import { classifyError } from '../engine/errors.js';
+import { normalizeMessages } from '../engine/spec.js';
+import { InMemoryTaskStore, isThenable, nextTaskId } from '../store/store.js';
+import { combineSignals } from '../core/abort.js';
+export class AsyncRunner {
+    app;
+    store;
+    /** 本进程标识：写进认领的 TaskRecord.ownerId，供 resumePending 区分他我 */
+    ownerId;
+    client;
+    concurrency;
+    runTimeoutMs;
+    running = 0;
+    waitQueue = [];
+    /** 已受理但未达终态的任务数（queued + running）—— /healthz 与 drain 共用 */
+    active = 0;
+    draining = false;
+    drainWaiters = [];
+    /** 任务终态唤醒表：taskId → 等待者。仅覆盖**本进程**写终态（他进程写靠兜底轮询） */
+    #taskWaiters = new Map();
+    taskSinks;
+    constructor(app, opts = {}) {
+        this.app = app;
+        this.store = opts.store ?? new InMemoryTaskStore();
+        this.client = opts.client;
+        this.taskSinks = opts.taskSinks ?? [];
+        this.concurrency = opts.concurrency ?? Number.POSITIVE_INFINITY;
+        if (!(this.concurrency > 0)) {
+            throw new Error(`concurrency 必须为正数，收到 ${opts.concurrency}`);
+        }
+        this.runTimeoutMs = opts.runTimeoutMs ?? 0;
+        if (this.runTimeoutMs < 0) {
+            throw new Error(`runTimeoutMs 不能为负，收到 ${opts.runTimeoutMs}`);
+        }
+        this.ownerId = `p${process.pid}-${randomUUID().slice(0, 8)}`;
+    }
+    /**
+     * 提交一次异步任务。入参可为 string / messages / {prompt|text|messages}。
+     * 幂等键存在且上一任务未失败 → 直接返回既有记录（去重）；失败的同键可产生新任务。
+     * 同步门面：同步 store 下立即去重并返回快照；异步 store 下 save 在后台完成、
+     * 去重推迟到执行前（见 #execute），返回新建任务的提交时刻快照。
+     */
+    submit(input, opts = {}) {
+        // 停机中不接单（drain 之后）；宿主据此回 503。放在最前：连入参规整都省了。
+        if (this.draining) {
+            throw new Error('runner 正在优雅停机，不再接受新任务');
+        }
+        const messages = normalizeMessages(input);
+        if (opts.idempotencyKey) {
+            const existing = this.store.byIdempotency(opts.idempotencyKey);
+            if (isThenable(existing)) {
+                // 异步 store 返回 Promise —— 同步门面无法 await，去重交给 #execute。
+                // 但**必须订阅它**：byIdempotency 的 reject（Redis 抖动等）若无人处理就是
+                // unhandledRejection（Node ≥15 默认终止宿主进程）。这里只做「查不到既有记录」
+                // 处理，拒绝即视为无记录，交 #execute 的去重兜底。
+                existing.catch(() => undefined);
+            }
+            else if (existing && existing.status !== 'failed') {
+                return { ...existing }; // at-least-once 去重：不重复执行
+            }
+        }
+        const rec = {
+            taskId: nextTaskId(),
+            status: 'queued',
+            idempotencyKey: opts.idempotencyKey,
+            spec: { messages, options: opts.options, source: opts.source ?? 'async' },
+            createdAt: Date.now(),
+            ownerId: this.ownerId,
+        };
+        const saved = this.store.save(rec);
+        if (isThenable(saved)) {
+            // 异步落库失败：尽力把任务标记为 failed 重存，避免静默吞错 / unhandled rejection。
+            // 但只在任务**尚未被 #execute 推进**时改判：初始 save 的 reject 可能迟到，
+            // 那时 run 已跑完并写了成功终态，无条件覆写会把成功翻成失败（落库终态与真实结果相反）。
+            saved.catch((e) => {
+                if (rec.status !== 'queued' || rec.finishedAt !== undefined)
+                    return;
+                rec.status = 'failed';
+                rec.error = classifyError(e);
+                rec.finishedAt = Date.now();
+                void this.#safeSave(rec);
+            });
+        }
+        void this.#execute(rec);
+        // 返回浅拷贝：记录会被后台状态机原地推进，调用方拿到的是提交时刻的快照
+        return { ...rec };
+    }
+    /** 查任务当前记录（异步 store 下返回 Promise，调用方 await） */
+    poll(taskId) {
+        return this.store.get(taskId);
+    }
+    byIdempotency(key) {
+        return this.store.byIdempotency(key);
+    }
+    list() {
+        return this.store.list();
+    }
+    /** 已受理但未达终态的任务数（queued + running）—— 健康检查与 drain 共用同一口径 */
+    get inFlight() {
+        return this.active;
+    }
+    /** 是否已进入优雅停机（drain 之后为 true）—— HTTP 宿主据此对新单回 503 */
+    get isDraining() {
+        return this.draining;
+    }
+    /**
+     * 优雅停机：停止接单（此后 `submit` 抛错），等待已受理任务排空（或超时）。
+     *
+     * 返回是否排空干净：超时仍返回 `false`，**未完成的任务留在 store 里**，下次启动由
+     * `resumePending` 续跑（所以 drain 不是「丢弃」，是「不再往前推」）。
+     * - `timeoutMs` 缺省 0 = 一直等。
+     * - 等待的是**所有已受理**的任务（queued 的也在内），不只是正在占槽位的那些。
+     */
+    async drain(opts = {}) {
+        this.draining = true;
+        const timeoutMs = opts.timeoutMs ?? 0;
+        if (this.active === 0)
+            return true;
+        const drained = new Promise((resolve) => this.drainWaiters.push(() => resolve(true)));
+        if (timeoutMs <= 0)
+            return drained;
+        let timer;
+        try {
+            return await Promise.race([
+                drained,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(false), timeoutMs);
+                    // ⚠️ 不 unref：`drain()` 返回的正是这个 false —— 计时器的触发就是「调用方的 await 得以结束」
+                    // 的条件。unref 过它 ⇒ 空事件循环下进程先退出，停机等待没有任何结论
+                    // （见 `tests/timeoutLiveness.test.ts` 与 spec §10 ④）。
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** 任务终态唤醒：在 #execute 的统一出口调用，覆盖成功 / 失败 / 采纳既有结果各路径 */
+    #notifyTaskDone(taskId) {
+        const waiters = this.#taskWaiters.get(taskId);
+        if (!waiters || waiters.length === 0)
+            return;
+        this.#taskWaiters.delete(taskId);
+        for (const w of waiters)
+            w();
+    }
+    /** 等「本进程把该任务写到终态」或被 timeoutMs 兜底唤醒（二者先到先返回） */
+    #waitTaskDone(taskId, timeoutMs) {
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                const waiters = this.#taskWaiters.get(taskId);
+                if (waiters) {
+                    const i = waiters.indexOf(finish);
+                    if (i >= 0)
+                        waiters.splice(i, 1);
+                    if (waiters.length === 0)
+                        this.#taskWaiters.delete(taskId);
+                }
+                resolve();
+            };
+            const timer = setTimeout(finish, timeoutMs);
+            const waiters = this.#taskWaiters.get(taskId);
+            if (waiters)
+                waiters.push(finish);
+            else
+                this.#taskWaiters.set(taskId, [finish]);
+        });
+    }
+    /** 排空通知：只在确无在飞任务时唤醒等待者（drain 的唯一出口） */
+    #notifyDrained() {
+        if (this.active !== 0 || this.drainWaiters.length === 0)
+            return;
+        const waiters = this.drainWaiters.splice(0, this.drainWaiters.length);
+        for (const w of waiters)
+            w();
+    }
+    /** 等到任务终态；超时抛错。 */
+    async awaitTask(taskId, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        // intervalMs 现在只是**兜底轮询**间隔，不是主路径：本进程把任务写到终态会主动唤醒
+        // （见 #notifyTaskDone）。默认从 5ms 放宽到 250ms —— 旧实现每 5ms 读一次 store，
+        // 等 30s 就是约 6000 次读（SQLite/Redis 下是 6000 次往返）。用异步 store 且终态由
+        // **他进程**写入时唤不醒，才靠这个间隔兜底。
+        const intervalMs = opts.intervalMs ?? 250;
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const rec = await this.store.get(taskId);
+            if (!rec)
+                throw new Error(`task 不存在: ${taskId}`);
+            if (rec.status === 'succeeded' || rec.status === 'failed')
+                return rec;
+            const left = deadline - Date.now();
+            if (left <= 0)
+                throw new Error(`task ${taskId} 等待超时（${rec.status}）`);
+            await this.#waitTaskDone(taskId, Math.min(intervalMs, left));
+        }
+    }
+    /**
+     * 宿主重启续跑：把 store 里 queued | running 的记录重新派发执行
+     * （running 视为进程中断）。返回重派数量（异步 store 下返回 Promise<number>）。
+     * 幂等键去重照常生效。
+     *
+     * 多进程共用一个 store 时靠 `ownerId` 区分他我：
+     * - 本进程的记录一律跳过（它还在本进程内存里跑，重派 = 跑两遍）；
+     * - `staleAfterMs > 0` 时，startedAt/createdAt 距今不足该值的他进程记录也跳过
+     *   （大概正被那个进程执行）。缺省 0 = 不判断、一律重派（单进程旧语义）。
+     */
+    resumePending(opts = {}) {
+        const listed = this.store.list();
+        const staleAfterMs = opts.staleAfterMs ?? 0;
+        if (isThenable(listed)) {
+            return listed.then((recs) => this.#redispatch(recs, staleAfterMs));
+        }
+        return this.#redispatch(listed, staleAfterMs);
+    }
+    #redispatch(recs, staleAfterMs) {
+        const now = Date.now();
+        const pending = recs.filter((r) => {
+            if (r.status !== 'queued' && r.status !== 'running')
+                return false;
+            if (r.ownerId === this.ownerId)
+                return false; // 自己的一定还活着
+            if (staleAfterMs > 0 && r.ownerId !== undefined) {
+                const since = r.startedAt ?? r.createdAt;
+                if (now - since < staleAfterMs)
+                    return false; // 他进程刚起的，别抢
+            }
+            return true;
+        });
+        for (const rec of pending) {
+            rec.status = 'queued'; // 重新入队，由 #execute 统一推进
+            rec.ownerId = this.ownerId; // 认领：此后本进程的记录不再被（自己）重派
+            void this.#execute(rec);
+        }
+        return pending.length;
+    }
+    /**
+     * 在飞计数包裹层：#executeInner 是状态机主体，这里只负责 active 计数与排空通知。
+     * 计数在**同步段**（第一个 await 之前）自增 —— 所以 `void this.#execute(rec)` 一返回，
+     * 该任务就已经计入了，drain 不会漏掉「刚 submit、还没开始跑」的任务。
+     */
+    async #execute(rec) {
+        this.active++;
+        try {
+            await this.#executeInner(rec);
+        }
+        finally {
+            // 通知在飞递减**之前**：drain() 返回时保证「任务已终态 + 回调已发完」。
+            // 内层 finally 保证回调万一抛错（理论上被吞掉）也不泄漏在飞计数。
+            try {
+                await this.#notifySinks(rec);
+            }
+            finally {
+                this.active--;
+                // 任务已达终态并落库 → 唤醒 awaitTask 的等待者（放在递减之后，语义与 drain 一致）
+                this.#notifyTaskDone(rec.taskId);
+                this.#notifyDrained();
+            }
+        }
+    }
+    /** 通知任务完成回调。逐个 await，**sink 抛错被吞** —— 回调失败不得影响任务状态。 */
+    async #notifySinks(rec) {
+        if (this.taskSinks.length === 0)
+            return;
+        // 传快照：回调拿到的是「此刻的终态」，之后记录再被改动不会串进回调持有的引用
+        const snapshot = { ...rec };
+        for (const sink of this.taskSinks) {
+            try {
+                await sink.onFinished(snapshot);
+            }
+            catch {
+                /* 回调失败不影响任务状态（同 trace sink / memory 回写的防护） */
+            }
+        }
+    }
+    async #executeInner(rec) {
+        // 顶层容错：异步 store（网络客户端）任何一处 reject 都不得逃逸成
+        // unhandled rejection（Node ≥15 默认终止进程）——任务标记失败尽力落库。
+        try {
+            // 异步 store 的幂等去重在此补齐（submit 同步门面无法 await）：
+            // 同键已有 succeeded 记录 → 采纳其结果，不重复执行；queued/running 不采纳 ——
+            // 重复执行本就是 at-least-once 允许的行为。同步 store 下 submit 已完成去重，
+            // 这里查到的一般是 rec 自身（taskId 相同，直接放行）。
+            // 注意（load-bearing）：该去重依赖 store.save 先写记录、后写 idem 索引的顺序
+            // （见 redisStore 头注释）——索引指向自身时上面的 taskId 相等判断放行。
+            if (rec.idempotencyKey) {
+                const existing = await this.store.byIdempotency(rec.idempotencyKey);
+                if (existing && existing.taskId !== rec.taskId && existing.status === 'succeeded') {
+                    rec.status = 'succeeded';
+                    rec.runId = existing.runId;
+                    rec.result = existing.result;
+                    rec.error = existing.error;
+                    rec.finishedAt = Date.now();
+                    // 采纳既有结果：落库失败也不该把一次已知成功的任务翻成 failed
+                    await this.#safeSave(rec);
+                    return;
+                }
+            }
+            await this.#acquireSlot();
+            try {
+                rec.status = 'running';
+                rec.startedAt = Date.now();
+                await this.store.save(rec);
+                try {
+                    // runTimeoutMs 到点即 abort（对尊重 signal 的客户端是真中止）；与调用方
+                    // 可能传入的 signal 合成，任一触发都中止本次 run。
+                    const timeoutAc = new AbortController();
+                    const callOpts = {
+                        ...(rec.spec.options ?? {}),
+                        client: rec.spec.options?.client ?? this.client,
+                        idempotencyKey: rec.idempotencyKey,
+                        rethrow: false, // 硬失败也以 failed 记录落库
+                        signal: combineSignals(rec.spec.options?.signal, timeoutAc.signal),
+                    };
+                    const out = await this.#raceTimeout(this.app.run(rec.spec.messages, callOpts), rec.taskId, () => timeoutAc.abort());
+                    rec.runId = out.run.runId;
+                    rec.status = out.run.status;
+                    rec.result = out.result;
+                    rec.error = out.result.error;
+                }
+                catch (e) {
+                    rec.error = classifyError(e);
+                    rec.status = 'failed';
+                }
+            }
+            finally {
+                rec.finishedAt = Date.now();
+                // 落库失败不遮罩、槽位必须释放：释放放在内层 finally，即便落库实现抛错也必达
+                try {
+                    await this.#safeSave(rec);
+                }
+                finally {
+                    this.#releaseSlot();
+                }
+            }
+        }
+        catch (e) {
+            rec.status = 'failed';
+            rec.error = classifyError(e);
+            rec.finishedAt = Date.now();
+            await this.#safeSave(rec);
+            console.error(`[agentia] task ${rec.taskId} 执行异常:`, e);
+        }
+    }
+    /**
+     * 尽力落库：**先包成 Promise 再挂 catch**。
+     *
+     * 同步 store（FileTaskStore 的 writeFileSync、node:sqlite）的 save 是**同步抛错**的。
+     * 若写成 `Promise.resolve(this.store.save(rec)).catch(...)`，`this.store.save(rec)`
+     * 会在 `Promise.resolve` 之前求值并同步抛出 —— 异常逃出 finally（跳过 #releaseSlot，
+     * 并发槽位永久泄漏），再被外层 catch 里同一写法抛第二次，最终逃出 #execute 变成
+     * unhandled rejection（Node ≥15 默认终止宿主进程）。
+     */
+    async #safeSave(rec) {
+        try {
+            await Promise.resolve().then(() => this.store.save(rec));
+        }
+        catch {
+            // 落库失败不遮罩主流程：任务结果仍在内存记录里可见
+        }
+    }
+    /**
+     * 超时竞速（runTimeoutMs > 0 时）：超时先 `onTimeout()`（abort 在飞请求）再 reject
+     * → 任务按 failed 落库、槽位回收。尊重 signal 的客户端会被真中止；不尊重者只是
+     * 停止等待（race 已订阅该 Promise，其后续 reject 不会变成 unhandled rejection）。
+     * timer 必须 clear（否则每次任务都留一个定时器）。
+     */
+    async #raceTimeout(p, taskId, onTimeout) {
+        if (this.runTimeoutMs <= 0)
+            return p;
+        let timer;
+        try {
+            return await Promise.race([
+                p,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        onTimeout?.();
+                        reject(new Error(`task ${taskId} 执行超时（${this.runTimeoutMs}ms）`));
+                    }, this.runTimeoutMs);
+                    // ⚠️ 不 unref：这个 reject 是 `awaitTask` / 调用方 await 的终点（spec §10 ④）。
+                    // 见 `tests/timeoutLiveness.test.ts`。
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** 并发槽位：超限则排队等待（任务记录保持 queued，由 store 可见） */
+    #acquireSlot() {
+        if (this.running < this.concurrency) {
+            this.running++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => this.waitQueue.push(resolve));
+    }
+    #releaseSlot() {
+        const next = this.waitQueue.shift();
+        if (next) {
+            next(); // 槽位直接移交给等待者，running 计数不变
+        }
+        else {
+            this.running--;
+        }
+    }
+}
+//# sourceMappingURL=async.js.map

package/dist/transport/async.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.js","sourceRoot":"","sources":["../../src/transport/async.ts"],"names":[],"mappings":"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"}

package/dist/transport/http.d.ts

@@ -0,0 +1,146 @@
+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）。
+ *
+ * 只产出一个 (req, res) handler，不做 listen —— 交给用户
+ * `http.createServer(createHttpHandler(app)).listen(...)`，可挂进任意 Node HTTP 框架。
+ *
+ * 端点契约（全部 JSON）：
+ * - POST /run        同步 RPC。body = RunInput（string / messages / {prompt|text|messages}），
+ *                    走 normalizeMessages 规整后同步执行；200 { runId, status, stopReason,
+ *                    finalText, typed?, trace, error? }。status=failed 也照返 200
+ *                    （rethrow:false 语义：硬失败以 error 字段返回，不用 HTTP 错误码表达）；
+ *                    输入无法规整为 messages → 400 { error }；
+ *                    并发 run 超 maxConcurrentRuns → 503 + Retry-After（见该选项）。
+ * - POST /tasks      异步任务。body { input, idempotencyKey?, options? } →
+ *                    AsyncRunner.submit → 202 TaskRecord（queued，幂等键去重照常生效）。
+ * - GET  /tasks/<id> 轮询任务记录 → 200 TaskRecord；不存在 → 404。
+ * - GET  /healthz    健康检查 → 200 { ok, inFlight, uptimeMs, draining }；**不鉴权**
+ *                    （探针不该带凭据）。停机中仍回 200（进程活着），就绪与否看 draining。
+ *
+ * 方法不符 405；路径不符 404；body 非法 JSON 400。runner 缺省内部 new AsyncRunner(app)。
+ *
+ * 鉴权（B1）：配了 `authenticate` 时，**除 /healthz 外的所有路径**先过钩子，且必须在
+ * 读 body 之前 —— 未通过即回错误并断开连接，**不接收 body**（省资源）。框架只给缝：
+ * token / JWT / 签名策略是宿主或反代的事（框架不读 env、不碰凭据）。
+ *
+ * 优雅停机（B2）：`handler.drain()` 拒新单（POST /run 与 /tasks → 503）、等异步任务与
+ * 在飞同步 run 收尾、强制收口仍开着的 SSE 流；`GET /tasks/<id>` 停机中照常可轮询
+ * （否则调用方拿不到在飞任务的结果）。
+ */
+/** POST /run 的响应形态 */
+export interface RunHttpResponse {
+    runId: string;
+    status: RunStatus;
+    stopReason: AgentStopReason;
+    finalText: string;
+    /** 结构化结果（R2 起应用可携带；无则省略） */
+    typed?: unknown;
+    trace: Trace;
+    error?: SpanError;
+}
+/** POST /tasks 的请求体形态 */
+export interface TaskSubmitBody {
+    input: unknown;
+    idempotencyKey?: string;
+    options?: RunInvocationOptions;
+}
+export interface HttpHandlerOptions {
+    /** 异步任务宿主；缺省 new AsyncRunner(app)（InMemoryTaskStore） */
+    runner?: AsyncRunner;
+    /** 请求 body 上限（字节），超限回 413；缺省 1 MiB */
+    maxBodyBytes?: number;
+    /**
+     * 同时在执行的 POST /run 上限；缺省 32，超限回 503 + `Retry-After`。
+     * 传 `Infinity` 恢复无上限（旧行为）。**行为变更**：旧版本无此闸门。
+     * 闸门针对同步 RPC —— 每次请求都会真跑一次 run，不设上限时少量并发请求
+     * 就能把宿主压垮（上游模型并发也一起打满）；异步走 POST /tasks（runner 自带上限）。
+     */
+    maxConcurrentRuns?: number;
+    /**
+     * 是否把内部异常原文回给调用方；缺省 false。
+     * false 时 500 只回通用文案，细节走 `console.error` —— 否则
+     * `ECONNREFUSED 10.0.0.7:6379` 这类内部拓扑会回给未鉴权的调用方。
+     */
+    exposeErrors?: boolean;
+    /**
+     * SSE 下游积压上限（字节）：`res.writableLength` 超过它即收口该 SSE 流（见 `sseWriter`）。
+     * 缺省 8 MiB —— 正常客户端远达不到，实际只拦「连得上但不读」的消费者。
+     *
+     * **收口会连带中止对应的 run**：客户端已经不消费了，继续逐 token 生成只是白花模型钱，
+     * 同时把内存堆高。要高限额传更大的值；要记录/告警请自行在 `sseWriter` 之上包一层 sink。
+     */
+    sseMaxBufferedBytes?: number;
+    /**
+     * 入口鉴权钩子。请求进入时调用，**除 /healthz 外所有路径**都过它，且**在读 body 之前**
+     * （未通过就不接收 body，省资源）。
+     * - 正常返回（任意值）→ 视为通过。返回值框架不转交：要 per-request 上下文请在钩子自己的
+     *   闭包里存（避免为「暂时没有消费点」的东西发明传递通道）；
+     * - 抛出 `HttpException` → 按其 `status` / `body` 回响应（想回 403 就抛 `status: 403`）；
+     * - 抛出其它错误 → 回 401 `{ error: '未通过鉴权' }`，原文只进服务端日志
+     *   （与 `exposeErrors` 同理：不把内部拓扑回给未鉴权的调用方）。
+     *
+     * 框架**不实现策略**（token / JWT / 签名都不做）—— 那是宿主或反代的事（框架不读 env、
+     * 不碰凭据）。为什么不做成 middleware：middleware 拦的是**能力调用**（run 内部），
+     * 而鉴权要拦的是 **run 入口**，且必须早于 body 读取。
+     */
+    authenticate?: (req: IncomingMessage) => unknown | Promise<unknown>;
+    /**
+     * 指标出口（G4）：提供后 `GET /metrics` 输出其 Prometheus 文本（`text/plain; version=0.0.4`）。
+     * 通常直接传 `metricsSink()`（它有 `render()`）。
+     *
+     * 与 `/healthz` 同档处理：**不鉴权**、停机中仍可拉（拉取端在集群内网）。要保护它，
+     * 请放到反代之后，或不要传这个选项、自己在 handler 外层挂路由。
+     *
+     * 框架只给缝：它不知道指标从哪来 —— 传 sink、传读快照的闭包都行。
+     */
+    metrics?: {
+        render(): string;
+    } | (() => string);
+}
+/** GET /healthz 的响应形态 */
+export interface HealthResponse {
+    /** 恒为 true：能回这个响应就说明进程活着（停机中也是 true，就绪与否看 draining） */
+    ok: true;
+    /**
+     * 在飞工作量 = **正在处理的同步 run**（并发闸门计数，含 SSE 流）
+     *            + **已受理未完成的异步任务**（queued + running）。
+     * 与 `drain()` 等的范围一致 —— 这样健康检查和停机判断看的是同一个数。
+     */
+    inFlight: number;
+    /** 本 handler 创建至今的毫秒数 */
+    uptimeMs: number;
+    /** 是否已进入优雅停机（drain 之后）—— 负载均衡据此摘流量 */
+    draining: boolean;
+}
+/**
+ * 鉴权钩子可抛出的异常：显式携带 HTTP 状态与响应体。
+ * 钩子抛别的错误一律按 401 处理（设计 F4：与「工具抛错即 is_error」的既有风格一致）。
+ */
+export declare class HttpException extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body?: unknown, message?: string);
+}
+/** createHttpHandler 的产物：可直接传给 http.createServer，另带停机控制面 */
+export interface HttpHandler {
+    (req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * 优雅停机：拒新单（POST /run、/tasks → 503）→ 等异步任务与在飞同步 run 收尾
+     * （或超时）→ 强制收口仍开着的 SSE 流。返回是否排空干净（超时/仍有在飞为 false）。
+     * 未完成的任务仍在 store 里，下次启动由 `resumePending` 续跑。
+     * 框架**不订阅 SIGTERM**：`process.on('SIGTERM', () => handler.drain())` 是宿主的事。
+     */
+    drain(opts?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    /** 内部 AsyncRunner —— 需要时手动控制（resumePending / awaitTask / list 等） */
+    readonly runner: AsyncRunner;
+}
+export declare function createHttpHandler(app: AppCallable, opts?: HttpHandlerOptions): HttpHandler;