@zhushanwen/pi-llm-shared 0.4.2 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-llm-shared",
-  "version": "0.4.2",
-  "description": "Shared LLM invocation library for Pi extensions — model resolution (ref exact only), LLM calling (completeSimple), and config read/write with mtime caching. Shared library, not a Pi extension.",
+  "version": "0.5.0",
+  "description": "Shared LLM invocation library for Pi extensions — model resolution (ref exact only), LLM calling (completeSimple), and config read/write with mtime+size caching. Shared library, not a Pi extension.",
   "type": "module",
   "main": "src/index.ts",
   "keywords": [
@@ -14,12 +14,11 @@
   ],
   "license": "MIT",
   "files": [
-    "src/",
-    "index.ts"
+    "src/"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.3.1",
-    "@zhushanwen/pi-file-lock": "0.1.2"
+    "@zhushanwen/pi-extension-logger": "0.4.0",
+    "@zhushanwen/pi-file-lock": "0.2.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.4",

package/src/__tests__/call.test.ts

@@ -47,42 +47,42 @@ describe("callLLM", () => {
 		expect(optionsArg).toMatchObject({ apiKey: "k", sessionId: "sess-1" });
 	});
 
-	it("TC12 auth-fail → {ok:false, recoverable:true}，不调 completeSimple（narrow 不取 apiKey）", async () => {
+	it("TC12 auth-fail → {ok:false, error}，不调 completeSimple（narrow 不取 apiKey）", async () => {
 		const ctx = makeCtx({ ok: false, error: "no key" });
 
 		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
 
-		expect(result).toEqual({ ok: false, error: "no key", recoverable: true });
+		expect(result).toEqual({ ok: false, error: "no key" });
 		expect(mockComplete).not.toHaveBeenCalled();
 	});
 
-	it("TC13 completeSimple throw → {ok:false, recoverable:true, error 含错误信息}", async () => {
+	it("TC13 completeSimple throw → {ok:false, error 含错误信息}", async () => {
 		const ctx = makeCtx({ ok: true, apiKey: "k" });
 		mockComplete.mockRejectedValue(new Error("network timeout"));
 
 		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
 
 		expect(result.ok).toBe(false);
-		expect(result).toMatchObject({ recoverable: true, error: expect.stringContaining("network") });
+		expect(result).toMatchObject({ error: expect.stringContaining("network") });
 	});
 
-	it("TC1 stopReason=error → {ok:false, error, recoverable:true, stopReason:'error'}（不再 ok:true 返回错误文本）", async () => {
+	it("TC1 stopReason=error → {ok:false, error, stopReason:'error'}（不再 ok:true 返回错误文本）", async () => {
 		const ctx = makeCtx({ ok: true, apiKey: "k" });
 		// completeSimple 对错误也 resolve（带 stopReason），content 是错误文本
 		mockComplete.mockResolvedValue({ stopReason: "error", content: [{ type: "text", text: "API error: 429 rate limited" }] });
 
 		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
 
-		expect(result).toEqual({ ok: false, error: "API error: 429 rate limited", recoverable: true, stopReason: "error" });
+		expect(result).toEqual({ ok: false, error: "API error: 429 rate limited", stopReason: "error" });
 	});
 
-	it("TC2 stopReason=aborted → {ok:false, error, recoverable:true, stopReason:'aborted'}", async () => {
+	it("TC2 stopReason=aborted → {ok:false, error, stopReason:'aborted'}", async () => {
 		const ctx = makeCtx({ ok: true, apiKey: "k" });
 		mockComplete.mockResolvedValue({ stopReason: "aborted", content: [{ type: "text", text: "user aborted" }] });
 
 		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
 
-		expect(result).toEqual({ ok: false, error: "user aborted", recoverable: true, stopReason: "aborted" });
+		expect(result).toEqual({ ok: false, error: "user aborted", stopReason: "aborted" });
 	});
 
 	it("TC3 stopReason=stop（正常）→ 不受 stopReason 检查影响，ok:true 提取文本", async () => {
@@ -100,7 +100,7 @@ describe("callLLM", () => {
 
 		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
 
-		expect(result).toEqual({ ok: false, error: "unknown error", recoverable: true, stopReason: "error" });
+		expect(result).toEqual({ ok: false, error: "unknown error", stopReason: "error" });
 	});
 
 	it("TC13 catch 路径不设 stopReason（错误原因不可知）", async () => {
@@ -176,13 +176,13 @@ describe("callLLM", () => {
 	});
 
 
-	it("B5: getApiKeyAndHeaders reject（抛异常）→ {ok:false, recoverable:true}（归一入 catch，不向上抛）", async () => {
+	it("B5: getApiKeyAndHeaders reject（抛异常）→ {ok:false, error}（归一入 catch，不向上抛）", async () => {
 		const getApiKeyAndHeaders = vi.fn().mockRejectedValueOnce(new Error("registry exploded"));
 		const ctx = { modelRegistry: { getApiKeyAndHeaders } } as unknown as ExtensionContext;
 
 		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
 
-		expect(result).toEqual({ ok: false, error: "registry exploded", recoverable: true });
+		expect(result).toEqual({ ok: false, error: "registry exploded" });
 		// 凭证阶段就 reject，completeSimple 未被调用
 		expect(mockComplete).not.toHaveBeenCalled();
 	});

package/src/call.ts

@@ -37,9 +37,12 @@ export interface CallLLMOptions {
 	/** 透传给 SimpleStreamOptions.sessionId（provider 用于 session 缓存 / 路由）。review TF1 新增。 */
 	sessionId?: string;
 	/**
-	 * thinking/reasoning 级别，透传给 SimpleStreamOptions.reasoning（pi 的 THINKING_ORDER SSOT：
-	 * minimal/low/medium/high/xhigh/max）。"off" 表示关闭 thinking，由本库映射为「不传 reasoning 字段」
-	 * （provider 默认行为）；不传 = 同样 provider 默认。
+	 * thinking/reasoning 级别，透传给 SimpleStreamOptions.reasoning。值域源自 pi 的
+	 * ThinkingLevel 类型（pi-ai：ThinkingLevel = minimal/low/medium/high/xhigh/max，
+	 * ModelThinkingLevel = "off" | ThinkingLevel；pi 无 THINKING_ORDER 符号——该常量的
+	 * SSOT 在本仓 subagent-core src/shared/model-ref.ts，值集与本类型一致）。"off" 表示
+	 * 关闭 thinking，由本库映射为「不传 reasoning 字段」（provider 默认行为）；不传 = 同样
+	 * provider 默认。
 	 */
 	reasoning?: ModelThinkingLevel;
 }
@@ -47,13 +50,12 @@ export interface CallLLMOptions {
 /**
  * callLLM 出参。
  * - ok:true → content 为提取并 trim 的文本
- * - ok:false → recoverable 表示可恢复性（C2b：当前实现统一 true，细分待未来有消费者）；
- *   stopReason 是独立透传字段（失败原因维度，不映射 recoverable），供调用方保留
+ * - ok:false → stopReason 是独立透传字段（失败原因维度），供调用方保留
  *   error/aborted 的日志区分（如 permission classifier 的 G3 语义）。
  */
 export type CallLLMResult =
 	| { ok: true; content: string }
-	| { ok: false; error: string; recoverable: boolean; stopReason?: "error" | "aborted" };
+	| { ok: false; error: string; stopReason?: "error" | "aborted" };
 
 // ──────────────────────── 文本提取 ────────────────────────
 
@@ -84,10 +86,10 @@ export function extractText(resp: {
  *    保证 reject 归一为 {ok:false}，调用方日志前缀一致）
  * 2. 调用：completeSimple(model, {systemPrompt, messages, tools:[]}, {apiKey, headers?, env?, signal?, maxTokens?, timeoutMs?, sessionId?})
  * 3. 检查 resp.stopReason：error/aborted（completeSimple 对错误/中止也 resolve 带 stopReason，G3）
- *    → {ok:false, error: 提取错误文本, recoverable:true, stopReason}（不再当正常内容提取）
+ *    → {ok:false, error: 提取错误文本, stopReason}（不再当正常内容提取）
  * 4. 提取 text → {ok:true, content}
- * 5. throw（getApiKeyAndHeaders reject / 网络 / 超时 / 解析）→ catch → {ok:false, error:String(e), recoverable:true}
- *    （C2b：catch 路径不细分 recoverable，统一 true；stopReason 不设——错误原因不可知）
+ * 5. throw（getApiKeyAndHeaders reject / 网络 / 超时 / 解析）→ catch → {ok:false, error:String(e)}
+ *    （stopReason 不设——错误原因不可知）
  *
  * tools 显式传 []（不塞工具）—— 本库用于标题生成等 best-effort 场景，不需要工具调用。
  */
@@ -96,13 +98,13 @@ export async function callLLM(
 	opts: CallLLMOptions,
 ): Promise<CallLLMResult> {
 	// 整个流程纳入 try：getApiKeyAndHeaders / completeSimple 任一 reject/throw 都归一为
-	// {ok:false, recoverable:true}，保证调用方日志前缀一致（B5：凭证注入原在 try 外，reject 时
+	// {ok:false}，保证调用方日志前缀一致（B5：凭证注入原在 try 外，reject 时
 	// callLLM 直接 reject，上游走外层 .catch 输出不一致前缀，如 [pi-rename-session] 而非 [rename-session]）。
 	try {
 		// 1. 凭证（判别联合必须 narrow）：返回 {ok:false} → 提前返回；reject（抛异常）→ 进 catch
 		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(opts.model);
 		if (!auth.ok) {
-			return { ok: false, error: auth.error, recoverable: true };
+			return { ok: false, error: auth.error };
 		}
 
 		// 2. 调用 completeSimple（字段名经探针⑤对齐：Context{systemPrompt?,messages,tools?},
@@ -126,13 +128,13 @@ export async function callLLM(
 		};
 		const resp = await completeSimple(opts.model, context, options);
 		// G3/C1a：completeSimple 对 error/aborted 也 resolve（带 stopReason，不 reject）。
-		// 归一为 ok:false + stopReason 独立透传（recoverable 统一 true，与 C2b 一致不触发细分）。
+		// 归一为 ok:false + stopReason 独立透传。
 		if (resp.stopReason === "error" || resp.stopReason === "aborted") {
 			const errorText = extractText(resp) || "unknown error";
-			return { ok: false, error: errorText, recoverable: true, stopReason: resp.stopReason };
+			return { ok: false, error: errorText, stopReason: resp.stopReason };
 		}
 		return { ok: true, content: extractText(resp) };
 	} catch (error) {
-		return { ok: false, error: error instanceof Error ? error.message : String(error), recoverable: true };
+		return { ok: false, error: error instanceof Error ? error.message : String(error) };
 	}
 }

package/src/config.ts

@@ -2,11 +2,13 @@
  * 泛型配置读写：getConfigPath + loadConfig<T> + saveConfig + mtime+size 缓存 + 原子写。
  *
  * 与 permission/config.ts 的区别：本库是泛型版（pkgName 参数化，normalize 由调用方传），
- * 不内置任何 schema —— rename-session / permission / scheduler 等 consumer 各自定义 normalize。
+ * 不内置任何 schema —— rename-session / permission / smart-context / base-tool-enhance
+ * 等 consumer 各自定义 normalize。
  * 范式（mtime+size 双 key 缓存、原子写 tmp+rename、tmp 失败清理）借鉴 permission/config.ts。
  *
  * 路径解析用 pi 导出的 getAgentDir（尊重 PI_CODING_AGENT_DIR 覆盖），禁止自实现 ——
- * permission/config.ts:18-22 有重复自实现待 P3 清理，本库直接用 pi 导出版。
+ * [HISTORICAL] permission/config.ts 曾有重复自实现，P3 已清理（现全部委托本库），
+ * 本库直接用 pi 导出版。
  *
  * ── 热重载契约（consumer 必读） ──
  * 本库的 loadConfig 提供「读时刷新（pull-based）热重载」：每次调用 statSync 文件 mtime+size，
@@ -70,7 +72,7 @@ function clone<T>(value: T): T {
 /**
  * 加载配置，文件未变化时返回缓存（深拷贝，防调用方修改污染缓存）。
  *
- * @param pkgName 包名（决定文件路径 <agentDir>/config/<pkgName>.json）
+ * @param pkgName 包名（决定文件路径 <agentDir>/config/<pkgName>-ext-config.json）
  * @param defaults 文件缺失/坏 JSON/normalize 失败时的默认值
  * @param normalize 把 JSON.parse 的 unknown 归一化成 T（调用方负责校验 + 默认值填充）
  * @param onWarning 非致命问题（解析失败）的警告回调

package/src/index.ts

@@ -1,8 +1,8 @@
 // @zhushanwen/pi-llm-shared —— 统一 public API 出口。
 // resolve: 模型解析（仅 ref 精确指定）
 // call: LLM 调用（completeSimple + 凭证 + 文本提取）
-// config: 泛型配置读写（mtime 缓存 + 原子写）
+// config: 泛型配置读写（mtime+size 双 key 缓存 + 原子写）
 export { resolveModel, getCurrentModelId, type ModelSelector } from "./resolve.ts";
-export { callLLM, extractText, type CallLLMOptions, type CallLLMResult } from "./call.ts";
+export { callLLM, type CallLLMOptions, type CallLLMResult } from "./call.ts";
 export { getConfigPath, loadConfig, saveConfig, clearConfigCache } from "./config.ts";
 export { migrateLegacyConfig, type MigrationResult } from "./migrate.ts";

package/index.ts

@@ -1 +0,0 @@
-export * from "./src/index.ts";