Crate cortex_sdk 

Cortex SDK

The official SDK for building Cortex plugins.

This crate defines the public plugin surface with zero dependency on Cortex internals. The runtime loads plugins via FFI and bridges these traits to its own turn runtime, command surface, and transport layer.

Architecture

 ┌──────────────┐     dlopen      ┌──────────────────┐
 │ cortex-runtime│ ──────────────▶ │  your plugin.so  │
 │   (daemon)    │                 │  cortex-sdk only  │
 └──────┬───────┘   FFI call      └────────┬─────────┘
        │        cortex_plugin_              │
        │        create_multi()              │
        ▼                                    ▼
   ToolRegistry  ◀─── register ───  MultiToolPlugin
                                    ├─ plugin_info()
                                    └─ create_tools()
                                        ├─ Tool A
                                        └─ Tool B

Plugins are compiled as cdylib shared libraries. The runtime calls a single FFI entry point (cortex_plugin_create_multi) that returns a MultiToolPlugin trait object. Each tool returned by MultiToolPlugin::create_tools is registered into the global tool registry and becomes available to the LLM during turns.

The SDK now exposes a runtime-aware execution surface as well:

• InvocationContext gives tools stable metadata such as session id, canonical actor, transport/source, and foreground/background scope
• ToolRuntime lets tools emit progress updates and observer text back to the parent turn
• ToolCapabilities lets tools declare whether they emit runtime signals and whether they are background-safe
• Attachment and ToolResult::with_media let tools return structured image, audio, video, or file outputs without depending on Cortex internals

Quick Start

Cargo.toml:

[lib]
crate-type = ["cdylib"]

[dependencies]
cortex-sdk = "1.0"
serde_json = "1"

src/lib.rs:

use cortex_sdk::prelude::*;

// 1. Define the plugin entry point.
#[derive(Default)]
struct MyPlugin;

impl MultiToolPlugin for MyPlugin {
    fn plugin_info(&self) -> PluginInfo {
        PluginInfo {
            name: "my-plugin".into(),
            version: env!("CARGO_PKG_VERSION").into(),
            description: "My custom tools for Cortex".into(),
        }
    }

    fn create_tools(&self) -> Vec<Box<dyn Tool>> {
        vec![Box::new(WordCountTool)]
    }
}

// 2. Implement one or more tools.
struct WordCountTool;

impl Tool for WordCountTool {
    fn name(&self) -> &'static str { "word_count" }

    fn description(&self) -> &'static str {
        "Count words in a text string. Use when the user asks for word \
         counts, statistics, or text length metrics."
    }

    fn input_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "description": "The text to count words in"
                }
            },
            "required": ["text"]
        })
    }

    fn execute(&self, input: serde_json::Value) -> Result<ToolResult, ToolError> {
        let text = input["text"]
            .as_str()
            .ok_or_else(|| ToolError::InvalidInput("missing 'text' field".into()))?;
        let count = text.split_whitespace().count();
        Ok(ToolResult::success(format!("{count} words")))
    }
}

// 3. Export the FFI entry point.
cortex_sdk::export_plugin!(MyPlugin);

Tools that need runtime context can override Tool::execute_with_runtime instead of only Tool::execute.

Build & Install

cargo build --release
mkdir -p my-plugin/lib
cp target/release/libmy_plugin.so my-plugin/lib/     # .dylib on macOS
cortex plugin install ./my-plugin/

Plugin Lifecycle

1. Load — dlopen at daemon startup
2. Create — runtime calls export_plugin!-generated FFI function
3. Register — MultiToolPlugin::create_tools is called once; each Tool is registered in the global tool registry
4. Execute — the LLM invokes tools by name during turns; the runtime calls Tool::execute with JSON parameters
5. Retain — the library handle is held for the daemon’s lifetime; Drop runs only at shutdown

Tool Design Guidelines

• name: lowercase with underscores (word_count, not WordCount). Must be unique across all tools in the registry.
• description: written for the LLM — explain what the tool does, when to use it, and when not to use it. The LLM reads this to decide whether to call the tool.
• input_schema: a JSON Schema object describing the parameters. The LLM generates JSON matching this schema.
• execute: receives the LLM-generated JSON. Return ToolResult::success for normal output or ToolResult::error for recoverable errors the LLM should see. Return ToolError only for unrecoverable failures (invalid input, missing deps).
• Media output: attach files with ToolResult::with_media. Cortex delivers attachments through the active transport; plugins should not call channel-specific APIs directly.
• execute_with_runtime: use this when the tool needs invocation metadata or wants to emit progress / observer updates during execution.
• timeout_secs: optional per-tool timeout override. If None, the global [turn].tool_timeout_secs applies.

Re-exports

pub use serde_json;

Modules

prelude

Convenience re-exports for plugin development.

Macros

export_plugin

Generate the FFI entry point for a MultiToolPlugin.

Structs

Attachment

Stable multimedia attachment DTO exposed to plugins.

InvocationContext

Stable runtime metadata exposed to plugin tools during execution.

PluginInfo

Plugin metadata returned to the runtime at load time.

ToolCapabilities

Declarative hints about how a tool participates in the runtime.

ToolResult

Result of a tool execution returned to the LLM.

Enums

ExecutionScope

Whether a tool invocation belongs to a user-visible foreground turn or a background maintenance execution.

ToolError

Error from tool execution.

Traits

MultiToolPlugin

A plugin that provides multiple tools from a single shared library.

Tool

A tool that the LLM can invoke during conversation.

ToolRuntime

Runtime bridge presented to tools during execution.