README
E
JournalCorrupted
E
WorkflowError
- ::AgentAttemptAgentAttempt::AgentAttempt
- ::AgentCallAgentCall::AgentCall
T
AgentDisposition
T
AgentFailure
- ::attemptAgentOutcome::attempt
- ::in_memoryJournal::in_memory
- ::loadJournal::load
- ::priorJournal::prior
- ::recordedJournal::recorded
- ::JournalEntryJournalEntry::JournalEntry
T
ReplayDecision
- ::RunnerRunner::Runner
- ::invokeRunner::invoke
- ::WorkflowWorkflow::Workflow
- ::agentWorkflow::agent
- ::agent_asWorkflow::agent_as
- ::agent_callWorkflow::agent_call
- ::calls_madeWorkflow::calls_made
- ::calls_replayedWorkflow::calls_replayed
- ::cost_usdWorkflow::cost_usd
- ::phaseWorkflow::phase
- ::tokens_spentWorkflow::tokens_spent
T
WorkflowEvent
V
all_ok
V
attempt
V
collect_ok
V
fan_out
V
parallel
V
retry
V
worth_retrying

scout

A small executable showing how to connect a workflow to an external engine, fan out calls, handle typed failures, and replay a journal. It supports native and wasm and exports no library API. Read main.mbt as a complete example of workflow with spawn.

#Run the keyless probe

From the repository root, give it an executable that accepts OpenSeek's run --input-format json --cancel-on-stdin-eof --kind <kind> --result-file<path> and speaks the child contract. For example, with OpenSeek installed:

moon run examples/scout -- /absolute/path/to/openseek --journal scout.jsonl
moon run examples/scout -- /absolute/path/to/openseek --journal scout.jsonl

The first run launches three echo children for alpha, beta, and gamma. The second run serves their successful reports from the same journal. Its final summary should show zero new children, three replays, and zero fresh tokens. Failures other than Skipped are attempted again.

The published form is:

moonx moonbitlang/workflow/examples/scout /absolute/path/to/openseek --journal scout.jsonl

The engine is external: this example does not install or build it. Although the contract is engine-independent, the example's argv builder assumes OpenSeek's run command and flags. It cannot point directly at the Claude or Codex shim; use their documented LaunchSpec instead.

#Run a model-backed scout

moon run examples/scout -- /absolute/path/to/openseek --kind explore --journal explore.jsonl

Any non-echo kind takes the single-scout path. Its prompt asks where openseek run --kind dispatches its presets, with a hint to internal/openseek/run and a step request of 24. Run it with the intended source tree as the engine's working directory; the published command can be invoked from that tree. The engine inherits the working directory and provider credentials from the environment. Model-backed calls may incur usage charges.

Argument	Default and behavior
engine	Required executable path or name.
--journal PATH	Optional persistent journal; otherwise in memory.
--kind KIND	echo; only this kind fans out the three keyless probes.
--model NAME	Optional --model flag passed to the engine.

The request carries kind and any max_steps; the launcher also names the kind on argv (OpenSeek checks the two agree) and forwards the chosen model. It uses the runner's default 10-minute deadline, workflow concurrency 4, and a maximum of 16 live calls. Those settings are in source, not command-line options.

#Execution and output

flowchart TD
  Start["Load journal or create an in-memory journal"] --> Kind{"kind is echo?"}
  Kind -->|Yes| Probes["Fan out alpha, beta, gamma"]
  Kind -->|No| Scout["One repository scout, max_steps 24"]
  Probes --> Call["Workflow: replay or launch through spawn"]
  Scout --> Call
  Call --> Result["attempt: one Result per call"]
  Result --> Print["Print reports or failures, then usage summary"]

Launches print ▶ label; replay hits print ↺ label (replayed). Each result prints a report: JSON value or FAILED: message. The final line reports live calls, replay count, and fresh token usage. A typed agent failure is printed and does not by itself crash the example; cancellation and infrastructure errors still propagate. Do not use a successful process exit alone as proof that every agent returned a report.

Only calls and outcomes are durable, not arbitrary program side effects. The example uses an empty replay scope and does not include the model or working tree revision in its call identity. Use a new journal when changing those settings, or add an appropriate replay_scope when adapting the code.

Render its journal with:

moon run viz -- scout.jsonl scout.html

See viz for what the report can infer from completed calls.

moon run examples/scout --target native -- --help
moon check examples/scout --target native
moon check examples/scout --target wasm

This directory is a normal package and uses the local module when run from the repository. The adjacent .mbtx scripts, including simplify.mbtx and compose.mbtx, instead bind the published module without a version pin. They are separate programs: moon test does not compile them, and moon check <script.mbtx> does not validate them. Use moon run <script.mbtx> to execute those examples with their required engines and credentials.