berry-agent-sdk 0.1.0-alpha.2

package/dist/packages/berry-agent-sdk/src/stdio.js

@@ -0,0 +1,238 @@
+/**
+ * berry-agent-sdk/stdio — spawn serve stdio 传输（批 13f-3）。
+ *
+ * spawn 子进程（缺省 process.execPath + 调用方给 args——serve 形态如
+ * `['<主包>/dist/host/main.js', 'serve']`，安装布局由调用方知悉、本件不猜）、
+ * stdin/stdout 行帧 NDJSON（编解码复用主仓 channels jsonl 件——行安全转义
+ * 与分帧单源，零第二套）。
+ *
+ * 建立即连接级握手（03 §10.6 ⑤ 定形补笔）：spawn 后先发 sessionId 缺席的
+ * 连接级 hello（宿主 wire-core 连接级档——零订阅纯握手，应答 hello 帧回携
+ * protocolVersion 双方比对），先于任何请求帧（串行链头位保证）；版本不符
+ * 即毒丸化 fail-loud 拒用传输（此后一切事务面携 SDK_PROTOCOL_MISMATCH 拒）。
+ *
+ * 帧归属纪律：线协议无请求 id ⇒ 事务串行链（一次一事务——前一事务应答落定
+ * 才发下一笔）；在队帧〔event/heartbeat/ask/重放 entries/replay-end〕入当前
+ * 订阅监听面。订阅建立 = hello 帧（取快照高水位）→ replay-end（衔接界标即
+ * resolve 位；界标帧本身也入监听面——重放段全量承诺）两段同事务。
+ *
+ * 终局纪律（03 §10.6 传输腿错误面定形补笔①）：子进程终局（exit/error/close）
+ * → 在飞事务 fail-loud 拒绝（SDK_TRANSPORT 含退出码）并清 inflight——串行链
+ * 自动续走（防前一事务不落定致整链静默挂死）；终局后的新事务同律即拒。
+ */
+import { spawn } from 'node:child_process';
+import { decodeWireLine, encodeWireLine, isSdkRequest, splitWireLines } from '../../../src/channels/sdk/jsonl.js';
+import { SDK_PROTOCOL_VERSION } from '../../../src/channels/sdk/protocol.js';
+import { SdkError } from './types.js';
+/** 各动词的应答帧闭集（帧归属判据——事务串行 + 服务端同步受理语义下单调） */
+const EXPECTED_KINDS = {
+    prompt: ['ack', 'error'],
+    getEntries: ['entries', 'error'],
+    sessions: ['sessions', 'error'],
+    decide: ['decide-result', 'error'],
+};
+/** spawn serve 子进程并建传输 */
+export function spawnServeTransport(options) {
+    const warn = options.onWarn ?? (() => { });
+    const child = spawn(options.command ?? process.execPath, [...options.args], {
+        env: options.env ?? process.env,
+        cwd: options.cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    // —— 入站环：分帧（跨 chunk 安全）→ 解码（fail-loud 坏行跳过不崩）→ 归属 ——
+    let remainder = '';
+    let liveListener;
+    /** 在队事务（串行链保证至多一笔）——expect 帧族命中即 resolve；终局兜底走 reject（fail-loud） */
+    let inflight;
+    const deliver = (frame) => {
+        if (inflight !== undefined && inflight.expect.has(frame.kind)) {
+            const done = inflight;
+            inflight = undefined;
+            done.resolve(frame);
+            return;
+        }
+        liveListener?.(frame); // 直播/重放/心跳帧——订阅面
+    };
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+        const split = splitWireLines(chunk, remainder);
+        remainder = split.remainder;
+        for (const line of split.lines) {
+            try {
+                const decoded = decodeWireLine(line);
+                // 出站方向只有帧——请求形属协议违约（反向帧），跳过不崩
+                if (isSdkRequest(decoded)) {
+                    warn(`反向帧跳过（客户端不应收请求形）：${line}`);
+                    continue;
+                }
+                deliver(decoded);
+            }
+            catch (err) {
+                warn(`坏行跳过：${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => options.onStderr?.(chunk));
+    // stdin 写侧防御监听：子进程先亡后的残写（EPIPE 等平台形）归因诊断面——
+    // 无 error 监听的流错误以未捕获异常打崩 SDK 消费进程（本平台静默丢弃、他平台防御）
+    child.stdin.on('error', (err) => {
+        warn(`stdin 写失败：${err instanceof Error ? err.message : String(err)}`);
+    });
+    // —— 事务串行链：一次一事务（帧归属在结构上无歧义——线协议无请求 id）——
+    let chain = Promise.resolve();
+    const serialize = (transaction) => {
+        const next = chain.then(transaction, transaction);
+        chain = next.catch(() => { }); // 链不断——前事务失败不阻塞后事务
+        return next;
+    };
+    /** 单帧应答事务：写请求、挂期望帧族、等归属命中；门检先行（毒丸/终局即 fail-loud 拒） */
+    const roundTrip = (req, expect) => serialize(() => new Promise((resolve, reject) => {
+        const gate = transactionGate();
+        if (gate !== undefined) {
+            reject(gate);
+            return;
+        }
+        inflight = { expect: new Set(expect), resolve, reject };
+        child.stdin.write(encodeWireLine(req));
+    }));
+    // —— 终局：exit 正常位；spawn 失败形（ENOENT 等）exit 不触发——error/close 兜底 -1 ——
+    let exited = false;
+    let exitCode; // 终局码（门检报因携带——settle 内先于 exited 置位）
+    const exitedPromise = new Promise((resolve) => {
+        const settle = (code) => {
+            if (exited)
+                return;
+            exitCode = code;
+            exited = true;
+            // 终局 → 在飞事务 fail-loud 拒（03 §10.6 定形补笔①：SDK_TRANSPORT 含退出码）；
+            // 清 inflight 使串行链自动续走——防前一事务不落定致整链静默挂死
+            const pending = inflight;
+            inflight = undefined;
+            pending?.reject(new SdkError('SDK_TRANSPORT', `子进程已退出（code=${code}）——在飞事务无法落定`));
+            resolve(code);
+        };
+        child.on('exit', (code) => settle(code ?? 0));
+        child.on('error', () => settle(-1));
+        child.on('close', (code) => settle(code ?? -1)); // spawn 失败形 exit 缺席 close 补位
+    });
+    // —— 建立即连接级握手（03 §10.6 ⑤ 定形补笔）：串行链头位——先于任何请求帧 ——
+    let handshakeError; // 版本错配毒丸——此后一切事务面 fail-loud 拒用传输
+    /** 事务面门检（fail-loud 先于写 stdin）：毒丸/终局任一在场即拒新事务 */
+    const transactionGate = () => {
+        if (handshakeError !== undefined)
+            return handshakeError;
+        if (exited)
+            return new SdkError('SDK_TRANSPORT', `子进程已退出（code=${exitCode}）——传输不可再用`);
+        return undefined;
+    };
+    const handshake = serialize(() => new Promise((resolve, reject) => {
+        const gate = transactionGate(); // 构造后立即 close / 子进程瞬亡形——握手本身即拒
+        if (gate !== undefined) {
+            handshakeError = gate;
+            reject(gate);
+            return;
+        }
+        inflight = {
+            expect: new Set(['hello', 'error']),
+            resolve: (frame) => {
+                if (frame.kind === 'error') {
+                    // 宿主版本闸（⑤ 不符即拒连）——错误帧原码投形毒丸化
+                    const err = new SdkError(frame.code, frame.message);
+                    handshakeError = err;
+                    reject(err);
+                    return;
+                }
+                // 应答 hello 帧回携 protocolVersion——客户端侧比对（⑤「双方携版本比对」）
+                const serverVersion = frame.protocolVersion;
+                if (serverVersion !== SDK_PROTOCOL_VERSION) {
+                    const err = new SdkError('SDK_PROTOCOL_MISMATCH', `线协议版本不符：服务端 ${serverVersion} / 调用方 ${SDK_PROTOCOL_VERSION}`);
+                    handshakeError = err;
+                    reject(err);
+                    return;
+                }
+                resolve();
+            },
+            reject: (err) => {
+                // 握手期子进程终局（settle 兜底 reject）——同毒丸拒用
+                handshakeError = err;
+                reject(err);
+            },
+        };
+        child.stdin.write(encodeWireLine({ verb: 'hello', protocolVersion: SDK_PROTOCOL_VERSION }));
+    }));
+    // 握手失败即 best-effort 收线子进程（连接已不可用——不等优雅 EOF 退出序；已亡形 kill 为 no-op）
+    handshake.catch(() => {
+        child.kill();
+    });
+    /** 订阅收口（stdio 形：线无退订动词——记客户端口径，监听面回置空） */
+    const liveClose = async () => {
+        liveListener = undefined;
+    };
+    // —— 收口（幂等）：收线 + 监听解挂；终局 = 子进程退出码 ——
+    let closed = false;
+    const transport = {
+        exited: exitedPromise,
+        request: (req) => {
+            const expect = EXPECTED_KINDS[req.verb];
+            if (expect === undefined) {
+                // hello/interrupt 非单帧事务位（hello = openLive 两段、interrupt = send 无应答）
+                return Promise.reject(new SdkError('SDK_TRANSPORT', `动词 ${req.verb} 不走请求档（hello→subscribe / interrupt→send）`));
+            }
+            return roundTrip(req, expect);
+        },
+        send: (req) => serialize(async () => {
+            // 事务面门检同律：终局/毒丸后写 stdin 是伪成功——诚实拒
+            const gate = transactionGate();
+            if (gate !== undefined)
+                throw gate;
+            child.stdin.write(encodeWireLine(req));
+        }),
+        openLive: (params, onFrame) => serialize(() => new Promise((resolve, reject) => {
+            const gate = transactionGate();
+            if (gate !== undefined) {
+                reject(gate);
+                return;
+            }
+            liveListener = onFrame;
+            let highWaterSeq = -1;
+            // 订阅两段同事务：hello（快照高水位）→ replay-end（衔接界标即建立点）
+            inflight = {
+                expect: new Set(['hello', 'error']),
+                resolve: (frame) => {
+                    if (frame.kind === 'error') {
+                        reject(new SdkError(frame.code, frame.message));
+                        return;
+                    }
+                    highWaterSeq = frame.highWaterSeq;
+                    inflight = {
+                        expect: new Set(['replay-end']),
+                        resolve: (marker) => {
+                            onFrame(marker); // 界标帧入监听面（重放段全量承诺）后再立柄
+                            resolve({ sessionId: params.sessionId, highWaterSeq, close: liveClose });
+                        },
+                        reject, // 建立期终局兜底（replay-end 前）——订阅建立 Promise 不得悬挂
+                    };
+                },
+                reject,
+            };
+            child.stdin.write(encodeWireLine({
+                verb: 'hello',
+                protocolVersion: SDK_PROTOCOL_VERSION,
+                sessionId: params.sessionId,
+                ...(params.after !== undefined ? { after: params.after } : {}),
+                ...(params.noDelta !== undefined ? { noDelta: params.noDelta } : {}),
+            }));
+        })),
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            liveListener = undefined;
+            child.stdin.end(); // 收线（EOF——serve 优雅退出序）
+            await exitedPromise;
+        },
+    };
+    return transport;
+}
+//# sourceMappingURL=stdio.js.map

package/dist/packages/berry-agent-sdk/src/stdio.js.map

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

package/dist/packages/berry-agent-sdk/src/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * berry-agent-sdk/types — 客户端契约面（批 13f-3 契约先行）。
+ *
+ * 类型面单源（03 §10.6 批 13f 落码定形）：线协议词面自 channels 协议件
+ * 相对导入 re-export、事件/审批词面自 contracts 相对导入 re-export——构建
+ * 时编译入包（同仓单源、零拷贝漂移，「生成」的实质即此）。策展式点名
+ * re-export（非整桶）：发布物的公共面是稳定 API，进什么出什么逐项过目。
+ *
+ * 传输抽象（两形态同面）：请求档〔单帧应答事务、串行〕/ 无应答档
+ * 〔interrupt——stdio 写后即决、HTTP 形 204〕/ 直播档〔stdio = 线内 hello、
+ * HTTP = GET /v1/events SSE——重放帧与直播帧一律入 onFrame；订阅在
+ * replay-end 落定后 resolve（衔接界标即建立点）〕。
+ */
+import type { ApprovalAskAnswer } from '../../../src/contracts/approval.js';
+import type { SdkAckFrame, SdkEntriesFrame, SdkRequest, SdkSessionSummary, SdkWireFrame } from '../../../src/channels/sdk/protocol.js';
+/** 线事件词面（04 §2 十型——live 帧载荷） */
+export type { AgentEvent } from '../../../src/agent/events.js';
+/** 审批应答四值闭集（decide 动词入参） */
+export type { ApprovalAskAnswer } from '../../../src/contracts/approval.js';
+/** 线协议请求族（六动词——手工构造进阶位；常规用法走 client 方法面） */
+export type { SdkRequest } from '../../../src/channels/sdk/protocol.js';
+/** 线帧全族（kind 判别联合——onFrame 消费面 pattern-match 用） */
+export type { SdkWireFrame } from '../../../src/channels/sdk/protocol.js';
+/** 受理回执帧（prompt 应答——sessionId/duplicate/highWaterSeq） */
+export type { SdkAckFrame } from '../../../src/channels/sdk/protocol.js';
+/** durable 投影页帧（getEntries 应答） */
+export type { SdkEntriesFrame } from '../../../src/channels/sdk/protocol.js';
+/** 会话清单行（sessions 应答元素） */
+export type { SdkSessionSummary } from '../../../src/channels/sdk/protocol.js';
+/** durable 平铺事件（type/seq/time/data 四字段——重放与轮询共形） */
+export type { SdkDurableEntry } from '../../../src/channels/sdk/protocol.js';
+/** live 事件帧（event + seq——直播段载荷） */
+export type { SdkEventFrame } from '../../../src/channels/sdk/protocol.js';
+/** hello 应答帧（订阅建立序首帧——highWaterSeq 快照位） */
+export type { SdkHelloFrame } from '../../../src/channels/sdk/protocol.js';
+/** 错误帧（code/message——线面业务错词面） */
+export type { SdkErrorFrame } from '../../../src/channels/sdk/protocol.js';
+/** 线协议版本（握手常量——与主包同一源） */
+export { SDK_PROTOCOL_VERSION } from '../../../src/channels/sdk/protocol.js';
+/** 业务错（线面错误帧的客户端投形——code 为 SDK_ 族/SESSION_* 线词面） */
+export declare class SdkError extends Error {
+    /** 线面错误码（SDK_PROTOCOL_MISMATCH / SESSION_NOT_FOUND / …） */
+    readonly code: string;
+    /** 关联会话（错误帧在场时透传——缺席 undefined） */
+    readonly sessionId?: string | undefined;
+    constructor(
+    /** 线面错误码（SDK_PROTOCOL_MISMATCH / SESSION_NOT_FOUND / …） */
+    code: string, message: string, 
+    /** 关联会话（错误帧在场时透传——缺席 undefined） */
+    sessionId?: string | undefined);
+}
+/** 直播帧监听面（重放段〔entries/replay-end〕与直播段〔event/heartbeat/ask〕一律入此） */
+export type SdkFrameListener = (frame: SdkWireFrame) => void;
+/** 订阅参数（= hello 动词载荷——after = 断线续读位、noDelta = 剥 delta） */
+export interface SdkLiveParams {
+    readonly sessionId: string;
+    /** 重放起点（已收末条 seq——窗口 (after, 高水位]；缺席 -1 从头） */
+    readonly after?: number;
+    /** 剥 message_update delta 帧（07 §5 --no-delta 客户端立场） */
+    readonly noDelta?: boolean;
+}
+/** 直播订阅柄（replay-end 落定后建立——close 退订〔stdio 形线内续用不受影响〕） */
+export interface SdkLiveHandle {
+    readonly sessionId: string;
+    /** 订阅序首帧的快照高水位（衔接界标前的 durable 水位——对账起点参考） */
+    readonly highWaterSeq: number;
+    /** 退订（幂等）：stdio 形仅记客户端口径〔线协议无退订动词——close 整连接即退〕、HTTP 形关 SSE 流 */
+    close(): Promise<void>;
+}
+/**
+ * 传输抽象（spawn stdio / 直连 HTTP 两实装同面）。
+ *
+ * 事务串行纪律：request/openLive 一次一事务（前一事务应答落定才发下一笔）
+ * ——线协议无请求 id，串行化使帧归属在结构上无歧义（乱序并发进阶位不采）。
+ */
+export interface SdkTransport {
+    /** 请求档：发一动词、取应答帧（错误帧原样返回不抛——由 client 投形 SdkError） */
+    request(req: SdkRequest): Promise<SdkWireFrame>;
+    /** 无应答档（interrupt——受理经事件流可观察：错误帧走 onFrame 面） */
+    send(req: SdkRequest): Promise<void>;
+    /** 直播档建立：重放帧与直播帧入 onFrame；replay-end 后 resolve 订阅柄 */
+    openLive(params: SdkLiveParams, onFrame: SdkFrameListener): Promise<SdkLiveHandle>;
+    /** 整连接收口（幂等）：stdio 形收线子进程、HTTP 形关连接池面 */
+    close(): Promise<void>;
+}
+/** prompt 入参（messageId 缺省 = 客户端计数器形 `sdk-N` 每次全新——幂等语义未申请即不虚构） */
+export interface SdkPromptInput {
+    /** 续接会话句柄——缺席即新建 */
+    readonly sessionId?: string;
+    /** 幂等键（同键同内容重发收 duplicate 收执）——缺席计数器形全新 */
+    readonly messageId?: string;
+    readonly content: string;
+}
+/** getEntries 入参（since 缺省 -1 从头全窗；cursor = 分页续读游标——SDK 面亦透传） */
+export interface SdkEntriesInput {
+    readonly sessionId: string;
+    readonly since?: number;
+    /** 分页续读游标（上一页 entries 帧 nextCursor 在场即携之续读——跟尽义务的回送位，分页帽落地时可跟尽） */
+    readonly cursor?: string;
+}
+/** 类型化客户端（传输无关面——两传输同方法面消费） */
+export interface SdkClient {
+    /** 会话发起/续接（→ ack 应答：会话句柄 + 受理回执）；错误帧 → 抛 {@link SdkError} */
+    prompt(input: SdkPromptInput): Promise<SdkAckFrame>;
+    /** 断线对账读面（→ entries 页帧）；跟尽义务在调用方（nextCursor 在场即续读——cursor 位透传，分页帽落地时可跟尽） */
+    getEntries(input: SdkEntriesInput): Promise<SdkEntriesFrame>;
+    /** 会话清单 */
+    sessions(): Promise<SdkSessionSummary[]>;
+    /** 打断在飞 run（无应答档——写后即决；missing 会话错误帧走订阅帧面） */
+    interrupt(sessionId: string): Promise<void>;
+    /** 审批应答（跨入口竞速回执——applied / superseded） */
+    decide(approvalId: string, answer: ApprovalAskAnswer, note?: string): Promise<'applied' | 'superseded'>;
+    /** 直播订阅（= hello 动词承载位——重放→衔接→直播；帧全量入 onFrame） */
+    subscribe(params: SdkLiveParams, onFrame: SdkFrameListener): Promise<SdkLiveHandle>;
+    /** 整连接收口（幂等） */
+    close(): Promise<void>;
+}

package/dist/packages/berry-agent-sdk/src/types.js

@@ -0,0 +1,19 @@
+/** 线协议版本（握手常量——与主包同一源） */
+export { SDK_PROTOCOL_VERSION } from '../../../src/channels/sdk/protocol.js';
+/* ---------------- 客户端契约 ---------------- */
+/** 业务错（线面错误帧的客户端投形——code 为 SDK_ 族/SESSION_* 线词面） */
+export class SdkError extends Error {
+    code;
+    sessionId;
+    constructor(
+    /** 线面错误码（SDK_PROTOCOL_MISMATCH / SESSION_NOT_FOUND / …） */
+    code, message, 
+    /** 关联会话（错误帧在场时透传——缺席 undefined） */
+    sessionId) {
+        super(`[${code}] ${message}`);
+        this.code = code;
+        this.sessionId = sessionId;
+        this.name = 'SdkError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/packages/berry-agent-sdk/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/types.ts"],"names":[],"mappings":"AA8CA,0BAA0B;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAE7E,6CAA6C;AAE7C,oDAAoD;AACpD,MAAM,OAAO,QAAS,SAAQ,KAAK;IAGtB;IAGA;IALX;IACE,2DAA2D;IAClD,IAAY,EACrB,OAAe;IACf,mCAAmC;IAC1B,SAAkB;QAE3B,KAAK,CAAC,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QALrB,SAAI,GAAJ,IAAI,CAAQ;QAGZ,cAAS,GAAT,SAAS,CAAS;QAG3B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF"}

package/dist/src/agent/events.d.ts

@@ -0,0 +1,11 @@
+/**
+ * agent 件 — AgentEvent 活体事件族（04 篇 §2 机制真源）。
+ *
+ * 归位注记（2026-09-08 U3 落码批）：类型族（RunStatus/DeliverChannel/
+ * AgentEvent/AgentEventSink）归位 contracts/agent-events.ts——插件侧 UI 后端
+ * 类型可达（03 §2.2 registerUiBackend 定形注记：虚拟主键 `berry-agent` 面只达
+ * contracts）；本件 re-export 维持 agent 公开面与件内消费路径不变（批 11b
+ * ApprovalAsk 归位同款先例）。顺序铁律与活体流纪律的成文真源随类型走
+ * （contracts/agent-events.ts 件头）。
+ */
+export type { AgentEvent, AgentEventSink, DeliverChannel, RunStatus } from '../contracts/index.js';

package/dist/src/agent/events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=events.js.map

package/dist/src/agent/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../../../src/agent/events.ts"],"names":[],"mappings":""}

package/dist/src/agent/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * agent 件公开面（loop 骨架 + 三通道队列 + 活体事件；04 篇 §2/§4）。
+ *
+ * 单向 DAG：agent → contracts 唯一边（不 import llm/session/context——02 篇
+ * §4.2 关键不依赖第一条的码面执法）。驱动侧（conversation 件）经 startRun
+ * 入口消费（seeds 空数组 = 纯续入）；continueRun 为恢复续入形第二入口
+ * （04 §2 入口两式）。PendingMessageQueue 是三通道暂存机制件。
+ */
+export type { AgentContext, AgentLoopConfig, BeforeToolCallDecision, TurnAdjustment, RunResult, EmitFn, } from './types.js';
+export type { RunStatus, DeliverChannel, AgentEvent, AgentEventSink } from './events.js';
+export type { QueueMode, OverflowPolicy, PendingItem, EnqueueReceipt } from './queue.js';
+export { PendingMessageQueue, DEFAULT_QUEUE_CAPACITY } from './queue.js';
+export { startRun, continueRun } from './loop.js';

package/dist/src/agent/index.js

@@ -0,0 +1,3 @@
+export { PendingMessageQueue, DEFAULT_QUEUE_CAPACITY } from './queue.js';
+export { startRun, continueRun } from './loop.js';
+//# sourceMappingURL=index.js.map

package/dist/src/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/agent/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/agent/loop.d.ts

@@ -0,0 +1,19 @@
+/**
+ * agent 件 — loop 骨架（04 §2 形态铁律：双 while、≤150 行、零 try/catch、零存储感知）。
+ * 外层 turn 循环：steering 注入 → 流消费 → 终态判定 → 工具批 → followUp 续跑裁决。
+ * 内层流消费与工具批执行分别住在 stream.ts / tools-batch.ts（骨架只留控制流）。
+ * 全部策略经注入回调（AgentLoopConfig 12 项）、全部状态经活体事件回流——
+ * loop 不知道 conversation 存在；错误不就地 try/catch（StreamFn 永不抛契约），失败由 run 终态承载（04 §2/§3）。
+ */
+import type { AgentMessage } from '../contracts/index.js';
+import type { AgentContext, AgentLoopConfig, RunResult } from './types.js';
+/**
+ * 种子起跑：seeds 逐条入列（用户直发——channel 缺省）后进主循环。
+ * @param context 运行上下文（messages 活数组） @param config 回调面 @param seeds 种子消息（缺省空）
+ */
+export declare function startRun(context: AgentContext, config: AgentLoopConfig, seeds?: AgentMessage[]): Promise<RunResult>;
+/**
+ * 续入起跑：末角色校验（经 convertToLlm 转换后须 user/toolResult——违者
+ * AGENT_CONTINUE_INVALID fail-loud，防把 assistant 尾直接重发 provider）。
+ */
+export declare function continueRun(context: AgentContext, config: AgentLoopConfig): Promise<RunResult>;

package/dist/src/agent/loop.js

@@ -0,0 +1,140 @@
+/**
+ * agent 件 — loop 骨架（04 §2 形态铁律：双 while、≤150 行、零 try/catch、零存储感知）。
+ * 外层 turn 循环：steering 注入 → 流消费 → 终态判定 → 工具批 → followUp 续跑裁决。
+ * 内层流消费与工具批执行分别住在 stream.ts / tools-batch.ts（骨架只留控制流）。
+ * 全部策略经注入回调（AgentLoopConfig 12 项）、全部状态经活体事件回流——
+ * loop 不知道 conversation 存在；错误不就地 try/catch（StreamFn 永不抛契约），失败由 run 终态承载（04 §2/§3）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { streamAssistantResponse } from './stream.js';
+import { executeToolBatch } from './tools-batch.js';
+/** 种子/续跑消息入列（steering 顶注与 followUp 续跑共用——channel 随事件披露） */
+function pushAll(context, messages, emit, channel) {
+    for (const message of messages) {
+        context.messages.push(message);
+        emit({ type: 'message_start', role: message.role, ...(channel ? { channel } : {}) });
+        emit({ type: 'message_end', message, ...(channel ? { channel } : {}) });
+    }
+}
+/** assistant 内联 toolCall 块直取（工具批与截断配对的公共提取面） */
+function toolCallsOf(message) {
+    return message.content.filter((block) => block.type === 'toolCall');
+}
+/**
+ * 种子起跑：seeds 逐条入列（用户直发——channel 缺省）后进主循环。
+ * @param context 运行上下文（messages 活数组） @param config 回调面 @param seeds 种子消息（缺省空）
+ */
+export function startRun(context, config, seeds = []) {
+    const emit = (event) => void config.onEvent?.(event);
+    pushAll(context, seeds, emit);
+    return runLoop(context, config, emit);
+}
+/**
+ * 续入起跑：末角色校验（经 convertToLlm 转换后须 user/toolResult——违者
+ * AGENT_CONTINUE_INVALID fail-loud，防把 assistant 尾直接重发 provider）。
+ */
+export function continueRun(context, config) {
+    const last = context.messages[context.messages.length - 1];
+    const converted = last === undefined ? null : config.convertToLlm(last);
+    const role = Array.isArray(converted) ? converted[converted.length - 1]?.role : converted?.role;
+    if (role !== 'user' && role !== 'toolResult') {
+        throw new BaseError('AGENT_CONTINUE_INVALID', `continueRun 末角色校验红：转换后末角色为 ${String(role ?? '空')}（须 user/toolResult——恢复续入的上下文形状前提）`);
+    }
+    return runLoop(context, config, (event) => void config.onEvent?.(event));
+}
+/** 主循环（双 while 的外层本体——内层流消费在 streamAssistantResponse 内） */
+async function runLoop(context, config, emit) {
+    emit({ type: 'agent_start' });
+    let turn = 0;
+    let stopReason;
+    let errorMessage;
+    while (true) {
+        // turn 顶：steering 注入（busy 中插入的消息进本轮上下文）——消费点在
+        // preModelRequest 之前（同步零让出）：await 窗若先于消费点，busy 期
+        // submit 会漂移进 steer 通道（本应 followUp 尾声消费——通道语义时序
+        // 回归锁见 driver.test 队列通道族）
+        pushAll(context, config.getSteeringMessages?.() ?? [], emit, 'steer');
+        // 模型请求前检查（03 §2.4 agent_pre_step 窗——'stop' 刹停零 dangling turn）：
+        // 位置 = steering 消费后、turn_start 前（steering 注入属上下文组装非模型
+        // 请求；刹停时 steer 件已落 durable 由下次 run 重播种承载）
+        if ((await config.preModelRequest?.(context)) === 'stop') {
+            stopReason = 'stop';
+            break;
+        }
+        turn += 1;
+        emit({ type: 'turn_start', turn });
+        const assistant = await streamAssistantResponse(config, context, emit);
+        stopReason = assistant.stopReason;
+        errorMessage = assistant.errorMessage;
+        // 中止竞速败者形重归因：pi-ai 层 response promise 与 abort 信号竞速——败者形 =
+        // stopReason 'error' + errorMessage 系 AbortError 文案（'This operation was aborted'
+        // 等）。signal 已 aborted 即实证善意中止在途（issue watchdog 预算帽 / TUI Esc /
+        // webui stop），重归因 aborted——消费面善意词面（『每 issue 预算帽耗尽』等）全靠
+        // aborted 分支承载。窄判据三合一（缺一不触发）：error + signal.aborted + abort 文案
+        // ——真 error（网络断等）不受泛化误伤。
+        if (stopReason === 'error' &&
+            config.signal?.aborted === true &&
+            errorMessage !== undefined &&
+            /abort/i.test(errorMessage)) {
+            stopReason = 'aborted';
+        }
+        emit({ type: 'turn_end', turn, stopReason });
+        // 终态短路：error/aborted → run 收场（status 映射见函数尾）
+        if (assistant.stopReason === 'error' || assistant.stopReason === 'aborted')
+            break;
+        // 截断防御：length → 整批配对 isError 后收 failed（残缺批不进下一轮）
+        if (assistant.stopReason === 'length') {
+            errorMessage = assistant.errorMessage ?? '输出被上下文窗口截断（stopReason=length）';
+            pushAll(context, toolCallsOf(assistant).map((call) => ({
+                role: 'toolResult',
+                toolCallId: call.id,
+                toolName: call.name,
+                content: [{ type: 'text', text: '输出被上下文窗口截断——整批配对收口，不进下一轮' }],
+                isError: true,
+                timestamp: Date.now(),
+            })), emit);
+            break;
+        }
+        if (assistant.stopReason === 'toolUse') {
+            const outcome = await executeToolBatch(config, context, toolCallsOf(assistant), emit);
+            pushAll(context, outcome.results, emit);
+            if (outcome.terminate)
+                break; // 批内一致 terminate → 优雅停
+        }
+        // turn 终止裁决（停止词/预算尽/打断）——先于 followUp 消费：停则留在驱动侧队列不入列
+        if (await config.shouldStopAfterTurn?.(context, assistant))
+            break;
+        if (assistant.stopReason !== 'toolUse') {
+            // stop/deferred：followUp 是 idle 起跑通道——空即自然停 completed
+            const followUps = config.getFollowUpMessages?.() ?? [];
+            if (followUps.length === 0)
+                break;
+            pushAll(context, followUps, emit, 'followUp');
+        }
+        // turn 间准备窗：换 model/thinkingLevel 唯一时机（todo/goal 注入同窗）。
+        // 实况注记（2026-09-11 定形）：换档只改内存 config 不落 session/thinking-level
+        // durable 事件——该词 v1 词先锚定（05 §1.1 在册、写点随会话档位切换面立题；
+        // 冷启动恢复走栈级静态 options.thinkingLevel）
+        const adjustment = await config.prepareNextTurn?.(context);
+        if (adjustment) {
+            if (adjustment.model !== undefined)
+                config.model = adjustment.model;
+            if (adjustment.thinkingLevel !== undefined)
+                config.thinkingLevel = adjustment.thinkingLevel;
+        }
+    }
+    // 终态映射：error/length → failed；aborted → aborted；其余（stop/toolUse/deferred）→ completed
+    const status = stopReason === 'error' || stopReason === 'length' ? 'failed' : stopReason === 'aborted' ? 'aborted' : 'completed';
+    emit({
+        type: 'agent_end',
+        status,
+        ...(stopReason !== undefined ? { stopReason } : {}),
+        ...(errorMessage !== undefined ? { errorMessage } : {}),
+    });
+    return {
+        status,
+        ...(stopReason !== undefined ? { stopReason } : {}),
+        ...(errorMessage !== undefined ? { errorMessage } : {}),
+    };
+}
+//# sourceMappingURL=loop.js.map

package/dist/src/agent/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../../../../../src/agent/loop.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAMlD,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,2DAA2D;AAC3D,SAAS,OAAO,CAAC,OAAqB,EAAE,QAAwB,EAAE,IAAY,EAAE,OAA8B;IAC5G,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACrF,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,SAAS,WAAW,CAAC,OAAyB;IAC5C,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAA0B,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AAC9F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,OAAqB,EACrB,MAAuB,EACvB,QAAwB,EAAE;IAE1B,MAAM,IAAI,GAAW,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;IAC7D,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC9B,OAAO,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAqB,EAAE,MAAuB;IACxE,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACxE,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC;IAChG,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;QAC7C,MAAM,IAAI,SAAS,CACjB,wBAAwB,EACxB,8BAA8B,MAAM,CAAC,IAAI,IAAI,GAAG,CAAC,mCAAmC,CACrF,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,2DAA2D;AAC3D,KAAK,UAAU,OAAO,CAAC,OAAqB,EAAE,MAAuB,EAAE,IAAY;IACjF,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;IAC9B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,UAAkC,CAAC;IACvC,IAAI,YAAgC,CAAC;IACrC,OAAO,IAAI,EAAE,CAAC;QACZ,8CAA8C;QAC9C,iDAAiD;QACjD,gDAAgD;QAChD,0BAA0B;QAC1B,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACtE,+DAA+D;QAC/D,sDAAsD;QACtD,0CAA0C;QAC1C,IAAI,CAAC,MAAM,MAAM,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC;YACzD,UAAU,GAAG,MAAM,CAAC;YACpB,MAAM;QACR,CAAC;QACD,IAAI,IAAI,CAAC,CAAC;QACV,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;QACnC,MAAM,SAAS,GAAG,MAAM,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACvE,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC;QAClC,YAAY,GAAG,SAAS,CAAC,YAAY,CAAC;QACtC,0DAA0D;QAC1D,iFAAiF;QACjF,+DAA+D;QAC/D,uDAAuD;QACvD,+DAA+D;QAC/D,yBAAyB;QACzB,IACE,UAAU,KAAK,OAAO;YACtB,MAAM,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI;YAC/B,YAAY,KAAK,SAAS;YAC1B,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,EAC3B,CAAC;YACD,UAAU,GAAG,SAAS,CAAC;QACzB,CAAC;QACD,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;QAC7C,6CAA6C;QAC7C,IAAI,SAAS,CAAC,UAAU,KAAK,OAAO,IAAI,SAAS,CAAC,UAAU,KAAK,SAAS;YAAE,MAAM;QAClF,iDAAiD;QACjD,IAAI,SAAS,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;YACtC,YAAY,GAAG,SAAS,CAAC,YAAY,IAAI,+BAA+B,CAAC;YACzE,OAAO,CACL,OAAO,EACP,WAAW,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAqB,EAAE,CAAC,CAAC;gBACvD,IAAI,EAAE,YAAY;gBAClB,UAAU,EAAE,IAAI,CAAC,EAAE;gBACnB,QAAQ,EAAE,IAAI,CAAC,IAAI;gBACnB,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,EAAE,CAAC;gBAC7D,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;aACtB,CAAC,CAAC,EACH,IAAI,CACL,CAAC;YACF,MAAM;QACR,CAAC;QACD,IAAI,SAAS,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACvC,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC;YACtF,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACxC,IAAI,OAAO,CAAC,SAAS;gBAAE,MAAM,CAAC,uBAAuB;QACvD,CAAC;QACD,qDAAqD;QACrD,IAAI,MAAM,MAAM,CAAC,mBAAmB,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC;YAAE,MAAM;QAClE,IAAI,SAAS,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACvC,sDAAsD;YACtD,MAAM,SAAS,GAAG,MAAM,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,CAAC;YACvD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;gBAAE,MAAM;YAClC,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QAChD,CAAC;QACD,wDAAwD;QACxD,8DAA8D;QAC9D,kDAAkD;QAClD,oCAAoC;QACpC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,UAAU,EAAE,CAAC;YACf,IAAI,UAAU,CAAC,KAAK,KAAK,SAAS;gBAAE,MAAM,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;YACpE,IAAI,UAAU,CAAC,aAAa,KAAK,SAAS;gBAAE,MAAM,CAAC,aAAa,GAAG,UAAU,CAAC,aAAa,CAAC;QAC9F,CAAC;IACH,CAAC;IACD,oFAAoF;IACpF,MAAM,MAAM,GACV,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;IACpH,IAAI,CAAC;QACH,IAAI,EAAE,WAAW;QACjB,MAAM;QACN,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC,CAAC;IACH,OAAO;QACL,MAAM;QACN,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxD,CAAC;AACJ,CAAC"}