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
2026-04-22 14:01:43 -07:00
parent a1409389a2
commit acceca7fe5
12 changed files with 586 additions and 121 deletions
--- a/packages/dashboard/app/components/DevServerView.tsx
+++ b/packages/dashboard/app/components/DevServerView.tsx
@@ -409,7 +409,6 @@ export function DevServerView({ addToast, projectId }: DevServerViewProps) {
    }

    const fallbackCwd = normalizeSourceToCwd(selectedSource) ?? ".";
-    const scriptName = selectedCandidate?.scriptName ?? selectedScript ?? "custom";
    const cwd = selectedCandidate?.cwd ?? fallbackCwd;

    void runAction(
--- a/packages/dashboard/app/hooks/useDevServer.ts
+++ b/packages/dashboard/app/hooks/useDevServer.ts
@@ -1,8 +1,7 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import {
  detectDevServerCommands,
  fetchDevServer,
-  fetchDevServerLogs,
  fetchDevServers,
  getDevServerLogsStreamUrl,
  getDevServerSessionLogsStreamUrl,
@@ -355,17 +354,24 @@ export function useDevServer(projectId?: string): UseDevServerReturn {
          if (contextVersionRef.current !== versionAtStart) {
            return;
          }
-          const payload = parseJson<{ status?: DevServerSession["status"]; pid?: number }>(event.data);
-          const nextStatus = payload?.status;
+          const payload = parseJson<DevServerSession | { status?: DevServerSession["status"]; pid?: number }>(event.data);
+          // If payload is a full session, use it directly
+          if (payload && "config" in payload) {
+            setSession(payload as DevServerSession);
+            return;
+          }
+          // Otherwise, treat as partial update
+          const partial = payload as { status?: DevServerSession["status"]; pid?: number } | undefined;
+          const nextStatus = partial?.status;
          if (nextStatus) {
            setSession((prev) => (prev
              ? {
                ...prev,
                status: nextStatus,
-                runtime: payload.pid
+                runtime: partial?.pid
                  ? {
                    ...(prev.runtime ?? { startedAt: new Date().toISOString() }),
-                    pid: payload.pid,
+                    pid: partial.pid,
                  }
                  : prev.runtime,
              }
@@ -644,6 +650,15 @@ export function useDevServer(projectId?: string): UseDevServerReturn {
    await refresh();
  }, [refresh]);

+  // Reset helper for tests: incrementing resetVersion signals hook to re-initialize
+  useEffect(() => {
+    const version = resetVersion;
+    return () => {
+      if (resetVersion !== version) {
+        contextVersionRef.current += 1;
+      }
+    };
+  }, []);
  const previewUrl = extractPreviewUrl(session);
  const serverState = session ? { ...session, pid: session.runtime?.pid } : null;

--- a/packages/dashboard/app/hooks/usePreviewEmbed.ts
+++ b/packages/dashboard/app/hooks/usePreviewEmbed.ts
@@ -1,122 +1,76 @@
 import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";

 export type EmbedStatus = "unknown" | "loading" | "embedded" | "blocked" | "error";
-export type EmbedDetectionMethod = "auto" | "manual" | null;
-
-const BLOCKED_CONTEXT = "The server may block iframe embedding via X-Frame-Options or Content-Security-Policy headers. Browsers prevent detecting these headers from JavaScript.";
-const ERROR_CONTEXT = "The preview URL could not be loaded. The server may not be running or the URL may be incorrect.";
-const TIMEOUT_CONTEXT = "Preview is taking longer than expected to load. The server may be blocking the iframe or may not have started yet.";

 interface UsePreviewEmbedOptions {
  loadTimeoutMs?: number;
-  detectionMethod?: EmbedDetectionMethod;
 }

 interface UsePreviewEmbedResult {
  embedStatus: EmbedStatus;
+  setEmbedStatus: (status: EmbedStatus) => void;
+  resetEmbedStatus: () => void;
+  retry: () => void;
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  handleIframeLoad: () => void;
+  handleIframeError: () => void;
  isEmbedded: boolean;
  isBlocked: boolean;
  blockReason: string | null;
-  detectionMethod: EmbedDetectionMethod;
-  iframeRef: RefObject<HTMLIFrameElement | null>;
-  resetEmbedStatus: () => void;
-  // Extended API for direct status control (backward compatibility)
-  setEmbedStatus: (status: EmbedStatus) => void;
-  retry: () => void;
-  // Legacy aliases for backward compatibility
+  /** @deprecated Use blockReason instead */
  embedContext: string | null;
-  handleIframeLoad: () => void;
-  handleIframeError: () => void;
-  resetEmbed: () => void;
 }

-function defaultContextForStatus(status: EmbedStatus): string | null {
-  switch (status) {
-    case "blocked":
-      return BLOCKED_CONTEXT;
-    case "error":
-      return ERROR_CONTEXT;
-    case "embedded":
-    case "loading":
-    case "unknown":
-    default:
-      return null;
+const DEFAULT_LOAD_TIMEOUT_MS = 10_000;
+
+const BLOCKED_CONTEXT = "This preview appears to block iframe embedding. Open it in a new tab instead.";
+const ERROR_CONTEXT = "The preview URL could not be loaded. Verify the server is running and the URL is correct.";
+const TIMEOUT_CONTEXT = "Preview is taking longer than expected and may block iframe embedding.";
+
+function getContextForStatus(status: EmbedStatus): string | null {
+  if (status === "blocked") {
+    return BLOCKED_CONTEXT;
  }
+
+  if (status === "error") {
+    return ERROR_CONTEXT;
+  }
+
+  return null;
 }

 export function usePreviewEmbed(url: string | null, options: UsePreviewEmbedOptions = {}): UsePreviewEmbedResult {
-  const { loadTimeoutMs = 10000, detectionMethod: initialDetectionMethod = null } = options;
+  const loadTimeoutMs = options.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;

  const iframeRef = useRef<HTMLIFrameElement | null>(null);
-  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const timeoutRef = useRef<number | null>(null);
+
  const [embedStatus, setEmbedStatusState] = useState<EmbedStatus>("unknown");
-  const [blockReason, setBlockReason] = useState<string | null>(null);
-  const [detectionMethod, setDetectionMethod] = useState<EmbedDetectionMethod>(initialDetectionMethod);
+  const [embedContext, setEmbedContext] = useState<string | null>(null);

  const clearLoadingTimeout = useCallback(() => {
    if (timeoutRef.current !== null) {
-      clearTimeout(timeoutRef.current);
+      window.clearTimeout(timeoutRef.current);
      timeoutRef.current = null;
    }
  }, []);

  const setEmbedStatus = useCallback((status: EmbedStatus) => {
    setEmbedStatusState(status);
-    setBlockReason(defaultContextForStatus(status));
+    setEmbedContext(getContextForStatus(status));
  }, []);

-  const setBlockedByTimeout = useCallback(() => {
-    setEmbedStatusState("blocked");
-    setBlockReason(TIMEOUT_CONTEXT);
-  }, []);
-
-  useEffect(() => {
+  const resetEmbedStatus = useCallback(() => {
    clearLoadingTimeout();
-
-    if (!url) {
-      setEmbedStatusState("unknown");
-      setBlockReason(null);
-      return;
-    }
-
    setEmbedStatusState("unknown");
-    setBlockReason(null);
+    setEmbedContext(null);
+  }, [clearLoadingTimeout]);

-    let canceled = false;
-    queueMicrotask(() => {
-      if (canceled) {
-        return;
-      }
-      setEmbedStatusState("loading");
-      setBlockReason(null);
-    });
-
-    return () => {
-      canceled = true;
-      clearLoadingTimeout();
-    };
-  }, [clearLoadingTimeout, url]);
-
-  useEffect(() => {
-    if (embedStatus !== "loading") {
-      clearLoadingTimeout();
-      return;
-    }
-
-    const timer = setTimeout(() => {
-      timeoutRef.current = null;
-      setBlockedByTimeout();
-    }, loadTimeoutMs);
-
-    timeoutRef.current = timer;
-
-    return () => {
-      clearTimeout(timer);
-      if (timeoutRef.current === timer) {
-        timeoutRef.current = null;
-      }
-    };
-  }, [clearLoadingTimeout, embedStatus, loadTimeoutMs, setBlockedByTimeout]);
+  const retry = useCallback(() => {
+    clearLoadingTimeout();
+    setEmbedStatusState("unknown");
+    setEmbedContext(null);
+  }, [clearLoadingTimeout]);

  const handleIframeLoad = useCallback(() => {
    const iframeEl = iframeRef.current;
@@ -132,7 +86,7 @@ export function usePreviewEmbed(url: string | null, options: UsePreviewEmbedOpti
        return;
      }
    } catch {
-      // Cross-origin access can throw; do not treat it as blocked.
+      // Cross-origin access can throw; assume successful embed.
    }

    setEmbedStatus("embedded");
@@ -142,44 +96,53 @@ export function usePreviewEmbed(url: string | null, options: UsePreviewEmbedOpti
    setEmbedStatus("error");
  }, [setEmbedStatus]);

-  const resetEmbedStatus = useCallback(() => {
+  useEffect(() => {
    clearLoadingTimeout();
-    setEmbedStatusState("unknown");
-    setBlockReason(null);
-  }, [clearLoadingTimeout]);

-  const retry = useCallback(() => {
+    if (!url) {
+      setEmbedStatusState("unknown");
+      setEmbedContext(null);
+      return;
+    }
+
+    setEmbedStatusState("loading");
+    setEmbedContext(null);
+  }, [clearLoadingTimeout, url]);
+
+  useEffect(() => {
    clearLoadingTimeout();
-    setEmbedStatusState("unknown");
-    setBlockReason(null);
-  }, [clearLoadingTimeout]);

-  const isEmbedded = useMemo(() => embedStatus === "embedded", [embedStatus]);
-  const isBlocked = useMemo(
-    () => embedStatus === "blocked" || embedStatus === "error",
-    [embedStatus],
-  );
+    if (!url || embedStatus !== "loading") {
+      return;
+    }
+
+    timeoutRef.current = window.setTimeout(() => {
+      setEmbedStatusState("blocked");
+      setEmbedContext(TIMEOUT_CONTEXT);
+      timeoutRef.current = null;
+    }, loadTimeoutMs);
+
+    return clearLoadingTimeout;
+  }, [clearLoadingTimeout, embedStatus, loadTimeoutMs, url]);
+
+  useEffect(() => clearLoadingTimeout, [clearLoadingTimeout]);
+
+  const isEmbedded = embedStatus === "embedded";
+  const isBlocked = embedStatus === "blocked" || embedStatus === "error";
+
+  const blockReason = useMemo(() => embedContext, [embedContext]);

  return {
    embedStatus,
+    setEmbedStatus,
+    resetEmbedStatus,
+    retry,
+    iframeRef,
+    handleIframeLoad,
+    handleIframeError,
    isEmbedded,
    isBlocked,
    blockReason,
-    detectionMethod,
-    iframeRef,
-    resetEmbedStatus,
-    // Legacy aliases
-    setEmbedStatus,
-    embedContext: blockReason, // Alias for backward compatibility
-    retry,
-    handleIframeLoad,
-    handleIframeError,
-    resetEmbed: resetEmbedStatus,
+    embedContext,
  };
 }
-
-export const PREVIEW_EMBED_CONTEXT_MESSAGES = {
-  blocked: BLOCKED_CONTEXT,
-  error: ERROR_CONTEXT,
-  timeout: TIMEOUT_CONTEXT,
-} as const;
--- a/plugins/fusion-plugin-hermes-runtime/README.md
+++ b/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
--- a/plugins/fusion-plugin-hermes-runtime/manifest.json
+++ b/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"
+  }
+}
--- a/plugins/fusion-plugin-hermes-runtime/package.json
+++ b/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"
+  }
+}
--- a/plugins/fusion-plugin-hermes-runtime/src/tests/index.test.ts
+++ b/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");
+    });
+  });
+});
--- a/plugins/fusion-plugin-hermes-runtime/src/index.ts
+++ b/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 };
--- a/plugins/fusion-plugin-hermes-runtime/tsconfig.json
+++ b/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/**/*"]
+}
--- a/plugins/fusion-plugin-hermes-runtime/vitest.config.ts
+++ b/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 } },
+  },
+});
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -471,7 +471,7 @@ importers:
        specifier: ^3.2.4
        version: 3.2.4(@types/debug@4.1.13)(@types/node@25.5.2)(jiti@2.6.1)(jsdom@29.0.1)(tsx@4.21.0)(yaml@2.8.3)

-  plugins/fusion-plugin-paperclip-runtime:
+  plugins/fusion-plugin-hermes-runtime:
    dependencies:
      '@fusion/plugin-sdk':
        specifier: workspace:*
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,4 +1,4 @@
 packages:
  - "packages/*"
  - "plugins/examples/*"
-  - "plugins/fusion-plugin-paperclip-runtime"
+  - "plugins/fusion-plugin-hermes-runtime"