Jack Chen
1d37ce6026
* refactor(repo): monorepo groundwork for an easier first run Trying OMA for the first time costs more than it should: a lot to read before anything runs, and no one-command way to watch a team actually work. The plan is to fix that with a `npm create oma` scaffold (a multi-agent demo that runs on the first try) and an npm README that leads with getting started. Neither lands cleanly until core lives in its own package, so this PR does that part first. This is groundwork, not the payoff: nothing changes for anyone installing `@open-multi-agent/core` today. It turns the repo into an npm-workspaces monorepo with core in `packages/core/`, and splits the README into a GitHub landing page (root) and the npm package page (`packages/core/`). Doing it now, while the repo is small, avoids migrating twice. The published package is byte-identical: same name, same three runtime dependencies, same entry points, guarded by an isolated-install smoke test. `npm ci` + lint + test (1060) + build pass; the tarball still ships only `dist/`, `README.md`, `LICENSE`, and `package.json`. * build: restore cross-platform optional deps in package-lock.json Regenerating the lockfile on macOS pruned the non-host rollup/esbuild optional binaries (npm/cli#4828), so Linux CI could not load @rollup/rollup-linux-x64-gnu and vitest failed to start. Rebuild the lock from the pre-migration base so every platform variant is present again. Verified with npm ci + lint + build + test (1060). * fix(examples,docs): correct monorepo paths and anchors after the packages/core move with-vercel-ai-sdk example (pre-existing, surfaced by the move): - package.json: the @open-multi-agent/core file: link was file:../../, which resolves to packages/core/examples (no manifest). Corrected to file:../../.. (packages/core); predev cd updated to match. - package-lock.json regenerated: was linking ../.. and pinning a stale core 1.4.0; now links ../../.. at 1.7.0. - README: setup paths and the file: note updated. docs missed by the move: - docs/cli.md: repo-clone build output is now packages/core/dist/cli/oma.js; the quick-start anchor now lives in the package README. - CONTRIBUTING.md: the architecture anchor and src/ entry-point paths now live under packages/core/.
2.2 KiB
Observability
open-multi-agent exposes three telemetry layers: live progress events, structured trace spans, and a static post-run dashboard.
Progress Events
Use onProgress when you need lightweight lifecycle events for logs, terminal output, or a live UI.
const orchestrator = new OpenMultiAgent({
onProgress: (event) => {
console.log(event.type, event.task ?? event.agent ?? '')
},
})
Common event types include task_start, task_complete, task_retry, task_skipped, agent_start, agent_complete, budget_exceeded, and error.
Trace Spans
Use onTrace when you need structured spans for LLM calls, tool executions, and tasks. Each span carries parent IDs, durations, token counts, and best-effort-redacted tool I/O.
const orchestrator = new OpenMultiAgent({
onTrace: async (span) => {
await traceSink.write(span)
},
})
Forward trace spans to OpenTelemetry, Datadog, Honeycomb, Langfuse, or your own run database only after deciding what data is safe for that sink. See integrations/trace-observability for a runnable example.
Post-Run Dashboard
renderTeamRunDashboard(result) returns a static HTML page that visualizes the executed task DAG with timing, token usage, per-task status, and task details.
import { writeFileSync } from 'node:fs'
import { renderTeamRunDashboard } from '@open-multi-agent/core'
const result = await orchestrator.runTeam(team, goal)
writeFileSync('run.html', renderTeamRunDashboard(result))
The library does not write files by itself. The CLI can write dashboard HTML for you with oma run --dashboard; see docs/cli.md.
The generated dashboard is self-contained and does not load remote scripts, stylesheets, or fonts. Sensitive-looking values in the embedded run payload are redacted before rendering.
What to Persist
For production runs, persist enough data to reconstruct a failure without replaying the entire job:
TeamRunResult.tasksfor the executed DAG and task states.TeamRunResult.totalTokenUsagefor cost attribution.onTracespans for LLM calls and tool executions.- The rendered dashboard HTML when you need a shareable post-mortem artifact.