feat(FN-2477): add executable OpenClaw runtime adapter

- Replace deferred OpenClaw placeholder runtime with an executable adapter that creates sessions, prompts with fallback, describes models, and disposes safely
- Add a dedicated pi-module seam and local runtime contract types to decouple plugin compilation from engine internals while preserving runtime behavior
- Update OpenClaw plugin metadata, manifest/package descriptions, and README to reflect active execution support instead of deferred status
- Harden dashboard DevServerStore save flow against ENOENT temp-directory races and add regression coverage for project-directory removal during save

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

@@ -1,5 +1,19 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+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, { openclawRuntimeMetadata, openclawRuntimeFactory, OPENCLAW_RUNTIME_ID } from "../index.js";
+import { OpenClawRuntimeAdapter } from "../runtime-adapter.js";
 
 interface MockLogger {
   info: ReturnType<typeof vi.fn>;
@@ -61,7 +75,7 @@ describe("openclaw-runtime plugin", () => {
       expect(plugin.runtime).toBeDefined();
       expect(plugin.runtime?.metadata.runtimeId).toBe(OPENCLAW_RUNTIME_ID);
       expect(plugin.runtime?.metadata.name).toBe("OpenClaw Runtime");
-      expect(plugin.runtime?.metadata.description).toContain("execution deferred");
+      expect(plugin.runtime?.metadata.description).toContain("OpenClaw-backed AI session");
       expect(plugin.runtime?.metadata.version).toBe("0.1.0");
     });
 
@@ -76,13 +90,10 @@ describe("openclaw-runtime plugin", () => {
       const ctx = createMockContext();
       await plugin.hooks.onLoad?.(ctx as any);
 
-      expect(ctx.logger.info).toHaveBeenCalledWith(
-        expect.stringContaining("OpenClaw Runtime Plugin loaded"),
-      );
+      expect(ctx.logger.info).toHaveBeenCalledWith("OpenClaw Runtime Plugin loaded");
       expect(ctx.emitEvent).toHaveBeenCalledWith("openclaw-runtime:loaded", {
         runtimeId: OPENCLAW_RUNTIME_ID,
         version: "0.1.0",
-        status: "deferred",
       });
     });
 
@@ -91,34 +102,27 @@ describe("openclaw-runtime plugin", () => {
     });
   });
 
-  describe("deferred runtime behavior", () => {
+  describe("runtime factory behavior", () => {
     it("should export runtime constants", () => {
       expect(OPENCLAW_RUNTIME_ID).toBe("openclaw");
       expect(openclawRuntimeMetadata.runtimeId).toBe("openclaw");
       expect(typeof openclawRuntimeFactory).toBe("function");
     });
 
-    it("runtime factory should return placeholder runtime shape", () => {
-      const runtime = openclawRuntimeFactory(createMockContext() as any) as Record<string, unknown>;
+    it("runtime factory should return executable runtime adapter", async () => {
+      const runtime = (await openclawRuntimeFactory(createMockContext() as any)) as OpenClawRuntimeAdapter;
 
-      expect(runtime).toMatchObject({
-        runtimeId: "openclaw",
-        version: "0.1.0",
-        status: "deferred",
-      });
-      expect(runtime).toHaveProperty("message");
-      expect(String(runtime.message)).toContain("discovery and configuration only");
-      expect(String(runtime.message)).not.toContain("FN-");
+      expect(runtime).toBeInstanceOf(OpenClawRuntimeAdapter);
+      expect(runtime.id).toBe("openclaw");
+      expect(runtime.name).toBe("OpenClaw Runtime");
+      expect(runtime).not.toHaveProperty("status");
+      expect(runtime).not.toHaveProperty("execute");
     });
 
-    it("runtime execute should reject with deferred/not-implemented error", async () => {
-      const runtime = openclawRuntimeFactory(createMockContext() as any) as { execute: () => Promise<never> };
-      await expect(runtime.execute()).rejects.toThrow("not implemented");
-      await expect(runtime.execute()).rejects.toThrow("deferred");
-    });
-
-    it("factory creation should not throw", () => {
-      expect(() => openclawRuntimeFactory(createMockContext() as any)).not.toThrow();
+    it("factory creation should not throw", async () => {
+      await expect(openclawRuntimeFactory(createMockContext() as any)).resolves.toBeInstanceOf(
+        OpenClawRuntimeAdapter,
+      );
     });
   });
 });

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

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { OpenClawRuntimeAdapter } 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("OpenClawRuntimeAdapter", () => {
+  let adapter: OpenClawRuntimeAdapter;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockDescribeModel.mockReturnValue("mock/anthropic-claude");
+    adapter = new OpenClawRuntimeAdapter();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("has stable runtime identity", () => {
+    expect(adapter.id).toBe("openclaw");
+    expect(adapter.name).toBe("OpenClaw 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-openclaw-runtime/src/index.ts

@@ -1,14 +1,14 @@
 /**
  * OpenClaw Runtime Plugin
  *
- * Registers an experimental OpenClaw runtime with Fusion's plugin runtime
- * discovery pipeline. Runtime execution behavior is intentionally deferred.
+ * Provides an executable OpenClaw runtime adapter for Fusion's plugin runtime
+ * discovery and session execution pipeline.
  */
 
 import { definePlugin } from "@fusion/plugin-sdk";
+import { OpenClawRuntimeAdapter } from "./runtime-adapter.js";
 import type {
   FusionPlugin,
-  PluginContext,
   PluginRuntimeFactory,
   PluginRuntimeManifestMetadata,
 } from "@fusion/plugin-sdk";
@@ -19,23 +19,12 @@ const OPENCLAW_RUNTIME_VERSION = "0.1.0";
 const openclawRuntimeMetadata: PluginRuntimeManifestMetadata = {
   runtimeId: OPENCLAW_RUNTIME_ID,
   name: "OpenClaw Runtime",
-  description: "Experimental OpenClaw runtime integration for Fusion tasks (execution deferred)",
+  description: "OpenClaw-backed AI session using the user's configured pi provider and model",
   version: OPENCLAW_RUNTIME_VERSION,
 };
 
-const openclawRuntimeFactory: PluginRuntimeFactory = (_ctx: PluginContext) => {
-  return {
-    runtimeId: OPENCLAW_RUNTIME_ID,
-    version: OPENCLAW_RUNTIME_VERSION,
-    status: "deferred",
-    message:
-      "OpenClaw runtime execution is currently deferred. This runtime is registered for discovery and configuration only.",
-    execute: async () => {
-      throw new Error(
-        "OpenClaw runtime is not implemented yet. Runtime discovery and configuration are supported, but execution is deferred.",
-      );
-    },
-  };
+const openclawRuntimeFactory: PluginRuntimeFactory = async () => {
+  return new OpenClawRuntimeAdapter();
 };
 
 const plugin: FusionPlugin = definePlugin({
@@ -43,7 +32,7 @@ const plugin: FusionPlugin = definePlugin({
     id: "fusion-plugin-openclaw-runtime",
     name: "OpenClaw Runtime Plugin",
     version: "0.1.0",
-    description: "OpenClaw runtime plugin for Fusion with experimental deferred execution",
+    description: "Provides OpenClaw runtime for Fusion AI agents",
     author: "Fusion Team",
     homepage: "https://github.com/gsxdsm/fusion",
     runtime: openclawRuntimeMetadata,
@@ -51,11 +40,10 @@ const plugin: FusionPlugin = definePlugin({
   state: "installed",
   hooks: {
     onLoad: (ctx) => {
-      ctx.logger.info("OpenClaw Runtime Plugin loaded (experimental placeholder runtime)");
+      ctx.logger.info("OpenClaw Runtime Plugin loaded");
       ctx.emitEvent("openclaw-runtime:loaded", {
         runtimeId: OPENCLAW_RUNTIME_ID,
         version: OPENCLAW_RUNTIME_VERSION,
-        status: "deferred",
       });
     },
     onUnload: () => {
@@ -70,4 +58,4 @@ const plugin: FusionPlugin = definePlugin({
 
 export default plugin;
 
-export { openclawRuntimeMetadata, openclawRuntimeFactory, OPENCLAW_RUNTIME_ID };
+export { openclawRuntimeMetadata, openclawRuntimeFactory, OPENCLAW_RUNTIME_ID };

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

@@ -0,0 +1,44 @@
+/**
+ * Pi Module Seam
+ *
+ * Provides a mockable import path for pi functions used by the OpenClawRuntimeAdapter.
+ */
+
+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-openclaw-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 OpenClawRuntimeAdapter implements AgentRuntime {
+  readonly id = "openclaw";
+  readonly name = "OpenClaw 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-openclaw-runtime/src/types.ts

@@ -0,0 +1,47 @@
+/**
+ * OpenClaw 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>;
+}