Extensions

Extension Manager
├── Loader           ── Discovery, manifest parsing, validation
├── Registry         ── Plugin registration, tool lookup, status tracking
├── Watcher          ── Hot reload on file changes
└── Plugin Runtimes
    ├── WASM Runtime (Extism)  ── Sandboxed, fast startup, limited I/O
    └── Node.js Runtime (IPC)  ── Full Node.js API, stdio communication

~/.aleph/plugins/my-plugin/
├── aleph_plugin.toml    # Plugin manifest (required)
├── dist/
│   └── index.js         # Entry point (Node.js)
├── src/
│   └── index.ts         # Source code
├── SKILL.md             # Optional prompt file
└── docs/
    └── INSTRUCTIONS.md  # Optional tool-specific instructions

[plugin]
id = "my-plugin"                    # Unique identifier
name = "My Plugin"                  # Display name
version = "1.0.0"                   # SemVer version
description = "Does something useful"
author = "Your Name"
kind = "nodejs"                     # nodejs | wasm | static
entry = "dist/index.js"            # Entry point for nodejs/wasm

[permissions]
network = ["connect:https://*"]     # Network access rules
filesystem = ["read:./data", "write:./output"]
env = ["API_KEY", "DEBUG"]          # Allowed environment variables

[prompt]
file = "SKILL.md"                   # Prompt file path
scope = "system"                    # system | tool | standalone | disabled

[[tools]]
name = "my_tool"
description = "Performs a specific task"
handler = "handleMyTool"
instruction_file = "docs/INSTRUCTIONS.md"

[[tools]]
name = "another_tool"
description = "Another useful tool"
handler = "handleAnotherTool"

[[hooks]]
event = "before_tool_call"
kind = "interceptor"                # interceptor | observer | resolver
priority = "normal"                 # system | high | normal | low
handler = "onBeforeTool"

[[hooks]]
event = "after_tool_call"
kind = "observer"
priority = "low"
handler = "onAfterTool"

pub struct WasmRuntime {
    plugins: HashMap<String, ExtismPlugin>,
}

impl WasmRuntime {
    pub fn load(&mut self, path: &Path) -> Result<()>;
    pub fn call(&self, plugin: &str, function: &str, input: &[u8])
        -> Result<Vec<u8>>;
}

use extism_pdk::*;

#[plugin_fn]
pub fn my_tool(input: String) -> FnResult<String> {
    let args: serde_json::Value = serde_json::from_str(&input)?;
    let result = process(args);
    Ok(serde_json::to_string(&result)?)
}

[extensions.runtimes.wasm]
enabled = true
memory_limit = "256MB"
timeout_ms = 30000

pub struct NodejsRuntime {
    processes: HashMap<String, Child>,
}

impl NodejsRuntime {
    pub async fn start(&mut self, plugin: &PluginManifest) -> Result<()>;
    pub async fn call(&self, plugin: &str, method: &str, args: Value)
        -> Result<Value>;
}

import { createServer } from '@aleph/plugin-sdk';

const server = createServer({
  name: 'my-plugin',
  tools: {
    my_tool: async (args: { input: string }) => {
      return { result: `Processed: ${args.input}` };
    },
    another_tool: async (args: { query: string }) => {
      const response = await fetch(`https://api.example.com?q=${args.query}`);
      return response.json();
    }
  }
});

server.start();

Plugin Directory Found
    │
    ▼
1. Parse manifest (aleph_plugin.toml)
    │
    ▼
2. Validate manifest
   • Required fields present
   • Version compatibility
   • No tool name conflicts
    │
    ▼
3. Select runtime
   WASM → WasmRuntime
   Node.js → NodejsRuntime
   Static → No runtime needed
    │
    ▼
4. Register tools in ToolServer
    │
    ▼
Plugin Ready

pub enum PluginStatus {
    Loaded,      // Manifest parsed, not yet started
    Running,     // Runtime active, tools available
    Stopped,     // Manually stopped
    Error(String), // Failed to start or crashed
}

// Interceptor: can modify or block
async function onBeforeTool(context: HookContext): Promise<HookContext> {
  if (context.toolName === 'dangerous_tool') {
    throw new Error('Tool blocked by security policy');
  }
  context.args.timestamp = Date.now();
  return context;
}

// Observer: fire-and-forget
async function onAfterTool(context: HookContext): Promise<void> {
  console.log(`Tool ${context.toolName} executed in ${context.duration}ms`);
}

// Resolver: first-win
async function resolveConfig(context: HookContext): Promise<Config | null> {
  if (context.key in myConfigs) {
    return myConfigs[context.key];  // Wins, stops chain
  }
  return null;  // Continue to next resolver
}

[[commands]]
name = "ping"
description = "Check if the plugin is responsive"
handler = "handlePing"

[[commands]]
name = "status"
description = "Get current plugin status"
handler = "handleStatus"

[[services]]
name = "file-watcher"
description = "Watches filesystem for changes"
start_handler = "startFileWatcher"
stop_handler = "stopFileWatcher"
auto_start = true

[[services]]
name = "sync-daemon"
description = "Background sync service"
start_handler = "startSync"
stop_handler = "stopSync"
auto_start = false

[[channels]]
name = "slack"
description = "Slack workspace integration"
connect_handler = "connectSlack"
disconnect_handler = "disconnectSlack"
send_handler = "sendSlack"

[[providers]]
name = "local-llama"
description = "Local Llama.cpp server"
list_models_handler = "listModels"
chat_handler = "handleChat"
stream_handler = "handleStream"
embed_handler = "handleEmbed"

[[http_routes]]
method = "POST"
path = "/webhooks/github"
handler = "handleGithubWebhook"

[[http_routes]]
method = "GET"
path = "/api/status"
handler = "handleStatus"

pub struct PluginWatcher {
    watcher: RecommendedWatcher,
    registry: Arc<RwLock<PluginRegistry>>,
}

[extensions]
enabled = true
search_paths = ["~/.aleph/plugins", "./plugins"]
hot_reload = true

[extensions.runtimes.wasm]
enabled = true
memory_limit = "256MB"
timeout_ms = 30000

[extensions.runtimes.nodejs]
enabled = true
node_version = "20"