feat(FN-2263): merge fusion/fn-2263 (auto-resolved)

- docs(FN-2263): update README with scaffolded scope and deferral documentation
- test(FN-2263): verify hermes runtime plugin build and tests
- feat(FN-2263): implement plugin entrypoint with runtime registration shell
- feat(FN-2263): scaffold Hermes runtime plugin package
- test(FN-2256): add mocks for createResolvedAgentSession in tests
- docs(FN-2256): update architecture docs and add changeset
- fix(FN-2256): fix lint errors and TypeScript issues
- feat(FN-2256): add runtime selection regression tests — Step 4
- feat(FN-2256): route engine session creation through runtime resolver — Step 3
- feat(FN-2256): extend PluginRunner runtime lookup surface — Step 2
- feat(FN-2256): add runtime abstraction and resolver — Step 1

plugins/fusion-plugin-hermes-runtime/README.md

@@ -0,0 +1,116 @@
+# Hermes Runtime Plugin
+
+> **Status:** Scaffolded - Full implementation deferred to FN-2264
+
+Provides a Hermes AI runtime plugin for Fusion, enabling AI agent execution capabilities for task automation.
+
+## Overview
+
+This plugin registers the Hermes runtime with the Fusion plugin system. The Hermes runtime is designed to provide AI-powered task execution capabilities for Fusion tasks.
+
+**Note:** The runtime behavior is intentionally deferred. Any runtime invocation will return a "not implemented" signal referencing FN-2264 for the full implementation.
+
+## Features
+
+- **Hermes Runtime Registration**: Registers the Hermes runtime with the Fusion plugin system
+- **Runtime Discovery**: Exposes runtime metadata for plugin discovery pipeline
+- **Runtime Factory**: Provides factory function for runtime instance creation (placeholder)
+
+## Installation
+
+### Option 1: Copy to plugins directory
+
+```bash
+cp -r fusion-plugin-hermes-runtime ~/.fusion/plugins/
+```
+
+### Option 2: Install via CLI
+
+```bash
+fn plugin install /path/to/fusion-plugin-hermes-runtime
+```
+
+## Current Status
+
+| Component | Status |
+|-----------|--------|
+| Plugin Scaffold | ✅ Complete |
+| Runtime Registration | ✅ Complete |
+| Runtime Behavior | ⏳ Deferred to FN-2264 |
+
+## Runtime Registration
+
+The plugin registers a runtime with the following metadata:
+
+- **Runtime ID:** `hermes-runtime`
+- **Name:** `Hermes AI Runtime`
+- **Description:** AI agent execution runtime for Fusion tasks
+- **Version:** `0.1.0`
+
+### Deferred Implementation
+
+The runtime factory currently returns a placeholder object. When `execute()` is called, it throws an error referencing FN-2264:
+
+```
+Error: Hermes runtime is not yet implemented. Full implementation deferred to FN-2264.
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Build
+pnpm build
+```
+
+### Test Coverage
+
+The plugin includes comprehensive tests covering:
+
+- Plugin manifest identity verification
+- Runtime registration presence and metadata consistency
+- Deferred implementation behavior (placeholder, error on execute)
+- Plugin lifecycle hooks (onLoad, onUnload)
+
+## API
+
+### Plugin Manifest
+
+```json
+{
+  "id": "fusion-plugin-hermes-runtime",
+  "name": "Hermes Runtime Plugin",
+  "version": "0.1.0",
+  "description": "Hermes AI runtime plugin for Fusion",
+  "author": "Fusion Team",
+  "homepage": "https://github.com/gsxdsm/fusion",
+  "runtime": {
+    "runtimeId": "hermes-runtime",
+    "name": "Hermes AI Runtime",
+    "description": "AI agent execution runtime for Fusion tasks",
+    "version": "0.1.0"
+  }
+}
+```
+
+### Exports
+
+The plugin exports the following for testing and verification:
+
+- `default` - The FusionPlugin instance
+- `hermesRuntimeMetadata` - Runtime manifest metadata object
+- `hermesRuntimeFactory` - Factory function for creating runtime instances
+- `HERMES_RUNTIME_ID` - Runtime ID constant (`"hermes-runtime"`)
+
+## Related
+
+- [FN-2264](https://github.com/gsxdsm/fusion/issues/FN-2264) - Full Hermes runtime implementation
+
+## License
+
+MIT

plugins/fusion-plugin-hermes-runtime/manifest.json

@@ -0,0 +1,14 @@
+{
+  "id": "fusion-plugin-hermes-runtime",
+  "name": "Hermes Runtime Plugin",
+  "version": "0.1.0",
+  "description": "Hermes AI runtime plugin for Fusion - provides AI agent execution runtime capabilities",
+  "author": "Fusion Team",
+  "homepage": "https://github.com/gsxdsm/fusion",
+  "runtime": {
+    "runtimeId": "hermes-runtime",
+    "name": "Hermes AI Runtime",
+    "description": "AI agent execution runtime for Fusion tasks",
+    "version": "0.1.0"
+  }
+}

plugins/fusion-plugin-hermes-runtime/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@fusion-plugin-examples/hermes-runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Hermes AI runtime plugin for Fusion - provides AI agent execution runtime",
+  "keywords": [
+    "fusion-plugin",
+    "hermes",
+    "runtime",
+    "ai"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "private": true,
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --silent=passed-only --reporter=dot"
+  },
+  "dependencies": {
+    "@fusion/plugin-sdk": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "vitest": "^3.2.4"
+  }
+}

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

@@ -0,0 +1,209 @@
+/**
+ * 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 ───────────────────────────────────────────────────────────────
+
+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 {
+  return {
+    pluginId: "fusion-plugin-hermes-runtime",
+    settings: {},
+    logger: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn(),
+    },
+    emitEvent: vi.fn(),
+    taskStore: {
+      getTask: vi.fn(),
+    },
+    ...overrides,
+  };
+}
+
+// ── Test Suite ─────────────────────────────────────────────────────────────────
+
+describe("hermes-runtime plugin", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("plugin manifest identity", () => {
+    it("should have correct manifest id", () => {
+      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", () => {
+      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 AI Runtime");
+      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);
+    });
+  });
+
+  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 () => {
+      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.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();
+      expect(hermesRuntimeMetadata.runtimeId).toBe("hermes-runtime");
+      expect(hermesRuntimeMetadata.name).toBe("Hermes AI 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-runtime");
+    });
+
+    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");
+    });
+  });
+});

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

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+
+import { definePlugin } from "@fusion/plugin-sdk";
+import type {
+  FusionPlugin,
+  PluginContext,
+  PluginRuntimeFactory,
+  PluginRuntimeManifestMetadata,
+} from "@fusion/plugin-sdk";
+
+// ── Hermes Runtime Metadata ───────────────────────────────────────────────────
+
+const HERMES_RUNTIME_ID = "hermes-runtime";
+const HERMES_RUNTIME_VERSION = "0.1.0";
+
+const hermesRuntimeMetadata: PluginRuntimeManifestMetadata = {
+  runtimeId: HERMES_RUNTIME_ID,
+  name: "Hermes AI Runtime",
+  description: "AI agent execution runtime for Fusion tasks",
+  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`,
+      );
+    },
+  };
+};
+
+// ── Plugin Definition ─────────────────────────────────────────────────────────
+
+const plugin: FusionPlugin = definePlugin({
+  manifest: {
+    id: "fusion-plugin-hermes-runtime",
+    name: "Hermes Runtime Plugin",
+    version: "0.1.0",
+    description: "Hermes AI runtime plugin for Fusion - provides AI agent execution runtime capabilities",
+    author: "Fusion Team",
+    homepage: "https://github.com/gsxdsm/fusion",
+    runtime: hermesRuntimeMetadata,
+  },
+  state: "installed",
+  hooks: {
+    onLoad: (ctx) => {
+      ctx.logger.info("Hermes Runtime Plugin loaded (placeholder - FN-2264 pending)");
+      ctx.emitEvent("hermes-runtime:loaded", {
+        runtimeId: HERMES_RUNTIME_ID,
+        version: HERMES_RUNTIME_VERSION,
+        status: "deferred",
+      });
+    },
+    onUnload: () => {
+      // No context available during unload
+    },
+  },
+  runtime: {
+    metadata: hermesRuntimeMetadata,
+    factory: hermesRuntimeFactory,
+  },
+});
+
+export default plugin;
+
+// ── Exports for Testing ───────────────────────────────────────────────────────
+
+export { hermesRuntimeMetadata, hermesRuntimeFactory, HERMES_RUNTIME_ID };

plugins/fusion-plugin-hermes-runtime/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*"]
+}

plugins/fusion-plugin-hermes-runtime/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "vitest/config";
+
+const requestedMaxWorkers = Number.parseInt(process.env.VITEST_MAX_WORKERS ?? "2", 10);
+const maxWorkers = Math.max(1, Math.min(2, Number.isFinite(requestedMaxWorkers) ? requestedMaxWorkers : 2));
+process.env.VITEST_MAX_WORKERS = String(maxWorkers);
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+    pool: "threads",
+    maxWorkers,
+    poolOptions: { threads: { minThreads: 1, maxThreads: maxWorkers }, forks: { minForks: 1, maxForks: maxWorkers } },
+  },
+});