{"_id":"@ai-agencee/engine","_rev":"3-caf81f9b413fae5447604a498a628725","name":"@ai-agencee/engine","dist-tags":{"latest":"1.1.4"},"versions":{"1.1.0":{"name":"@ai-agencee/engine","version":"1.1.0","_id":"@ai-agencee/engine@1.1.0","maintainers":[{"name":"formular.dev","email":"pianatadeo@hotmail.com"}],"dist":{"shasum":"e150654103d58b706fa06c61fb274aeb17481d89","tarball":"https://registry.npmjs.org/@ai-agencee/engine/-/engine-1.1.0.tgz","fileCount":686,"integrity":"sha512-eX0atBVQ32N1oKaTBa7dW9LEsMgD3sslUM9RMD20IuSktB6zJTnuTb4vY1CVvNpi6Lo0W1qrYWst3GbgF7SRqg==","signatures":[{"sig":"MEUCIG76QNn59CjqYWxUybVnnP1Xh8I64D9MfQ/31JrI2JJiAiEA4juVoKmjLRhTRc0yDXHFdpVJR/SUypJeukJvWpwQ0Gw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2195892},"main":"./dist/index.js","type":"commonjs","_from":"file:ai-agencee-engine-1.1.0.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"scripts":{"dev":"tsc --watch","lint":"tsc --noEmit","test":"jest","build":"tsc && node scripts/copy-agents.js"},"_npmUser":{"name":"formular.dev","email":"pianatadeo@hotmail.com"},"_resolved":"/tmp/6ea5081425a950bf6f54fa24a2bb4cd8/ai-agencee-engine-1.1.0.tgz","_integrity":"sha512-eX0atBVQ32N1oKaTBa7dW9LEsMgD3sslUM9RMD20IuSktB6zJTnuTb4vY1CVvNpi6Lo0W1qrYWst3GbgF7SRqg==","_npmVersion":"10.8.2","description":"Agent orchestration and execution engine for AI Agencee","directories":{},"_nodeVersion":"20.20.0","dependencies":{"@ai-agencee/core":"^1.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.2.0","ts-jest":"^29.1.5","typescript":"^5.4.5","@types/jest":"^30.0.0","@types/node":"^25.3.5"},"_npmOperationalInternal":{"tmp":"tmp/engine_1.1.0_1772914842045_0.9499216084251048","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package is legacy and no longer maintained."},"1.1.4":{"name":"@ai-agencee/engine","version":"1.1.4","_id":"@ai-agencee/engine@1.1.4","maintainers":[{"name":"formular.dev","email":"pianatadeo@hotmail.com"}],"dist":{"shasum":"c884aeb88331782f15175ca2e5bacaed0aa970b1","tarball":"https://registry.npmjs.org/@ai-agencee/engine/-/engine-1.1.4.tgz","fileCount":3802,"integrity":"sha512-/BLsdrQIdseb05AIm0tnnMqX0mQhM9KdJgxOvChfNkAIrlbrX661yDL8wPzMCOQT4hxrTunV2M73vY0lxgsI5g==","signatures":[{"sig":"MEUCIQCdFZiqCi6N4+Ow/4xU5QqjFfg9oBLV/mwZJh2tNnRW8wIgSNofH6t/AxmS2vVO7K6zyXdk71/iWCccXBIu9m+r30I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":6546375},"main":"./dist/index.js","type":"commonjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./code-assistant":{"types":"./dist/code-assistant/index.d.ts","default":"./dist/code-assistant/index.js"},"./code-assistant/parsers":{"types":"./dist/code-assistant/parsers/index.d.ts","default":"./dist/code-assistant/parsers/index.js"},"./code-assistant/storage":{"types":"./dist/code-assistant/storage/index.d.ts","default":"./dist/code-assistant/storage/index.js"},"./code-assistant/embeddings":{"types":"./dist/code-assistant/embeddings/index.d.ts","default":"./dist/code-assistant/embeddings/index.js"}},"gitHead":"057758a6bf88ee28e086d4976f26e2d4ecfbe7b0","scripts":{"dev":"tsc --watch","lint":"tsc --noEmit","test":"jest","build":"tsc && node scripts/copy-agents.js","prepublishOnly":"pnpm run build","demo:code-assistant":"node scripts/demo-code-assistant.js"},"_npmUser":{"name":"formular.dev","email":"pianatadeo@hotmail.com"},"_npmVersion":"10.9.0","description":"Agent orchestration and execution engine for AI Agencee","directories":{},"_nodeVersion":"24.12.0","dependencies":{"glob":"^10.5.0","ignore":"^6.0.2","cosmiconfig":"^9.0.1","@ai-agencee/core":"workspace:^","@xenova/transformers":"^2.17.2","@sqlite.org/sqlite-wasm":"3.49.2-build1","@ai-agencee/tech-registry":"workspace:^"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^30.3.0","ts-jest":"^29.4.9","typescript":"^5.9.3","@types/jest":"^30.0.0","@types/node":"^25.6.0"},"_npmOperationalInternal":{"tmp":"tmp/engine_1.1.4_1778145963598_0.21464958714300675","host":"s3://npm-registry-packages-npm-production"},"deprecated":"This package is legacy and no longer maintained."}},"time":{"created":"2026-03-07T20:20:41.915Z","modified":"2026-07-01T08:49:56.919Z","1.1.0":"2026-03-07T20:20:42.219Z","1.1.4":"2026-05-07T09:26:03.889Z"},"description":"Agent orchestration and execution engine for AI Agencee","maintainers":[{"name":"formular.dev","email":"pianatadeo@hotmail.com"}],"readme":"# @ai-agencee/engine\r\n\r\n[![npm](https://img.shields.io/npm/v/@ai-agencee/engine)](https://www.npmjs.com/package/@ai-agencee/engine)\r\n[![license](https://img.shields.io/npm/l/@ai-agencee/engine)](https://github.com/binaryjack/ai-agencee/blob/main/LICENSE)\r\n\r\nThe core execution engine for **AI Agencee**. Runs multi-lane, supervised, DAG-driven AI agent workflows with pluggable LLM providers, per-USD budget caps, cross-lane barrier coordination, and a full 5-phase interactive planning system.\r\n\r\nUsed internally by [`@ai-agencee/mcp`](https://www.npmjs.com/package/@ai-agencee/mcp) and [`@ai-agencee/cli`](https://www.npmjs.com/package/@ai-agencee/cli).\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @ai-agencee/engine\r\n# or\r\npnpm add @ai-agencee/engine\r\n```\r\n\r\n> **Node ≥ 20** required. CommonJS module. Peer dependency: `@ai-agencee/core`.\r\n\r\n---\r\n\r\n## Concepts\r\n\r\n### DAG — Directed Acyclic Graph of agent lanes\r\n\r\nA **DAG** (`dag.json`) declares a set of parallel **lanes**, each driven by a JSON agent definition and an optional supervisor. Lanes run concurrently up to their declared dependencies. The orchestrator resolves the dependency graph, dispatches lanes, and collects results.\r\n\r\n```\r\ndag.json\r\n├── lane: business-analyst   (no deps)\r\n├── lane: architecture        (depends on: business-analyst)\r\n├── lane: backend             (depends on: architecture)\r\n├── lane: frontend            (depends on: architecture)\r\n└── lane: testing             (depends on: backend, frontend)\r\n```\r\n\r\n### Checkpoint System\r\n\r\nAgents are generator functions that **yield** `CheckpointPayload` objects at decision points. The engine routes each checkpoint through the supervisor and resumes the generator with a `SupervisorVerdict`.\r\n\r\n| Checkpoint mode | Behaviour |\r\n|----------------|-----------|\r\n| `self` | Supervisor validates this lane's own output |\r\n| `read-contract` | Non-blocking read of another lane's latest snapshot |\r\n| `soft-align` | Wait up to `timeoutMs` for another lane's snapshot |\r\n| `hard-barrier` | All named lanes must reach this point before any continues |\r\n| `needs-human-review` | Pause and prompt the operator (when `--interactive`) |\r\n\r\n### Verdict System\r\n\r\n```ts\r\ntype VerdictType = 'APPROVE' | 'RETRY' | 'HANDOFF' | 'ESCALATE';\r\n```\r\n\r\n| Verdict | Outcome |\r\n|---------|---------|\r\n| `APPROVE` | Lane continues to next step |\r\n| `RETRY` | Lane re-runs current step with corrective instructions |\r\n| `HANDOFF` | Lane transfers context to a specialist lane |\r\n| `ESCALATE` | Automatic resolution failed — human review required |\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n### 1. Run a DAG directly\r\n\r\n```ts\r\nimport { DagOrchestrator } from '@ai-agencee/engine';\r\n\r\nconst orchestrator = new DagOrchestrator('/path/to/project', {\r\n  verbose: true,\r\n  budgetCapUSD: 0.50,\r\n});\r\n\r\nconst result = await orchestrator.run('agents/dag.json');\r\n\r\nconsole.log(result.status);   // 'success' | 'partial' | 'failed'\r\nconsole.log(result.costUSD);  // actual spend\r\n```\r\n\r\n### 2. Dry-run (validate config, no LLM calls)\r\n\r\n```ts\r\nconst dag = await orchestrator.loadDag('agents/dag.json');\r\nconsole.log(`${dag.lanes.length} lanes, ${dag.globalBarriers?.length ?? 0} barriers`);\r\n```\r\n\r\n### 3. Use the Plan System (5-phase interactive planning)\r\n\r\n```ts\r\nimport { ModelRouter, PlanOrchestrator } from '@ai-agencee/engine';\r\n\r\nconst router = await ModelRouter.fromFile('agents/model-router.json');\r\nconst planner = new PlanOrchestrator(router, { projectRoot: '/path/to/project' });\r\n\r\nconst result = await planner.run({ startFrom: 'discover' });\r\n```\r\n\r\n---\r\n\r\n## API\r\n\r\n### `DagOrchestrator`\r\n\r\n```ts\r\nnew DagOrchestrator(projectRoot: string, options?: DagRunOptions)\r\n```\r\n\r\n#### `DagRunOptions`\r\n\r\n| Option | Type | Default | Description |\r\n|--------|------|---------|-------------|\r\n| `verbose` | `boolean` | `false` | Emit per-checkpoint log lines |\r\n| `budgetCapUSD` | `number` | `undefined` | Abort when estimated spend exceeds this |\r\n| `interactive` | `boolean` | `false` | Pause at `needs-human-review` checkpoints |\r\n| `modelRouterFile` | `string` | `'agents/model-router.json'` | Path to model-router config |\r\n| `agentsBaseDir` | `string` | DAG file's directory | Directory containing agent/supervisor JSON |\r\n| `forceProvider` | `string` | auto-detect | Override LLM provider for all lanes: `anthropic \\| openai \\| vscode \\| mock` |\r\n| `samplingCallback` | `SamplingCallback` | — | VS Code MCP sampling bridge (no API keys needed) |\r\n\r\n#### Methods\r\n\r\n| Method | Returns | Description |\r\n|--------|---------|-------------|\r\n| `loadDag(dagFile)` | `Promise<DagDefinition>` | Parse and validate a dag.json without running |\r\n| `run(dagFile)` | `Promise<DagResult>` | Execute the full DAG |\r\n\r\n#### `DagResult`\r\n\r\n```ts\r\ninterface DagResult {\r\n  dagId: string;\r\n  status: 'success' | 'partial' | 'failed';\r\n  costUSD: number;\r\n  laneResults: LaneResult[];\r\n  startedAt: string;   // ISO timestamp\r\n  finishedAt: string;\r\n}\r\n```\r\n\r\n---\r\n\r\n### `ModelRouter`\r\n\r\nRoutes tasks to the appropriate LLM provider and model tier based on task type.\r\n\r\n```ts\r\nimport { ModelRouter, TaskType } from '@ai-agencee/engine';\r\n\r\nconst router = await ModelRouter.fromFile('agents/model-router.json');\r\n// or\r\nconst router = ModelRouter.fromConfig({ defaultProvider: 'anthropic', taskProfiles: {}, providers: {} });\r\n\r\nconst response = await router.route({\r\n  taskType: 'code-generation',\r\n  messages: [{ role: 'user', content: 'Write a TypeScript utility…' }],\r\n});\r\n```\r\n\r\n#### Task → Model tier mapping\r\n\r\n| Task type | Model tier | Suitable for |\r\n|-----------|-----------|--------------|\r\n| `file-analysis` | Haiku | File reading, counting, data extraction |\r\n| `contract-extraction` | Haiku | Pulling schema/interface data from code |\r\n| `validation` | Haiku | Applying deterministic rules |\r\n| `code-generation` | Sonnet | Writing TypeScript/JS/CSS |\r\n| `refactoring` | Sonnet | Restructuring existing code |\r\n| `api-design` | Sonnet | Designing interfaces and contracts |\r\n| `prompt-synthesis` | Sonnet | Compressing context for next agent |\r\n| `architecture-decision` | Opus | Long-range consequence reasoning |\r\n| `hard-barrier-resolution` | Opus | Arbitrating cross-lane conflicts |\r\n| `security-review` | Opus | Adversarial thinking |\r\n\r\n#### Supported providers\r\n\r\n| Provider | Env var | Notes |\r\n|----------|---------|-------|\r\n| `anthropic` | `ANTHROPIC_API_KEY` | Claude Haiku / Sonnet / Opus |\r\n| `openai` | `OPENAI_API_KEY` | GPT-4o and variants |\r\n| `vscode` | — | VS Code Copilot via MCP sampling; no API key |\r\n| `mock` | — | No LLM calls — for tests and CI dry-runs |\r\n\r\n---\r\n\r\n### Plan System\r\n\r\nA structured 5-phase planning workflow. Each phase builds on the previous one.\r\n\r\n```\r\nPhase 0 — discover    BA ↔ User structured interview\r\nPhase 1 — synthesize  BA produces plan skeleton; user approves\r\nPhase 2 — decompose   Each agent fills in tasks (parallel)\r\nPhase 3 — wire        Dependency graph + alignment gates resolved\r\nPhase 4 — execute     PlanOrchestrator runs wired plan via DagOrchestrator\r\n```\r\n\r\n```ts\r\nimport { PlanOrchestrator, PlanPhase } from '@ai-agencee/engine';\r\n\r\nconst planner = new PlanOrchestrator(router, { projectRoot, agentsBaseDir });\r\nconst result = await planner.run({ startFrom: 'decompose' }); // resume mid-plan\r\n```\r\n\r\n#### `PlanResult`\r\n\r\n```ts\r\ninterface PlanResult {\r\n  status: 'success' | 'partial' | 'failed' | 'cancelled';\r\n  plan?: Plan;\r\n  dagResult?: DagResult;\r\n}\r\n```\r\n\r\n---\r\n\r\n### Cost Tracker\r\n\r\n```ts\r\nimport { CostTracker } from '@ai-agencee/engine';\r\n\r\nconst tracker = new CostTracker({ perRun: 1.00, perLane: 0.20, currency: 'USD' });\r\n\r\ntracker.record({ inputTokens: 1500, outputTokens: 300 }, 'sonnet', 'anthropic');\r\nconsole.log(tracker.totalUSD()); // e.g. 0.012\r\n\r\ntracker.assertBudget(); // throws BudgetExceededError if over cap\r\n```\r\n\r\n---\r\n\r\n### Events\r\n\r\nThe engine emits typed events via a global event bus for monitoring and UI integration.\r\n\r\n```ts\r\nimport { getGlobalEventBus } from '@ai-agencee/engine';\r\n\r\nconst bus = getGlobalEventBus();\r\n\r\nbus.on('dag:start',         (e) => console.log('Run started:', e.runId));\r\nbus.on('dag:end',           (e) => console.log('Run ended:', e.status, `$${e.costUSD}`));\r\nbus.on('lane:start',        (e) => console.log('Lane:', e.laneId));\r\nbus.on('lane:end',          (e) => console.log('Lane done:', e.laneId, e.status));\r\nbus.on('llm:call',          (e) => console.log('LLM call:', e.provider, e.model));\r\nbus.on('budget:exceeded',   (e) => console.warn('Budget cap hit:', e.spentUSD));\r\nbus.on('checkpoint:complete',(e) => console.log('Checkpoint:', e.checkpointId, e.verdict));\r\nbus.on('rbac:denied',       (e) => console.warn('RBAC denied:', e.principal, e.action));\r\n```\r\n\r\n---\r\n\r\n### Enterprise Modules\r\n\r\nThe engine includes production-grade infrastructure available for direct use:\r\n\r\n| Module | Import | Description |\r\n|--------|--------|-------------|\r\n| `AuditLog` | `@ai-agencee/engine` | Append-only structured run log |\r\n| `CircuitBreaker` | `@ai-agencee/engine` | Prevents cascade failures across lanes |\r\n| `RateLimiter` | `@ai-agencee/engine` | Per-provider request rate limiting |\r\n| `RbacPolicy` | `@ai-agencee/engine` | Role-based access control for lane actions |\r\n| `PromptInjectionDetector` | `@ai-agencee/engine` | Detects and blocks prompt injection in LLM inputs |\r\n| `PiiScrubber` | `@ai-agencee/engine` | Redacts PII from prompts and outputs |\r\n| `RunRegistry` | `@ai-agencee/engine` | Tracks active and historical DAG runs |\r\n| `SqliteVectorMemory` | `@ai-agencee/engine` | Persistent vector memory for cross-run context |\r\n| `TenantRegistry` | `@ai-agencee/engine` | Multi-tenant isolation for enterprise deployments |\r\n| `EvalHarness` | `@ai-agencee/engine` | Regression testing of agent outputs |\r\n\r\n---\r\n\r\n## `dag.json` Schema\r\n\r\n```jsonc\r\n{\r\n  \"name\": \"my-workflow\",\r\n  \"modelRouterFile\": \"agents/model-router.json\",\r\n  \"lanes\": [\r\n    {\r\n      \"id\": \"business-analyst\",\r\n      \"agentFile\": \"agents/01-business-analyst.agent.json\",\r\n      \"supervisorFile\": \"agents/business-analyst.supervisor.json\"\r\n    },\r\n    {\r\n      \"id\": \"backend\",\r\n      \"agentFile\": \"agents/03-backend.agent.json\",\r\n      \"supervisorFile\": \"agents/backend.supervisor.json\",\r\n      \"dependsOn\": [\"business-analyst\"]\r\n    }\r\n  ],\r\n  \"globalBarriers\": [\r\n    {\r\n      \"name\": \"design-complete\",\r\n      \"participants\": [\"business-analyst\", \"backend\"],\r\n      \"timeoutMs\": 60000\r\n    }\r\n  ]\r\n}\r\n```\r\n\r\nFull schema: [`schemas/dag.schema.json`](https://github.com/binaryjack/ai-agencee/blob/main/schemas/dag.schema.json)\r\n\r\n---\r\n\r\n## Related Packages\r\n\r\n| Package | Description |\r\n|---------|-------------|\r\n| [`@ai-agencee/core`](https://www.npmjs.com/package/@ai-agencee/core) | File system utilities and project validation |\r\n| [`@ai-agencee/mcp`](https://www.npmjs.com/package/@ai-agencee/mcp) | MCP server — run DAGs from AI assistants, no API keys |\r\n| [`@ai-agencee/cli`](https://www.npmjs.com/package/@ai-agencee/cli) | CLI tool — `ai-kit agent:dag` / `agent:plan` |\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT — see [LICENSE](https://github.com/binaryjack/ai-agencee/blob/main/LICENSE)\r\n","readmeFilename":"README.md"}