A portable action-script protocol. Write one declarative script — play this audio, wait for the far end to answer, cut in mid-sentence, call this API, send this text — and run it unchanged on any engine that implements the vocabulary: a browser session today, a real carrier phone call tomorrow, a native app after that.
A libretto is the fixed text that different productions perform. That is the whole idea: the script is data (flat YAML steps, not code), the engines are performers, and a manifest tells you exactly which parts of the vocabulary a given engine speaks.
spec_version: "0.1"
steps:
- { type: call.dial, id: dial, number: "+15551234" }
- { type: call.wait_answered, id: answered, timeout_ms: 30000 }
- { type: audio.play, id: q1, file: /srv/corpus/question1.wav }
- { type: audio.wait_for_speech_start, id: onset, wait_after_start_ms: 2000 }
- { type: audio.play, id: bargein, file: /srv/corpus/interrupt.wav }
- { type: audio.wait_for_speech, id: reaction, end_timeout_ms: 40000 }
- { type: call.hangup, id: bye }Every step comes back as a structured outcome — id, t_start_ms, t_end_ms, end_reason — stamped against the session recording's own clock, alongside timeline-aligned rx/tx audio legs. What you do with that record (latency metrics, QA judgments, monitoring alerts) is your business: Libretto defines execution and observation, never evaluation.
SPEC.md — draft v0.1. Namespaces (control.*, browser.*, audio.*, call.*, sms.*, restful.*, reserved app.*), execution classes and the session-block rule, templating, the outcome/recording envelope, capability manifests, conformance profiles, versioning, and migration notes for the founding implementations.
| Component | Role | Profile | Status |
|---|---|---|---|
| DialF | Phone engine (real SIM, carrier calls, SMS) | convo-phone |
Conformant as of v0.3.8 (server.manifest, step timing, barge-in, call metadata) |
| aeval | Web/browser conversation engine | convo-web |
Native step vocabulary already spec-shaped; canonical-form migration per SPEC §10 |
| Vox | Orchestrator + trusted REST broker (first consumer: AI voice-agent evaluation) | orchestrator, trusted-rest |
Compiles eval scenarios to Libretto scripts; dispatches per manifest |
The spec is owned here, not by any implementer. Major versions (semantics changes, removals) require review sign-off from the aeval, DialF, and Vox maintainers; minor versions (purely additive) merge on standard review. Engines track the spec at their own pace behind their manifests — advertising a spec_version an engine doesn't fully honor for its declared steps is a conformance bug.
Draft v0.1 — extracted 2026-09-21 from the Vox Phone-vs-Agent design, as the consolidation of two already-convergent step vocabularies (aeval scenarios and DialF jobs). Open workstreams are tracked in the issues: a conformance test suite, JSON Schemas for scripts + manifests, and finalization of the reserved steps.