@moda-ai/cli 1.0.5 → 1.1.0

package/.env.example

@@ -1,8 +1,8 @@
 # Moda API Key (required)
-# Get this from https://app.modaflows.com/settings
+# Get this from https://moda.dev/settings
 MODA_API_KEY=moda_sk_...
 
 # Moda Backend URL (optional)
-# Defaults to production: https://modaflows.com
+# Defaults to production: https://moda.dev
 # For local development, override with:
 # MODA_BASE_URL=http://localhost:3001

package/README.md

@@ -1,6 +1,6 @@
 # moda-cli
 
-CLI for [Moda](https://modaflows.com) -- AI agent analytics and observability.
+CLI for [Moda](https://moda.dev) -- AI agent analytics and observability.
 
 Query your conversation analytics from the terminal.
 
@@ -30,7 +30,7 @@ Or set the key manually:
 export MODA_API_KEY="moda_sk_..."
 ```
 
-Get your API key from [modaflows.com/settings](https://modaflows.com/settings).
+Get your API key from [moda.dev/settings](https://moda.dev/settings).
 
 ## Usage
 
@@ -52,9 +52,11 @@ moda context <conversation_id> --msg-index=5     # Center on message 5
 
 moda frustrations                                # User frustration detections
 moda frustrations --days-back=14 --limit=20
+moda frustrations --include-window --window=1    # Attach 3-message slice per row
 
 moda tool-failures                               # Tool failure overview
 moda tool-failure-detail <tool_name>             # Per-tool failure detail
+moda tool-failure-detail <tool_name> --include-window --window=1
 
 # Agent runs runtime (workflows = recurring class, run = one execution)
 moda workflows --time-range=7d                   # Recurring workflow catalog with health
@@ -76,18 +78,48 @@ moda loops | jq '.loops | sort_by(-.cycle_visits) | .[0:5] | .[].loop_signature_
 moda workflows | jq '.workflows | sort_by(.health) | .[] | select(.health < 0.8)'
 ```
 
+## Anchors and message windows
+
+Rows returned by `moda frustrations` and `moda tool-failure-detail` carry
+a top-level `anchor` block naming the exact turn the event fired on:
+
+```json
+// frustrations
+{ "kind": "frustration",  "conversation_id": "...", "msg_index": 12,
+  "signal": "exasperation", "quote_preview": "...", "all_turns": [...],
+  "no_anchor": false }
+
+// tool-failure-detail examples
+{ "kind": "tool_failure",  "conversation_id": "...", "msg_index": 7,
+  "tool_name": "search", "tool_use_id": "...",
+  "error_subtype": "SEARCH_NO_RESULTS", "no_anchor": false }
+```
+
+`msg_index` is the 0-indexed turn where the breakage happened. For
+frustrations it's 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. `no_anchor: true` means no anchor could be derived for
+that row.
+
+Both commands accept two flags to inline a message window per row:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--include-window` | off | Attach a `window` field with the message slice centered on the anchor |
+| `--window=N` | `1` | Half-width (1–5). `--window=1` ⇒ 3 messages total (anchor ± 1) |
+
 ## Environment Variables
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `MODA_API_KEY` | Yes | -- | Your Moda API key (`moda_sk_...`) |
-| `MODA_BASE_URL` | No | `https://modaflows.com` | Base URL for the Data API |
+| `MODA_BASE_URL` | No | `https://moda.dev` | Base URL for the Data API |
 
 ## Documentation
 
-- [CLI Reference](https://docs.modaflows.com/data-api/cli)
-- [Data API Overview](https://docs.modaflows.com/data-api/overview)
-- [Quickstart](https://docs.modaflows.com/quickstart)
+- [CLI Reference](https://docs.moda.dev/data-api/cli)
+- [Data API Overview](https://docs.moda.dev/data-api/overview)
+- [Quickstart](https://docs.moda.dev/quickstart)
 
 ## License
 

package/dist/cli.d.ts

@@ -6,5 +6,6 @@ interface ParsedArgs {
 }
 export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function flagsToArgs(flags: Record<string, string>, positionalKey?: string, positionalValue?: string): Record<string, unknown>;
+export declare function runCommand(command: string, positional: string | undefined, flags: Record<string, string>): Promise<void>;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { validateConfig, VERSION } from './config.js';
 import { callDataAPI, ApiError } from './api-client.js';
 import { OverviewSchema, ClustersSchema, ClusterConversationsSchema, ConversationsSchema, ContextSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, WorkflowsSchema, RunsSchema, RunDetailSchema, LoopsSchema, LoopDetailSchema, } from './schemas.js';
+import { withFrustrationAnchors, withToolFailureAnchors, embeddedWindowSize, asRecord, asString, asNumber } from './transforms.js';
 export function parseArgs(argv) {
     const args = argv.slice(2);
     const command = args[0] || '';
@@ -107,7 +108,51 @@ Examples:
   moda loop 12345678-1234-1234-1234-1234567890ab`);
 }
 // --- Command Handlers ---
-async function runCommand(command, positional, flags) {
+async function attachWindows(rows, windowSize) {
+    return Promise.all(rows.map(async (row) => {
+        const anchor = asRecord(row.anchor);
+        if (!anchor || anchor.no_anchor === true) {
+            return { ...row, window: null };
+        }
+        const msg_index = asNumber(anchor.msg_index);
+        if (msg_index === null) {
+            return { ...row, window: null };
+        }
+        const conv_id = asString(anchor.conversation_id) ?? '';
+        if (!conv_id) {
+            return { ...row, window: null };
+        }
+        const conversation = asRecord(row.conversation);
+        // embedded window may be wider than requested (backend default = 2); reuse anything ≥ requested
+        const embedded = conversation ? embeddedWindowSize(conversation) : null;
+        if (conversation && embedded !== null && embedded >= windowSize) {
+            return { ...row, window: conversation };
+        }
+        try {
+            const query = new URLSearchParams();
+            query.set('msg_index', msg_index.toString());
+            query.set('window', windowSize.toString());
+            const data = await callDataAPI(`/conversations/${conv_id}/context?${query.toString()}`);
+            return { ...row, window: data };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { ...row, window: { error: message } };
+        }
+    }));
+}
+async function printWithOptionalWindows(enriched, listKey, includeWindow, windowSize) {
+    if (!includeWindow) {
+        console.log(JSON.stringify(enriched, null, 2));
+        return;
+    }
+    const list = Array.isArray(enriched[listKey])
+        ? enriched[listKey]
+        : [];
+    const withWindows = await attachWindows(list, windowSize);
+    console.log(JSON.stringify({ ...enriched, [listKey]: withWindows }, null, 2));
+}
+export async function runCommand(command, positional, flags) {
     switch (command) {
         case 'overview': {
             const args = flagsToArgs(flags);
@@ -201,7 +246,7 @@ async function runCommand(command, positional, flags) {
                 query.set('offset', params.offset.toString());
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/frustrations${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            await printWithOptionalWindows(withFrustrationAnchors(data), 'frustrations', params.include_window === true, params.window ?? 1);
             break;
         }
         case 'tool-failures': {
@@ -231,7 +276,7 @@ async function runCommand(command, positional, flags) {
                 query.set('offset', params.offset.toString());
             const queryString = query.toString() ? `?${query.toString()}` : '';
             const data = await callDataAPI(`/tool-failures/${params.tool_name}${queryString}`);
-            console.log(JSON.stringify(data, null, 2));
+            await printWithOptionalWindows(withToolFailureAnchors(data), 'examples', params.include_window === true, params.window ?? 1);
             break;
         }
         // ─── Workflows + Runs ──────────────────────────────────────

package/dist/config.js

@@ -1,11 +1,11 @@
 // src/config.ts
 export const VERSION = '1.0.4';
 export const MODA_API_KEY = process.env.MODA_API_KEY;
-export const MODA_BASE_URL = process.env.MODA_BASE_URL || 'https://modaflows.com';
+export const MODA_BASE_URL = process.env.MODA_BASE_URL || 'https://moda.dev';
 export function validateConfig() {
     if (!MODA_API_KEY) {
         console.error('Error: MODA_API_KEY environment variable is required');
-        console.error('Get your API key from https://modaflows.com/settings');
+        console.error('Get your API key from https://moda.dev/settings');
         process.exit(1);
     }
 }

package/dist/init/index.js

@@ -46,7 +46,7 @@ export async function runInit(flags) {
     console.log('  Now paste this into your coding agent to integrate Moda:\n');
     console.log('    Integrate the Moda SDK into this project. Follow the Moda SDK');
     console.log('    integration guide in the project rules.\n');
-    console.log('  Dashboard: https://modaflows.com');
+    console.log('  Dashboard: https://moda.dev');
     console.log('');
 }
 //# sourceMappingURL=index.js.map

package/dist/init/tenant.js

@@ -12,7 +12,7 @@ export async function selectTenantAndCreateKey() {
     console.log(`  Authenticated as ${ctx.user.email}`);
     // 2. Select tenant
     if (ctx.tenants.length === 0) {
-        console.error('  No organizations found. Create one at https://app.modaflows.com');
+        console.error('  No organizations found. Create one at https://moda.dev');
         process.exit(1);
     }
     let tenantId;

package/dist/schemas.d.ts

@@ -71,14 +71,20 @@ export declare const FrustrationsSchema: z.ZodObject<{
     days_back: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     offset: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    include_window: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
+    window: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
     days_back?: number | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
+    window?: number | undefined;
+    include_window?: boolean | undefined;
 }, {
     days_back?: number | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
+    window?: number | undefined;
+    include_window?: unknown;
 }>;
 export declare const ToolFailuresSchema: z.ZodObject<{
     days_back: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
@@ -93,17 +99,23 @@ export declare const ToolFailureDetailSchema: z.ZodObject<{
     days_back: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     limit: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     offset: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    include_window: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
+    window: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
 }, "strip", z.ZodTypeAny, {
     tool_name: string;
     days_back?: number | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
+    window?: number | undefined;
+    include_window?: boolean | undefined;
     subtype?: string | undefined;
 }, {
     tool_name: string;
     days_back?: number | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
+    window?: number | undefined;
+    include_window?: unknown;
     subtype?: string | undefined;
 }>;
 /** moda workflows — recurring workflow catalog (read from agent_job_classes). */

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,6 +51,8 @@ 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) ──────────────────
 //

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,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {
@@ -39,9 +39,9 @@
     "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"
   },

package/skills/moda-cli/SKILL.md

@@ -34,7 +34,7 @@ Before running any command except `moda init`:
 
 Optional:
 
-- `MODA_BASE_URL` defaults to `https://modaflows.com`; override only for
+- `MODA_BASE_URL` defaults to `https://moda.dev`; override only for
   self-hosted or staging.
 
 ## Setup
@@ -55,7 +55,7 @@ npx -p @moda-ai/cli moda <command>
 ### Manual key
 
 ```bash
-export MODA_API_KEY="moda_sk_..."   # from modaflows.com/settings
+export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
 ```
 
 ## Procedure
@@ -84,7 +84,7 @@ moda cluster-conversations <node_id>          # conversations in cluster
 ### 3. Search conversations
 
 ```bash
-export MODA_API_KEY="moda_sk_..."   # from modaflows.com/settings
+export MODA_API_KEY="moda_sk_..."   # from moda.dev/settings
 ```
 
 Filters: `--search`, `--cluster-id`, `--user-id`, `--time-range`
@@ -104,20 +104,49 @@ moda context <conversation_id> --window=3     # 3 messages each side (max 5)
 ```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
@@ -244,7 +273,7 @@ moda tool-failures | jq '.tools[] | {tool: .tool_name, failures: .failure_count}
 
 **`Error: MODA_API_KEY environment variable is required`**
 Run `moda init`, or have the user export `MODA_API_KEY` from
-[modaflows.com/settings](https://modaflows.com/settings).
+[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.
@@ -289,3 +318,6 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 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).