Systematic documentation review: 12 new docs pages (coordinator, streaming, budgets and limits, errors, hooks and callbacks, glossary, production checklist, Run Viewer, MCP, sandbox and shell, evaluation in CI, routing evaluation) plus a docs index; the three longest guides split with stub sections that keep existing anchors; observability release records moved to docs/internal; statements re-verified against the code and corrected; READMEs, AGENTS.md, CONTRIBUTING.md, and issue templates synced. Documentation only, no behavior change.
* feat(core): add unified run viewer
* feat(cli): export run viewer from trace store
* docs(core): add deterministic run viewer demo
* fix(examples): resolve workspace paths in typecheck
* fix(dashboard): center detail status labels
* fix(dashboard): remove DAG status rails
* fix(dashboard): enlarge DAG task cards
* fix(dashboard): clarify run summary header
* docs: align readmes with run viewer
Error-aware task retry (opt-in via maxRetries > 0):
- Skip retries on provably-terminal failures (4xx client errors except
408/409/429, token-budget, invalid-message, aborted calls).
- Equal jitter on backoff to avoid lockstep retries against a rate-limited
provider.
- Honor abortSignal between attempts (no full-backoff sleep or extra attempt
after cancel).
- Non-streaming path preserves the structured error on AgentRunResult.error so
classification works off the default runTeam path; test-covered.
Off by default; behavior changes only when retry is enabled.
Closes#337
* 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/.
Sandbox default root narrows from `process.cwd()` to `<cwd>/.agent-workspace`, an auto-created subdirectory. Built-in filesystem tools (`file_read`, `file_write`, `file_edit`, `grep`, `glob`) enforce this root and require absolute paths. `bash` is intentionally out of scope; full caveat and the three-config knob (default / `process.cwd()` / `null`) live in `docs/tool-configuration.md`.
`defaultWorkspaceDir()` centralises the fallback; `OrchestratorConfig.defaultCwd`, `AgentConfig.cwd`, `RunnerOptions.cwd`, and the tool-layer fallbacks in `path-safety`, `grep`, and `glob` all route through it. Only `file_write` auto-creates the root via `resolvePathWithinCwd`'s new `ensureRoot` option; read-only tools error on a missing root.
22 examples switched from `/tmp/` to `<cwd>/.agent-workspace/<sub>` (basics x 3, providers x 18, integrations x 1). `mcp-bilig-workpaper` routes its existing tmpdir workDir into the Agent's `cwd`.
`README.md`, `README_zh.md`, `docs/tool-configuration.md`, `docs/cli.md`, `docs/providers/minimax.md` updated. JSDoc on the four `cwd` fields aligned with the new default. `.gitignore` ignores `.agent-workspace/`.
`v1.4.2` is current on npm; no released version is affected. Consumers wanting the prior `process.cwd()` default can set `defaultCwd: process.cwd()` explicitly.
Sandbox built-in filesystem tools (`file_read`, `file_write`, `file_edit`, `grep`, `glob`) to a per-agent working directory. Paths must be absolute and resolve inside that directory; symlinks are resolved via `realpath` before the check and skipped during recursive walks via `lstat`. New config: `AgentConfig.cwd`, `OrchestratorConfig.defaultCwd`, `CoordinatorConfig.cwd` (per-agent override > orchestrator default > `process.cwd()`).
`bash` is deliberately not sandboxed; pass `disallowedTools: ['bash']` if path containment matters. Process-group cleanup is now in place so backgrounded children no longer outlive timeouts or aborts; aborted runs exit 130.
`mcp.ts` forwards `ToolUseContext.abortSignal` into `callTool` so MCP tools observe agent cancellations.
`resolvePathWithinCwd` returns the realpath-resolved candidate (rather than the raw input) so callers hand a symlink-free path to fs APIs, closing the TOCTOU window between the sandbox check and the fs call. The new `realpathTolerant` helper handles non-existent paths (e.g. `file_write` creating a new file) by resolving the longest existing prefix and re-attaching the suffix.
**Behavior change.** Sandbox is on by default. Agents that previously read or wrote files outside \`process.cwd()\`, or used relative paths, now get a sandbox error. Set \`OrchestratorConfig.defaultCwd\` to your workspace root for multi-directory deployments, or pass \`defaultCwd: null\` to restore unrestricted access.
First-class `provider: 'mimo'` backed by the OpenAI-compatible adapter, defaulting to https://api.xiaomimimo.com/v1 and MIMO_API_KEY. Token Plan keys (tp-*) read MIMO_BASE_URL for the cluster URL.
Overrides `echoesReasoning` to 'tool-use-only' so tool-calling agents replay reasoning_content correctly, matching DeepSeek V4 (#251).
Refs #25.
* fix: redact secrets in traces, bash env, and dashboard payloads
Adds src/utils/redaction.ts and applies best-effort redaction at three
sinks where sensitive data could leak:
- tool_call trace events (input, output)
- the bash tool's output buffer
- the post-run dashboard's embedded JSON payload
The bash tool no longer inherits the parent process.env. Child processes
receive a fixed allowlist (HOME, LANG, LC_ALL, LOGNAME, PATH, SHELL,
TEMP, TERM, TMP, TMPDIR, USER), so provider API keys and similar
secrets are no longer visible to spawned shells.
The post-run dashboard no longer loads Tailwind CDN, Google Fonts, or
Material Symbols at view time. The page is self-contained and renders
without network access.
llmMessagesToAiSdkModelMessages no longer concatenates the opaque
redactedData payload into the reasoning text emitted to the AI SDK; it
emits only the [redacted_thinking] marker.
The MCP GitHub example uses --no-install instead of -y and passes an
explicit env allowlist instead of spreading process.env.
* fix(redaction): consume full value for quoted and unquoted assignments
The single ASSIGNMENT_PATTERN stopped at the first whitespace inside a
value, so values with spaces were only partially redacted and the
remainder leaked into trace events, dashboard payloads, and the bash
output buffer. Three reviewer-reported cases on PR #263:
password=secret value -> password=[redacted] value
password="secret value" -> password="[redacted]" value"
apiKey: "abc def" -> apiKey: "[redacted]" def"
Splits the single pattern into two passes. The quoted pass consumes
to the back-referenced closing quote so password="my pass" is fully
matched. The unquoted pass consumes to the next structural delimiter
(comma, semicolon, brace, bracket, newline) so password=my pass is
fully matched.
Adds tests/redaction.test.ts covering the three reviewer cases, the
existing Authorization orphan-bracket regression, common token literal
patterns, and idempotence.
First-class `provider: 'doubao'` backed by the OpenAI-compatible adapter, defaulting to the Volcengine Ark endpoint and ARK_API_KEY env var.
Refs #25 (Doubao section). Original first-class attempt in #236 closed under the duplicate-claim rule when #232 was active.
Mirrors the DeepSeek provider coverage for Qiniu, landing after #154:
- README quick-start env list, Multi-model teams bullet, architecture
diagram, providers table (Verified), first-class support note, and
usage snippet with official Qiniu AI inference docs link
- docs/cli.md `oma provider template` list
- examples/providers/qiniu.ts modeled on examples/providers/deepseek.ts
* feat: expose custom MemoryStore via TeamConfig.sharedMemoryStore (#156)
The MemoryStore interface was already public, and SharedMemory / TeamInfo
already used the interface internally. This adds the final user-config wire
so integrators can attach custom backends (Redis, Postgres, Engram, etc.)
without hacking SharedMemory private fields.
Priority: sharedMemoryStore > sharedMemory: true > no memory.
Fully backward-compatible: existing sharedMemory: true users see no change.
SDK-only: the CLI cannot pass runtime objects through JSON config.
Closes#156.
* fix: validate sharedMemoryStore shape and reject from CLI JSON
Addresses Codex P2 review on #157. Plain objects from untrusted JSON could
previously reach `new SharedMemory(plainObject)` and crash later on the first
`.set`/`.list` call with a cryptic TypeError.
Defense-in-depth:
- SharedMemory constructor performs a runtime shape check and throws a clear
TypeError if the provided store does not implement get/set/list/delete/clear.
- CLI `asTeamConfig` explicitly rejects `sharedMemoryStore` in JSON with a
message pointing to the SDK path, since this field is documented SDK-only.
Adds 4 tests covering malformed stores (plain object, partial interface,
null, Team constructor path).
* fix: route falsy-but-present sharedMemoryStore through shape check
Addresses Codex finding 2 on #157. The truthy gate silently skipped falsy
values (null, 0, ''), letting config bugs downgrade to the default in-memory
store or no memory instead of failing fast.
Switched to `!== undefined` so any present value reaches SharedMemory's
runtime shape check and throws a clear TypeError. Adds 2 tests: null as a
bogus store throws; omitting the field still honors `sharedMemory: true`.
Adds `oma run --dashboard` to write a static post-execution DAG HTML to `oma-dashboards/runTeam-<timestamp>.html`.
- Pure `renderTeamRunDashboard(result: TeamRunResult)` in `src/dashboard/`, no FS/network I/O in the library
- `TeamRunResult` gains `goal` + `tasks: TaskExecutionRecord[]` (with `TaskExecutionMetrics`)
- `layoutTasks()` extracted as pure function with cycle detection
- XSS mitigations: `application/json` payload, `</script>` escape, `textContent`-only node rendering
- CLI awaits write before exit (no race with `process.exit`)
Closes#4
Co-authored-by: Ibrahim Kazimov <74775400+ibrahimkzmv@users.noreply.github.com>
Jack Chen