@zhushanwen/pi-subagent-workflow 8.1.1 → 8.2.0

package/src/injectors/__tests__/model-list-injector.test.ts

@@ -0,0 +1,139 @@
+// model-list-injector 单测
+//
+// 覆盖（与 workflow-list-injector.test.ts 对称，但本 injector 无文件发现/模块级
+// 缓存，纯函数比重更大）：
+// 1. formatModelList：排序稳定性（registry 返回顺序不保证，输出必须字节稳定）、
+//    caps 推导（reasoning/vision）、空 caps 省略、XML 转义、空列表不注入
+// 2. setupModelListInjector handler：注入 append、空列表返回 undefined、
+//    registry 异常不阻断（fail-safe）
+
+import { describe, expect, it, vi } from "vitest";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { ModelEntry } from "../model-list-injector";
+
+// ── 测试数据工厂 ────────────────────────────────────────
+
+function entry(overrides: Partial<ModelEntry> = {}): ModelEntry {
+	return {
+		provider: "zai-coding-cn",
+		id: "glm-5.2",
+		name: "GLM 5.2",
+		reasoning: true,
+		input: ["text"],
+		contextWindow: 200_000,
+		...overrides,
+	};
+}
+
+// ── 纯函数：formatModelList ─────────────────────────────
+
+describe("formatModelList", () => {
+	it("空列表返回空串（不注入）", async () => {
+		const { formatModelList } = await import("../model-list-injector");
+		expect(formatModelList([])).toBe("");
+	});
+
+	it("渲染 provider/modelId + name + caps + contextWindow", async () => {
+		const { formatModelList } = await import("../model-list-injector");
+		const out = formatModelList([
+			entry({ provider: "p1", id: "m1", name: "Model One" }),
+		]);
+		expect(out).toContain("<available_provider_models>");
+		expect(out).toContain("<model><id>p1/m1</id><name>Model One</name><caps>reasoning</caps><contextWindow>200000</contextWindow></model>");
+		expect(out).toContain("</available_provider_models>");
+	});
+
+	it("input 含 image 时 caps 加 vision；无能力时省略 caps 段", async () => {
+		const { formatModelList } = await import("../model-list-injector");
+		const out = formatModelList([
+			entry({ id: "vision-m", input: ["text", "image"] }),
+			entry({ id: "plain-m", reasoning: false }),
+		]);
+		expect(out).toContain("<id>zai-coding-cn/vision-m</id>");
+		expect(out).toContain("<caps>reasoning,vision</caps>");
+		// plain-m：reasoning=false 且无 image → 无 caps 段
+		expect(out).toMatch(/<id>zai-coding-cn\/plain-m<\/id><name>[^<]*<\/name><contextWindow>/);
+	});
+
+	it("按 (provider, id) 排序——输入乱序输出仍字节稳定（KV cache 前提）", async () => {
+		const { formatModelList } = await import("../model-list-injector");
+		const models = [
+			entry({ provider: "b-prov", id: "z-model" }),
+			entry({ provider: "a-prov", id: "y-model" }),
+			entry({ provider: "a-prov", id: "x-model" }),
+		];
+		const out1 = formatModelList([...models]);
+		const out2 = formatModelList([...models].reverse());
+		expect(out1).toBe(out2);
+		// 排序断言：a-prov/x-model 在最前，b-prov 在最后
+		const ids = [...out1.matchAll(/<id>([^<]+)<\/id>/g)].map((m) => m[1]);
+		expect(ids).toEqual(["a-prov/x-model", "a-prov/y-model", "b-prov/z-model"]);
+	});
+
+	it("排序为码点序而非 locale 序（跨环境字节一致契约，禁 localeCompare）", async () => {
+		const { formatModelList } = await import("../model-list-injector");
+		// 判别样本：码点序 "B"(0x42) < "a"(0x61)，而多数 locale 的 localeCompare
+		// 会把 "a-model" 排在 "B-model" 前——本断言在 localeCompare 实现下必挂
+		const out = formatModelList([
+			entry({ provider: "p", id: "a-model" }),
+			entry({ provider: "p", id: "B-model" }),
+		]);
+		const ids = [...out.matchAll(/<id>([^<]+)<\/id>/g)].map((m) => m[1]);
+		expect(ids).toEqual(["p/B-model", "p/a-model"]);
+	});
+
+	it("name 含 XML 特殊字符时转义（防注入段结构破坏）", async () => {
+		const { formatModelList } = await import("../model-list-injector");
+		const out = formatModelList([
+			entry({ provider: "p", id: "m", name: `A<&>"'B` }),
+		]);
+		expect(out).toContain("<name>A&lt;&amp;&gt;&quot;&apos;B</name>");
+	});
+});
+
+// ── handler 行为：setupModelListInjector ────────────────
+
+describe("setupModelListInjector", () => {
+	type Handler = (event: unknown, ctx: unknown) => Promise<unknown>;
+
+	async function setupWithRegistry(models: ModelEntry[], fail = false): Promise<Handler> {
+		const mod = await import("../model-list-injector");
+		const handlers: Record<string, Handler> = {};
+		const pi = {
+			on: (name: string, fn: Handler) => {
+				handlers[name] = fn;
+			},
+		} as unknown as ExtensionAPI;
+		mod.setupModelListInjector(pi);
+		const registry = fail
+			? { getAvailable: vi.fn(() => { throw new Error("registry boom"); }) }
+			: { getAvailable: vi.fn(() => models) };
+		const handler = handlers["before_agent_start"];
+		if (!handler) throw new Error("before_agent_start handler not registered");
+		return (event: unknown) => handler(event, { modelRegistry: registry });
+	}
+
+	it("注册 before_agent_start handler，注入 append 到 systemPrompt 尾部", async () => {
+		const handler = await setupWithRegistry([entry()]);
+		const result = (await handler({ systemPrompt: "BASE" }, {})) as {
+			systemPrompt: string;
+		};
+		expect(result.systemPrompt.startsWith("BASE")).toBe(true);
+		expect(result.systemPrompt).toContain("<available_provider_models>");
+		expect(result.systemPrompt).toContain("zai-coding-cn/glm-5.2");
+	});
+
+	it("空模型列表返回 undefined（不返回 systemPrompt，不干预链）", async () => {
+		const handler = await setupWithRegistry([]);
+		const result = await handler({ systemPrompt: "BASE" }, {});
+		expect(result).toBeUndefined();
+	});
+
+	it("registry 异常被吞掉（fail-safe，不阻断 agent turn）", async () => {
+		const handler = await setupWithRegistry([], true);
+		const result = await handler({ systemPrompt: "BASE" }, {});
+		expect(result).toBeUndefined();
+	});
+});

package/src/injectors/__tests__/subagent-list-injector.test.ts

@@ -10,43 +10,20 @@
 
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
 import type { DiscoveredResource } from "../../shared/resource-discovery.ts";
+// 共享 mock 基建（vi.mock 工厂 / mock pi / mock ctx）：helpers/injector-test-mocks.ts
+import { createDiscoveryModuleMock, createLoggerModuleMock, createMockCtx, createMockPi, type CapturedHandlers } from "./helpers/injector-test-mocks.ts";
 
 // ── 稳定 spy：vi.hoisted 保证 resetModules 后引用不变（vi.mock 工厂闭包捕获同一 fn，
 //    故 fresh import 的注入器拿到的 discoverResources === spies.discoverResources，跨
 //    resetModules 调用计数连续，mockClear 控制每用例重置） ──
-const spies = vi.hoisted(() => ({
-	discoverResources: vi.fn(),
-	getCachedFileContent: vi.fn(),
-}));
-
-vi.mock("../../shared/resource-discovery.ts", () => ({
-	discoverResources: spies.discoverResources,
-	findWorkspaceRoot: () => "/ws",
-	getCachedFileContent: spies.getCachedFileContent,
-}));
-
-vi.mock("@zhushanwen/pi-extension-logger", () => ({
-	getLogger: () => ({
-		debug: () => {
-			/* no-op */
-		},
-		info: () => {
-			/* no-op */
-		},
-		warn: () => {
-			/* no-op */
-		},
-		error: () => {
-			/* no-op */
-		},
-	}),
-	setPiHandle: () => {
-		/* no-op */
-	},
-}));
+const spies = vi.hoisted(() => ({ discoverResources: vi.fn(), getCachedFileContent: vi.fn() }));
+
+vi.mock("../../shared/resource-discovery.ts", () => createDiscoveryModuleMock(spies));
+
+// 工厂必须写成箭头惰性形式：vi.mock 被提升到 import 之前执行，直接传
+// createLoggerModuleMock 引用会在提升位置立即求值 import 绑定 → TDZ ReferenceError
+vi.mock("@zhushanwen/pi-extension-logger", () => createLoggerModuleMock());
 
 // ── 纯函数测试：静态 import（模块级缓存状态不影响纯函数；与下方缓存 describe 隔离） ──
 import { formatAgentList, parseAgentFrontmatter } from "../subagent-list-injector";
@@ -173,45 +150,9 @@ describe("formatAgentList", () => {
 });
 
 // ──────────────────────────────────────────────────────────────
-// session 级缓存行为（TC1-TC4）
+// session 级缓存行为（TC1-TC4；mock pi/ctx 构造在 helpers/injector-test-mocks.ts）
 // ──────────────────────────────────────────────────────────────
 
-/** before_agent_start handler 的返回结构（取 systemPrompt 断言）。 */
-interface BeforeAgentResult {
-	systemPrompt: string;
-}
-
-/** 三 handler 捕获引用（setupSubagentListInjector 注册后填充）。 */
-interface CapturedHandlers {
-	sessionStart?: (event: unknown, ctx: unknown) => Promise<void> | void;
-	beforeAgentStart?: (event: { systemPrompt: string }, ctx: unknown) => Promise<BeforeAgentResult | void> | BeforeAgentResult | void;
-	sessionShutdown?: (event: unknown, ctx: unknown) => void;
-}
-
-/** 构造 mock pi：捕获三 handler 引用，其余 prop 走 noop（仅 on 被调用）。 */
-function createMockPi(handlers: CapturedHandlers): ExtensionAPI {
-	const on = (event: string, handler: (...args: unknown[]) => unknown): void => {
-		if (event === "session_start") {
-			handlers.sessionStart = handler as CapturedHandlers["sessionStart"];
-		} else if (event === "before_agent_start") {
-			handlers.beforeAgentStart = handler as CapturedHandlers["beforeAgentStart"];
-		} else if (event === "session_shutdown") {
-			handlers.sessionShutdown = handler as CapturedHandlers["sessionShutdown"];
-		}
-	};
-	const noop = (): void => {
-		/* mock */
-	};
-	// setupSubagentListInjector 仅调 pi.on；用最小对象 + 双重断言满足 ExtensionAPI 契约
-	// （测试 mock 约定，见 crash-recovery.test.ts 的 Proxy 模式）
-	return { on, appendEntry: noop, registerTool: noop, registerCommand: noop, registerMessageRenderer: noop, events: { emit: noop, on: noop } } as unknown as ExtensionAPI;
-}
-
-/** 最小 ctx mock（注入器只读 ctx.cwd）。 */
-function createMockCtx(): Record<string, unknown> {
-	return { cwd: "/ws", mode: "tui" };
-}
-
 /** fixture：单个 worker agent 的 DiscoveredResource。 */
 function agentResource(path: string): DiscoveredResource {
 	return { path, source: "project-agents", available: true };
@@ -344,3 +285,52 @@ describe("subagent-list-injector session 级缓存", () => {
 		expect(r?.systemPrompt).toContain("<name>worker</name>");
 	});
 });
+
+// ──────────────────────────────────────────────────────────────
+// KV-cache 顺序契约：输出按 name 码点序，重建（两次发现）逐字节一致
+// ──────────────────────────────────────────────────────────────
+
+describe("discoverAllAgents 顺序契约（KV-cache）", () => {
+	it("输出按 name 码点序排序，与发现层返回顺序（readdir 枚举序）无关", async () => {
+		const byPath: Record<string, string> = {
+			"/ws/.agents/agents/zeta.md": agentMd("zeta", "z"),
+			"/ws/.agents/agents/worker.md": agentMd("worker", "w"),
+			"/ws/.agents/agents/alpha.md": agentMd("alpha", "a"),
+		};
+		// 刻意以非字母序返回（模拟 readdir 无契约枚举序）
+		spies.discoverResources.mockResolvedValue([
+			agentResource("/ws/.agents/agents/zeta.md"),
+			agentResource("/ws/.agents/agents/worker.md"),
+			agentResource("/ws/.agents/agents/alpha.md"),
+		]);
+		spies.getCachedFileContent.mockImplementation((p: string) => byPath[p] ?? null);
+
+		const { discoverAllAgents } = await import("../subagent-list-injector");
+		const agents = await discoverAllAgents("/ws", "/agent");
+		expect(agents.map((a) => a.name)).toEqual(["alpha", "worker", "zeta"]);
+	});
+
+	it("重建（两次发现）输出与渲染结果逐字节一致——目录不变时 session_start/fallback/resume 任意重建等价", async () => {
+		const byPath: Record<string, string> = {
+			"/ws/.agents/agents/b.md": agentMd("beta", "b"),
+			"/ws/.agents/agents/a.md": agentMd("alpha", "a"),
+		};
+		// 两次发现返回顺序不同（模拟跨进程 readdir 漂移）
+		spies.discoverResources
+			.mockResolvedValueOnce([
+				agentResource("/ws/.agents/agents/b.md"),
+				agentResource("/ws/.agents/agents/a.md"),
+			])
+			.mockResolvedValueOnce([
+				agentResource("/ws/.agents/agents/a.md"),
+				agentResource("/ws/.agents/agents/b.md"),
+			]);
+		spies.getCachedFileContent.mockImplementation((p: string) => byPath[p] ?? null);
+
+		const { discoverAllAgents, formatAgentList } = await import("../subagent-list-injector");
+		const first = await discoverAllAgents("/ws", "/agent");
+		const second = await discoverAllAgents("/ws", "/agent");
+		expect(second).toEqual(first);
+		expect(formatAgentList(second)).toBe(formatAgentList(first));
+	});
+});

package/src/injectors/__tests__/workflow-list-injector.test.ts

@@ -10,41 +10,17 @@
 
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
 import type { DiscoveredResource } from "../../shared/resource-discovery.ts";
+// 共享 mock 基建（vi.mock 工厂 / mock pi / mock ctx）：helpers/injector-test-mocks.ts
+import { createDiscoveryModuleMock, createLoggerModuleMock, createMockCtx, createMockPi, type CapturedHandlers } from "./helpers/injector-test-mocks.ts";
 
 // ── 稳定 spy（vi.hoisted 保证 resetModules 后引用不变，见 subagent 测试同款注释） ──
-const spies = vi.hoisted(() => ({
-	discoverResources: vi.fn(),
-	getCachedFileContent: vi.fn(),
-}));
-
-vi.mock("../../shared/resource-discovery.ts", () => ({
-	discoverResources: spies.discoverResources,
-	findWorkspaceRoot: () => "/ws",
-	getCachedFileContent: spies.getCachedFileContent,
-}));
-
-vi.mock("@zhushanwen/pi-extension-logger", () => ({
-	getLogger: () => ({
-		debug: () => {
-			/* no-op */
-		},
-		info: () => {
-			/* no-op */
-		},
-		warn: () => {
-			/* no-op */
-		},
-		error: () => {
-			/* no-op */
-		},
-	}),
-	setPiHandle: () => {
-		/* no-op */
-	},
-}));
+const spies = vi.hoisted(() => ({ discoverResources: vi.fn(), getCachedFileContent: vi.fn() }));
+
+vi.mock("../../shared/resource-discovery.ts", () => createDiscoveryModuleMock(spies));
+
+// 工厂必须写成箭头惰性形式（vi.mock 提升后直接传引用会 TDZ，见 helper 文件头注释）
+vi.mock("@zhushanwen/pi-extension-logger", () => createLoggerModuleMock());
 
 // ── 纯函数测试：静态 import（模块级缓存状态不影响纯函数） ──
 import {
@@ -178,43 +154,10 @@ describe("formatWorkflowList", () => {
 });
 
 // ──────────────────────────────────────────────────────────────
-// session 级缓存行为（TC1-TC4，与 subagent 对称）
+// session 级缓存行为（TC1-TC4，与 subagent 对称；mock pi/ctx 构造在
+// helpers/injector-test-mocks.ts）
 // ──────────────────────────────────────────────────────────────
 
-/** before_agent_start handler 的返回结构（取 systemPrompt 断言）。 */
-interface BeforeAgentResult {
-	systemPrompt: string;
-}
-
-/** 三 handler 捕获引用（setupWorkflowListInjector 注册后填充）。 */
-interface CapturedHandlers {
-	sessionStart?: (event: unknown, ctx: unknown) => Promise<void> | void;
-	beforeAgentStart?: (event: { systemPrompt: string }, ctx: unknown) => Promise<BeforeAgentResult | void> | BeforeAgentResult | void;
-	sessionShutdown?: (event: unknown, ctx: unknown) => void;
-}
-
-/** 构造 mock pi：捕获三 handler 引用，其余 prop 走 noop（仅 on 被调用）。 */
-function createMockPi(handlers: CapturedHandlers): ExtensionAPI {
-	const on = (event: string, handler: (...args: unknown[]) => unknown): void => {
-		if (event === "session_start") {
-			handlers.sessionStart = handler as CapturedHandlers["sessionStart"];
-		} else if (event === "before_agent_start") {
-			handlers.beforeAgentStart = handler as CapturedHandlers["beforeAgentStart"];
-		} else if (event === "session_shutdown") {
-			handlers.sessionShutdown = handler as CapturedHandlers["sessionShutdown"];
-		}
-	};
-	const noop = (): void => {
-		/* mock */
-	};
-	return { on, appendEntry: noop, registerTool: noop, registerCommand: noop, registerMessageRenderer: noop, events: { emit: noop, on: noop } } as unknown as ExtensionAPI;
-}
-
-/** 最小 ctx mock（注入器只读 ctx.cwd）。 */
-function createMockCtx(): Record<string, unknown> {
-	return { cwd: "/ws", mode: "tui" };
-}
-
 /** fixture：单个 workflow 的 DiscoveredResource。 */
 function workflowResource(path: string): DiscoveredResource {
 	return { path, source: "project-pi-tmp", available: true };
@@ -330,3 +273,50 @@ describe("workflow-list-injector session 级缓存", () => {
 		expect(r?.systemPrompt).toContain("<name>chain</name>");
 	});
 });
+
+// ──────────────────────────────────────────────────────────────
+// KV-cache 顺序契约：输出按 name 码点序，重建（两次发现）逐字节一致
+// ──────────────────────────────────────────────────────────────
+
+describe("discoverAllWorkflows 顺序契约（KV-cache）", () => {
+	it("输出按 name 码点序排序，与发现层返回顺序（readdir 枚举序）无关", async () => {
+		const byPath: Record<string, string> = {
+			"/ws/.pi/workflows/zeta.js": workflowJs("zeta", "z"),
+			"/ws/.pi/workflows/chain.js": workflowJs("chain", "c"),
+			"/ws/.pi/workflows/alpha.js": workflowJs("alpha", "a"),
+		};
+		spies.discoverResources.mockResolvedValue([
+			workflowResource("/ws/.pi/workflows/zeta.js"),
+			workflowResource("/ws/.pi/workflows/chain.js"),
+			workflowResource("/ws/.pi/workflows/alpha.js"),
+		]);
+		spies.getCachedFileContent.mockImplementation((p: string) => byPath[p] ?? null);
+
+		const { discoverAllWorkflows } = await import("../workflow-list-injector");
+		const workflows = await discoverAllWorkflows("/ws", "/agent");
+		expect(workflows.map((w) => w.name)).toEqual(["alpha", "chain", "zeta"]);
+	});
+
+	it("重建（两次发现顺序不同）输出与渲染结果逐字节一致", async () => {
+		const byPath: Record<string, string> = {
+			"/ws/.pi/workflows/b.js": workflowJs("beta", "b"),
+			"/ws/.pi/workflows/a.js": workflowJs("alpha", "a"),
+		};
+		spies.discoverResources
+			.mockResolvedValueOnce([
+				workflowResource("/ws/.pi/workflows/b.js"),
+				workflowResource("/ws/.pi/workflows/a.js"),
+			])
+			.mockResolvedValueOnce([
+				workflowResource("/ws/.pi/workflows/a.js"),
+				workflowResource("/ws/.pi/workflows/b.js"),
+			]);
+		spies.getCachedFileContent.mockImplementation((p: string) => byPath[p] ?? null);
+
+		const { discoverAllWorkflows, formatWorkflowList } = await import("../workflow-list-injector");
+		const first = await discoverAllWorkflows("/ws", "/agent");
+		const second = await discoverAllWorkflows("/ws", "/agent");
+		expect(second).toEqual(first);
+		expect(formatWorkflowList(second)).toBe(formatWorkflowList(first));
+	});
+});

package/src/injectors/model-list-injector.ts

@@ -0,0 +1,138 @@
+/**
+ * Model List Injector
+ *
+ * 通过 before_agent_start 每 turn 注入 `<available_provider_models>` 段，列出
+ * 当前 auth 可用的模型（provider/modelId + 能力 + contextWindow），与
+ * `<available_subagents>` / `<available_workflows>` 对称——三者合起来让模型掌握
+ * 派发所需的全部资源清单。
+ *
+ * 背景：模型列表的最大消费者是本包的 subagent/workflow `model` 参数（要求
+ * "provider/modelId" 格式，非法值直接 throw）。注入后模型可直接按 id 派发，
+ * 无需臆造模型名。
+ *
+ * 与另两个 injector 的差异：数据源不是文件发现而是 ModelRegistry.getAvailable()
+ * （pi 权威的 auth 可用模型快照，纯内存同步调用），因此：
+ * - 不需要 session_start 预热 / 渲染缓存 / session_shutdown 清理（无模块级
+ *   状态——结构上规避了缓存生命周期问题）
+ * - 每 turn 直接渲染；排序 (provider, id) 码点序保证输出字节稳定（turn 间
+ *   systemPrompt 前缀稳定 = KV cache 友好；跨环境逐字节可复现，与另两个
+ *   injector 的码点序契约对齐）。数据真实变化（用户中途配置了新 provider）
+ *   时下一 turn 自然反映。
+ *
+ * 立场：本注入段只服务「派发时选模型」，明确告知模型不要在会话中切换主模型
+ * （KV cache 不友好）；用户明确要求换模型时走 pi 原生 /model 命令（人手动触发）。
+ */
+
+import type {
+	Api,
+	Model,
+} from "@earendil-works/pi-ai";
+import type {
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+import { escapeXml, renderXmlSection } from "../shared/xml-injection.ts";
+
+const logger = getLogger("injector");
+
+/** 注入段的最小模型投影（从 Model<Api> 收窄，测试无需构造完整 Model） */
+export interface ModelEntry {
+	provider: string;
+	id: string;
+	name: string;
+	reasoning: boolean;
+	input: string[];
+	contextWindow: number;
+}
+
+/** Model<Api> → ModelEntry 投影（只留注入段消费的字段；模块内唯一消费方 setupModelListInjector） */
+function toModelEntry(model: Model<Api>): ModelEntry {
+	return {
+		provider: model.provider,
+		id: model.id,
+		name: model.name,
+		reasoning: model.reasoning,
+		input: [...model.input],
+		contextWindow: model.contextWindow,
+	};
+}
+
+/** 码点序比较（显式契约，禁 localeCompare——宿主 locale 差异会破坏跨环境字节一致）。 */
+function compareByCodepoint(a: string, b: string): number {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** 能力标记：reasoning → "reasoning"，input 含 image → "vision"（空则省略 caps 段） */
+function formatCaps(entry: ModelEntry): string {
+	const caps: string[] = [];
+	if (entry.reasoning) caps.push("reasoning");
+	if (entry.input.includes("image")) caps.push("vision");
+	return caps.join(",");
+}
+
+/**
+ * 将模型列表格式化为 XML 注入段。
+ *
+ * 输入按 (provider, id) 码点序排序——registry 返回顺序不作保证，排序后同一
+ * 数据集输出字节稳定。码点序是显式契约（禁 localeCompare——宿主 locale 差异
+ * 会破坏跨环境字节一致，见 subagent-list-injector.ts sortByCodepoint 注释），
+ * 保证注入段进每 turn system prompt 时跨环境逐字节可复现（cache-probe 前缀
+ * 指纹归因 / 换机器 resume 场景依赖此性质）。空列表返回空串（不注入）。
+ */
+export function formatModelList(models: ModelEntry[]): string {
+	if (models.length === 0) return "";
+
+	const sorted = [...models].sort((a, b) =>
+		a.provider === b.provider
+			? compareByCodepoint(a.id, b.id)
+			: compareByCodepoint(a.provider, b.provider),
+	);
+
+	const items = sorted.map((m) => {
+		const caps = formatCaps(m);
+		return (
+			`  <model><id>${escapeXml(`${m.provider}/${m.id}`)}</id>`
+				+ `<name>${escapeXml(m.name)}</name>`
+				+ (caps ? `<caps>${caps}</caps>` : "")
+				+ `<contextWindow>${m.contextWindow}</contextWindow></model>`
+		);
+	});
+	return renderXmlSection({
+		tag: "available_provider_models",
+		guide: "The following models are available (auth-configured). Use these ids when delegating via the subagent/workflow `model` param (\"provider/modelId\" format) to match the task (e.g. vision models for screenshots, strong reasoners for architecture). Do NOT switch the main conversation model mid-session — per-call model override on delegates only (switching the main model is cache-hostile); use the /model command only when the user explicitly asks to change it.",
+		items,
+	});
+}
+
+/**
+ * 注册 before_agent_start handler，注入 `<available_provider_models>` 段。
+ *
+ * 每 turn 从 ctx.modelRegistry.getAvailable() 同步取快照渲染注入；空列表不
+ * 返回 systemPrompt；任何异常被吞掉（记日志），不阻断 agent turn。与 subagent/
+ * workflow 注入 handler 链式（pi 串联多 handler 的 systemPrompt 返回值）。
+ */
+export function setupModelListInjector(pi: ExtensionAPI): void {
+	pi.on(
+		"before_agent_start",
+		async (
+			event: BeforeAgentStartEvent,
+			ctx: ExtensionContext,
+		): Promise<BeforeAgentStartEventResult | void> => {
+			try {
+				const injection = formatModelList(
+					ctx.modelRegistry.getAvailable().map(toModelEntry),
+				);
+				if (!injection) return;
+				return { systemPrompt: event.systemPrompt + injection };
+			} catch (err) {
+				logger.error("[model-list-injector] before_agent_start failed", {
+					reason: err instanceof Error ? err.message : String(err),
+				});
+			}
+		},
+	);
+}