0 Fork 0

mirror of https://github.com/JackChen-me/open-multi-agent.git synced 2026-10-19 01:29:57 -05:00

Files

T

Jack Chen e36cd1f4c0 feat(core): add authoritative run store and execution leases (#587 )

A checkpoint records what a run can resume from, not who is allowed to
advance it. Two processes can restore the same snapshot and both continue
it, and a worker that stalled past its own liveness can wake up and
overwrite the state a replacement has since written.

Add an opt-in `runStore`: one authoritative, versioned record per logical
run holding its lifecycle status, execution lease, and a monotonic fencing
token.

- `RunRecord` keeps `version` for optimistic concurrency and `fencingToken`
  for ownership, so a worker holding an old token stays detectable across
  any number of unrelated writes. Legal transitions are enumerated and
  terminal statuses have no outgoing edge.
- `RunStore` is three methods plus an explicit `atomicity` declaration.
  Lease expiry, fencing, transition legality, and command idempotency live
  above the seam in `RunLedger`, so a Postgres or Redis backend reproduces
  storage semantics rather than a state machine.
- `MemoryStoreRunStore` adapts any `MemoryStore` with compare-and-set and
  defaults to `atomicity: 'process'`. `FileStore` remains the sequential
  restart reference store and is not presented as a lease backend.
- The orchestrator acquires the lease before it dispatches, fences every
  checkpoint write with its token, stops the run at the dispatch gate when
  the lease is lost, and records the terminal transition. A worker that
  lost its lease writes no terminal status and never reports success.
- `restore()` is the resume command: it makes a suspended record eligible
  and takes ownership before reconciling the approval ledger.

Ownership and lifecycle writes fail closed rather than inheriting the
best-effort semantics of checkpoint and telemetry writes. With no run store
configured, existing single-process checkpoint and restore behavior is
unchanged.

Ships a reusable `RunStore` conformance suite covering create races,
version-matched compare-and-set, lease expiry, takeover, stale-writer
rejection, and terminal closure, so an out-of-repository backend can prove
the same contract.

Closes #481

2026-09-07 02:35:32 +08:00

5.7 KiB

Raw Blame History

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?
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.

5.7 KiB Raw Blame History