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

packages/engine/src/plugin-runner.test.ts

@@ -822,6 +822,98 @@ describe("PluginRunner", () => {
     });
   });
 
+  describe("Paperclip runtime compatibility", () => {
+    /**
+     * Verify that the paperclip runtime registration from
+     * plugins/fusion-plugin-paperclip-runtime is correctly resolvable
+     * through the engine's runtime resolution system.
+     */
+
+    it("should resolve paperclip runtime when registered", () => {
+      const paperclipRuntime = {
+        metadata: {
+          runtimeId: "paperclip",
+          name: "Paperclip Runtime",
+          description: "Paperclip-backed AI session using the user's configured pi provider and model",
+          version: "1.0.0",
+        },
+        factory: vi.fn().mockResolvedValue({}),
+      };
+      mockPluginLoader.getPluginRuntimes.mockReturnValue([
+        { pluginId: "fusion-plugin-paperclip-runtime", runtime: paperclipRuntime as any },
+      ]);
+
+      const result = pluginRunner.getRuntimeById("paperclip");
+      expect(result).toBeDefined();
+      expect(result?.pluginId).toBe("fusion-plugin-paperclip-runtime");
+      expect(result?.runtime.metadata.runtimeId).toBe("paperclip");
+      expect(result?.runtime.metadata.name).toBe("Paperclip Runtime");
+      expect(result?.runtime.metadata.description).toContain("Paperclip");
+      expect(result?.runtime.metadata.version).toBe("1.0.0");
+    });
+
+    it("should expose paperclip runtime metadata correctly", () => {
+      const paperclipRuntime = {
+        metadata: {
+          runtimeId: "paperclip",
+          name: "Paperclip Runtime",
+          description: "Paperclip-backed AI session using the user's configured pi provider and model",
+          version: "1.0.0",
+        },
+        factory: vi.fn().mockResolvedValue({}),
+      };
+      mockPluginLoader.getPluginRuntimes.mockReturnValue([
+        { pluginId: "fusion-plugin-paperclip-runtime", runtime: paperclipRuntime as any },
+      ]);
+
+      const runtimes = pluginRunner.getPluginRuntimes();
+      const paperclip = runtimes.find(r => r.runtime.metadata.runtimeId === "paperclip");
+
+      expect(paperclip).toBeDefined();
+      expect(paperclip?.runtime.metadata).toEqual({
+        runtimeId: "paperclip",
+        name: "Paperclip Runtime",
+        description: "Paperclip-backed AI session using the user's configured pi provider and model",
+        version: "1.0.0",
+      });
+    });
+
+    it("should allow factory invocation for paperclip runtime", async () => {
+      const mockAdapter = {
+        id: "paperclip",
+        name: "Paperclip Runtime",
+        createSession: vi.fn(),
+        promptWithFallback: vi.fn(),
+        describeModel: vi.fn(),
+        dispose: vi.fn(),
+      };
+      const paperclipRuntime = {
+        metadata: {
+          runtimeId: "paperclip",
+          name: "Paperclip Runtime",
+          description: "Paperclip-backed AI session using the user's configured pi provider and model",
+          version: "1.0.0",
+        },
+        factory: vi.fn().mockResolvedValue(mockAdapter),
+      };
+      mockPluginLoader.getPluginRuntimes.mockReturnValue([
+        { pluginId: "fusion-plugin-paperclip-runtime", runtime: paperclipRuntime as any },
+      ]);
+
+      const result = pluginRunner.getRuntimeById("paperclip");
+      expect(result).toBeDefined();
+
+      // Invoke the factory (simulating runtime instantiation)
+      const context = { pluginId: "fusion-plugin-paperclip-runtime" };
+      const runtime = await result!.runtime.factory(context as any);
+
+      expect(paperclipRuntime.factory).toHaveBeenCalledWith(context);
+      expect(runtime).toBe(mockAdapter);
+      expect(runtime.id).toBe("paperclip");
+      expect(runtime.name).toBe("Paperclip Runtime");
+    });
+  });
+
   describe("getLoader() / getStore()", () => {
     it("should return the plugin loader", () => {
       const loader = pluginRunner.getLoader();