Agent Interface

Agents operate WorldFork through the worldfork CLI. The CLI is backed by /api/agent/* and the canonical runtime APIs.

Rules

  • Start with worldfork agent discover and worldfork status.

  • For first-time setup or Atlas onboarding, run worldfork setup and use it to explain provider/model options before asking the user which providers to configure.

  • Do not hardcode backend host URLs. Use the CLI default, --base-url, WORLD_FORK_API_BASE, or BACKEND_API_BASE.

  • Put global flags before the command.

  • Use --verbosity summary first.

  • Use --fields a,b,c when only selected top-level fields are needed.

  • Use bounded waits for jobs.

  • Prefer watch for live run state instead of repeated ad hoc queries.

  • Treat reports as structured database records; Markdown/PDF outputs are artifacts for a report version.

Discovery

worldfork agent discover
worldfork status
worldfork setup

agent discover returns the schema version, supported verbosity tiers, recommended command flow, known job types, scenario metadata, and service metadata. setup returns the provider-choice map and the recommended Atlas split: cheap, fast models for high-volume cohort/timeline work and stronger models for initialization, God review, endpoint-ledger evaluation, and reports.

Context Control

Use summary output first:

worldfork --verbosity summary runs list
worldfork --verbosity summary runs workspace <big-bang-id>

Project large rows when a task only needs a few fields:

worldfork --fields id,status,created_at jobs list
worldfork --fields id,status,name runs list

Emit JSON when another tool will parse output:

worldfork --json status

Create And Watch

worldfork init --name "<name>" --scenario-file <scenario.md>
worldfork watch big-bang <big-bang-id>
worldfork watch multiverse <multiverse-id>

init waits for initialization to complete, then returns the initialized workspace plus initialization artifacts and state. watch streams workspace, tick, tool-call, and log updates until the selected target is terminal.

Use machine-readable event streams when an agent needs to consume watch output:

worldfork watch big-bang <big-bang-id> --json-lines

Initialization is blocking for the standard CLI path. It returns after the backend has created the root multiverse, T0 state, initializer artifacts, population-aware cohorts, graphs, initial events, and endpoint ledger seed. See Runtime Walkthrough when you need the exact initializer output contract.

Jobs

worldfork jobs list --status failed
worldfork jobs wait <job-id> --timeout 300 --poll-interval 2
worldfork jobs pause <job-id>
worldfork jobs resume <job-id>
worldfork jobs interrupt <job-id>
worldfork jobs requeue <job-id>
worldfork jobs run <job-id>

If a command enqueues long work, capture the job ID and use a bounded wait. Do not spin forever.

Runtime Inspection

worldfork runs list
worldfork runs workspace <big-bang-id>
worldfork multiverses trace <multiverse-id>
worldfork cohorts transcript <cohort-id> --multiverse-id <multiverse-id>
worldfork ticks timing <tick-snapshot-id>
worldfork ticks cost <tick-snapshot-id> --include-calls
worldfork runs cost <big-bang-id> --include-calls
worldfork runs estimate <big-bang-id>
worldfork logs list --status failed
worldfork models defaults
worldfork settings show
worldfork update --dry-run

Use ticks timing to answer “what stage is the tick at?” and “what was the blocker?” It exposes runtime executions, checkpoint timings, attempt timings, LLM timing, and cost summaries.

Reports

worldfork reports list <big-bang-id>
worldfork reports versions <report-id>
worldfork reports view <report-version-id>
worldfork reports view <report-version-id> --format json
worldfork reports render <report-version-id> --format pdf --output report.pdf
worldfork reports pack <big-bang-id> --mode summary
worldfork reports adjudicate <big-bang-id>
worldfork reports adjudication <big-bang-id>
worldfork ledgers list <big-bang-id>
worldfork ledgers path-mass <big-bang-id>

Use reports view before rendering a PDF. Rendering is ephemeral and does not change the canonical report version.

Report generation is split across audited LLM routes. predicate_extractor, predicate_resolver, and single_report_agent can run on the fast default model, while final_report_agent uses final_report_agent_model and a higher budget for final cross-timeline synthesis. Inspect or override these through worldfork models defaults and /api/settings/model-routing.

Endpoint ledgers answer endpoint status questions. Path mass answers how much retained branch probability sits behind those endpoint statuses. Do not treat an endpoint ledger entry as the same thing as branch probability.

Direct API Escape Hatch

Use query only when a first-class CLI command does not exist:

worldfork query GET /api/agent/discover
worldfork query GET /readyz --no-api-prefix

Live Runs

Use the configured model split for live validation. The default policy keeps high-volume calls on OpenRouter DeepSeek Flash and uses OpenAI Codex gpt-5.4 for initializer, God review, endpoint ledgers, report fallback, and final synthesis:

openrouter/deepseek/deepseek-v4-flash
openai-codex/gpt-5.4

Full live smoke:

worldfork smoke live

Atlas onboarding:

worldfork demo atlas

Atlas is a demonstration, not a minimal smoke test. It runs a larger branching simulation, drains terminal timelines, generates per-multiverse reports, and generates a final cross-multiverse report-agent summary. When running it for a new user, narrate the phases and explain how to inspect any printed Big Bang, multiverse, job, log, or report IDs.