agent

Invocation#

echo-cli agent report --product <id> --from <ISO instant> --to <ISO instant> --window-days <days>
echo-cli agent schedules
echo-cli agent schedule --product <id> --period-days <days> --window-days <days> --to <email> --by <name>
echo-cli agent send --schedule <schedule-id>
echo-cli agent unschedule --id <schedule-id>

Inputs and output#

report writes product_id, from, to, window_days and actions: every audit row recorded between --from and --to, newest first, with its id, occurred_at, actor_kind, actor, action, trigger, inputs, effect, outcome and error, plus after_complete (false while the --window-days after the action have not passed yet) and metrics, each metric of the product's tree with metric_id, name, before (its value over the --window-days before the action), after (over the --window-days from it) and change. schedules writes every schedule, oldest declared first: id, product_id, period_days, window_days, recipient, declared_by, declared_at, attempted_at (when it last ran), sent_through (the end of the last period it emailed) and error (why its last attempt failed, or null). schedule, send and unschedule write the schedule as it now stands; send's carries the outcome of the attempt it made.

State effect#

report calls Echo Web's GET /api/automation/effects and the other verbs /api/automation/effects/schedules, with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the What automation changed section of the Automation tab of /diagnostics and of Echo Desktop's GEO screen reads the same report and its Emailed reports part the same schedules, and echo-mcp answers them as echo_automation_effects and echo_automation_effect_schedules. A report is never stored: the actions are the rows echo-cli audit list shows, and each metric counts the stored web and mobile analytics events the way echo-cli tracking metrics show counts them. A change beside an action is what the metrics did around it, not proof the action caused it; an action whose after-window has not ended is marked so its values are still accruing. A product has at most one schedule. Every hour /api/cron/automation-effects emails the report of each schedule never attempted or last attempted at least --period-days ago, covering the time since the end of the last period it sent (the --period-days before now when none was), from ECHO_EFFECT_REPORT_FROM through Echo's Resend integration as plain text naming each action, how it ended and each metric before and after it; send does the same for one schedule now. A suppressed recipient is not emailed. Each attempt keeps when it ran and either the end of the period sent or the error that stopped it (a missing ECHO_EFFECT_REPORT_FROM, a suppression, a product without metrics, Resend's refusal), so the next attempt sends the same period with what came after it.

Refusals#

• A wrong invocation is refused before anything is sent: "agent takes <every verb's usage, separated by semicolons>; got <word>", "agent <verb> does not take <flag>; it takes …", "<flag> needs a value", "agent <verb> needs <flag>" for each flag the verb needs, and "--window-days must be a whole number of days; got <value>" (and --period-days).
• Echo Web answers a bad request with "product_id is required: the product whose metrics measure the effect", "window_days is required: …", "from must be an ISO instant; got <value>" (and to), "to (<instant>) must come after from (<instant>)", "window_days must be a whole number of days of at least 1: how far before and after each action the metrics are counted; got <value>", "period_days must be a positive whole number of days: …; got <value>" (and window_days), "address must be one email address, a local part and a domain around one @; got <value>" or "id is required: …"; not found with "product <id> defines no metrics; echo-cli tracking metrics define gives it its North Star first", "no product has id <id>; echo-cli products lists the ones that exist" or "no effect report schedule has id <id>; echo-cli agent schedules lists them"; and a conflict with "product <id> already has an effect report schedule (<id>) emailing <address>, declared by <name>; remove it first". The command prints Echo Web's sentence and exits non-zero.