@moda-ai/cli 1.49.0 → 1.52.0

package/skills/moda-cli/SKILL.md

@@ -364,8 +364,8 @@ Fields an agent should read:
 
 `errors[].code` is one of `input_error`, `api_error`, `network_error`,
 `auth_required`, `input_required`, `cancelled`, `command_error`,
-`access_denied`, `unknown_error`, or a documented domain code such as
-`cloud_unavailable`. `access_denied` (exit 1) is an access problem — no
+`access_denied`, `output_error`, `unknown_error`, or a documented domain
+code such as `cloud_unavailable`. `access_denied` (exit 1) is an access problem — no
 organizations or an insufficient (viewer) role — distinct from `auth_required`
 (exit 4, missing/expired credentials).
 
@@ -408,14 +408,26 @@ Treat an answer as degraded if **any** of these hold:
 
 ### Large outputs and unknown flags
 
-- **Byte limit.** In `--agent` mode, envelopes over 200 KB are bounded
-  *without* breaking their shape: long text fields (usually embedded
-  transcripts) are shortened with `… [truncated N chars]`, then trailing list
-  items are dropped. `warnings[]` and `truncation.data` say exactly what was
-  cut (`dropped_items`, `complete: false`). `data` is still normal JSON, so
-  `data.frustrations[0].conversation_id` keeps working. For complete results,
-  page with a smaller `--limit` and `--offset`, or rerun with `--json` (no byte
-  limit).
+- **Byte limit.** In `--agent` mode, envelopes over 200 KB
+  (`MODA_AGENT_MAX_OUTPUT_BYTES`) are bounded *without* cutting any text or
+  breaking their shape: the complete output (the same JSON `--json` prints) is
+  written to a local file, and whole trailing list items are dropped from
+  `data`. `truncation.data.full_output_path` (also an `artifacts[]` entry of
+  kind `full_output`) is that file; read it in line ranges or with `jq`.
+  These files are pruned after 24 hours (`MODA_AGENT_OUTPUT_RETENTION_HOURS`).
+  `truncation.data` also says what was dropped (`dropped_items`,
+  `complete: false`). `data` is still normal JSON, so
+  `data.frustrations[0].conversation_id` keeps working. If even one item is
+  over budget, `data` is a stub `{ truncated, original_bytes, max_bytes,
+  full_output_path }`. If that file cannot be written (unwritable
+  `MODA_AGENT_OUTPUT_DIR`, full disk), nothing is dropped: the envelope keeps
+  the whole result over the limit with `status: "error"`, an `output_error`
+  (`cause: "full_output_save_failed"`), and exit `1`. If only the oversized
+  envelope text could not be saved (`cause: "envelope_text_save_failed"`),
+  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).
 - **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
@@ -446,6 +458,8 @@ fail instead of being clamped.
 time window. On `context`, `--window=0` returns only the anchor message (plus
 `total_messages`), and a value above 5 is clamped to 5 with a warning that
 prints the `--all --from --max-messages` command for a wider slice.
+`--metadata-only` returns only the summary and `total_messages`, with no
+messages.
 
 ### Schema introspection
 
@@ -534,11 +548,13 @@ compare scores across modes.
 Hand the anchors straight to `moda context`:
 
 ```bash
-# Find, then read the exact turn
-hit=$(moda search "double charge" --limit=1 | jq -r '.results[0]')
+# Find, then read the exact turn. --json prints the bare payload; piped output
+# without it is the agent envelope, where results sit under .data.results.
+hit=$(moda search "double charge" --limit=1 --json | jq -c '.results[0] // empty')
 cid=$(echo "$hit" | jq -r '.conversation_id')
-idx=$(echo "$hit" | jq -r '.message_index')
-moda context "$cid" --msg-index="$idx"
+# Trace-level fallback hits (match_grain: "trace") have no message_index.
+idx=$(echo "$hit" | jq -r '.message_index // empty')
+moda context "$cid" ${idx:+--msg-index="$idx"}
 ```
 
 ### 2. Overview (start here for health questions)
@@ -635,6 +651,7 @@ moda context <conversation_id>                # default window around middle
 moda context <conversation_id> --msg-index=5  # center on message 5
 moda context <conversation_id> --window=3     # 3 messages each side (max 5)
 moda context <conversation_id> --msg-index=40 --window=0  # just message 40 + total_messages
+moda context <conversation_id> --metadata-only  # summary + total_messages, no messages
 moda context <conversation_id> --all          # whole trace in order, first 500 messages
 moda context <conversation_id> --all --from=500 --max-messages=500  # continue (max 5000)
 ```
@@ -746,9 +763,9 @@ Pass `--include-window` to attach a `window` field per row (instead of
 (1–5, default `1`) is the half-width; `--window=1` ⇒ 3 messages total
 (anchor ± 1).
 
-Examples default to `--limit=5` (max 20). Strings inside `examples[]` longer
-than 300 characters are cut, and a warning says so; read the full text with
-the row's `context_command`. Agent output lists the 20 most frequent
+Examples default to `--limit=5` (max 20). Example text is returned whole; if
+the agent envelope goes over its byte limit, whole trailing examples are
+dropped and `truncation.data.full_output_path` holds every example. Agent output lists the 20 most frequent
 `subtypes` (`subtypes_total` has the full count); `--json` lists all.
 
 ### 7. Prompt management
@@ -1116,16 +1133,17 @@ and archiving an active custom signal (pause it, or delete a draft).
 
 ```bash
 # Semantic: find the moment a user expressed an intent, in their own words
-moda search "user wants to cancel subscription" --mode=semantic --limit=5 \
+moda search "user wants to cancel subscription" --mode=semantic --limit=5 --json \
   | jq -r '.results[] | "\(.conversation_id) @\(.message_index)  \(.snippet)"'
 
 # Keyword: locate every tool call/result mentioning an exact identifier
 moda search "stripe.refunds.create" --mode=keyword --limit=10
 
-# Search, then open the top hit at the exact turn
-moda search "rate limit exceeded" --limit=1 \
-  | jq -r '.results[0] | "\(.conversation_id) \(.message_index)"' \
-  | xargs -n2 sh -c 'moda context "$0" --msg-index="$1"'
+# Search, then open the top message-level hit at the exact turn (skips
+# trace-level fallback hits, which have no message_index)
+moda search "rate limit exceeded" --limit=5 --json \
+  | jq -r 'first(.results[] | select(.message_index != null)) | "\(.conversation_id) \(.message_index)"' \
+  | xargs -r -n2 sh -c 'moda context "$0" --msg-index="$1"'
 ```
 
 ### Daily health check