@moda-ai/cli 1.55.24 → 1.55.26

package/skills/moda-cli/references/output-protocol.md

@@ -40,7 +40,7 @@ Branch on the exit code; it is stable and cheaper than parsing the payload:
 |---|---|---|
 | `0` | ok — answer is grounded in Moda Cloud intelligence | Trust it. |
 | `1` | error — bad input, unknown id (`not_found`), access denied, API/network failure | Read `errors[0].code`; retry only `network_error` / 5xx `api_error`. For `not_found`, find a valid id first (the `cause` names the command). |
-| `3` | degraded — Moda Cloud was unavailable; answer synthesized from local Data API evidence | Answer is present but lower-trust; verify before acting. |
+| `3` | degraded — Moda Cloud was unavailable and the answer was synthesized from local Data API evidence (`ask`), or some sources failed to load (`investigate`/`failures`, named in `data.failedSources`) | Answer is present but lower-trust or partial; verify before acting, and never read a partial result as "no issues". |
 | `4` | auth required — no API key, or the API rejected it (HTTP 401) | Set `MODA_API_KEY` or run the `login_command` from the `auth` payload (`moda auth login --api-key`), then re-run. |
 | `5` | input required — a choice is needed that the non-interactive run could not answer | Pick a choice from the `input_request` payload and re-invoke the same command with that choice's `resume_flags` appended. |
 | `130` | cancelled | Treat as interrupted or closed pipe; do not retry blindly. |
@@ -195,17 +195,42 @@ Treat an answer as degraded if **any** of these hold:
   that text stays whole, and the error message says whether `data` is whole
   or bounded with its complete copy at `truncation.data.full_output_path`.
   You can also page with a smaller `--limit` and
-  `--offset`, or rerun with `--json` (no byte limit).
+  `--offset`, or rerun with `--json` (no byte limit). Commands that read
+  per-row extras (`--include-window`, `--include-world-state`, batch reads)
+  stop reading once the budget is spent; rows they did not enrich carry
+  `window_skipped` / `world_state_skipped: "agent_output_budget"`.
+- **`--json` is compact when piped.** `--json` prints one line of JSON when
+  stdout is not a terminal (indented on a terminal); `--pretty` indents it
+  anyway. `--json` prints the payload as read: `--profile` is stamped only on
+  the agent envelope's generated commands (`next_commands`, `*_command`
+  fields), never on trace content.
 - **Unknown flags fail.** A flag the command doesn't take (a typo, or a
   filter it lacks) exits `1` with the valid flag list and a "did you mean",
-  instead of being silently ignored. Stray arguments on commands that take
-  none fail the same way.
-- **`--dry-run` is only accepted where it's implemented** (for example
-  `registry push`, `harness sync|delete|register`, `prompts sync|decide`,
-  `skills sync|policy`, `signals` write subcommands, `problem-reopen`;
-  `moda <command> --help` says whether a command takes it). Anywhere else it fails **before
-  anything is sent**. It is never silently ignored, so a "preview" can't
-  perform a real write.
+  instead of being silently ignored. So does a flag the chosen mode would
+  not send (`moda signal <id> --limit=3` without `--detections`).
+- **`--days-back` and `--days_back` are the same flag.** Every flag is read
+  under its kebab-case name whichever spelling you type.
+- **A value flag needs a value.** `--user-id` with nothing after it (often an
+  empty shell variable) exits `1` naming the flag instead of sending the
+  string "true". Switches such as `--include-tool-io` stay bare.
+- **Numbers are plain decimal integers.** `--limit=0x10`, `--limit=1e1` and
+  `--limit=2.5` fail; text flags keep their text (`--search=404` searches
+  for "404").
+- **Extra words fail.** A command that takes one id rejects a second word
+  instead of ignoring it. Free text joins every word: `moda traces search
+  refund not processed` searches "refund not processed" (same for `ask` and
+  `feedback`).
+- **Writes take `--dry-run`** (`prompts promote|ab|propose` excepted).
+  - `problems feedback|reopen|link`, `review`, `feedback`, `signals` writes
+    and `skills policy` validate fully, send nothing, and return
+    `data.planned` (method, endpoint, body) plus a `next_commands` entry
+    that runs the write for real (`requires_approval: true`).
+  - `registry push`, `harness sync|delete|register`, `prompts sync|decide`
+    and `skills sync` return their own preview. Some ask the server to
+    compute it (`skills sync --dry-run` sends the local skills marked
+    `dryRun: true`), but none of them applies a change.
+  - A read refuses `--dry-run` **before anything is sent**, so a "preview"
+    can't perform a real write.
 - **Unknown profiles fail.** `--profile=<name>` or `MODA_PROFILE` naming a
   profile that doesn't exist exits `1` instead of falling back to another
   profile's key and tenant. Time windows differ by command (below).

package/skills/moda-cli/references/production-intelligence.md

@@ -90,7 +90,8 @@ Rules that keep the fix grounded:
 - Cite the Moda problem id and the trace ids you relied on in the PR
   description, so a reviewer can open the same evidence.
 - To test a prompt change against real traffic before shipping it, A/B it with
-  `moda prompts ab --baseline=<path> --candidate=<path> --traces=<ids>` (see
-  section 7).
+  `moda prompts ab --baseline=<path> --candidate=<path> --problem=<problem_id>`
+  (replays the Problem's failing traces from their evidence anchors) or
+  `--traces=<ids>` (see section 7).
 - Mark the Problem fixed only after the change ships. If the issue is detected
   again, the Problem comes back; `moda problems reopen` reopens it by hand.

package/skills/moda-cli/references/prompts.md

@@ -72,7 +72,10 @@ read, they fail (exit 1) with the number and the exact command to re-run with `-
 Only add `--yes` when the user has agreed to that spend. Limits: `--cases`
 default 5, max 100; `--seeds` default 3, max 10; `--traces` at most 100
 (`--traces=conv_id@412` replays that trace from msg_index 412, with the
-earlier turns as history);
+earlier turns as history, and writes its case from the messages around 412);
+`--problem=<problem_id>` picks a Problem's affected traces, each anchored at
+its earliest evidence msg_index, up to
+`--max-cases` (default 10, max 100), and prints them (`problemCases`);
 `--model` / `--assistant-model` must be one of `openai/gpt-5.6-luna`,
 `openai/gpt-4o-mini`, `openai/gpt-4o`, `anthropic/claude-sonnet-4-5`,
 `anthropic/claude-haiku-4-5`, `google/gemini-2.5-flash`,
@@ -80,7 +83,8 @@ earlier turns as history);
 
 `prompts ab --traces=<ids>` builds one case per trace from Moda's distilled
 scenario and success criteria for that trace. A trace Moda cannot distill
-falls back to its opening user message with three generic criteria (which long
+falls back to its opening user message (for `id@N`, the user message leading
+into N) with three generic criteria (which long
 traces pass easily); the run warns and lists it under `caseSources.fallback`.
 `prompts ab` never makes its replay set the tenant's primary set unless you
 pass `--promote`.

package/skills/moda-cli/references/search-and-traces.md

@@ -110,7 +110,16 @@ moda traces get <conversation_id> --all --from=500 --max-messages=500  # continu
 ```
 
 `--all` returns `has_more`/`next_from`; when it stops at the cap, the warning
-prints the exact `--from` command to continue.
+prints the exact `--from` command to continue. In agent output `--all` reads
+only about what fits the byte budget (a ~50-message first page), so
+`returned` can be well under `--max-messages`; follow `next_from`.
+
+A window over the agent byte budget is cut around its anchor, never past it:
+the requested message is always returned, the rest are kept nearest-first on
+both sides, `context.from_index`/`to_index` describe what was returned
+(`requested_from_index`/`requested_to_index` and `omitted_for_byte_limit`
+what was asked for), and `next_commands` has an `--all --from` command for
+each side that lost messages.
 
 **Several traces? Batch them in one call instead of looping `moda traces get`
 per id.** Pass up to 25 targets as positionals or one per line with
@@ -130,7 +139,9 @@ plus `succeeded`/`failed` counts. A missing trace is a per-item
 `error.code: "not_found"`, not a failed call; the exit code is 1 only when
 every target failed. When the agent byte budget would overflow, the items that
 fit are returned and `remaining_targets` plus a `next_commands` entry read the
-rest. One positional id keeps the single-trace output above.
+rest. Agent output stops reading targets once the budget is spent, so the
+targets it names were not read yet (nothing is read and then dropped). One
+positional id keeps the single-trace output above.
 
 `moda traces get` returns messages whole, with their tool calls and results. An
 older Moda server cuts message text, tool inputs, and tool results at 500
@@ -148,6 +159,7 @@ moda traces spans <conversation_id> --include-raw    # attach verbatim raw_event
 moda traces spans <conversation_id> --include-bodies # keep prompt/response/attribute bodies
 moda traces spans <conversation_id> --limit=1000     # ingest rows to read (default 200, max 1000)
 moda traces spans <conversation_id> --cursor=<next_cursor>  # next page of a capped audit
+moda traces spans <conversation_id> --cursor=<c> --span-offset=N  # rest of a page cut for the agent budget
 moda traces spans <id1> <id2> <id3>                  # batch: up to 25 ids, one envelope
 ```
 
@@ -162,6 +174,12 @@ A full `--limit` page of ingest rows, the server's ~3 MB response budget
 (`summary.truncated_reason: "byte_limit"`) or a span cap sets both, and a
 warning plus `next_commands` give the follow-up — usually the `--cursor=` page
 from `next_cursor`; for very large traces audit one OTLP trace at a time
+(see below). In agent output a page over the byte budget (the server's
+smallest page, 32 KiB, is over the 24,000-byte default) keeps the most spans
+that fit: `span_offset`/`next_span_offset`/`page_spans` say which,
+`next_cursor` is `null` until the last spans of the page are read, and
+`next_commands` has the `--span-offset=N` command that reads the rest of the
+same page. Following `next_commands` never skips a span;
 (`summary.trace_ids`, `--kind=trace`). Prompt/response bodies are omitted by
 default (`{"omitted": true, "original_bytes": N}`); `--include-bodies` keeps
 them, cutting strings over 8 KB to `{"truncated": true, "original_bytes": N,