@moda-ai/cli 1.55.25 → 1.55.26

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,