@moda-ai/cli 1.10.1 → 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';
@@ -27,6 +28,7 @@ import { CliInputError } from './errors.js';
 const SKILLS_REQUEST_TIMEOUT_MS = 15_000;
 const VALID_STATUSES = new Set(['approved', 'proposed', 'all']);
 const SKILLS_MANIFEST_PATH = join('.moda', 'skills.yml');
+const SKILL_PROPOSALS_MANIFEST_PATH = join('.moda', 'skill-proposals.yml');
 /**
  * Fetch a tenant's generated skills from the ingest worker. Uses the persisted
  * API key + ingest URL (`~/.moda/config.json`), mirroring snapshot auth.
@@ -342,15 +344,110 @@ function getGitCommit(cwd) {
         return undefined;
     }
 }
-/**
- * `moda skills <subcommand>` dispatcher.
- */
-export async function runSkillsCommand(args) {
-    const sub = args.positional;
+async function fetchSkillProposals(flags, profileOptions = {}) {
+    const params = new URLSearchParams();
+    if (flags['generation-run-id'])
+        params.set('generationRunId', flags['generation-run-id']);
+    const status = flags.status ?? 'ready_for_pr';
+    if (status !== 'all')
+        params.set('status', status);
+    if (flags['tenant-id'])
+        params.set('tenantId', flags['tenant-id']);
+    const suffix = params.toString() ? `?${params.toString()}` : '';
+    const response = (await callControlAPI(`/skills/proposals${suffix}`, { method: 'GET' }, profileOptions));
+    return Array.isArray(response.proposals) ? response.proposals : [];
+}
+async function applySkillProposal(proposalId, flags, profileOptions = {}, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const params = new URLSearchParams();
+    if (flags['tenant-id'])
+        params.set('tenantId', flags['tenant-id']);
+    const suffix = params.toString() ? `?${params.toString()}` : '';
+    const proposal = (await callControlAPI(`/skills/proposals/${encodeURIComponent(proposalId)}${suffix}`, { method: 'GET' }, profileOptions));
+    if (!proposal.skillMd?.trim()) {
+        throw new CliInputError(`Proposal ${proposalId} does not include SKILL.md content`);
+    }
+    const safeId = safeSkillId(proposal.skillId);
+    const relativePath = `.claude/skills/${safeId}/SKILL.md`;
+    const writeStatus = writeIfChanged(join(cwd, relativePath), proposal.skillMd);
+    if (writeStatus === 'failed') {
+        throw new Error(`Failed to write ${relativePath}`);
+    }
+    writeSkillProposalManifest(cwd, proposal, relativePath);
+    let acknowledged = true;
+    let ackError;
+    try {
+        await callControlAPI(`/skills/proposals/${encodeURIComponent(proposalId)}/mark-applied${suffix}`, {
+            method: 'POST',
+            body: JSON.stringify({ appliedBy: 'moda-cli' }),
+        }, profileOptions);
+    }
+    catch (err) {
+        acknowledged = false;
+        ackError = err instanceof Error ? err.message : String(err);
+    }
+    return {
+        proposalId,
+        skillId: proposal.skillId,
+        path: relativePath,
+        status: writeStatus,
+        acknowledged,
+        ackError,
+    };
+}
+function safeSkillId(skillId) {
+    const safeId = basename(skillId || '');
+    if (!safeId || !/^[A-Za-z0-9_-]+$/.test(safeId)) {
+        throw new CliInputError(`Invalid skill_id in proposal: ${JSON.stringify(skillId).slice(0, 80)}`);
+    }
+    return safeId;
+}
+function writeSkillProposalManifest(cwd, proposal, relativePath) {
+    const manifestPath = join(cwd, SKILL_PROPOSALS_MANIFEST_PATH);
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    const existing = existsSync(manifestPath) ? readFileSync(manifestPath, 'utf8') : 'applied_proposals:\n';
+    const entry = [
+        `  - proposal_id: "${escapeYamlString(proposal.proposalId)}"`,
+        `    skill_id: "${escapeYamlString(proposal.skillId)}"`,
+        `    skill_family_id: "${escapeYamlString(proposal.skillFamilyId)}"`,
+        `    skill_version: ${Number(proposal.skillVersion || 0)}`,
+        `    generation_run_id: "${escapeYamlString(proposal.generationRunId)}"`,
+        `    clustering_run_id: "${escapeYamlString(proposal.clusteringRunId)}"`,
+        `    topic_id: "${escapeYamlString(proposal.topicId)}"`,
+        `    replay_set_id: "${escapeYamlString(proposal.replaySetId)}"`,
+        `    delta_pass_rate: ${Number(proposal.deltaPassRate || 0)}`,
+        `    path: "${escapeYamlString(relativePath)}"`,
+        `    applied_at: "${new Date().toISOString()}"`,
+    ].join('\n');
+    const prefix = existing.endsWith('\n') ? existing : `${existing}\n`;
+    writeFileSync(manifestPath, `${prefix}${entry}\n`);
+}
+function escapeYamlString(value) {
+    return String(value ?? '').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function formatProposalRate(value) {
+    return `${(Number(value || 0) * 100).toFixed(1)}%`;
+}
+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([
@@ -371,19 +468,69 @@ export async function runSkillsCommand(args) {
         }
         return Number(result.sessions_failed ?? 0) > 0 ? 1 : 0;
     }
+    if (sub === 'proposals' && positionals[1] === 'list') {
+        const proposals = await fetchSkillProposals(flags, { profile: context.profile });
+        if (flags.json === 'true') {
+            console.log(JSON.stringify({ proposals }));
+        }
+        else if (proposals.length === 0) {
+            console.log('No skill proposals found.');
+        }
+        else {
+            for (const proposal of proposals) {
+                console.log([
+                    proposal.proposalId,
+                    proposal.proposalStatus,
+                    `${proposal.skillId}@v${proposal.skillVersion}`,
+                    `delta=${formatProposalRate(proposal.deltaPassRate)}`,
+                    `baseline=${formatProposalRate(proposal.baselinePassRate)}`,
+                    `candidate=${formatProposalRate(proposal.candidatePassRate)}`,
+                    proposal.name,
+                ].filter(Boolean).join('\t'));
+            }
+        }
+        return 0;
+    }
+    if (sub === 'proposal' && positionals[1] === 'apply') {
+        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, flags, { profile: context.profile });
+        if (flags.json === 'true') {
+            console.log(JSON.stringify(result));
+        }
+        else {
+            console.log([
+                `${result.status} ${result.path}`,
+                result.acknowledged ? 'acknowledged: true' : 'acknowledged: false',
+            ].join('\n'));
+        }
+        if (!result.acknowledged) {
+            // The local SKILL.md was written, but the server still lists this
+            // proposal as ready_for_pr. Warn (to stderr so JSON stdout stays clean)
+            // and exit non-zero so the failed acknowledgement isn't silently treated
+            // as success — re-running `apply` re-attempts the acknowledgement.
+            console.error(`Warning: wrote ${result.path} but failed to acknowledge proposal ${proposalId} on the server` +
+                (result.ackError ? ` (${result.ackError})` : '') +
+                '. The proposal is still listed as ready — re-run `moda skills proposal apply` to acknowledge it.');
+            return 1;
+        }
+        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] [--reprocess-segments] [--force-reprocess] [--wait] | moda skills pull [--status=approved|proposed|all] | moda skills sync [--dry-run]');
+        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`,
@@ -391,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) {
@@ -418,6 +568,7 @@ async function generateSkills(flags) {
         start_at: flags['start-at'] || undefined,
         end_at: flags['end-at'] || undefined,
         clustering_run_id: flags['clustering-run-id'] || undefined,
+        replay_set_id: flags['replay-set-id'] || flags['eval-set-id'] || undefined,
         run_clustering: flags['no-clustering'] !== 'true',
         source: normalizeSkillSource(flags.source),
         clustering_timeout_seconds: parsePositiveInt(flags['clustering-timeout-seconds'], 0),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moda-ai/cli",
-  "version": "1.10.1",
+  "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