mast

Overview ¶

Command mast is the entry point for the mast agent runtime.

mast one-shot mode: `mast --task=<class> [--model=...] [--provider=...] [--session-db=...] "<prompt>"`. A positional prompt switches the binary from serving to running exactly one turn to completion and printing the result on stdout (logs stay on stderr). Serve remains the no-prompt default — scripts/demo-spike2.sh's flag-only invocations are untouched.

mast sessions — the operator-facing session surface (docs/durable-execution-design.md, "Operator-facing surface" + "The v0.2 pause/abort mechanics").

mast sessions list   --session-db=... [--user=...] [--state=paused|aborted|interrupted|idle]
mast sessions show   <session-id> --session-db=...
mast sessions resume <session-id> --interrupt=<iid> --response='{"approved":true}' [--ack-effects] [--addr=...]
mast sessions resume --token=<mrt_...> [--response='<json>'] [--ack-effects] [--addr=... | --session-db=...]
mast sessions pause  <session-id> --reason=<enum> [--message=...] [--resume-at=RFC3339 | --resume-after=15m]
                     [--interrupt] [--ttl=48h] [--addr=...]
mast sessions extend-token <mrt_...> --ttl=<duration> [--addr=...]
mast sessions abort  <session-id> [--reason=...] [--addr=...]
mast sessions ack-effects <session-id> [--reason=...] [--addr=... | --session-db=...]

list/show read the SQLite session DB directly (works with or without a running daemon). resume/pause/extend-token/abort go through a running daemon — resume must be executed by the runner that owns the workflow, hard pause must reach the daemon's cancel registry, and a single-writer store stays single-writer. Exception: `resume --token --session-db=...` clears a GATE pause directly, ONLY on a DB no daemon is serving (an interrupt pause always needs the daemon).

The v0.1 deviation note (resume keyed by interrupt ID, not token) is resolved: both keyings now exist, and tokens are the v0.2 programmatic-pause surface as originally sketched.

mast stop — the planned-stop verb (issue #42; docs/durable-execution- design.md, "Planned stop"). Asks a running daemon to drain and exit: exactly the SIGTERM path, with the interruption markers classified "operator stop" instead of "daemon shutdown".

mast stop [--addr=...] [--reason=...] [--pause-sessions]

Exit-code contract (the daemon's, not this command's): 0 = clean drain, 3 = drain window expired with interrupted survivors, 1 = error. The exit code encodes work-cut-short, not who initiated — Restart=on-failure supervision revives the daemon exactly when boot-time repair has work to do.