@moda-ai/cli 1.10.2 → 1.11.0

package/dist/skills.d.ts

@@ -1,4 +1,4 @@
-import type { ParsedArgs } from './cli.js';
+import { type CommandContext } from './command-context.js';
 import type { ProfileIOOptions } from './profiles.js';
 interface PullSummary {
     total: number;
@@ -46,6 +46,12 @@ export declare function runSkillSync(flags?: Record<string, string>, profileOpti
 /**
  * `moda skills <subcommand>` dispatcher.
  */
-export declare function runSkillsCommand(args: ParsedArgs): Promise<number>;
+type LegacySkillsArgs = {
+    command: string;
+    positional: string | undefined;
+    positionals: string[];
+    flags: Record<string, string>;
+};
+export declare function runSkillsCommand(input: CommandContext | LegacySkillsArgs): Promise<number>;
 export {};
 //# sourceMappingURL=skills.d.ts.map

package/dist/skills.js

@@ -20,6 +20,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, isAbsolute, join, normalize, relative, resolve } from 'node:path';
 import { callControlAPI } from './api-client.js';
+import { createCommandContext } from './command-context.js';
 import { resolveApiKey, resolveIngestUrl, resolveTenantId } from './config.js';
 import { claudeSkillToCursorRule } from './init/rules.js';
 import { detectAgents } from './init/mcp.js';
@@ -427,16 +428,26 @@ function escapeYamlString(value) {
 function formatProposalRate(value) {
     return `${(Number(value || 0) * 100).toFixed(1)}%`;
 }
-/**
- * `moda skills <subcommand>` dispatcher.
- */
-export async function runSkillsCommand(args) {
-    const sub = args.positional;
-    const positionals = args.positionals ?? (sub ? [sub] : []);
+export async function runSkillsCommand(input) {
+    const context = 'output' in input
+        ? input
+        : createCommandContext({
+            command: input.command,
+            positional: input.positional,
+            positionals: input.positionals,
+            flags: input.flags,
+        }, {
+            outputMode: input.flags.agent === 'true' ? 'agent' : input.flags.json === 'true' ? 'json' : 'human',
+        });
+    const sub = context.positional;
+    const positionals = context.positionals ?? (sub ? [sub] : []);
+    const flags = context.flags;
     if (sub === 'gen') {
-        const result = await generateSkills(args.flags);
-        if (args.flags.json === 'true') {
-            console.log(JSON.stringify(result));
+        const result = await generateSkills(flags);
+        if (context.outputMode !== 'human') {
+            context.output.writeData(result, {
+                status: Number(result.sessions_failed ?? 0) > 0 ? 'error' : 'success',
+            });
         }
         else if (result.accepted) {
             console.log([
@@ -458,8 +469,8 @@ export async function runSkillsCommand(args) {
         return Number(result.sessions_failed ?? 0) > 0 ? 1 : 0;
     }
     if (sub === 'proposals' && positionals[1] === 'list') {
-        const proposals = await fetchSkillProposals(args.flags, { profile: args.flags.profile });
-        if (args.flags.json === 'true') {
+        const proposals = await fetchSkillProposals(flags, { profile: context.profile });
+        if (flags.json === 'true') {
             console.log(JSON.stringify({ proposals }));
         }
         else if (proposals.length === 0) {
@@ -481,12 +492,12 @@ export async function runSkillsCommand(args) {
         return 0;
     }
     if (sub === 'proposal' && positionals[1] === 'apply') {
-        const proposalId = positionals[2] || args.flags['proposal-id'];
+        const proposalId = positionals[2] || flags['proposal-id'];
         if (!proposalId) {
             throw new CliInputError('A proposal id is required', 'Usage: moda skills proposal apply <proposal-id>');
         }
-        const result = await applySkillProposal(proposalId, args.flags, { profile: args.flags.profile });
-        if (args.flags.json === 'true') {
+        const result = await applySkillProposal(proposalId, flags, { profile: context.profile });
+        if (flags.json === 'true') {
             console.log(JSON.stringify(result));
         }
         else {
@@ -508,18 +519,18 @@ export async function runSkillsCommand(args) {
         return 0;
     }
     if (sub === 'sync') {
-        const result = await runSkillSync(args.flags, { profile: args.flags.profile });
-        console.log(JSON.stringify({ synced: result.synced, dryRun: result.dryRun }));
+        const result = await runSkillSync(flags, { profile: context.profile, env: context.env });
+        context.output.writeData({ synced: result.synced, dryRun: result.dryRun });
         return 0;
     }
     if (sub !== 'pull') {
         throw new CliInputError(sub ? `Unknown skills subcommand '${sub}'` : 'A skills subcommand is required', 'Usage: moda skills gen [--source=all|sdk|coding-agent] [--max-sessions=N] [--start-at=ISO] [--end-at=ISO] [--replay] [--replay-set-id=ID] [--reprocess-segments] [--force-reprocess] [--wait] | moda skills proposals list [--status=ready_for_pr] | moda skills proposal apply <proposal-id> | moda skills pull [--status=approved|proposed|all] | moda skills sync [--dry-run]');
     }
-    const status = (args.flags.status ?? 'approved').toLowerCase();
+    const status = (flags.status ?? 'approved').toLowerCase();
     if (!VALID_STATUSES.has(status)) {
         throw new CliInputError(`Invalid --status '${status}'`, `Must be one of: ${[...VALID_STATUSES].join(', ')}`);
     }
-    const summary = await pullSkills({ status });
+    const summary = await pullSkills({ status, silent: context.outputMode !== 'human' });
     const parts = [
         summary.pruned && `${summary.pruned} pruned`,
         summary.wrote && `${summary.wrote} written`,
@@ -527,9 +538,12 @@ export async function runSkillsCommand(args) {
         summary.unchanged && `${summary.unchanged} unchanged`,
         summary.failed && `${summary.failed} failed`,
     ].filter(Boolean);
-    if (summary.total > 0) {
+    if (context.outputMode === 'human' && summary.total > 0) {
         console.log(`  Done — ${parts.join(', ') || 'no changes'}`);
     }
+    if (context.outputMode !== 'human') {
+        context.output.writeData({ status, summary });
+    }
     return summary.failed > 0 ? 1 : 0;
 }
 async function generateSkills(flags) {

package/package.json

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

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