feat(FN-2709): migrate Hermes runtime plugin to pi-ai streaming client

- Replace Hermes pi module integration with pi-ai session streaming and updated runtime adapter contracts
- Remove legacy engine guard scaffolding and add hermes-stream-client coverage for streaming behavior
- Rewrite plugin and engine e2e tests to align with the new runtime flow and regenerate dist artifacts
- Update Hermes runtime README and package metadata to document pi-ai execution expectations

plugins/fusion-plugin-hermes-runtime/src/__tests__/engine-guard-stub.ts

@@ -1,25 +0,0 @@
-/**
- * Resolution stub for @fusion/engine in plugin test mode.
- *
- * Vitest resolves mocked module IDs before applying vi.mock factories. The
- * real @fusion/engine workspace package points to dist outputs that are not
- * built for plugin-local test runs, so we alias to this stub in vitest config.
- *
- * Any direct import of @fusion/engine in plugin tests should still fail fast.
- */
-const guardError = () =>
-  new Error(
-    "Guard: @fusion/engine was imported without an explicit mock. Runtime plugin tests must mock '../pi-module.js' to prevent loading the real engine.",
-  );
-
-export const createFnAgent = () => {
-  throw guardError();
-};
-
-export const promptWithFallback = async () => {
-  throw guardError();
-};
-
-export const describeModel = () => {
-  throw guardError();
-};

plugins/fusion-plugin-hermes-runtime/src/__tests__/engine-guard.test.ts

@@ -1,33 +0,0 @@
-/**
- * Verifies the engine guard mock is active.
- *
- * This test ensures that the setup-engine-guard.ts setup file is correctly
- * loaded and that any test importing @fusion/engine without mocking pi-module
- * would fail fast with a descriptive error.
- */
-import { describe, it, expect } from "vitest";
-
-describe("engine import guard", () => {
-  it("should have @fusion/engine mock installed (prevents real engine load)", () => {
-    // The guard is verified indirectly: if this test file runs at all,
-    // the setup-engine-guard.ts loaded successfully. The guard throws only
-    // when a test file actually imports @fusion/engine without mocking
-    // pi-module.js — and since we don't do that here, we confirm the setup
-    // is wired without triggering the error.
-    expect(true).toBe(true);
-  });
-
-  it("should mock pi-module seam (not load real engine)", async () => {
-    // Dynamically import pi-module to verify it is mocked, not the real one.
-    // Since this test file has no vi.mock("../pi-module.js"), it relies on
-    // no code path reaching pi-module at all. The guard in setup-engine-guard.ts
-    // would throw if the real @fusion/engine were loaded.
-    //
-    // We do NOT import pi-module here because that would trigger the guard.
-    // Instead we verify the setup file exists and is wired via vitest config.
-    const { existsSync } = await import("node:fs");
-    const { join } = await import("node:path");
-    const guardPath = join(import.meta.dirname, "setup-engine-guard.ts");
-    expect(existsSync(guardPath)).toBe(true);
-  });
-});

plugins/fusion-plugin-hermes-runtime/src/__tests__/hermes-stream-client.test.ts

@@ -0,0 +1,221 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createStreamSession,
+  describeStreamModel,
+  resolveModelConfig,
+  streamPrompt,
+} from "../pi-module.js";
+
+const { mockGetModel, mockStreamSimple } = vi.hoisted(() => ({
+  mockGetModel: vi.fn(),
+  mockStreamSimple: vi.fn(),
+}));
+
+vi.mock("@mariozechner/pi-ai", () => ({
+  getModel: mockGetModel,
+  streamSimple: mockStreamSimple,
+}));
+
+function createFakeStream(events: unknown[], finalMessage: unknown) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const event of events) {
+        yield event;
+      }
+    },
+    result: vi.fn().mockResolvedValue(finalMessage),
+  };
+}
+
+describe("hermes pi-ai stream client", () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env = { ...originalEnv };
+    delete process.env.HERMES_PROVIDER;
+    delete process.env.HERMES_MODEL_ID;
+    delete process.env.HERMES_API_KEY;
+    delete process.env.HERMES_THINKING_LEVEL;
+
+    mockGetModel.mockReturnValue({ provider: "anthropic", id: "claude-sonnet-4-5" });
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it("resolveModelConfig prefers settings over env and env over defaults", () => {
+    process.env.HERMES_PROVIDER = "openai";
+    process.env.HERMES_MODEL_ID = "gpt-5";
+    process.env.HERMES_API_KEY = "env-key";
+    process.env.HERMES_THINKING_LEVEL = "medium";
+
+    expect(resolveModelConfig()).toEqual({
+      provider: "openai",
+      modelId: "gpt-5",
+      apiKey: "env-key",
+      thinkingLevel: "medium",
+    });
+
+    expect(
+      resolveModelConfig({ provider: "anthropic", modelId: "claude", apiKey: "plugin-key", thinkingLevel: "high" }),
+    ).toEqual({
+      provider: "anthropic",
+      modelId: "claude",
+      apiKey: "plugin-key",
+      thinkingLevel: "high",
+    });
+
+    delete process.env.HERMES_PROVIDER;
+    delete process.env.HERMES_MODEL_ID;
+    delete process.env.HERMES_API_KEY;
+    delete process.env.HERMES_THINKING_LEVEL;
+
+    expect(resolveModelConfig()).toEqual({
+      provider: "anthropic",
+      modelId: "claude-sonnet-4-5",
+      apiKey: undefined,
+      thinkingLevel: undefined,
+    });
+  });
+
+  it("createStreamSession resolves model and initializes session state", () => {
+    const onText = vi.fn();
+    const onThinking = vi.fn();
+    const onToolStart = vi.fn();
+    const onToolEnd = vi.fn();
+
+    const session = createStreamSession({
+      provider: "anthropic",
+      modelId: "claude-sonnet-4-5",
+      apiKey: "key",
+      thinkingLevel: "high",
+      systemPrompt: "You are Hermes",
+      callbacks: { onText, onThinking, onToolStart, onToolEnd },
+    });
+
+    expect(mockGetModel).toHaveBeenCalledWith("anthropic", "claude-sonnet-4-5");
+    expect(session.model).toEqual({ provider: "anthropic", id: "claude-sonnet-4-5" });
+    expect(session.systemPrompt).toBe("You are Hermes");
+    expect(session.messages).toEqual([]);
+    expect(session.apiKey).toBe("key");
+    expect(session.thinkingLevel).toBe("high");
+    expect(session.callbacks).toEqual({ onText, onThinking, onToolStart, onToolEnd });
+    expect(session.lastModelDescription).toBe("anthropic/claude-sonnet-4-5");
+    expect(session.sessionId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+
+    const second = createStreamSession({
+      provider: "anthropic",
+      modelId: "claude-sonnet-4-5",
+      systemPrompt: "You are Hermes",
+    });
+    expect(second.sessionId).not.toBe(session.sessionId);
+  });
+
+  it("streamPrompt streams deltas, handles tool calls, stores usage, and appends assistant text only", async () => {
+    const onText = vi.fn();
+    const onThinking = vi.fn();
+    const onToolStart = vi.fn();
+    const onToolEnd = vi.fn();
+
+    const session = createStreamSession({
+      provider: "anthropic",
+      modelId: "claude-sonnet-4-5",
+      apiKey: "api-key",
+      thinkingLevel: "medium",
+      systemPrompt: "system",
+      callbacks: { onText, onThinking, onToolStart, onToolEnd },
+    });
+    session.messages.push({ role: "user", content: "hello" });
+
+    const doneMessage = {
+      content: [
+        { type: "text", text: "Hello" },
+        { type: "thinking", thinking: "internal" },
+        { type: "toolCall", id: "t1", name: "bash", arguments: { cmd: "ls" } },
+        { type: "text", text: " world" },
+      ],
+      usage: { input: 1, output: 2 },
+    };
+
+    mockStreamSimple.mockReturnValue(
+      createFakeStream(
+        [
+          { type: "text_delta", delta: "Hello" },
+          { type: "thinking_delta", delta: "thinking" },
+          { type: "toolcall_end", toolCall: { name: "bash", arguments: { cmd: "ls" } } },
+          { type: "text_delta", delta: " world" },
+          { type: "done", message: doneMessage },
+        ],
+        doneMessage,
+      ),
+    );
+
+    await streamPrompt(session, { role: "user", content: "ignored" } as any);
+
+    expect(mockStreamSimple).toHaveBeenCalledWith(
+      session.model,
+      {
+        systemPrompt: "system",
+        messages: [{ role: "user", content: "hello" }],
+      },
+      {
+        sessionId: session.sessionId,
+        apiKey: "api-key",
+        reasoning: "medium",
+      },
+    );
+
+    expect(onText).toHaveBeenNthCalledWith(1, "Hello");
+    expect(onText).toHaveBeenNthCalledWith(2, " world");
+    expect(onThinking).toHaveBeenCalledWith("thinking");
+    expect(onToolStart).toHaveBeenCalledWith("bash", { cmd: "ls" });
+    expect(onToolEnd).toHaveBeenCalledWith("bash", false, { cmd: "ls" });
+    expect(session.usage).toEqual({ input: 1, output: 2 });
+    expect(session.messages).toEqual([
+      { role: "user", content: "hello" },
+      { role: "assistant", content: "Hello world" },
+    ]);
+    expect(describeStreamModel(session)).toBe("anthropic/claude-sonnet-4-5");
+  });
+
+  it("streamPrompt omits optional apiKey/reasoning when unset", async () => {
+    const session = createStreamSession({
+      provider: "anthropic",
+      modelId: "claude-sonnet-4-5",
+      systemPrompt: "system",
+    });
+    session.messages.push({ role: "user", content: "hello" });
+
+    const doneMessage = { content: [{ type: "text", text: "ok" }], usage: { input: 1, output: 1 } };
+    mockStreamSimple.mockReturnValue(createFakeStream([{ type: "done", message: doneMessage }], doneMessage));
+
+    await streamPrompt(session, { role: "user", content: "ignored" } as any);
+
+    expect(mockStreamSimple).toHaveBeenCalledWith(
+      session.model,
+      { systemPrompt: "system", messages: [{ role: "user", content: "hello" }] },
+      { sessionId: session.sessionId },
+    );
+  });
+
+  it("streamPrompt throws on error event", async () => {
+    const session = createStreamSession({
+      provider: "anthropic",
+      modelId: "claude-sonnet-4-5",
+      systemPrompt: "system",
+    });
+
+    const errorMessage = {
+      type: "error",
+      error: {
+        errorMessage: "boom",
+      },
+    };
+    mockStreamSimple.mockReturnValue(createFakeStream([errorMessage], { content: [], usage: {} }));
+
+    await expect(streamPrompt(session, { role: "user", content: "ignored" } as any)).rejects.toThrow("boom");
+    expect(session.messages).toEqual([]);
+  });
+});

plugins/fusion-plugin-hermes-runtime/src/__tests__/index.test.ts

@@ -1,41 +1,25 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 
-const { mockCreateFnAgent, mockPromptWithFallback, mockDescribeModel } = vi.hoisted(() => ({
-  mockCreateFnAgent: vi.fn(),
-  mockPromptWithFallback: vi.fn(),
-  mockDescribeModel: vi.fn().mockReturnValue("unknown model"),
+const { mockResolveModelConfig } = vi.hoisted(() => ({
+  mockResolveModelConfig: vi.fn().mockReturnValue({
+    provider: "anthropic",
+    modelId: "claude-sonnet-4-5",
+    apiKey: undefined,
+    thinkingLevel: undefined,
+  }),
 }));
 
 vi.mock("../pi-module.js", () => ({
-  createFnAgent: mockCreateFnAgent,
-  promptWithFallback: mockPromptWithFallback,
-  describeModel: mockDescribeModel,
+  resolveModelConfig: mockResolveModelConfig,
 }));
 
 import plugin, { hermesRuntimeMetadata, hermesRuntimeFactory, HERMES_RUNTIME_ID } from "../index.js";
 import { HermesRuntimeAdapter } from "../runtime-adapter.js";
 
-interface MockLogger {
-  info: ReturnType<typeof vi.fn>;
-  warn: ReturnType<typeof vi.fn>;
-  error: ReturnType<typeof vi.fn>;
-  debug: ReturnType<typeof vi.fn>;
-}
-
-interface MockContext {
-  pluginId: string;
-  settings: Record<string, unknown>;
-  logger: MockLogger;
-  emitEvent: ReturnType<typeof vi.fn>;
-  taskStore: {
-    getTask: ReturnType<typeof vi.fn>;
-  };
-}
-
-function createMockContext(overrides: Partial<MockContext> = {}): MockContext {
+function createMockContext(settings: Record<string, unknown> = {}) {
   return {
     pluginId: "fusion-plugin-hermes-runtime",
-    settings: {},
+    settings,
     logger: {
       info: vi.fn(),
       warn: vi.fn(),
@@ -46,7 +30,6 @@ function createMockContext(overrides: Partial<MockContext> = {}): MockContext {
     taskStore: {
       getTask: vi.fn(),
     },
-    ...overrides,
   };
 }
 
@@ -55,74 +38,61 @@ describe("hermes-runtime plugin", () => {
     vi.clearAllMocks();
   });
 
-  afterEach(() => {
-    vi.restoreAllMocks();
+  it("has expected manifest identity", () => {
+    expect(plugin.manifest.id).toBe("fusion-plugin-hermes-runtime");
+    expect(plugin.manifest.name).toBe("Hermes Runtime Plugin");
+    expect(plugin.manifest.version).toBe("0.1.0");
+    expect(plugin.state).toBe("installed");
   });
 
-  describe("plugin manifest identity", () => {
-    it("should have correct manifest fields", () => {
-      expect(plugin.manifest.id).toBe("fusion-plugin-hermes-runtime");
-      expect(plugin.manifest.name).toBe("Hermes Runtime Plugin");
-      expect(plugin.manifest.version).toBe("0.1.0");
-      expect(plugin.manifest.description).toContain("Hermes");
-      expect(plugin.manifest.author).toBe("Fusion Team");
-      expect(plugin.state).toBe("installed");
+  it("registers runtime metadata and exports matching constants", () => {
+    expect(HERMES_RUNTIME_ID).toBe("hermes");
+    expect(plugin.runtime?.metadata.runtimeId).toBe("hermes");
+    expect(plugin.runtime?.metadata.name).toBe("Hermes Runtime");
+    expect(plugin.runtime?.metadata.description).toContain("pi-ai direct streaming");
+    expect(plugin.manifest.runtime).toEqual(hermesRuntimeMetadata);
+  });
+
+  it("onLoad resolves model config and logs selected provider/model without api key", async () => {
+    const ctx = createMockContext({ provider: "openai", modelId: "gpt-5", apiKey: "secret" });
+    mockResolveModelConfig.mockReturnValue({
+      provider: "openai",
+      modelId: "gpt-5",
+      apiKey: "secret",
+      thinkingLevel: "medium",
+    });
+
+    await plugin.hooks.onLoad?.(ctx as any);
+
+    expect(mockResolveModelConfig).toHaveBeenCalledWith(ctx.settings);
+    expect(ctx.logger.info).toHaveBeenCalledWith("Hermes Runtime Plugin loaded — using openai/gpt-5");
+    expect(ctx.logger.info.mock.calls[0][0]).not.toContain("secret");
+    expect(ctx.emitEvent).toHaveBeenCalledWith("hermes-runtime:loaded", {
+      runtimeId: "hermes",
+      version: "0.1.0",
     });
   });
 
-  describe("runtime registration", () => {
-    it("should register hermes runtime metadata", () => {
-      expect(plugin.runtime).toBeDefined();
-      expect(plugin.runtime?.metadata.runtimeId).toBe(HERMES_RUNTIME_ID);
-      expect(plugin.runtime?.metadata.name).toBe("Hermes Runtime");
-      expect(plugin.runtime?.metadata.description).toContain("Hermes-backed AI session");
-      expect(plugin.runtime?.metadata.version).toBe("0.1.0");
+  it("runtime factory resolves settings and returns HermesRuntimeAdapter", async () => {
+    const ctx = createMockContext({ provider: "openai", modelId: "gpt-5" });
+    mockResolveModelConfig.mockReturnValue({
+      provider: "openai",
+      modelId: "gpt-5",
+      apiKey: "api-key",
+      thinkingLevel: "high",
     });
 
-    it("should have consistent runtime metadata between export and manifest", () => {
-      expect(plugin.manifest.runtime).toEqual(hermesRuntimeMetadata);
-      expect(plugin.runtime?.metadata).toEqual(hermesRuntimeMetadata);
-    });
-  });
+    const runtime = (await hermesRuntimeFactory(ctx as any)) as HermesRuntimeAdapter;
 
-  describe("hooks", () => {
-    it("onLoad should log startup message and emit loaded event", async () => {
-      const ctx = createMockContext();
-      await plugin.hooks.onLoad?.(ctx as any);
-
-      expect(ctx.logger.info).toHaveBeenCalledWith("Hermes Runtime Plugin loaded");
-      expect(ctx.emitEvent).toHaveBeenCalledWith("hermes-runtime:loaded", {
-        runtimeId: HERMES_RUNTIME_ID,
-        version: "0.1.0",
-      });
-    });
-
-    it("onUnload should not throw", () => {
-      expect(() => plugin.hooks.onUnload?.()).not.toThrow();
-    });
-  });
-
-  describe("runtime factory behavior", () => {
-    it("should export runtime constants", () => {
-      expect(HERMES_RUNTIME_ID).toBe("hermes");
-      expect(hermesRuntimeMetadata.runtimeId).toBe("hermes");
-      expect(typeof hermesRuntimeFactory).toBe("function");
-    });
-
-    it("runtime factory should return executable runtime adapter", async () => {
-      const runtime = (await hermesRuntimeFactory(createMockContext() as any)) as HermesRuntimeAdapter;
-
-      expect(runtime).toBeInstanceOf(HermesRuntimeAdapter);
-      expect(runtime.id).toBe("hermes");
-      expect(runtime.name).toBe("Hermes Runtime");
-      expect(runtime).not.toHaveProperty("status");
-      expect(runtime).not.toHaveProperty("execute");
-    });
-
-    it("factory creation should not throw", async () => {
-      await expect(hermesRuntimeFactory(createMockContext() as any)).resolves.toBeInstanceOf(
-        HermesRuntimeAdapter,
-      );
+    expect(mockResolveModelConfig).toHaveBeenCalledWith(ctx.settings);
+    expect(runtime).toBeInstanceOf(HermesRuntimeAdapter);
+    expect(runtime.id).toBe("hermes");
+    expect(runtime.name).toBe("Hermes Runtime");
+    expect((runtime as any).config).toEqual({
+      provider: "openai",
+      modelId: "gpt-5",
+      apiKey: "api-key",
+      thinkingLevel: "high",
     });
   });
 });

plugins/fusion-plugin-hermes-runtime/src/__tests__/integration.test.ts

@@ -1,21 +1,30 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { FusionPlugin } from "@fusion/plugin-sdk";
 import plugin from "../index.js";
 import type { AgentRuntime } from "../types.js";
 
-const { mockCreateFnAgent, mockPromptWithFallback, mockDescribeModel } = vi.hoisted(() => ({
-  mockCreateFnAgent: vi.fn().mockResolvedValue({
-    session: { id: "hermes-session" },
-    sessionFile: "/tmp/hermes.session.json",
+const {
+  mockResolveModelConfig,
+  mockCreateStreamSession,
+  mockStreamPrompt,
+  mockDescribeStreamModel,
+} = vi.hoisted(() => ({
+  mockResolveModelConfig: vi.fn().mockReturnValue({
+    provider: "anthropic",
+    modelId: "claude-sonnet-4-5",
+    apiKey: undefined,
+    thinkingLevel: undefined,
   }),
-  mockPromptWithFallback: vi.fn().mockResolvedValue(undefined),
-  mockDescribeModel: vi.fn().mockReturnValue("anthropic/claude-sonnet-4-5"),
+  mockCreateStreamSession: vi.fn().mockReturnValue({ messages: [], dispose: vi.fn() }),
+  mockStreamPrompt: vi.fn().mockResolvedValue(undefined),
+  mockDescribeStreamModel: vi.fn().mockReturnValue("anthropic/claude-sonnet-4-5"),
 }));
 
 vi.mock("../pi-module.js", () => ({
-  createFnAgent: mockCreateFnAgent,
-  promptWithFallback: mockPromptWithFallback,
-  describeModel: mockDescribeModel,
+  resolveModelConfig: mockResolveModelConfig,
+  createStreamSession: mockCreateStreamSession,
+  streamPrompt: mockStreamPrompt,
+  describeStreamModel: mockDescribeStreamModel,
 }));
 
 function isAgentRuntime(value: unknown): value is AgentRuntime {
@@ -33,7 +42,7 @@ function isAgentRuntime(value: unknown): value is AgentRuntime {
 function createMockContext() {
   return {
     pluginId: "fusion-plugin-hermes-runtime",
-    settings: {},
+    settings: { provider: "anthropic", modelId: "claude-sonnet-4-5" },
     logger: {
       info: vi.fn(),
       warn: vi.fn(),
@@ -50,10 +59,6 @@ describe("Hermes runtime plugin integration", () => {
     vi.clearAllMocks();
   });
 
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
   it("exports a valid Fusion plugin manifest", () => {
     const fusionPlugin = plugin as FusionPlugin;
 
@@ -61,17 +66,20 @@ describe("Hermes runtime plugin integration", () => {
     expect(fusionPlugin.manifest.id).toBe("fusion-plugin-hermes-runtime");
   });
 
-  it("registers Hermes runtime metadata", () => {
-    expect(plugin.runtime).toBeDefined();
-    expect(plugin.runtime?.metadata.runtimeId).toBe("hermes");
-  });
-
   it("runtime factory returns an AgentRuntime-compatible Hermes adapter", async () => {
     const runtime = (await plugin.runtime!.factory(createMockContext() as any)) as AgentRuntime;
 
     expect(runtime.id).toBe("hermes");
     expect(runtime.name).toBe("Hermes Runtime");
     expect(isAgentRuntime(runtime)).toBe(true);
+
+    const created = await runtime.createSession({ cwd: "/tmp", systemPrompt: "helpful" });
+    expect(created.sessionFile).toBeUndefined();
+
+    await runtime.promptWithFallback(created.session, "Hello integration");
+    expect(mockStreamPrompt).toHaveBeenCalled();
+
+    expect(runtime.describeModel(created.session)).toBe("anthropic/claude-sonnet-4-5");
   });
 
   it("onLoad emits hermes-runtime:loaded with runtime metadata", async () => {
@@ -79,6 +87,7 @@ describe("Hermes runtime plugin integration", () => {
 
     await plugin.hooks.onLoad?.(ctx as any);
 
+    expect(mockResolveModelConfig).toHaveBeenCalledWith(ctx.settings);
     expect(ctx.emitEvent).toHaveBeenCalledWith("hermes-runtime:loaded", {
       runtimeId: "hermes",
       version: "0.1.0",

plugins/fusion-plugin-hermes-runtime/src/__tests__/runtime-adapter.test.ts

@@ -1,97 +1,109 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, vi, beforeEach } from "vitest";
 import { HermesRuntimeAdapter } from "../runtime-adapter.js";
 
-const { mockCreateFnAgent, mockPromptWithFallback, mockDescribeModel } = vi.hoisted(() => ({
-  mockCreateFnAgent: vi.fn(),
-  mockPromptWithFallback: vi.fn(),
-  mockDescribeModel: vi.fn(),
+const {
+  mockCreateStreamSession,
+  mockStreamPrompt,
+  mockDescribeStreamModel,
+} = vi.hoisted(() => ({
+  mockCreateStreamSession: vi.fn(),
+  mockStreamPrompt: vi.fn(),
+  mockDescribeStreamModel: vi.fn(),
 }));
 
 vi.mock("../pi-module.js", () => ({
-  createFnAgent: mockCreateFnAgent,
-  promptWithFallback: mockPromptWithFallback,
-  describeModel: mockDescribeModel,
+  createStreamSession: mockCreateStreamSession,
+  streamPrompt: mockStreamPrompt,
+  describeStreamModel: mockDescribeStreamModel,
 }));
 
 describe("HermesRuntimeAdapter", () => {
-  let adapter: HermesRuntimeAdapter;
-
   beforeEach(() => {
     vi.clearAllMocks();
-    mockDescribeModel.mockReturnValue("mock/anthropic-claude");
-    adapter = new HermesRuntimeAdapter();
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
   });
 
   it("has stable runtime identity", () => {
+    const adapter = new HermesRuntimeAdapter({ provider: "anthropic", modelId: "claude-sonnet-4-5" });
     expect(adapter.id).toBe("hermes");
     expect(adapter.name).toBe("Hermes Runtime");
   });
 
-  it("delegates createSession to createFnAgent with mapped options", async () => {
-    const mockSession = { dispose: vi.fn() };
-    mockCreateFnAgent.mockResolvedValue({ session: mockSession, sessionFile: "/tmp/session.json" });
+  it("createSession passes model config/systemPrompt/callbacks and returns undefined sessionFile", async () => {
+    const adapter = new HermesRuntimeAdapter({
+      provider: "openai",
+      modelId: "gpt-5",
+      apiKey: "secret",
+      thinkingLevel: "high",
+    });
+    const session = { messages: [], dispose: vi.fn() };
+    mockCreateStreamSession.mockReturnValue(session);
+
+    const onText = vi.fn();
+    const onThinking = vi.fn();
+    const onToolStart = vi.fn();
+    const onToolEnd = vi.fn();
 
     const result = await adapter.createSession({
-      cwd: "/project",
-      systemPrompt: "You are helpful",
-      defaultProvider: "anthropic",
-      defaultModelId: "claude-sonnet-4-5",
-      fallbackProvider: "openai",
-      fallbackModelId: "gpt-4o",
+      cwd: "/tmp/project",
+      systemPrompt: "You are Hermes",
+      tools: "coding",
+      customTools: [{ name: "ignored" }],
+      sessionManager: { foo: "bar" },
+      skillSelection: { all: true },
       skills: ["bash"],
+      onText,
+      onThinking,
+      onToolStart,
+      onToolEnd,
     });
 
-    expect(mockCreateFnAgent).toHaveBeenCalledWith({
-      cwd: "/project",
-      systemPrompt: "You are helpful",
-      tools: undefined,
-      customTools: undefined,
-      onText: undefined,
-      onThinking: undefined,
-      onToolStart: undefined,
-      onToolEnd: undefined,
-      defaultProvider: "anthropic",
-      defaultModelId: "claude-sonnet-4-5",
-      fallbackProvider: "openai",
-      fallbackModelId: "gpt-4o",
-      defaultThinkingLevel: undefined,
-      sessionManager: undefined,
-      skillSelection: undefined,
-      skills: ["bash"],
+    expect(mockCreateStreamSession).toHaveBeenCalledWith({
+      provider: "openai",
+      modelId: "gpt-5",
+      apiKey: "secret",
+      thinkingLevel: "high",
+      systemPrompt: "You are Hermes",
+      callbacks: {
+        onText,
+        onThinking,
+        onToolStart,
+        onToolEnd,
+      },
     });
-    expect(result.session).toBe(mockSession);
-    expect(result.sessionFile).toBe("/tmp/session.json");
+    expect(result).toEqual({ session, sessionFile: undefined });
+    expect(JSON.stringify(mockCreateStreamSession.mock.calls[0][0])).not.toContain("/tmp/project");
+    expect(JSON.stringify(mockCreateStreamSession.mock.calls[0][0])).not.toContain("coding");
   });
 
-  it("delegates promptWithFallback to pi seam", async () => {
-    const session = { id: "s-1" };
-    mockPromptWithFallback.mockResolvedValue(undefined);
+  it("promptWithFallback appends user message then delegates to streamPrompt", async () => {
+    const adapter = new HermesRuntimeAdapter({ provider: "anthropic", modelId: "claude-sonnet-4-5" });
+    const session = { messages: [], dispose: vi.fn() } as any;
 
-    await adapter.promptWithFallback(session as any, "Hello", { images: [] });
+    await adapter.promptWithFallback(session, "Hello from Hermes");
 
-    expect(mockPromptWithFallback).toHaveBeenCalledWith(session, "Hello", { images: [] });
+    expect(session.messages).toEqual([{ role: "user", content: "Hello from Hermes" }]);
+    expect(mockStreamPrompt).toHaveBeenCalledWith(session, {
+      role: "user",
+      content: "Hello from Hermes",
+    });
   });
 
-  it("delegates describeModel to pi seam", () => {
-    const session = { id: "s-2" };
-    mockDescribeModel.mockReturnValue("anthropic/claude-sonnet-4-5");
+  it("describeModel delegates to describeStreamModel", () => {
+    const adapter = new HermesRuntimeAdapter({ provider: "anthropic", modelId: "claude-sonnet-4-5" });
+    const session = { messages: [], dispose: vi.fn() } as any;
+    mockDescribeStreamModel.mockReturnValue("anthropic/claude-sonnet-4-5");
 
-    const result = adapter.describeModel(session as any);
-
-    expect(mockDescribeModel).toHaveBeenCalledWith(session);
-    expect(result).toBe("anthropic/claude-sonnet-4-5");
+    expect(adapter.describeModel(session)).toBe("anthropic/claude-sonnet-4-5");
+    expect(mockDescribeStreamModel).toHaveBeenCalledWith(session);
   });
 
-  it("dispose calls session.dispose when present and no-ops otherwise", async () => {
-    const disposeMock = vi.fn().mockResolvedValue(undefined);
+  it("dispose is a no-op when missing and calls dispose when present", async () => {
+    const adapter = new HermesRuntimeAdapter({ provider: "anthropic", modelId: "claude-sonnet-4-5" });
+    const dispose = vi.fn();
 
-    await adapter.dispose({ dispose: disposeMock });
-    await expect(adapter.dispose({ id: "no-dispose" } as any)).resolves.toBeUndefined();
+    await expect(adapter.dispose({ messages: [], dispose } as any)).resolves.toBeUndefined();
+    await expect(adapter.dispose({ messages: [] } as any)).resolves.toBeUndefined();
 
-    expect(disposeMock).toHaveBeenCalledTimes(1);
+    expect(dispose).toHaveBeenCalledTimes(1);
   });
 });

plugins/fusion-plugin-hermes-runtime/src/__tests__/setup-engine-guard.ts

@@ -1,26 +0,0 @@
-/**
- * Engine import guard for plugin tests.
- *
- * Runtime plugin tests mock the seam module (../pi-module.js) to avoid loading
- * the real @fusion/engine, which pulls in @fusion/core and triggers homedir()-
- * based path resolution. This setup file installs a global vi.mock on
- * @fusion/engine that throws if the real module is ever loaded without an
- * explicit override.
- *
- * If you see the guard error in a test:
- *   1. Add `vi.mock("../pi-module.js", ...)` at the top of the failing test
- *   2. If you genuinely need to import @fusion/engine, you must also add HOME
- *      isolation setup (see setup-test-isolation.ts in packages/core) to this
- *      plugin's vitest config setupFiles before the guard.
- */
-import { vi } from "vitest";
-
-vi.mock("@fusion/engine", () => {
-  throw new Error(
-    "Guard: @fusion/engine was imported without an explicit mock. " +
-      "Runtime plugin tests must mock '../pi-module.js' to prevent loading " +
-      "the real engine. If you need the real engine, add HOME isolation " +
-      "setup (setup-test-isolation.ts) to vitest config setupFiles BEFORE " +
-      "this guard, and remove or override this mock.",
-  );
-});