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

- feat(FN-2262): document Paperclip runtime configuration and constraints
- docs(FN-2261): update README with implementation details
- feat(FN-2261): add paperclip runtime resolution compatibility tests
- feat(FN-2261): add runtime adapter and registration tests
- feat(FN-2261): integrate adapter into plugin entrypoint
- feat(FN-2261): implement PaperclipRuntimeAdapter
- fix(FN-2261): remove pi-coding-agent re-exports from types.ts
- feat(FN-2261): define runtime types for Paperclip plugin
- feat(FN-2260): merge fusion/fn-2260

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

@@ -1,5 +1,6 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import plugin from "../index.js";
+import { PaperclipRuntimeAdapter } from "../runtime-adapter.js";
 
 // ── Test Suite ─────────────────────────────────────────────────────────────────
 
@@ -8,9 +9,9 @@ describe("paperclip-runtime plugin", () => {
     it("should export a valid FusionPlugin with correct manifest fields", () => {
       expect(plugin.manifest.id).toBe("fusion-plugin-paperclip-runtime");
       expect(plugin.manifest.name).toBe("Paperclip Runtime Plugin");
-      expect(plugin.manifest.version).toBe("0.1.0");
+      expect(plugin.manifest.version).toBe("1.0.0");
       expect(plugin.manifest.description).toBe(
-        "Provides Paperclip web access runtime for Fusion AI agents",
+        "Provides Paperclip runtime for Fusion AI agents",
       );
       expect(plugin.manifest.author).toBe("Fusion Team");
       expect(plugin.state).toBe("installed");
@@ -20,7 +21,7 @@ describe("paperclip-runtime plugin", () => {
       expect(plugin.manifest.runtime).toBeDefined();
       expect(plugin.manifest.runtime!.runtimeId).toBe("paperclip");
       expect(plugin.manifest.runtime!.name).toBe("Paperclip Runtime");
-      expect(plugin.manifest.runtime!.version).toBe("0.1.0");
+      expect(plugin.manifest.runtime!.version).toBe("1.0.0");
     });
 
     it("should have fusionVersion requirement", () => {
@@ -28,7 +29,7 @@ describe("paperclip-runtime plugin", () => {
     });
   });
 
-  describe("runtime placeholder registration", () => {
+  describe("runtime registration", () => {
     it("should have runtime registration", () => {
       expect(plugin.runtime).toBeDefined();
     });
@@ -37,7 +38,10 @@ describe("paperclip-runtime plugin", () => {
       const runtime = plugin.runtime!;
       expect(runtime.metadata.runtimeId).toBe("paperclip");
       expect(runtime.metadata.name).toBe("Paperclip Runtime");
-      expect(runtime.metadata.version).toBe("0.1.0");
+      expect(runtime.metadata.description).toBe(
+        "Paperclip-backed AI session using the user's configured pi provider and model",
+      );
+      expect(runtime.metadata.version).toBe("1.0.0");
     });
 
     it("should have a factory function", () => {
@@ -46,25 +50,32 @@ describe("paperclip-runtime plugin", () => {
     });
   });
 
-  describe("runtime placeholder invocation", () => {
-    it("should throw deterministic error with FN-2261 reference when factory is invoked", async () => {
-      const factory = plugin.runtime!.factory;
-
-      await expect(factory({} as any)).rejects.toThrow(
-        "Paperclip runtime implementation is deferred to FN-2261",
-      );
+  describe("runtime factory invocation", () => {
+    beforeEach(() => {
+      // Mock @fusion/engine for createFnAgent
+      vi.mock("@fusion/engine", () => ({
+        createFnAgent: vi.fn().mockResolvedValue({ session: {} }),
+        promptWithFallback: vi.fn(),
+      }));
+      // Mock describeModel
+      vi.mock("../../engine/src/pi.js", () => ({
+        describeModel: vi.fn().mockReturnValue("mock/model"),
+      }));
     });
 
-    it("should throw error with placeholder message in the error text", async () => {
-      const factory = plugin.runtime!.factory;
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
 
-      try {
-        await factory({} as any);
-        expect.fail("Expected factory to throw an error");
-      } catch (error) {
-        expect((error as Error).message).toContain("placeholder");
-        expect((error as Error).message).toContain("FN-2261");
-      }
+    it("should return a PaperclipRuntimeAdapter instance when factory is invoked", async () => {
+      const runtime = await plugin.runtime!.factory({} as any);
+      expect(runtime).toBeInstanceOf(PaperclipRuntimeAdapter);
+    });
+
+    it("should return an adapter with correct id and name", async () => {
+      const runtime = await plugin.runtime!.factory({} as any);
+      expect(runtime.id).toBe("paperclip");
+      expect(runtime.name).toBe("Paperclip Runtime");
     });
   });
 
@@ -91,5 +102,25 @@ describe("paperclip-runtime plugin", () => {
 
       expect(() => plugin.hooks.onLoad!(mockCtx as any)).not.toThrow();
     });
+
+    it("onLoad should call logger.info", () => {
+      const mockLogger = {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+      };
+      const mockCtx = {
+        pluginId: "fusion-plugin-paperclip-runtime",
+        settings: {},
+        logger: mockLogger,
+        emitEvent: () => {},
+        taskStore: {},
+      };
+
+      plugin.hooks.onLoad!(mockCtx as any);
+
+      expect(mockLogger.info).toHaveBeenCalledWith("Paperclip Runtime Plugin loaded");
+    });
   });
 });

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

@@ -0,0 +1,206 @@
+/**
+ * Runtime Adapter Tests
+ *
+ * Tests for the PaperclipRuntimeAdapter class.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { PaperclipRuntimeAdapter } from "../runtime-adapter.js";
+
+// ── Mock Modules ────────────────────────────────────────────────────────────────
+
+// Mock @fusion/engine for createFnAgent and promptWithFallback
+const mockCreateFnAgent = vi.fn();
+const mockPromptWithFallback = vi.fn();
+
+vi.mock("@fusion/engine", () => ({
+  createFnAgent: mockCreateFnAgent,
+  promptWithFallback: mockPromptWithFallback,
+}));
+
+// Mock the relative import of describeModel from pi.ts
+// This uses require() in the adapter, so we mock the entire module
+vi.mock("../../engine/src/pi.js", () => ({
+  describeModel: vi.fn().mockReturnValue("mock/anthropic-claude"),
+}));
+
+// ── Test Suite ─────────────────────────────────────────────────────────────────
+
+describe("PaperclipRuntimeAdapter", () => {
+  let adapter: PaperclipRuntimeAdapter;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    adapter = new PaperclipRuntimeAdapter();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("runtime identity", () => {
+    it("should have id 'paperclip'", () => {
+      expect(adapter.id).toBe("paperclip");
+    });
+
+    it("should have name 'Paperclip Runtime'", () => {
+      expect(adapter.name).toBe("Paperclip Runtime");
+    });
+  });
+
+  describe("createSession", () => {
+    it("should call createFnAgent with correct options", async () => {
+      const mockSession = { dispose: vi.fn() };
+      const mockResult = { session: mockSession, sessionFile: "/path/to/session.json" };
+      mockCreateFnAgent.mockResolvedValue(mockResult);
+
+      const options = {
+        cwd: "/project",
+        systemPrompt: "You are helpful",
+        skills: ["bash", "read"],
+      };
+
+      const result = await adapter.createSession(options);
+
+      expect(mockCreateFnAgent).toHaveBeenCalledTimes(1);
+      expect(mockCreateFnAgent).toHaveBeenCalledWith({
+        cwd: "/project",
+        systemPrompt: "You are helpful",
+        tools: undefined,
+        customTools: undefined,
+        onText: undefined,
+        onThinking: undefined,
+        onToolStart: undefined,
+        onToolEnd: undefined,
+        defaultProvider: undefined,
+        defaultModelId: undefined,
+        fallbackProvider: undefined,
+        fallbackModelId: undefined,
+        defaultThinkingLevel: undefined,
+        sessionManager: undefined,
+        skillSelection: undefined,
+        skills: ["bash", "read"],
+      });
+      expect(result.session).toBe(mockSession);
+      expect(result.sessionFile).toBe("/path/to/session.json");
+    });
+
+    it("should pass through model options", async () => {
+      mockCreateFnAgent.mockResolvedValue({ session: {} });
+
+      await adapter.createSession({
+        cwd: "/project",
+        systemPrompt: "Test",
+        defaultProvider: "anthropic",
+        defaultModelId: "claude-sonnet-4-5",
+        fallbackProvider: "openai",
+        fallbackModelId: "gpt-4o",
+      });
+
+      expect(mockCreateFnAgent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          defaultProvider: "anthropic",
+          defaultModelId: "claude-sonnet-4-5",
+          fallbackProvider: "openai",
+          fallbackModelId: "gpt-4o",
+        }),
+      );
+    });
+
+    it("should pass through custom tools", async () => {
+      mockCreateFnAgent.mockResolvedValue({ session: {} });
+      const customTools = [{ name: "custom_tool", execute: vi.fn() }];
+
+      await adapter.createSession({
+        cwd: "/project",
+        systemPrompt: "Test",
+        customTools,
+      });
+
+      expect(mockCreateFnAgent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          customTools,
+        }),
+      );
+    });
+
+    it("should pass through skill selection context", async () => {
+      mockCreateFnAgent.mockResolvedValue({ session: {} });
+      const skillSelection = {
+        projectRootDir: "/project",
+        requestedSkillNames: ["bash"],
+        sessionPurpose: "executor" as const,
+      };
+
+      await adapter.createSession({
+        cwd: "/project",
+        systemPrompt: "Test",
+        skillSelection,
+      });
+
+      expect(mockCreateFnAgent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          skillSelection,
+        }),
+      );
+    });
+  });
+
+  describe("promptWithFallback", () => {
+    it("should delegate to promptWithFallback from engine", async () => {
+      const mockSession = { id: "test-session" };
+      mockPromptWithFallback.mockResolvedValue(undefined);
+
+      await adapter.promptWithFallback(mockSession as any, "Hello", { images: [] });
+
+      expect(mockPromptWithFallback).toHaveBeenCalledTimes(1);
+      expect(mockPromptWithFallback).toHaveBeenCalledWith(mockSession, "Hello", { images: [] });
+    });
+
+    it("should work without options", async () => {
+      mockPromptWithFallback.mockResolvedValue(undefined);
+
+      await adapter.promptWithFallback({} as any, "Hello");
+
+      expect(mockPromptWithFallback).toHaveBeenCalledWith({}, "Hello", undefined);
+    });
+  });
+
+  describe("describeModel", () => {
+    it("should return model description from pi describeModel", () => {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { describeModel } = require("../../engine/src/pi.js");
+
+      const mockSession = { model: { provider: "anthropic", id: "claude-sonnet-4-5" } };
+      const result = adapter.describeModel(mockSession as any);
+
+      expect(describeModel).toHaveBeenCalledWith(mockSession);
+      expect(result).toBe("mock/anthropic-claude"); // from mock
+    });
+  });
+
+  describe("dispose", () => {
+    it("should call session.dispose() when available", async () => {
+      const disposeMock = vi.fn().mockResolvedValue(undefined);
+      const mockSession = { dispose: disposeMock } as any;
+
+      await adapter.dispose(mockSession);
+
+      expect(disposeMock).toHaveBeenCalledTimes(1);
+    });
+
+    it("should be a no-op when session has no dispose method", async () => {
+      const mockSession = { id: "test" } as any;
+
+      // Should not throw
+      await expect(adapter.dispose(mockSession)).resolves.toBeUndefined();
+    });
+
+    it("should handle dispose that throws", async () => {
+      const disposeMock = vi.fn().mockRejectedValue(new Error("Dispose failed"));
+      const mockSession = { dispose: disposeMock } as any;
+
+      await expect(adapter.dispose(mockSession)).rejects.toThrow("Dispose failed");
+    });
+  });
+});