A canonical-world simulation kernel with LLM-powered synths, exposed as REST, MCP, and SSE over a single OpenAPI schema.
Four pillars that define the system under the control plane.
Every cognitive cycle runs against a working copy. The Director commits only after invariants pass; on failure, the working copy is discarded and canonical state is unchanged. Snapshots land at cycle boundaries.
Each synth owns a phenomenology — self-model, beliefs, mental models of other synths, affect, projects, memories. Perception is mediated through sensory bundles; actions flow through symbolic intent resolution.
Every canonical change is journaled to per-session JSONL. Runs are deterministic (stable IDs from scenario_id + authored_id) and fully replayable from cached LLM responses.
The same OpenAPI spec drives REST, Swagger UI, ReDoc, the LLM tool manifest, the MCP tools/list for agent discovery, and this dashboard. Six consumers, one source of truth.
Each role has a direct entry point. Scopes are checked on every call.
Attach to a running simulation without disturbing it. scope: read
/v1/sessions/{id}/stream — browser-native live feedresolve_ref) for finding synths by nameStep the simulation, submit turns, manage sessions. scope: operate
list_scenarios → create_session)step_session) or auto-advance (resume_session)submit_turnlist_snapshots + restore_snapshotBuild on top of the control plane — agents, UIs, or new synths. scope: any
/openapi.json — authoritative contractPOST /mcp — JSON-RPC 2.0 tool discovery for agentsscenarios/*.yaml; contract in ArchitectureSee what happened, find what broke, drop a new scenario without code changes. scope: admin
/v1/admin/logs — 15 filtersX-Request-Id — grep the log by ID for full contextapply_patch) and queue stimuli (queue_stimulus) — admin onlyCopy-paste, LAN-accessible. No auth by default; set SINGING_BIRD_API_TOKEN to turn it on.
# List available scenario packs
curl -s https://singing-bird.benac.dev/v1/scenarios | jq# Create a session and keep the id SID=$(curl -s -X POST https://singing-bird.benac.dev/v1/sessions \ -H 'content-type: application/json' \ -d '{"scenario_path":"scenarios/park_bench.yaml"}' | jq -r .session_id) # Advance one cognitive cycle curl -X POST https://singing-bird.benac.dev/v1/sessions/$SID/step \ -H 'content-type: application/json' -d '{"n":1}'
# Any MCP-aware client (Claude Desktop, agent, etc.)
curl -X POST https://singing-bird.benac.dev/mcp \
-H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | jq# Every response carries X-Request-Id; use it to pull the record
curl -D - https://singing-bird.benac.dev/v1/scenarios -o /dev/null | grep -i request-id
curl 'https://singing-bird.benac.dev/v1/admin/logs?request_id=<id>' | jqAll six are derived from the same OpenAPI document. Change the code, all six update.
Operator UI — 22 tiles across five lanes, live status, audit tail, theme-aware.
OpenAPI 3.1 JSON. Source of truth for every other surface. Load into any generator.
Interactive API explorer with try-it-out forms for every endpoint.
Reference-style API docs, easier to read in long form than Swagger.
Compact LLM-friendly JSON tool list (name, method, path, scope, description).
JSON-RPC 2.0 over POST /mcp. tools/list, tools/call, ping. GET returns 405.
Bookmarkable index of every URL on this host.