berry-agent 0.1.0-alpha.1

package/dist/exec/registry.js

@@ -0,0 +1,120 @@
+/**
+ * 子进程登记簿（04 §11：全部 spawn 子进程入册；写面容错；孤儿清扫）。
+ *
+ * 三语义：
+ * - **写面容错**：登记/出册的持久化失败降 warn 不抛——「登记丢失不损执行
+ *   正确性」，杀树退化为已知 pid 集兜底；持久化走 tmp+rename 原子写（半写
+ *   文件不进正身）。
+ * - **孤儿清扫**（启动期一次）：读残留册，上代宿主已死（entry.hostPid 判
+ *   活）→ 验命令行（pid 复用防线——命令行与登记 argv 不符即跳过，杀错无
+ *  辜进程比漏杀孤儿更糟）→ 树杀 → 出册。
+ * - **stale 判定**：清扫只认「宿主已死」的条目；宿主仍活的条目是并发实例
+ *   的活账，不动。
+ */
+import { rename, readFile, writeFile } from 'node:fs/promises';
+import { createLogger } from '../context/index.js';
+/**
+ * 建子进程登记簿。内存 Map 是唯一真相源，文件是崩溃恢复账——写路径全容错
+ * （任何一步失败 warn 后照常返回，调用方无感）。
+ */
+export function createProcessRegistry(options = {}) {
+    const logger = options.logger ?? createLogger('exec');
+    const entries = new Map();
+    /** 持久化串行链（写-写竞态防线——见 persist 注记） */
+    let persistChain = Promise.resolve();
+    // 持久化（tmp+rename 原子写；全链容错——04 §11「写面容错」条款）。
+    // 串行化关键：多次 add/remove 各自 fire-and-forget 会并发争用同一 tmp 路径
+    // （先到 rename 可吞后到写入——终态倒退成旧快照）；承诺链按入队序逐笔落盘，
+    // 末笔即最新快照，文件终态收敛
+    const persist = (snapshot) => {
+        if (options.filePath === undefined)
+            return;
+        const filePath = options.filePath;
+        const tmp = `${filePath}.tmp`;
+        persistChain = persistChain.then(async () => {
+            try {
+                await writeFile(tmp, `${JSON.stringify(snapshot)}\n`, 'utf8');
+                await rename(tmp, filePath);
+            }
+            catch (error) {
+                logger.warn('登记簿持久化失败（容错降级——内存账仍准确）', {
+                    filePath,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        });
+    };
+    return {
+        add(entry) {
+            entries.set(entry.pid, entry);
+            persist([...entries.values()]);
+        },
+        remove(pid) {
+            // 幂等出册（结算可能后于清扫——缺席即无事）
+            if (!entries.delete(pid))
+                return;
+            persist([...entries.values()]);
+        },
+        list() {
+            return [...entries.values()];
+        },
+    };
+}
+/**
+ * 启动期孤儿清扫（04 §11：扫残留册、hostPid 判活、验命令行、树杀）。
+ * 读文件失败（无文件/坏 JSON）= 空册起步 + warn——清扫是恢复面不是启动门槛。
+ *
+ * 先把残留条目回填进内存账再逐条裁——直接 remove 未回填条目会把内存快照
+ * （空）持久化、误抹并发活实例的账本。
+ * @param deps 判活/命令行/树杀依赖面（注入桩可测；装配批接真实现）
+ */
+export async function sweepOrphans(registry, options, deps) {
+    const logger = options.logger ?? createLogger('exec');
+    const hostPid = options.hostPid ?? process.pid;
+    let persisted = [];
+    if (options.filePath !== undefined) {
+        try {
+            const raw = await readFile(options.filePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                persisted = parsed;
+        }
+        catch {
+            logger.warn('登记簿文件缺失/坏形——空册起步（清扫恢复面非启动门槛）', {
+                filePath: options.filePath,
+            });
+            return { killed: 0, skipped: 0, removed: 0 };
+        }
+    }
+    // 残留条目回填内存账（stale 条目随裁剪出册——持久化走内存快照单源）
+    for (const entry of persisted)
+        registry.add(entry);
+    let killed = 0;
+    let skipped = 0;
+    let removed = 0;
+    // 裁剪对象 = 回填后的整本账（内存既有 + 文件残留——启动期内存通常为空，
+    // 但纯内存腿调用〔无 filePath〕同样可扫）
+    for (const entry of registry.list()) {
+        // 宿主仍活：并发实例的活账，不动（stale 判定——只清上代遗产）
+        if (entry.hostPid === hostPid || deps.isAlive(entry.hostPid))
+            continue;
+        // 孤儿谱系：进程本身已死则纯出册；活着则验命令行再树杀（pid 复用防线）
+        if (deps.isAlive(entry.pid)) {
+            const cmdline = deps.readCmdline(entry.pid);
+            const expected = entry.argv.join(' ');
+            if (cmdline === null || !cmdline.includes(expected)) {
+                skipped += 1;
+                logger.warn('孤儿命令行不符——pid 复用嫌疑跳过树杀（宁漏杀孤儿不误杀无辜）', {
+                    pid: entry.pid,
+                    expected,
+                });
+                continue;
+            }
+            deps.killTree(entry.pid);
+            killed += 1;
+        }
+        registry.remove(entry.pid);
+        removed += 1;
+    }
+    return { killed, skipped, removed };
+}

package/dist/exec/spawn.js

@@ -0,0 +1,281 @@
+/**
+ * spawn 管道真身（04 §11 六条款的执行体：失败二分/进程组树杀/超时归因/
+ * 输出保尾/env 白名单/子进程登记）。
+ *
+ * 编排单入口 run()：空 argv 与预中止两防御 → spawn（detached 独立进程组）
+ * → 登记入册 → 三源竞速（自然退出/超时/打断——先到者落归因即封，其余源
+ * 结算即摘监听）→ close 结算保尾产出。spawn 'error'（进程从未存在）走
+ * BaseError EXEC_SPAWN_FAILED 抛出面——与 exitCode ≠ 0（执行阶段失败，正常
+ * 结算进 result）构成失败二分。
+ *
+ * 树杀纪律：超时/打断即进程组树杀（SIGKILL 直杀不递进 TERM——预算已燃尽，
+ * 可捕获信号的优雅退出窗会拉长超时尾；组杀失败〔组不在〕降杀进程本体）。
+ */
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { BaseError } from '../contracts/index.js';
+import { createLogger } from '../context/index.js';
+import { buildChildEnv } from './env.js';
+import { createProcessRegistry } from './registry.js';
+import { OutputTail } from './tail.js';
+/**
+ * 建 spawn 管道（登记簿随建——宿主启动期孤儿清扫消费 pipeline.registry）。
+ */
+export function createSpawnPipeline(options = {}) {
+    const logger = options.logger ?? createLogger('exec');
+    const now = options.now ?? Date.now;
+    const hostEnv = options.hostEnv ?? process.env;
+    const hostPid = options.hostPid ?? process.pid;
+    const registry = createProcessRegistry(options);
+    const deps = {
+        logger,
+        now,
+        hostEnv,
+        hostPid,
+        registry,
+        resolveEnvRef: options.resolveEnvRef,
+    };
+    return {
+        registry,
+        run: (request) => runSpawn(request, deps),
+        spawnInteractive: (request) => spawnInteractiveChild(request, deps),
+    };
+}
+/**
+ * 长存活双工子进程真身（三桥 stdio 桥——MCP/LSP 的 spawn 面）。
+ *
+ * 与 run 的分野：run 跑完即结算（三源竞速 + 保尾产出）；本面桥侧独占
+ * stdin/stdout 双工（协议帧往返）、进程退出经 onExit 一次送达（close 语义
+ * ——stdio 全闭；spawn 'error'〔进程从未存在〕折 spawnError 位送达，失败
+ * 二分信息不丢）。同律不变项：detached 独立进程组（树杀组锚）、env 白名单
+ * deny-by-default、登记簿同册（spawn 入册 / close 出册——幂等闸防 error 与
+ * close 双计双删）。
+ */
+function spawnInteractiveChild(request, deps) {
+    const argv0 = request.argv[0];
+    if (argv0 === undefined || argv0 === '') {
+        throw new BaseError('EXEC_SPAWN_FAILED', 'argv 为空——无可执行（spawn 阶段失败前置防御）');
+    }
+    const child = spawn(argv0, request.argv.slice(1), {
+        cwd: request.cwd,
+        // 独立进程组（posix）——树杀的组锚；win32 语义为 CREATE_NEW_PROCESS_GROUP
+        detached: true,
+        // 三桥双工面：stdin 必须管道（协议帧写出）；run 管道的 'ignore' 缺省不适用
+        stdio: ['pipe', 'pipe', 'pipe'],
+        // 引用形展开唯一执法点（注入腿 c-4——两入口同点汇入）
+        env: buildChildEnv(request.env, deps.hostEnv, deps.resolveEnvRef),
+    });
+    if (child.pid !== undefined) {
+        deps.registry.add({
+            pid: child.pid,
+            argv: request.argv,
+            owner: request.owner,
+            hostPid: deps.hostPid,
+            startedAt: deps.now(),
+        });
+    }
+    // 退出一次结算（error/close 竞速同封——先到者送达，迟到源 no-op）
+    let exited = false;
+    let lastInfo;
+    const exitCallbacks = [];
+    const finish = (info) => {
+        if (exited)
+            return;
+        exited = true;
+        lastInfo = info;
+        if (child.pid !== undefined)
+            deps.registry.remove(child.pid);
+        for (const cb of [...exitCallbacks])
+            cb(info);
+    };
+    // 失败二分前者：error 事件 = spawn 阶段失败（进程从未存在——ENOENT/EACCES）；
+    // 结算后的迟到 error（stdio EPIPE 类）不改写已封事实
+    child.on('error', (error) => finish({ code: null, spawnError: error }));
+    // close（非 exit）——stdio 全闭才是协议桥的终点事件
+    child.on('close', (code) => finish({ code }));
+    return {
+        pid: child.pid,
+        argv: request.argv,
+        // stdio 三管道位已定形——此处恒非 null（类型面收窄）
+        stdin: child.stdin,
+        stdout: child.stdout,
+        stderr: child.stderr,
+        onExit(callback) {
+            // 已退出：即回调（迟到订阅不丢事件）；未退：入队
+            if (exited)
+                callback(lastInfo);
+            else
+                exitCallbacks.push(callback);
+        },
+        kill() {
+            // 幂等（已退出 no-op）；树杀组锚 = pid（子未成组长降杀本体——killProcessTree 内处理）
+            if (!exited && child.pid !== undefined)
+                killProcessTree(child.pid, deps.logger);
+        },
+    };
+}
+/** 单次执行真身（run 入口的自由函数形——闭包依赖束显式传） */
+async function runSpawn(request, deps) {
+    const argv0 = request.argv[0];
+    if (argv0 === undefined || argv0 === '') {
+        throw new BaseError('EXEC_SPAWN_FAILED', 'argv 为空——无可执行（spawn 阶段失败前置防御）');
+    }
+    // 预中止请求：不造进程直接结算（打断先到——竞速的时序前移态）
+    if (request.signal?.aborted) {
+        return {
+            outcome: 'abort',
+            exitCode: null,
+            stdout: '',
+            stderr: '',
+            truncated: false,
+            bytes: 0,
+            durationMs: 0,
+        };
+    }
+    const start = deps.now();
+    const child = spawn(argv0, request.argv.slice(1), {
+        cwd: request.cwd,
+        // 独立进程组（posix）——树杀的组锚；win32 语义为 CREATE_NEW_PROCESS_GROUP
+        detached: true,
+        // 04 §8 无 stdin：bash 工具面不喂输入；后续桥件自定 stdio 时不走本管道缺省
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // 引用形展开唯一执法点（注入腿 c-4——两入口同点汇入）
+        env: buildChildEnv(request.env, deps.hostEnv, deps.resolveEnvRef),
+    });
+    if (child.pid !== undefined) {
+        deps.registry.add({
+            pid: child.pid,
+            argv: request.argv,
+            owner: request.owner ?? 'exec',
+            hostPid: deps.hostPid,
+            startedAt: deps.now(),
+        });
+    }
+    return await new Promise((resolve, reject) => {
+        const tail = new OutputTail();
+        let settled = false;
+        let outcome = 'exit';
+        let timer;
+        let onAbort;
+        // 摘源（先到者结算即封后，其余源到达即摘——timer 清除 + abort 摘监听）
+        const detachSources = () => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (onAbort !== undefined && request.signal !== undefined) {
+                request.signal.removeEventListener('abort', onAbort);
+                onAbort = undefined;
+            }
+        };
+        const settle = (o) => {
+            if (settled)
+                return;
+            settled = true;
+            outcome = o;
+            detachSources();
+            // 超时/打断即树杀（close 随后到达完成结算——归因已封不改写）
+            if (o !== 'exit' && child.pid !== undefined)
+                killProcessTree(child.pid, deps.logger);
+        };
+        child.stdout?.on('data', (chunk) => tail.append('stdout', chunk));
+        child.stderr?.on('data', (chunk) => tail.append('stderr', chunk));
+        // 失败二分前者：error 事件 = spawn 阶段失败（进程从未存在——ENOENT/EACCES）；
+        // 结算后的迟到 error（stdio EPIPE 类）不改写已封归因
+        child.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            detachSources();
+            if (child.pid !== undefined)
+                deps.registry.remove(child.pid);
+            reject(new BaseError('EXEC_SPAWN_FAILED', `spawn 失败（进程从未存在）：${request.argv.join(' ')}——${error.message}`, {
+                cause: error,
+            }));
+        });
+        if (request.timeoutMs !== undefined && request.timeoutMs > 0) {
+            timer = setTimeout(() => settle('timeout'), request.timeoutMs);
+        }
+        if (request.signal !== undefined) {
+            onAbort = () => settle('abort');
+            request.signal.addEventListener('abort', onAbort);
+        }
+        // close（非 exit）——stdio 全闭才是输出终值点；自然退出也经 settle 收编
+        // （已封则 no-op，归因保留先到者）
+        child.on('close', (code) => {
+            settle('exit');
+            detachSources();
+            if (child.pid !== undefined)
+                deps.registry.remove(child.pid);
+            const finished = tail.finish();
+            resolve({
+                outcome,
+                exitCode: outcome === 'exit' ? (code ?? child.exitCode ?? null) : null,
+                ...finished,
+                durationMs: deps.now() - start,
+            });
+        });
+    });
+}
+/* ------------------------------------------------------------------ */
+/* 平台真身（孤儿清扫 SweepDeps 与树杀的平台实现——装配/测试注入桩替身可测） */
+/* ------------------------------------------------------------------ */
+/**
+ * 进程组树杀（04 §11）：posix 负 pid 组杀（SIGKILL 直杀——预算已燃尽不递进
+ * TERM，可捕获信号会拉长超时尾）；组不在（子未成组长）降杀本体。win32 走
+ * taskkill /T /F（树形递归强杀）。
+ */
+export function killProcessTree(pid, logger = createLogger('exec')) {
+    if (process.platform === 'win32') {
+        const killer = spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        killer.on('error', (error) => logger.warn('taskkill 树杀失败', { pid, error: error.message }));
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            // 本体也已不在——树杀幂等语义，静默（close 随后到达）
+        }
+    }
+}
+/** pid 判活（posix 惯例 kill(pid, 0)；EPERM = 存在但非本主——仍算活） */
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * 读进程命令行（pid 复用防线比对源）：linux 走 /proc/<pid>/cmdline（NUL 分隔
+ * argv），其余平台走 ps -o command=（同步一次性——仅宿主启动期清扫用，不进
+ * 热路径）。读不到返回 null（清扫面视为不匹配跳过）。
+ */
+export function readCmdlineSync(pid) {
+    if (process.platform === 'linux') {
+        try {
+            const raw = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+            return raw.split('\0').filter(Boolean).join(' ').trim();
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        return execSync(`ps -o command= -p ${pid}`, {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}

package/dist/exec/tail.js

@@ -0,0 +1,77 @@
+/**
+ * 输出保尾器（04 §11：stdout/stderr 合计截尾保后半 60KiB）。
+ *
+ * 合计帽语义：两流按到达序共享同一字节预算——超预算时弃头部保尾部（尾部
+ * 才有失败现场：栈迹/错误摘要在尾）。实现 = 到达序分块账本（每块记来源流
+ * 与字节），超帽先整块弃最旧，仅剩单块仍超帽时劈尾保后半。
+ *
+ * 解码纪律：UTF-8 增量宽容解码（decoder.decode(part, {stream:true})——分块
+ * 边界不劈多字节字符；fatal:false 替换符）。与 fs 读的 strict 拒收分立：
+ * fs 读是数据面（mojibake 进上下文污染模型观察），进程输出是诊断面（二进
+ * 制命令〔cat file.bin〕的输出须能以可读形态回执，不能整单拒收）。
+ */
+import { OUTPUT_TAIL_BYTES } from './types.js';
+/** 合计保尾器（构造帽缺省 OUTPUT_TAIL_BYTES；帽 0 = 全弃仍记账） */
+export class OutputTail {
+    cap;
+    chunks = [];
+    totalBytes = 0;
+    droppedBytes = 0;
+    constructor(cap = OUTPUT_TAIL_BYTES) {
+        this.cap = cap;
+    }
+    /** 追加一块输出（到达序）；随即收缩——账本在任意时刻都满足保尾不变式 */
+    append(stream, bytes) {
+        if (bytes.byteLength === 0 || this.cap === 0) {
+            // 帽 0 形：不记账本只记体量（全弃仍是真实输出量）
+            this.droppedBytes += bytes.byteLength;
+            return;
+        }
+        this.chunks.push({ stream, bytes });
+        this.totalBytes += bytes.byteLength;
+        // 整块弃最旧（块级粒度：read() 边界的块不必劈——留最后一块保证有现场）
+        while (this.chunks.length > 1 && this.totalBytes > this.cap) {
+            const oldest = this.chunks.shift();
+            if (oldest === undefined)
+                break;
+            this.totalBytes -= oldest.bytes.byteLength;
+            this.droppedBytes += oldest.bytes.byteLength;
+        }
+        // 仅剩单块仍超帽：劈尾保后半（单块 100KiB 帽 60KiB 形）
+        const only = this.chunks[0];
+        if (only !== undefined && this.totalBytes > this.cap) {
+            const drop = this.totalBytes - this.cap;
+            this.chunks[0] = { stream: only.stream, bytes: only.bytes.subarray(drop) };
+            this.totalBytes = this.cap;
+            this.droppedBytes += drop;
+        }
+    }
+    /** 结算：按流增量解码归并（分块边界不劈多字节字符） */
+    finish() {
+        // 每流一个增量解码器 + 累积面——decode(part, {stream:true}) 的返回值是本批
+        // 已解码文本（解码器内部只留存尾部未完序列不存产出），丢弃返回值 = 丢文本
+        const decoders = {
+            stdout: new TextDecoder('utf-8'),
+            stderr: new TextDecoder('utf-8'),
+        };
+        let stdout = '';
+        let stderr = '';
+        for (const chunk of this.chunks) {
+            const text = decoders[chunk.stream].decode(chunk.bytes, { stream: true });
+            if (chunk.stream === 'stdout')
+                stdout += text;
+            else
+                stderr += text;
+        }
+        // 终了 flush：补出留存在解码器内的尾部未完序列（替换符或空）
+        stdout += decoders.stdout.decode();
+        stderr += decoders.stderr.decode();
+        // 实收总量含已丢弃——披露真实体量（「输出被截了多少」模型可自知）
+        return {
+            stdout,
+            stderr,
+            truncated: this.droppedBytes > 0,
+            bytes: this.totalBytes + this.droppedBytes,
+        };
+    }
+}

package/dist/exec/types.js

@@ -0,0 +1,5 @@
+/** 输出保尾预算（04 §11：stdout/stderr 合计 60KiB 截尾保后半——尾部才有失败现场） */
+export const OUTPUT_TAIL_BYTES = 60 * 1024;
+/** bash 工具超时缺省与上限（04 §8：缺省 120s、上限 600s） */
+export const BASH_TIMEOUT_DEFAULT_MS = 120_000;
+export const BASH_TIMEOUT_MAX_MS = 600_000;

package/dist/goal/codes.js

@@ -0,0 +1,33 @@
+/**
+ * goal 域错误码注册（03 §10.5 + 04 §12——GOAL_ 前缀族；02 §5.3 批 15b
+ * 明列四码，前两码承 berry 同名码〔03 §10 章头指认〕、后两码本仓新立）。
+ *
+ * 码语义分层：GOAL_TRANSITION_INVALID 管状态迁转机器否决（完成否决律/
+ * 撞席守卫/挂钟注册失败回执同折）；GOAL_TODO_SCOPE 管 todo/write 段约束
+ * 双向执法（goal 段缺字段/坏词法、非段申报扩字段、gate 申报位 fail-closed）；
+ * GOAL_NOT_FOUND 管幽灵 goalId；GOAL_GOAL_INVALID 管行载荷词法。
+ * 本文件由模块公开面 index.ts 引入（注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'GOAL_TRANSITION_INVALID',
+        module: 'goal',
+        description: 'goal 状态迁转机器否决——goal_update 终态 completed 必附 evidence 且 open 项在/携 gate 项未全绿即拒（响亮回执列 open 项）、同会话既有 active goal 撞席拒、GoalJobsFace register 坏串回执同折、/goal approve 批准无对象〔未申报 needsWrite 或终态行——f-1 批 03 §10.5 定形注〕',
+    },
+    {
+        code: 'GOAL_TODO_SCOPE',
+        module: 'goal',
+        description: 'todo/write 段约束双向执法——goal 段内 deferred 缺 resume_when、completed 缺后继二择一（follow_up/noFollowUp）、resume_when 词法坏形拒；非 goal 段申报扩字段亦拒；gate 声明申报位 fail-closed（command 未过 needsWrite 申报+人面批准、diagnostics 缺 lsp 面）',
+    },
+    {
+        code: 'GOAL_NOT_FOUND',
+        module: 'goal',
+        description: '幽灵 goalId 零行守卫——update/complete/abandon/wake/approve 作用行缺席响亮拒',
+    },
+    {
+        code: 'GOAL_GOAL_INVALID',
+        module: 'goal',
+        description: 'goal 行载荷坏——objective 空/超 16KiB',
+    },
+]);