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.",
-  );
-});

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

@@ -6,6 +6,7 @@
  */
 
 import { definePlugin } from "@fusion/plugin-sdk";
+import { resolveModelConfig } from "./pi-module.js";
 import { HermesRuntimeAdapter } from "./runtime-adapter.js";
 import type {
   FusionPlugin,
@@ -21,14 +22,21 @@ const HERMES_RUNTIME_VERSION = "0.1.0";
 const hermesRuntimeMetadata: PluginRuntimeManifestMetadata = {
   runtimeId: HERMES_RUNTIME_ID,
   name: "Hermes Runtime",
-  description: "Hermes-backed AI session using the user's configured pi provider and model",
+  description: "Hermes raw-model runtime using pi-ai direct streaming",
   version: HERMES_RUNTIME_VERSION,
 };
 
 // ── Hermes Runtime Factory ────────────────────────────────────────────────────
 
-const hermesRuntimeFactory: PluginRuntimeFactory = async () => {
-  return new HermesRuntimeAdapter();
+const hermesRuntimeFactory: PluginRuntimeFactory = async (ctx) => {
+  const config = resolveModelConfig(ctx.settings);
+
+  return new HermesRuntimeAdapter({
+    provider: config.provider,
+    modelId: config.modelId,
+    apiKey: config.apiKey,
+    thinkingLevel: config.thinkingLevel,
+  });
 };
 
 // ── Plugin Definition ─────────────────────────────────────────────────────────
@@ -46,7 +54,8 @@ const plugin: FusionPlugin = definePlugin({
   state: "installed",
   hooks: {
     onLoad: (ctx) => {
-      ctx.logger.info("Hermes Runtime Plugin loaded");
+      const config = resolveModelConfig(ctx.settings);
+      ctx.logger.info(`Hermes Runtime Plugin loaded — using ${config.provider}/${config.modelId}`);
       ctx.emitEvent("hermes-runtime:loaded", {
         runtimeId: HERMES_RUNTIME_ID,
         version: HERMES_RUNTIME_VERSION,

plugins/fusion-plugin-hermes-runtime/src/pi-module.ts

@@ -1,53 +1,134 @@
-/**
- * Pi Module Seam
- *
- * Provides a mockable import path for pi functions used by the HermesRuntimeAdapter.
- * Tests intercept this module via `vi.mock("../pi-module.js", ...)`. The runtime
- * implementations come from @fusion/engine; the local types provide a loose
- * surface so the adapter doesn't have to depend on @fusion/engine's full types.
- */
+import { randomUUID } from "node:crypto";
 import {
-  createFnAgent as _createFnAgent,
-  promptWithFallback as _promptWithFallback,
-  describeModel as _describeModel,
-} from "@fusion/engine";
+  getModel,
+  streamSimple,
+  type Api,
+  type AssistantMessageEvent,
+  type Context,
+  type Message,
+  type Model,
+  type SimpleStreamOptions,
+  type ThinkingLevel,
+} from "@mariozechner/pi-ai";
+import type {
+  HermesCallbacks,
+  HermesStreamSession,
+  ResolvedModelConfig,
+} from "./types.js";
 
-export interface PiAgentSession {
-  dispose?: () => Promise<void> | void;
+const DEFAULT_PROVIDER = "anthropic";
+const DEFAULT_MODEL_ID = "claude-sonnet-4-5";
+
+function resolveStringSetting(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }
 
-export interface PiAgentResult {
-  session: PiAgentSession;
-  sessionFile?: string;
+export function resolveModelConfig(settings?: Record<string, unknown>): ResolvedModelConfig {
+  const provider =
+    resolveStringSetting(settings?.provider) ?? resolveStringSetting(process.env.HERMES_PROVIDER) ?? DEFAULT_PROVIDER;
+  const modelId =
+    resolveStringSetting(settings?.modelId) ?? resolveStringSetting(process.env.HERMES_MODEL_ID) ?? DEFAULT_MODEL_ID;
+  const apiKey = resolveStringSetting(settings?.apiKey) ?? resolveStringSetting(process.env.HERMES_API_KEY);
+  const thinkingLevel =
+    resolveStringSetting(settings?.thinkingLevel) ?? resolveStringSetting(process.env.HERMES_THINKING_LEVEL) ?? undefined;
+
+  return { provider, modelId, apiKey, thinkingLevel };
 }
 
-export interface PiAgentOptions {
-  cwd: string;
+export function createStreamSession(options: {
+  provider: string;
+  modelId: string;
+  apiKey?: string;
+  thinkingLevel?: string;
   systemPrompt: string;
-  tools?: "coding" | "readonly";
-  customTools?: unknown;
-  onText?: (text: string) => void;
-  onThinking?: (text: string) => void;
-  onToolStart?: (toolName: string, args?: Record<string, unknown>) => void;
-  onToolEnd?: (toolName: string, isError: boolean, result?: unknown) => void;
-  defaultProvider?: string;
-  defaultModelId?: string;
-  fallbackProvider?: string;
-  fallbackModelId?: string;
-  defaultThinkingLevel?: string;
-  sessionManager?: unknown;
-  skillSelection?: unknown;
-  skills?: string[];
+  callbacks?: HermesCallbacks;
+}): HermesStreamSession {
+  const model = getModel(options.provider as never, options.modelId as never) as Model<Api>;
+
+  return {
+    model,
+    systemPrompt: options.systemPrompt,
+    messages: [],
+    apiKey: options.apiKey,
+    thinkingLevel: options.thinkingLevel,
+    sessionId: randomUUID(),
+    lastModelDescription: `${model.provider}/${model.id}`,
+    callbacks: options.callbacks ?? {},
+    usage: undefined,
+    dispose: () => undefined,
+  };
 }
 
-export const createFnAgent = _createFnAgent as unknown as (
-  options: PiAgentOptions,
-) => Promise<PiAgentResult>;
+export async function streamPrompt(session: HermesStreamSession, _userMessage: Message): Promise<void> {
+  const context: Context = {
+    systemPrompt: session.systemPrompt,
+    messages: [...(session.messages as Message[])],
+  };
 
-export const promptWithFallback = _promptWithFallback as unknown as (
-  session: PiAgentSession,
-  prompt: string,
-  options?: unknown,
-) => Promise<void>;
+  const options: SimpleStreamOptions = {
+    sessionId: session.sessionId,
+  };
 
-export const describeModel = _describeModel as unknown as (session: PiAgentSession) => string;
+  if (session.apiKey) {
+    options.apiKey = session.apiKey;
+  }
+
+  if (session.thinkingLevel) {
+    options.reasoning = session.thinkingLevel as ThinkingLevel;
+  }
+
+  const stream = streamSimple(session.model as Model<Api>, context, options);
+
+  let fullText = "";
+  for await (const event of stream) {
+    handleStreamEvent(event, session, (delta) => {
+      fullText += delta;
+    });
+  }
+
+  const finalMessage = await stream.result();
+  const responseText =
+    finalMessage.content
+      .filter((content) => content.type === "text")
+      .map((content) => content.text)
+      .join("") || fullText;
+
+  session.messages.push({ role: "assistant", content: responseText });
+  session.lastModelDescription = `${(session.model as Model<Api>).provider}/${(session.model as Model<Api>).id}`;
+}
+
+function handleStreamEvent(
+  event: AssistantMessageEvent,
+  session: HermesStreamSession,
+  onTextDelta: (delta: string) => void,
+): void {
+  if (event.type === "text_delta") {
+    session.callbacks.onText?.(event.delta);
+    onTextDelta(event.delta);
+    return;
+  }
+
+  if (event.type === "thinking_delta") {
+    session.callbacks.onThinking?.(event.delta);
+    return;
+  }
+
+  if (event.type === "toolcall_end") {
+    session.callbacks.onToolStart?.(event.toolCall.name, event.toolCall.arguments);
+    session.callbacks.onToolEnd?.(event.toolCall.name, false, event.toolCall.arguments);
+    return;
+  }
+
+  if (event.type === "error") {
+    const errorMessage = event.error.errorMessage ?? "Hermes stream failed";
+    throw new Error(errorMessage);
+  }
+
+  if (event.type === "done") {
+    session.usage = event.message.usage;
+  }
+}
+
+export function describeStreamModel(session: HermesStreamSession): string {
+  return session.lastModelDescription;
+}

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

@@ -3,47 +3,55 @@ import type {
   AgentRuntimeOptions,
   AgentSession,
   AgentSessionResult,
+  HermesModelConfig,
 } from "./types.js";
-import { createFnAgent, describeModel, promptWithFallback } from "./pi-module.js";
-
-const getModelDescription = describeModel;
+import { createStreamSession, describeStreamModel, streamPrompt } from "./pi-module.js";
 
 export class HermesRuntimeAdapter implements AgentRuntime {
   readonly id = "hermes";
   readonly name = "Hermes Runtime";
 
+  constructor(
+    private readonly config: HermesModelConfig = {
+      provider: "anthropic",
+      modelId: "claude-sonnet-4-5",
+    },
+  ) {}
+
   async createSession(options: AgentRuntimeOptions): Promise<AgentSessionResult> {
-    return createFnAgent({
-      cwd: options.cwd,
+    const session = createStreamSession({
+      provider: this.config.provider,
+      modelId: this.config.modelId,
+      apiKey: this.config.apiKey,
+      thinkingLevel: this.config.thinkingLevel,
       systemPrompt: options.systemPrompt,
-      tools: options.tools,
-      customTools: options.customTools,
-      onText: options.onText,
-      onThinking: options.onThinking,
-      onToolStart: options.onToolStart,
-      onToolEnd: options.onToolEnd,
-      defaultProvider: options.defaultProvider,
-      defaultModelId: options.defaultModelId,
-      fallbackProvider: options.fallbackProvider,
-      fallbackModelId: options.fallbackModelId,
-      defaultThinkingLevel: options.defaultThinkingLevel,
-      sessionManager: options.sessionManager,
-      skillSelection: options.skillSelection,
-      skills: options.skills,
+      callbacks: {
+        onText: options.onText,
+        onThinking: options.onThinking,
+        onToolStart: options.onToolStart,
+        onToolEnd: options.onToolEnd,
+      },
     });
+
+    return {
+      session,
+      sessionFile: undefined,
+    };
   }
 
-  async promptWithFallback(session: AgentSession, prompt: string, options?: unknown): Promise<void> {
-    return promptWithFallback(session, prompt, options);
+  async promptWithFallback(session: AgentSession, prompt: string, _options?: unknown): Promise<void> {
+    const userMessage = { role: "user", content: prompt };
+    session.messages.push(userMessage);
+    await streamPrompt(session, userMessage as any);
   }
 
   describeModel(session: AgentSession): string {
-    return getModelDescription(session);
+    return describeStreamModel(session);
   }
 
   async dispose(session: AgentSession): Promise<void> {
-    if (typeof (session as { dispose?: () => Promise<void> }).dispose === "function") {
-      await (session as { dispose: () => Promise<void> }).dispose();
+    if (typeof session.dispose === "function") {
+      session.dispose();
     }
   }
 }

plugins/fusion-plugin-hermes-runtime/src/types.ts

@@ -5,12 +5,33 @@
  * internal engine exports.
  */
 
-/** Minimal session shape used by the runtime adapter. */
-export interface AgentSession {
-  dispose?: () => Promise<void> | void;
+export interface HermesCallbacks {
+  onText?: (text: string) => void;
+  onThinking?: (text: string) => void;
+  onToolStart?: (toolName: string, args?: unknown) => void;
+  onToolEnd?: (toolName: string, isError: boolean, result?: unknown) => void;
 }
 
-/** Options for creating an agent session. Mirrors createFnAgent inputs used by the adapter. */
+export interface HermesStreamSession {
+  model: unknown;
+  systemPrompt: string;
+  messages: unknown[];
+  apiKey: string | undefined;
+  thinkingLevel: string | undefined;
+  sessionId: string;
+  lastModelDescription: string;
+  callbacks: HermesCallbacks;
+  usage?: unknown;
+  dispose(): void;
+}
+
+export type AgentSession = HermesStreamSession;
+
+/**
+ * Options for creating an agent session.
+ * Mirrors the engine's runtime options shape. Hermes accepts these options
+ * for compatibility and silently ignores Pi-specific fields.
+ */
 export interface AgentRuntimeOptions {
   cwd: string;
   systemPrompt: string;
@@ -18,7 +39,7 @@ export interface AgentRuntimeOptions {
   customTools?: unknown;
   onText?: (text: string) => void;
   onThinking?: (text: string) => void;
-  onToolStart?: (toolName: string, args?: Record<string, unknown>) => void;
+  onToolStart?: (toolName: string, args?: unknown) => void;
   onToolEnd?: (toolName: string, isError: boolean, result?: unknown) => void;
   defaultProvider?: string;
   defaultModelId?: string;
@@ -45,3 +66,17 @@ export interface AgentRuntime {
   describeModel(session: AgentSession): string;
   dispose?(session: AgentSession): Promise<void>;
 }
+
+export interface HermesModelConfig {
+  provider: string;
+  modelId: string;
+  apiKey?: string;
+  thinkingLevel?: string;
+}
+
+export interface ResolvedModelConfig {
+  provider: string;
+  modelId: string;
+  apiKey: string | undefined;
+  thinkingLevel: string | undefined;
+}