playbooks

Invocation#

echo-cli playbooks list --product <id>
echo-cli playbooks publish --product <id> --name <text> --steps <steps.json> --by <name>
echo-cli playbooks run --version <version-id> --by <name>
echo-cli playbooks runs --version <version-id>

Inputs and output#

list writes the product's versions by name, newest first: id, product_id, name, version, steps (each action, payload, reason and, when it waits, wait_hours), published_by and published_at. publish writes the version it stored. run writes the run: id, version_id, started_by, started_at and results, one per step with index, action, request_id and status of the approval request it queued, error when it was refused, or status held when it waits; and held, the steps held for their waits (index, action, payload, reason, wait_hours, queued_at, request_id, status and error, each null until the step is queued). runs writes a version's runs, newest first, each with its held steps as they stand now.

State effect#

Every verb calls Echo Web's authenticated /api/automation/playbooks with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Playbooks section of the approvals screen and of Echo Desktop's GEO screen calls the same operations, and echo-mcp reads versions and runs (echo_list_playbooks, echo_playbook_runs). The steps file is a JSON array of { "action": "publish_blog_post", "payload": { "post_id": "…" }, "reason": "…", "wait_hours": 24 }; action is one of the operations echo-cli approvals list names, each payload is checked against its operation when published, and wait_hours, when a step states it, is how many hours after the step before it was queued this one is queued. Publishing under an existing name stores its next version; a version is never edited or deleted, the database grants nothing more than reading and adding one. run never takes a step itself: each is queued in the approval queue with the playbook, version and step in its reason, and runs when a reviewer approves it. run queues the steps up to the first that waits; that step and every one after it are held, and every hour /api/cron/playbook-steps queues each held step whose wait has passed since the step before it was queued (a held step without a wait follows the one before it at once), keeping when it was queued and its request or refusal. The run's own record stays as it started; runs shows the held steps beside it.

Refusals#

• A wrong invocation is refused before anything is sent: "playbooks takes <every verb's usage, separated by semicolons>; got <word>", "playbooks <verb> does not take <flag>; it takes …", "<flag> needs a value", "playbooks <verb> needs <flag>" for each flag the verb needs, "--steps names <path>, which cannot be read: <reason>" and "--steps names <path>, which is not JSON: <reason>".
• Echo Web answers a bad request with "product_id is required: …", "name is required: …", "steps is required: the ordered operations, each { action, payload, reason }, action one of <operations>", "step <n> is not an object with action, payload and reason", "step <n> names <action>; a step runs one of <operations>", "step <n> (<action>) carries a payload it does not take: <issues>", "step <n> reason is required: …", "step <n> wait_hours must be a positive whole number of hours after the step before it is queued; got <value>" or "<field>_by is required: an internal caller has no signed-in user, so it names who is acting"; not found with "no product has id <id>; echo-cli products lists the ones that exist" or "no playbook version has id <id>; echo-cli playbooks list --product <id> lists them"; and a conflict with "version <n> of <name> was published by another caller at the same moment; publish again to make the next version". Editing a version through PATCH /api/automation/playbooks is refused with a conflict: "a published playbook version never changes; publish the changed steps under the same name to make its next version". The command prints Echo Web's sentence and exits non-zero.