@moda-ai/cli 1.9.0 → 1.10.0

package/dist/profiles.js

@@ -2,7 +2,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, normalize, relative } from 'node:path';
 export const PROFILE_CONFIG_VERSION = 1;
-export const PROD_BASE_URL = 'https://www.moda.dev';
+export const PROD_BASE_URL = 'https://moda.dev';
 export const DEFAULT_INGEST_URL = 'https://moda-ingest.modas.workers.dev';
 export const DEFAULT_PROFILE_NAME = 'prod';
 function getEnv(options = {}) {
@@ -93,6 +93,65 @@ export function createDefaultProfiles(options = {}) {
         prod: profileDefaults('prod', 'prod', now),
     };
 }
+function isLoopbackHostname(hostname) {
+    const host = hostname.toLowerCase();
+    return (host === 'localhost' ||
+        host === '127.0.0.1' ||
+        host === '::1' ||
+        host === '[::1]');
+}
+export function isLoopbackBaseUrl(url) {
+    try {
+        return isLoopbackHostname(new URL(url).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function defaultBaseUrlForEnvironment(environment) {
+    if (environment === 'local')
+        return 'http://localhost:3000';
+    if (environment === 'staging')
+        return 'https://staging.moda.dev';
+    return PROD_BASE_URL;
+}
+function defaultIngestUrlForEnvironment(environment) {
+    if (environment === 'local')
+        return 'http://localhost:8787';
+    return DEFAULT_INGEST_URL;
+}
+function environmentAllowsLoopback(environment) {
+    return environment !== 'prod';
+}
+function sanitizeProfileBaseUrl(url, environment) {
+    const normalized = normalizeModaBaseUrl(url);
+    if (environmentAllowsLoopback(environment) || !isLoopbackBaseUrl(normalized)) {
+        return normalized;
+    }
+    return PROD_BASE_URL;
+}
+function sanitizeProfileIngestUrl(url, environment) {
+    if (!url)
+        return url;
+    if (environmentAllowsLoopback(environment) || !isLoopbackBaseUrl(url)) {
+        return url;
+    }
+    return DEFAULT_INGEST_URL;
+}
+function enforceNonLoopbackBaseUrl(url, environment) {
+    return sanitizeProfileBaseUrl(url, environment);
+}
+function enforceNonLoopbackIngestUrl(url, environment) {
+    return sanitizeProfileIngestUrl(url, environment) ?? defaultIngestUrlForEnvironment(environment);
+}
+function activeProfileEnvironment(options) {
+    try {
+        return getActiveProfile(options).environment;
+    }
+    catch {
+        return 'prod';
+    }
+}
 function normalizeEnvironment(value) {
     if (value === 'local' ||
         value === 'dev' ||
@@ -131,8 +190,8 @@ function normalizeProfile(fallbackName, value, options) {
     const defaults = profileDefaults(name, normalizeEnvironment(value.environment), options.now ?? new Date());
     return {
         ...defaults,
-        base_url: optionalString(value.base_url) ?? defaults.base_url,
-        ingest_url: optionalString(value.ingest_url) ?? defaults.ingest_url,
+        base_url: sanitizeProfileBaseUrl(optionalString(value.base_url) ?? defaults.base_url, normalizeEnvironment(value.environment)),
+        ingest_url: sanitizeProfileIngestUrl(optionalString(value.ingest_url) ?? defaults.ingest_url, normalizeEnvironment(value.environment)),
         tenant_id: optionalString(value.tenant_id),
         workspace_id: optionalString(value.workspace_id),
         api_key_ref: normalizeSecretReference(value.api_key_ref),
@@ -170,9 +229,12 @@ function applyLegacyAwareness(config, options) {
     const migration = inspectProfileMigrationState(options);
     const prod = config.profiles.prod;
     if (prod && (legacy.api_key || legacy.ingest_url || legacy.tenant_id)) {
+        const migratedIngestUrl = legacy.ingest_url && !isLoopbackBaseUrl(legacy.ingest_url)
+            ? legacy.ingest_url
+            : prod.ingest_url;
         config.profiles.prod = {
             ...prod,
-            ingest_url: legacy.ingest_url ?? prod.ingest_url,
+            ingest_url: migratedIngestUrl,
             tenant_id: legacy.tenant_id ?? prod.tenant_id,
             api_key_ref: legacy.api_key ? 'legacy:config.api_key' : prod.api_key_ref,
             auth_token_ref: migration.legacy_auth.has_access_token
@@ -343,17 +405,58 @@ export function resolveApiKeyFromActiveProfile(options = {}) {
         return undefined;
     }
 }
+/**
+ * Vercel serves moda.dev as canonical and 308-redirects www to the apex. Node
+ * fetch strips Authorization on cross-host redirects, which breaks moda init
+ * step 3 when the base URL still points at www.
+ */
+export function normalizeModaBaseUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.hostname === 'www.moda.dev') {
+            parsed.hostname = 'moda.dev';
+            return parsed.toString().replace(/\/$/, '');
+        }
+    }
+    catch {
+        // Not a valid URL; return unchanged and let the caller surface the error.
+    }
+    return url.replace(/\/$/, '');
+}
 export function resolveBaseUrl(options = {}) {
+    const environment = activeProfileEnvironment(options);
     const envBase = optionalString(getEnv(options).MODA_BASE_URL);
-    if (envBase)
-        return envBase;
+    if (envBase) {
+        return enforceNonLoopbackBaseUrl(normalizeModaBaseUrl(envBase), environment);
+    }
     try {
-        return getActiveProfile(options).base_url || PROD_BASE_URL;
+        return enforceNonLoopbackBaseUrl(normalizeModaBaseUrl(getActiveProfile(options).base_url || PROD_BASE_URL), environment);
     }
     catch {
         return PROD_BASE_URL;
     }
 }
+export function resolveIngestUrl(options = {}) {
+    const environment = activeProfileEnvironment(options);
+    const envIngest = optionalString(getEnv(options).MODA_INGEST_URL);
+    if (envIngest) {
+        return enforceNonLoopbackIngestUrl(envIngest, environment);
+    }
+    try {
+        const profileIngest = getActiveProfile(options).ingest_url;
+        if (profileIngest) {
+            return enforceNonLoopbackIngestUrl(profileIngest, environment);
+        }
+    }
+    catch {
+        // Fall through to legacy/default below.
+    }
+    const legacyIngest = optionalString(loadLegacyCliConfig(options).ingest_url);
+    if (legacyIngest) {
+        return enforceNonLoopbackIngestUrl(legacyIngest, environment);
+    }
+    return defaultIngestUrlForEnvironment(environment);
+}
 export function resolveIngestUrlFromActiveProfile(options = {}) {
     try {
         return getActiveProfile(options).ingest_url;

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
@@ -190,14 +210,14 @@ export declare const RunsSchema: z.ZodObject<{
     limit?: number | undefined;
     offset?: number | undefined;
     user_id?: string | undefined;
-    outcome?: "unknown" | "running" | "failed" | "succeeded" | "partial" | "loop" | "abandoned" | undefined;
+    outcome?: "unknown" | "loop" | "running" | "failed" | "succeeded" | "partial" | "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;
+    outcome?: "unknown" | "loop" | "running" | "failed" | "succeeded" | "partial" | "abandoned" | undefined;
     class_id?: string | undefined;
 }>;
 /** moda run <runId> — single execution detail with side-effect receipts. */

package/dist/schemas.js

@@ -68,6 +68,16 @@ export const ToolFailureDetailSchema = z.object({
     include_window: boolFlag(),
     window: z.number().min(1).max(5).default(1).optional(),
 });
+/**
+ * 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(),
+});
 // ─── Workflows + Runs (agent runs runtime) ──────────────────
 //
 // Naming model:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "CLI for Moda - AI agent analytics and observability",
   "type": "module",
   "bin": {
@@ -13,8 +13,7 @@
     "!dist/__tests__",
     "hooks/**",
     "skills/**/SKILL.md",
-    "README.md",
-    ".env.example"
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"

package/skills/moda-cli/SKILL.md

@@ -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
@@ -393,6 +536,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 +587,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 |

package/.env.example

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