@koda-sl/baker-cli 0.338.0 → 0.340.0-dev.10990633f

package/README.md

@@ -32,7 +32,7 @@ export BAKER_GSC_SITE_URL="https://example.com/"
 # Optional: default X Ads account ID (base36)
 export BAKER_X_ADS_ACCOUNT_ID="18ce53xyz"
 
-# Required for `baker actions ...` and `baker scheduled-actions create/update/delete` commands that stage against a chat
+# Required for `baker actions ...` and `baker scheduled-agents create/update/delete` commands that stage against a chat
 export BAKER_CHAT_ID="<chat-id>"
 ```
 
@@ -43,7 +43,7 @@ export BAKER_CHAT_ID="<chat-id>"
 - `BAKER_GA4_PROPERTY_ID` — default GA4 property ID. Used when `--property-id` is not passed. If neither is set and exactly one property is connected, it is auto-selected.
 - `BAKER_GSC_SITE_URL` — default GSC site URL. Used when `--site-url` is not passed. If neither is set and exactly one site is verified, it is auto-selected.
 - `BAKER_X_ADS_ACCOUNT_ID` — default X Ads account ID (base36). Used when `--account-id` is not passed. If neither is set and exactly one X Ads account is connected, it is auto-selected.
-- `BAKER_CHAT_ID` — chat context for staged Work Action commands and staged Scheduled Action create/update/delete. `scheduled-actions trigger` does not require it. When set, it is also sent as an `x-baker-chat-id` header on every request, so library additions that apply immediately (images, videos, followed brands) are listed in that chat's changes as already applied.
+- `BAKER_CHAT_ID` — chat context for staged Work Action commands and staged Scheduled agent create/update/delete. `scheduled-agents run` does not require it. When set, it is also sent as an `x-baker-chat-id` header on every request, so library additions that apply immediately (images, videos, followed brands) are listed in that chat's changes as already applied.
 
 ## Debug logging
 
@@ -689,7 +689,7 @@ Command groups: `budgets`, `campaigns`, `ad-groups`, `keywords` (add/update/remo
 
 **Amending a staged op** — `draft amend <ref> (--file patch.json | --patch '<json>')` merges a JSON patch into an already-staged op's payload (objects deep-merge, `null` deletes a key, arrays/scalars replace) and re-validates it in full. Always prefer this over removing and re-staging — it preserves the op's ref (so dependents don't break) and its position in the draft. `draft show <ref>` prints the full staged payload (including warnings/annotations) so you can verify a change looks right before publish.
 
-**Reading an earlier chat's changes** — `draft list` and `draft show` take `--chat <chat-id>` to read another chat in the same company instead of the current one. Every staged-draft family accepts it: `ads google|meta|linkedin draft list|show`, `tag-manager draft list|show`, `actions draft`, `tags draft`, and `scheduled-actions list|get`. A published draft is kept in full, so this returns what that chat actually wrote — every headline, bid and target — plus each op's outcome and error. Use it when asked to redo or reapply earlier work rather than reconstructing copy from a summary. Read-only: staging, `amend`, `remove` and `clear` stay bound to `BAKER_CHAT_ID`, so one chat can never edit another's draft. To re-run only the changes a publish failed to land, use the chat's **Retry** control in the dashboard — it re-sends exactly those and leaves the ones that applied untouched.
+**Reading an earlier chat's changes** — `draft list` and `draft show` take `--chat <chat-id>` to read another chat in the same company instead of the current one. Every staged-draft family accepts it: `ads google|meta|linkedin draft list|show`, `tag-manager draft list|show`, `actions draft`, `tags draft`, and `scheduled-agents list|get`. A published draft is kept in full, so this returns what that chat actually wrote — every headline, bid and target — plus each op's outcome and error. Use it when asked to redo or reapply earlier work rather than reconstructing copy from a summary. Read-only: staging, `amend`, `remove` and `clear` stay bound to `BAKER_CHAT_ID`, so one chat can never edit another's draft. To re-run only the changes a publish failed to land, use the chat's **Retry** control in the dashboard — it re-sends exactly those and leaves the ones that applied untouched.
 
 **Already-satisfied writes aren't staged** — an update or pause/resume whose every field already holds the requested value on the live account is dropped instead of staged: the envelope returns `"staged": false, "noop": true` with a `reason` ("this ad is already Paused on Google Ads"), plus a hint. This is a success, not an error — there is nothing to publish. Only a positively-read live snapshot can trigger it; a failed or empty read always stages. Batch responses list the dropped ops under `skipped`, and `count` reflects what actually entered the draft.
 
@@ -3261,63 +3261,79 @@ baker winning-ads patterns --winners a_1,a_2,a_3 --duds a_9,a_8 --top-n 10 --out
 
 ---
 
-### Scheduled Actions (`baker scheduled-actions`)
+### Scheduled agents (`baker scheduled-agents`)
 
-Manage company-scoped scheduled recipes that spawn Work Actions later or on a cadence. `create`, `update`, and `delete` stage draft ops on `BAKER_CHAT_ID` and apply when the chat is published. `list` and `get` include draft state when `BAKER_CHAT_ID` is set. `trigger` runs immediately on a published scheduled action and does not require a chat id. Use a regular Work Action instead when there is no date or cadence.
+A Scheduled agent is a **trigger** and a **prompt**. When the trigger fires, a Session opens with that prompt and does the job — there is no Task in between. `create`, `update`, and `delete` stage draft ops on `BAKER_CHAT_ID` and apply when the chat is published. `list` and `get` include draft state when `BAKER_CHAT_ID` is set. `run` fires a published item immediately and does not require a chat id.
 
 ```bash
-baker scheduled-actions list
-baker scheduled-actions get <id-or-temp_sched_id>
+baker scheduled-agents triggers                    # every trigger there is
+baker scheduled-agents list
+baker scheduled-agents get <id-or-temp_agent_id>
 
-baker scheduled-actions create --name "Weekly report" --description "Prepare report" --cron "0 9 * * MON" --timezone Europe/Madrid
-baker scheduled-actions create --name "Launch reminder" --description "Check launch" --run-at "2026-09-01T07:00:00Z" --disabled --no-spawn-agent
-baker scheduled-actions create --name "Spend review" --description "Review spend anomalies" --cron "0 9 * * MON" --prompt "Focus on blockers"
+baker scheduled-agents create --name "Weekly report" --description "Prepare report" --prompt "Review last week's spend." --cron "0 9 * * MON" --timezone Europe/Madrid
+baker scheduled-agents create --name "Launch reminder" --description "Check launch" --prompt "Check the launch checklist." --run-at "2026-09-01T07:00:00Z" --disabled
+baker scheduled-agents create --name "Chase a new quote" --description "Follow up while it is warm" --prompt "Read the answers and draft the follow-up." --trigger form.submitted --form quote
+baker scheduled-agents create --name "Celebrate the first sale" --description "Once, ever" --prompt "Write the announcement." --trigger event.received --event purchase --occurrences 1
 
-baker scheduled-actions update <id-or-temp_sched_id> --enabled false
-baker scheduled-actions update <id-or-temp_sched_id> --run-at "2026-09-02T07:00:00Z" --spawn-agent true --prompt "Use the launch checklist"
-baker scheduled-actions update <id-or-temp_sched_id> --mode publish     # runs go live unreviewed
-baker scheduled-actions update <id-or-temp_sched_id> --mode recommend   # runs advise and change nothing
-baker scheduled-actions delete <id-or-temp_sched_id>
+baker scheduled-agents update <id-or-temp_agent_id> --enabled false
+baker scheduled-agents update <id-or-temp_agent_id> --run-at "2026-09-02T07:00:00Z" --prompt "Use the launch checklist"
+baker scheduled-agents update <id-or-temp_agent_id> --trigger experiment.ended
+baker scheduled-agents delete <id-or-temp_agent_id>
 
-baker scheduled-actions trigger <id>
+baker scheduled-agents run <id>
 
-baker scheduled-actions templates --list                  # every recipe this company can run
-baker scheduled-actions templates --category measurement  # one group only
-baker scheduled-actions create --template baker-ads --name "Weekly ad review" --description "..." --cron "0 8 * * MON"
+baker scheduled-agents templates --list                  # every recipe this company can run
+baker scheduled-agents templates --category measurement  # one group only
+baker scheduled-agents create --template baker-ads --name "Weekly ad review" --description "..." --cron "0 8 * * MON"
 ```
 
+Triggers:
+
+| `--trigger` | Fires when | Narrow it with |
+|---|---|---|
+| *(use `--run-at`)* | Once, at a time you pick | — |
+| *(use `--cron`)* | On a repeating cadence | — |
+| `webhook.received` | Another tool posts to this item's own private address | — |
+| `event.received` | An event arrives from the site or a connected tool | `--event <name>` |
+| `form.submitted` | Somebody sends answers from a Form | `--form <slug>` |
+| `flow.step.submitted` | Somebody gets as far as one step of a Form | `--form <slug> --step <id>` |
+| `experiment.ended` | Somebody ends an A/B test | `--experiment <id>` |
+| `experiment.concluded` | The winner has been moved into the page | `--experiment <id>` |
+| `task.completed` | A Task is closed | `--tag <slug>` |
+| `task.claimed` | An agent picks up a Task | `--tag <slug>` |
+
 Rules:
 
-- `--cron` and `--run-at` are mutually exclusive.
-- `--run-at` must be an ISO UTC timestamp ending in `Z`, and still in the future — a time that has already passed is refused when the op is staged. If a one-off's time passes while the chat is still open, publishing creates the task **switched off** with the reason on it rather than dropping it, so it is never lost.
-- Draft-created ids use `temp_sched_*`; use them with `get`, `update`, or `delete` before publish.
+- `--cron`, `--run-at` and `--trigger` are mutually exclusive — an item has exactly one trigger.
+- `--run-at` must be an ISO UTC timestamp ending in `Z`, and still in the future — a time that has already passed is refused when the op is staged. If a one-off's time passes while the chat is still open, publishing creates it **switched off** with the reason on it rather than dropping it.
+- Leaving a narrowing flag off means "any" — any Form, any event, any test — including ones that do not exist yet.
+- `--occurrences 1` runs only the first time the trigger ever fires; `--occurrences 1,3` the first and the third. Omit it to run every time. It counts firings of this item's trigger, so a firing that `--occurrences` declines is still counted.
+- A signal-triggered item will not start a second run while its last one is still going, and never wakes itself.
+- `--prompt` is the whole job: there is no mode and no `--spawn-agent`. If a run should only advise, the brief says so.
+- Publishing every run's work unreviewed is a standing authorization only the user can grant, on the item in Baker. The API refuses `autoPublish` outright.
+- Draft-created ids use `temp_agent_*`; use them with `get`, `update`, or `delete` before publish.
 - Staged commands require `BAKER_CHAT_ID` to point to an `in_progress` chat.
-- `trigger` rejects `temp_sched_*` and only accepts published scheduled-action ids.
+- `run` rejects `temp_agent_*` and only accepts published ids. It returns the `chatId` of the Session it opened.
 - Company Timezone is the default; `--timezone` is an explicit IANA override.
-- `--mode` sets how far a run goes on its own: `remind` (opens the Task, runs nothing), `recommend` (writes up what it would change, touches nothing), `propose` (does the work, waits to be published — the default), `publish` (does the work and publishes it unreviewed). It applies when the chat is published, on the authority of whoever published it; a chat completed with no person behind it lands a `publish` task on `propose` instead.
-- `--mode` supersedes `--spawn-agent`/`--no-spawn-agent`, which can only reach `remind` and `propose`. Passing both is rejected.
-- Scheduled actions spawn agents by default; create with `--no-spawn-agent` or update with `--spawn-agent false` to disable it.
-- `--prompt` maps to the scheduled action's additional spawned-agent instructions (`agentPrompt`), not a replacement for Baker's automatic spawned Work Action reference.
-- `--prompt` requires a run that does the work: it is rejected alongside `--mode remind`, `--no-spawn-agent` (create) or `--spawn-agent false` (update), since a bypassed agent never reads it.
-- `--template <id>` binds the schedule to a marketplace recipe instead of a prompt you wrote. The row stores the id alone: name, brief and prompt resolve at fire time, so the job improves when the recipe does. `--description` carries what is true of this company. One row per recipe per company; a second `create` for the same id is refused.
+- `--template <id>` copies a marketplace recipe's brief onto the item — a copy, not a link, so the owner can read and edit every word, and a later change to the recipe does not reach it. `--prompt` is appended after it. The same recipe can be used more than once.
 
 #### Marketplace recipes (`templates`)
 
-`templates` lists every recipe a company can switch on — the ones Baker maintains plus any the company wrote — and is also how one of theirs is written. Recipes we maintain take priority: a company recipe can never use one of our ids, and resolution reads ours first.
+`templates` lists every recipe a company can build an item from — the ones Baker maintains plus any the company wrote — and is also how one of theirs is written. Recipes we maintain take priority: a company recipe can never use one of our ids, and resolution reads ours first.
 
 ```bash
-baker scheduled-actions templates --list --drafts        # include theirs not offered yet
+baker scheduled-agents templates --list --drafts        # include theirs not offered yet
 
 # Writing one of theirs, in this order:
-baker scheduled-actions templates --save weekly-posthog-check \
+baker scheduled-agents templates --save weekly-posthog-check \
   --name "Weekly PostHog check" \
   --tagline "What moved in the funnel, from PostHog rather than GA4." \
   --recipe-category measurement --frequency weekly \
   --brief-file ./brief.md
 
-# ...schedule it with --template, trigger it, read what the run produced, then:
-baker scheduled-actions templates --publish weekly-posthog-check
-baker scheduled-actions templates --delete weekly-posthog-check
+# ...build an item from it with --template, run that item, read what it produced, then:
+baker scheduled-agents templates --publish weekly-posthog-check
+baker scheduled-agents templates --delete weekly-posthog-check
 ```
 
 - **Saving does not offer it.** A saved recipe is invisible and cannot be scheduled until `--publish`. The step between the two is running it: nothing enforces that, and it is the only way to know it produces anything worth reading.
@@ -3435,7 +3451,7 @@ baker actions create --name "Build hero" --priority high --tags landing,creative
 # (temp_hero_copy, not hero_copy) and is rejected with a VALIDATION_ERROR otherwise — the prefix is
 # what tells a task staged in this chat apart from a published action id in link/update/complete/draft remove.
 # If the name/description reads as recurring or future-dated (e.g. "weekly", "every Monday", "schedule"),
-# create emits a hint to use `baker scheduled-actions create` instead of a Work Action.
+# create emits a hint to use `baker scheduled-agents create` instead of a Work Action.
 # If it instead names work a surface executes in-chat (a GTM container change, a site tag, an ad-platform
 # write, a page or form edit, or a value only the user has), create emits a do-it-now hint naming that
 # surface — doing the work is the default, an action is the exception. One advisory hint per call: the
@@ -3651,7 +3667,7 @@ baker chats diff <id> --live              # in-progress Session: read from its l
 ```
 
 **`list` flags:** `--status active|archived|all` (default `all`), `--limit` (1-100, default 20), `--full` (include each Session's full change list).
-**`view`:** returns the unified `effects` — git content (`content`, `creatives`) AND DB-only effects that never touch the repo (`actions`, `scheduledActions`, `tags`, `ads.{google,meta,linkedin}`), each resolved to real detail and flagged `staged` (in-progress draft) vs applied. Plus `kickoff`, `outputs` counts, `threads`, `commits`, `diffAvailable`.
+**`view`:** returns the unified `effects` — git content (`content`, `creatives`) AND DB-only effects that never touch the repo (`actions`, `scheduledActions`, `tags`, `ads.{google,meta,linkedin,x}`, `tagManager`, `ga4`, `funnel` (with the ways in it added or removed, `triggersAdded`/`triggersRemoved`), `conversions`, `conversionSends`, `eventSources`), plus `otherChanges` for every other change the Session made (A/B tests, recipes, library images), each resolved to real detail and flagged `staged` (in-progress draft) vs applied. Plus `kickoff`, `outputs` counts, `threads`, `commits`, `diffAvailable`.
 **`transcript` flags:** `--limit` (1-1000, default 100, most recent), `--full` (untruncated text). Returns `entries` (`role` + `text`) and `truncated`.
 **`diff` flags:** `--surface knowledge|company|brand|landings|flows|creatives`, `--full` (patch text per file), `--live` (read an in-progress Session's changes from its live workspace). Returns `available`, `source` (`published`|`live`), `files` (`path`, `surface`, `status`, `additions`, `deletions`, `patch`), and `truncated` when a large live diff was capped.
 

package/dist/{chunk-FFOURYP5.js → chunk-D5P4COPD.js}

@@ -19,9 +19,9 @@ import {
   shouldEscalate
 } from "./chunk-4VP5WWPR.js";
 
-// ../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js
+// ../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/766ad107c42df28eeadaf0ac2f9089c8a9e200f6ba0b2b1a817b8d536cbdcc49/node_modules/safe-stable-stringify/index.js
 var require_safe_stable_stringify = __commonJS({
-  "../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/index.js"(exports, module) {
+  "../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/766ad107c42df28eeadaf0ac2f9089c8a9e200f6ba0b2b1a817b8d536cbdcc49/node_modules/safe-stable-stringify/index.js"(exports, module) {
     "use strict";
     var { hasOwnProperty } = Object.prototype;
     var stringify = configure2();
@@ -1113,7 +1113,7 @@ function resolveAdaptFormats(params) {
   return params.formats ?? [];
 }
 
-// ../../node_modules/.pnpm/safe-stable-stringify@2.5.0/node_modules/safe-stable-stringify/esm/wrapper.js
+// ../../.pnpm-store/v10/links/@/safe-stable-stringify/2.5.0/766ad107c42df28eeadaf0ac2f9089c8a9e200f6ba0b2b1a817b8d536cbdcc49/node_modules/safe-stable-stringify/esm/wrapper.js
 var import__ = __toESM(require_safe_stable_stringify(), 1);
 var configure = import__.default.configure;
 var wrapper_default = import__.default;
@@ -9804,4 +9804,4 @@ export {
   defaultRegistry,
   createEngineFromEnv
 };
-//# sourceMappingURL=chunk-FFOURYP5.js.map
+//# sourceMappingURL=chunk-D5P4COPD.js.map