berry-agent 0.1.0-alpha.1

package/dist/llm/complete.js

@@ -0,0 +1,196 @@
+/**
+ * llm — 单发受托管补全服务（04 §3.7 complete 单发 + §5 预算两维）。
+ *
+ * complete 是后台件（compaction 摘要、goal 轮间沉淀、记忆 review）发起单次
+ * 补全的唯一合法路径：
+ * 1. 轻量单发就是单发——不起 subagent loop（loop 装配是任务委派的成本，
+ *    不是摘要/分类的成本）；
+ * 2. 复用 resolveModel + retryAssistantCall + StreamFnDefaults——与主对话
+ *    同一模型解析、重试语义与请求参数面，调用方不另立炉灶。
+ *
+ * 预算闸门（04 §5 两维——承 berry 三维删插件维，2026-09-04 立项裁决）：
+ * canAfford(priority)——foreground 恒 true（用户可见请求永远放行）；background
+ * 当日后台累计 tokens < 限额（缺省 4M）。执法位点 = llm 层拒发
+ * （LLM_BUDGET_EXCEEDED 拒在请求发出前）；底账 = 注入的聚合查询
+ * （backgroundSpentToday 读侧）——余额不存储、重放推导（llm/usage durable
+ * 事件聚合，05 篇）。硬拒之上另有软着陆层（04 §5 预警三档）：backgroundUsage
+ * 投影读面 + budgetAdvisoryLevel 档位判定（70/85/95%）供装配位铸造瞬态预警
+ * 注入文案；子代理 90% reserve 线常量同件单源（SUBAGENT_RESERVE_THRESHOLD）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { randomUUID } from 'node:crypto';
+import { formatModelId } from './model-id.js';
+import { classifyError, isContextOverflow, retryAssistantCall, } from './recovery.js';
+/** 缺省重试策略：开 1 次重试、500ms 起步指数退避（SDK 级重试之外的有界第二层） */
+const DEFAULT_RETRY = { enabled: true, maxRetries: 1, baseDelayMs: 500 };
+/** 零用量（达帽错误终态合成用——同 stream-fn 的 errorStream 惯例） */
+const NO_USAGE = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 };
+/** 缺省后台预算：当日后台补全 tokens（in+out 合计）限额（04 §5 起草值） */
+const DEFAULT_BACKGROUND_BUDGET = 4_000_000;
+/**
+ * 预警三档线（04 §5 软着陆层——达 70 / 85 / 95% 各档：NOTICE / URGENT /
+ * CRITICAL）：常量可配置、不入库。exhausted 不设档——池尽归 canAfford 硬拒
+ * 与停靠腿（04 §5 成熟度 #5 实装），本层不重复造词。
+ */
+export const BUDGET_ADVISORY_THRESHOLDS = { notice: 0.7, urgent: 0.85, critical: 0.95 };
+/**
+ * 非交互子代理 reserve 线（04 §5——总预算 90% 线强停子代理）：留余量给
+ * 主循环写终态（子代理先耗尽则父终态写不出，实证失败模式）。执法位 =
+ * host/subagent-factory（起跑前 + 在飞轮询），本件只持常量单源。
+ */
+export const SUBAGENT_RESERVE_THRESHOLD = 0.9;
+/** 档位判定（ratio → 三档；null = 未达 notice 线无预警——消费面零注入） */
+export function budgetAdvisoryLevel(ratio) {
+    if (ratio >= BUDGET_ADVISORY_THRESHOLDS.critical)
+        return 'critical';
+    if (ratio >= BUDGET_ADVISORY_THRESHOLDS.urgent)
+        return 'urgent';
+    if (ratio >= BUDGET_ADVISORY_THRESHOLDS.notice)
+        return 'notice';
+    return null;
+}
+/**
+ * 创建单发受托管补全服务（host 装配根 provide 的那一个对象）。
+ */
+export function createLlmService(options) {
+    const { runtime, defaults = {}, defaultModel, retry = DEFAULT_RETRY, tracker, hookDispatch } = options;
+    const budget = options.backgroundBudgetTokens ?? DEFAULT_BACKGROUND_BUDGET;
+    // 当日后台已耗 = 注入的聚合查询（底账 = llm/usage 事件投影，缺省无已耗）
+    const spentToday = options.backgroundSpentToday ?? (() => 0);
+    /**
+     * 预算闸门（04 §5 两维）：foreground 恒 true（用户可见请求永远优先——前台
+     * 不硬断）；background = 当日后台累计 < 全局限额。
+     */
+    const canAfford = (priority) => {
+        if (priority === 'foreground')
+            return true;
+        return spentToday() < budget;
+    };
+    /** pi-ai Model → ModelInfo 投影（listModels/getModel 同一映射，同表同账） */
+    const toModelInfo = (m) => ({
+        id: formatModelId(m.provider, m.id),
+        name: m.name,
+        provider: m.provider,
+        reasoning: m.reasoning,
+        input: [...m.input],
+        contextWindow: m.contextWindow,
+        maxTokens: m.maxTokens,
+    });
+    /** 目录点查窗口：全形 id → contextWindow；缺模型 undefined（诚实退化） */
+    const contextWindowOf = (id) => {
+        const found = runtime.listModels().find((m) => formatModelId(m.provider, m.id) === id);
+        return found === undefined ? undefined : found.contextWindow;
+    };
+    return {
+        registerProvider: (provider) => runtime.registerProvider(provider),
+        unregisterProvider: (id) => runtime.unregisterProvider(id),
+        // 错误桶判定：recovery 桶表直通——单源表的公开消费位
+        classifyError: (message) => classifyError(message),
+        // 溢出判定：窗口活取目录点查——缺模型 undefined 即仅错误正则一路
+        // （静默溢出/length 零输出两路天然不触发，诚实退化不阻断）
+        isContextOverflowFor: (message, model) => isContextOverflow(message, contextWindowOf(model)),
+        // 模型目录只读投影：pi-ai Model → ModelInfo 字段子集直通——id 组
+        // "provider/model-id" 全形（resolveModel 同名可解析），传输/配置面不披露
+        listModels(provider) {
+            return runtime.listModels(provider).map(toModelInfo);
+        },
+        // 点查复用同一投影（同表同账）；全形 id 不在目录 = undefined（点查语义——
+        // 不抛 LLM_MODEL_NOT_FOUND，那是 resolveModel 发补全请求时的 fail-loud 面）
+        getModel(id) {
+            const found = runtime.listModels().find((m) => formatModelId(m.provider, m.id) === id);
+            return found === undefined ? undefined : toModelInfo(found);
+        },
+        canAfford,
+        // 当日后台预算投影（canAfford 同源数值面——同 spentToday/限额两单点）
+        backgroundUsage: () => {
+            const spent = spentToday();
+            return { spent, limit: budget, ratio: spent / budget };
+        },
+        async complete(req) {
+            // 钩子派发段前置查（03 §3.4——02 §5.3 LLM_CALL_IN_HOOK）：钩子 handler
+            // 内 await 单发补全 = 耦合违法（fire-and-forget 尾链窗外合法）；先于预算
+            // 闸/模型解析（调用方违例最先判）
+            if (hookDispatch?.inHookDispatch() === true) {
+                throw new BaseError('LLM_CALL_IN_HOOK', '钩子执行段禁模型调用（03 §3.4——钩子 handler 内 await 单发补全即耦合；起异步任务不等结果合法）');
+            }
+            // 预算闸门（04 §5 执法位点）：后台调用且当日已耗尽 → 拒在请求发出前
+            // （不是事后记账发现超了——钱花出去才拒不是预算）。检查在调用前；入账在
+            // 成功后（装配层经 onUsage 落 llm/usage durable 事件）——最后一发可略超
+            // 限额（check-then-act 于单发粒度；另 write-behind 批落窗口内的最近一笔
+            // 闸门可能未见，同为「略超」语义——预算是软闸门，不是安全边界）。
+            if (req.priority === 'background' && !canAfford('background')) {
+                throw new BaseError('LLM_BUDGET_EXCEEDED', `当日后台预算已耗尽（限额 ${budget} tokens）——用户可见请求永远优先，后台任务下个周期再试`);
+            }
+            // 模型解析 fail-loud（BaseError LLM_MODEL_*）；在重试环外：解析错误是
+            // 确定性的，重试无意义
+            const modelSpec = req.model ?? defaultModel();
+            const model = runtime.resolveModel(modelSpec);
+            // 标准三角色零转换直通（同 stream-fn 直通策略）；单发无工具面
+            const piContext = {
+                systemPrompt: req.systemPrompt,
+                messages: req.messages,
+            };
+            // defaults 打底 → 具名 timeoutMs/signal 覆盖
+            const piOptions = {
+                ...defaults,
+                ...(req.timeoutMs !== undefined ? { timeoutMs: req.timeoutMs } : {}),
+                ...(req.signal !== undefined ? { signal: req.signal } : {}),
+            };
+            // 单发不 loop——一次 streamSimple + 有界 transient 重试（retryAssistantCall）。
+            // 计时起点：全调用口径——含重试在内的墙钟耗时，终点在成功终态后
+            const startedAt = performance.now();
+            const message = await retryAssistantCall(async () => {
+                // 在飞帽（04 §3.6）：与主对话路同源计数；达帽同拒——错误终态带
+                // errorCode，经 pi-ai 正则归 non-retryable 即刻上抛（不造排队口子）
+                const slot = tracker?.tryAcquire(model.provider) ?? null;
+                if (slot === null && tracker !== undefined) {
+                    return {
+                        role: 'assistant',
+                        content: [],
+                        usage: NO_USAGE,
+                        stopReason: 'error',
+                        errorMessage: `[LLM_INFLIGHT_LIMIT] 在飞请求达帽（provider=${model.provider}）：过载期单发失败，调用方稍后自然重试`,
+                        errorCode: 'LLM_INFLIGHT_LIMIT',
+                        timestamp: Date.now(),
+                    };
+                }
+                try {
+                    const stream = runtime.models.streamSimple(model, piContext, piOptions);
+                    return (await stream.result());
+                }
+                finally {
+                    slot?.release(); // result() 即流终结：单发消费面只走这一条路，finally 必达
+                }
+            }, retry, req.signal);
+            // 错误终态 → BaseError 上抛（04 §3.7：complete 是 Promise 面不是流面——
+            // 「永不抛」是 StreamFn 的流事件契约，单发面向 await 的调用方，错误
+            // 回到异常形态）
+            if (message.stopReason === 'error') {
+                throw new BaseError('LLM_COMPLETE_FAILED', message.errorMessage ?? '单发补全失败（错误终态）');
+            }
+            if (message.stopReason === 'aborted') {
+                throw new BaseError('LLM_COMPLETE_FAILED', message.errorMessage ?? '单发补全被取消（aborted）');
+            }
+            // 计量身份随结果携带：callId 供装配层落 llm/usage（settlement 幂等），
+            // priority 供事件分道（聚合只计 background），elapsedMs 供事件耗时聚合
+            const result = {
+                message,
+                usage: message.usage,
+                callId: randomUUID(),
+                priority: req.priority ?? 'foreground',
+                // 全调用耗时（performance.now 差——亚毫秒精度足够观测聚合，不取整保精度）
+                elapsedMs: performance.now() - startedAt,
+            };
+            // 计量 seam：回调异常隔离（观测面不拖垮补全结果；底账由装配层在此落 durable）
+            try {
+                options.onUsage?.(result, modelSpec);
+            }
+            catch (usageErr) {
+                // onUsage 异常隔离不变，但不再零可观测：llm/usage 是预算闸门唯一底账，
+                // 丢账必须可观测——经 onUsageError 交接线面落 warn（04 §3.7）
+                options.onUsageError?.(usageErr, { callId: result.callId, model: modelSpec });
+            }
+            return result;
+        },
+    };
+}

package/dist/llm/events.js

@@ -0,0 +1,15 @@
+/**
+ * Usage → 计量桶单源映射（05 §1.1——四桶必落、cacheWrite1h/reasoning 上报
+ * 才落、totalTokens/cost 不入账）。run 路桥接与 complete 路 onUsage 共用
+ * （run-entry/scheduler-tick 旧扫退役后本函数是唯一映射位）。
+ */
+export function usageBucketsOf(usage) {
+    return {
+        input: usage.input,
+        output: usage.output,
+        cacheRead: usage.cacheRead,
+        cacheWrite: usage.cacheWrite,
+        ...(usage.cacheWrite1h !== undefined ? { cacheWrite1h: usage.cacheWrite1h } : {}),
+        ...(usage.reasoning !== undefined ? { reasoning: usage.reasoning } : {}),
+    };
+}

package/dist/llm/index.js

@@ -0,0 +1,24 @@
+/**
+ * llm 模块公开面（L2 模型运行时；02 篇 §4.1 边表：llm → contracts 单边，
+ * pi-ai 裸导入仅本模块——07 篇栈纪律）。
+ *
+ * 桶出口 = 模型标识解析 + Models 宿主 + StreamFn 适配 + 会话层恢复零件 +
+ * 单发补全服务 + 在飞计数器 + provider 工厂面。pi-ai 的注入面类型在此再出口
+ * ——host 装配根做 persist→pi-ai 两 Store 适配时从这里取类型，不直接依赖 pi-ai。
+ */
+import './codes.js';
+export { DEFAULT_MODEL_SPEC, resolveDefaultModelSpec, parseModelSpec, formatModelId, resolveModel, } from './model-id.js';
+export { createLlmRuntime } from './runtime.js';
+export { createStreamFn } from './stream-fn.js';
+export { InFlightTracker, DEFAULT_MAX_INFLIGHT_PER_PROVIDER } from './inflight.js';
+export { classifyError, diagnoseProviderFailure, isContextOverflow, isRecoverableLength, isRetryableAssistantError, retryAssistantCall, } from './recovery.js';
+export { createLlmService, budgetAdvisoryLevel, BUDGET_ADVISORY_THRESHOLDS, SUBAGENT_RESERVE_THRESHOLD, } from './complete.js';
+export { usageBucketsOf } from './events.js';
+/** 虚拟键 berry-agent/llm 注入物（pi-ai provider 工厂族背书导出，03 篇 §3.2） */
+export { providerApiFace } from './provider-face.js';
+/**
+ * pi-ai faux provider（脚本模型工厂——host 装配根/插件层测试经本面取用；
+ * pi-ai 裸导入纪律仅本模块因此不破，llm 系测试同源）。pi-ai 主包一等同族
+ * 导出，非 test-only 附属包——再出口语义与上方类型族同律。
+ */
+export { fauxProvider } from '@earendil-works/pi-ai';

package/dist/llm/inflight.js

@@ -0,0 +1,65 @@
+/**
+ * llm — per-provider 在飞请求计数器（04 §3.6：缺省 4）。
+ *
+ * 主对话流 + complete 单发 + 子代理多驱动并发是现实形态，在飞帽 = 进程内
+ * 背压：达帽**显式拒绝**（不造排队口子——背压不排队爆仓）。
+ *
+ * 两出口同源计数（知 provider 的调用点恰两个）：
+ * - createStreamFn 主对话路：达帽编码为流内 error 事件（永不抛契约保持，
+ *   errorCode=LLM_INFLIGHT_LIMIT 归 transient 桶——会话层 auto-retry 退避后
+ *   槽已释放重试成功，拒绝与重试天然咬合）；
+ * - complete 单发路：达帽同拒——错误终态经 pi-ai 正则归 non-retryable 即刻
+ *   上抛 LLM_COMPLETE_FAILED；过载期单发失败由调用方自然重试（记忆提取下轮
+ *   / compaction 下次触发）。
+ *
+ * 释放三路保险（幂等）：消费面 for-await 自然耗尽（next() 返回 done）或中途
+ * 退出（迭代 return()/throw()）、不迭代的终态路径 result() finally 兜底——
+ * 任一路先到即减计数，重复调用无害。
+ */
+/** 在飞帽缺省值（04 §3.6：每 provider 并发上限 4） */
+export const DEFAULT_MAX_INFLIGHT_PER_PROVIDER = 4;
+/**
+ * per-provider 在飞计数器（host 装配根构造一份、两出口共享传入——「唯一知
+ * provider 的层」以模块内共享面形式成立，per-provider 名实相符）。
+ */
+export class InFlightTracker {
+    /** 每 provider 在飞上限（0 = 不限） */
+    max;
+    /** provider → 当前在飞数（0 时删键防泄漏增长） */
+    counts = new Map();
+    /** @param maxPerProvider 每 provider 并发上限（缺省 4，04 §3.6；0 = 不限） */
+    constructor(maxPerProvider = DEFAULT_MAX_INFLIGHT_PER_PROVIDER) {
+        this.max = maxPerProvider;
+    }
+    /**
+     * 尝试占一个名额（达帽返回 null = 显式拒绝信号，调用方按各自出口编码错误）。
+     * @param provider 供应商标识（模型解析所得）
+     */
+    tryAcquire(provider) {
+        if (this.max <= 0)
+            return NOOP_SLOT; // 0 = 不限：恒成功且不计数
+        const current = this.counts.get(provider) ?? 0;
+        if (current >= this.max)
+            return null;
+        this.counts.set(provider, current + 1);
+        let released = false;
+        return {
+            release: () => {
+                if (released)
+                    return; // 幂等：迭代 return() 与 result() 双路径只生效一次
+                released = true;
+                const now = this.counts.get(provider) ?? 1;
+                if (now <= 1)
+                    this.counts.delete(provider);
+                else
+                    this.counts.set(provider, now - 1);
+            },
+        };
+    }
+    /** 当前某 provider 在飞数（诊断面/测试断言；不限档恒 0） */
+    inFlight(provider) {
+        return this.counts.get(provider) ?? 0;
+    }
+}
+/** 不限档的空名额（release 无操作——不计数也不减） */
+const NOOP_SLOT = { release: () => undefined };

package/dist/llm/model-id.js

@@ -0,0 +1,58 @@
+/**
+ * llm — 模型标识解析（04 §5 模型标识解析细则：model 为字符串 id，解析归 llm 模块）。
+ *
+ * 约定形式：`"provider/model-id"`，**首斜杠分割**——provider 不得含斜杠，
+ * model-id 允许再含斜杠（openrouter 路径式 id 如 `openrouter/qwen/qwen3-coder`
+ * → provider=openrouter、id=qwen/qwen3-coder）。agent loop 全程只传字符串，
+ * Model 对象在 LLM 调用边界才解析。
+ *
+ * 同文件承载缺省模型声明与 env 覆盖（04 §5 + 07 篇表 #4/#6）：缺省
+ * `anthropic/claude-sonnet-5` 随包声明，BERRY_AGENT_MODEL 覆盖（用户级一次性
+ * 换脑，不落库）。
+ */
+import { BaseError } from '../contracts/index.js';
+/** 缺省模型（07 篇表 #6 拍板：anthropic/claude-sonnet-5——随包声明） */
+export const DEFAULT_MODEL_SPEC = 'anthropic/claude-sonnet-5';
+/**
+ * 解析缺省模型标识（04 §5：BERRY_AGENT_MODEL 覆盖缺省模型）。
+ * @param env 环境变量面（缺省 process.env——测试注入）
+ * @returns 生效模型标识（env 未设/空串回落 DEFAULT_MODEL_SPEC；env 值本身的
+ *          合法性留给 resolveModel fail-loud——此处不做二次校验）
+ */
+export function resolveDefaultModelSpec(env = process.env) {
+    const override = env.BERRY_AGENT_MODEL;
+    return override !== undefined && override !== '' ? override : DEFAULT_MODEL_SPEC;
+}
+/**
+ * 解析模型标识字符串（纯语法层，不查目录）。
+ * @param spec 形如 "provider/model-id"；provider 段与 id 段均须非空
+ * @throws BaseError(LLM_MODEL_SPEC_INVALID) 格式非法时
+ */
+export function parseModelSpec(spec) {
+    const slashIndex = spec.indexOf('/');
+    if (slashIndex <= 0 || slashIndex >= spec.length - 1) {
+        throw new BaseError('LLM_MODEL_SPEC_INVALID', `模型标识格式非法："${spec}"——必须是 "provider/model-id" 形式（如 ${DEFAULT_MODEL_SPEC}，首斜杠分割）`);
+    }
+    return { provider: spec.slice(0, slashIndex), id: spec.slice(slashIndex + 1) };
+}
+/**
+ * 组回标准形式（与 parseModelSpec 互逆；目录清单展示用）。
+ */
+export function formatModelId(provider, id) {
+    return `${provider}/${id}`;
+}
+/**
+ * 在 Models 目录中解析模型标识为具体 Model 对象（fail-loud 路径，供 UI/装配层用）。
+ * @throws BaseError(LLM_MODEL_NOT_FOUND) provider 未注册或模型不在目录时
+ */
+export function resolveModel(models, spec) {
+    const { provider, id } = parseModelSpec(spec);
+    if (!models.getProvider(provider)) {
+        throw new BaseError('LLM_MODEL_NOT_FOUND', `provider 未注册：${provider}（标识 "${spec}"）`);
+    }
+    const model = models.getModel(provider, id);
+    if (!model) {
+        throw new BaseError('LLM_MODEL_NOT_FOUND', `模型不存在：${spec}——该 provider 目录中的模型 id 无此条目`);
+    }
+    return model;
+}

package/dist/llm/provider-face.d.ts

@@ -0,0 +1,32 @@
+/**
+ * llm — 虚拟键 `berry-agent/llm` 注入物（03 篇 §3.2 虚拟面六键之一：
+ * 「LLM 工厂面（pi-ai 适配的 provider API face）——模型层正路」）。
+ *
+ * provider 插件的正确路径：用**宿主同版本**的 pi-ai 工厂族造 provider，再经
+ * ctx.llm.registerProvider 入册——不自捆 pi-ai 副本（双实例 = 传输层行为分叉
+ * 的温床，03 §3.2「防双实例」纪律）、不自拼 fetch。
+ *
+ * 拓扑护栏：本面对象由 host 装配根经 jiti transform 注入插件模块说明符
+ * `berry-agent/llm`——pi-ai 裸导入纪律（仅 llm 模块）因此不破，模块 DAG 不变。
+ */
+import { createProvider, hasApi, lazyApi } from '@earendil-works/pi-ai';
+/**
+ * 虚拟键注入物：pi-ai provider 工厂族再导出对象。
+ *
+ * - createProvider / hasApi（models 出口）：造 provider 实例 + Model 的 api
+ *   收窄守卫——插件 registerProvider 路径的两件套；
+ * - lazyApi（api/lazy 出口）：动态 api 模块包装器（首调用才加载）；
+ * - anthropicMessagesApi / openAICompletionsApi（两家直取便捷键——Anthropic
+ *   messages 形与 OpenAI chat-completions 形，覆盖 provider 接入面的两大主流
+ *   协议）：其余 provider 的 lazy 工厂（google/…共十余家）经 pi-ai 子路径
+ *   `@earendil-works/pi-ai/api/<name>.lazy` 可达——插件应优先走 createProvider
+ *   全链而非裸拿 api 流；确需扩展时按需增键（单键解决一个 provider 的诉求，
+ *   成批抄全 = 面无纪律）。
+ */
+export declare const providerApiFace: {
+    readonly createProvider: typeof createProvider;
+    readonly hasApi: typeof hasApi;
+    readonly lazyApi: typeof lazyApi;
+    readonly anthropicMessagesApi: () => import("@earendil-works/pi-ai").ProviderStreams;
+    readonly openAICompletionsApi: () => import("@earendil-works/pi-ai").ProviderStreams;
+};

package/dist/llm/provider-face.js

@@ -0,0 +1,34 @@
+/**
+ * llm — 虚拟键 `berry-agent/llm` 注入物（03 篇 §3.2 虚拟面六键之一：
+ * 「LLM 工厂面（pi-ai 适配的 provider API face）——模型层正路」）。
+ *
+ * provider 插件的正确路径：用**宿主同版本**的 pi-ai 工厂族造 provider，再经
+ * ctx.llm.registerProvider 入册——不自捆 pi-ai 副本（双实例 = 传输层行为分叉
+ * 的温床，03 §3.2「防双实例」纪律）、不自拼 fetch。
+ *
+ * 拓扑护栏：本面对象由 host 装配根经 jiti transform 注入插件模块说明符
+ * `berry-agent/llm`——pi-ai 裸导入纪律（仅 llm 模块）因此不破，模块 DAG 不变。
+ */
+import { createProvider, hasApi, lazyApi } from '@earendil-works/pi-ai';
+import { anthropicMessagesApi } from '@earendil-works/pi-ai/api/anthropic-messages.lazy';
+import { openAICompletionsApi } from '@earendil-works/pi-ai/api/openai-completions.lazy';
+/**
+ * 虚拟键注入物：pi-ai provider 工厂族再导出对象。
+ *
+ * - createProvider / hasApi（models 出口）：造 provider 实例 + Model 的 api
+ *   收窄守卫——插件 registerProvider 路径的两件套；
+ * - lazyApi（api/lazy 出口）：动态 api 模块包装器（首调用才加载）；
+ * - anthropicMessagesApi / openAICompletionsApi（两家直取便捷键——Anthropic
+ *   messages 形与 OpenAI chat-completions 形，覆盖 provider 接入面的两大主流
+ *   协议）：其余 provider 的 lazy 工厂（google/…共十余家）经 pi-ai 子路径
+ *   `@earendil-works/pi-ai/api/<name>.lazy` 可达——插件应优先走 createProvider
+ *   全链而非裸拿 api 流；确需扩展时按需增键（单键解决一个 provider 的诉求，
+ *   成批抄全 = 面无纪律）。
+ */
+export const providerApiFace = {
+    createProvider,
+    hasApi,
+    lazyApi,
+    anthropicMessagesApi,
+    openAICompletionsApi,
+};

package/dist/llm/recovery.js

@@ -0,0 +1,146 @@
+/**
+ * llm — 会话层恢复零件的 berry-agent 类型面包装（04 §3.5：classifyError 单源
+ * 纯函数表 + pi-ai 零件复用）。
+ *
+ * pi-ai 的 isContextOverflow / retryAssistantCall 等零件面向 pi-ai
+ * AssistantMessage 类型签名；本文件以**我们的 contracts AssistantMessage**
+ * 为签名薄包装（结构同构，边界单次收口），conversation 驱动（turn 级
+ * auto-retry 与溢出 compact-and-retry-once，04 §3.3/§3.4）从这里取用，
+ * 不直接触 pi-ai 类型。
+ */
+import { isContextOverflow as piIsContextOverflow, isRecoverableLength as piIsRecoverableLength, isRetryableAssistantError as piIsRetryable, retryAssistantCall as piRetryAssistantCall, } from '@earendil-works/pi-ai';
+/** 边界收口：宿主消息 → pi-ai 签名（结构同构，超集兼容子集方向） */
+function toPi(message) {
+    return message;
+}
+/**
+ * 检测上下文溢出（04 §3.4 溢出兜底的第一步）。
+ * 覆盖三类：显式报错（provider 正则）、静默溢出（input+cacheRead 超窗）、
+ * length 且零输出（截断填满型）。
+ * @param contextWindow 模型上下文窗口——传入才启用静默溢出检测
+ */
+export function isContextOverflow(message, contextWindow) {
+    return piIsContextOverflow(toPi(message), contextWindow);
+}
+/**
+ * length 截止是否低于预期输出上限（上下文压力/供应商截断信号——
+ * 允许上层做一次有界 compact-and-retry）。
+ */
+export function isRecoverableLength(message, desiredMaxOutput) {
+    return piIsRecoverableLength(toPi(message), desiredMaxOutput);
+}
+/** 失败消息是否像 transient（网络/限流类）错误——决定 turn 级重试是否值得 */
+export function isRetryableAssistantError(message) {
+    return piIsRetryable(toPi(message));
+}
+/**
+ * 错误四桶（04 §3.5 表）——词汇定义已归 contracts/llm.ts（ErrorBucket），
+ * 此处 re-export 维持 llm 公开面不变：
+ * transient/non-retryable/quota 是消费动作桶（每桶一个动作无歧义态），
+ * overflow 只分类不消费（动作挂溢出兜底纵切）。
+ * 驱动 runTurns 重试循环只消费 'transient'。
+ */
+/**
+ * 配额耗尽文案子集（pi-ai retry.ts NON_RETRYABLE 正则的配额族词表——
+ * 该正则模块内私有不导出，此处同款自写）。
+ * quota 桶与 generic non-retryable 的分流：配额类失败要明示「重试治不了」
+ * 的诊断语义（04 §3.5 桶③），不是重试判定差异——两者都不进 auto-retry。
+ */
+const QUOTA_TEXT_PATTERN = /(GoUsageLimit|FreeUsageLimit|Monthly usage limit|available balance|insufficient_quota|out of budget|quota exceeded|billing)/i;
+/** 错误文案的取值面：errorMessage 优先，退而 content 首文本块（与 pi-ai 判定面同源） */
+function errorText(message) {
+    if (message.errorMessage !== undefined && message.errorMessage !== '')
+        return message.errorMessage;
+    const text = message.content.find((block) => block.type === 'text');
+    return text?.text ?? '';
+}
+/**
+ * 错误桶判定（04 §3.5——单源纯函数表，llm 适配层唯一分类点，全仓无第二
+ * 分类处；判定序 2026-09-05 llm 落码批定序）：errorCode 在场码优先、文案
+ * 正则兜底。判定步：
+ * ① errorCode=LLM_INFLIGHT_LIMIT（在飞帽拒绝）→ transient——并发压力自解，
+ *    退避后槽已释放；
+ * ② isContextOverflow → overflow（分类不消费）；
+ * ③ 配额文案族 → quota（429/rate limit 不在此族——归 transient 桶；
+ *    provider 真错误码归一挂 provider 钩子纵切，落码前 errorCode 无 provider
+ *    写点、文案正则是唯一现实路）；
+ * ④ pi-ai isRetryable 正则（网络/5xx/429/overloaded/流早断）→ transient；
+ * ⑤ 其余 → non-retryable（保守：未知错误不重试）。
+ */
+export function classifyError(message) {
+    // ① 宿主合成码优先（errorCode 是机器判定位，摆脱 [CODE] 文本前缀约定）
+    if (message.errorCode === 'LLM_INFLIGHT_LIMIT')
+        return 'transient';
+    // ② 溢出分类位（provider 正则 + 静默溢出 + length 零输出）
+    if (piIsContextOverflow(toPi(message)))
+        return 'overflow';
+    // ③ 配额族文案 → quota（在 isRetryable 之前测：insufficient_quota 在 pi-ai
+    //    归 non-retryable，此处细分到 quota 桶供诊断面区分）
+    if (QUOTA_TEXT_PATTERN.test(errorText(message)))
+        return 'quota';
+    // ④ transient 正则（429/5xx/网络/流早断）
+    if (piIsRetryable(toPi(message)))
+        return 'transient';
+    // ⑤ 保守默认：未知即不可重试（auth/参数/内容策略类重试只会再失败）
+    return 'non-retryable';
+}
+/**
+ * 鉴权失败文案族（401/403/invalid api key 族——provider 报文人间千姿，
+ * 正则面兜大类；provider 真错误码归一挂 provider 钩子纵切落码前，文案
+ * 正则是唯一现实判位——与错误桶表 quota 族判据同境况）。
+ */
+const AUTH_TEXT_PATTERN = /(\b401\b|\b403\b|invalid[^\n]{0,40}api.?key|incorrect api key|api key not (?:valid|found)|unauthorized|authentication|permission denied)/i;
+/** 上游报文附注截断帽（与 RunOutcome.error 同幅——≤200 字符人读够用） */
+const UPSTREAM_NOTE_CAP = 200;
+/** 模型标识 → provider 名（'provider/model-id' 前段；无斜杠回退原串） */
+function providerNameOf(modelSpec) {
+    const slash = modelSpec.indexOf('/');
+    return slash > 0 ? modelSpec.slice(0, slash) : modelSpec;
+}
+/** 上游报文附注（超帽截断加省略号——原文降附注律） */
+function upstreamNote(text) {
+    return text.length > UPSTREAM_NOTE_CAP ? `${text.slice(0, UPSTREAM_NOTE_CAP)}…` : text;
+}
+/**
+ * provider 失败形态识别（07 §5——与错误桶表同源居本模块；纯函数零 IO）。
+ * 判据两形态：
+ * - unconfigured：宿主合成码 LLM_MODEL_NOT_FOUND / LLM_MODEL_SPEC_INVALID
+ *   （stream-fn resolveModel 失败——provider 未注册或目录无此模型；errorCode
+ *   与 `[CODE]` 文案前缀双在位，任一判位命中即识——run settle 只透传
+ *   errorMessage 时文案判位兜底）；
+ * - auth：错误文案正则。
+ * 非两形态回 undefined——调用方原文直出（transient/quota 族已有桶语义，
+ * 不在本面越俎）。
+ */
+export function diagnoseProviderFailure(failure, modelSpec) {
+    const text = failure.errorMessage ?? '';
+    if (failure.errorCode === 'LLM_MODEL_NOT_FOUND' ||
+        failure.errorCode === 'LLM_MODEL_SPEC_INVALID' ||
+        text.includes('[LLM_MODEL_NOT_FOUND]') ||
+        text.includes('[LLM_MODEL_SPEC_INVALID]')) {
+        return {
+            kind: 'unconfigured',
+            hint: `模型不可用：${modelSpec}——provider 未注册或目录中无此模型。` +
+                `检查模型标识拼写（形如 provider/model-id）；更换缺省模型设 BERRY_AGENT_MODEL 环境变量。` +
+                `上游报文：${upstreamNote(text)}`,
+        };
+    }
+    if (text !== '' && AUTH_TEXT_PATTERN.test(text)) {
+        return {
+            kind: 'auth',
+            hint: `provider 鉴权失败（${providerNameOf(modelSpec)}）：请配置该 provider 的 API 凭证——` +
+                `对应环境变量（如 ANTHROPIC_API_KEY / OPENAI_API_KEY）或数据目录凭证表。` +
+                `上游报文：${upstreamNote(text)}`,
+        };
+    }
+    return undefined;
+}
+/**
+ * 单次 assistant 产出的有界重试（04 §3.7 complete 单发的轻量重试零件；
+ * pi 原用途挂 compaction 摘要旁路）。abort 归一为 aborted 消息、非可重试
+ * 错误立即返回、成功即返回——语义细节见 pi-ai retry.ts 文档注释。
+ */
+export async function retryAssistantCall(produce, policy, signal, callbacks) {
+    const final = await piRetryAssistantCall(async () => toPi(await produce()), policy, signal, callbacks);
+    return final;
+}

package/dist/llm/runtime.js

@@ -0,0 +1,46 @@
+/**
+ * llm — Models 宿主包装（04 §5 模型层：llm 模块 = pi-ai Models 接口的宿主包装 +
+ * StreamFn 适配）。
+ *
+ * 职责边界：
+ * - 包装 pi-ai `createModels`（凭证/模型目录经注入——persist 的 credentials/
+ *   model_catalog 两面由 host 装配根适配后注入；llm 不 import persist，
+ *   02 篇边表 llm → contracts 单边）；
+ * - 内置 provider 全家桶默认注册（Anthropic-first 体现在缺省模型约定与文档，
+ *   不在 provider 注册面做裁剪——未配置凭证的 provider 天然不可用）；
+ * - `registerProvider` 即插件钩 `ctx.llm.registerProvider` 的实现底座（03 篇
+ *   §2.2 注册动词表）；`berry-agent/llm` 虚拟键的注入物（providerApiFace）
+ *   与本面同源——插件用宿主同版本的工厂造 provider 入册，防双实例（03 §3.2）。
+ */
+import { builtinProviders } from '@earendil-works/pi-ai/providers/all';
+import { createModels } from '@earendil-works/pi-ai';
+import { resolveModel } from './model-id.js';
+/**
+ * 创建 llm 运行时（宿主包装本体）。
+ * 不做网络访问：createModels 只装配；目录刷新是显式 refresh 调用。
+ */
+export function createLlmRuntime(options = {}) {
+    const models = createModels({
+        credentials: options.credentials,
+        modelsStore: options.modelsStore,
+    });
+    for (const provider of options.providers ?? builtinProviders()) {
+        // 按 id upsert——测试/装配显式传入的集合整体生效，不与内置目录叠加
+        models.setProvider(provider);
+    }
+    return {
+        models,
+        resolveModel: (spec) => resolveModel(models, spec),
+        listModels: (provider) => models.getModels(provider),
+        refresh: (refreshOptions) => models.refresh(refreshOptions),
+        checkAuth: (providerId, checkOptions) => models.checkAuth(providerId, checkOptions),
+        registerProvider(provider) {
+            models.setProvider(provider);
+            return () => {
+                // 简单移除语义：不比对是否仍是本 provider（卸载期竞态由宿主装载序串行化）
+                models.deleteProvider(provider.id);
+            };
+        },
+        unregisterProvider: (id) => models.deleteProvider(id),
+    };
+}