@migor/agentia 0.2.0 → 0.2.2

package/dist/transport/http.js

@@ -0,0 +1,387 @@
+import { AsyncRunner } from './async.js';
+import { sseWriter } from './sse.js';
+import { normalizeMessages } from '../engine/spec.js';
+/**
+ * 鉴权钩子可抛出的异常：显式携带 HTTP 状态与响应体。
+ * 钩子抛别的错误一律按 401 处理（设计 F4：与「工具抛错即 is_error」的既有风格一致）。
+ */
+export class HttpException extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message ?? `HTTP ${status}`);
+        this.name = 'HttpException';
+        this.status = status;
+        this.body = body ?? { error: `HTTP ${status}` };
+    }
+}
+/** body 上限缺省值：1 MiB —— 本宿主只接 messages JSON，正常远小于此 */
+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);
+}
+/** 把 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）——
+ *   否则一个未鉴权的大 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）。
+ *
+ * **连接处理**：这里在读到 body 之前就回了响应，请求体没被消费 —— 连接不能复用，
+ * 否则残留字节会被当成下一个请求（与 413 同理）。故 `req.complete` 为假时显式
+ * `connection: close`，让客户端尽早停止上传（这也正是「省资源」的落点）。
+ */
+function sendUnauthorized(req, res, e, exposeErrors) {
+    // 在读到 body 之前就回了响应：请求体没被消费 → 连接不能复用
+    // （残留字节会被当成下一个请求，与 413 同理）。这也正是「不收 body 省资源」的落点。
+    if (!req.complete)
+        res.setHeader('connection', 'close');
+    if (e instanceof HttpException) {
+        sendJson(res, e.status, e.body);
+        return;
+    }
+    if (exposeErrors) {
+        sendJson(res, 401, { error: errMessage(e) });
+        return;
+    }
+    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: '服务正在优雅停机，不再接受新任务' });
+}
+export function createHttpHandler(app, opts = {}) {
+    const runner = opts.runner ?? new AsyncRunner(app);
+    const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    const maxConcurrentRuns = opts.maxConcurrentRuns ?? DEFAULT_MAX_CONCURRENT_RUNS;
+    const exposeErrors = opts.exposeErrors ?? false;
+    const sseMaxBufferedBytes = opts.sseMaxBufferedBytes;
+    const authenticate = opts.authenticate;
+    const metricsProvider = 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;
+        }
+        // 细节只进服务端日志，响应里不回内部拓扑
+        console.error('[agentia:http] 请求处理异常:', e);
+        sendJson(res, 500, { error: '内部错误' });
+    };
+    /** 优雅停机（B2）：拒新单 → 等异步任务与在飞同步 run → 强制收口 SSE。 */
+    const drain = async (drainOpts = {}) => {
+        draining = true; // 先拒新单，再等存量
+        const timeoutMs = drainOpts.timeoutMs ?? 0;
+        const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : Number.POSITIVE_INFINITY;
+        const remaining = () => deadline === Number.POSITIVE_INFINITY ? 0 : Math.max(0, deadline - Date.now());
+        // 异步任务：排在 waitQueue 里的也一并等（它们的记录在 store 里，超时未跑完则下次启动续跑）
+        const tasksDrained = await runner.drain(deadline === Number.POSITIVE_INFINITY ? {} : { timeoutMs: remaining() });
+        // 同步 /run（含 SSE 流）也在 inFlightRuns 里计数 —— 同样给到 deadline
+        const runsDrained = inFlightRuns === 0 || (await waitUntil(() => inFlightRuns === 0, deadline));
+        // 收口：超时仍挂着的 SSE 流强制关闭（其 run 因 res 'close' 中止，stopReason='aborted'）
+        for (const close of [...openSse])
+            close();
+        return tasksDrained && runsDrained;
+    };
+    const handler = async (req, res) => {
+        const method = req.method ?? 'GET';
+        const pathname = (req.url ?? '/').split('?')[0];
+        try {
+            // 健康检查：不鉴权（探针带不了凭据）、停机中也回（探针要先能问到才有意义）
+            if (pathname === '/healthz') {
+                if (method !== 'GET') {
+                    methodNotAllowed(res, method, 'GET');
+                    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');
+                    return;
+                }
+                sendPrometheus(res, typeof metricsProvider === 'function' ? metricsProvider() : metricsProvider.render());
+                return;
+            }
+            // 鉴权缝：必须在读 body 之前（未通过即断开，body 一个字节都不收）
+            if (authenticate) {
+                try {
+                    await authenticate(req);
+                }
+                catch (e) {
+                    sendUnauthorized(req, res, e, exposeErrors);
+                    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}，请稍后重试`,
+                    });
+                    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');
+                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 是长连，不关会把进程吊住）
+                        const closeSse = () => {
+                            clearInterval(heartbeat);
+                            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 }),
+                            });
+                            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 });
+                    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;
+                let rec;
+                try {
+                    rec = runner.submit(submitBody.input, {
+                        idempotencyKey: submitBody.idempotencyKey,
+                        options: submitBody.options,
+                        source: 'http',
+                    });
+                }
+                catch (e) {
+                    sendJson(res, 400, { error: errMessage(e) });
+                    return;
+                }
+                sendJson(res, 202, rec);
+                return;
+            }
+            if (pathname.startsWith('/tasks/')) {
+                if (method !== 'GET') {
+                    methodNotAllowed(res, method, 'GET');
+                    return;
+                }
+                let taskId;
+                try {
+                    taskId = decodeURIComponent(pathname.slice('/tasks/'.length));
+                }
+                catch {
+                    // 残缺的 % 转义会抛 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}` });
+                    return;
+                }
+                sendJson(res, 200, rec);
+                return;
+            }
+            sendJson(res, 404, { error: `路径不存在: ${pathname}` });
+        }
+        catch (e) {
+            sendInternalError(res, e);
+        }
+    };
+    // 把停机控制面挂在 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

package/dist/transport/http.js.map

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

package/dist/{run → transport}/scheduler.d.ts

@@ -1,5 +1,5 @@
 import type { AsyncRunner } from './async.js';
-import type { RunInvocationOptions } from './spec.js';
+import type { RunInvocationOptions } from '../engine/spec.js';
 export interface ScheduleEveryOptions {
     /** 任务级调用参数 */
     options?: RunInvocationOptions;
@@ -7,6 +7,12 @@ export interface ScheduleEveryOptions {
     idempotencyPrefix?: string;
     /** 覆盖触发来源标记 */
     source?: string;
+    /**
+     * 同时未终态的任务数上限；缺省 1（上一片没跑完就跳过本次 tick）。
+     * 没有它时 `every(1000)` + 60s 任务会每个 tick 都 submit 一次，任务无上限堆积。
+     * 传 `Infinity` 关闭闸门（旧行为）。'at' 单发天然不受影响。
+     */
+    maxInFlight?: number;
 }
 export interface ScheduleHandle {
     id: string;
@@ -23,5 +29,7 @@ export declare class Scheduler {
     cancel(id: string): void;
     stop(): void;
     get active(): number;
+    /** 清掉已到终态的追踪项（异步 store 下 poll 返回 Promise，到货后再清） */
+    private pruneInFlight;
     private dispatch;
 }

package/dist/transport/scheduler.js

@@ -0,0 +1,133 @@
+import { randomUUID } from 'node:crypto';
+import { isThenable } from '../store/store.js';
+export class Scheduler {
+    runner;
+    jobs = new Map();
+    constructor(runner) {
+        this.runner = runner;
+    }
+    /** 周期触发（毫秒间隔）。首次触发在 intervalMs 之后。 */
+    every(intervalMs, input, opts = {}) {
+        if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+            // setInterval(0) 会退化成「尽快重复」的空转循环，把事件循环打满（Node 会把
+            // 0 钳到 1ms 但仍是每毫秒一次的忙轮询）。这是配置错误，直接报错。
+            throw new Error(`Scheduler.every 的 intervalMs 必须为正有限数，收到 ${intervalMs}`);
+        }
+        const id = randomUUID();
+        const timer = setInterval(() => {
+            const job = this.jobs.get(id);
+            if (job)
+                this.dispatch(job);
+        }, intervalMs);
+        if (typeof timer === 'object' && 'unref' in timer)
+            timer.unref?.();
+        this.jobs.set(id, {
+            id,
+            kind: 'every',
+            timer,
+            intervalMs,
+            input,
+            options: opts.options,
+            source: opts.source,
+            prefix: opts.idempotencyPrefix,
+            inFlight: new Set(),
+            maxInFlight: opts.maxInFlight ?? 1,
+        });
+        return { id, cancel: () => this.cancel(id) };
+    }
+    /** 单次触发（指定时刻）。 */
+    at(when, input, opts = {}) {
+        if (!(when instanceof Date) || !Number.isFinite(when.getTime())) {
+            // 非法日期 → delay 为 NaN → setTimeout(fn, NaN) 会立即触发且无任何提示
+            throw new Error(`Scheduler.at 需要一个合法 Date（非 Invalid Date），收到 ${String(when)}`);
+        }
+        const id = randomUUID();
+        const delay = Math.max(0, when.getTime() - Date.now());
+        const timer = setTimeout(() => {
+            const job = this.jobs.get(id);
+            this.jobs.delete(id);
+            if (job)
+                this.dispatch(job);
+        }, delay);
+        // 与 every() 一致：定时器不阻止进程退出（宿主 stop() 仍可显式取消）
+        if (typeof timer === 'object' && 'unref' in timer)
+            timer.unref?.();
+        this.jobs.set(id, {
+            id,
+            kind: 'at',
+            timer,
+            input,
+            options: opts.options,
+            source: opts.source,
+            prefix: opts.idempotencyPrefix,
+        });
+        return { id, cancel: () => this.cancel(id) };
+    }
+    cancel(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            return;
+        clearTimeout(job.timer);
+        this.jobs.delete(id);
+    }
+    stop() {
+        for (const id of [...this.jobs.keys()])
+            this.cancel(id);
+    }
+    get active() {
+        return this.jobs.size;
+    }
+    /** 清掉已到终态的追踪项（异步 store 下 poll 返回 Promise，到货后再清） */
+    pruneInFlight(inFlight) {
+        const forget = (taskId) => inFlight.delete(taskId);
+        for (const taskId of inFlight) {
+            const rec = this.runner.poll(taskId);
+            if (isThenable(rec)) {
+                void rec
+                    .then((r) => {
+                    if (!r || r.status === 'succeeded' || r.status === 'failed')
+                        forget(taskId);
+                })
+                    .catch(() => forget(taskId)); // 查不到就别再挡住后续 tick
+                continue;
+            }
+            const r = rec;
+            if (!r || r.status === 'succeeded' || r.status === 'failed')
+                forget(taskId);
+        }
+    }
+    dispatch(job) {
+        // maxInFlight 闸门（仅周期任务）：上一片还在跑就跳过本次 tick —— 否则
+        // every(1000) + 60s 任务会每个 tick 都派发，任务无上限堆积。
+        // Infinity = 闸门关闭：也不追踪（否则 inFlight 集合随 tick 无界增长）。
+        const maxInFlight = job.maxInFlight ?? 1;
+        const track = maxInFlight === Number.POSITIVE_INFINITY ? undefined : job.inFlight;
+        if (track) {
+            this.pruneInFlight(track);
+            if (track.size >= maxInFlight)
+                return;
+        }
+        // 'at' 单发：有 prefix 则用固定键（同次重复提交去重）；周期任务用窗口键
+        const idempotencyKey = job.prefix
+            ? job.kind === 'every'
+                ? `${job.prefix}:${Math.floor(Date.now() / (job.intervalMs ?? 1))}`
+                : job.prefix
+            : undefined;
+        try {
+            const rec = this.runner.submit(job.input, {
+                idempotencyKey,
+                options: job.options,
+                source: job.source ?? `schedule:${job.id.slice(0, 8)}`,
+            });
+            // 追踪未终态的派发（去重命中已有终态记录时不计入）
+            if (track && (rec.status === 'queued' || rec.status === 'running')) {
+                track.add(rec.taskId);
+            }
+        }
+        catch (e) {
+            // 调度触发不应崩掉宿主进程：入参非法等以 console 形式暴露
+            console.error(`[agentia:scheduler] ${job.id} 触发失败`, e?.message ?? e);
+        }
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/transport/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/transport/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAkD/C,MAAM,OAAO,SAAS;IAGS,MAAM;IAFlB,IAAI,GAAG,IAAI,GAAG,EAAe,CAAC;IAE/C,YAA6B,MAAmB;sBAAnB,MAAM;IAAgB,CAAC;IAEpD,sCAAsC;IACtC,KAAK,CAAC,UAAkB,EAAE,KAAc,EAAE,IAAI,GAAyB,EAAE;QACvE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;YACpD,iDAAiD;YACjD,sCAAsC;YACtC,MAAM,IAAI,KAAK,CAAC,2CAA2C,UAAU,EAAE,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,GAAG;gBAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC,EAAE,UAAU,CAAC,CAAC;QACf,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK;YAC9C,KAAuC,CAAC,KAAK,EAAE,EAAE,CAAC;QACrD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE;YAChB,EAAE;YACF,IAAI,EAAE,OAAO;YACb,KAAK;YACL,UAAU;YACV,KAAK;YACL,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,iBAAiB;YAC9B,QAAQ,EAAE,IAAI,GAAG,EAAU;YAC3B,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC;SACnC,CAAC,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;IAC/C,CAAC;IAED,kBAAkB;IAClB,EAAE,CAAC,IAAU,EAAE,KAAc,EAAE,IAAI,GAAyB,EAAE;QAC5D,IAAI,CAAC,CAAC,IAAI,YAAY,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YAChE,uDAAuD;YACvD,MAAM,IAAI,KAAK,CAAC,+CAA+C,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACvD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACrB,IAAI,GAAG;gBAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC,EAAE,KAAK,CAAC,CAAC;QACV,4CAA4C;QAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK;YAC9C,KAAuC,CAAC,KAAK,EAAE,EAAE,CAAC;QACrD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE;YAChB,EAAE;YACF,IAAI,EAAE,IAAI;YACV,KAAK;YACL,KAAK;YACL,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,iBAAiB;SAC/B,CAAC,CAAC;QACH,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;IAC/C,CAAC;IAED,MAAM,CAAC,EAAU;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,YAAY,CAAC,GAAG,CAAC,KAAsC,CAAC,CAAC;QACzD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC;IAED,IAAI;QACF,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,mDAAmD;IAC3C,aAAa,CAAC,QAAqB;QACzC,MAAM,MAAM,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC3D,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrC,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpB,KAAK,GAAG;qBACL,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE;oBACV,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ;wBAAE,MAAM,CAAC,MAAM,CAAC,CAAC;gBAC9E,CAAC,CAAC;qBACD,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,kBAAkB;gBAClD,SAAS;YACX,CAAC;YACD,MAAM,CAAC,GAAG,GAAsC,CAAC;YACjD,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ;gBAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;IAEO,QAAQ,CAAC,GAAQ;QACvB,+CAA+C;QAC/C,4CAA4C;QAC5C,mDAAmD;QACnD,MAAM,WAAW,GAAG,GAAG,CAAC,WAAW,IAAI,CAAC,CAAC;QACzC,MAAM,KAAK,GAAG,WAAW,KAAK,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;QAClF,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,KAAK,CAAC,IAAI,IAAI,WAAW;gBAAE,OAAO;QACxC,CAAC;QACD,4CAA4C;QAC5C,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM;YAC/B,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,OAAO;gBACpB,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE;gBACnE,CAAC,CAAC,GAAG,CAAC,MAAM;YACd,CAAC,CAAC,SAAS,CAAC;QACd,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE;gBACxC,cAAc;gBACd,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE;aACvD,CAAC,CAAC;YACH,2BAA2B;YAC3B,IAAI,KAAK,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,EAAE,CAAC;gBACnE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,mCAAmC;YACnC,OAAO,CAAC,KAAK,CAAC,uBAAuB,GAAG,CAAC,EAAE,OAAO,EAAG,CAAW,EAAE,OAAO,IAAI,CAAC,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;CACF"}

package/dist/transport/sse.d.ts

@@ -0,0 +1,43 @@
+import type { ServerResponse } from 'node:http';
+/**
+ * Agentia —— SSE（Server-Sent Events）写出器（零依赖）。
+ *
+ * 帧格式：`event: <name>\ndata: <json>\n\n`；注释帧 `: <text>\n\n` 用作心跳
+ * （长时间无数据时中间代理会掐连接）。
+ *
+ * 语义约束（调用方必须知道）：**一旦写出响应头，HTTP 状态码就定了**（200）。
+ * 之后的错误只能以 `error` 事件表达，不能再改成 4xx/5xx —— 所以流开之前的
+ * 校验（方法 / 并发闸门 / body 解析）必须先做，那些用普通 HTTP 状态码回。
+ *
+ * **背压**：`res.write()` 在 socket 发送缓冲写满时返回 `false`，此时 Node 仍会把
+ * 后续数据留在内存里排队 —— 一个「连得上但不读」的客户端能凭一条 SSE 连接把宿主
+ * 内存吃光（逐 token 下发时尤其快）。所以这里盯着 `res.writableLength`，超过
+ * `maxBufferedBytes` 即收口：不再无限缓冲，并回调 `onBackpressure`（宿主据此中止
+ * 对应 run，别继续为空耗 token）。做的是**有界缓冲 + 超限收口**，不是静默丢帧 ——
+ * 丢帧会让客户端拿到看起来正常、实则残缺的输出。
+ */
+export interface SseWriter {
+    /** 写一个事件帧（data 走 JSON.stringify）；已关闭或积压超限时为 no-op */
+    event(name: string, data: unknown): void;
+    /** 写一个注释帧（心跳） */
+    comment(text: string): void;
+    /** 结束响应；之后再 event/comment 都是 no-op */
+    close(): void;
+    /** 响应是否已关闭 */
+    readonly closed: boolean;
+}
+export interface SseWriterOptions {
+    /**
+     * 下游积压上限（字节），按 `res.writableLength` 计；缺省 8 MiB。
+     * 正常客户端远达不到，实际只拦「连上但不读」的病态消费者。
+     */
+    maxBufferedBytes?: number;
+    /** 因积压超限而收口时回调（收口**先于**回调发生，回调抛错不影响收口） */
+    onBackpressure?: (info: {
+        bufferedBytes: number;
+        limitBytes: number;
+    }) => void;
+}
+/** 缺省积压上限：8 MiB —— 一条 8 MiB 都没被读走的流，已经不是「慢」而是「断了」 */
+export declare const SSE_DEFAULT_MAX_BUFFERED_BYTES: number;
+export declare function sseWriter(res: ServerResponse, opts?: SseWriterOptions): SseWriter;