@moda-ai/cli 1.0.4 → 1.1.0

package/dist/schemas.js

@@ -1,5 +1,10 @@
 // src/schemas.ts
 import { z } from 'zod';
+// CLI flags arrive as strings; this coerces 'true'/'false' to booleans
+// at parse time so individual schemas can declare boolean fields cleanly.
+const boolFlag = () => z
+    .preprocess((val) => (val === 'true' ? true : val === 'false' ? false : val), z.boolean())
+    .optional();
 export const OverviewSchema = z.object({
     days_back: z.number().min(1).max(90).default(7).optional(),
 });
@@ -33,6 +38,8 @@ export const FrustrationsSchema = z.object({
     days_back: z.number().min(1).max(90).default(7).optional(),
     limit: z.number().min(1).max(20).default(10).optional(),
     offset: z.number().min(0).default(0).optional(),
+    include_window: boolFlag(),
+    window: z.number().min(1).max(5).default(1).optional(),
 });
 export const ToolFailuresSchema = z.object({
     days_back: z.number().min(1).max(90).default(7).optional(),
@@ -44,5 +51,42 @@ export const ToolFailureDetailSchema = z.object({
     days_back: z.number().min(1).max(90).default(7).optional(),
     limit: z.number().min(1).max(20).default(5).optional(),
     offset: z.number().min(0).default(0).optional(),
+    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'];
+const TIME_RANGES = ['all', '1h', '3d', '7d', '24h', '30d', '90d'];
+/** 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(),
+});
+/** moda loop <detectionId> — single loop detection detail. */
+export const LoopDetailSchema = z.object({
+    detection_id: z.string().uuid({ message: 'detection_id must be a UUID' }),
 });
 //# sourceMappingURL=schemas.js.map

package/dist/transforms.d.ts

@@ -0,0 +1,25 @@
+export interface FrustrationAnchor {
+    kind: 'frustration';
+    conversation_id: string;
+    msg_index: number | null;
+    signal: string | null;
+    quote_preview: string | null;
+    all_turns: number[];
+    no_anchor: boolean;
+}
+export interface ToolFailureAnchor {
+    kind: 'tool_failure';
+    conversation_id: string;
+    msg_index: number | null;
+    tool_name: string;
+    tool_use_id: string | null;
+    error_subtype: string | null;
+    no_anchor: boolean;
+}
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+export declare function asString(value: unknown): string | null;
+export declare function asNumber(value: unknown): number | null;
+export declare function withFrustrationAnchors(response: Record<string, unknown>): Record<string, unknown>;
+export declare function withToolFailureAnchors(response: Record<string, unknown>): Record<string, unknown>;
+export declare function embeddedWindowSize(conversation: Record<string, unknown> | null | undefined): number | null;
+//# sourceMappingURL=transforms.d.ts.map

package/dist/transforms.js

@@ -0,0 +1,102 @@
+export function asRecord(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+export function asString(value) {
+    return typeof value === 'string' ? value : null;
+}
+export function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function buildFrustrationAnchor(row) {
+    const conversation_id = asString(row.conversation_id) ?? '';
+    const userQuotes = Array.isArray(row.user_quotes) ? row.user_quotes : [];
+    const firstQuote = asRecord(userQuotes[0]);
+    const keyTurnsRaw = Array.isArray(row.key_turns) ? row.key_turns : [];
+    const all_turns = keyTurnsRaw.filter((t) => typeof t === 'number');
+    // Prefer key_turns[0] because the backend Data API centers the embedded
+    // windowed conversation on it; anchor must match that center so
+    // --include-window stays consistent.
+    let msg_index = null;
+    if (all_turns.length > 0) {
+        msg_index = all_turns[0];
+    }
+    if (msg_index === null && firstQuote) {
+        const turn = asNumber(firstQuote.turn);
+        if (turn !== null)
+            msg_index = turn;
+    }
+    let signal = null;
+    let quote_preview = null;
+    if (firstQuote) {
+        signal = asString(firstQuote.signal);
+        const quote = asString(firstQuote.quote);
+        if (quote !== null)
+            quote_preview = quote.slice(0, 200);
+    }
+    return {
+        kind: 'frustration',
+        conversation_id,
+        msg_index,
+        signal,
+        quote_preview,
+        all_turns,
+        no_anchor: msg_index === null,
+    };
+}
+function buildToolFailureAnchor(row, toolName) {
+    const conversation_id = asString(row.conversation_id) ?? '';
+    const msg_index = asNumber(row.msg_index);
+    const tool_use_id = asString(row.tool_use_id);
+    const error_subtype = asString(row.error_subtype);
+    return {
+        kind: 'tool_failure',
+        conversation_id,
+        msg_index,
+        tool_name: toolName,
+        tool_use_id,
+        error_subtype,
+        no_anchor: msg_index === null,
+    };
+}
+export function withFrustrationAnchors(response) {
+    if (!Array.isArray(response.frustrations))
+        return response;
+    const frustrations = response.frustrations.map((item) => {
+        const row = asRecord(item);
+        if (!row)
+            return item;
+        const anchor = buildFrustrationAnchor(row);
+        return { ...row, anchor };
+    });
+    return { ...response, frustrations };
+}
+export function withToolFailureAnchors(response) {
+    if (!Array.isArray(response.examples))
+        return response;
+    const toolName = asString(response.tool_name) ?? '';
+    const examples = response.examples.map((item) => {
+        const row = asRecord(item);
+        if (!row)
+            return item;
+        const anchor = buildToolFailureAnchor(row, toolName);
+        return { ...row, anchor };
+    });
+    return { ...response, examples };
+}
+export function embeddedWindowSize(conversation) {
+    if (!conversation)
+        return null;
+    const ctx = asRecord(conversation.context);
+    if (!ctx)
+        return null;
+    const center = asNumber(ctx.center_index);
+    const from = asNumber(ctx.from_index);
+    const to = asNumber(ctx.to_index);
+    if (center === null || from === null || to === null)
+        return null;
+    return Math.min(center - from, to - center);
+}
+//# sourceMappingURL=transforms.js.map

package/package.json

@@ -1,21 +1,19 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.0.4",
-  "description": "CLI and MCP server for Moda - AI agent analytics and observability",
+  "version": "1.1.0",
+  "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
-  "main": "dist/index.js",
   "bin": {
     "cli": "./dist/cli.js",
-    "moda": "./dist/cli.js",
-    "moda-mcp": "./dist/index.js"
+    "moda": "./dist/cli.js"
   },
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "!dist/__tests__",
+    "skills/**/SKILL.md",
     "README.md",
-    ".env.example",
-    "mcp-config.example.json"
+    ".env.example"
   ],
   "publishConfig": {
     "access": "public"
@@ -24,13 +22,10 @@
     "build": "tsc",
     "prepublishOnly": "tsc",
     "dev": "tsc --watch",
-    "start": "node dist/index.js",
-    "start:http": "node dist/http-server.js",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:ci": "vitest run",
-    "test:watch": "vitest",
-    "test:e2e": "npm run build && vitest run e2e"
+    "test:watch": "vitest"
   },
   "repository": {
     "type": "git",
@@ -40,28 +35,22 @@
     "moda",
     "llm",
     "observability",
-    "mcp",
     "cli",
     "analytics",
     "ai-agents"
   ],
-  "author": "Moda <hello@modaflows.com>",
+  "author": "Moda <hello@moda.dev>",
   "license": "MIT",
-  "homepage": "https://docs.modaflows.com/data-api/cli",
+  "homepage": "https://docs.moda.dev/data-api/cli",
   "bugs": {
     "url": "https://github.com/ModaLabs/moda-cli/issues"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.1",
-    "@modelcontextprotocol/sdk": "^1.0.4",
-    "cors": "^2.8.5",
-    "express": "^4.21.2",
     "open": "^11.0.0",
     "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.6",
     "@types/node": "^22.10.5",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"

package/skills/integrate-moda/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: integrate-moda
+description: Integrate the Moda SDK into this project for LLM observability. Use when the user asks to add Moda, set up observability, or instrument LLM calls.
+---
+
+# Integrate Moda SDK
+
+Moda auto-instruments LLM calls (OpenAI, Anthropic) via OpenTelemetry.
+After `Moda.init()`, all LLM calls are captured automatically — no wrappers needed.
+
+## Steps
+
+1. Install the SDK: `npm install moda-ai` (or bun/yarn/pnpm equivalent)
+2. Ensure `MODA_API_KEY` is set in the environment
+3. Initialize once at app startup, before any LLM client is created:
+
+```typescript
+import { Moda } from 'moda-ai';
+await Moda.init(process.env.MODA_API_KEY!);
+```
+
+Python: `import moda; moda.init()`
+
+4. Set conversation ID before LLM calls to group multi-turn conversations.
+   Without this, each call appears as a separate conversation in the dashboard.
+
+```typescript
+Moda.conversationId = sessionId;
+Moda.userId = userId; // optional but recommended
+```
+
+For concurrent requests, use scoped context:
+```typescript
+import { withConversationId } from 'moda-ai';
+await withConversationId(sessionId, async () => {
+  await openai.chat.completions.create({ ... });
+});
+```
+
+Python: `moda.conversation_id = session_id` or `with moda.set_conversation_id(session_id):`
+
+5. Flush pending traces before process exit: `await Moda.flush();`
+
+## Vercel AI SDK
+
+When using the `ai` package, auto-instrumentation does not cover it. Pass telemetry config:
+```typescript
+const result = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello',
+  experimental_telemetry: Moda.getVercelAITelemetry(),
+});
+```
+
+## Rules
+
+- Initialize Moda before creating any LLM client instances
+- Place `Moda.init()` in the app entry point, not in individual route handlers
+- Set `conversationId` per request/session, not globally
+- Use `withConversationId` in server environments handling concurrent requests
+- Call `Moda.flush()` in graceful shutdown handlers and before `process.exit()`
+- Do not wrap LLM calls — auto-instrumentation handles OpenAI and Anthropic automatically
+- Do not import or configure OpenTelemetry manually — Moda manages its own provider

package/skills/moda-cli/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: moda-cli
+description: Query Moda's AI agent conversation analytics from the terminal — overview KPIs, topic clusters, conversation search, message context, user frustration detections, tool failures, agent jobs (per-run outcomes), recurring workflows, and active loop detections. Use when the user asks about moda, modaflows, conversation analytics, user frustrations, agent observability, tool failure debugging, why an agent run partially completed or looped, or wants to investigate how their AI agent is performing.
+---
+
+# Moda CLI
+
+## What this skill does
+
+Wraps the `moda` CLI so the agent can query a Moda tenant's conversation
+analytics directly. Every command returns JSON on stdout; pipe to `jq` to
+filter. Read-only — no command in this skill modifies data.
+
+## When to use
+
+Activate this skill when the user wants to:
+
+- Inspect agent health: conversation volume, frustration rate, tool failures
+- Debug a specific frustrated conversation
+- Investigate which tools are failing and why
+- Browse conversation topics (clusters)
+- Search conversations by content, user, environment, or time range
+
+**Do not** activate for: writing code that calls the Moda Data API directly
+(use the API docs instead), instrumenting an app with the Moda SDK (different
+skill / docs), or any modification action — this CLI is read-only.
+
+## Required inputs
+
+Before running any command except `moda init`:
+
+- `MODA_API_KEY` env var must be set (`moda_sk_...`). If missing, run
+  `moda init` to provision one, or have the user export it.
+
+Optional:
+
+- `MODA_BASE_URL` defaults to `https://moda.dev`; override only for
+  self-hosted or staging.
+
+## Setup
+
+### First-time install
+
+```bash
+npm install -g @moda-ai/cli
+moda init                       # browser-based auth + key provisioning
+```
+
+Or one-shot via npx without installing:
+
+```bash
+npx -p @moda-ai/cli moda <command>
+```
+
+### Manual key
+
+```bash
+export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
+```
+
+## Procedure
+
+Default investigation pattern: **broad → narrow → context**. Always start with
+`moda overview` to ground subsequent calls in real numbers.
+
+### 1. Overview (always start here)
+
+```bash
+moda overview                        # last 7 days
+moda overview --days-back=30
+```
+
+Returns total conversations, trend, frustration rate, tool failure summary,
+top clusters, recent activity.
+
+### 2. Browse topic clusters
+
+```bash
+moda clusters                                 # root-level
+moda clusters --parent-id=<node_id>           # drill in
+moda cluster-conversations <node_id>          # conversations in cluster
+```
+
+### 3. Search conversations
+
+```bash
+export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
+```
+
+Filters: `--search`, `--cluster-id`, `--user-id`, `--time-range`
+(`all|1h|3d|7d|24h|30d|90d`), `--environment`
+(`all|development|staging|production`), `--limit`, `--offset`.
+
+### 4. Read a single conversation
+
+```bash
+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)
+```
+
+### 5. Frustration analysis
+
+```bash
+moda frustrations                             # last 7 days
+moda frustrations --days-back=14 --limit=20
+moda frustrations --include-window --window=1 --limit=5
+```
+
+Each result includes inline conversation snippet, user quotes, trajectory,
+signal breakdown (exasperation, profanity, anger, sarcasm, giving_up, insult),
+and primary cause.
+
+Every row carries a top-level `anchor` block:
+`{ kind: 'frustration', conversation_id, msg_index, signal, quote_preview,
+all_turns, no_anchor }`. `msg_index` is the 0-indexed turn where the
+frustration fired, derived from `key_turns[0]` (the same turn the API centers
+the embedded window on), falling back to `user_quotes[0].turn` when
+`key_turns` is empty — reference `anchor.conversation_id` and
+`anchor.msg_index` directly instead of digging into `user_quotes` to locate
+the moment.
+`no_anchor: true` means no anchor could be derived.
+
+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), the canonical
+"three lines" view.
+
+### 6. Tool failure investigation
+
+```bash
+moda tool-failures                            # which tools are breaking
+moda tool-failure-detail <tool_name>          # subtype breakdown + examples
+moda tool-failure-detail search --subtype=SEARCH_NO_RESULTS --limit=10
+moda tool-failure-detail search --include-window --window=1 --limit=5
+```
+
+Every example row in `tool-failure-detail` output carries a top-level
+`anchor` block:
+`{ kind: 'tool_failure', conversation_id, msg_index, tool_name, tool_use_id,
+error_subtype, no_anchor }`. `msg_index` is the 0-indexed turn of the failing
+tool call — reference `anchor.conversation_id` and `anchor.msg_index`
+directly instead of matching by `tool_use_id` against the conversation.
+`no_anchor: true` means no anchor could be derived.
+
+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
+
+```bash
+moda loops                                      # everything currently stuck
+moda loops --limit=10
+moda loop <detection_id>                        # one loop signature in detail
+```
+
+Loops are detected in real time by the conversation worker (tier 0/1) and
+the analytics container (tier 2). A row with `cycle_visits=378` means the
+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).
+
+## Common workflow recipes
+
+### Daily health check
+
+```bash
+moda overview --days-back=1
+moda frustrations --days-back=1 --limit=5
+moda tool-failures --days-back=1
+```
+
+### Debug a frustrated user
+
+```bash
+moda frustrations --days-back=7 --limit=10
+# Pick a conversation_id from output
+moda context <conversation_id>
+moda context <conversation_id> --msg-index=<turn>  # zoom on the bad turn
+```
+
+### Diagnose a flaky tool
+
+```bash
+moda tool-failures
+moda tool-failure-detail <tool_name>
+# Pick an example conversation_id from the output
+moda context <conversation_id>
+```
+
+### Explore what users are doing
+
+```bash
+moda clusters
+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
+# Pull primary causes of recent frustrations
+moda frustrations --days-back=7 | jq -r '.frustrations[].primary_cause'
+
+# Get conversation IDs for a search and fetch context for each
+for id in $(moda conversations --search="timeout" --limit=3 | jq -r '.conversations[].id'); do
+  moda context "$id"
+done
+
+# Tool failure leaderboard
+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.
+- Errors print to stderr with non-zero exit. Check stderr before claiming
+  success.
+- If the JSON has `"conversations": []` or `"frustrations": []`, the call
+  worked but the time window is empty — widen `--days-back` before
+  concluding "no data".
+
+## Troubleshooting
+
+**`Error: MODA_API_KEY environment variable is required`**
+Run `moda init`, or have the user export `MODA_API_KEY` from
+[moda.dev/settings](https://moda.dev/settings).
+
+**`API error (HTTP 401)`**
+Key is invalid or revoked. Re-run `moda init` to get a fresh one.
+
+**`API error (HTTP 404)` on `cluster-conversations`, `context`, or
+`tool-failure-detail`**
+The id/name doesn't exist in this tenant. Verify by listing first:
+`moda clusters`, `moda conversations`, or `moda tool-failures`.
+
+**`Validation error:`**
+A flag value didn't match the schema. Check enums (`time_range` must be
+`1h|24h|3d|7d|30d|90d|all`, not `"7 days"`) and numeric ranges
+(`days_back` is 1–90, `window` max 5).
+
+**Empty results**
+Widen the window: try `--days-back=30` or `--time-range=30d`. Confirm with
+`moda overview` that data exists in the tenant at all.
+
+**`moda: command not found`**
+Either install globally (`npm install -g @moda-ai/cli`) or invoke through
+npx: `npx -p @moda-ai/cli moda <command>`.
+
+## Reference: all commands at a glance
+
+| Command | Purpose |
+|---|---|
+| `moda init` | Browser auth + provision API key + install agent rules |
+| `moda overview` | Dashboard KPIs, top clusters, recent activity |
+| `moda clusters` | Browse topic cluster hierarchy |
+| `moda cluster-conversations <node_id>` | Conversations in a cluster |
+| `moda conversations` | Search/filter conversations |
+| `moda context <conversation_id>` | Windowed message context (max 5 per side) |
+| `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 |
+
+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>`.
+`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).

package/dist/__tests__/api-client.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=api-client.test.d.ts.map