mirror of
https://github.com/JackChen-me/open-multi-agent.git
synced 2026-10-19 01:29:57 -05:00
Jack Chen
d4084ef803
* fix(core): resolve dangling symlinks in the filesystem sandbox check The sandbox resolver treated a dangling symlink as a path that does not exist yet, so the containment check passed on the link's own location and file_write then created the link's target, which could be outside the agent's working directory. The resolver now follows a dangling symlink to the target it names, rejects targets outside the root, keeps in-root targets writable, and bounds resolution at 40 hops so a loop fails the check. Addresses GHSA-h42w-g3ch-rjjm (CVE-2026-108600). * fix(core): fail the sandbox check when realpath reports ELOOP A symlink chain longer than the kernel's link limit made realpath fail with ELOOP, and the resolver then followed the first link by hand and resolved the rest, accepting a path the kernel itself refuses. ELOOP from realpath now fails the check, and the resolver's own hop limit stays as the bound for links it follows by hand. * fix(core): resolve symlink targets one component at a time Following a dangling symlink, the resolver normalized the target with path.resolve, which collapses a/.. lexically. When a is itself a symlink the kernel steps out of the directory a points to, so a target such as pivot/../created.txt resolved to a different file than a write through the link would create. The resolver now walks the target component by component, following symlinks before applying .., and fails when .. would step out of a missing directory, as the kernel does. The previous test for a self-referencing target built the link with path.join, which folded ghost/../self to self, so it only exercised a plain loop. Link targets in these tests are now joined without normalization. * fix(core): keep the directory requirement of a trailing separator in symlink targets A symlink target ending in a separator or "." names a directory, so the kernel refuses to open or create a file through it. The resolver dropped those components, and native realpath does the same on macOS, so a link to victim/ resolved to the file victim and file_write overwrote it. The resolver now requires an existing directory at the end of such a target, and confirms each realpath result with stat, which takes the same lookup as open, before trusting it.
Documentation
Every page under docs/, grouped by what you are trying to do. Each line says
which question the page answers, so you can pick one without opening five.
Start here
| Page | What it answers |
|---|---|
| Core package guide | What are the three execution modes, and how do I get a team running? |
| Examples | Which runnable script is closest to what I am building? |
| Glossary | What does OMA mean by coordinator, task, run, span, gate, or budget? |
| Production checklist | Which defaults are deliberately permissive, and what must I decide before going live? |
Configure models and tools
| Page | What it answers |
|---|---|
| Providers | Which providers are built in, what credentials do they need, and how do I point one at a local or OpenAI-compatible endpoint? |
| LLM egress policy | Which network requests can OMA restrict before an adapter opens them, and which are outside that boundary? |
| Self-hosting and data residency | What does the framework run, reach, and persist when it runs on my own infrastructure? |
| Tool configuration | How are built-in, custom, and delegation tools granted, filtered, and gated per call? |
| Sandbox and shell execution | Where can a filesystem tool reach, and where does a granted bash command actually run? |
| MCP tools | What does connectMCPTools() do, and which OMA controls extend into the MCP child process? |
| Image generation and editing | How do I generate or edit an image across a fallback chain of image models, and what does each attempt record? |
| Structured agent input | How do I pass caller-owned conversation history, images, or files instead of a single prompt string? |
| External agents | How do process and ACP backends put coding CLIs on the same task DAG, and what stops applying to them? |
Control orchestration
| Page | What it answers |
|---|---|
| Coordinator | What does the planning agent decide, what does it see, and how do I configure or replace it? |
| Task scheduling and dispatch | In what order do tasks run, how do dependency payloads reach them, and what happens on retry, approval, or abort? |
| Execution routing | Should an automatic runTeam() call use one agent or a coordinator-built team plan? |
| Model routing | How do I send planning and leaf work to different models without changing the team? |
| Consensus | How do judge agents verify an answer, and what does a quorum cost against the budget? |
| Plan preview and replay | How do I freeze a coordinator plan as reviewable data and replay it without planning again? |
| Adaptive recovery | When may a run revise the not-yet-executed part of its own graph? |
| Durable approval gates | How does a run suspend at an approval boundary and resume from the same reviewed content after a restart? |
| Hooks and callbacks | Which function-typed field fires when, in which run mode, and what can its return value change? |
| Shared memory | How do agents read each other's findings, and which store backs that? |
| Streaming | Which APIs return incremental output, what does each StreamEvent carry, and which paths never stream? |
| Budgets and limits | Which ceilings bound a run, where are they checked, and what happens when one trips? |
Operate
| Page | What it answers |
|---|---|
| Observability | What do progress events, trace spans, and stores record, and what does telemetry cost? |
| Run Viewer | How do I render one finished run as a self-contained page with a task DAG and span waterfall? |
| Run event journal | What exactly did each agent see at the moment it was asked, and can that be verified offline? |
| Checkpoint and resume | How does an interrupted run resume without repeating completed work? |
| Run store and execution leases | Which worker owns a run, and what stops two of them from advancing it at once? |
| Context management | How does a long conversation shrink as it grows, and what happens to reasoning blocks? |
| Evaluation | How do EvalSets, scorers, and stores measure quality without changing the business result? |
| Evaluation in CI | How do I turn an EvalSet into a pass/fail signal a CI job can act on? |
| Routing evaluation | Which frozen EvalSets guard routing decisions, and what would let a routing regression through? |
| Migrating to Observability v2 | How do I move an onTrace integration to the v2 path one layer at a time? |
| Errors | Which error class is this, who raised it, and does a retry help? |
| CLI | Which oma subcommands exist, what JSON do they print, and which exit codes do they use? |
Partners
| Page | What it answers |
|---|---|
| Featured Partner program | What does a featured placement in the project README include, and who qualifies? |
| Atlas Cloud setup guide | How do I configure the Atlas Cloud provider sponsor's endpoint and credentials? |
| Atlas Cloud 接入指南 | Chinese translation of the Atlas Cloud setup guide. |
Internal records
internal/ holds engineering records kept for
auditability, such as benchmark snapshots and release-readiness reviews. They
describe a specific point in time on specific hardware and are not user
documentation; nothing there is a supported contract.