# 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 ```bash 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: ```bash worldfork --verbosity summary runs list worldfork --verbosity summary runs workspace ``` Project large rows when a task only needs a few fields: ```bash worldfork --fields id,status,created_at jobs list worldfork --fields id,status,name runs list ``` Emit JSON when another tool will parse output: ```bash worldfork --json status ``` ## Create And Watch ```bash worldfork init --name "" --scenario-file worldfork watch big-bang worldfork watch multiverse ``` `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: ```bash worldfork watch big-bang --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](runtime.md) when you need the exact initializer output contract. ## Jobs ```bash worldfork jobs list --status failed worldfork jobs wait --timeout 300 --poll-interval 2 worldfork jobs pause worldfork jobs resume worldfork jobs interrupt worldfork jobs requeue worldfork jobs run ``` If a command enqueues long work, capture the job ID and use a bounded wait. Do not spin forever. ## Runtime Inspection ```bash worldfork runs list worldfork runs workspace worldfork multiverses trace worldfork cohorts transcript --multiverse-id worldfork ticks timing worldfork ticks cost --include-calls worldfork runs cost --include-calls worldfork runs estimate 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 ```bash worldfork reports list worldfork reports versions worldfork reports view worldfork reports view --format json worldfork reports render --format pdf --output report.pdf worldfork reports pack --mode summary worldfork reports adjudicate worldfork reports adjudication worldfork ledgers list worldfork ledgers path-mass ``` 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: ```bash 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: ```text openrouter/deepseek/deepseek-v4-flash openai-codex/gpt-5.4 ``` Full live smoke: ```bash worldfork smoke live ``` Atlas onboarding: ```bash 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.