{"_id":"@agentsonar/oma","_rev":"8-0b5763158e3d87e321d025c59b8ce346","name":"@agentsonar/oma","dist-tags":{"alpha":"0.1.0-alpha.2","latest":"0.2.2"},"versions":{"0.1.0-alpha.1":{"name":"@agentsonar/oma","version":"0.1.0-alpha.1","keywords":["multi-agent","observability","open-multi-agent","agentsonar","coordination"],"license":"Apache-2.0","_id":"@agentsonar/oma@0.1.0-alpha.1","maintainers":[{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"}],"dist":{"shasum":"06f9bf3d9a2a2464c65307648daf06a2db5b6633","tarball":"https://registry.npmjs.org/@agentsonar/oma/-/oma-0.1.0-alpha.1.tgz","fileCount":6,"integrity":"sha512-vhT/EIURaQRzF+oeNkvnD+6OVkDbD2L2UuPNJI2/zDFwwa/LcSmlpCCpR3yQSH0IoCUgfuH9Ygj/ZZFrbcczOg==","signatures":[{"sig":"MEQCIETIDjUGV91qMykNIMWztdcq/MW3ZJH55ju/0eGGyaGYAiBsRGd6TiV2301JZw50th/1OvKlIEBGdDfIQq9vaAtK8Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48792},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"6ba7854a38ad8e5a535ea24be946bd016bea1ec5","scripts":{"demo":"tsx examples/demo.ts","test":"node --test --import tsx tests/safety.test.ts tests/edges.test.ts tests/trace.test.ts","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"},"_npmVersion":"11.12.1","description":"AgentSonar integration for Open Multi-Agent (OMA) — bridges OMA task graphs and trace events to the AgentSonar coordination engine.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","typescript":"^5.6.0","@types/node":"^22.0.0","@jackchen_me/open-multi-agent":">=1.2.0"},"peerDependencies":{"@jackchen_me/open-multi-agent":">=1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/oma_0.1.0-alpha.1_1777170709719_0.5981319452467746","host":"s3://npm-registry-packages-npm-production"}},"0.1.0-alpha.2":{"name":"@agentsonar/oma","version":"0.1.0-alpha.2","keywords":["multi-agent","observability","open-multi-agent","agentsonar","coordination"],"license":"Apache-2.0","_id":"@agentsonar/oma@0.1.0-alpha.2","maintainers":[{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"}],"dist":{"shasum":"c97bfcaeba9b8edf98d7cd586ced05896ca34dba","tarball":"https://registry.npmjs.org/@agentsonar/oma/-/oma-0.1.0-alpha.2.tgz","fileCount":6,"integrity":"sha512-62H4qjufsTkd627HhoIIbKuO6xGdcOOwl2cCNRJbFIeTJPgHjcPPHw6AkR/geCQoEYS4sP3cGEwL7XoiZmhDMw==","signatures":[{"sig":"MEUCIC1EbC2QUBVuWVEgU0vm5zeW4iIOuZmJnEzib71iWogZAiEA+y37n4+EMRxoEADPasQ4H4fctHeK6QmC/J+k2Pn/SyQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48553},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"81ef160879136ecf612cc31e06cc25e7bcd5c0de","scripts":{"demo":"tsx examples/demo.ts","test":"node --test --import tsx tests/safety.test.ts tests/edges.test.ts tests/trace.test.ts","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"},"_npmVersion":"11.12.1","description":"AgentSonar integration for Open Multi-Agent (OMA) — bridges OMA task graphs and trace events to the AgentSonar coordination engine.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"tsx":"^4.7.0","typescript":"^5.6.0","@types/node":"^22.0.0","@jackchen_me/open-multi-agent":">=1.2.0"},"peerDependencies":{"@jackchen_me/open-multi-agent":">=1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/oma_0.1.0-alpha.2_1777171168444_0.2416188965321171","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@agentsonar/oma","version":"0.1.0","keywords":["multi-agent","observability","open-multi-agent","agentsonar","coordination"],"license":"Apache-2.0","_id":"@agentsonar/oma@0.1.0","maintainers":[{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"}],"dist":{"shasum":"67960f01d0e8f517646bcfee4ffc6f156b04caed","tarball":"https://registry.npmjs.org/@agentsonar/oma/-/oma-0.1.0.tgz","fileCount":6,"integrity":"sha512-cWmAZ9KFnUrXFZMo0CNcULKm6wKo4UKHN5m3Wimyzb1Cn48zBAWAb7pgjsXaciAGoMJiqJySl2ZrrLIAtp8XvQ==","signatures":[{"sig":"MEYCIQC2yf6Rd8ECXegttYhV6jgbflNxk5qqO5KUSpOUvuJEKAIhAJtK3oue7bdbaZar6ULtfqsLvd90BUZei2+FFFf7k9OJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48545},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"2bd6f67bb554e4b1726c005776f7632f3e63f3aa","scripts":{"demo":"tsx examples/demo.ts","test":"node --test --import tsx tests/safety.test.ts tests/edges.test.ts tests/trace.test.ts","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"},"_npmVersion":"11.12.1","description":"AgentSonar integration for Open Multi-Agent (OMA) — bridges OMA task graphs and trace events to the AgentSonar coordination engine.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","typescript":"^5.6.0","@types/node":"^22.0.0","@jackchen_me/open-multi-agent":">=1.2.0"},"peerDependencies":{"@jackchen_me/open-multi-agent":">=1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/oma_0.1.0_1777172273298_0.11895409303659354","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agentsonar/oma","version":"0.1.1","keywords":["multi-agent","observability","open-multi-agent","agentsonar","coordination"],"license":"Apache-2.0","_id":"@agentsonar/oma@0.1.1","maintainers":[{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"}],"dist":{"shasum":"7c0ca53d2692ead6f3329bff24a121a196e2f54a","tarball":"https://registry.npmjs.org/@agentsonar/oma/-/oma-0.1.1.tgz","fileCount":6,"integrity":"sha512-RqKZ9/1Sw6wz+itmI1GJaTu8y2SpmxzMSxfr65M4UItmUkYwxRQrsUnqegtqQWWjB2sieohXOiuAGP5sLjUsPQ==","signatures":[{"sig":"MEUCIQDqOb3lfYwQdzlNzDcu1K8hhHoJOtjBL8iEt1vkXvkKMgIgBhXjVSHGyt5PlHwTTwaHVnVPE+nQHFyFE/OPtGhBpQY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48507},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"2bd6f67bb554e4b1726c005776f7632f3e63f3aa","scripts":{"demo":"tsx examples/demo.ts","test":"node --test --import tsx tests/safety.test.ts tests/edges.test.ts tests/trace.test.ts","build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"},"_npmVersion":"11.12.1","description":"AgentSonar integration for Open Multi-Agent (OMA) — bridges OMA task graphs and trace events to the AgentSonar coordination engine.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","typescript":"^5.6.0","@types/node":"^22.0.0","@jackchen_me/open-multi-agent":">=1.2.0"},"peerDependencies":{"@jackchen_me/open-multi-agent":">=1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/oma_0.1.1_1777172485219_0.033449064512743654","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@agentsonar/oma","version":"0.2.0","keywords":["multi-agent","observability","open-multi-agent","agentsonar","coordination"],"license":"Apache-2.0","_id":"@agentsonar/oma@0.2.0","maintainers":[{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"}],"homepage":"https://github.com/agentsonar/agentsonar-oma","bugs":{"url":"https://github.com/agentsonar/agentsonar/issues"},"dist":{"shasum":"ee7edcfad390470cf0434879ddd3aad5a341dbd6","tarball":"https://registry.npmjs.org/@agentsonar/oma/-/oma-0.2.0.tgz","fileCount":6,"integrity":"sha512-qJDZUTRnOapGJeGhgVLgj2HAXY7bH+t6MduC+vjL1Zc4gXVI/JlN+a1hngL3L7k0rUoiSRTTbS45i2zeruzpwQ==","signatures":[{"sig":"MEQCIHtZvkD3brOIHtSudvRRXf94wRXzqDVSAML/2Mb09HlWAiBnexNHVpghI0VTEuL6mCJfHjh4XVteU5xBePfI+N3sVQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66043},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"eb013641519a9764543d1cb93de27d588435876c","scripts":{"demo":"tsx examples/demo.ts","test":"node --test --import tsx tests/safety.test.ts tests/edges.test.ts tests/trace.test.ts tests/prevent.test.ts","build":"tsc","typecheck":"tsc --noEmit","prevent-demo":"tsx examples/prevent.demo.ts"},"_npmUser":{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"},"repository":{"url":"git+https://github.com/agentsonar/agentsonar-oma.git","type":"git"},"_npmVersion":"11.12.1","description":"AgentSonar integration for Open Multi-Agent (OMA) — bridges OMA task graphs and trace events to the AgentSonar coordination engine.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","typescript":"^5.6.0","@types/node":"^22.0.0","@jackchen_me/open-multi-agent":">=1.2.0"},"peerDependencies":{"@jackchen_me/open-multi-agent":">=1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/oma_0.2.0_1777437895502_0.4532659592297985","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@agentsonar/oma","version":"0.2.1","keywords":["multi-agent","observability","open-multi-agent","agentsonar","coordination"],"license":"Apache-2.0","_id":"@agentsonar/oma@0.2.1","maintainers":[{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"}],"homepage":"https://github.com/agentsonar/agentsonar-oma","bugs":{"url":"https://github.com/agentsonar/agentsonar/issues"},"dist":{"shasum":"b5a64df7d1888e558bf2c9bf65536b84914f58b2","tarball":"https://registry.npmjs.org/@agentsonar/oma/-/oma-0.2.1.tgz","fileCount":6,"integrity":"sha512-26PH2xjJZNtrsg1+gt7hQ3KnIN40Tn9c+5N+JSZhgkNYFVVYwc68bw3gyYbyilTk22wOvziGJyGEgLzIVc7p6Q==","signatures":[{"sig":"MEUCIB9mJPVaYlQuO+VpDfmALg/uyS8eKDQ4qROxZYqa9vFvAiEAgqrk2dQZ39A1/IheWqpbGu765xDmrW9ZQPvA7Ssk5JI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":66210},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"f2085dbf06a6c29b25cf066d017a61169e7a429b","scripts":{"demo":"tsx examples/demo.ts","test":"node --test --import tsx tests/safety.test.ts tests/edges.test.ts tests/trace.test.ts tests/prevent.test.ts tests/sidecar.test.ts","build":"tsc","typecheck":"tsc --noEmit","prevent-demo":"tsx examples/prevent.demo.ts"},"_npmUser":{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"},"repository":{"url":"git+https://github.com/agentsonar/agentsonar-oma.git","type":"git"},"_npmVersion":"11.12.1","description":"AgentSonar integration for Open Multi-Agent (OMA): bridges OMA task graphs and trace events to the AgentSonar coordination engine.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","typescript":"^5.6.0","@types/node":"^22.0.0","@jackchen_me/open-multi-agent":">=1.2.0"},"peerDependencies":{"@jackchen_me/open-multi-agent":">=1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/oma_0.2.1_1777610480259_0.6660007729670274","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@agentsonar/oma","version":"0.2.2","description":"AgentSonar integration for Open Multi-Agent (OMA) and any Node multi-agent bus: bridges agent-to-agent events to the AgentSonar coordination engine.","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","demo":"tsx examples/demo.ts","prevent-demo":"tsx examples/prevent.demo.ts","test":"node --test --import tsx tests/safety.test.ts tests/edges.test.ts tests/trace.test.ts tests/prevent.test.ts tests/sidecar.test.ts tests/record.test.ts","typecheck":"tsc --noEmit"},"engines":{"node":">=18"},"repository":{"type":"git","url":"git+https://github.com/agentsonar/agentsonar-oma.git"},"homepage":"https://github.com/agentsonar/agentsonar-oma","bugs":{"url":"https://github.com/agentsonar/agentsonar/issues"},"peerDependencies":{"@jackchen_me/open-multi-agent":">=1.2.0"},"devDependencies":{"@jackchen_me/open-multi-agent":">=1.2.0","@types/node":"^22.0.0","tsx":"^4.7.0","typescript":"^5.6.0"},"keywords":["multi-agent","observability","open-multi-agent","agentsonar","coordination"],"license":"Apache-2.0","gitHead":"a18e0d216641dfaa14e5c08c6c2a23b9f6513a43","_id":"@agentsonar/oma@0.2.2","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-w/h5DI1OSM0/S8uurB5WPpNIfROPgZZRFvz9dGkXKPveiNwDUxbFhSS4MXuMst3Ghov0FFW5yfHfwQ+qdrGVQw==","shasum":"4da4c0a08aba3437d1b98eb41042412ec16992eb","tarball":"https://registry.npmjs.org/@agentsonar/oma/-/oma-0.2.2.tgz","fileCount":6,"unpackedSize":74218,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDrr+5rAmCN4KiJZ5nLQ/6h7FIIwF6bvEa46FL7S0no1wIhANjKjVcV45miwzLh/sWJtTQbViE/DYwdbAHzr/OMRKqL"}]},"_npmUser":{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"},"directories":{},"maintainers":[{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/oma_0.2.2_1777790081893_0.18925156660425313"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-26T02:31:49.596Z","modified":"2026-05-03T06:34:42.143Z","0.1.0-alpha.1":"2026-04-26T02:31:49.847Z","0.1.0-alpha.2":"2026-04-26T02:39:28.596Z","0.1.0":"2026-04-26T02:57:53.442Z","0.1.1":"2026-04-26T03:01:25.360Z","0.2.0":"2026-04-29T04:44:55.670Z","0.2.1":"2026-05-01T04:41:20.400Z","0.2.2":"2026-05-03T06:34:42.040Z"},"bugs":{"url":"https://github.com/agentsonar/agentsonar/issues"},"license":"Apache-2.0","homepage":"https://github.com/agentsonar/agentsonar-oma","keywords":["multi-agent","observability","open-multi-agent","agentsonar","coordination"],"repository":{"type":"git","url":"git+https://github.com/agentsonar/agentsonar-oma.git"},"description":"AgentSonar integration for Open Multi-Agent (OMA) and any Node multi-agent bus: bridges agent-to-agent events to the AgentSonar coordination engine.","maintainers":[{"name":"srinivasycplf8","email":"srinivas.ycplf8@gmail.com"}],"readme":"# @agentsonar/oma\r\n\r\n**Your AI agents are burning money right now.**\r\n*Detect agent loops and runaway token spend during your OMA workflows. Stop them before the bill arrives.*\r\n\r\nAgentSonar integration for [Open Multi-Agent (OMA)](https://github.com/JackChen-me/open-multi-agent). Bridges OMA task dependencies and trace events to a local AgentSonar Python sidecar over HTTP, so cycles, repetition, and runaway throughput surface in real time as your workflow runs.\r\n\r\n> **New here?** The full AgentSonar guide (concepts, all four adapters, examples, FAQ) lives at [agentsonar/agentsonar/docs](https://github.com/agentsonar/agentsonar/tree/main/docs). This README focuses specifically on the OMA TypeScript adapter.\r\n\r\n## What it detects\r\n\r\nThree classes of multi-agent coordination failures, detected purely from the structure of your agent graph (no LLM is asked to evaluate anything):\r\n\r\n- **`cyclic_delegation`**: agent-to-agent delegation cycles that emerge across independent task chains or runs.\r\n- **`repetitive_delegation`**: the same delegation edge repeated past an exponential-decay threshold.\r\n- **`resource_exhaustion`**: per-edge throughput bursts beyond a sliding-window limit.\r\n\r\nOutput is a standalone HTML report at `agentsonar_logs/run-<slug>/report.html`.\r\n\r\n## How this complements OMA's runtime guards\r\n\r\nOMA blocks same-chain `A → B → A` cycles at delegate-tool time (`delegate.ts:60`). `@agentsonar/oma` catches the cumulative-graph patterns those guards don't see, cycles and repetition that emerge across independent chains or across runs.\r\n\r\n## Install\r\n\r\n```bash\r\n# TypeScript client\r\nnpm install @agentsonar/oma\r\n\r\n# Python sidecar dependency\r\npip install agentsonar\r\n```\r\n\r\nThe npm package ships with the Python sidecar script bundled at `node_modules/@agentsonar/oma/sidecar/sidecar.py`. Run it from there or copy it next to your app code:\r\n\r\n```bash\r\npython node_modules/@agentsonar/oma/sidecar/sidecar.py\r\n```\r\n\r\nRequirements: Node 18+, Python 3.10+.\r\n\r\n> **Heads up:** starting in `agentsonar` 0.4.0, the Python sidecar sends one anonymous session-start event per run (install ID, version, OS, adapter, no agent content). On by default, opt-out with `AGENTSONAR_TELEMETRY=off` or `DO_NOT_TRACK=1` in the sidecar's environment before starting it. [Full details](https://www.agent-sonar.com/telemetry).\r\n\r\n## Quickstart\r\n\r\n```ts\r\nimport { OpenMultiAgent } from '@jackchen_me/open-multi-agent'\r\nimport {\r\n  emitDelegations,\r\n  createTraceHandler,\r\n  shutdown,\r\n  type DelegationTask,\r\n} from '@agentsonar/oma'\r\n\r\nconst tasks: DelegationTask[] = [\r\n  { title: 'research', description: '...', assignee: 'researcher' },\r\n  { title: 'write',    description: '...', assignee: 'writer',\r\n    dependsOn: ['research'] },\r\n]\r\n\r\nconst orchestrator = new OpenMultiAgent({\r\n  defaultModel: 'gpt-4o-mini',\r\n  onTrace: createTraceHandler(),\r\n})\r\n\r\nconst team = orchestrator.createTeam('my-team', { /* ... */ })\r\n\r\nawait emitDelegations(tasks)            // emit delegation edges before the run\r\nawait orchestrator.runTasks(team, tasks)\r\nawait shutdown()                        // write the report and close the sidecar\r\n```\r\n\r\nThe sidecar must be running. The simplest setup is a separate terminal; for production, spawn it as a subprocess from your application.\r\n\r\n## Using outside OMA: event-driven buses (Electron, EventEmitter, custom orchestrators)\r\n\r\n`emitDelegations` is built around OMA's task-graph pattern (you pass a list of tasks with `dependsOn` arrays and it walks the DAG). For setups where agents communicate through a bus or EventEmitter in real time, the right primitive is `recordDelegation`. It takes one edge directly:\r\n\r\n```ts\r\nimport { recordDelegation } from '@agentsonar/oma'\r\n\r\nclass AgentBus extends EventEmitter {\r\n  send(from: string, to: string, message: unknown) {\r\n    this.emit(`agent:${to}`, { from, message })\r\n    // Fire-and-forget: never blocks the bus, never throws on network errors\r\n    recordDelegation(from, to).catch(() => {})\r\n  }\r\n}\r\n```\r\n\r\nThat's the whole integration. The sidecar still runs separately on `localhost:8787`, your Node app stays Node-only, and every coordination failure (cycles, repetition, cost spikes) shows up in the same HTML report.\r\n\r\nOptional metadata for breadcrumbs in the report:\r\n\r\n```ts\r\nrecordDelegation(from, to, {\r\n  metadata: { taskId: 'task-42', sessionId: 'sess-01', via: 'electron_bus' },\r\n}).catch(() => {})\r\n```\r\n\r\nSame safety contract as everything else in the package: never blocks longer than `timeoutMs` (default 2 s), silently swallows network errors, only `PreventError` propagates (and only when Prevent Mode is enabled on the sidecar).\r\n\r\n## Run the included demo\r\n\r\nTwo terminals.\r\n\r\n### Terminal 1: start the sidecar\r\n\r\n```bash\r\npython sidecar/sidecar.py\r\n```\r\n\r\nYou'll see:\r\n\r\n```\r\nAgentSonar OMA sidecar listening on http://localhost:8787\r\n  POST /ingest     delegation events\r\n  POST /trace      OMA trace events (stashed for cost work)\r\n  POST /shutdown   write report.html + exit\r\n  GET  /health     liveness + current counts\r\n```\r\n\r\n### Terminal 2: run the demo\r\n\r\n```bash\r\nexport OPENAI_API_KEY=sk-...\r\nnpm run demo\r\n```\r\n\r\nThe demo runs a 4-task workflow `researcher → reviewer → writer → researcher`, the last task is a fact-check returning to the same researcher. The task DAG is linear, but the agent graph forms a 3-node cycle. `CycleDetector` fires `cyclic_delegation` on the third edge.\r\n\r\nWhen the demo finishes, the sidecar prints the report path. Open it in a browser to see the graph and detected alerts.\r\n\r\n## What the output looks like\r\n\r\nEvery run produces a self-contained HTML report at `agentsonar_logs/run-<slug>/report.html`, no external CSS or JavaScript, no network requests, dark mode that respects your system preference. Two top-level tabs organize the view:\r\n\r\n**1. Coordination Failures**: the primary signal. One card per detected failure with severity badge, failure class (hover for a definition), fingerprint, and expandable topology / thresholds / provider-error / downstream-impact blocks. Filter chips at the top let you narrow to Critical or Warning with one click.\r\n\r\n![Coordination Failures tab: the primary signal, Sentry-style](docs/images/coordination-failures.png)\r\n\r\n**2. Session Activity**: INFO-level context, always one click away. Two sub-tabs switch between lenses on the same run:\r\n\r\n- **Edge Activity**: every delegation edge the graph saw, with fire count and severity attribution. Red border = edge involved in a critical alert, no border = clean.\r\n- **Chronological Log**: raw event stream with timestamps. Rows color-coded where an alert fired: light red for critical, light orange for warning.\r\n\r\n![Session Activity tab: Edge Activity view](docs/images/session-activity.png)\r\n\r\nThe \"Coordination Failures, Raw JSON\" drop-down at the bottom of every report carries the same payload as `report.json`, copy it straight into a dashboard or CI gate without opening a second file.\r\n\r\nAll four output files land in a per-run session directory under `agentsonar_logs/`:\r\n\r\n| File | Written | Purpose |\r\n|---|---|---|\r\n| `timeline.jsonl` | **Live, flushed on every event** | Every event, one JSON object per line. Tail with `tail -f` to watch what's happening as your OMA run progresses. |\r\n| `alerts.log` | **Live, flushed on every alert** | Signal-only, human-readable. The \"just show me the problems\" view. |\r\n| `report.json` | On `shutdown()` | Structured summary report, deduped + inhibited. Pipe into your dashboard. |\r\n| `report.html` | On `shutdown()` | The standalone two-tab HTML report shown above. |\r\n\r\n## Configuration\r\n\r\nTwo config surfaces.\r\n\r\n### TS client options (Node side)\r\n\r\nPassed on every `emitDelegations` / `createTraceHandler` / `shutdown` call, or via env var.\r\n\r\n| Option / env var | Default | Purpose |\r\n|---|---|---|\r\n| `endpoint` / `AGENTSONAR_ENDPOINT` | `http://localhost:8787` | Sidecar URL. |\r\n| `timeoutMs` | `2000` | Per-request HTTP timeout in ms. |\r\n| `debug` | `false` | Log wire activity to stderr. |\r\n\r\n### Detection thresholds (sidecar side)\r\n\r\nPass as CLI flags to the sidecar, or set env vars before starting it. Run `python sidecar/sidecar.py --help` for the full list.\r\n\r\n| Flag | Env var | Default | Controls |\r\n|---|---|---|---|\r\n| `--warning-threshold` | `AGENTSONAR_WARNING_THRESHOLD` | `5` | Rotations / events to fire WARNING |\r\n| `--critical-threshold` | `AGENTSONAR_CRITICAL_THRESHOLD` | `15` | Rotations / events to escalate to CRITICAL |\r\n| `--per-edge-limit` | `AGENTSONAR_PER_EDGE_LIMIT` | `10` | Max events on one edge in the window |\r\n| `--global-limit` | `AGENTSONAR_GLOBAL_LIMIT` | `200` | Max total events in the window |\r\n| `--window-size` | `AGENTSONAR_WINDOW_SIZE` | `180.0` | Rate-limiter sliding window in seconds |\r\n| `--half-life` | `AGENTSONAR_HALF_LIFE` | `180.0` | `repetitive_delegation` decay half-life |\r\n| `--z-score-threshold` |, | `3.0` | Z-score to fire `repetitive_delegation` |\r\n| `--resolve-after` |, | `60.0` | Seconds before alerts auto-resolve |\r\n| `--log-dir` | `AGENTSONAR_LOG_DIR` | `.` | Where `agentsonar_logs/` lands |\r\n| `--port` | `AGENTSONAR_PORT` | `8787` | Sidecar HTTP port |\r\n| `--no-console` |, |, | Suppress alert streaming to stderr |\r\n| `--no-report` |, |, | Skip the HTML/JSON report write |\r\n| `--report-title` | `AGENTSONAR_REPORT_TITLE` | `\"AgentSonar Report\"` | HTML report title |\r\n| `--prevent-cyclic-delegation` | `AGENTSONAR_PREVENT_CYCLIC_DELEGATION` | off | Enable Prevent Mode (see below) |\r\n| `--prevent-max-rotations` | `AGENTSONAR_PREVENT_MAX_ROTATIONS` |, | Trip Prevent Mode at exactly N rotations (overrides CRITICAL severity gating) |\r\n\r\nResolution order: CLI flag > env var > SDK default.\r\n\r\n**Example: tighter thresholds for testing**\r\n\r\n```bash\r\npython sidecar/sidecar.py --warning-threshold 1 --critical-threshold 2\r\n```\r\n\r\n**Example: alternate port**\r\n\r\n```bash\r\npython sidecar/sidecar.py --port 9100\r\n```\r\n\r\nThen on the Node side:\r\n\r\n```ts\r\nawait emitDelegations(tasks, { endpoint: 'http://localhost:9100' })\r\n```\r\n\r\n## Prevent Mode\r\n\r\nOpt-in \"circuit breaker\" mode. When enabled, the sidecar's coordination engine raises an exception in the TypeScript client if it detects a cycle that crosses the trip threshold, letting your code stop a runaway workflow before more tokens are spent.\r\n\r\n### How it works\r\n\r\n1. Start the sidecar with `--prevent-cyclic-delegation`.\r\n2. When a tracked failure (currently `cyclic_delegation`) crosses CRITICAL severity, the sidecar answers the next `/ingest` with HTTP 409 + RFC 7807 Problem Details (`Content-Type: application/problem+json`).\r\n3. The TS client detects this exact response shape and throws `PreventError` from `emitDelegations()` into your code.\r\n4. Every other failure mode (network errors, plain 409s, malformed responses, 500s) stays silently swallowed, only `PreventError` ever reaches your `try/catch`.\r\n\r\n### Quickstart\r\n\r\n```bash\r\n# Sidecar: enable Prevent Mode\r\npython sidecar/sidecar.py --prevent-cyclic-delegation\r\n```\r\n\r\n```ts\r\nimport {\r\n  emitDelegations,\r\n  shutdown,\r\n  PreventError,\r\n  type DelegationTask,\r\n} from '@agentsonar/oma'\r\n\r\nconst tasks: DelegationTask[] = [/* ... */]\r\n\r\ntry {\r\n  await emitDelegations(tasks)\r\n  await orchestrator.runTasks(team, tasks)\r\n} catch (e) {\r\n  if (e instanceof PreventError) {\r\n    console.log(`Stopped: ${e.reason}`)\r\n    console.log(`Cycle:   ${e.cyclePath.join(' -> ')}`)\r\n    console.log(`After:   ${e.rotations} rotations (severity ${e.severity})`)\r\n  } else {\r\n    throw e\r\n  }\r\n} finally {\r\n  await shutdown()\r\n}\r\n```\r\n\r\n### Custom trip threshold\r\n\r\nBy default Prevent Mode trips on CRITICAL severity (= `--critical-threshold` rotations, default 15). To trip earlier:\r\n\r\n```bash\r\npython sidecar/sidecar.py --prevent-cyclic-delegation --prevent-max-rotations 5\r\n```\r\n\r\nThis trips at exactly rotation 5 regardless of severity gating. Useful for tight test loops or production caps below the default CRITICAL threshold.\r\n\r\n### Wire format\r\n\r\nThe 409 response body follows [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) with an `agentsonar` extension namespace:\r\n\r\n```json\r\n{\r\n  \"type\": \"https://github.com/agentsonar/agentsonar/blob/main/docs/problems/coordination-prevented.md\",\r\n  \"title\": \"Coordination Failure Prevented\",\r\n  \"status\": 409,\r\n  \"detail\": \"cyclic_delegation prevented after 15 rotations: a -> b -> c\",\r\n  \"instance\": \"/ingest\",\r\n  \"agentsonar\": {\r\n    \"failure_class\": \"cyclic_delegation\",\r\n    \"severity\": \"CRITICAL\",\r\n    \"rotations\": 15,\r\n    \"cycle_path\": [\"a\", \"b\", \"c\"],\r\n    \"reason\": \"cyclic_delegation prevented after 15 rotations: a -> b -> c\",\r\n    \"timestamp\": 1714089600.123\r\n  }\r\n}\r\n```\r\n\r\nAdditional response headers:\r\n- `Cache-Control: no-cache, no-store`, discourage proxy caching of this informational state\r\n- `X-AgentSonar-Prevent: cyclic_delegation`, cheap observability hook for proxy/log inspection\r\n\r\n### Limitations\r\n\r\n- **Once tripped, the sidecar's tracked state stays tripped.** Subsequent `emitDelegations` calls keep throwing `PreventError`. To resume detection, restart the sidecar.\r\n- **Static-DAG cycles only, currently.** Prevent Mode trips on cycles visible at `emitDelegations` time, walked from the `dependsOn` graph. Cycles that emerge at runtime through the OMA orchestrator's `runTasks` are forwarded to `/trace` and stashed for future cost work, but they do not currently feed the detection engine. Wiring the runtime path into detection is on the roadmap.\r\n- **Sidecar must be reachable.** If the sidecar is down, `emitDelegations` warns once and continues, no `PreventError` is thrown because detection isn't running.\r\n\r\n## Sidecar lifecycle\r\n\r\nOne sidecar process = one observation session = one final report. The model is shaped for short-lived workloads (CLI tools, demos, batch jobs). Match your usage to one of these patterns:\r\n\r\n| Pattern | Setup |\r\n|---|---|\r\n| **One-shot script** (the demo, CLI tools) | Start sidecar in another terminal. Your script calls `shutdown()` at the end → sidecar writes the report and exits. |\r\n| **Long-running web server / app** | Start the sidecar once at process startup. Make many `runTasks` calls over its lifetime. Call `shutdown()` ONCE when your process exits, not between runs. All runs accumulate into a single report. |\r\n| **Multiple concurrent sessions** | Run a separate sidecar per session, each on a different port via `--port`. Each emits its own report. |\r\n\r\nIf you call `shutdown()` between runs, the next call has no sidecar to talk to and operates as if it were unreachable (silent no-op). The next run won't be observed unless you start a fresh sidecar first.\r\n\r\nThe sidecar is **stateless across restarts**: killing and restarting it loses the in-memory graph for the current session. There's no checkpointing in v1.\r\n\r\n## Architecture\r\n\r\nThe TypeScript client posts two kinds of events to the local Python sidecar over HTTP. The sidecar runs the AgentSonar detection engine and writes a self-contained run report.\r\n\r\n```mermaid\r\nflowchart LR\r\n    subgraph oma[\"Your OMA app (Node.js)\"]\r\n        traceFn[\"OpenMultiAgent<br/>onTrace handler\"]\r\n        emitFn[\"emitDelegations<br/>(walks dependsOn)\"]\r\n    end\r\n    subgraph py[\"AgentSonar sidecar (Python)\"]\r\n        engine[\"monitor_orchestrator()<br/>engine\"]\r\n        layers[\"Detection layers:<br/>cycle / repetitive<br/>rate / SCC\"]\r\n        out[\"agentsonar_logs/<br/>run-&lt;slug&gt;/<br/>report.html<br/>report.json\"]\r\n    end\r\n    traceFn -- \"POST /trace\" --> engine\r\n    emitFn -- \"POST /ingest\" --> engine\r\n    engine --> layers\r\n    layers --> out\r\n```\r\n\r\nThe TypeScript client is fire-and-forget. Every HTTP call has a 2-second timeout, every public function wraps its body in try/catch, and every fetch failure is swallowed silently (with a single console warning the first time the sidecar is unreachable). If the sidecar is down, slow, or throwing, the OMA run completes normally without observability, never with a crash. This invariant is enforced by the test suite (`npm test`).\r\n\r\n## Links\r\n\r\n- **AgentSonar full docs**: [github.com/agentsonar/agentsonar/docs](https://github.com/agentsonar/agentsonar/tree/main/docs) (concepts, all four adapters, configuration reference, FAQ, examples)\r\n- **AgentSonar**: [GitHub](https://github.com/agentsonar/agentsonar) · [PyPI](https://pypi.org/project/agentsonar/) · [npm `@agentsonar/oma`](https://www.npmjs.com/package/@agentsonar/oma)\r\n- **Open Multi-Agent**: [GitHub](https://github.com/JackChen-me/open-multi-agent) · [npm `@jackchen_me/open-multi-agent`](https://www.npmjs.com/package/@jackchen_me/open-multi-agent)\r\n- **Issues / feature requests**: [agentsonar/agentsonar issues](https://github.com/agentsonar/agentsonar/issues)\r\n\r\n## License\r\n\r\nApache-2.0\r\n","readmeFilename":"README.md"}