@istuen/pt 0.1.0

package/dist/verify/ref-check.js

@@ -0,0 +1,88 @@
+// src/verify/ref-check.ts — Profile→Blueprint→Domain 引用完整性校验
+//
+// pt 引用图是三层星型（非 OXN Domain→Domain 网状），无环风险。
+// 校验重点是完整性：悬空引用检测。
+// 不校验 Blueprint.groups[].modules（H2 段名是模块类型声明，非 Domain 引用）。
+//
+// v11.x：Profile 全局 domains 覆盖是主用例——"未实例化"警告在该模式下静默
+// （未实例化 = 走全局分发，无 warning；只有 Profile 完全空 + 聚合组全空时才报 warning）。
+/** 校验单个 Profile 的引用完整性。
+ *  传入该 Profile 引用的 Blueprint（若存在）+ 全集 Domains。 */
+export function checkProfileRefs(profile, blueprints, domains) {
+    const errors = [];
+    const warnings = [];
+    const domainNames = new Set(domains.map((d) => d.name));
+    const _blueprintNames = new Set(blueprints.map((b) => b.name));
+    // 1. Profile → Blueprint 存在性
+    const bp = blueprints.find((b) => b.name === profile.blueprint);
+    if (!bp) {
+        errors.push(`Profile "${profile.name}" 引用的 Blueprint "${profile.blueprint}" 不存在`);
+    }
+    // 2. Profile → Domain（全局 domains）
+    for (const dn of profile.domains) {
+        if (!domainNames.has(dn)) {
+            errors.push(`Profile "${profile.name}" 的 domains 引用悬空 Domain "${dn}"`);
+        }
+    }
+    // 3. Profile.groups → Domain + 聚合组名匹配
+    for (const group of profile.groups) {
+        // 3a. 聚合组名应在 Blueprint 里有对应
+        if (bp) {
+            const bpGroup = bp.groups.find((bg) => bg.name === group.name);
+            if (!bpGroup) {
+                errors.push(`Profile "${profile.name}" 的聚合组 "${group.name}" 在 Blueprint "${bp.name}" 里无对应`);
+            }
+        }
+        // 3b. 聚合组引用的 Domain 存在
+        for (const dn of group.domains) {
+            if (!domainNames.has(dn)) {
+                errors.push(`Profile "${profile.name}" 聚合组 "${group.name}" 引用悬空 Domain "${dn}"`);
+            }
+        }
+    }
+    // 4. 警告：Blueprint 声明了聚合组但 Profile 未实例化（非错误——Profile 可只实例化部分聚合组）
+    //    v11.x：Profile 有全局 domains 时，聚合组未 H2 实例化是合法用法（全局分发到所有聚合组），
+    //    静默不报。只有 Profile 全空（无全局 domains + 无 H2 实例化）时才报"未实例化" warning。
+    if (bp && profile.domains.length === 0) {
+        for (const bpGroup of bp.groups) {
+            const hasProfileGroup = profile.groups.some((pg) => pg.name === bpGroup.name);
+            if (!hasProfileGroup) {
+                warnings.push(`Blueprint "${bp.name}" 的聚合组 "${bpGroup.name}" 在 Profile "${profile.name}" 里未实例化`);
+            }
+        }
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+/** 校验所有 Profile 的引用完整性（批量入口）。 */
+export function checkAllRefs(profiles, blueprints, domains) {
+    const allErrors = [];
+    const allWarnings = [];
+    for (const profile of profiles) {
+        const r = checkProfileRefs(profile, blueprints, domains);
+        allErrors.push(...r.errors);
+        allWarnings.push(...r.warnings);
+    }
+    return { ok: allErrors.length === 0, errors: allErrors, warnings: allWarnings };
+}
+/** 把 RefCheckResult 格式化为人类可读文本（pt_check_refs tool 输出用）。 */
+export function formatRefCheckResult(r) {
+    const lines = [];
+    if (r.ok && r.warnings.length === 0) {
+        lines.push("✓ 引用完整性检查通过，无悬空引用");
+        return lines.join("\n");
+    }
+    if (r.errors.length > 0) {
+        lines.push(`✗ ${r.errors.length} 个悬空引用：`);
+        for (const e of r.errors)
+            lines.push(`  - ${e}`);
+    }
+    if (r.warnings.length > 0) {
+        lines.push(`⚠ ${r.warnings.length} 个警告：`);
+        for (const w of r.warnings)
+            lines.push(`  - ${w}`);
+    }
+    if (r.ok && r.warnings.length > 0) {
+        lines.unshift("✓ 引用完整性检查通过（有警告）");
+    }
+    return lines.join("\n");
+}

package/dist/verify/test-pass.d.ts

@@ -0,0 +1,2 @@
+import type { ProbeOutcome } from "../schema.js";
+export declare function testPass(cwd: string, params: Record<string, string>): Promise<ProbeOutcome>;

package/dist/verify/test-pass.js

@@ -0,0 +1,17 @@
+// src/verify/test-pass.ts — 验证测试通过
+import { execSync } from "node:child_process";
+import { readStderr } from "./read-stderr.js";
+export async function testPass(cwd, params) {
+    const cmd = params.cmd ?? "npx vitest run tests/verify/";
+    try {
+        execSync(cmd, { cwd, stdio: "pipe", timeout: 120000 });
+        return { outcome: "COMPLETED", message: `测试通过: ${cmd}` };
+    }
+    catch (e) {
+        return {
+            outcome: "DEVIATED",
+            message: `测试失败: ${cmd}`,
+            actual: readStderr(e).slice(0, 500),
+        };
+    }
+}

package/dist/verify/ts-compiles.d.ts

@@ -0,0 +1,2 @@
+import type { ProbeOutcome } from "../schema.js";
+export declare function tsCompiles(cwd: string, params: Record<string, string>): Promise<ProbeOutcome>;

package/dist/verify/ts-compiles.js

@@ -0,0 +1,17 @@
+// src/verify/ts-compiles.ts — 验证 TS 编译通过
+import { execSync } from "node:child_process";
+import { readStderr } from "./read-stderr.js";
+export async function tsCompiles(cwd, params) {
+    const cmd = params.cmd ?? "npx tsc --noEmit";
+    try {
+        execSync(cmd, { cwd, stdio: "pipe", timeout: 60000 });
+        return { outcome: "COMPLETED", message: `TS 编译通过: ${cmd}` };
+    }
+    catch (e) {
+        return {
+            outcome: "DEVIATED",
+            message: `TS 编译失败: ${cmd}`,
+            actual: readStderr(e).slice(0, 500),
+        };
+    }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@istuen/pt",
+  "version": "0.1.0",
+  "description": "Pt \u2014 Turn domain knowledge into configurable Agent Context.",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "verify": "biome check && vitest run tests/verify/",
+    "verify:phase9": "vitest run tests/verify/phase9.test.ts",
+    "verify:flows": "vitest run tests/verify/flows.test.ts",
+    "prebuild": "tsc --noEmit && biome check",
+    "build": "tsup",
+    "prepublishOnly": "npm run build && npm run verify"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.11",
+    "@types/node": "^26.4.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.13",
+    "typescript": "^7.0.2",
+    "vitest": "^3.2.7"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "packageManager": "pnpm@10.11.0+sha512.6540583f41cc5f628eb3d9773ecee802f4f9ef9923cc45b69890fb47991d4b092964694ec3a4f738a420c918a333062c8b925d312f42e4f0c263eb603551f977",
+  "license": "MIT",
+  "author": "istuen <issac.tuen@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/istuen/pt.git"
+  },
+  "homepage": "https://github.com/istuen/pt#readme",
+  "bugs": {
+    "url": "https://github.com/istuen/pt/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/agent/api-bridge.ts

@@ -0,0 +1,105 @@
+// src/agent/api-bridge.ts — Pi ExtensionAPI ↔ AgentAPI 桥接（P1.3 抽出）
+//
+// 把 Pi ExtensionAPI 转换成 AgentAPI（结构类型子集）供 AgentAdapter 使用。
+// 同一个 Pi runtime 复用同一个 AgentAPI wrapper——否则 PiAdapter 每次 registerInject
+// 都会得到不同的对象身份，导致 system prompt handler 被重复注册。
+//
+// v12.x（issue pt-session-singleton-pi-web-pollution 修复）：
+//   - 原设计 `api.log` getter / `onInjected` 直接读写 module-level `session` 单例
+//     → tab B 的 wrapper.onInjected 写 tab B 的 lastBuiltPrompt 但走的是 module 单例
+//     → tab A 跑 turn 时 `lastBuiltPrompt` 也是 tab B 的（被覆盖）
+//   - 改造为 per-pi wrapper 内部维护 `currentSessionId` 闭包变量：
+//     - wrapper 的 `api.on` 包装函数在每个 handler 触发前自动从 `args[1]?.sessionManager`
+//       拿 sessionId 写入 `currentSessionId`
+//     - `api.log` getter / `onInjected` 通过 `currentSessionId` 走 `getSessionById(...)`
+//       取 per-session state
+//   - TUI 模式下只有一个 pi 实例，行为等同 module-level 单例（同一 sessionId 始终）
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentAPI, AgentUI } from "../schema.js";
+import { getSessionById } from "../session.js";
+
+/** AgentAPI 的 ui 字段类型（NonNullable<AgentAPI["ui"]>）。 */
+type AgentUIContext = AgentUI;
+
+/** 将 Pi ExtensionAPI 转换为 AgentAPI（结构类型子集，运行时透明）。
+ *  Pi ExtensionAPI 是 AgentAPI 的超集，多余方法（registerCommand/registerFlag 等）不暴露给 Adapter。
+ *  v9.1：提供 ui 能力，adapter 可走 ui.notify 报错 / ui.setStatus 设状态（不需 console）。
+ *  v10.x：提供 log 能力，adapter 的 try/catch 异常走 session.logger（不再 swallow）。
+ *  ctx 用 Pi 扩展的 ctx（ExtensionContext/ExtensionCommandContext 都含 ui）——子集够用。
+ *
+ *  同一个 Pi runtime 复用同一个 AgentAPI wrapper，否则 PiAdapter 每次 registerInject
+ *  都会得到不同的对象身份，导致系统 prompt handler 被重复注册。 */
+const agentApiCache = new WeakMap<
+  ExtensionAPI,
+  {
+    api: AgentAPI;
+    setContext: (ctx: { ui: AgentUIContext }) => void;
+    /** v12.x：当前触发中的 sessionId（wrapper.on 包装在 handler 触发前写入）。
+     *  api.log / api.onInjected 通过此字段拿 per-session state。 */
+    currentSessionId: string | undefined;
+  }
+>();
+
+export function toAgentAPI(pi: ExtensionAPI, ctx: { ui: AgentUIContext }): AgentAPI {
+  let holder = agentApiCache.get(pi);
+  if (!holder) {
+    let currentCtx = ctx;
+    // v12.x：closure 捕获 currentSessionId，供 api.log/onInjected 拿 per-session state
+    const stateRef: { currentSessionId: string | undefined } = { currentSessionId: undefined };
+
+    // v12.x：on 包装——handler 触发前自动从 args[1] ctx 拿 sessionId 注入 stateRef
+    const onWrapped = (event: string, handler: (...args: unknown[]) => unknown): void => {
+      pi.on(
+        event as Parameters<ExtensionAPI["on"]>[0],
+        ((event: unknown, extCtx: unknown) => {
+          // 提取 sessionId：extCtx 是 ExtensionContext
+          const c = extCtx as { sessionManager?: { getSessionId?: () => string } } | undefined;
+          stateRef.currentSessionId = c?.sessionManager?.getSessionId?.();
+          return handler(event, extCtx as unknown);
+        }) as Parameters<ExtensionAPI["on"]>[1]
+      );
+    };
+
+    const api: AgentAPI = {
+      on: onWrapped,
+      registerCommand: (name, spec) =>
+        pi.registerCommand(name, spec as Parameters<ExtensionAPI["registerCommand"]>[1]),
+      registerFlag: (name, spec) =>
+        pi.registerFlag(name, spec as Parameters<ExtensionAPI["registerFlag"]>[1]),
+      getFlag: (name) => pi.getFlag(name),
+      ui: {
+        notify: (msg, level) => currentCtx.ui.notify(msg, level),
+        setStatus: (name, text) => currentCtx.ui.setStatus(name, text),
+      },
+      // v12.x：api.log 走 per-session logger（避免 tab A 写到 tab B 的日志文件）
+      get log() {
+        const sid = stateRef.currentSessionId;
+        return sid ? getSessionById(sid).logger?.toWriter() : undefined;
+      },
+      // v12.x：onInjected 写 per-session lastBuiltPrompt
+      onInjected: (systemPrompt) => {
+        const sid = stateRef.currentSessionId;
+        if (sid) getSessionById(sid).lastBuiltPrompt = systemPrompt;
+      },
+    };
+    holder = {
+      api,
+      setContext: (nextCtx) => {
+        currentCtx = nextCtx;
+      },
+      currentSessionId: undefined,
+    };
+    // 把 stateRef 同步到 holder（保持单一来源）
+    Object.defineProperty(holder, "currentSessionId", {
+      get: () => stateRef.currentSessionId,
+      set: (v: string | undefined) => {
+        stateRef.currentSessionId = v;
+      },
+    });
+    agentApiCache.set(pi, holder);
+  } else {
+    holder.setContext(ctx);
+  }
+  return holder.api;
+}

package/src/agent/index.ts

@@ -0,0 +1,4 @@
+// src/agent/index.ts — Agent 适配器入口
+
+export { PiAdapter } from "./pi-adapter.js";
+export { getAgentAdapter } from "./registry.js";

package/src/agent/pi-adapter.ts

@@ -0,0 +1,326 @@
+// src/agent/pi-adapter.ts — PiAdapter：封装 Pi Agent 注入机制
+//
+// Phase 9.6：v9 新增 — AgentAdapter 的 Pi 实现。
+//   - system_prompt 注入：api.on("before_agent_start") 每轮追加 segment
+//   - context_message 触发：api.on("input") 拦截 /manual:xxx 和 /<flow-name>
+//   - 这些是 Agent Runtime 层（Pi API），本 Adapter 在该层做 session→system_prompt、turn→context_message 映射
+//
+// Pt 核心只调 AgentAdapter 接口，不直接调 Pi API。加新 Agent 只加 Adapter。
+//
+// Tech Debt T6: 全用 type guard 收窄，不用 as 断言（pt-quality #1）
+// Tech Debt T2: 用 constants 模块名常量（pt-quality #5）
+//
+// v12.x（issue pt-session-singleton-pi-web-pollution 修复）：
+//   - handler 内部读 `args[1]?.sessionManager?.getSessionId()` 拿 per-session sessionId
+//   - 通过 `getSessionById(sessionId)` 拿 per-session SessionState，**不再读 module-level 单例**
+//   - 配合 `src/agent/registry.ts` 的 per-pi WeakMap 改造，
+//     `this.ctx / this.blueprint / this.domains / this.segment / this.injectedApi` 五个实例字段
+//     现在是 per-pi 隔离——其他 session 的 setContext 不会覆盖本 session 的 segment
+
+import { AGENT_PI, MOD_FLOWS, MOD_RULES } from "../constants.js";
+import { isFlowTemplateArray, isRuleArray } from "../compile/type-guards.js";
+import { renderInjectionFooter } from "../injection-status.js";
+import { getSessionById } from "../session.js";
+import {
+  filterDomainsByProfile,
+  type AgentAdapter,
+  type AgentAPI,
+  type AgentContext,
+  type Blueprint,
+  type Domain,
+  type Profile,
+} from "../schema.js";
+import { renderTurnInject } from "../render/turn-inject.js";
+import { renderSessionInject } from "../render/session-inject.js";
+
+/** v12.x：从 handler 的 args[1] ctx 提取 sessionId。
+ *  pi 的 `pi.on(event, handler)` 触发时传 `(event, ctx)` 两个参数；通过 AgentAPI 包装后
+ *  handler 拿到 `(...args)`，args[0] = event, args[1] = ctx (ExtensionContext)。 */
+function sessionIdFromArgs(args: unknown[]): string | undefined {
+  const ctx = args[1] as { sessionManager?: { getSessionId?: () => string } } | undefined;
+  return ctx?.sessionManager?.getSessionId?.();
+}
+
+/** PiAdapter：封装 Pi Agent 的注入机制。 */
+export class PiAdapter implements AgentAdapter {
+  name = AGENT_PI;
+  /** Phase term-P4.3：保留 Pi API 名 system_prompt/context_message——
+   *  这是 AgentAdapter 映射边界声明（Pi 支持哪些 Agent Runtime 层注入位置）。
+   *  Blueprint 用 session/turn 语义值（聚合组 inject 字段），Adapter 内部映射到此字段声明的 Pi API 名。 */
+  supportedTargets = ["system_prompt", "context_message"];
+
+  private ctx: AgentContext | null = null;
+  private blueprint: Blueprint | null = null;
+  private domains: Domain[] = [];
+  private segment: string | null = null;
+  /** 与当前 Pi runtime 的 AgentAPI 绑定；同一 runtime 不重复注册 handler。
+   *  v12.x：per-pi 实例字段——`registry.ts` 给每个 pi 一个新 PiAdapter，所以 `injectedApi`
+   *  不会被其他 session 覆盖。 */
+  private injectedApi: AgentAPI | null = null;
+  /** v13.x（issue pt-turn-inject-not-profile-scoped）：当前 Profile——turn 路径 scope 过滤用。 */
+  private profile: Profile | null = null;
+
+  /** 设置编译产物（transpile 后调）。v12.x：per-pi 实例字段——本 session 的 segment
+   *  不会被其他 session 覆盖。
+   *  v13.x（issue pt-turn-inject-not-profile-scoped）：加 profile 参数——turn 路径 scope 过滤用。 */
+  setAgentContext(
+    ctx: AgentContext,
+    blueprint: Blueprint,
+    domains: Domain[],
+    profile: Profile
+  ): void {
+    this.ctx = ctx;
+    this.blueprint = blueprint;
+    this.domains = domains;
+    this.profile = profile;
+    this.segment = renderSessionInject(ctx, blueprint);
+  }
+
+  /** 清除当前 session 的 context；保留当前 runtime 的 handler 绑定。
+   *  v12.x：per-pi 实例字段——只清本 session 的状态。 */
+  resetInjection(): void {
+    this.ctx = null;
+    this.blueprint = null;
+    this.domains = [];
+    this.profile = null;
+    this.segment = null;
+  }
+
+  /** 启动时注册：把 AgentContext 注入到 Agent。 */
+  registerInject(
+    api: AgentAPI,
+    ctx: AgentContext,
+    blueprint: Blueprint,
+    domains: Domain[] = this.domains,
+    profile: Profile | null = this.profile
+  ): void {
+    // 先更新状态；同一 runtime 的后续 Profile 切换不能重新注册 handler，
+    // 但 handler 会在事件发生时读取最新的 this.segment / this.ctx。
+    this.ctx = ctx;
+    this.blueprint = blueprint;
+    this.domains = domains;
+    this.profile = profile;
+    this.segment = renderSessionInject(ctx, blueprint);
+
+    if (this.injectedApi === api) {
+      api.log?.debug("agent:registerInject skipped (already injected)");
+      return;
+    }
+    this.injectedApi = api;
+
+    // session 注入（inject=session → Pi system_prompt 事件）：每轮追加 segment
+    // v10.x：包 try/catch，运行时异常走 api.log.error + ui.notify，不再 swallow
+    // v11.x（issue pt-injection-status-manual-track）：三分支写 session.injectionState +
+    //   调 api.ui?.setStatus，让 footer 三态文字真实反映注入结果（自报，不检测 Pi）
+    // v12.x：从 args[1] ctx 拿 per-session sessionId，写 per-session SessionState
+    api.on("before_agent_start", async (...args: unknown[]) => {
+      const t0 = Date.now();
+      try {
+        const sessionId = sessionIdFromArgs(args);
+        const sessionState = sessionId ? getSessionById(sessionId) : null;
+
+        const currentSegment = this.segment;
+        // v14.x（issue pt-asset-migration-visibility Layer 2）：footer 末尾追加 ⚠ N issues。
+        //   从 sessionState.assetHealthIssues 读计数——session_start 已批量体检过。
+        const healthCount = sessionState?.assetHealthIssues?.length ?? 0;
+        // v14.x（tagline）：footer 拼 `: <tagline>`。从 sessionState.cachedProfile 读——transpile 时已存。
+        const tagline = sessionState?.cachedProfile?.tagline ?? null;
+        if (!currentSegment) {
+          // 无 segment（未加载 Profile / 已被 reset）→ idle
+          if (sessionState) {
+            sessionState.injectionState = "idle";
+            sessionState.injectionError = null;
+            api.ui?.setStatus(
+              "pt",
+              renderInjectionFooter(
+                "idle",
+                sessionState.activeProfile,
+                null,
+                healthCount,
+                "auto",
+                tagline
+              )
+            );
+          }
+          return undefined;
+        }
+        const event = args[0];
+        if (!isSystemPromptEvent(event)) {
+          // 事件形状异常：归类为 idle（不视为失败——Pi 可能改了事件签名）
+          if (sessionState) {
+            sessionState.injectionState = "idle";
+            sessionState.injectionError = null;
+            api.ui?.setStatus(
+              "pt",
+              renderInjectionFooter(
+                "idle",
+                sessionState.activeProfile,
+                null,
+                healthCount,
+                "auto",
+                tagline
+              )
+            );
+          }
+          return undefined;
+        }
+        const final = `${event.systemPrompt}\n\n## 当前任务上下文\n\n${currentSegment}`;
+        api.log?.debug("agent:before_agent_start ok", {
+          originalLen: event.systemPrompt.length,
+          injectedLen: final.length,
+          deltaLen: final.length - event.systemPrompt.length,
+          durationMs: Date.now() - t0,
+        });
+        if (sessionState) {
+          api.onInjected?.(final);
+          // 成功注入 → injected
+          sessionState.injectionState = "injected";
+          sessionState.injectionError = null;
+          api.ui?.setStatus(
+            "pt",
+            renderInjectionFooter(
+              "injected",
+              sessionState.activeProfile,
+              null,
+              healthCount,
+              "auto",
+              tagline
+            )
+          );
+        } else {
+          api.onInjected?.(final);
+        }
+        return { systemPrompt: final };
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        api.log?.error("agent:before_agent_start failed", {
+          err: msg,
+          durationMs: Date.now() - t0,
+        });
+        api.ui?.notify(`[pt] before_agent_start failed: ${msg}`, "error");
+        // 异常 → failed + 错误消息（footer 追加）
+        const sessionId = sessionIdFromArgs(args);
+        const sessionState = sessionId ? getSessionById(sessionId) : null;
+        // v14.x：catch 路径同样透传 healthCount + tagline（避免修复丢告警 / tagline）
+        const healthCount = sessionState?.assetHealthIssues?.length ?? 0;
+        const tagline = sessionState?.cachedProfile?.tagline ?? null;
+        if (sessionState) {
+          sessionState.injectionState = "failed";
+          sessionState.injectionError = msg;
+          api.ui?.setStatus(
+            "pt",
+            renderInjectionFooter(
+              "failed",
+              sessionState.activeProfile,
+              msg,
+              healthCount,
+              "auto",
+              tagline
+            )
+          );
+        }
+        return undefined; // 失败降级, 不影响主流程
+      }
+    });
+
+    // context_message 触发：/manual:xxx + /<flow-name>
+    // v10.x：包 try/catch，renderTurnInject 抛错不再 swallow
+    api.on("input", async (...args: unknown[]) => {
+      const t0 = Date.now();
+      try {
+        if (!this.ctx || !this.blueprint) return { action: "continue" };
+        const event = args[0];
+        if (!isInputEvent(event)) return { action: "continue" };
+        // Phase term-P4.3：renderContextMessage → renderTurnInject
+        // v13.x（issue pt-turn-inject-not-profile-scoped）：按 Profile scope 过滤 domains + 传 profile
+        //   让 /manual:<domain> 在未引用该 domain 的 Profile 下返 null（与 /pt flows 列表一致）
+        const scoped = filterDomainsByProfile(this.domains, this.profile);
+        const result = renderTurnInject(this.ctx, this.blueprint, scoped, this.profile, event.text);
+        const durationMs = Date.now() - t0;
+        if (result === null) {
+          api.log?.debug("agent:input passthrough", {
+            inputPreview: event.text.slice(0, 80),
+            durationMs,
+          });
+          return { action: "continue" };
+        }
+        api.log?.info("agent:input transformed", {
+          inputPreview: event.text.slice(0, 80),
+          outputLen: result.length,
+          durationMs,
+        });
+        return { action: "transform", text: result };
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        api.log?.error("agent:input render failed", {
+          err: msg,
+          input: args[0],
+          durationMs: Date.now() - t0,
+        });
+        api.ui?.notify(`[pt] input render failed: ${msg}`, "error");
+        return { action: "continue" }; // 失败降级: 不拦截 input, 让原文本过 LLM
+      }
+    });
+  }
+
+  /** 查询可用手册（/pt flows 用）。
+   *  v9：遍历 Blueprint 的 inject=turn 聚合组 → 引用 Domain → 找 FlowTemplate + Rules 段的 Rule。 */
+  listManuals(
+    _ctx: AgentContext,
+    blueprint: Blueprint,
+    domains: Domain[]
+  ): Array<{ name: string; hint?: string; domain: string }> {
+    const flows: Array<{ name: string; hint?: string; domain: string }> = [];
+
+    for (const group of blueprint.groups) {
+      // Phase term-P4.3：inject 语义值 context_message → turn
+      // Phase term-naming：字段名 target → inject
+      if (group.inject !== "turn") continue;
+      // v13.x（issue pt-turn-inject-not-profile-scoped）：按 Profile scope 过滤 domains——
+      // adapter 内部统一过滤，调用方（commands.ts flowsText）无需预过滤。
+      const scoped = filterDomainsByProfile(domains, this.profile);
+      for (const d of scoped) {
+        // Phase term-P9.2：FlowTemplate 在 ## Flows 段；Rule[] 在 ## Rules 段；Checklist[] 在 ## Checklists 段。
+        const flowsContent = d.modules[MOD_FLOWS];
+        if (isFlowTemplateArray(flowsContent)) {
+          for (const t of flowsContent) {
+            flows.push({ name: t.name, hint: t.argumentHint, domain: d.name });
+          }
+        }
+        const rulesContent = d.modules[MOD_RULES];
+        if (isRuleArray(rulesContent) && rulesContent.length > 0) {
+          // term-Domain 的 Rule[] 作为 /manual:<domain> 暴露
+          flows.push({
+            name: `/manual:${d.name}`,
+            hint: `${rulesContent.length} 条规范`,
+            domain: d.name,
+          });
+        }
+        // Checklist[] 暂不单独暴露——/manual:<domain> 命令会统一处理（renderDomainManual）
+      }
+    }
+
+    // 去重（按 name）
+    const seen = new Set<string>();
+    return flows.filter((f) => {
+      const key = `${f.domain}/${f.name}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+}
+
+// ==================== Pi ExtensionAPI 事件 type guards ====================
+
+function isSystemPromptEvent(x: unknown): x is { systemPrompt: string } {
+  return (
+    !!x &&
+    typeof x === "object" &&
+    typeof (x as { systemPrompt?: unknown }).systemPrompt === "string"
+  );
+}
+
+function isInputEvent(x: unknown): x is { text: string } {
+  return !!x && typeof x === "object" && typeof (x as { text?: unknown }).text === "string";
+}

package/src/agent/registry.ts

@@ -0,0 +1,44 @@
+// src/agent/registry.ts — AgentAdapter 注册表
+//
+// Phase 9.6：v9 新增 — 按 Agent 名取 Adapter 实例。
+// 加新 Agent（如 Codex / OpenCode）只在这里加一行注册 + 实现 Adapter。
+//
+// v12.x（issue pt-session-singleton-pi-web-pollution 修复）：
+//   - 原设计 `agentAdapters: Record<string, AgentAdapter>` 是 module-level 单例
+//     → 所有 session 共享同一个 PiAdapter 实例 → 单例 `this.segment / this.ctx /
+//       this.blueprint / this.domains / this.injectedApi` 跨 session 被覆盖
+//     → tab B 调 setContext 覆盖 this.segment → tab A 的 before_agent_start handler
+//       读到 tab B 的 segment → LLM 拿到错业务上下文（业务上下文级污染）
+//   - 改造为 `WeakMap<ExtensionAPI, Record<string, AgentAdapter>>`：
+//     - 每 session 一份 `Record<name, Adapter>` 缓存
+//     - pi 实例销毁时（pi-web session 退出）WeakMap 自动 GC
+//     - TUI 模式只有一个 pi 实例，行为等同 module-level 单例
+//   - getAgentAdapter 签名改成 `(pi, name)`：调用方传 pi 作 key
+//     - `src/index.ts:105` `transpileActive` 改 `getAgentAdapter(pi, ...)`
+//     - `src/index.ts:70-77` `registerInjectionIfReady` 调 `adapter.registerInject(...)`
+//       时拿到的 adapter 已是 per-pi 实例，handler 闭包持 this（per-pi），this.segment
+//       不被其他 session 覆盖
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentAdapter } from "../schema.js";
+import { PiAdapter } from "./pi-adapter.js";
+
+/** v12.x：per-pi Adapter 缓存（弱引用，pi 实例销毁后自动 GC）。 */
+const adapterCache = new WeakMap<ExtensionAPI, Record<string, AgentAdapter>>();
+
+/** 取指定 pi + name 的 AgentAdapter。未找到返 pi 的 per-pi 实例（fallback）。 */
+export function getAgentAdapter(pi: ExtensionAPI, name: string): AgentAdapter {
+  let cache = adapterCache.get(pi);
+  if (!cache) {
+    cache = {};
+    adapterCache.set(pi, cache);
+  }
+  let adapter = cache[name];
+  if (!adapter) {
+    // 当前只支持 pi；未来 codex/opencode 在这里 switch name
+    adapter = new PiAdapter();
+    cache[name] = adapter;
+    if (!cache.pi) cache.pi = adapter; // 把 fallback 也指到同一实例
+  }
+  return adapter;
+}