{"_id":"@ahmedtaha/aether","name":"@ahmedtaha/aether","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@ahmedtaha/aether","version":"0.2.0","description":"AETHER — Autonomous Agent Orchestration Framework","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"aether":"bin/aether.ts","aether-mcp":"bin/aether-mcp.ts"},"scripts":{"dev":"bun run bin/aether.ts","link:start":"bun run protocol/server.ts","test":"bun test","build":"bun build bin/aether.ts --outdir ./dist --target bun","build:mcp":"bun build bin/aether-mcp.ts --outdir ./dist --target bun","compile":"bun run dsl/cli.ts","prepublishOnly":"bun run build && bun run build:mcp"},"exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./core/*":"./core/*","./protocol/*":"./protocol/*"},"engines":{"bun":">=1.1.0"},"keywords":["ai","agents","orchestration","llm","framework","multi-agent","rag","bun"],"license":"BSL-1.1","devDependencies":{"@types/bun":"latest"},"dependencies":{"msgpackr":"^1.11.8","sqlite-vec":"^0.1.7-alpha.2"},"_id":"@ahmedtaha/aether@0.2.0","gitHead":"acb2aef6abc00d292f104ffad0c3c4b3e70ffbaa","_nodeVersion":"23.7.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-lyNb3bg64R3Y4cFqQZH6N3w3ixOOgszfusQ8heBRBpW5nHU0s64ruP6NI7EqMWWx4xYM7jyvYPtvp5RnB9HpIg==","shasum":"d296ae175e5003d31ee5020ab7f1a847c1fe8b1c","tarball":"https://registry.npmjs.org/@ahmedtaha/aether/-/aether-0.2.0.tgz","fileCount":103,"unpackedSize":2072921,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCcDnLHmwbH3Ez5/KCMIMO0vT8KgG+vrzptHp2U3mrPHwIhAKE6ta+fXtm6nXeR96xxHi8aYGkU/pOmyag3rot1KR3Z"}]},"_npmUser":{"name":"ahmedtaha","email":"tahaa755@yahoo.com"},"directories":{},"maintainers":[{"name":"ahmedtaha","email":"tahaa755@yahoo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aether_0.2.0_1772978894623_0.7720817073645261"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-08T14:08:14.499Z","0.2.0":"2026-03-08T14:08:14.847Z","modified":"2026-03-08T14:08:15.095Z"},"maintainers":[{"name":"ahmedtaha","email":"tahaa755@yahoo.com"}],"description":"AETHER — Autonomous Agent Orchestration Framework","keywords":["ai","agents","orchestration","llm","framework","multi-agent","rag","bun"],"license":"BSL-1.1","readme":"# AETHER\n\n**Autonomous Agent Orchestration Framework**\n\nAETHER is a multi-agent LLM orchestration framework built on Bun. It coordinates a 3-tier agent hierarchy (Master/Manager/Worker) across 28 subsystems — including context-aware routing, pre/post LLM guardrails, durable workflows with checkpoint/resume, a typed Agent Communication Protocol, entity-level knowledge accumulation, and a plugin system with 8 lifecycle hooks. Agents are defined as `.agent.md` files and can be backed by any LLM provider (Claude, OpenAI, Gemini, Ollama). All state persists in a single SQLite database (19 tables, WAL mode, sqlite-vec + FTS5).\n\n## Quick Start\n\n```bash\n# Install dependencies\nbun install\n\n# Initialize in your project\nbun run dev -- init\n\n# Run a task\nbun run dev -- run \"explain the project structure\"\n\n# Start the WebSocket server\nbun run dev -- link\n\n# View registered agents\nbun run dev -- registry\n\n# Check status\nbun run dev -- status\n```\n\n## Architecture\n\n```\n                    +─────────────+\n                    |  cortex-0   |  Master\n                    |  (Opus)     |\n                    +──────┬──────+\n                           |\n              +────────────┼────────────+\n              |            |            |\n        +─────┴─────+ +───┴───+ +──────┴─────+\n        |  manager   | | mgr-2 | |  manager   |  Managers\n        |  (Sonnet)  | |       | |  (Sonnet)  |\n        +─────┬──────+ +───┬───+ +──────┬─────+\n              |            |            |\n         +────┴────+   +──┴──+   +─────┴────+\n         | workers  |  | ... |   | workers   |    Workers\n         | (Haiku)  |  |     |   | (Flash)   |\n         +-────────+   +─────+   +──────────+\n```\n\n**Tiers:**\n\n- **Master** — Strategic oversight, final escalation target\n- **Manager** — Domain coordination, sub-task delegation\n- **Worker** — Specialized task execution\n\n**Key Subsystems:**\n\n- **Registry** — Agent discovery and multi-index capability lookup\n- **Escalation** — Circuit-breaker-protected escalation chains\n- **MemoryHighway** — Pub/sub messaging with persistent history and automatic RAG indexing\n- **RAGIndex** — SQLite-vec + FTS5 hybrid search across 6 namespaces\n- **InteractionNet** — Graph-based parallel task execution (interaction combinators)\n- **Aether-Link** — WebSocket server with BAP-02 binary protocol\n- **AgentRouter** — 6-strategy context-aware routing with confidence scoring\n- **GuardrailsPipeline** — Pre/post LLM safety filters (injection, PII, code safety)\n- **SchemaValidator** — Structured output validation with correction-prompt retry\n- **ConversationManager** — Multi-turn conversation tracking with checkpoint/resume\n- **EntityMemory** — Entity-level knowledge accumulation across sessions\n- **HandoffManager** — Horizontal peer-to-peer agent transfer with cycle detection\n- **GroupChat** — Multi-agent round-table discussions with pluggable speaker selection\n- **StateGraph** — Conditional-edge state machines with reflection loops\n- **ProgressTracker** — Stall, loop, and budget exhaustion detection\n- **DurableWorkflow** — Checkpoint/resume workflows that survive crashes\n- **ACPBus** — Typed message envelopes, request-response, dead-letter queue\n- **ConflictResolver** — Multi-output contradiction detection and resolution\n- **SharedStateBus** — Observable immutable state with versioned transitions\n- **StructuredLogger** — JSON logging, scoped context, LLM call instrumentation\n- **PluginRegistry** — 8 lifecycle hook slots for external extensions\n- **ReactionEngine** — Event-driven autonomous workflow triggers\n- **SettingsManager** — Unified settings with 13 configurable subsystem groups\n\n## Agent Authoring\n\nCreate `.agent.md` files in `agents/`, `.aether/agents/`, or `.github/agents/`:\n\n```markdown\n---\nid: react-specialist\nname: React Specialist\ntier: worker\nsections: [FRONTEND]\ncapabilities: [react, typescript, component-design]\ndependencies: [tailwind]\nllmRequirement: sonnet\nformat: markdown\nescalationTarget: frontend-manager\n---\n\n# React Specialist\n\nYou are a React specialist agent. You build high-quality React\ncomponents using TypeScript and modern patterns...\n```\n\n**Supported metadata formats:** YAML frontmatter, key-value pairs, XML tags, or auto-infer from filename.\n\n## Configuration\n\nAfter `aether init`, configuration lives in two files:\n\n**`.aether/config.json`** — Auto-generated workspace config (not intended for manual editing):\n\n```json\n{\n  \"version\": \"0.2.0\",\n  \"workspace\": { ... },\n  \"providers\": {\n    \"master\": { \"provider\": \"gemini\", \"model\": \"gemini-pro\" },\n    \"manager\": { \"provider\": \"gemini\", \"model\": \"gemini-pro\" },\n    \"worker\": { \"provider\": \"gemini\", \"model\": \"gemini-flash\" },\n    \"fallbackChain\": []\n  },\n  \"server\": {\n    \"port\": 9999,\n    \"host\": \"localhost\",\n    \"authToken\": \"...\"\n  },\n  \"logging\": { \"level\": \"info\", \"file\": \"...\" }\n}\n```\n\n**`.aether/settings.json`** — User-editable tuning knobs for all 28 subsystems:\n\n```json\n{\n  \"methodology\": { \"mode\": \"tdd\", \"testCommand\": \"bun test\" },\n  \"agents\": { \"maxConcurrent\": 10 },\n  \"execution\": { \"maxDepth\": 3, \"temperature\": 0.7, \"maxTokens\": 4096 },\n  \"escalation\": { \"threshold\": 3, \"windowMs\": 300000 },\n  \"routing\": { \"confidenceThreshold\": 0.6 },\n  \"progress\": { \"maxTokenBudget\": 500000, \"stallThresholdMs\": 60000 },\n  \"server\": { \"port\": 9999, \"host\": \"localhost\" }\n}\n```\n\nManage settings via the CLI: `aether config get execution.maxDepth`, `aether config set execution.maxDepth 5`.\n\n## CLI Reference\n\n| Command             | Description                              |\n| ------------------- | ---------------------------------------- |\n| `aether init`       | Scan workspace, create `.aether/` config |\n| `aether run <task>` | Execute a task with an AI agent          |\n| `aether link`       | Start the Aether-Link WebSocket server   |\n| `aether status`     | Show runtime and server status           |\n| `aether registry`   | List all registered agents               |\n| `aether spawn <id>` | Activate a specific agent                |\n| `aether config`     | View and manage settings                 |\n| `aether scan`       | Scan workspace and display tech stack    |\n\n**Config sub-commands:**\n\n| Sub-command                     | Description                                   |\n| ------------------------------- | --------------------------------------------- |\n| `aether config`                 | Show all current settings                     |\n| `aether config get <path>`      | Get a specific setting (dot-path)             |\n| `aether config set <path> <val>`| Set a specific setting                        |\n| `aether config reset [section]` | Reset to defaults (all or specific section)   |\n| `aether config edit`            | Open `settings.json` in `$EDITOR`             |\n| `aether config validate`        | Validate current settings                     |\n| `aether config path`            | Print path to `settings.json`                 |\n\n**Run options:**\n\n- `-p, --provider <name>` — LLM provider (`claude`, `openai`, `gemini`, `ollama`)\n- `-m, --model <name>` — Model name or alias\n- `-a, --agent <id>` — Target a specific agent\n\n```bash\naether run -p gemini -m gemini-2.0-flash \"explain recursion\"\naether run -p ollama -m deepseek-r1 \"hello world\"\naether run -a cortex-0 \"decompose this project\"\n```\n\n## Provider Setup\n\nSet API keys as environment variables:\n\n| Provider         | Environment Variable                |\n| ---------------- | ----------------------------------- |\n| Google Gemini    | `GOOGLE_AI_KEY` or `GEMINI_API_KEY` |\n| Anthropic Claude | `ANTHROPIC_API_KEY`                 |\n| OpenAI           | `OPENAI_API_KEY`                    |\n| Ollama           | (runs locally, no key needed)       |\n\nAETHER auto-detects available providers on `init` and maps them to agent tiers.\n\n## Synapse DSL\n\nDefine workflows in `.syn` files:\n\n```synapse\n@workflow data-pipeline\n  @trigger on_commit(\"main\")\n\n  step analyze = research-agent(\"Analyze the PR changes\")\n  step review  = code-reviewer(analyze.output)\n  step report  = report-writer(review.output)\n\n  @output report.output\n```\n\nCompile with: `bun run compile -- workflow.syn`\n\n## Storage\n\nAETHER uses a single SQLite database at `.aether/aether.db` (WAL mode) with sqlite-vec for vector embeddings and FTS5 for full-text search. Nineteen tables store all state — agent registry, task history, escalation records, messages, RAG index, conversations, entity knowledge, workflow checkpoints, file ownership rules, progress events, and metrics — persisting across restarts.\n\n## Security\n\n- **WebSocket auth** — Token-based authentication on connection upgrade\n- **Origin validation** — Localhost-only by default\n- **Rate limiting** — Connection attempt throttling per IP\n- **Input validation** — Message size limits, field format validation, timestamp range checks\n- **Health endpoints** — `/health` (liveness), `/metrics` (Prometheus format)\n\n## Development\n\n```bash\n# Run tests\nbun test\n\n# Build for distribution\nbun run build\n\n# Type check\nbunx tsc --noEmit\n```\n\n## License\n\n[BSL-1.1](./LICENSE) — Business Source License 1.1. Converts to MIT after 4 years.\n","readmeFilename":"README.md","_rev":"1-3a9cdeb7d168c6707931fd287f877cb1"}