@fractal-os/plugin

The official developer SDK and plugin toolkit for the Fractal AIOS (Artificial Intelligence Operating System).

Build, extend, and publish autonomous agent capabilities, persistent schemas, user interface panels, custom error diagnostics, and system hook interceptions with ease.

Key Features

• 🛠️ FractalTool: Fluent builder to define cognitive inputs, schemas, and asynchronous execution logic for AI agents.
• 🔌 FractalToolset: Group related tools under connection configurations (REST, Model Context Protocol standard stdio/http, CLI).
• 🗄️ FractalCollection: Define reactive data persistence schemas with built-in lifetime event hooks (onCreated, onUpdated, onDeleted).
• 🖥️ FractalView: Construct beautiful, reactive UI trees and panels directly inside the active user workspace.
• 🚦 FractalHook: Intercept, inspect, and modify pipeline events (e.g. PreToolUse, SessionStart) to audit or control agent behavior.
• 🚨 FractalError: Dynamic custom error registries complete with actionable Call-To-Action (CTA) suggestions for both developers and agents.

Installation

Add the SDK as a peer or runtime dependency in your project:

# Using bun (Recommended)
bun add @fractal-os/plugin

# Using npm
npm install @fractal-os/plugin

# Using pnpm
pnpm add @fractal-os/plugin

Core Builders Usage

1. Defining a Tool (FractalTool)

Tools represent callable actions that AI agents can run to interact with the system or external APIs.

import { z } from "zod";
import { FractalTool } from "@fractal-os/plugin";

const GreetSchema = z.object({
  name: z.string().describe("The name of the user to greet")
});

export default FractalTool.create("greet")
  .withDescription("Greets a user by name professionally")
  .withSchema(GreetSchema)
  .withHandler(async ({ input, fractal }) => {
    return `Hello, ${input.name}! Welcome to the Fractal AIOS.`;
  });

2. Grouping Tools in a Toolset (FractalToolset)

Toolsets define connections (e.g., standard Model Context Protocol servers) and hold groups of tools.

import { FractalToolset } from "@fractal-os/plugin";
import greetTool from "./greet.tool";

export default FractalToolset.create("standard-utilities")
  .withDescription("A set of essential workspace helper tools")
  .withConnection({ type: "custom" })
  .addTool(greetTool);

3. Creating a Collection (FractalCollection)

Collections represent local files or records modeled after a specific schema with reactive life-cycle hooks.

import { z } from "zod";
import { FractalCollection } from "@fractal-os/plugin";

const UserSchema = z.object({
  id: z.string(),
  username: z.string(),
  role: z.enum(["admin", "developer", "user"])
});

export default FractalCollection.create("users")
  .withSchema(UserSchema)
  .withPatterns(["users/*.json"])
  .onCreated(async (ctx) => {
    console.log(`User ${ctx.data.username} has been persisted in workspace: ${ctx.workspace.config.name}`);
  });

4. Creating a Workspace View (FractalView)

Views render custom visual trees, statistics metrics, and interactive buttons directly inside the user's sidebar or main viewport.

import { FractalView } from "@fractal-os/plugin";

export default FractalView.create("recent-activities")
  .withTitle("Recent Activities")
  .withDescription("Displays recent actions performed in the active workspace")
  .withData(async (ctx) => {
    const logPath = ctx.workspace.path("workspace", "logs", "activity.json");
    // Retrieve metrics list ...
    return {
      items: [
        { id: "1", title: "Configured plugin", status: "success" }
      ],
      stats: {
        total: 1
      }
    };
  });

5. Intercepting Events with Hooks (FractalHook)

Hooks intercept operations on the OS pipeline, allowing you to run safety checks or modify results.

import { FractalHook } from "@fractal-os/plugin";

export default FractalHook.create("sandbox-safety-guard")
  .onType("PreToolUse")
  .withHandler(async (event) => {
    const cmd = event.input.toolInput?.command || "";
    if (cmd.includes("rm -rf")) {
      throw new Error("Destructive terminal commands are forbidden in this workspace.");
    }
    return event.output;
  });

6. Dynamic Custom Errors (FractalError)

Define diagnostic error codes with actionable Call-To-Action buttons that both developers and agents can execute.

import { z } from "zod";
import { FractalError } from "@fractal-os/plugin";

const MissingEnvSchema = z.object({ key: z.string() });

export const WorkspaceErrors = FractalError.create()
  .addError("ENV_VARIABLE_MISSING", {
    status: 400,
    schema: MissingEnvSchema,
    message: ({ issue }) => `Required environment variable "${issue?.key}" is not set.`,
    cta: ({ issue }) => ({
      description: "Set the missing environment variable in your config.",
      commands: [
        {
          command: `fractal config set ${issue?.key}="<value>"`,
          description: "Configure the environment key"
        }
      ]
    })
  })
  .build();

Contributing & Development

To build the plugin SDK locally:

# Install dependencies
bun install

# Build CJS, ESM, and DTS typings
bun run build

License

This package is licensed under the public MIT License.