berry-agent 0.1.0-alpha.1

package/dist/llm/stream-fn.js

@@ -0,0 +1,147 @@
+/**
+ * llm — StreamFn 适配层（04 §3：pi-ai 流 → agent StreamFn 契约）。
+ *
+ * 「永不抛错」契约的实现侧：一切解析/装配失败在本层编码为流内 error 终止
+ * 事件 + stopReason='error' 的最终消息（错误是数据不是异常，loop 零 try/catch
+ * 的根基）。pi-ai 自身的 lazyStream 已把 auth/网络装配失败编码为流 error
+ * 事件，本层只补齐「模型解析失败」与「在飞帽拒绝」两个前置环节。
+ *
+ * 直通策略：messages 标准三角色零转换直通 pi-ai（同构形状，结构化赋值即可）；
+ * 工具描述仅做类型收口（parameters 已是 JSON Schema 对象）。
+ */
+// 注意：AssistantMessageEventStream 类名被 pi-ai types 的 type-only 再输出遮蔽，
+// 值只能经官方工厂函数取得（该工厂即为此用途提供——"for use in extensions"）
+import { createAssistantMessageEventStream } from '@earendil-works/pi-ai';
+import { BaseError } from '../contracts/index.js';
+/** 零用量（错误合成消息用） */
+const NO_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 };
+/**
+ * 创建 agent StreamFn（模型层整体注入 loop 的那一个函数）。
+ * @param runtime llm 运行时（Models 宿主）
+ * @param defaults 请求参数默认值（重试/采样档位，闭包持有）
+ * @param tracker per-provider 在飞计数器（04 §3.6——host 装配根与 complete
+ *        单发路共享同一份传入，「两出口同源计数」名实相符；不传 = 不限）
+ * @param hookDispatch 钩子派发段只读面（03 §3.4 执法——02 §5.3 LLM_CALL_IN_HOOK
+ *        接线：钩子 handler 执行段内流式调用即耦合死锁位，前置查命中转错误流
+ *        携码；不传 = 该执法缺席〔lib/测试形〕。02 §4.1 llm 无 host 逆边——
+ *        窗态经装配注入，本域自持同形结构副本）
+ */
+export function createStreamFn(runtime, defaults = {}, tracker, hookDispatch) {
+    return (context, options, signal) => {
+        // 钩子派发段前置查（03 §3.4）：钩子 handler 内 await 流式模型面 = 耦合
+        // 违法（fire-and-forget 尾链窗外合法——guard 深度随派发收口归零）；先于
+        // 模型解析（调用方违例与模型配置无关，最先判）
+        if (hookDispatch?.inHookDispatch() === true) {
+            return errorStream('钩子执行段禁模型调用（03 §3.4——钩子 handler 内 await 流式即耦合；起异步任务不等结果合法）', 'LLM_CALL_IN_HOOK');
+        }
+        // 模型解析失败 → 编码为错误流（永不抛错；错误在此转数据）。
+        // 文案携带 [CODE] 前缀维持人读可辨（机器判定位是 errorCode 字段）
+        let model;
+        try {
+            model = runtime.resolveModel(options.model);
+        }
+        catch (error) {
+            const baseError = error instanceof BaseError ? error : null;
+            const code = baseError?.code ? `[${baseError.code}] ` : '';
+            return errorStream(`模型解析失败：${code}${baseError?.message ?? String(error)}`, baseError?.code);
+        }
+        // 在飞帽（04 §3.6）：达帽显式拒绝——错误流带 errorCode（transient 桶，
+        // 会话层 auto-retry 退避后槽已释放重试成功）。模型解析先行是顺序必然：
+        // provider 名来自解析产物。
+        if (tracker !== undefined) {
+            const slot = tracker.tryAcquire(model.provider);
+            if (slot === null) {
+                return errorStream(`在飞请求达帽（provider=${model.provider}）：并发压力自解，会话层退避后重试`, 'LLM_INFLIGHT_LIMIT');
+            }
+            return withRelease(runtime.models.streamSimple(model, buildPiContext(context), buildPiOptions(defaults, options, signal)), slot);
+        }
+        // 事件流结构同构（12 型协议 + result()），超集兼容子集直通
+        return runtime.models.streamSimple(model, buildPiContext(context), buildPiOptions(defaults, options, signal));
+    };
+}
+/** 标准三角色零转换直通（超集兼容子集；引用同一数组，无拷贝） */
+function buildPiContext(context) {
+    return {
+        systemPrompt: context.systemPrompt,
+        messages: context.messages,
+        tools: context.tools?.map(toPiTool),
+    };
+}
+/** defaults 打底 + 具名覆盖 + signal 透传（reasoning 无 'off' 档——undefined 即关闭） */
+function buildPiOptions(defaults, options, signal) {
+    return {
+        ...defaults,
+        reasoning: options.thinkingLevel !== undefined && options.thinkingLevel !== 'off' ? options.thinkingLevel : undefined,
+        ...(options.apiKey !== undefined ? { apiKey: options.apiKey } : {}),
+        ...(signal !== undefined ? { signal } : {}),
+    };
+}
+/**
+ * 流终结释放包装（释放三保险的流侧两路）：消费面 for-await **自然耗尽**
+ * （next() 返回 done——正常结束不触发 return()）或**中途退出**（break/throw
+ * 触发迭代 return()）即释放；不迭代的消费形态走 result() 的 finally 兜底
+ * （见下）。任一路先到即减计数（slot.release 幂等，多路径只生效一次）。
+ * 转发不拦截：事件与终值原样透传。
+ */
+function withRelease(stream, slot) {
+    return {
+        [Symbol.asyncIterator]() {
+            const iterator = stream[Symbol.asyncIterator]();
+            return {
+                next: async (value) => {
+                    const r = await iterator.next(value);
+                    if (r.done)
+                        slot.release(); // 自然耗尽路：流终结即释放（不依赖消费面调 result()）
+                    return r;
+                },
+                return: (value) => {
+                    slot.release();
+                    return iterator.return?.(value) ?? Promise.resolve({ value: undefined, done: true });
+                },
+                throw: (error) => {
+                    slot.release();
+                    return iterator.throw ? iterator.throw(error) : Promise.reject(error);
+                },
+            };
+        },
+        result: async () => {
+            try {
+                return await stream.result();
+            }
+            finally {
+                slot.release(); // result() 兜底：流未被迭代（或已早 break）的终态取值形态
+            }
+        },
+    };
+}
+/** 工具描述收口：LlmTool → pi-ai Tool（parameters 已是 JSON Schema 对象） */
+function toPiTool(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        // 类型层面 JSON Schema 对象 → TSchema（运行时同一对象，typebox schema 即
+        // JSON Schema；LlmTool.parameters 为宽收 object——兼容构建器产物与手写
+        // schema 两种来源）
+        parameters: tool.parameters,
+    };
+}
+/**
+ * 合成错误流：单 error 终止事件 + 终值消息（pi-ai 事件流原语自建，协议同构）。
+ * @param errorMessage 人读错误说明（携 [CODE] 前缀）
+ * @param errorCode 宿主合成码（classifyError 判定序的机器判定位）
+ */
+function errorStream(errorMessage, errorCode) {
+    const message = {
+        role: 'assistant',
+        content: [],
+        usage: NO_USAGE,
+        stopReason: 'error',
+        errorMessage: errorCode !== undefined ? `[${errorCode}] ${errorMessage}` : errorMessage,
+        ...(errorCode !== undefined ? { errorCode } : {}),
+        timestamp: Date.now(),
+    };
+    const stream = createAssistantMessageEventStream();
+    stream.push({ type: 'error', reason: 'error', error: message });
+    stream.end(message);
+    return stream;
+}

package/dist/lsp/codes.js

@@ -0,0 +1,31 @@
+/**
+ * lsp 桥域错误码注册（03 §10.2——LSP_ 前缀族首批，02 §5.3 明列三码、
+ * 2026-09-13 f-2 批增列第四码）。
+ *
+ * 码名清单与语义真源 = 03 篇 §10.2 生命周期条 LSP_ 三码 + config 坏形条
+ * LSP_CONFIG_INVALID。本文件由模块公开面 index.ts 引入（注册纪律：写入点
+ * 文件必须实际 import 本文件注册才发生——与 issue/scheduler/mcp 先例同款）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'LSP_CONNECT_FAILED',
+        module: 'lsp',
+        description: 'LSP 实例 spawn/initialize 握手失败或超时（实例标 failed + ui.notify warn、在途/后续调用工具结果 error、下用再试并计熔断一败）',
+    },
+    {
+        code: 'LSP_FRAME_INVALID',
+        module: 'lsp',
+        description: 'Content-Length 帧坏形或帧资源双帽超限（攒头 16KiB / 攒正文 16MiB——声明值即缓冲吸收上界）——连接死归因 + 同步树杀，计熔断一败（坏帧 crash 与 close 事件经幂等闸不双计）',
+    },
+    {
+        code: 'LSP_CIRCUIT_OPEN',
+        module: 'lsp',
+        description: '同 server 3 连败熔断开（实例级旗标、复位走 /reload、行内他服务器不受累；作用域回卷的协议化关停不计熔断计数）',
+    },
+    {
+        code: 'LSP_CONFIG_INVALID',
+        module: 'lsp',
+        description: '行 config 坏形装载期归一响亮拒——servers 对象形/command 绝对路径/languages 非空/超时正数域逐一校验，坏形 = 行级装载失败 /reload 时刻可修（03 §10.2 config 坏形条，2026-09-13 f-2 批增列）',
+    },
+]);

package/dist/lsp/connection.js

@@ -0,0 +1,147 @@
+/**
+ * 帧式 JSON-RPC 连接（03 §10.2 帧层承载——Content-Length 帧上的请求关联表）。
+ *
+ * 与 mcp 件 JsonRpcConnection 同律异帧（行帧 vs 长度帧）——DAG 零边故平行
+ * 实现，词面独立律（02 §4.1）：
+ * - 请求关联表：id 递增登记、三源结清竞速先到即摘（响应/超时/failAll）；
+ * - 服务器→客户端请求一律 -32601 拒答（v1 不承载 workspace/configuration
+ *   等反向能力面）；
+ * - 服务器通知按 method 分发给订阅面（publishDiagnostics 唯一真消费）；
+ * - 帧 fatal（双帽超限/坏头）→ onFatal 上报一次 + pending 总清（载体级
+ *   失败收场归实例侧：封读 + 同步树杀）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { FrameDecoder, encodeFrame } from './frame.js';
+/**
+ * 单实例线协议连接。生命周期语义：dead 旗（载体死/fatal）后 request 即拒
+ * （快失败不悬挂）；failAll 是 pending 的总结清面（crash/超限共用）。
+ */
+export class LspWire {
+    nextId = 1;
+    pending = new Map();
+    decoder = new FrameDecoder();
+    notificationHandlers = new Map();
+    options;
+    dead = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /** 发请求（关联表登记 + 可选超时执法——两钟接力：握手钟/请求钟各自传入） */
+    request(method, params, timeoutMs) {
+        if (this.dead) {
+            return Promise.reject(new BaseError('LSP_CONNECT_FAILED', '连接已死（载体级失败/crash）——不再发请求'));
+        }
+        const id = this.nextId++;
+        const frame = { jsonrpc: '2.0', id, method };
+        if (params !== undefined)
+            frame.params = params;
+        return new Promise((resolve, reject) => {
+            let timer;
+            if (timeoutMs !== undefined && timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new Error(`LSP 请求超时（${method}，预算 ${timeoutMs}ms）`));
+                }, timeoutMs);
+            }
+            this.pending.set(id, { resolve, reject, timer });
+            this.options.send(encodeFrame(JSON.stringify(frame)));
+        });
+    }
+    /** 发通知（无 id 不等回复——initialized/didOpen/didChange/didClose/exit） */
+    notify(method, params) {
+        if (this.dead)
+            return;
+        const frame = { jsonrpc: '2.0', method };
+        if (params !== undefined)
+            frame.params = params;
+        this.options.send(encodeFrame(JSON.stringify(frame)));
+    }
+    /** 订阅服务器通知（method 分发；返回退订闭包） */
+    onNotification(method, handler) {
+        const list = this.notificationHandlers.get(method) ?? [];
+        list.push(handler);
+        this.notificationHandlers.set(method, list);
+        return () => {
+            const current = this.notificationHandlers.get(method);
+            if (current === undefined)
+                return;
+            const idx = current.indexOf(handler);
+            if (idx >= 0)
+                current.splice(idx, 1);
+        };
+    }
+    /** stdout 字节喂入（帧劈 → 逐帧分派；帧 fatal 即载体级失败收口） */
+    feed(chunk) {
+        const { frames, fatal } = this.decoder.feed(chunk);
+        if (fatal) {
+            this.die(new BaseError('LSP_FRAME_INVALID', 'Content-Length 帧坏形或双帽超限（攒头 16KiB / 攒正文 16MiB）——载体级失败'), '帧双帽超限/坏头');
+            return;
+        }
+        for (const frame of frames)
+            this.dispatch(frame);
+    }
+    /** 载体死结清（crash/close——pending 全拒；幂等） */
+    failAll(error) {
+        this.die(error, undefined);
+    }
+    /** 内部死面：dead 封口 + pending 总清（fatal 时另报 onFatal 一次） */
+    die(error, fatalReason) {
+        if (this.dead)
+            return;
+        this.dead = true;
+        for (const entry of this.pending.values()) {
+            if (entry.timer !== undefined)
+                clearTimeout(entry.timer);
+            entry.reject(error);
+        }
+        this.pending.clear();
+        if (fatalReason !== undefined)
+            this.options.onFatal?.(fatalReason);
+    }
+    /** 单帧分派（响应结清 / 服务器方向请求拒答 / 通知分发） */
+    dispatch(frame) {
+        let msg;
+        try {
+            msg = JSON.parse(frame);
+        }
+        catch {
+            this.options.warn?.(`LSP 帧 JSON 坏形跳过：${frame.slice(0, 120)}`);
+            return;
+        }
+        if (typeof msg !== 'object' || msg === null)
+            return;
+        const m = msg;
+        if (typeof m.method === 'string') {
+            if (m.id !== undefined) {
+                // 服务器→客户端请求：一律 -32601（v1 不承载反向能力面）
+                if (!this.dead) {
+                    this.options.send(encodeFrame(JSON.stringify({
+                        jsonrpc: '2.0',
+                        id: m.id,
+                        error: { code: -32601, message: `v1 拒答服务器请求 ${m.method}` },
+                    })));
+                }
+                return;
+            }
+            // 通知：按 method 分发给订阅面（publishDiagnostics 唯一真消费）
+            for (const handler of [...(this.notificationHandlers.get(m.method) ?? [])]) {
+                handler({ method: m.method, params: m.params });
+            }
+            return;
+        }
+        if (typeof m.id === 'number') {
+            const entry = this.pending.get(m.id);
+            if (entry === undefined)
+                return; // 迟到/未知 id——超时已结清
+            this.pending.delete(m.id);
+            if (entry.timer !== undefined)
+                clearTimeout(entry.timer);
+            if (m.error !== undefined) {
+                entry.reject(new Error(`LSP ${m.error.code}: ${m.error.message}`));
+            }
+            else {
+                entry.resolve(m.result);
+            }
+        }
+    }
+}

package/dist/lsp/frame.js

@@ -0,0 +1,110 @@
+/**
+ * Content-Length 帧编解码（03 §10.2 帧层——手写零依赖）。
+ *
+ * 帧形：`Content-Length: <n>\r\n[其余头行……]\r\n\r<n 字节正文>`（LSP stdio
+ * 载体标准形；正文 UTF-8 JSON）。
+ *
+ * 帧资源卫生双帽（03 §10.2 明律）：
+ * - 攒头态 16KiB——无 \r\n\r\n 分隔符的持续流不无界攒积；
+ * - 攒正文态 16MiB——**Content-Length 声明值即缓冲吸收上界**：头解析时刻
+ *   即拒超帽声明（不攒了才发现——巨帧在头落地时就被拦在门外）。
+ * 任一超帽/坏头 = fatal 坏帧：同批已解帧全弃（半批不发），此后解码器恒死
+ * （不再攒、不再上报——一次语义）；fatal 后残余不外发（pending 由连接层
+ * 结清）。与 mcp 件 LineDecoder 同律异形（行帧 vs 长度帧）——DAG 零边故
+ * 平行实现，词面独立律（02 §4.1）。
+ */
+import { LSP_BODY_LIMIT_BYTES, LSP_HEADER_LIMIT_BYTES } from './types.js';
+/** 头分隔符（\r\n\r\n——四字节） */
+const HEADER_SEPARATOR = '\r\n\r\n';
+/** 帧编码（payload → Content-Length 帧 Buffer——写出面单源） */
+export function encodeFrame(payload) {
+    const body = Buffer.from(payload, 'utf8');
+    return Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii'), body]);
+}
+/**
+ * 帧解码器（字节面——攒头/攒正文两态；跨 chunk 拼接）。
+ *
+ * 状态即 `pendingBodyLength`：undefined = 攒头态；数值 = 攒正文态（已闭
+ * 合头的声明正文长）。凑满一帧即出帧、余段自动进入下一帧解析循环。
+ */
+export class FrameDecoder {
+    buf = [];
+    size = 0;
+    fatal = false;
+    pendingBodyLength;
+    /**
+     * 喂入一段字节；返回完整帧正文（UTF-8 解码）。
+     * fatal = true 即载体级失败（本次起解码器死——后续 feed 恒空恒不报；
+     * 同批先出的正常帧一并弃——半批不发）。
+     */
+    feed(chunk) {
+        if (this.fatal)
+            return { frames: [], fatal: false };
+        this.buf.push(chunk);
+        this.size += chunk.length;
+        const frames = [];
+        for (;;) {
+            if (this.pendingBodyLength === undefined) {
+                // ── 攒头态：找 \r\n\r\n ──
+                const merged = this.concat();
+                const sep = merged.indexOf(HEADER_SEPARATOR, 'ascii');
+                if (sep < 0) {
+                    // 头未闭合——攒头帽执法（无分隔符持续流不无界攒积）
+                    if (this.size > LSP_HEADER_LIMIT_BYTES)
+                        return this.die();
+                    this.buf = [Buffer.from(merged)]; // subarray 视图拷贝释放（帽内拷贝有界）
+                    return { frames, fatal: false };
+                }
+                const declared = parseContentLength(merged.subarray(0, sep).toString('ascii'));
+                if (declared === undefined || declared > LSP_BODY_LIMIT_BYTES)
+                    return this.die();
+                this.pendingBodyLength = declared;
+                const rest = merged.subarray(sep + HEADER_SEPARATOR.length);
+                this.buf = rest.length > 0 ? [Buffer.from(rest)] : [];
+                this.size = rest.length;
+                // 落入攒正文态——继续循环凑正文
+            }
+            else {
+                // ── 攒正文态：凑满即出帧 ──
+                if (this.size < this.pendingBodyLength)
+                    return { frames, fatal: false }; // 还不够
+                const merged = this.concat();
+                frames.push(merged.subarray(0, this.pendingBodyLength).toString('utf8'));
+                const rest = merged.subarray(this.pendingBodyLength);
+                this.buf = rest.length > 0 ? [Buffer.from(rest)] : [];
+                this.size = rest.length;
+                this.pendingBodyLength = undefined;
+                if (this.size === 0)
+                    return { frames, fatal: false }; // 恰好耗尽——零余段
+                // 余段可能含后续帧——回循环重新走攒头态
+            }
+        }
+    }
+    /** 缓冲合并（单段零拷贝直取；攒头帽内的合并有界） */
+    concat() {
+        return this.buf.length === 1 ? this.buf[0] : Buffer.concat(this.buf);
+    }
+    /** 死面（清槽 + 恒死封口；同批已解帧全弃） */
+    die() {
+        this.fatal = true;
+        this.buf = [];
+        this.size = 0;
+        this.pendingBodyLength = undefined;
+        return { frames: [], fatal: true };
+    }
+}
+/** 头区解析 Content-Length（大小写不敏感；坏形/负数返 undefined） */
+function parseContentLength(headerText) {
+    for (const line of headerText.split('\r\n')) {
+        const colon = line.indexOf(':');
+        if (colon < 0)
+            continue;
+        if (line.slice(0, colon).trim().toLowerCase() !== 'content-length')
+            continue;
+        const value = Number.parseInt(line.slice(colon + 1).trim(), 10);
+        if (!Number.isFinite(value) || value < 0)
+            return undefined;
+        return value;
+    }
+    return undefined;
+}

package/dist/lsp/index.js

@@ -0,0 +1,16 @@
+/**
+ * core:lsp 公开面（02 §4.1 席位 core:lsp——Content-Length 帧手写 + 惰性
+ * per-(server, rootUri) 实例 + 诊断回流，03 §10.2 六条款全兑现）。
+ *
+ * DAG deps = {contracts, context}；spawn/注册/作用域/事件/文件系统全经窄面
+ * 注入（LspSpawnFace 等——compat.test 真 SpawnPipeline 结构互证）。装载态
+ * 集成归批 12 装载面后的装配批。
+ */
+import './codes.js';
+export * from './types.js';
+export { FrameDecoder, encodeFrame } from './frame.js';
+export { LspWire } from './connection.js';
+export { connectLspInstance } from './instance.js';
+export { buildLspToolDefs } from './tools.js';
+export { createDiagnosticsInjector } from './inject.js';
+export { createLspService } from './service.js';

package/dist/lsp/inject.js

@@ -0,0 +1,58 @@
+import { TOOL_POST_EXECUTE_EVENT } from '../contracts/index.js';
+/**
+ * 组 tools_post_execute waterfall 监听器（onWaterfall 挂线）。失败恒
+ * contained：吞错 + warn + 原样透传。
+ */
+export function createDiagnosticsInjector(deps) {
+    return async (input, next) => {
+        const posted = await next(input); // 先透传——注入纯后置
+        try {
+            await maybeInject(posted.result, posted, deps);
+        }
+        catch (err) {
+            // contained 铁律：注入失败不改写原结果、不置 isError——只 warn
+            deps.warn(`诊断 post 注入失败（contained 吞错）：${err instanceof Error ? err.message : String(err)}`);
+        }
+        return posted;
+    };
+}
+/** 注入判定与编舞（await 收口——竞速钟帽内落定，管道返回前诊断段已追加） */
+async function maybeInject(result, input, deps) {
+    const { tool, args } = input;
+    if (result.isError === true)
+        return; // 失败写不注入（成功 = 非 isError）
+    const written = [];
+    const deleted = [];
+    if (tool.name === 'write') {
+        if (typeof args.path === 'string')
+            written.push(args.path);
+    }
+    else if (tool.name === 'edit') {
+        // edit 结构化操作账：{operations: [{op: 'add'|'update'|'delete', path}]}
+        const details = result.details;
+        if (details !== null && typeof details === 'object' && Array.isArray(details.operations)) {
+            for (const op of details.operations) {
+                if (typeof op?.path !== 'string')
+                    continue;
+                if (op.op === 'delete')
+                    deleted.push(op.path);
+                else
+                    written.push(op.path);
+            }
+        }
+    }
+    else {
+        return; // 非 {write, edit} 工具——零注入零等待
+    }
+    if (deleted.length > 0)
+        deps.face.closeDocuments(deleted); // didClose 唯一触发点
+    if (written.length === 0)
+        return;
+    const segments = await deps.face.injectDiagnostics(written); // 竞速钟帽内（面内执法）
+    for (const segment of segments) {
+        if (segment !== '')
+            result.content.push({ type: 'text', text: segment });
+    }
+}
+/** 注入器挂线事件名（单源再导出——装配根与测试共用） */
+export { TOOL_POST_EXECUTE_EVENT };