{"_id":"@agent-stack2/coordinator","_rev":"2-17ccbea5fa04a08e5b2a18fef3cb6413","name":"@agent-stack2/coordinator","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@agent-stack2/coordinator","version":"0.1.0","keywords":["agent-stack","multi-agent","coordination","mcp","coding-agents"],"author":{"name":"jsalvadorlpz"},"license":"MIT","_id":"@agent-stack2/coordinator@0.1.0","maintainers":[{"name":"josepsalvador","email":"josep100998@gmail.com"}],"homepage":"https://github.com/jsalvadorlpz/agent-stack#readme","bugs":{"url":"https://github.com/jsalvadorlpz/agent-stack/issues"},"bin":{"agent-coordinator":"dist/server.js"},"dist":{"shasum":"1562797b1e2b985acb9fa5ca927440d386a14f9b","tarball":"https://registry.npmjs.org/@agent-stack2/coordinator/-/coordinator-0.1.0.tgz","fileCount":183,"integrity":"sha512-KOFKbeEzGDeo43R984+a5oBcaQ9YsQ6NfCOiEGnW/A6DP+hRgX3TeIhKEax1VhXLyCI+dQba8Z4D4vjy8u7Ehw==","signatures":[{"sig":"MEUCIQD3Kei9Fo0GHacRfNTFLa7lS6wPaoy+fpW1+mLIejPZTQIgIcjPdYjAIySI66oVqXgMxBgh4qQm1lc4jBRWuPPsXPo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":954623},"main":"dist/server.js","type":"module","_from":"file:agent-stack2-coordinator-0.1.0.tgz","types":"./dist/server.d.ts","engines":{"node":">=18.0.0"},"scripts":{"test":"vitest run","build":"tsc","clean":"rm -rf dist","start":"node dist/server.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"josepsalvador","email":"josep100998@gmail.com"},"_resolved":"/tmp/6b3b1ae3f4931b1fee7a5eaa02062f34/agent-stack2-coordinator-0.1.0.tgz","_integrity":"sha512-KOFKbeEzGDeo43R984+a5oBcaQ9YsQ6NfCOiEGnW/A6DP+hRgX3TeIhKEax1VhXLyCI+dQba8Z4D4vjy8u7Ehw==","repository":{"url":"git+https://github.com/jsalvadorlpz/agent-stack.git","type":"git","directory":"packages/coordinator"},"_npmVersion":"10.8.2","description":"Multi-agent coordination MCP server — sessions, claims, handoffs, merge-risk prediction, and team metrics","directories":{},"_nodeVersion":"20.20.1","dependencies":{"zod":"^3.24.4","@agent-stack2/token-gate":"0.1.0","@modelcontextprotocol/sdk":"^1.12.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.1","typescript":"^5.8.3","@types/node":"^22.15.3"},"_npmOperationalInternal":{"tmp":"tmp/coordinator_0.1.0_1774196710758_0.05554283084261358","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@agent-stack2/coordinator","version":"0.2.0","description":"Multi-agent coordination MCP server — sessions, claims, handoffs, merge-risk prediction, and team metrics","license":"MIT","author":{"name":"jsalvadorlpz"},"repository":{"type":"git","url":"git+https://github.com/jsalvadorlpz/agent-stack.git","directory":"packages/coordinator"},"homepage":"https://github.com/jsalvadorlpz/agent-stack#readme","bugs":{"url":"https://github.com/jsalvadorlpz/agent-stack/issues"},"keywords":["agent-stack","multi-agent","coordination","mcp","coding-agents"],"type":"module","main":"dist/server.js","bin":{"agent-coordinator":"dist/server.js"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","zod":"^3.24.4","@agent-stack2/token-gate":"0.1.0"},"devDependencies":{"@types/node":"^22.15.3","typescript":"^5.8.3","vitest":"^3.1.1"},"scripts":{"build":"tsc","start":"node dist/server.js","test":"vitest run","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_id":"@agent-stack2/coordinator@0.2.0","types":"./dist/server.d.ts","_integrity":"sha512-FdK632LZ6NRupOSqd6y4+IwlgonXTWY0VlfCwj8kfgfVniRk3NME9CMZkDVx4A6B/U7xzNpdHErxutlYaCGlgA==","_resolved":"/tmp/c182826894f2bc090ab93e0a20d43de2/agent-stack2-coordinator-0.2.0.tgz","_from":"file:agent-stack2-coordinator-0.2.0.tgz","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-FdK632LZ6NRupOSqd6y4+IwlgonXTWY0VlfCwj8kfgfVniRk3NME9CMZkDVx4A6B/U7xzNpdHErxutlYaCGlgA==","shasum":"f5ab95350e503e71661e4465d8648622f85358d0","tarball":"https://registry.npmjs.org/@agent-stack2/coordinator/-/coordinator-0.2.0.tgz","fileCount":95,"unpackedSize":449899,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHw3ZZGMbAwVLX0FTx2n/90gq0U8zm98fN/griyD8qkWAiEAyawdEMP6SVklXcZZh5Fha0wChhCMJfLjXToI/IXkaj0="}]},"_npmUser":{"name":"josepsalvador","email":"josep100998@gmail.com"},"directories":{},"maintainers":[{"name":"josepsalvador","email":"josep100998@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/coordinator_0.2.0_1774460981582_0.8453343630908383"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-22T16:25:10.666Z","modified":"2026-03-25T17:49:41.884Z","0.1.0":"2026-03-22T16:25:10.929Z","0.2.0":"2026-03-25T17:49:41.745Z"},"bugs":{"url":"https://github.com/jsalvadorlpz/agent-stack/issues"},"author":{"name":"jsalvadorlpz"},"license":"MIT","homepage":"https://github.com/jsalvadorlpz/agent-stack#readme","keywords":["agent-stack","multi-agent","coordination","mcp","coding-agents"],"repository":{"type":"git","url":"git+https://github.com/jsalvadorlpz/agent-stack.git","directory":"packages/coordinator"},"description":"Multi-agent coordination MCP server — sessions, claims, handoffs, merge-risk prediction, and team metrics","maintainers":[{"name":"josepsalvador","email":"josep100998@gmail.com"}],"readme":"# Agent Coordinator\n\nAgent Coordinator is the control plane for multi-agent software work.\n\nIt answers the questions that every serious agent team eventually hits:\n\n- Who is working right now?\n- On what task?\n- With what mission?\n- Which files or modules do they plan to touch?\n- Is it safe for me to continue, review, or take over?\n\nThis repo starts from a small MCP server and grows toward a full multi-agent\ncoordination layer for coding teams.\n\n## Product thesis\n\nStrong coding agents do not fail only because they lack reasoning. They also\nfail because they lack shared operational state.\n\nWithout coordination, multiple agents:\n\n- duplicate work\n- edit the same area at once\n- leave vague handoffs\n- lose track of blockers\n- make humans guess who owns what\n\nAgent Coordinator exists to make multi-agent execution feel normal, reliable,\nand commercially useful.\n\n## What \"good\" looks like\n\nIn the ideal flow, every agent session has four visible steps:\n\n1. Announce presence and mission.\n2. Claim a workset before editing.\n3. Leave structured checkpoints, blockers, and handoffs.\n4. Hand work off or close the session cleanly.\n\nThe next agent should not need to guess. It should know:\n\n- who was here before\n- what they were trying to do\n- what they touched\n- what is still blocked\n- whether it is safe to continue\n\n## Current status\n\nThe current implementation includes:\n\n- actor registry (auto-registered on session start)\n- session v2 with heartbeat, stale/terminal enforcement\n- workset claims: project-scoped with conflict severity\n- handoff v2: ownership-enforced accept/complete/cancel lifecycle\n- assignment model with priority routing, accept/complete lifecycle\n- agent inbox: handoffs + assignments in one call\n- watch model: target-aware subscriptions (project/node/claim/actor) with eventTypes filtering\n- notifications: event-aware fanout for handoffs, assignments, conflicts, stale expiries\n- notification read-state: mark_notification_read, mark_all_notifications_read\n- team status: compact operational summary with alerts\n- activity feed with consistent project filtering\n- memory bridge: deterministic mapping layer from coordinator events to Agent Memory descriptors (15 event types)\n- memory recorder: live recording of coordinator events into Agent Memory with pluggable writer, node resolver, fail-open policy, and actor provenance\n- memory runtime: production wiring with LocalMemoryWriter (JSONL to .agent-memory/) and CoordinatorNodeResolver\n- boot overlay: coordinator state snapshot for agent startup — who is active, what is claimed, what is waiting, what is risky, what can I take over\n- end-to-end resume demo: proven two-actor handoff/resume with safe claim ownership transfer and durable memory evidence\n- cross-vendor resume benchmark: symmetric Claude↔Codex resume with call counts, guarantees, and limitations\n- merge-risk heuristics: directory overlap, test-surface overlap, and semantic module coupling for predictive conflict detection\n- predict_merge_risk: MCP tool combining heuristic engine with live coordinator state for proactive conflict assessment against active claims; emits merge_risk_predicted activity\n- multi-project registry: auto-registered on all write paths (sessions, claims, handoffs, assignments), explicit registration via register_project\n- cross-project actor view: get_actor_projects shows where an actor is active, blocked, or overloaded across repos\n- consistent actor identity: actors auto-registered on all write paths so get_actor_projects never returns null for active participants\n- coordination metrics: quantitative ROI signals — conflicts detected, handoff acceptance/completion rates, assignment pickup, stale work, pickup latency, per-project breakdown, human-readable highlights\n- team control plane demo: proven 3-agent + 1-human scenario with merge-risk prevention, human reassignment, handoff pickup, and durable memory evidence\n- MCP server v0.5 with 37 tools (369 tests passing)\n\nPhases 1-6 complete. The module is ready for design-partner adoption.\n\n## Quickstart\n\n```bash\nnpm install\nnpm run build\nnpm test          # 369+ tests\nnpm run smoke     # build + team demo\n```\n\nWire into your MCP client by pointing at `dist/server.js`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-coordinator\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/agent-coordinator/dist/server.js\"]\n    }\n  }\n}\n```\n\nFull setup instructions: [docs/INSTALL.md](docs/INSTALL.md)\n\n## Docs\n\n- [docs/INSTALL.md](docs/INSTALL.md) - install and quickstart guide\n- [docs/RELEASE.md](docs/RELEASE.md) - release workflow and checklist\n- [docs/DEMO-TEAM-CONTROL-PLANE.md](docs/DEMO-TEAM-CONTROL-PLANE.md) - 3-agent + 1-human demo and benchmark\n- [docs/DEMO-RESUME.md](docs/DEMO-RESUME.md) - two-agent handoff and resume demo\n- [docs/MCP-SPEC.md](docs/MCP-SPEC.md) - tool contracts, schemas, and state model\n- [ROADMAP.md](ROADMAP.md) - product roadmap and phases\n- [PAIN-POINTS.md](PAIN-POINTS.md) - tracked coordination failures\n- [docs/BACKLOG.md](docs/BACKLOG.md) - implementation tasks in execution order\n- [docs/IDEAL-COORDINATOR.md](docs/IDEAL-COORDINATOR.md) - what the finished product should feel like\n\n## Relationship to Agent Memory\n\n`agent-memory-kit` stores durable execution memory.\n\n`agent-coordinator` stores live operational coordination state.\n\nThe long-term goal is:\n\n- memory tells the next session what happened\n- coordinator tells the next session who is active right now\n\nTogether they give an agent both continuity and situational awareness.\n\n## Product shape across the toolkit\n\nThe right end-state is not one app per tool.\n\nThe better model is:\n\n- one unified toolkit app / workbench\n- `agent-memory` as the continuity core and likely UI nucleus\n- each subrepo keeping its own MCP surface, storage, tests, and domain logic\n\nThat gives the user one coherent product while preserving clean ownership in each tool repo.\n\n## Development workflow\n\nThis project uses Agent Memory (local mode via `.mcp.json`).\n\nIf `.agent-memory/` is empty on a fresh clone, bootstrap it with:\n\n```powershell\n./scripts/bootstrap-memory.ps1\n```\n\nRecommended workflow for future work:\n\n1. `boot_context()`\n2. Read `README.md`, `ROADMAP.md`, `PAIN-POINTS.md`, and `docs/`\n3. If memory does not resolve an active node, run `./scripts/bootstrap-memory.ps1`\n4. Execute the next task from [docs/BACKLOG.md](docs/BACKLOG.md)\n5. Record meaningful decisions and blockers in memory\n6. `finalize_node(summary=\"...\")`\n\nTreat Agent Memory as mandatory, not optional. A coding session in this repo is incomplete if it changed code or product direction but did not leave memory updates behind.\n\n## Long-term promise\n\nThe real value proposition is not \"more tools for agents\".\n\nIt is:\n\n\"Run multiple coding agents on the same codebase without chaos.\"\n","readmeFilename":"README.md"}