machina-driving
Drive a Machina state machine to a deterministic outcome on behalf of an AI agent. USE WHEN: a task is governed by a state machine (a machine definition JSON with states, transitions, guards, actions,
SKILL.mdskills/machina-driving/SKILL.md
GitHubMachina Driving
Execute a task under a Machina state machine: the driver (scripts/machine-driver.py)
is the sole mutator of run state; you perform the real work, choose events, and
satisfy evidence checks. The outcome is a deterministic, auditable report.
Run History Convention
All machina run history must be stored in:
<session-workspace>/machina-runs/<run-id>/
This convention ensures:
- Consistent traceability across sessions
- Easy discovery of run artifacts
- Standardized audit trail
The --run-dir parameter should point to machina-runs/ under the session workspace.
The driver defaults to machina-runs/ (resolving via COPILOT_DOJO or ~/.copilot-dojo env vars for the session workspace root; falls back to <cwd>/machina-runs/).
Quick start
From the skill directory (or any workspace with this skill installed):
python3 scripts/machine-driver.py init --machine <machine.json> --scenario <id> --input k=v
python3 scripts/machine-driver.py status --run <run_id>
python3 scripts/machine-driver.py fire <EVENT> --run <run_id> --note "what you did"
python3 scripts/machine-driver.py check --run <run_id>
python3 scripts/machine-driver.py report --run <run_id>
Every command prints exactly one strict-JSON object. A blocked fire is a first-class outcome, not an error.
Workflow
- Discover the governing machine — read the relevant skill's
SKILL.mdfrontmatter (machina: { machine, scenario }), or use the machine file the human conductor names. - Init the run with all required scenario inputs.
- Open the simulator canvas — immediately after
init, attemptopen_canvasper Simulator canvas integration so the human conductor watches the run live. If theopen_canvastool does not exist in this runtime, say so in one line and continue — never retry. - Work the current state — the state's
descriptiontells you what the state demands. Do real work before firing events. - Check status —
statusshows enabled vs blocked events and why. - Fire events with a
--note; iterate onblockedoutcomes by fixing the underlying condition (guard or evidence), never by forcing the machine. - Verify integrity —
checkre-runs the full ledger + artifact-hash verification and returns{ok:true}only when the run is intact. - Report at terminal — ground your final summary to the report facts.
Simulator canvas integration
When the machina-simulator Copilot extension is installed, the driving skill
auto-opens its interactive canvas so the human conductor can visually observe
the state machine being driven in real time.
Open on init
After a successful init, open the simulator canvas:
open_canvas(canvasId: "machine-simulator", input: {
runRef: "<run-id>",
sessionWorkspace: "<session-folder>"
})
runRef: the run ID returned byinit(the directory name undermachina-runs/).sessionWorkspace: the agent's current session folder (from the system prompt, e.g.~/.copilot/session-state/<uuid>). This scopes run-history discovery to the current session so the canvas shows only this session's runs.
The canvas enters replay mode, loading machine.json + ledger.jsonl from
the persisted run and displaying the state graph, compliance score, and ledger
trace.
Refresh on fire
After each successful fire, re-open the canvas with the same runRef +
sessionWorkspace to refresh the replay with the updated ledger. The canvas
open handler is idempotent — it re-reads the ledger and broadcasts a load
SSE event to the browser, so the conductor sees the latest state without
manual intervention.
STUCK / escalation
When the run enters STUCK or ESCALATED, the canvas is already showing the
stuck state and blocked events. No extra canvas action is needed — the
grounded report to the human conductor is the escalation channel.
Graceful fallback (three tiers)
open_canvasunavailable (e.g. VS Code / Agent-Host SDK runtimes without canvas tools): auto-start the standalone simulator instead of giving up — runnode "<extension>/scripts/start-standalone.mjs"where<extension>is the installed machina-simulator folder (~/.copilot/extensions/machina-simulator; the workspace copy'sscripts/start-standalone.mjsworks too). The launcher is idempotent: if a simulator already listens on127.0.0.1:7750it exits 0 with "already running" — treat both outcomes as success. Then emit one line for the human conductor:machina-simulator ready at http://127.0.0.1:7750/ — open it to watch this run (runRef <run-id>)and continue driving; the conductor browses Runs/Live tabs manually.- Start failed (no shell, no node, script missing): emit one line —
simulator unavailable (open_canvas absent, standalone start failed); continuing without it— then continue the run. - Never retry, never treat as an error. The simulator is a convenience, not a requirement.
Tamper prevention
The driver makes accidental or silent tampering fail closed. Four mechanisms (v0.3.0):
- Ledger hash chain —
ledger.jsonlrecords chain viaprev_hash/hash; any insert, remove, or reorder is detected on every command. - Artifact-hash binding —
initpins the run's machine definition (machine_sha256) and every referenced tool/checker script (tool_hashes) in the init record;status/fire/check/reportrecompute them and fail closed on mismatch. A mid-run edit tomachine.jsonor a checker script is a ledger integrity violation. - Repo-worktree run-dir refusal —
initrefuses to create a run dir inside a git worktree (only overridable viaMACHINA_ALLOW_REPO_RUNS=1), so run state cannot silently land in something you might commit. - Report bound to the ledger —
report.jsoncarriesledger_final_hash(the last ledger record's hash), so a report can be traced to the exact ledger state it was generated from.
Honest ceiling: this is detect-and-fail-closed, not cryptographic proof. The driver verifies hashes it derives from the same run directory, so an attacker who can rewrite all of it (including the init record) is not stopped — there is no OS-level read-only and no HMAC by design. The guarantee is that any edit to the definition copy, a checker script, or the ledger is detected and the run refuses to continue.
Hard rules
- INV-1: never hand-edit a machine's state, context, history, or logs. The driver is the only writer; the ledger is tamper-evident.
- INV-2: never inline code into machine JSON. Tools are named references to scripts the driver executes.
- Never run runs from inside a repo:
initrefuses repo-worktree run dirs (override withMACHINA_ALLOW_REPO_RUNS=1); run state stays session-scoped. - Post-init context immutability: after
init, only machine actions and tool-output mappings mutate context. Your--notenever touches context. - STUCK is not a crash: a non-final state with zero enabled events is a modeling gap. Report it to the human conductor; never improvise a transition or fabricate completion.
- Ground your summary to the report: render only report facts
(
result,final_state,path,events,evidence,context_snapshot).
References (load on demand)
| File | Load when |
|---|---|
| references/driving-protocol.md | Any driving task — the full protocol: command surface, driving loop, evidence, phase states, STUCK/escalation, report grounding, discovery |
| references/schema-v3.md | Reading or writing machine JSON — v3 field reference, tools registry, checks/requires/ensures, inputs, limits, phase states |
Dependency
This skill depends on machina-authoring:
scripts/machine-driver.py imports the shared engine (guard/action evaluation,
terminal detection, compliance scoring) from machina-authoring/scripts/machine-validator.py.
Distributing this skill to a workspace implicitly distributes machina-authoring.
The machina-simulator Copilot
extension is auto-invoked when installed — the driving skill opens its
canvas on init for live visual observability. When absent, the skill degrades
gracefully (no canvas, run continues normally).
For precision: the driver consumes the engine's blocking validation
(run_compliance(...)["blocking"]) as the structural gate and executes the machine's declared
tool scripts itself. It does not consume the authoring compliance score — see
machina-authoring's Compliance boundary. "Excellent" is a
declaration-quality signal; runtime soundness is established only by actually running the tools.
Samples
- samples/docs-authoring.machine.json — a v3 machine with tools, checks, requires, inputs, and a phase state.
- samples/scripts/check_file.py — a read-only checker script referenced by the sample machine.
Trust boundary
The driver executes referenced checker scripts with the user's privileges.
Machines are trusted artifacts (authored by the user or by machina-authoring).
No sandboxing in v1.
Corollary of the compliance boundary: a machine can be declared "Excellent" yet fail at runtime if its tool scripts are missing, incorrect, or hostile — the driver is what establishes runtime behavior by executing the declared read-only checkers, which is exactly why they must exist and stay read-only.
Hook hardening (defense-in-depth)
Three agent hooks provide lifecycle-based enforcement that augments the driver's internal tamper prevention. These hooks are advisory-to-mandatory depending on the event type and fill gaps where the driver's prompt-level instructions are insufficient.
| Hook | Event | Enforcement | Gap filled |
|---|---|---|---|
machina-ensures-runner |
postToolUse |
modifiedResult (mandatory data) |
ensures[] post-conditions declared in schema but not enforced by driver |
machina-event-gate |
postToolUse |
modifiedResult (mandatory data) |
status shows events "enabled" when evidence checks would block them |
machina-summary-guard |
agentStop |
decision:"block" (forced turn) |
Agent can fabricate summary contradicting report.json |
How they work:
- Fire guard: After a
firecommand, runstransition.ensures[]tools and appends pass/fail results to the tool output. The agent sees post-condition failures as part of the fire result. - Status enhancer: After a
statuscommand, cross-referencesenabled_eventsagainststate.checks[]and replaces the output with accurate categorization (truly enabled vs checks-failed vs checks-pending). - Report validator: Before session ends, compares the last assistant message
against
report.jsonfacts. If contradictions are found, forces another turn to correct the summary (capped at 8 consecutive blocks).
Deployment: These hooks live in hooks/machina-*/ and are published to
.github/hooks/ via publish-hooks.ps1. They activate automatically when the
agent uses the machina-driving skill.
Report output contract
Your final user-facing summary is a grounded report that renders only facts
from the terminal report output. It is not prose — each field must trace to a
machina.report.v1 field.
| Report field | Required content | Source (report) field |
|---|---|---|
result |
SUCCESS · ESCALATED · ABORTED · STUCK · IN_PROGRESS |
result |
final_state |
the final state id | final_state |
path |
the visited state sequence | path |
events |
count + comma-separated event names | events, agent_notes[].event |
evidence |
passed N / failed M |
evidence.passed, evidence.failed |
blocked_events |
only when present | blocked_events |
context_snapshot |
only when it affects the outcome | context_snapshot |
Rules:
- Keep it under ~80 words; one paragraph per report.
- Never invent claims beyond the report. If
resultisSTUCK, saySTUCK— do not claim success. - On
STUCKorESCALATED, head the summary as a grounded escalation: state the blocked events, the evidence failures, and the decision the human conductor must make. Never improvise a transition or fabricate completion. - On
ABORTED, render the abort reason from the report. - If the driver emitted a strict-JSON
machina.report.v1object, that object is the report — do not paraphrase it into different fields.
Resources
scripts/—machine-driver.pyimplements theinit/status/fire/abort/check/reportcommand surface. Execute it directly; do not load into context.references/—driving-protocol.md(the driving loop, evidence, STUCK, report grounding, tamper prevention) andschema-v3.md(machine JSON v3 reference). Load on demand per the table above.samples/—docs-authoring.machine.jsonand itsscripts/checkers for a worked example of a driven run.