@moda-ai/cli 1.55.36 → 1.55.38

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

@@ -44,6 +44,59 @@ slice centered on the anchor. `--window=N` (1–5, default `1`) is the
 half-width; `--window=1` ⇒ 3 messages total (anchor ± 1), the canonical
 "three lines" view.
 
+### 5a. Per-trace lists and dashboard filters (`--group-by=trace`)
+
+By default emotion and frustration rows are one per (trace, family)
+detection, and hallucination rows are one per scored message, so their
+`pagination.total` is NOT the dashboard's trace count. Every list response
+says which counting it uses in `counting` (`per_detection`, `per_message` or
+`per_trace`), and the agent summary repeats it.
+
+`--group-by=trace` reads the dashboard Signals tab's own list: one row per
+trace in `traces[]`, the dashboard's filters and sort, and a total that
+counts traces exactly as the dashboard does. Any filter below implies it.
+
+```bash
+moda detections list --family=emotion --group-by=trace                       # emotion tab, per trace
+moda detections list --family=frustration --trajectory=building              # implies --group-by=trace
+moda detections list --family=emotion:sadness --elicitor=bot --status=detected
+moda detections list --family=emotion --signal=sarcasm,anger --sort=risk_score --order=desc
+moda detections list --family=hallucination --rule=<rule_id> --status=all    # rule ids: summary.rule_breakdown
+moda detections list --family=hallucination --source=judge --sort=last_detected_at
+moda detections list --family=laziness --status=strong --sort=strong_count   # laziness is always per trace
+```
+
+| family | flags (values) |
+|---|---|
+| emotion, frustration | `--search` (trace ID or cause), `--status=all\|detected`, `--elicitor=bot\|external\|self\|ambiguous`, `--trajectory=none\|building\|peak\|resolved\|sustained`, `--signal=<s>[,<s>]`, `--sort=score\|risk_score\|detected_at\|message_count`, `--order=asc\|desc` |
+| hallucination | `--search` (trace ID), `--status=contradicted\|all`, `--rule=<rule_id>`, `--source=rule\|classifier\|gpu\|judge\|human`, `--sort=contradicted_count\|verified_count\|last_detected_at`, `--order` |
+| laziness | `--search` (trace ID), `--status=all\|strong`, `--sort=detections_count\|strong_count\|last_detected_at`, `--order` |
+
+The per-trace list has no user scope and no single-trace read: `--user-id`,
+`--conversation-id`, `--include-window` (and `--kind` for hallucinations) are
+rejected with it; drop the trace filters to use them. `summary` in a per-trace
+response covers the whole window and ignores the list filters (except
+hallucination `--rule`, which scopes the summary too, as on the dashboard).
+
+### 5b. Detector switched off, or trace not processed
+
+An empty detection list is not proof a trace is clean:
+
+- **Detector off.** `moda overview` lists every detector under `detectors`
+  (`enabled: true|false|null`, the `setting` it reads). The emotion stage
+  (every emotion family, frustration included) reads `signals.frustration`;
+  custom signals read `signals.custom_signals`; laziness, hallucination and
+  tool failures have no tenant switch. `detections list --family=emotion|frustration`
+  and `--family=custom_signal` carry the same state in `processing` and warn
+  when it is off.
+- **Not processed yet.** `traces list` rows carry `processing_status`
+  (`pending` until the pipeline completes the trace, then `complete`),
+  `error_message`, `indexed_at` and `membership_score` (use-case confidence
+  for `cluster_id`), the same values as the dashboard trace list.
+  `traces get` (including `--all`) carries them in `trace_state`. Both warn on
+  pending or errored traces: a pending trace may already have some detections,
+  but its detections may be incomplete.
+
 ### 6. Tool failure investigation
 
 ```bash
@@ -77,3 +130,43 @@ 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.
+`next_commands` include `moda tools get <tool_name>` for the tool's call
+count, success rate and schema.
+
+### 7. Tool catalog: calls, success rate and schema
+
+`moda detections tools` lists failing tools only. For the call denominator of
+every tool, healthy ones included, and for what a tool takes as input, use the
+Tool catalog (the same figures as the dashboard Tool catalog page):
+
+```bash
+moda tools list                                   # every tool, most called first
+moda tools list --sort=failure_rate --limit=10    # calls, failed calls, success rate
+moda tools list --search=calendar --direction=write
+moda tools get <tool_name>                        # stats, schema, usage, failure categories
+moda tools get <tool_name> --days-back=30 --full  # observed values and inputs uncut
+```
+
+`tools list` pages with `--limit` (1-200, default 25) and `--offset`; when
+`pagination.has_more` is true, `next_commands` holds the next page. Sorts are
+`calls`, `failure_rate`, `failures`, `traces`, `last_seen` (all descending).
+
+`tools get` returns `stats`, `definition.registered` (the description and
+schema pushed with `moda registry push` or added in the dashboard, else `null`),
+`definition.observed_fields` (keys seen in recorded call inputs, with types and
+common values), `usage` (calls and failed calls per day, or per hour under 7
+days), `tool_classes`, `effect_profile`, `failure_categories` and
+`recent_calls`. Each failure category carries `latest_failure`, a
+`context_command` that opens it, and an `examples_command`
+(`moda detections tools <tool_name> --subtype=<category>`). Agent output keeps
+20 observed fields with 3 common values each and 5 recent calls, and cuts
+inputs and sample errors at 200 characters (`*_total` fields give the full
+counts); `--full` keeps everything. The registered schema is never cut. A tool with no calls in the window is
+`not_found`.
+
+Two failure counts, from two sources: `calls`, `failed_calls` and
+`success_rate_pct` count recorded tool receipts (what the catalog shows);
+`stats.failure_detections` and `failure_categories` count classified tool
+failures, the same rows as `moda detections tools`. A call can succeed on its
+receipt and still be classified as a failure (wrong content, a policy block),
+so the second count can be higher. `metric_note` in each response says the same.