feat(FN-2481): align Hermes runtime artifacts and compatibility coverage

- Regenerate fusion-plugin-hermes-runtime build artifacts and manifest metadata for runtime packaging
- Refactor Hermes runtime source into dedicated pi-module, runtime-adapter, and shared type modules
- Expand Hermes and engine plugin-runner tests to validate cross-runtime compatibility behavior
- Update getting-started, settings reference, and Hermes README docs to reflect the current runtime integration guidance

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

@@ -1,15 +1,19 @@
-/**
- * Hermes Runtime Plugin Tests
- *
- * Tests verify:
- * - Plugin manifest identity
- * - Runtime registration presence
- * - Deferred-implementation behavior
- */
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import plugin, { hermesRuntimeMetadata, hermesRuntimeFactory, HERMES_RUNTIME_ID } from "../index.js";
 
-// ── Mock Context ───────────────────────────────────────────────────────────────
+const { mockCreateFnAgent, mockPromptWithFallback, mockDescribeModel } = vi.hoisted(() => ({
+  mockCreateFnAgent: vi.fn(),
+  mockPromptWithFallback: vi.fn(),
+  mockDescribeModel: vi.fn().mockReturnValue("unknown model"),
+}));
+
+vi.mock("../pi-module.js", () => ({
+  createFnAgent: mockCreateFnAgent,
+  promptWithFallback: mockPromptWithFallback,
+  describeModel: mockDescribeModel,
+}));
+
+import plugin, { hermesRuntimeMetadata, hermesRuntimeFactory, HERMES_RUNTIME_ID } from "../index.js";
+import { HermesRuntimeAdapter } from "../runtime-adapter.js";
 
 interface MockLogger {
   info: ReturnType<typeof vi.fn>;
@@ -46,8 +50,6 @@ function createMockContext(overrides: Partial<MockContext> = {}): MockContext {
   };
 }
 
-// ── Test Suite ─────────────────────────────────────────────────────────────────
-
 describe("hermes-runtime plugin", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -58,153 +60,69 @@ describe("hermes-runtime plugin", () => {
   });
 
   describe("plugin manifest identity", () => {
-    it("should have correct manifest id", () => {
+    it("should have correct manifest fields", () => {
       expect(plugin.manifest.id).toBe("fusion-plugin-hermes-runtime");
-    });
-
-    it("should have correct manifest name", () => {
       expect(plugin.manifest.name).toBe("Hermes Runtime Plugin");
-    });
-
-    it("should have correct version", () => {
       expect(plugin.manifest.version).toBe("0.1.0");
-    });
-
-    it("should have description", () => {
-      expect(plugin.manifest.description).toBeDefined();
       expect(plugin.manifest.description).toContain("Hermes");
-    });
-
-    it("should have author", () => {
       expect(plugin.manifest.author).toBe("Fusion Team");
-    });
-
-    it("should have homepage", () => {
-      expect(plugin.manifest.homepage).toBe("https://github.com/gsxdsm/fusion");
-    });
-
-    it("should have state 'installed'", () => {
       expect(plugin.state).toBe("installed");
     });
   });
 
   describe("runtime registration", () => {
-    it("should have runtime registration", () => {
+    it("should register hermes runtime metadata", () => {
       expect(plugin.runtime).toBeDefined();
-    });
-
-    it("should have correct runtime metadata", () => {
-      expect(plugin.runtime?.metadata).toBeDefined();
       expect(plugin.runtime?.metadata.runtimeId).toBe(HERMES_RUNTIME_ID);
       expect(plugin.runtime?.metadata.name).toBe("Hermes Runtime");
-      expect(plugin.runtime?.metadata.description).toContain("deferred to FN-2264");
+      expect(plugin.runtime?.metadata.description).toContain("Hermes-backed AI session");
       expect(plugin.runtime?.metadata.version).toBe("0.1.0");
     });
 
-    it("should have runtime factory function", () => {
-      expect(plugin.runtime?.factory).toBeDefined();
-      expect(typeof plugin.runtime?.factory).toBe("function");
-    });
-
     it("should have consistent runtime metadata between export and manifest", () => {
-      expect(plugin.manifest.runtime).toBeDefined();
-      expect(plugin.manifest.runtime?.runtimeId).toBe(hermesRuntimeMetadata.runtimeId);
-      expect(plugin.manifest.runtime?.name).toBe(hermesRuntimeMetadata.name);
-      expect(plugin.manifest.runtime?.version).toBe(hermesRuntimeMetadata.version);
+      expect(plugin.manifest.runtime).toEqual(hermesRuntimeMetadata);
+      expect(plugin.runtime?.metadata).toEqual(hermesRuntimeMetadata);
     });
   });
 
   describe("hooks", () => {
-    it("should have onLoad hook", () => {
-      expect(plugin.hooks.onLoad).toBeDefined();
-      expect(typeof plugin.hooks.onLoad).toBe("function");
-    });
-
-    it("should have onUnload hook", () => {
-      expect(plugin.hooks.onUnload).toBeDefined();
-      expect(typeof plugin.hooks.onUnload).toBe("function");
-    });
-
-    it("onLoad should log startup message", async () => {
+    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(
-        expect.stringContaining("Hermes Runtime Plugin loaded"),
-      );
-    });
 
-    it("onLoad should 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",
-        status: "deferred",
       });
     });
 
     it("onUnload should not throw", () => {
-      expect(plugin.hooks.onUnload).toBeDefined();
       expect(() => plugin.hooks.onUnload?.()).not.toThrow();
     });
   });
 
-  describe("deferred implementation behavior", () => {
-    it("should export hermesRuntimeMetadata", () => {
-      expect(hermesRuntimeMetadata).toBeDefined();
+  describe("runtime factory behavior", () => {
+    it("should export runtime constants", () => {
+      expect(HERMES_RUNTIME_ID).toBe("hermes");
       expect(hermesRuntimeMetadata.runtimeId).toBe("hermes");
-      expect(hermesRuntimeMetadata.name).toBe("Hermes Runtime");
-    });
-
-    it("should export hermesRuntimeFactory", () => {
-      expect(hermesRuntimeFactory).toBeDefined();
       expect(typeof hermesRuntimeFactory).toBe("function");
     });
 
-    it("should export HERMES_RUNTIME_ID constant", () => {
-      expect(HERMES_RUNTIME_ID).toBe("hermes");
+    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("runtime factory should return placeholder object", () => {
-      const ctx = createMockContext();
-      const runtime = hermesRuntimeFactory(ctx as any) as Record<string, unknown>;
-
-      expect(runtime).toBeDefined();
-      expect(runtime).toHaveProperty("runtimeId", HERMES_RUNTIME_ID);
-      expect(runtime).toHaveProperty("version", "0.1.0");
-      expect(runtime).toHaveProperty("status", "deferred");
-      expect(runtime).toHaveProperty("message");
-      expect(runtime.message).toContain("FN-2264");
-    });
-
-    it("runtime factory execute should throw error referencing FN-2264", async () => {
-      const ctx = createMockContext();
-      const runtime = hermesRuntimeFactory(ctx as any) as { execute: () => Promise<never> };
-
-      await expect(runtime.execute()).rejects.toThrow("FN-2264");
-      await expect(runtime.execute()).rejects.toThrow("not yet implemented");
-    });
-
-    it("runtime factory should not throw during creation (only on execute)", () => {
-      const ctx = createMockContext();
-      expect(() => hermesRuntimeFactory(ctx as any)).not.toThrow();
-    });
-  });
-
-  describe("manifest consistency", () => {
-    it("plugin.manifest.runtime matches hermesRuntimeMetadata", () => {
-      expect(plugin.manifest.runtime).toEqual(hermesRuntimeMetadata);
-    });
-
-    it("plugin.runtime.metadata matches hermesRuntimeMetadata", () => {
-      expect(plugin.runtime?.metadata).toEqual(hermesRuntimeMetadata);
-    });
-
-    it("manifest.json fields match plugin manifest", () => {
-      // These should match the manifest.json file
-      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");
+    it("factory creation should not throw", async () => {
+      await expect(hermesRuntimeFactory(createMockContext() as any)).resolves.toBeInstanceOf(
+        HermesRuntimeAdapter,
+      );
     });
   });
 });

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

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { HermesRuntimeAdapter } from "../runtime-adapter.js";
+
+const { mockCreateFnAgent, mockPromptWithFallback, mockDescribeModel } = vi.hoisted(() => ({
+  mockCreateFnAgent: vi.fn(),
+  mockPromptWithFallback: vi.fn(),
+  mockDescribeModel: vi.fn(),
+}));
+
+vi.mock("../pi-module.js", () => ({
+  createFnAgent: mockCreateFnAgent,
+  promptWithFallback: mockPromptWithFallback,
+  describeModel: mockDescribeModel,
+}));
+
+describe("HermesRuntimeAdapter", () => {
+  let adapter: HermesRuntimeAdapter;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDescribeModel.mockReturnValue("mock/anthropic-claude");
+    adapter = new HermesRuntimeAdapter();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("has stable runtime identity", () => {
+    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" });
+
+    const result = await adapter.createSession({
+      cwd: "/project",
+      systemPrompt: "You are helpful",
+      defaultProvider: "anthropic",
+      defaultModelId: "claude-sonnet-4-5",
+      fallbackProvider: "openai",
+      fallbackModelId: "gpt-4o",
+      skills: ["bash"],
+    });
+
+    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(result.session).toBe(mockSession);
+    expect(result.sessionFile).toBe("/tmp/session.json");
+  });
+
+  it("delegates promptWithFallback to pi seam", async () => {
+    const session = { id: "s-1" };
+    mockPromptWithFallback.mockResolvedValue(undefined);
+
+    await adapter.promptWithFallback(session as any, "Hello", { images: [] });
+
+    expect(mockPromptWithFallback).toHaveBeenCalledWith(session, "Hello", { images: [] });
+  });
+
+  it("delegates describeModel to pi seam", () => {
+    const session = { id: "s-2" };
+    mockDescribeModel.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");
+  });
+
+  it("dispose calls session.dispose when present and no-ops otherwise", async () => {
+    const disposeMock = vi.fn().mockResolvedValue(undefined);
+
+    await adapter.dispose({ dispose: disposeMock });
+    await expect(adapter.dispose({ id: "no-dispose" } as any)).resolves.toBeUndefined();
+
+    expect(disposeMock).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -1,17 +1,14 @@
 /**
  * Hermes Runtime Plugin
  *
- * Provides Hermes AI runtime capabilities for Fusion tasks.
- * This plugin registers the Hermes runtime with the Fusion plugin system.
- *
- * Note: Full runtime behavior is deferred to FN-2264.
- * Any runtime invocation will return a "not implemented" signal.
+ * Provides an executable Hermes runtime adapter for Fusion's plugin runtime
+ * discovery and session execution pipeline.
  */
 
 import { definePlugin } from "@fusion/plugin-sdk";
+import { HermesRuntimeAdapter } from "./runtime-adapter.js";
 import type {
   FusionPlugin,
-  PluginContext,
   PluginRuntimeFactory,
   PluginRuntimeManifestMetadata,
 } from "@fusion/plugin-sdk";
@@ -24,37 +21,14 @@ const HERMES_RUNTIME_VERSION = "0.1.0";
 const hermesRuntimeMetadata: PluginRuntimeManifestMetadata = {
   runtimeId: HERMES_RUNTIME_ID,
   name: "Hermes Runtime",
-  description: "Experimental Hermes runtime integration for Fusion tasks (implementation deferred to FN-2264)",
+  description: "Hermes-backed AI session using the user's configured pi provider and model",
   version: HERMES_RUNTIME_VERSION,
 };
 
 // ── Hermes Runtime Factory ────────────────────────────────────────────────────
 
-/**
- * Factory function for creating the Hermes runtime instance.
- *
- * This is a placeholder implementation. Full runtime behavior is deferred to FN-2264.
- * Any runtime invocation will throw a descriptive error referencing FN-2264.
- *
- * @param _ctx - Plugin context (unused in placeholder)
- * @throws Error with message referencing FN-2264 for full implementation
- */
-const hermesRuntimeFactory: PluginRuntimeFactory = (_ctx: PluginContext) => {
-  // Return a placeholder object that signals deferred implementation
-  return {
-    runtimeId: HERMES_RUNTIME_ID,
-    version: HERMES_RUNTIME_VERSION,
-    status: "deferred",
-    message: `Hermes runtime implementation is deferred to FN-2264. ` +
-             `Current invocation is a placeholder.`,
-    execute: async () => {
-      throw new Error(
-        `Hermes runtime is not yet implemented. ` +
-        `Full implementation deferred to FN-2264. ` +
-        `See https://github.com/gsxdsm/fusion/issues/FN-2264`,
-      );
-    },
-  };
+const hermesRuntimeFactory: PluginRuntimeFactory = async () => {
+  return new HermesRuntimeAdapter();
 };
 
 // ── Plugin Definition ─────────────────────────────────────────────────────────
@@ -72,11 +46,10 @@ const plugin: FusionPlugin = definePlugin({
   state: "installed",
   hooks: {
     onLoad: (ctx) => {
-      ctx.logger.info("Hermes Runtime Plugin loaded (placeholder - FN-2264 pending)");
+      ctx.logger.info("Hermes Runtime Plugin loaded");
       ctx.emitEvent("hermes-runtime:loaded", {
         runtimeId: HERMES_RUNTIME_ID,
         version: HERMES_RUNTIME_VERSION,
-        status: "deferred",
       });
     },
     onUnload: () => {

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

@@ -0,0 +1,44 @@
+/**
+ * Pi Module Seam
+ *
+ * Provides a mockable import path for pi functions used by the HermesRuntimeAdapter.
+ */
+
+export interface PiAgentSession {
+  dispose?: () => Promise<void> | void;
+}
+
+export interface PiAgentResult {
+  session: PiAgentSession;
+  sessionFile?: string;
+}
+
+export interface PiAgentOptions {
+  cwd: string;
+  systemPrompt: string;
+  tools?: unknown;
+  customTools?: unknown;
+  onText?: (text: string) => void;
+  onThinking?: (text: string) => void;
+  onToolStart?: (toolName: string, args?: unknown) => void;
+  onToolEnd?: (toolName: string, result?: unknown) => void;
+  defaultProvider?: string;
+  defaultModelId?: string;
+  fallbackProvider?: string;
+  fallbackModelId?: string;
+  defaultThinkingLevel?: string;
+  sessionManager?: unknown;
+  skillSelection?: unknown;
+  skills?: string[];
+}
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const _piModule = require("../../../packages/engine/src/pi.js") as {
+  createFnAgent: (options: PiAgentOptions) => Promise<PiAgentResult>;
+  promptWithFallback: (session: PiAgentSession, prompt: string, options?: unknown) => Promise<void>;
+  describeModel: (session: PiAgentSession) => string;
+};
+
+export const createFnAgent = _piModule.createFnAgent;
+export const promptWithFallback = _piModule.promptWithFallback;
+export const describeModel = _piModule.describeModel;

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

@@ -0,0 +1,49 @@
+import type {
+  AgentRuntime,
+  AgentRuntimeOptions,
+  AgentSession,
+  AgentSessionResult,
+} from "./types.js";
+import { createFnAgent, describeModel, promptWithFallback } from "./pi-module.js";
+
+const getModelDescription = describeModel;
+
+export class HermesRuntimeAdapter implements AgentRuntime {
+  readonly id = "hermes";
+  readonly name = "Hermes Runtime";
+
+  async createSession(options: AgentRuntimeOptions): Promise<AgentSessionResult> {
+    return createFnAgent({
+      cwd: options.cwd,
+      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,
+    });
+  }
+
+  async promptWithFallback(session: AgentSession, prompt: string, options?: unknown): Promise<void> {
+    return promptWithFallback(session, prompt, options);
+  }
+
+  describeModel(session: AgentSession): string {
+    return getModelDescription(session);
+  }
+
+  async dispose(session: AgentSession): Promise<void> {
+    if (typeof (session as { dispose?: () => Promise<void> }).dispose === "function") {
+      await (session as { dispose: () => Promise<void> }).dispose();
+    }
+  }
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Hermes Runtime Plugin - Type Definitions
+ *
+ * The runtime contract is defined locally to avoid compile-time coupling to
+ * internal engine exports.
+ */
+
+/** Minimal session shape used by the runtime adapter. */
+export interface AgentSession {
+  dispose?: () => Promise<void> | void;
+}
+
+/** Options for creating an agent session. Mirrors createFnAgent inputs used by the adapter. */
+export interface AgentRuntimeOptions {
+  cwd: string;
+  systemPrompt: string;
+  tools?: unknown;
+  customTools?: unknown;
+  onText?: (text: string) => void;
+  onThinking?: (text: string) => void;
+  onToolStart?: (toolName: string, args?: unknown) => void;
+  onToolEnd?: (toolName: string, result?: unknown) => void;
+  defaultProvider?: string;
+  defaultModelId?: string;
+  fallbackProvider?: string;
+  fallbackModelId?: string;
+  defaultThinkingLevel?: string;
+  sessionManager?: unknown;
+  skillSelection?: unknown;
+  skills?: string[];
+}
+
+/** Result of creating a session. */
+export interface AgentSessionResult {
+  session: AgentSession;
+  sessionFile?: string;
+}
+
+/** Agent runtime adapter interface. */
+export interface AgentRuntime {
+  id: string;
+  name: string;
+  createSession(options: AgentRuntimeOptions): Promise<AgentSessionResult>;
+  promptWithFallback(session: AgentSession, prompt: string, options?: unknown): Promise<void>;
+  describeModel(session: AgentSession): string;
+  dispose?(session: AgentSession): Promise<void>;
+}