@elizaos/plugin-agent-orchestrator 2.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# Agent Orchestrator Plugin
+
+Multi-language orchestration plugin for ElizaOS that manages task lifecycles and delegates execution to registered agent providers.
+
+## Overview
+
+This plugin provides:
+
+- **Task lifecycle management** — create, pause, resume, cancel tasks
+- **Provider-based execution model** — register custom agent providers that execute tasks
+- **Event system** — subscribe to task state changes
+- **Cross-platform parity** — TypeScript, Python, and Rust implementations with identical APIs
+
+The orchestrator does **not** perform file I/O directly. File operations, shell commands, and other implementation work are delegated to sub-agent workers configured via providers.
+
+## Implementations
+
+| Language   | Path                | Status |
+|------------|---------------------|--------|
+| TypeScript | `typescript/`       | ✅     |
+| Python     | `python/`           | ✅     |
+| Rust       | `rust/`             | ✅     |
+
+All implementations share the same:
+- Type definitions (TaskStatus, TaskStep, TaskResult, OrchestratedTask, etc.)
+- Service API (create, pause, resume, cancel, search, etc.)
+- Actions (CREATE_TASK, LIST_TASKS, SWITCH_TASK, SEARCH_TASKS, PAUSE_TASK, RESUME_TASK, CANCEL_TASK)
+- Provider interface (AgentProvider with executeTask)
+
+## Installation
+
+### TypeScript / Node.js
+
+```bash
+npm install @elizaos/plugin-agent-orchestrator
+```
+
+### Python
+
+```bash
+pip install elizaos-plugin-agent-orchestrator
+```
+
+### Rust
+
+```toml
+[dependencies]
+elizaos-plugin-agent-orchestrator = "2.0"
+```
+
+## Quick Start
+
+### TypeScript
+
+```typescript
+import {
+  agentOrchestratorPlugin,
+  configureAgentOrchestratorPlugin,
+} from "@elizaos/plugin-agent-orchestrator";
+
+// Define your agent provider
+const myProvider = {
+  id: "my-agent",
+  label: "My Agent",
+  executeTask: async (task, ctx) => {
+    await ctx.appendOutput("Hello from my-agent");
+    await ctx.updateProgress(100);
+    return { success: true, summary: "done", filesCreated: [], filesModified: [] };
+  },
+};
+
+// Configure before runtime.initialize()
+configureAgentOrchestratorPlugin({
+  providers: [myProvider],
+  defaultProviderId: "my-agent",
+  getWorkingDirectory: () => process.cwd(),
+});
+
+// Register plugin
+runtime.plugins.push(agentOrchestratorPlugin);
+```
+
+### Python
+
+```python
+from elizaos_plugin_agent_orchestrator import (
+    configure_agent_orchestrator_plugin,
+    AgentOrchestratorPluginOptions,
+    TaskResult,
+    plugin,
+)
+
+class MyProvider:
+    id = "my-agent"
+    label = "My Agent"
+    description = None
+
+    async def execute_task(self, task, ctx):
+        await ctx.append_output("Hello from my-agent")
+        await ctx.update_progress(100)
+        return TaskResult(success=True, summary="done")
+
+configure_agent_orchestrator_plugin(
+    AgentOrchestratorPluginOptions(
+        providers=[MyProvider()],
+        default_provider_id="my-agent",
+        get_working_directory=lambda: os.getcwd(),
+    )
+)
+
+runtime.register_plugin(plugin)
+```
+
+### Rust
+
+```rust
+use elizaos_plugin_agent_orchestrator::{
+    configure_agent_orchestrator_plugin,
+    AgentOrchestratorPluginOptions,
+    AgentProvider,
+    TaskResult,
+};
+use std::sync::Arc;
+
+struct MyProvider;
+
+#[async_trait::async_trait]
+impl AgentProvider for MyProvider {
+    fn id(&self) -> &str { "my-agent" }
+    fn label(&self) -> &str { "My Agent" }
+
+    async fn execute_task(&self, task: &OrchestratedTask, ctx: &ProviderTaskExecutionContext) -> TaskResult {
+        (ctx.append_output)("Hello from my-agent".to_string());
+        (ctx.update_progress)(100);
+        TaskResult::success("done")
+    }
+}
+
+configure_agent_orchestrator_plugin(
+    AgentOrchestratorPluginOptions::new(
+        vec![Arc::new(MyProvider)],
+        "my-agent",
+        || std::env::current_dir().unwrap().to_string_lossy().to_string(),
+    )
+);
+```
+
+## Actions
+
+| Action | Description |
+|--------|-------------|
+| `CREATE_TASK` | Create a new orchestrated task |
+| `LIST_TASKS` | List all tasks |
+| `SWITCH_TASK` | Switch current task context |
+| `SEARCH_TASKS` | Search tasks by query |
+| `PAUSE_TASK` | Pause a running task |
+| `RESUME_TASK` | Resume a paused task |
+| `CANCEL_TASK` | Cancel a task |
+
+## Task Lifecycle
+
+```
+pending → running → completed
+                 ↘ failed
+         ↓
+       paused → running (resume)
+         ↓
+      cancelled
+```
+
+## Provider Interface
+
+Providers implement task execution logic. The orchestrator calls `executeTask` when a task starts.
+
+```typescript
+interface AgentProvider {
+  id: string;              // Unique identifier
+  label: string;           // Human-readable name
+  description?: string;    // Optional description
+
+  executeTask(
+    task: OrchestratedTask,
+    ctx: ProviderTaskExecutionContext,
+  ): Promise<TaskResult>;
+}
+```
+
+### Execution Context
+
+The context provides callbacks for reporting progress:
+
+- `appendOutput(line)` — Add output to task history
+- `updateProgress(percent)` — Update progress (0-100)
+- `updateStep(stepId, status, output?)` — Update a plan step
+- `isCancelled()` — Check if task was cancelled
+- `isPaused()` — Check if task is paused
+
+### Suggested Provider IDs
+
+| ID | Description |
+|----|-------------|
+| `eliza` | Default Eliza worker with plugin-code |
+| `claude-code` | Claude Code / Claude Agent SDK |
+| `codex` | OpenAI Codex |
+| `sweagent` | SWE-agent methodology |
+| `opencode` | OpenCode CLI |
+| `custom:*` | Your custom providers |
+
+## Examples
+
+See `typescript/examples/` for:
+
+- **agent-team.ts** — Simple multi-agent team (planner, executor, reviewer)
+- **star-trek-bridge.ts** — Star Trek bridge crew simulation
+
+## Configuration
+
+Environment variable: `ELIZA_CODE_ACTIVE_SUB_AGENT`
+
+Set this to override the default provider for new tasks.
+
+## Building
+
+```bash
+# Build all languages
+bun run build
+
+# Build individual
+bun run build:ts
+bun run build:rust
+bun run build:python
+```
+
+## Testing
+
+```bash
+# Test all languages
+bun run test
+
+# Test individual
+bun run test:ts
+bun run test:rust
+bun run test:python
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@elizaos/plugin-agent-orchestrator",
+  "version": "2.0.0-alpha.1",
+  "description": "Agent orchestration plugin for ElizaOS (task lifecycle + agent providers) with multi-agent demos",
+  "type": "module",
+  "main": "typescript/dist/index.js",
+  "types": "typescript/dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./typescript/dist/index.d.ts",
+      "import": "./typescript/dist/index.js",
+      "default": "./typescript/dist/index.js"
+    }
+  },
+  "files": [
+    "typescript/dist",
+    "python",
+    "rust/src",
+    "rust/Cargo.toml",
+    "README.md"
+  ],
+  "keywords": [
+    "eliza",
+    "plugin",
+    "orchestrator",
+    "agents",
+    "tasks",
+    "multi-agent"
+  ],
+  "author": "elizaOS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elizaos/eliza.git"
+  },
+  "scripts": {
+    "build": "bun run build:ts && bun run build:rust && bun run build:python",
+    "build:ts": "cd typescript && bun run build.ts",
+    "build:rust": "test -d rust && cd rust && cargo build --release || echo 'Rust build skipped - no rust directory'",
+    "build:python": "test -d python && cd python && (python3 -m build 2>/dev/null || pyproject-build) || echo 'Python build skipped - no python directory'",
+    "dev": "cd typescript && bun --hot build.ts",
+    "clean": "rm -rf typescript/dist python/dist rust/target .turbo node_modules",
+    "test": "bun run test:ts && bun run test:rust && bun run test:python",
+    "test:ts": "cd typescript && vitest run || echo 'TypeScript tests skipped - no tests found'",
+    "test:rust": "test -d rust && cd rust && cargo test -- --test-threads=1 || echo 'Rust tests skipped'",
+    "test:python": "test -d python && cd python && python3 -m pytest -p no:anchorpy --asyncio-mode=auto || echo 'Python tests skipped'",
+    "typecheck": "tsc --noEmit -p typescript/tsconfig.json",
+    "lint": "bunx @biomejs/biome check --write ./typescript",
+    "lint:check": "bunx @biomejs/biome check ./typescript",
+    "lint:rust": "test -d rust && cd rust && cargo clippy --all-targets --fix --allow-dirty --allow-staged -- -D warnings && cargo fmt || echo 'Rust lint skipped'",
+    "lint:python": "test -d python && cd python && ruff check --fix . && ruff format . || echo 'Python lint skipped'"
+  },
+  "dependencies": {
+    "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@types/bun": "^1.3.5",
+    "@types/node": "^25.0.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "peerDependencies": {
+    "@elizaos/core": "2.0.0-alpha.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "ELIZA_CODE_ACTIVE_SUB_AGENT": {
+        "type": "string",
+        "description": "Default agent provider ID for new tasks",
+        "required": false,
+        "default": "eliza",
+        "sensitive": false
+      }
+    }
+  },
+  "gitHead": "05d4ca11d769db8c7f54a722ee24b2ce2b951543"
+}

package/python/README.md

@@ -0,0 +1,95 @@
+# Agent Orchestrator Plugin (Python)
+
+Python implementation of the Agent Orchestrator plugin for ElizaOS.
+
+## Overview
+
+This plugin orchestrates tasks across registered agent providers without performing
+file I/O directly - that responsibility belongs to sub-agent workers.
+
+## Features
+
+- Task lifecycle management (create, pause, resume, cancel)
+- Provider-based execution model
+- Event system for task state changes
+- Cross-platform parity with TypeScript and Rust implementations
+
+## Installation
+
+```bash
+pip install elizaos-plugin-agent-orchestrator
+```
+
+## Usage
+
+```python
+from elizaos_plugin_agent_orchestrator import (
+    configure_agent_orchestrator_plugin,
+    AgentOrchestratorPluginOptions,
+    plugin,
+)
+
+# Define your agent provider
+class MyProvider:
+    id = "my-agent"
+    label = "My Agent"
+    description = "Custom agent provider"
+
+    async def execute_task(self, task, ctx):
+        await ctx.append_output("Hello from my-agent")
+        await ctx.update_progress(100)
+        return TaskResult(
+            success=True,
+            summary="done",
+            files_created=[],
+            files_modified=[],
+        )
+
+# Configure the plugin before runtime initialization
+configure_agent_orchestrator_plugin(
+    AgentOrchestratorPluginOptions(
+        providers=[MyProvider()],
+        default_provider_id="my-agent",
+        get_working_directory=lambda: os.getcwd(),
+    )
+)
+
+# Register the plugin with your runtime
+runtime.register_plugin(plugin)
+```
+
+## Actions
+
+- `CREATE_TASK` - Create a new orchestrated task
+- `LIST_TASKS` - List all tasks
+- `SWITCH_TASK` - Switch current task context
+- `SEARCH_TASKS` - Search tasks by query
+- `PAUSE_TASK` - Pause a running task
+- `RESUME_TASK` - Resume a paused task
+- `CANCEL_TASK` - Cancel a task
+
+## Provider Interface
+
+Providers must implement the `AgentProvider` protocol:
+
+```python
+class AgentProvider(Protocol):
+    @property
+    def id(self) -> str: ...
+    
+    @property
+    def label(self) -> str: ...
+    
+    @property
+    def description(self) -> Optional[str]: ...
+    
+    async def execute_task(
+        self,
+        task: OrchestratedTask,
+        ctx: ProviderTaskExecutionContext,
+    ) -> TaskResult: ...
+```
+
+## License
+
+MIT

package/python/elizaos_plugin_agent_orchestrator/__init__.py

@@ -0,0 +1,84 @@
+"""
+Agent Orchestrator Plugin for ElizaOS.
+
+Orchestrates tasks across registered agent providers without performing
+file I/O directly - that responsibility belongs to sub-agent workers.
+"""
+
+from .actions import (
+    cancel_task_action,
+    create_task_action,
+    list_tasks_action,
+    pause_task_action,
+    resume_task_action,
+    search_tasks_action,
+    switch_task_action,
+)
+from .config import configure_agent_orchestrator_plugin, get_configured_options, reset_configuration
+from .providers import task_context_provider
+from .service import AgentOrchestratorService
+from .types import (
+    AgentOrchestratorPluginOptions,
+    AgentProvider,
+    AgentProviderId,
+    JsonValue,
+    OrchestratedTask,
+    OrchestratedTaskMetadata,
+    ProviderTaskExecutionContext,
+    TaskEvent,
+    TaskEventType,
+    TaskResult,
+    TaskStatus,
+    TaskStep,
+    TaskUserStatus,
+)
+
+__all__ = [
+    # Types
+    "JsonValue",
+    "TaskStatus",
+    "TaskUserStatus",
+    "TaskStep",
+    "TaskResult",
+    "AgentProviderId",
+    "OrchestratedTaskMetadata",
+    "OrchestratedTask",
+    "ProviderTaskExecutionContext",
+    "AgentProvider",
+    "AgentOrchestratorPluginOptions",
+    "TaskEventType",
+    "TaskEvent",
+    # Service
+    "AgentOrchestratorService",
+    # Config
+    "configure_agent_orchestrator_plugin",
+    "get_configured_options",
+    "reset_configuration",
+    # Actions
+    "create_task_action",
+    "list_tasks_action",
+    "switch_task_action",
+    "search_tasks_action",
+    "pause_task_action",
+    "resume_task_action",
+    "cancel_task_action",
+    # Providers
+    "task_context_provider",
+]
+
+# Plugin definition for elizaos
+plugin = {
+    "name": "agent-orchestrator",
+    "description": "Orchestrates tasks across registered agent providers",
+    "services": [AgentOrchestratorService],
+    "actions": [
+        create_task_action,
+        list_tasks_action,
+        switch_task_action,
+        search_tasks_action,
+        pause_task_action,
+        resume_task_action,
+        cancel_task_action,
+    ],
+    "providers": [task_context_provider],
+}

package/python/elizaos_plugin_agent_orchestrator/actions/__init__.py

@@ -0,0 +1,23 @@
+"""
+Actions for the Agent Orchestrator plugin.
+"""
+
+from .task_management import (
+    cancel_task_action,
+    create_task_action,
+    list_tasks_action,
+    pause_task_action,
+    resume_task_action,
+    search_tasks_action,
+    switch_task_action,
+)
+
+__all__ = [
+    "create_task_action",
+    "list_tasks_action",
+    "switch_task_action",
+    "search_tasks_action",
+    "pause_task_action",
+    "resume_task_action",
+    "cancel_task_action",
+]