@moda-ai/cli 1.10.2 → 1.12.0

package/skills/moda-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: moda-cli
-version: 2.0.0
+version: 2.1.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, 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.
 ---
 
@@ -80,10 +80,14 @@ 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.
+Run `moda manifest --json` first when integrating with the CLI. It returns the
+hand-maintained `moda.manifest.v1` contract: commands, output modes, exit codes,
+event catalog, env vars, schema ids, and a glossary.
+
+`moda` is agent-safe: it picks an output mode automatically, signals the
+orchestrator's next action through exit codes, and emits schema-versioned JSON
+on stdout in agent modes. Errors also ride stdout envelopes/events in agent
+mode; stderr is only for human-mode prose/progress.
 
 ### Output mode auto-selection
 
@@ -111,8 +115,11 @@ 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. |
+| `1` | error — bad input, API/network failure, or unexpected failure | Read `errors[]`; retry only when the code is retryable. |
 | `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. |
+| `4` | auth required | Run `auth.login_command`, then re-run `auth.resume_command` if present. |
+| `5` | input required | Pick a choice, append its `resume_flags`, and re-run. |
+| `130` | cancelled | Treat as interrupted or closed pipe; do not retry blindly. |
 
 ### The `moda.agent.v1` envelope
 
@@ -126,10 +133,44 @@ Fields an agent should read:
 - `next_commands[]` — suggested follow-up commands (each carries `mutability`
   and `requires_approval`).
 - `warnings[]`, `errors[]`.
+- `meta.run_id` — correlates a non-stream envelope with stream events.
 - `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).
 
+`errors[].code` is one of `input_error`, `api_error`, `network_error`,
+`auth_required`, `input_required`, `cancelled`, `command_error`,
+`unknown_error`, or a documented domain code such as `cloud_unavailable`.
+
+### The `moda.agent_event.v1` stream
+
+Use `--agent --stream` for commands whose progress matters (`init`, `harness
+analyze`, and any command where liveness matters). The stream is NDJSON, one
+event per stdout line.
+
+Ordering guarantees:
+
+- First event of every agent-stream run is `started`.
+- `run_id` is constant within a run; `seq` starts at `1` and increments without
+  gaps.
+- Exactly one terminal event ends every stream: `completed`, `error`,
+  `cancelled`, `needs_input`, or `auth_required` — on every exit path including
+  thrown errors, SIGINT, and refused input. Absence of a terminal event = the CLI
+  crashed.
+- `heartbeat` fires every 10s (`MODA_HEARTBEAT_MS`, `0` disables) whenever no
+  other event is emitted. No heartbeat for more than 30s during a run is the
+  canonical stall signal.
+- Secrets are redacted at the emit boundary; never expect full `moda_sk_`,
+  `moda_ct_`, JWT, bearer token, or `api_key` values in events.
+
+Interaction is exit-and-reinvoke, not stdin:
+
+- `needs_input` carries `input_request: { id, question, kind, choices,
+  resume_command }` and exits `5`. Choose a value and re-run with that choice's
+  `resume_flags`.
+- `auth_required` carries `auth: { reason, login_command, resume_command }` and
+  exits `4`. Run the argv array in `login_command`, then resume.
+
 ### Detecting a degraded answer
 
 Treat an answer as degraded if **any** of these hold:
@@ -141,7 +182,8 @@ Treat an answer as degraded if **any** of these hold:
 ### Schema introspection
 
 ```bash
-moda --json-schemas      # print the JSON Schemas for the agent output contract
+moda manifest --json     # discover commands/events/exit codes/glossary
+moda --json-schemas      # print JSON Schemas for the output contract
 ```
 
 ### Recommended agent usage
@@ -151,6 +193,8 @@ 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" ;;
+  4) echo "$answer" | jq -r '.errors[0].message'; exit 4 ;;
+  5) echo "$answer" | jq -r '.errors[0].message'; exit 5 ;;
   *) echo "moda ask failed:"; echo "$answer" | jq -r '.errors[].message'; exit 1 ;;
 esac
 

package/dist/init/detect.d.ts

@@ -1,9 +0,0 @@
-export interface ProjectInfo {
-    language: 'typescript' | 'python' | null;
-    packageManager: string | null;
-    llmProviders: string[];
-}
-export declare function detectProject(): Promise<ProjectInfo>;
-export declare function installSDK(project: ProjectInfo): Promise<boolean>;
-export declare function getInitSnippet(project: ProjectInfo): string;
-//# sourceMappingURL=detect.d.ts.map

package/dist/init/detect.js

@@ -1,179 +0,0 @@
-// src/init/detect.ts — Project detection and SDK installation
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
-import { select, confirm } from '@inquirer/prompts';
-const LOCKFILE_TO_PM = {
-    'package-lock.json': 'npm',
-    'yarn.lock': 'yarn',
-    'pnpm-lock.yaml': 'pnpm',
-    'bun.lockb': 'bun',
-    'bun.lock': 'bun',
-    'poetry.lock': 'poetry',
-    'uv.lock': 'uv',
-};
-const INSTALL_COMMANDS = {
-    npm: 'npm install moda-ai',
-    yarn: 'yarn add moda-ai',
-    pnpm: 'pnpm add moda-ai',
-    bun: 'bun add moda-ai',
-    pip: 'pip install moda-ai',
-    poetry: 'poetry add moda-ai',
-    uv: 'uv add moda-ai',
-};
-const LLM_PATTERNS = [
-    { pattern: /from openai|import openai|require\(['"]openai['"]\)/i, name: 'OpenAI' },
-    { pattern: /from anthropic|import.*@anthropic-ai\/sdk|require\(['"]@anthropic-ai\/sdk['"]\)/i, name: 'Anthropic' },
-    { pattern: /from ai |import.*@ai-sdk|require\(['"](ai|@ai-sdk)/i, name: 'Vercel AI SDK' },
-    { pattern: /from langchain|import.*langchain/i, name: 'LangChain' },
-    { pattern: /from claude_agent_sdk|import.*claude.agent/i, name: 'Claude Agent SDK' },
-];
-export async function detectProject() {
-    const cwd = process.cwd();
-    const hasPackageJson = existsSync(join(cwd, 'package.json'));
-    const hasPython = existsSync(join(cwd, 'pyproject.toml')) ||
-        existsSync(join(cwd, 'requirements.txt')) ||
-        existsSync(join(cwd, 'Pipfile'));
-    let language = null;
-    if (hasPackageJson && hasPython) {
-        language = await select({
-            message: 'Both TypeScript and Python detected. Which to configure?',
-            choices: [
-                { name: 'TypeScript / JavaScript', value: 'typescript' },
-                { name: 'Python', value: 'python' },
-            ],
-        });
-    }
-    else if (hasPackageJson) {
-        language = 'typescript';
-    }
-    else if (hasPython) {
-        language = 'python';
-    }
-    // Detect package manager
-    let packageManager = null;
-    if (language === 'typescript') {
-        for (const [lockfile, pm] of Object.entries(LOCKFILE_TO_PM)) {
-            if (existsSync(join(cwd, lockfile))) {
-                packageManager = pm;
-                break;
-            }
-        }
-        // No lockfile — detect which package manager is actually installed
-        if (!packageManager) {
-            for (const pm of ['bun', 'pnpm', 'yarn', 'npm']) {
-                try {
-                    execSync(`${pm} --version`, { stdio: 'pipe' });
-                    packageManager = pm;
-                    break;
-                }
-                catch {
-                    // not installed
-                }
-            }
-            if (!packageManager)
-                packageManager = 'npm';
-        }
-    }
-    else if (language === 'python') {
-        if (existsSync(join(cwd, 'poetry.lock'))) {
-            packageManager = 'poetry';
-        }
-        else if (existsSync(join(cwd, 'uv.lock'))) {
-            packageManager = 'uv';
-        }
-        else {
-            packageManager = 'pip';
-        }
-    }
-    // Detect LLM providers (shallow scan)
-    const llmProviders = detectLLMProviders(cwd, language);
-    return { language, packageManager, llmProviders };
-}
-function detectLLMProviders(cwd, language) {
-    if (!language)
-        return [];
-    const providers = new Set();
-    const extensions = language === 'typescript' ? ['.ts', '.tsx', '.js', '.jsx', '.mjs'] : ['.py'];
-    const dirs = ['src', 'app', 'lib', '.'];
-    for (const dir of dirs) {
-        const dirPath = join(cwd, dir);
-        if (!existsSync(dirPath))
-            continue;
-        try {
-            const files = readdirSync(dirPath, { withFileTypes: true });
-            for (const file of files) {
-                if (!file.isFile())
-                    continue;
-                if (!extensions.some((ext) => file.name.endsWith(ext)))
-                    continue;
-                try {
-                    const content = readFileSync(join(dirPath, file.name), 'utf8');
-                    for (const { pattern, name } of LLM_PATTERNS) {
-                        if (pattern.test(content)) {
-                            providers.add(name);
-                        }
-                    }
-                }
-                catch {
-                    // Skip unreadable files
-                }
-            }
-        }
-        catch {
-            // Skip unreadable dirs
-        }
-    }
-    return Array.from(providers);
-}
-export async function installSDK(project) {
-    if (!project.packageManager)
-        return false;
-    const command = INSTALL_COMMANDS[project.packageManager];
-    if (!command)
-        return false;
-    const shouldInstall = await confirm({
-        message: `Install moda-ai SDK? (${command})`,
-        default: true,
-    });
-    if (!shouldInstall) {
-        console.log(`  Skipped. Run manually: ${command}`);
-        return false;
-    }
-    console.log(`  Installing moda-ai (${project.packageManager})...`);
-    try {
-        execSync(command, { cwd: process.cwd(), stdio: 'pipe' });
-        console.log('  Installed moda-ai');
-        return true;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(`  Warning: SDK install failed: ${message}`);
-        console.error(`  Run manually: ${command}`);
-        return false;
-    }
-}
-export function getInitSnippet(project) {
-    if (project.language === 'typescript') {
-        return `
-    import { Moda } from 'moda-ai';
-
-    await Moda.init(process.env.MODA_API_KEY!);
-    // Moda.conversationId = 'your-session-id';
-    // ... your LLM calls are auto-instrumented ...
-    await Moda.flush();
-`;
-    }
-    if (project.language === 'python') {
-        return `
-    import moda
-
-    moda.init()  # reads MODA_API_KEY from env
-    # moda.conversation_id = 'your-session-id'
-    # ... your LLM calls are auto-instrumented ...
-    moda.flush()
-`;
-    }
-    return '';
-}
-//# sourceMappingURL=detect.js.map