@zhushanwen/pi-subagent-workflow 8.6.0 → 8.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.6.0",
+  "version": "8.7.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -21,15 +21,13 @@
     "index.ts",
     "agents/",
     "skills/",
-    "workflows/",
     "scripts/",
     "relay/",
     "src/index.ts",
-    "src/execution/",
+    "src/jsonl-run-store.ts",
+    "src/host/",
     "src/injectors/",
-    "src/orchestration/",
-    "src/interface/",
-    "src/shared/"
+    "src/interface/"
   ],
   "xyz-agent": {
     "role": "universal",
@@ -59,17 +57,15 @@
     ]
   },
   "dependencies": {
-    "ajv": "^8.20.0",
-    "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.7.0",
     "@xyz-agent/session-delivery": "0.3.0",
     "@zhushanwen/pi-extension-logger": "0.3.0",
-    "@zhushanwen/pi-file-lock": "0.1.2"
+    "@xyz-agent/extension-protocol": "0.7.0",
+    "@zhushanwen/subagent-core": "0.2.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-tui": "^0.84.1",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
     "@zhushanwen/pi-pending-notifications": "0.5.0",
     "@zhushanwen/pi-structured-output": "5.1.0"

package/relay/relay.mjs

@@ -8,7 +8,7 @@
  * 通道，payload 一律 base64 封装保字节精确。
  *
  * ============================ 镜像常量表 ============================
- * SSOT = src/execution/relay-env.ts（零依赖脚本不能 import workspace 包，只能内嵌镜像；
+ * SSOT = packages/subagent-core/src/execution/relay-env.ts（零依赖脚本不能 import workspace 包，只能内嵌镜像；
  * 改名/改值必须双侧同步，一致性由 E-3 conformance relay 变体断言锁定——设计 §10-5）：
  *
  *   | relay-env.ts 常量         | 本文件常量                | 值                          |

package/src/host/__tests__/pi-host.test.ts

@@ -0,0 +1,214 @@
+// pi-host.test.ts —— pi 壳宿主实现与现行为等价（u0-wire 验收①）。
+//
+// 三视角：①使用者——discoveryRoots 各 kind 的根清单/顺序/source 标签与
+// resource-discovery.ts buildScanTargets（user-pi/npm/npm-dev 段）、
+// skill-discovery.ts resolveSkillPath（skills 两根）现推导逐项一致；
+// ②构建者——dataRoot/log/countActiveFromEntries/createDelivery 四端口桥接形态；
+// ③观察者——getAgentDir 每次现取（PI_CODING_AGENT_DIR 实例隔离切换后重取生效，
+// 无模块级缓存）。
+//
+// mock 策略：pi SDK / pi 宿主协作件全部 vi.mock 工厂覆盖（vitest alias 的
+// mocks/ 桩只供其他测试族用，本文件需要可控返回值）。pending-notifications
+// mock 返回 {count: n} 形状直接验证「适配读 .count」；session-delivery mock
+// 验证 createDelivery 透传（参数 + 返回句柄）。
+
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── hoisted mocks（vi.mock 工厂 hoisting 不能引用外部 let/const） ──
+
+const piCodingAgentMock = vi.hoisted(() => ({
+  // 与实装版 getAgentDir 的 env 契约一致（PI_CODING_AGENT_DIR 实例隔离优先），
+  // 使「env 切换后重取生效」可直接断言；缺省值仅作 fallback。
+  getAgentDir: vi.fn(() => process.env.PI_CODING_AGENT_DIR ?? "/mock/default/agent-dir"),
+}));
+
+const extensionLoggerMock = vi.hoisted(() => ({
+  getLogger: vi.fn(),
+}));
+
+const pendingNotificationsMock = vi.hoisted(() => ({
+  countActiveFromEntries: vi.fn(),
+}));
+
+const sessionDeliveryMock = vi.hoisted(() => ({
+  createDelivery: vi.fn(),
+}));
+
+vi.mock("@earendil-works/pi-coding-agent", () => piCodingAgentMock);
+vi.mock("@zhushanwen/pi-extension-logger", () => extensionLoggerMock);
+vi.mock("@zhushanwen/pi-pending-notifications", () => pendingNotificationsMock);
+vi.mock("@xyz-agent/session-delivery", () => sessionDeliveryMock);
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { countActiveFromEntries } from "@zhushanwen/pi-pending-notifications";
+import { createDelivery } from "@xyz-agent/session-delivery";
+
+import { createPiHostServices, createPiNotifyDomainPorts } from "../pi-host.ts";
+
+beforeEach(() => {
+  vi.mocked(getAgentDir).mockClear();
+  vi.mocked(getLogger).mockReset();
+  vi.mocked(countActiveFromEntries).mockReset();
+  vi.mocked(createDelivery).mockReset();
+  delete process.env.PI_CODING_AGENT_DIR;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  delete process.env.PI_CODING_AGENT_DIR;
+});
+
+describe("createPiHostServices.discoveryRoots（与现推导逐项一致）", () => {
+  // 基线锚点：resource-discovery.ts buildScanTargets（join(agentDir, kind) /
+  // join(agentDir, "npm", "node_modules") / join(agentDir, "extensions")）与
+  // skill-discovery.ts resolveSkillPath（join(getAgentDir(), "skills") +
+  // join(getAgentDir(), "npm/node_modules")）。根列表按优先级低→高排列（D2）。
+  const AGENT_DIR = "/fake/agent-dir";
+
+  function stubAgentDir(): void {
+    vi.mocked(getAgentDir).mockReturnValue(AGENT_DIR);
+  }
+
+  it("agents 三根：顺序与 source 标签 = user-pi → npm → npm-dev", () => {
+    stubAgentDir();
+    const roots = createPiHostServices().discoveryRoots?.().agents;
+
+    expect(roots).toEqual([
+      { dir: join(AGENT_DIR, "agents"), source: "user-pi" },
+      { dir: join(AGENT_DIR, "npm", "node_modules"), source: "npm" },
+      { dir: join(AGENT_DIR, "extensions"), source: "npm-dev" },
+    ]);
+  });
+
+  it("workflows 三根：与 agents 同构，末级目录名切换为 workflows", () => {
+    stubAgentDir();
+    const roots = createPiHostServices().discoveryRoots?.().workflows;
+
+    expect(roots).toEqual([
+      { dir: join(AGENT_DIR, "workflows"), source: "user-pi" },
+      { dir: join(AGENT_DIR, "npm", "node_modules"), source: "npm" },
+      { dir: join(AGENT_DIR, "extensions"), source: "npm-dev" },
+    ]);
+  });
+
+  it("skills 两根：user-pi + npm，无 npm-dev（对齐 skill-discovery 现状）", () => {
+    stubAgentDir();
+    const roots = createPiHostServices().discoveryRoots?.().skills;
+
+    expect(roots).toEqual([
+      { dir: join(AGENT_DIR, "skills"), source: "user-pi" },
+      { dir: join(AGENT_DIR, "npm", "node_modules"), source: "npm" },
+    ]);
+  });
+
+  it("每次调用现取 getAgentDir（agentDir 变更后根列表跟随，不缓存）", () => {
+    stubAgentDir();
+    const first = createPiHostServices().discoveryRoots?.().agents;
+    const secondCallDir = "/another/agent-dir";
+    vi.mocked(getAgentDir).mockReturnValue(secondCallDir);
+    const second = createPiHostServices().discoveryRoots?.().agents;
+
+    expect(second?.[0].dir).toBe(join(secondCallDir, "agents"));
+    expect(first?.[0].dir).not.toBe(second?.[0].dir);
+  });
+});
+
+describe("createPiHostServices.dataRoot（每次现取 getAgentDir）", () => {
+  it("返回 getAgentDir() 本身（env 覆盖段与 warn-once 留 core data-dir）", () => {
+    vi.mocked(getAgentDir).mockReturnValue("/data/root");
+    expect(createPiHostServices().dataRoot()).toBe("/data/root");
+  });
+
+  it("PI_CODING_AGENT_DIR 切换后重取生效（实例隔离，无模块级缓存）", () => {
+    // 恢复 mock 工厂的 env 语义实现（其他用例的 mockReturnValue 会覆盖它）
+    vi.mocked(getAgentDir).mockImplementation(
+      () => process.env.PI_CODING_AGENT_DIR ?? "/mock/default/agent-dir",
+    );
+    process.env.PI_CODING_AGENT_DIR = "/instance-a";
+    const host = createPiHostServices();
+    expect(host.dataRoot()).toBe("/instance-a");
+
+    process.env.PI_CODING_AGENT_DIR = "/instance-b";
+    expect(host.dataRoot()).toBe("/instance-b");
+  });
+
+  it("透传 getAgentDir 调用（不缓存结果、不吞调用）", () => {
+    vi.mocked(getAgentDir).mockReturnValue("/d1");
+    const host = createPiHostServices();
+    host.dataRoot();
+    host.dataRoot();
+    expect(vi.mocked(getAgentDir)).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("createPiHostServices.log（桥接 pi-extension-logger）", () => {
+  function stubLogger(): { debug: ReturnType<typeof vi.fn>; warn: ReturnType<typeof vi.fn>; error: ReturnType<typeof vi.fn> } {
+    const fake = { debug: vi.fn(), warn: vi.fn(), error: vi.fn() };
+    vi.mocked(getLogger).mockReturnValue(fake);
+    return fake;
+  }
+
+  it("debug level → logger.debug，(message, data) 透传", () => {
+    const fake = stubLogger();
+    createPiHostServices().log("debug", "subagents", "d-msg", { k: 1 });
+
+    expect(vi.mocked(getLogger)).toHaveBeenCalledWith("subagents");
+    expect(fake.debug).toHaveBeenCalledWith("d-msg", { k: 1 });
+    expect(fake.warn).not.toHaveBeenCalled();
+    expect(fake.error).not.toHaveBeenCalled();
+  });
+
+  it("warn level → logger.warn；error level → logger.error", () => {
+    const fake = stubLogger();
+    const host = createPiHostServices();
+
+    host.log("warn", "comp-a", "w-msg");
+    host.log("error", "comp-b", "e-msg", { reason: "x" });
+
+    expect(fake.warn).toHaveBeenCalledWith("w-msg", undefined);
+    expect(fake.error).toHaveBeenCalledWith("e-msg", { reason: "x" });
+    expect(vi.mocked(getLogger)).toHaveBeenNthCalledWith(1, "comp-a");
+    expect(vi.mocked(getLogger)).toHaveBeenNthCalledWith(2, "comp-b");
+  });
+});
+
+describe("createPiNotifyDomainPorts.countActiveFromEntries（适配读 .count）", () => {
+  it("拆 CountActiveResult.count 为 number（core 端口契约），entries 透传", () => {
+    const entries: unknown[] = [{ customType: "pending:register" }];
+    vi.mocked(countActiveFromEntries).mockReturnValue({ count: 3, ids: ["a", "b", "c"], entries: [] });
+
+    const result = createPiNotifyDomainPorts().countActiveFromEntries?.(entries);
+
+    expect(result).toBe(3);
+    expect(vi.mocked(countActiveFromEntries)).toHaveBeenCalledWith(entries);
+  });
+
+  it("零活跃返回 0（{count: 0} 形状）", () => {
+    vi.mocked(countActiveFromEntries).mockReturnValue({ count: 0, ids: [], entries: [] });
+    expect(createPiNotifyDomainPorts().countActiveFromEntries?.([])).toBe(0);
+  });
+});
+
+describe("createPiNotifyDomainPorts.createDelivery（透传 session-delivery）", () => {
+  it("参数透传 + 返回句柄透传（不经包装）", () => {
+    const fakePort = {
+      supportedPayloads: ["text"] as const,
+      isIdle: () => true,
+      hasPendingMessages: () => false,
+      send: () => undefined,
+    };
+    const fakeConfig = { intent: "after-run" as const };
+    const fakeHandle = { send: () => {}, flush: () => {}, dispose: () => {} };
+    vi.mocked(createDelivery).mockReturnValue(fakeHandle);
+
+    const result = createPiNotifyDomainPorts().createDelivery?.(fakePort, fakeConfig);
+
+    expect(vi.mocked(createDelivery)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(createDelivery).mock.calls[0][0]).toBe(fakePort);
+    expect(vi.mocked(createDelivery).mock.calls[0][1]).toBe(fakeConfig);
+    expect(result).toBe(fakeHandle);
+  });
+});

package/src/host/pi-host.ts

@@ -0,0 +1,109 @@
+// src/host/pi-host.ts
+//
+// pi 壳宿主实现（subagent-core 包抽离 u0-wire）。设计权威源：
+// docs/design/subagent-core-package-extraction.md §3.3 D2（含计划期契约细化 3 条）。
+//
+// 本文件属壳侧（shell），不进 core 切面——对 pi SDK 与 pi 宿主协作件
+// （@earendil-works/pi-coding-agent / @zhushanwen/pi-extension-logger /
+// @zhushanwen/pi-pending-notifications / @xyz-agent/session-delivery）的运行时
+// import 收敛在此层，core 闭包（D9 守卫对象）不得出现这些包。
+//
+// 端口语义：
+//   - dataRoot / discoveryRoots 每次调用现取 getAgentDir()，禁止模块级缓存：
+//     getAgentDir 尊重 PI_CODING_AGENT_DIR 实例隔离（xyz-agent 按 session dir
+//     隔离 pi 实例），缓存会把后续切换实例的进程钉死在首个 agentDir。
+//   - discoveryRoots 的根清单/顺序/source 标签与 shared/resource-discovery.ts
+//     buildScanTargets、orchestration/skill-discovery.ts resolveSkillPath 的现推导
+//     逐项一致（user-pi / npm / npm-dev 字面即现 ResourceSource 标签）。
+//     project/workspace 根不在壳侧提供——core 消费方按 workspaceRoot 自行推导
+//     （u0-data-discovery 波次接注入消费）。
+//   - countActiveFromEntries 适配：pi 侧真函数返回 CountActiveResult 对象，core
+//     端口契约是 number（core 消费面只读 .count，notify-ports.ts 契约注释）——
+//     foundation 单元登记给本单元的适配责任。
+//   - createDelivery 透传：@xyz-agent/session-delivery 的 createDelivery 与 core
+//     的 Delivery* 结构化类型逐字段结构兼容（DeliveryHandle 的 sendChecked/depth
+//     是结构超集成员，多不碍兼容）——结构兼容由本注入点 typecheck 守护，上游签名
+//     漂移即红（notify-ports.ts「闭包红线」段）。
+
+import { join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { countActiveFromEntries } from "@zhushanwen/pi-pending-notifications";
+import { createDelivery } from "@xyz-agent/session-delivery";
+
+import type { DiscoveryRoot, HostServices } from "@zhushanwen/subagent-core/core/host-services.ts";
+import type { LogLevel } from "@zhushanwen/subagent-core/core/logger.ts";
+import type { NotifyDomainPorts } from "@zhushanwen/subagent-core/core/notify-ports.ts";
+
+/** agents/workflows 共享的 agentDir 派生根（末级目录名由 kind 决定）。
+ *  顺序与 source 标签逐项对齐 resource-discovery.ts buildScanTargets 的
+ *  user-pi → npm → npm-dev 段（根列表按优先级低→高排列，D2 语义边界）。 */
+function agentDirKindRoots(kind: "agents" | "workflows"): DiscoveryRoot[] {
+  const agentDir = getAgentDir();
+  return [
+    // 1. user .pi/agent/<kind>/
+    { dir: join(agentDir, kind), source: "user-pi" },
+    // 2. npm global: agentDir/npm/node_modules/*/<pkg>/
+    { dir: join(agentDir, "npm", "node_modules"), source: "npm" },
+    // 3. npm dev symlink: agentDir/extensions/*/<pkg>/
+    { dir: join(agentDir, "extensions"), source: "npm-dev" },
+  ];
+}
+
+/** skills 的 agentDir 派生根。对齐 skill-discovery.ts resolveSkillPath 的两处
+ *  推导（<agentDir>/skills + <agentDir>/npm/node_modules）——现状无 npm-dev 根，
+ *  刻意不补（避免静默引入新发现源）。 */
+function skillRoots(): DiscoveryRoot[] {
+  const agentDir = getAgentDir();
+  return [
+    { dir: join(agentDir, "skills"), source: "user-pi" },
+    { dir: join(agentDir, "npm", "node_modules"), source: "npm" },
+  ];
+}
+
+/** pi 宿主 HostServices 实现（扩展初始化最早处经 configureCore 注入）。 */
+export function createPiHostServices(): HostServices {
+  return {
+    // 每次现取 getAgentDir（实例隔离，见文件头）；env 覆盖段与 warn-once 留 core
+    // data-dir.ts，壳只返回数据根本身（D2 计划期细化③分段归属）。
+    dataRoot(): string {
+      return getAgentDir();
+    },
+
+    // 桥接到 pi-extension-logger：component 即 extName（复用其 loggerCache 单例
+    // 与 appendEntry/文件日志通路），按 level 分派方法，(message, data) 透传。
+    log(level: LogLevel, component: string, message: string, data?: unknown): void {
+      const logger = getLogger(component);
+      if (level === "error") logger.error(message, data);
+      else if (level === "warn") logger.warn(message, data);
+      else logger.debug(message, data);
+    },
+
+    discoveryRoots(): {
+      agents?: DiscoveryRoot[];
+      skills?: DiscoveryRoot[];
+      workflows?: DiscoveryRoot[];
+    } {
+      return {
+        agents: agentDirKindRoots("agents"),
+        skills: skillRoots(),
+        workflows: agentDirKindRoots("workflows"),
+      };
+    },
+  };
+}
+
+/** pi 侧通知域窄端口实现（configureNotifyDomain 注入）。zsw 壳不注入本端口
+ *  （其完成通知走 HostServices.notify，P2 落地）。 */
+export function createPiNotifyDomainPorts(): NotifyDomainPorts {
+  return {
+    // pi 真函数返回 CountActiveResult，core 契约只读 .count——壳侧拆数值。
+    countActiveFromEntries(entries: unknown[]): number {
+      return countActiveFromEntries(entries).count;
+    },
+
+    // 投递内核工厂直传本体（结构兼容论证见文件头）；不经包装避免多一层间接面。
+    createDelivery,
+  };
+}

package/src/index.ts

@@ -20,37 +20,47 @@ import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, SessionComp
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 
-import { bestEffort } from "./execution/best-effort.ts";
+// ═══ core 宿主端口接线（subagent-core 包抽离 u0-wire；实现见 src/host/pi-host.ts） ═══
+import { configureCore } from "@zhushanwen/subagent-core/core/host-services.ts";
+import { configureNotifyDomain } from "@zhushanwen/subagent-core/core/notify-ports.ts";
+import { createPiHostServices, createPiNotifyDomainPorts } from "./host/pi-host.ts";
+
+import { bestEffort } from "@zhushanwen/subagent-core/execution/best-effort.ts";
 // ═══ execution/ 层（subagents 核心 + 运行时） ═══
-import { getOrCreateChannelRegistry } from "./execution/channel-registry-access.ts";
-import { DialogGlobalQueue } from "./execution/dialog-queue.ts";
+import { getOrCreateChannelRegistry } from "@zhushanwen/subagent-core/execution/channel-registry-access.ts";
+import { DialogGlobalQueue } from "@zhushanwen/subagent-core/execution/dialog-queue.ts";
+// [engine-awareness U3] 全局 config 三态读取（检测 poll 与 session_start 基线共用）
+import { readGlobalConfig } from "@zhushanwen/subagent-core/execution/config.ts";
 // [U7] 引擎列表状态文件（registry → engines.json，GUI 引擎选择器数据源）
-import { syncEnginesFile } from "./execution/engine/engine-discovery.ts";
+import { syncEnginesFile } from "@zhushanwen/subagent-core/execution/engine/engine-discovery.ts";
 // [U7] 引擎模型段注入（defaultEngine 非 pi 时 system prompt 补 <available_<engine>_models>）
-import { buildEngineModelsPromptAppend } from "./execution/engine/model-prompt.ts";
+// [engine-awareness U3] 补恒在状态段 <current_subagent_engine>（D6，pi 引擎也声明）
+import { buildEngineModelsPromptAppend, buildSubagentEngineSection } from "@zhushanwen/subagent-core/execution/engine/model-prompt.ts";
 // [P1 引擎接线] 组合根登记 'pi' 引擎进 registry（引擎获取统一经 getEngine，缺省 id 'pi'）
-import { registerPiEngine } from "./execution/engine/engines/pi/registration.ts";
+import { registerPiEngine } from "@zhushanwen/subagent-core/execution/engine/engines/pi/registration.ts";
 // [P3 引擎接线] 组合根登记 'zcode' 引擎（spawn 单轮模式；engineDataDir 默认走
 // common/data-dir SSOT，见 engines/zcode/registration.ts）
-import { registerZcodeEngine } from "./execution/engine/engines/zcode/registration.ts";
-import { createUiRequestHandlerForMode } from "./execution/ui-request-handler-factory.ts";
+import { registerZcodeEngine } from "@zhushanwen/subagent-core/execution/engine/engines/zcode/registration.ts";
+import { createUiRequestHandlerForMode } from "@zhushanwen/subagent-core/execution/ui-request-handler-factory.ts";
 import {
   getModelConfigService,
   ModelConfigService,
   setModelConfigService,
-} from "./execution/model-config-service.ts";
-import { bindNotifyLedgerHost, getBoundNotifyLedger, type NotifyLedgerHost } from "./execution/notify-ledger.ts";
-import { IDENTITY_CUSTOM_TYPE, type SubagentIdentityData } from "./execution/session-reconstructor.ts";
-import type { ExecutionMode, SubagentRecord } from "./execution/types.ts";
-import { maybeCleanupExpiredSessionFiles } from "./execution/session-file-gc.ts";
+} from "@zhushanwen/subagent-core/execution/model-config-service.ts";
+import { bindNotifyLedgerHost, getBoundNotifyLedger, type NotifyLedgerHost } from "@zhushanwen/subagent-core/execution/notify-ledger.ts";
+import { IDENTITY_CUSTOM_TYPE, type SubagentIdentityData } from "@zhushanwen/subagent-core/execution/session-reconstructor.ts";
+import type { ExecutionMode, SubagentRecord } from "@zhushanwen/subagent-core/execution/types.ts";
+import { maybeCleanupExpiredSessionFiles } from "@zhushanwen/subagent-core/execution/session-file-gc.ts";
 import {
   getSubagentService,
   setSubagentService,
   SubagentService,
-} from "./execution/subagent-service.ts";
-import { killAllSpawnedChildren } from "./execution/session-runner.ts";
-import { SubprocessAgentRunner } from "./execution/subprocess-agent-runner.ts";
-import { WorktreeManager } from "./execution/worktree-manager.ts";
+} from "@zhushanwen/subagent-core/execution/subagent-service.ts";
+import { killAllSpawnedChildren } from "@zhushanwen/subagent-core/execution/session-runner.ts";
+import { SubprocessAgentRunner } from "@zhushanwen/subagent-core/execution/subprocess-agent-runner.ts";
+import { WorktreeManager } from "@zhushanwen/subagent-core/execution/worktree-manager.ts";
+// [engine-awareness U3] per-turn 引擎检测编排（D1/D1b/D2/D3/D5）
+import { normalizeEngineId, runEngineAwarenessTurn } from "./injectors/engine-awareness.ts";
 import { setupModelListInjector } from "./injectors/model-list-injector.ts";
 import { setupSubagentListInjector } from "./injectors/subagent-list-injector.ts";
 import { setupWorkflowListInjector } from "./injectors/workflow-list-injector.ts";
@@ -63,20 +73,20 @@ import { registerSubagentTool } from "./interface/subagent-tool.ts";
 import { registerSubagentsCommand } from "./interface/subagents.ts";
 import { registerWorkflowTool } from "./interface/tool-workflow.ts";
 import { registerWorkflowScriptTool } from "./interface/tool-workflow-script.ts";
-import { JsonlRunStore } from "./orchestration/jsonl-run-store.ts";
-import { clearSkillPathCache } from "./orchestration/skill-discovery.ts";
+import { JsonlRunStore } from "./jsonl-run-store.ts";
+import { clearSkillPathCache } from "@zhushanwen/subagent-core/orchestration/skill-discovery.ts";
 // ═══ orchestration/ 层（workflow engine + infra） ═══
-import type { LauncherDeps } from "./orchestration/launcher.ts";
-import { executeNestedWorkflow, runAndWait, type WorkflowRunResult } from "./orchestration/launcher.ts";
+import type { LauncherDeps } from "@zhushanwen/subagent-core/orchestration/launcher.ts";
+import { executeNestedWorkflow, runAndWait, type WorkflowRunResult } from "@zhushanwen/subagent-core/orchestration/launcher.ts";
 import {
   evictDoneRunsBeyondCap,
   MAX_RETAINED_DONE_RUNS,
   scheduleTimeBudget,
   terminateRunningRuns,
-} from "./orchestration/lifecycle.ts";
-import type { WorkflowRun } from "./orchestration/models/workflow-run.ts";
-import { WorkerHostImpl } from "./orchestration/worker-host.ts";
-import { WorkflowScriptRegistryImpl } from "./orchestration/workflow-script-registry-impl.ts";
+} from "@zhushanwen/subagent-core/orchestration/lifecycle.ts";
+import type { WorkflowRun } from "@zhushanwen/subagent-core/orchestration/models/workflow-run.ts";
+import { WorkerHostImpl } from "@zhushanwen/subagent-core/orchestration/worker-host.ts";
+import { WorkflowScriptRegistryImpl } from "@zhushanwen/subagent-core/orchestration/workflow-script-registry-impl.ts";
 
 // ── pi.__workflowRun 类型扩展（D-8 签名） ─────────────────
 
@@ -170,6 +180,14 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // 的 getLogger("subagents") 也能走 appendEntry。
   setPiHandle(pi);
 
+  // [u0-wire] core 宿主端口接线：本波端口尚无 core 消费方（消费切换在 u0-log /
+  // u0-data-discovery / u0-notify 波次），接线本身零行为变化。紧随 setPiHandle——
+  // core log 桥接走 pi-extension-logger，其 pi handle 先注入则配置完成即桥接链路
+  // 完整；且先于任何可能消费 core 端口的初始化逻辑（引擎登记等）。缺省态若被消费，
+  // dataRoot 抛 core_host_not_configured（§3.4），接线后不再可达。
+  configureCore(createPiHostServices());
+  configureNotifyDomain(createPiNotifyDomainPorts());
+
   // [P1 引擎接线] 组合根登记缺省引擎：进程级 SubagentService 单例（session_start 注入）
   // 经 registry 以 'pi' 暴露——引擎获取从此统一走 getEngine(DEFAULT_ENGINE_ID)，上层
   // 不再硬编码「spawn pi」。幂等（registerEngine 覆盖语义），工厂惰性解析服务单例。
@@ -267,6 +285,10 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
        *  workflow 域启动时 fail-fast，避免后续 store.save 再次失败导致 run 状态不落地。
        *  subagent 域不依赖 store，不受此标志影响。 */
       storeHealthy: boolean;
+      /** [engine-awareness D1b] 上一次已知默认引擎（session_start 初始化，per-turn 检测
+       *  diff 基准）。undefined = 初始化时 config 读失败——首 turn 检测遇 undefined
+       *  静默基线化，不算变更、不发通知（防首 turn 伪通知）。 */
+      lastEngine?: string;
     }
   >();
 
@@ -612,6 +634,13 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       ctxModel: ctx.model ?? undefined,
     });
 
+    // [engine-awareness D1b] lastEngine 初始化：构造性同源——单次 reloadGlobalConfig
+    // 读取同时刷新 Service 路由缓存与 lastEngine 基准，消灭 initModel 与本处两次独立
+    // 读取间的分叉窗口（两读值不一致时检测走 unchanged 分支不 reload，状态段/路由
+    // 永停旧值且永不通知）。ok/absent → 归一后的当前引擎；failed → undefined（首 turn
+    // 检测静默基线化兜底，此时缓存亦保持不动）。/resume、/fork 同样走 session_start
+    // （SR-3），基线天然覆盖。
+    const engineRead = modelService.reloadGlobalConfig();
     sessionState.set(sessionId, {
       store,
       runs,
@@ -619,6 +648,8 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       runner,
       ctx,
       storeHealthy,
+      lastEngine:
+        engineRead.status === "failed" ? undefined : normalizeEngineId(engineRead.config.defaultEngine),
     });
   });
 
@@ -642,15 +673,41 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   });
 
   // ════════════════════════════════════════════════════════════
-  //  [U7] before_agent_start：引擎模型段注入（defaultEngine 非 pi 且引擎实现
-  //  listModels 时追加 <available_<engine>_models>——每 turn 重判 config，改配置
-  //  后下一 turn 即生效；fail-safe 任何异常不注入不阻塞 agent loop）
+  //  [U7 + engine-awareness U3] before_agent_start：引擎感知注入（链尾注册，D7——
+  //  段内容变化只断 system prompt 尾部 cache 前缀）。
+  //  ① per-turn 检测编排（§2.3 数据流）：三态 poll config → lastEngine diff →
+  //     变更时读取结果先行提交缓存（D2，applyGlobalConfig 纯赋值，本 turn 路由生效）
+  //     → sendMessage 通知
+  //     （D3，不设 triggerTurn——P1 探针已证此形态消息进入本 turn LLM 上下文，
+  //     证据：真机 pi rpc payload dump + 0.84.4 dist sendMessage→_appendCustomMessage
+  //     →agent.state.messages.push→createContextSnapshot 调用链）→ 更新 lastEngine。
+  //  ② 恒在状态段 <current_subagent_engine>（D6）+ 引擎清单段 <available_<engine>_models>。
+  //     apply 后 getGlobalConfig() 即新值——通知、状态段、路由三处同 turn 对齐（G2）。
+  //  段序：状态段在前（文案声明 "listed ... below"），清单段在后；provider models 段
+  //  由更早注册的 handler 注入、位于上方。fail-safe 任何异常不注入不阻塞 agent loop。
   // ════════════════════════════════════════════════════════════
-  pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent, ctx: ExtensionContext) => {
     try {
       const service = getModelConfigService();
-      const append = service === null ? "" : buildEngineModelsPromptAppend(service.getGlobalConfig().defaultEngine);
-      if (append === "" || typeof event.systemPrompt !== "string") return undefined;
+      if (service === null || typeof event.systemPrompt !== "string") return undefined;
+      const sid = ctx.sessionManager.getSessionId();
+      runEngineAwarenessTurn({
+        readConfig: () => readGlobalConfig(getAgentDir()),
+        applyRead: (read) => service.applyGlobalConfig(read),
+        sendMessage: (message) => {
+          // D3：不设 triggerTurn——切换是用户主动行为，无需唤醒 AI 立即行动
+          pi.sendMessage(message, {});
+        },
+        getLastEngine: () => sessionState.get(sid)?.lastEngine,
+        setLastEngine: (engine) => {
+          const state = sessionState.get(sid);
+          if (state) state.lastEngine = engine;
+        },
+      });
+      const defaultEngine = service.getGlobalConfig().defaultEngine;
+      const append = [buildSubagentEngineSection(defaultEngine), buildEngineModelsPromptAppend(defaultEngine)]
+        .filter((part) => part !== "")
+        .join("\n\n");
       return { systemPrompt: `${event.systemPrompt}\n\n${append}` };
     } catch {
       return undefined;
@@ -953,4 +1010,4 @@ export {
   getOrCreateChannelRegistry,
   type UiChannelRegistry,
   type ChannelHandler,
-} from "./execution/channel-registry-access.ts";
+} from "@zhushanwen/subagent-core/execution/channel-registry-access.ts";