@moda-ai/cli 1.9.6 → 1.10.1

package/dist/schemas.d.ts

@@ -141,6 +141,26 @@ export declare const ToolFailureDetailSchema: z.ZodObject<{
     include_window?: unknown;
     subtype?: string | undefined;
 }>;
+/**
+ * moda audit <conversation_id|trace_id> — raw, non-deduped span/trace read.
+ * `kind=auto` (default) lets the backend try trace first, then conversation.
+ */
+export declare const AuditSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodOptional<z.ZodDefault<z.ZodEnum<["auto", "trace", "conversation"]>>>;
+    include_raw: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
+    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    kind?: "auto" | "trace" | "conversation" | undefined;
+    limit?: number | undefined;
+    include_raw?: boolean | undefined;
+}, {
+    id: string;
+    kind?: "auto" | "trace" | "conversation" | undefined;
+    limit?: number | undefined;
+    include_raw?: unknown;
+}>;
 /**
  * moda search "<query>" — keyword/semantic/hybrid search across conversation
  * messages. `q` arrives as a positional arg; the runCommand handler rejects an
@@ -165,49 +185,6 @@ export declare const SearchSchema: z.ZodObject<{
     limit?: number | undefined;
     user_id?: string | undefined;
 }>;
-/** moda workflows — recurring workflow catalog (read from agent_job_classes). */
-export declare const WorkflowsSchema: z.ZodObject<{
-    time_range: z.ZodOptional<z.ZodDefault<z.ZodEnum<["all", "1h", "3d", "7d", "24h", "30d", "90d"]>>>;
-    user_id: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    time_range?: "all" | "1h" | "3d" | "7d" | "24h" | "30d" | "90d" | undefined;
-    user_id?: string | undefined;
-}, {
-    time_range?: "all" | "1h" | "3d" | "7d" | "24h" | "30d" | "90d" | undefined;
-    user_id?: string | undefined;
-}>;
-/** moda runs — list workflow executions with classified outcomes. */
-export declare const RunsSchema: z.ZodObject<{
-    time_range: z.ZodOptional<z.ZodDefault<z.ZodEnum<["all", "1h", "3d", "7d", "24h", "30d", "90d"]>>>;
-    outcome: z.ZodOptional<z.ZodEnum<["running", "succeeded", "partial", "failed", "loop", "abandoned", "unknown"]>>;
-    /** Filter to one workflow class id (e.g. cron:helpscout-triage-hourly). */
-    class_id: z.ZodOptional<z.ZodString>;
-    user_id: z.ZodOptional<z.ZodString>;
-    limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
-    offset: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
-}, "strip", z.ZodTypeAny, {
-    time_range?: "all" | "1h" | "3d" | "7d" | "24h" | "30d" | "90d" | undefined;
-    limit?: number | undefined;
-    offset?: number | undefined;
-    user_id?: string | undefined;
-    outcome?: "unknown" | "running" | "failed" | "succeeded" | "partial" | "loop" | "abandoned" | undefined;
-    class_id?: string | undefined;
-}, {
-    time_range?: "all" | "1h" | "3d" | "7d" | "24h" | "30d" | "90d" | undefined;
-    limit?: number | undefined;
-    offset?: number | undefined;
-    user_id?: string | undefined;
-    outcome?: "unknown" | "running" | "failed" | "succeeded" | "partial" | "loop" | "abandoned" | undefined;
-    class_id?: string | undefined;
-}>;
-/** moda run <runId> — single execution detail with side-effect receipts. */
-export declare const RunDetailSchema: z.ZodObject<{
-    run_id: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    run_id: string;
-}, {
-    run_id: string;
-}>;
 /** moda loops — currently active loop detections. */
 export declare const LoopsSchema: z.ZodObject<{
     limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;

package/dist/schemas.js

@@ -68,13 +68,16 @@ export const ToolFailureDetailSchema = z.object({
     include_window: boolFlag(),
     window: z.number().min(1).max(5).default(1).optional(),
 });
-// ─── Workflows + Runs (agent runs runtime) ──────────────────
-//
-// Naming model:
-//   workflow = the recurring class definition (e.g. cron:helpscout-triage-hourly)
-//   run      = one execution of a workflow
-// `moda workflows` lists the catalog; `moda runs` lists executions.
-const RUN_OUTCOMES = ['running', 'succeeded', 'partial', 'failed', 'loop', 'abandoned', 'unknown'];
+/**
+ * moda audit <conversation_id|trace_id> — raw, non-deduped span/trace read.
+ * `kind=auto` (default) lets the backend try trace first, then conversation.
+ */
+export const AuditSchema = z.object({
+    id: z.string().min(1),
+    kind: z.enum(['auto', 'trace', 'conversation']).default('auto').optional(),
+    include_raw: boolFlag(),
+    limit: z.number().min(1).max(1000).default(200).optional(),
+});
 const TIME_RANGES = ['all', '1h', '3d', '7d', '24h', '30d', '90d'];
 const SEARCH_MODES = ['keyword', 'semantic', 'hybrid'];
 /**
@@ -89,25 +92,6 @@ export const SearchSchema = z.object({
     time_range: z.enum(TIME_RANGES).default('all').optional(),
     limit: z.number().min(1).max(100).default(20).optional(),
 });
-/** moda workflows — recurring workflow catalog (read from agent_job_classes). */
-export const WorkflowsSchema = z.object({
-    time_range: z.enum(TIME_RANGES).default('all').optional(),
-    user_id: z.string().optional(),
-});
-/** moda runs — list workflow executions with classified outcomes. */
-export const RunsSchema = z.object({
-    time_range: z.enum(TIME_RANGES).default('7d').optional(),
-    outcome: z.enum(RUN_OUTCOMES).optional(),
-    /** Filter to one workflow class id (e.g. cron:helpscout-triage-hourly). */
-    class_id: z.string().optional(),
-    user_id: z.string().optional(),
-    limit: z.number().min(1).max(100).default(50).optional(),
-    offset: z.number().min(0).default(0).optional(),
-});
-/** moda run <runId> — single execution detail with side-effect receipts. */
-export const RunDetailSchema = z.object({
-    run_id: z.string().uuid({ message: 'run_id must be a UUID' }),
-});
 /** moda loops — currently active loop detections. */
 export const LoopsSchema = z.object({
     limit: z.number().min(1).max(200).default(25).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.9.6",
+  "version": "1.10.1",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {

package/skills/moda-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: moda-cli
 version: 2.0.0
-description: Query Moda's AI agent conversation analytics and manage code-first prompt versions from the terminal — semantic/keyword/hybrid message search, overview KPIs, topic clusters, message context, user frustration detections, tool failures, agent jobs, recurring workflows, active loop detections, and moda prompts status/sync/promote. Use when the user asks about moda, modaflows, conversation analytics, prompt management, user frustrations, agent observability, tool failure debugging, why an agent run partially completed or looped, wants to find conversations or tool calls about a topic, or wants to investigate how their AI agent is performing.
+description: Query Moda's AI agent conversation analytics and manage code-first prompt versions from the terminal — semantic/keyword/hybrid message search, overview KPIs, topic clusters, message context, user frustration detections, tool failures, active loop detections, and moda prompts status/sync/promote. Use when the user asks about moda, modaflows, conversation analytics, prompt management, user frustrations, agent observability, tool failure debugging, wants to find conversations or tool calls about a topic, or wants to investigate how their AI agent is performing.
 ---
 
 # Moda CLI
@@ -78,6 +78,87 @@ npx -p @moda-ai/cli moda <command>
 export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
 ```
 
+## Agent protocol
+
+`moda` is agent-safe: it picks an output mode automatically, signals how much
+to trust an answer through exit codes, and (in agent mode) emits a
+schema-versioned `moda.agent.v1` JSON envelope you can parse instead of
+scraping prose.
+
+### Output mode auto-selection
+
+The mode is resolved in this priority order — first match wins, so you usually
+need no flags at all:
+
+1. **Explicit flags** override everything:
+   - `--agent` — `moda.agent.v1` schema-versioned JSON envelope
+   - `--json` — raw JSON payload (no envelope)
+   - `--agent --stream` — NDJSON stream of `moda.agent_event.v1` events
+   - `--human` — force human prose
+2. **`MODA_FORMAT` env var** — one of `human | json | agent | agent-stream`.
+3. **Agent-environment auto-detect** — if `CLAUDECODE`, `CURSOR`, `CI`, or
+   `MODA_AGENT` is set, default to the agent JSON envelope.
+4. **TTY auto-detect** — if stdout is not a TTY (piped or redirected), default
+   to the agent JSON envelope; an interactive terminal defaults to human prose.
+
+Running `moda` from inside Claude Code / Cursor, in CI, or through a pipe
+already yields agent JSON — no flag required.
+
+### Exit codes
+
+Branch on the exit code; it is stable and cheaper than parsing the payload:
+
+| Exit | Meaning | How to treat it |
+|---|---|---|
+| `0` | ok — answer is grounded in Moda Cloud intelligence | Trust it. |
+| `3` | degraded — Moda Cloud was unavailable; answer synthesized from local Data API evidence | Answer is present but lower-trust; verify before acting. |
+| `1` | error — bad input, unknown command, or unexpected failure | Read `errors[]` in the envelope. |
+
+### The `moda.agent.v1` envelope
+
+Fields an agent should read:
+
+- `status` — `ok` | `degraded` | `error`.
+- `summary.text` + `summary.confidence` — the answer and how much to trust it
+  (`high | medium | low | unknown`).
+- `evidence_refs[]` — each `{ id, kind, label, path }`. When `path` looks like
+  `conversation/<id>`, open it with `moda context <id>`.
+- `next_commands[]` — suggested follow-up commands (each carries `mutability`
+  and `requires_approval`).
+- `warnings[]`, `errors[]`.
+- `data` — the raw command payload. For `ask`, `data.source` is `cloud` or
+  `local_fallback` and `data.degraded` is a boolean — the canonical in-payload
+  way to detect degradation (in addition to exit code 3).
+
+### Detecting a degraded answer
+
+Treat an answer as degraded if **any** of these hold:
+
+- exit code is `3`, **or**
+- `data.degraded === true` (for `ask`; equivalently `data.source === "local_fallback"`), **or**
+- `status === "degraded"`.
+
+### Schema introspection
+
+```bash
+moda --json-schemas      # print the JSON Schemas for the agent output contract
+```
+
+### Recommended agent usage
+
+```bash
+answer=$(moda ask "what should I fix first?")
+case $? in
+  0) printf 'grounded answer:\n%s\n' "$answer" ;;
+  3) printf 'DEGRADED (local fallback — verify before acting):\n%s\n' "$answer" ;;
+  *) echo "moda ask failed:"; echo "$answer" | jq -r '.errors[].message'; exit 1 ;;
+esac
+
+# Pull the trusted parts straight out of the envelope
+echo "$answer" | jq -r '.summary.text'
+echo "$answer" | jq -r '.evidence_refs[] | "\(.kind)\t\(.label)\t\(.path // "")"'
+```
+
 ## Procedure
 
 Two entry points depending on the question:
@@ -146,6 +227,47 @@ moda overview --days-back=30
 Returns total conversations, trend, frustration rate, tool failure summary,
 top clusters, recent activity.
 
+### 2b. Ask & investigate (production intelligence)
+
+`moda ask` answers a natural-language production/harness question; `moda
+investigate` returns a ranked, evidence-backed list of the issues worth fixing
+first. Both default to the last 7 days (`--days-back=N`, 1–90).
+
+```bash
+moda ask "what should I fix first?"               # grounded answer + evidence
+moda ask "why are refunds failing?" --days-back=30
+moda investigate                                  # ranked findings, last 7d
+moda investigate --days-back=14
+moda overview                                     # health briefing (see §2)
+```
+
+In an agent environment these emit the `moda.agent.v1` envelope (see
+[Agent protocol](#agent-protocol)). For `ask`, branch on the exit code (`0`
+grounded, `3` degraded, `1` error) and read `data.source` /
+`data.degraded` to know whether the answer came from Moda Cloud or a local
+Data API fallback. Abbreviated envelope:
+
+```json
+{
+  "schema_version": "moda.agent.v1",
+  "command": "ask",
+  "status": "degraded",
+  "summary": { "text": "Strongest signal is: lookupCustomer is failing in production.", "confidence": "medium" },
+  "evidence_refs": [
+    { "id": "tool:lookupCustomer", "kind": "tool_failure", "label": "lookupCustomer: 12 failure(s)", "path": null }
+  ],
+  "next_commands": [
+    { "command": "moda tool-failure-detail lookupCustomer --include-window", "purpose": "Inspect tool failure examples and conversation anchors.", "mutability": "read", "requires_approval": false }
+  ],
+  "warnings": ["Cloud ask endpoint unavailable; synthesized answer from local Data API evidence."],
+  "errors": [],
+  "data": { "source": "local_fallback", "degraded": true, "question": "what should I fix first?", "answer": "…", "confidence": "medium" }
+}
+```
+
+`moda investigate` also accepts scoping flags (`--tool`, `--run`,
+`--conversation`, `--loop`) to focus the ranking on one signal.
+
 ### 3. Browse topic clusters
 
 ```bash
@@ -178,6 +300,27 @@ 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` is turn-windowed (≤5 turns, deduped, no tool spans). For the raw,
+complete picture of what was captured — every span, the parent/child hierarchy,
+tool calls, prompt/response bodies, and `gen_ai.*` attributes — use `moda audit`.
+
+### 4b. Audit raw spans/trace (completeness, orphans, duplicates)
+
+```bash
+moda audit <conversation_id|trace_id>         # auto-detects trace vs conversation
+moda audit <trace_id> --kind=trace            # force trace lookup
+moda audit <conversation_id> --include-raw    # attach verbatim raw_event bodies
+```
+
+Returns the raw, NON-deduped span set from the Layer-0 store (`events_raw`), so
+nothing is collapsed. Use it to verify capture completeness: the `summary` gives
+`total_spans`, `by_type` (llm/tool/agent/…), plus `orphan_count` (spans whose
+parent is missing) and `duplicate_count` (double-instrumentation — the same
+logical call emitted as >1 span). Each span carries `span_id`, `parent_span_id`,
+`trace_id`, `type` (tool spans included), timing, `prompt`, `response`, and the
+full semconv `attributes`. This is the honest substrate for auditing whether
+Moda captured every LLM/tool call for a conversation.
+
 ### 5. Frustration analysis
 
 ```bash
@@ -226,42 +369,7 @@ Pass `--include-window` to attach a `window` field per row with the message
 slice centered on the anchor. `--window=N` (1–5, default `1`) is the
 half-width; `--window=1` ⇒ 3 messages total (anchor ± 1).
 
-### 7. Workflow runs and outcomes
-
-Every triggered run of an agent (cron invocation, scheduled task, or
-interactive session) is classified `succeeded | partial | failed | loop |
-abandoned`. Use this layer to answer "did the job actually do its work?",
-which is structurally different from "did it error?" — most jobs that
-partially completed never threw.
-
-```bash
-moda runs                                       # last 7d, all outcomes
-moda runs --time-range=24h --outcome=partial    # which runs only half-finished
-moda runs --outcome=loop                        # runs caught in active loops
-moda runs --class-id=cron:helpscout-triage-hourly --limit=20
-moda run <run_id>                               # one execution + its side-effect receipts
-```
-
-`moda run <run_id>` returns the `agent_jobs` row plus every
-`side_effect_receipts` entry for the run — i.e. every tool call the agent
-made (read / write / send / spawn / compute), with success status and
-target system. This is the agent-as-employee log; use it instead of (or
-alongside) `moda context` when debugging "what did the agent actually
-DO".
-
-### 8. Recurring workflows / cron status board
-
-```bash
-moda workflows                                  # health per recurring class
-moda workflows --time-range=7d                  # filter to last 7d of activity
-```
-
-Each row is one job class (a cron slug, idea-widget id, or sourceType)
-with 30d rolling success / partial / failed / loop counts and a
-`health_score` (0–1). Sort by health to find degraded customer-facing
-crons that aren't crashing but aren't completing either.
-
-### 9. Active loop investigation
+### 7. Active loop investigation
 
 ```bash
 moda loops                                      # everything currently stuck
@@ -275,7 +383,7 @@ agent re-ran the same action 378 times. Use the `loop_signature_human`
 field to recognize cross-conversation patterns (one tool definition bug
 will produce identical signatures across many users).
 
-### 10. Prompt management
+### 8. Prompt management
 
 Use these only when working on the code-first prompt registry.
 
@@ -362,19 +470,6 @@ moda clusters --parent-id=<node_id>
 moda cluster-conversations <node_id>
 ```
 
-### Find degraded crons before customers do
-
-```bash
-# Health-sorted workflow board
-moda workflows | jq '.workflows | sort_by(.health) | .[] | select(.runs >= 4 and .health < 0.85)'
-
-# What loops are eating tokens right now?
-moda loops --limit=20 | jq '.loops[] | {sig: .loop_signature_human, visits: .cycle_visits, conv: .conversation_id}'
-
-# Drill into a partial run
-moda runs --outcome=partial --limit=5 | jq -r '.runs[].job_id' | head -1 | xargs -I{} moda run {}
-```
-
 ### One-liner chains with jq
 
 ```bash
@@ -393,6 +488,9 @@ moda tool-failures | jq '.tools[] | {tool: .tool_name, failures: .failure_count}
 ## Validation — how to know it worked
 
 - Every successful command exits 0 and prints valid JSON to stdout.
+- `moda ask` / `moda investigate` may exit `3` (degraded): a real,
+  lower-trust answer synthesized from local evidence — not a failure. Treat
+  exit `1` as the only hard error (see [Agent protocol](#agent-protocol)).
 - Errors print to stderr with non-zero exit. Check stderr before claiming
   success.
 - If the JSON has `"conversations": []` or `"frustrations": []`, the call
@@ -441,6 +539,8 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda init` | Browser auth + provision API key + install agent rules |
 | `moda search "<query>"` | **Message-grain semantic/keyword/hybrid search (incl. tool calls); primary content-discovery path** |
 | `moda overview` | Dashboard KPIs, top clusters, recent activity |
+| `moda ask "<question>"` | Natural-language production/harness answer with evidence (exit `3` = degraded local fallback) |
+| `moda investigate` | Rank production issues with evidence + next commands |
 | `moda clusters` | Browse topic cluster hierarchy |
 | `moda cluster-conversations <node_id>` | Conversations in a cluster |
 | `moda conversations` | List/filter conversations by structured fields |
@@ -448,9 +548,6 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda frustrations` | User frustration detections with evidence |
 | `moda tool-failures` | Tool failure overview |
 | `moda tool-failure-detail <tool_name>` | Per-tool failure breakdown + examples |
-| `moda workflows` | Recurring workflow catalog with 30d health per class |
-| `moda runs` | Recent workflow executions with classified outcomes |
-| `moda run <run_id>` | One execution + its side-effect receipts |
 | `moda loops` | Currently-active loop detections |
 | `moda loop <detection_id>` | One loop signature with blast radius |
 | `moda prompts status` | Read-only local prompt status |
@@ -462,8 +559,7 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 `--user-id`, `--time-range=<range>`, `--limit=N` (1–100, default 20).
 
 Common flags across most commands: `--days-back=N` (1–90), `--limit=N`,
-`--offset=N`, `--time-range=<range>`. Runs commands also accept
-`--outcome=<outcome>`, `--class-id=<workflow_class_id>`, and `--user-id=<id>`.
+`--offset=N`, `--time-range=<range>`.
 `frustrations` and `tool-failure-detail` additionally accept
 `--include-window` (attach a `window` slice per row) and `--window=N` (1–5,
 default `1`; half-width, so `--window=1` ⇒ 3 messages).