{"_id":"@alexintosh/agent-orchestrator","name":"@alexintosh/agent-orchestrator","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@alexintosh/agent-orchestrator","version":"0.1.0","description":"Standalone agent orchestration library — schedule, execute, and manage sessions for CLI-based AI agents (Claude, Codex, Gemini, Cursor, OpenCode, Pi, OpenClaw)","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./adapters/*":{"import":"./dist/adapters/*/index.js","types":"./dist/adapters/*/index.d.ts"},"./stores/*":{"import":"./dist/stores/*.js","types":"./dist/stores/*.d.ts"}},"scripts":{"build":"tsup","dev":"tsup --watch","check":"tsc --noEmit","test":"vitest run","test:watch":"vitest","docs:dev":"vitepress dev docs","docs:build":"vitepress build docs","docs:preview":"vitepress preview docs"},"devDependencies":{"@types/node":"^22.0.0","@types/ws":"^8.18.1","tsup":"^8.0.0","typescript":"^5.7.0","vitepress":"^1.6.4","vitest":"^3.0.0"},"engines":{"node":">=20"},"license":"MIT","dependencies":{"ws":"^8.19.0"},"_id":"@alexintosh/agent-orchestrator@0.1.0","gitHead":"85f0525c5e8f7ca74171042c7557f22f6b706442","_nodeVersion":"20.18.3","_npmVersion":"10.8.2","dist":{"integrity":"sha512-CowaEdx3v6yMgEWunt44/RgdXdJlJvMUqrcGBH+GeIygKiCFqbZBQoVGncBujrxKIh3ABE0y72QiS5JMiSkc6A==","shasum":"17cbfee92279fc6a7cc6a0333fe52f1cda0647dc","tarball":"https://registry.npmjs.org/@alexintosh/agent-orchestrator/-/agent-orchestrator-0.1.0.tgz","fileCount":49,"unpackedSize":963647,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBlT2DcZOlpnEM0ptn1xoUAoqgbUSY1Lq6+uEOttX5xcAiB1kxzGT1jmUEYDIC+9wBt4Gz/qZzSmPFR/WsL3z9gSpQ=="}]},"_npmUser":{"name":"alexintosh","email":"alessio.d@gmail.com"},"directories":{},"maintainers":[{"name":"alexintosh","email":"alessio.d@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-orchestrator_0.1.0_1775483160801_0.8289163607511234"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-06T13:46:00.632Z","0.1.0":"2026-04-06T13:46:00.969Z","modified":"2026-04-06T13:46:01.212Z"},"maintainers":[{"name":"alexintosh","email":"alessio.d@gmail.com"}],"description":"Standalone agent orchestration library — schedule, execute, and manage sessions for CLI-based AI agents (Claude, Codex, Gemini, Cursor, OpenCode, Pi, OpenClaw)","license":"MIT","readme":"# agent-orchestrator\n\nStandalone library for scheduling, executing, and managing sessions for CLI-based AI agents. Supports Claude, Codex, Gemini, Cursor, OpenCode, Pi, and OpenClaw out of the box.\n\n## Installation\n\n```bash\nnpm install agent-orchestrator\n```\n\nRequires **Node.js 20+**.\n\n## Quick Start\n\n```typescript\nimport {\n  createOrchestrator,\n  claudeLocalAdapter,\n  MemoryStore,\n} from \"agent-orchestrator\";\n\nconst orchestrator = createOrchestrator({\n  store: new MemoryStore(),\n  adapters: [claudeLocalAdapter],\n  workspace: { defaultCwd: \"/path/to/workspace\" },\n});\n\nconst agent = await orchestrator.registerAgent({\n  name: \"my-agent\",\n  adapterType: \"claude_local\",\n  adapterConfig: {\n    model: \"sonnet\",\n    dangerouslySkipPermissions: true,\n  },\n});\n\nconst run = await orchestrator.invoke(agent.id, {\n  source: \"on_demand\",\n  prompt: \"Hello, what can you do?\",\n});\n```\n\n## Bundled Adapters\n\n| Adapter | CLI Tool | Auth |\n|---------|----------|------|\n| `claudeLocalAdapter` | `claude` | `ANTHROPIC_API_KEY` or `claude login` |\n| `codexLocalAdapter` | `codex` | `OPENAI_API_KEY` |\n| `cursorLocalAdapter` | `cursor` | `CURSOR_API_KEY` |\n| `geminiLocalAdapter` | `gemini` | `GEMINI_API_KEY` |\n| `opencodeLocalAdapter` | `opencode` | Provider-specific |\n| `piLocalAdapter` | `pi` | Built-in auth |\n| `openclawGatewayAdapter` | N/A (WebSocket) | Device identity + API key |\n\nRegister all adapters at once:\n\n```typescript\nimport { adapters } from \"agent-orchestrator\";\n\nconst orchestrator = createOrchestrator({\n  store: new MemoryStore(),\n  adapters: Object.values(adapters),\n  workspace: { defaultCwd: process.cwd() },\n});\n```\n\nOr import individually for tree-shaking:\n\n```typescript\nimport { claudeLocalAdapter } from \"agent-orchestrator/adapters/claude-local\";\n```\n\n## Key Concepts\n\n- **Adapters** bridge the orchestrator to CLI-based agents. Each implements `ServerAdapterModule`.\n- **Sessions** persist agent context across runs, tracked per (agent, adapter, taskKey). Automatic compaction rotates sessions when they grow too large.\n- **Scheduler** queues and executes runs with concurrency control.\n- **Store** is pluggable. `MemoryStore` ships for testing; implement `OrchestratorStore` for production (e.g., PostgreSQL).\n- **Tenant isolation** via `tenantId` (optional, defaults to `\"default\"` for single-tenant use).\n\n## Running the Examples\n\nThe examples live in the `examples/` directory. Run them with `tsx`:\n\n```bash\n# Install tsx if you don't have it\nnpm install -g tsx\n```\n\n### Example 1: Single Agent Runner\n\nRegisters a Claude agent, invokes it with a prompt, and prints the result.\n\n**Prerequisites:** `claude` CLI installed and authenticated (`ANTHROPIC_API_KEY` or `claude login`).\n\n```bash\nnpx tsx examples/01-single-agent-runner.ts\n```\n\n### Example 2: Multi-Session Resume\n\nDemonstrates session persistence across multiple runs using a mock adapter (no CLI tools required):\n- Run 1: Agent starts a fresh session\n- Run 2: Same taskKey resumes the session\n- Run 3: Different taskKey starts a new session\n- Run 4: Returns to the original session\n\n```bash\nnpx tsx examples/02-multi-session-resume.ts\n```\n\n### Example 3: Agent Identity from Markdown\n\nShows how to give an agent a full identity via a markdown file — defining its role, personality, rules, and output format. Demonstrates two approaches:\n\n- **`instructionsFilePath`** — the agent identity is injected as a system prompt extension (recommended for Claude)\n- **`promptTemplate`** — the identity is embedded directly in the prompt (works with all adapters)\n\nThe example creates a code review agent and asks it to review a deliberately insecure login handler.\n\n**Prerequisites:** `claude` CLI installed and authenticated.\n\n```bash\nnpx tsx examples/03-agent-identity-from-markdown.ts\n```\n\n## Development\n\n```bash\n# Build\nnpm run build\n\n# Type-check\nnpm run check\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Documentation site (VitePress)\nnpm run docs:dev       # dev server\nnpm run docs:build     # production build\n```\n\n## Documentation\n\nFull API reference and guides are available via VitePress:\n\n```bash\nnpm run docs:dev\n```\n\nCovers architecture, adapter configuration, session management, storage backends, and custom adapter development.\n\n## License\n\nMIT\n\n## Acknowledgements\n\nThis library was extracted from [Paperclip](https://paperclip.com)'s agent orchestration platform. The core execution pipeline, adapter pattern, session management system, and scheduler were originally developed as part of Paperclip's multi-agent infrastructure for coordinating CLI-based AI agents at scale.\n","readmeFilename":"README.md","_rev":"1-f3b923d769eee9fe9b9710c17db58bb8"}