@zhushanwen/pi-llm-shared 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-llm-shared",
-  "version": "0.5.1",
+  "version": "0.7.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",
@@ -17,8 +17,8 @@
     "src/"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.4.1",
-    "@zhushanwen/pi-file-lock": "0.2.1"
+    "@zhushanwen/pi-extension-logger": "0.6.0",
+    "@zhushanwen/pi-file-lock": "0.4.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.4",

package/src/__tests__/call.test.ts

@@ -94,6 +94,39 @@ describe("callLLM", () => {
 		expect(result).toEqual({ ok: true, content: "hello" });
 	});
 
+	it("usage 透传：resp.usage 存在 → ok:true 结果透出该对象（additive，设计 §3.3 ②）", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		// 形态对齐 pi-ai 0.84.4 Usage（含 cost），贴近真实 provider 响应（P-usage-shape）
+		const usage = {
+			input: 10,
+			output: 5,
+			cacheRead: 2,
+			cacheWrite: 1,
+			totalTokens: 18,
+			cost: { input: 0.01, output: 0.02, cacheRead: 0.001, cacheWrite: 0.002, total: 0.033 },
+		};
+		mockComplete.mockResolvedValue({ stopReason: "stop", content: [{ type: "text", text: "hello" }], usage });
+
+		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			// 透传语义：同一引用，非拷贝/重组
+			expect(result.usage).toBe(usage);
+			expect(result.content).toBe("hello");
+		}
+	});
+
+	it("usage 缺失：resp.usage 不存在 → ok:true 结果无 usage 字段（跳过落账语义由调用方处理）", async () => {
+		const ctx = makeCtx({ ok: true, apiKey: "k" });
+		mockComplete.mockResolvedValue({ stopReason: "stop", content: [{ type: "text", text: "hello" }] });
+
+		const result = await callLLM(ctx, { model: makeModel(), systemPrompt: "s", messages: [] });
+
+		expect(result.ok).toBe(true);
+		expect(result).not.toHaveProperty("usage");
+	});
+
 	it("stopReason=error 且 content 无 text → error 回落 'unknown error'", async () => {
 		const ctx = makeCtx({ ok: true, apiKey: "k" });
 		mockComplete.mockResolvedValue({ stopReason: "error", content: [] });

package/src/__tests__/config.test.ts

@@ -21,7 +21,7 @@ vi.mock("@zhushanwen/pi-extension-logger", () => ({
 // 用 vi.mock 包装 readFileSync/renameSync/statSync/unlinkSync（默认走 actual，
 // 个别 test override），其他 fs 操作（writeFileSync/existsSync/mkdirSync...）原样
 // 透传 actual。statSync/unlinkSync 供 U4 logger.warn 留痕用例 override。
-// 注意：proper-lockfile（withFileLockSync 内部）走 graceful-fs，不受本 mock 影响。
+// 注意：withFileLockSync 内部为自实现 mkdir-lock（lock-core.ts，零依赖直用 node:fs，非 proper-lockfile）；本 mock 默认透传 actual，锁行为不受影响。
 vi.mock("node:fs", async (importOriginal) => {
 	const actual = await importOriginal() as typeof import("node:fs");
 	return {
@@ -50,7 +50,7 @@ afterEach(() => {
 	vi.mocked(fs.statSync).mockClear();
 	vi.mocked(fs.unlinkSync).mockClear();
 	loggerMock.warn.mockClear();
-	rmSync(dir, { recursive: true, force: true });
+	rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 	vi.unstubAllEnvs();
 });
 

package/src/__tests__/migrate.test.ts

@@ -10,7 +10,7 @@ describe("migrateLegacyConfig", () => {
 		dir = mkdtempSync(join(tmpdir(), "pi-migrate-test-"));
 	});
 	afterEach(() => {
-		rmSync(dir, { recursive: true, force: true });
+		rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 	});
 
 	it("旧路径不存在 → noop（migrated: false，不动文件系统）", () => {

package/src/call.ts

@@ -18,7 +18,7 @@ import type {
 	Context as LlmContext,
 	SimpleStreamOptions,
 } from "@earendil-works/pi-ai/compat";
-import type { Api, Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import type { Api, Message, Model, ModelThinkingLevel, Usage } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 // ──────────────────────── 类型 ────────────────────────
@@ -49,12 +49,14 @@ export interface CallLLMOptions {
 
 /**
  * callLLM 出参。
- * - ok:true → content 为提取并 trim 的文本
+ * - ok:true → content 为提取并 trim 的文本；usage 为 completeSimple 响应的 resp.usage 透传
+ *   （可选，存在才带——usage 整体缺失时不带字段，「跳过落账」语义由调用方处理，如
+ *   rename-session 的 appendEntry 存在性守卫；permission classifier 等既有调用方不消费，零影响）。
  * - ok:false → stopReason 是独立透传字段（失败原因维度），供调用方保留
  *   error/aborted 的日志区分（如 permission classifier 的 G3 语义）。
  */
 export type CallLLMResult =
-	| { ok: true; content: string }
+	| { ok: true; content: string; usage?: Usage }
 	| { ok: false; error: string; stopReason?: "error" | "aborted" };
 
 // ──────────────────────── 文本提取 ────────────────────────
@@ -87,7 +89,8 @@ export function extractText(resp: {
  * 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: 提取错误文本, stopReason}（不再当正常内容提取）
- * 4. 提取 text → {ok:true, content}
+ * 4. 提取 text → {ok:true, content}；resp.usage 存在则一并透传（条件 spread，缺失时不带字段——
+ *    AssistantMessage.usage 类型必填但运行时 provider 可能不回，P-usage-shape 的降级分支）
  * 5. throw（getApiKeyAndHeaders reject / 网络 / 超时 / 解析）→ catch → {ok:false, error:String(e)}
  *    （stopReason 不设——错误原因不可知）
  *
@@ -133,7 +136,12 @@ export async function callLLM(
 			const errorText = extractText(resp) || "unknown error";
 			return { ok: false, error: errorText, stopReason: resp.stopReason };
 		}
-		return { ok: true, content: extractText(resp) };
+		return {
+			ok: true,
+			content: extractText(resp),
+			// additive（设计 §3.3 ②）：透传 resp.usage，存在才带；缺失时整体不带字段
+			...(resp.usage ? { usage: resp.usage } : {}),
+		};
 	} catch (error) {
 		return { ok: false, error: error instanceof Error ? error.message : String(error) };
 	}

package/src/index.ts

@@ -5,4 +5,4 @@
 export { resolveModel, getCurrentModelId, type ModelSelector } from "./resolve.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";
+export { migrateLegacyConfig } from "./migrate.ts";