@moda-ai/cli 1.1.1 → 1.3.0

package/README.md

@@ -66,6 +66,14 @@ moda runs --class-id=cron:helpscout-triage-hourly # Scoped to one workflow class
 moda run <run_id>                                # One execution + its side-effect receipts
 moda loops                                       # Currently-active loop detections
 moda loop <detection_id>                         # One loop detail (signature + blast radius)
+
+# Prompt management
+moda prompts init                                # Create .moda/prompts.yml
+moda prompts status                              # Read-only local prompt status
+moda prompts diff                                # Read-only local prompt diff/status
+moda prompts sync                                # Upload changed prompt versions
+moda prompts sync --watch                        # Sync when local prompt hashes change
+moda prompts promote support.triage --label=prod --version=pver_abc123
 ```
 
 All commands output JSON. Pipe to `jq` for filtering:
@@ -78,6 +86,34 @@ moda loops | jq '.loops | sort_by(-.cycle_visits) | .[0:5] | .[].loop_signature_
 moda workflows | jq '.workflows | sort_by(.health) | .[] | select(.health < 0.8)'
 ```
 
+## Prompt Management
+
+Prompt management is code-first. Keep prompts in `prompts/**/*.prompt.md` or
+`prompts/**/*.prompt.json`, sync them with the CLI, and render them through the
+SDK so LLM spans include prompt metadata.
+
+```bash
+moda prompts init
+moda prompts status
+moda prompts sync
+```
+
+`status` and `diff` are read-only. `sync` uploads changed versions and writes
+`.moda/prompts.lock.json`. `promote` moves a remote `dev`, `staging`, or `prod`
+label.
+
+```typescript
+const rendered = Moda.prompt("support.triage").render({
+  ticket: { text: userMessage },
+});
+```
+
+```python
+rendered = moda.prompt("support.triage").render({
+    "ticket": {"text": user_message},
+})
+```
+
 ## Anchors and message windows
 
 Rows returned by `moda frustrations` and `moda tool-failure-detail` carry

package/dist/agent.d.ts

@@ -0,0 +1,5 @@
+import type { CommandContext } from './command-context.js';
+export declare function runAgentCommand(context: CommandContext): Promise<{
+    exitCode: number;
+}>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.js

@@ -0,0 +1,477 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { resolveApiKey, resolveIngestUrl, resolveModaBaseUrl, resolveTenantId } from './config.js';
+import { buildDoctorReport } from './doctor.js';
+import { CliInputError } from './errors.js';
+import { HARNESS_REPORT_APPROVAL_PATH, HARNESS_REPORT_PATH, hashHarnessReport, readHarnessReport, validateHarnessReport, } from './harness-report.js';
+import { readHarnessSyncState, graphForSync, summarizeHarness, } from './harness.js';
+import { hashStableJson } from './harness-report.js';
+const MODA_DIR = '.moda';
+const HARNESS_PATH = join(MODA_DIR, 'harness.json');
+const HARNESS_REPORT_MARKDOWN_PATH = join(MODA_DIR, 'HARNESS_REPORT.md');
+const HARNESS_SUMMARY_PATH = join(MODA_DIR, 'HARNESS.md');
+const MAX_AGENT_EVIDENCE_BYTES = 24_000;
+export async function runAgentCommand(context) {
+    const subcommand = context.positionals[0] ?? 'context';
+    switch (subcommand) {
+        case 'context': {
+            const loaded = await buildAgentContext(context);
+            context.output.writeData(loaded.payload, agentWriteOptions(loaded));
+            return { exitCode: 0 };
+        }
+        case 'investigate': {
+            const loaded = await buildAgentContext(context);
+            const question = context.positionals.slice(1).join(' ').trim() || context.flags.question;
+            context.output.writeData({
+                schemaVersion: 'agent_investigation.v0.1',
+                generatedAt: loaded.payload.generatedAt,
+                mode: 'local',
+                question: question || null,
+                status: loaded.payload.doctor.status,
+                findings: loaded.payload.doctor.topFindings,
+                recommendedActions: loaded.payload.recommendedActions,
+                evidenceRefs: loaded.payload.evidenceRefs,
+                limitations: [
+                    ...loaded.payload.limitations,
+                    'Production investigation is not yet implemented in P08; use P09/cloud commands for production-rooted analysis once shipped.',
+                ],
+            }, agentWriteOptions(loaded, {
+                summary: summarizeAgentContext(loaded.payload, 'investigation'),
+            }));
+            return { exitCode: 0 };
+        }
+        case 'next-action':
+        case 'next-actions': {
+            const loaded = await buildAgentContext(context);
+            context.output.writeData({
+                schemaVersion: 'agent_next_actions.v0.1',
+                generatedAt: loaded.payload.generatedAt,
+                status: loaded.payload.doctor.status,
+                recommendedActions: loaded.payload.recommendedActions,
+                nextCommands: loaded.payload.nextCommands,
+            }, agentWriteOptions(loaded, {
+                summary: `${loaded.payload.recommendedActions.length} recommended action(s) are ready for an agent to evaluate.`,
+            }));
+            return { exitCode: 0 };
+        }
+        case 'evidence': {
+            const ref = context.positionals[1] ?? context.flags.id ?? context.flags.ref ?? context.flags.finding;
+            if (!ref) {
+                throw new CliInputError('<ref> is required', 'Usage: moda agent evidence <ref>');
+            }
+            const loaded = await buildAgentContext(context);
+            const evidence = expandEvidenceRef(ref, loaded, context.cwd);
+            context.output.writeData(evidence, {
+                summary: {
+                    text: `Expanded evidence reference ${ref}.`,
+                    confidence: 'high',
+                },
+                evidenceRefs: [evidence.ref],
+                artifacts: evidence.artifact ? [evidence.artifact] : [],
+            });
+            return { exitCode: 0 };
+        }
+        case 'ask': {
+            const loaded = await buildAgentContext(context);
+            const question = context.positionals.slice(1).join(' ').trim() || context.flags.question;
+            context.output.writeData({
+                schemaVersion: 'agent_ask.v0.1',
+                generatedAt: loaded.payload.generatedAt,
+                question: question || null,
+                answer: 'Moda CLI can provide local harness context today. Cloud intelligence for free-form production questions belongs to the future Moda Ask layer.',
+                recommendedActions: loaded.payload.recommendedActions,
+                nextCommands: loaded.payload.nextCommands,
+                evidenceRefs: loaded.payload.evidenceRefs,
+            }, agentWriteOptions(loaded, {
+                summary: 'Returned local Moda context and next commands for the requested agent question.',
+            }));
+            return { exitCode: 0 };
+        }
+        default:
+            throw new CliInputError(`Unknown agent subcommand '${subcommand}'`, 'Usage: moda agent context|investigate|next-action|evidence');
+    }
+}
+async function buildAgentContext(context) {
+    const doctor = await buildDoctorReport(context, {
+        offline: context.flags.online !== 'true',
+    });
+    const graph = readHarnessGraphIfPresent(context.cwd);
+    const reportState = readHarnessReportState(context.cwd);
+    const syncState = readHarnessSyncState(context.cwd);
+    const topFindings = doctor.checks
+        .filter((check) => check.status === 'fail' || check.status === 'warning')
+        .slice(0, 12)
+        .map(checkToFinding);
+    const evidenceRefs = [
+        ...doctor.checks.map(checkToEvidenceRef),
+        ...reportEvidenceRefs(reportState.report).slice(0, 60),
+    ];
+    const artifacts = existingArtifacts(context.cwd);
+    const recommendedActions = recommendedActionsForDoctor(doctor);
+    const nextCommands = nextCommandsForActions(recommendedActions, doctor.nextCommands);
+    const payload = {
+        schemaVersion: 'agent_context.v0.1',
+        generatedAt: new Date().toISOString(),
+        mode: 'local',
+        workspace: {
+            cwd: context.cwd,
+            profile: context.profile,
+            tenantId: resolveTenantId({ profile: context.profile, env: context.env }) ?? null,
+            apiKey: resolveApiKey({ profile: context.profile, env: context.env }) ? 'configured' : 'missing',
+            baseUrl: resolveModaBaseUrl({ profile: context.profile, env: context.env }),
+            ingestUrl: resolveIngestUrl({ profile: context.profile, env: context.env }),
+        },
+        doctor: {
+            status: doctor.summary.status,
+            summary: doctor.summary,
+            topFindings,
+        },
+        harness: {
+            manifest: {
+                path: HARNESS_PATH,
+                exists: graph !== undefined,
+                summary: graph ? summarizeHarness(graph) : null,
+            },
+            report: reportState.state,
+            sync: syncState
+                ? {
+                    path: join(MODA_DIR, 'sync-state.json'),
+                    exists: true,
+                    source: syncState.source,
+                    updatedAt: syncState.updatedAt,
+                    stale: graph ? syncState.localGraphHash !== hashStableJson(graphForSync(graph)) : undefined,
+                    remoteHarnessId: syncState.remote.harnessId,
+                    remoteVersionId: syncState.remote.versionId,
+                }
+                : {
+                    path: join(MODA_DIR, 'sync-state.json'),
+                    exists: false,
+                },
+        },
+        recommendedActions,
+        evidenceRefs,
+        artifacts,
+        nextCommands,
+        limitations: [
+            'This context is local and bounded. It does not upload source content or prove production behavior.',
+            'Use evidence refs to expand claims instead of asking agents to scrape human output.',
+        ],
+    };
+    return {
+        payload,
+        doctor,
+        graph,
+        report: reportState.report,
+        reportValidation: reportState.validation,
+        reportApproval: reportState.approval,
+        syncState,
+    };
+}
+function agentWriteOptions(loaded, overrides = {}) {
+    return {
+        summary: overrides.summary ?? summarizeAgentContext(loaded.payload, 'context'),
+        findings: loaded.payload.doctor.topFindings,
+        evidenceRefs: loaded.payload.evidenceRefs,
+        recommendedActions: loaded.payload.recommendedActions,
+        nextCommands: loaded.payload.nextCommands,
+        artifacts: loaded.payload.artifacts,
+        warnings: [
+            ...(loaded.payload.harness.report.warnings ?? []),
+            ...loaded.payload.limitations,
+        ].slice(0, 40),
+    };
+}
+function summarizeAgentContext(payload, noun) {
+    const fail = payload.doctor.summary.fail;
+    const warning = payload.doctor.summary.warning;
+    const agents = payload.harness.manifest.summary?.runtimeAgentCount ?? 0;
+    if (fail > 0) {
+        return `Local Moda ${noun} found ${fail} failing check(s), ${warning} warning(s), and ${agents} runtime agent(s).`;
+    }
+    if (warning > 0) {
+        return `Local Moda ${noun} is usable with ${warning} warning(s) and ${agents} runtime agent(s).`;
+    }
+    return `Local Moda ${noun} is healthy with ${agents} runtime agent(s).`;
+}
+function readHarnessGraphIfPresent(cwd) {
+    const path = join(cwd, HARNESS_PATH);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readHarnessReportState(cwd) {
+    const path = join(cwd, HARNESS_REPORT_PATH);
+    if (!existsSync(path)) {
+        return {
+            state: {
+                path: HARNESS_REPORT_PATH,
+                exists: false,
+                status: 'missing',
+            },
+        };
+    }
+    try {
+        const report = readHarnessReport(path);
+        const validation = validateHarnessReport(report, cwd);
+        const approval = readApproval(cwd);
+        const reportHash = hashHarnessReport(report);
+        return {
+            state: {
+                path: HARNESS_REPORT_PATH,
+                exists: true,
+                status: validation.status === 'pass' ? 'valid' : 'invalid',
+                reportId: report.reportId,
+                reportHash,
+                validationStatus: validation.status,
+                approved: approval?.approved === true && approval.reportHash === reportHash,
+                claimCount: report.claims.length,
+                citationCount: report.citations.length,
+                warnings: validation.warnings,
+                errors: validation.errors,
+            },
+            report,
+            validation,
+            approval,
+        };
+    }
+    catch (error) {
+        return {
+            state: {
+                path: HARNESS_REPORT_PATH,
+                exists: true,
+                status: 'invalid',
+                errors: [error instanceof Error ? error.message : String(error)],
+            },
+        };
+    }
+}
+function readApproval(cwd) {
+    const path = join(cwd, HARNESS_REPORT_APPROVAL_PATH);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function checkToFinding(check) {
+    return {
+        id: check.id,
+        title: check.title,
+        status: check.status,
+        severity: check.severity,
+        description: check.remediation ?? `Doctor check ${check.id} is ${check.status}.`,
+        evidence_ref_ids: [`doctor:${check.id}`],
+    };
+}
+function checkToEvidenceRef(check) {
+    return {
+        id: `doctor:${check.id}`,
+        kind: 'doctor_check',
+        label: check.title,
+        status: check.status,
+    };
+}
+function reportEvidenceRefs(report) {
+    if (!report)
+        return [];
+    return [
+        ...report.claims.map((claim) => ({
+            id: `harness-report:claim:${claim.id}`,
+            kind: 'harness_claim',
+            label: claim.title,
+            status: claim.inference,
+        })),
+        ...report.citations.map((citation) => ({
+            id: `harness-report:citation:${citation.id}`,
+            kind: citation.type,
+            label: citation.reason,
+            path: citation.path,
+            line: citation.line,
+        })),
+    ];
+}
+function recommendedActionsForDoctor(report) {
+    return report.fixPlan.slice(0, 12).map((item, index) => ({
+        id: `action_${index + 1}_${item.checkId}`,
+        title: item.action,
+        command: item.command,
+        rationale: `Doctor check ${item.checkId} is not passing.`,
+        mutability: item.command ? inferMutability(item.command) : 'unknown',
+        requires_approval: item.command ? commandRequiresApproval(item.command) : true,
+    }));
+}
+function nextCommandsForActions(actions, doctorNextCommands) {
+    const seen = new Set();
+    const commands = [
+        ...actions.map((action) => action.command).filter((command) => Boolean(command)),
+        ...doctorNextCommands,
+    ].filter((command) => {
+        if (seen.has(command))
+            return false;
+        seen.add(command);
+        return true;
+    });
+    return commands.slice(0, 12).map((command) => ({
+        command,
+        purpose: purposeForCommand(command),
+        mutability: inferMutability(command),
+        requires_approval: commandRequiresApproval(command),
+    }));
+}
+function existingArtifacts(cwd) {
+    return [
+        [HARNESS_PATH, 'harness_manifest', 'Local harness graph manifest.'],
+        [HARNESS_REPORT_PATH, 'harness_report', 'Cited harness analyst report.'],
+        [HARNESS_REPORT_MARKDOWN_PATH, 'harness_report_markdown', 'Human-readable harness analyst report.'],
+        [HARNESS_SUMMARY_PATH, 'harness_summary', 'Human-readable harness graph summary.'],
+        [join(MODA_DIR, 'sync-state.json'), 'sync_state', 'Last local harness sync state.'],
+        [join(MODA_DIR, 'prompts.yml'), 'prompt_manifest', 'Local prompt discovery manifest.'],
+    ].flatMap(([path, kind, description]) => existsSync(join(cwd, path))
+        ? [{ path, kind, description }]
+        : []);
+}
+function expandEvidenceRef(ref, loaded, cwd) {
+    if (ref.startsWith('doctor:')) {
+        const checkId = ref.slice('doctor:'.length);
+        const check = loaded.doctor.checks.find((candidate) => candidate.id === checkId);
+        if (!check)
+            throw missingEvidence(ref);
+        return {
+            schemaVersion: 'agent_evidence.v0.1',
+            ref: checkToEvidenceRef(check),
+            value: check,
+        };
+    }
+    if (ref.startsWith('harness-report:claim:')) {
+        const claimId = ref.slice('harness-report:claim:'.length);
+        const claim = loaded.report?.claims.find((candidate) => candidate.id === claimId);
+        if (!claim)
+            throw missingEvidence(ref);
+        return {
+            schemaVersion: 'agent_evidence.v0.1',
+            ref: claimToEvidenceRef(claim),
+            value: claim,
+            artifact: { kind: 'harness_report', path: HARNESS_REPORT_PATH },
+        };
+    }
+    if (ref.startsWith('harness-report:citation:')) {
+        const citationId = ref.slice('harness-report:citation:'.length);
+        const citation = loaded.report?.citations.find((candidate) => candidate.id === citationId);
+        if (!citation)
+            throw missingEvidence(ref);
+        return {
+            schemaVersion: 'agent_evidence.v0.1',
+            ref: citationToEvidenceRef(citation),
+            value: {
+                citation,
+                currentExcerpt: citation.path ? readCitationExcerpt(cwd, citation) : undefined,
+            },
+            artifact: citation.path ? { kind: 'citation_source', path: citation.path } : undefined,
+        };
+    }
+    if (ref.startsWith('artifact:')) {
+        const path = ref.slice('artifact:'.length);
+        const artifact = loaded.payload.artifacts.find((candidate) => candidate.path === path);
+        if (!artifact)
+            throw missingEvidence(ref);
+        return {
+            schemaVersion: 'agent_evidence.v0.1',
+            ref: {
+                id: ref,
+                kind: artifact.kind,
+                label: artifact.description ?? artifact.path,
+                path: artifact.path,
+            },
+            value: readBoundedModaArtifact(cwd, artifact.path),
+            artifact,
+        };
+    }
+    throw missingEvidence(ref);
+}
+function claimToEvidenceRef(claim) {
+    return {
+        id: `harness-report:claim:${claim.id}`,
+        kind: 'harness_claim',
+        label: claim.title,
+        status: claim.inference,
+    };
+}
+function citationToEvidenceRef(citation) {
+    return {
+        id: `harness-report:citation:${citation.id}`,
+        kind: citation.type,
+        label: citation.reason,
+        path: citation.path,
+        line: citation.line,
+    };
+}
+function readCitationExcerpt(cwd, citation) {
+    if (!citation.path || citation.type !== 'file' && citation.type !== 'generated_doc')
+        return citation.excerpt;
+    const absolute = safeResolve(cwd, citation.path);
+    if (!absolute || !existsSync(absolute))
+        return citation.excerpt;
+    const text = readFileSync(absolute, 'utf8');
+    if (citation.line && citation.line > 0) {
+        return text.split(/\r?\n/)[citation.line - 1]?.slice(0, 1_000) ?? citation.excerpt;
+    }
+    return text.slice(0, 1_000);
+}
+function readBoundedModaArtifact(cwd, artifactPath) {
+    if (!artifactPath.startsWith('.moda/')) {
+        throw new CliInputError(`Artifact '${artifactPath}' is outside .moda and cannot be expanded directly.`, 'Use a citation evidence ref for source-file evidence.');
+    }
+    const absolute = safeResolve(cwd, artifactPath);
+    if (!absolute || !existsSync(absolute))
+        throw missingEvidence(`artifact:${artifactPath}`);
+    const size = statSync(absolute).size;
+    const text = readFileSync(absolute, 'utf8');
+    return {
+        path: artifactPath,
+        bytes: size,
+        truncated: size > MAX_AGENT_EVIDENCE_BYTES,
+        text: text.slice(0, MAX_AGENT_EVIDENCE_BYTES),
+    };
+}
+function safeResolve(cwd, path) {
+    const absolute = resolve(cwd, path);
+    const rel = relative(cwd, absolute);
+    if (rel.startsWith('..') || rel === '..' || rel.startsWith('/'))
+        return undefined;
+    return absolute;
+}
+function missingEvidence(ref) {
+    return new CliInputError(`Evidence reference '${ref}' was not found.`, 'Run `moda agent context` to list available evidence_refs.');
+}
+function inferMutability(command) {
+    if (/\bsync\b/.test(command))
+        return 'sync';
+    if (/\b(init|install|approve|pull|gen|promote|remove)\b/.test(command))
+        return 'write';
+    return 'read';
+}
+function commandRequiresApproval(command) {
+    return inferMutability(command) !== 'read' && !command.includes('--dry-run');
+}
+function purposeForCommand(command) {
+    if (command.includes('harness approve'))
+        return 'Approve the current harness report after human review.';
+    if (command.includes('harness sync'))
+        return 'Sync approved harness state to Moda Cloud.';
+    if (command.includes('harness analyze'))
+        return 'Produce or refresh a cited harness report.';
+    if (command.includes('doctor'))
+        return 'Re-run local diagnostics.';
+    if (command.includes('init'))
+        return 'Complete local Moda onboarding.';
+    return 'Inspect or repair local Moda state.';
+}
+//# sourceMappingURL=agent.js.map

package/dist/analyst-tui.d.ts

@@ -0,0 +1,81 @@
+export type AnalystTuiValidationStatus = 'pending' | 'running' | 'pass' | 'fail';
+export interface AnalystTuiEvent {
+    kind: 'agent_text' | 'rate_limit' | 'tool' | 'command' | 'system';
+    message: string;
+    toolName?: string;
+}
+export interface AnalystTuiSummary {
+    runtimeAgentCount?: number;
+    agentFamilyCount?: number;
+    artifactCount?: number;
+    modelProviderCount?: number;
+    unknownCount?: number;
+    claimCount?: number;
+    citationCount?: number;
+    relationshipCount?: number;
+}
+export interface AnalystTuiTimelineItem {
+    time: string;
+    label: string;
+    message: string;
+}
+export interface AnalystTuiState {
+    adapterName: string;
+    command: string;
+    root: string;
+    reportPath: string;
+    startedAt: number;
+    phase: string;
+    sawOutput: boolean;
+    lastOutputAt: number;
+    eventCount: number;
+    rateLimitCount: number;
+    validation: AnalystTuiValidationStatus;
+    artifacts: string[];
+    summary: AnalystTuiSummary;
+    timeline: AnalystTuiTimelineItem[];
+    toolCounts: Map<string, number>;
+    completed: boolean;
+}
+export interface AnalystTuiOptions {
+    adapterName: string;
+    command: string;
+    root: string;
+    reportPath: string;
+    startedAt?: number;
+    color?: boolean;
+    columns?: number;
+    rows?: number;
+}
+export interface AnalystTuiFrameOptions {
+    color?: boolean;
+    columns?: number;
+    rows?: number;
+    now?: number;
+    spinnerFrame?: string;
+}
+export declare class AnalystTui {
+    private state;
+    private active;
+    private closed;
+    private lastRenderAt;
+    private spinnerIndex;
+    constructor(options: AnalystTuiOptions);
+    start(): void;
+    recordEvent(event: AnalystTuiEvent): void;
+    heartbeat(options: {
+        elapsedSeconds: number;
+        quietForSeconds: number;
+        sawOutput: boolean;
+    }): void;
+    setValidation(status: AnalystTuiValidationStatus): void;
+    setSummary(summary: AnalystTuiSummary): void;
+    setArtifacts(artifacts: string[]): void;
+    complete(status: Extract<AnalystTuiValidationStatus, 'pass' | 'fail'>): void;
+    stop(): void;
+    private pushTimeline;
+    private render;
+}
+export declare function renderAnalystTuiFrame(state: AnalystTuiState, options?: AnalystTuiFrameOptions): string;
+export declare function shouldUseAnalystTui(flags: Record<string, string>, outputMode: string): boolean;
+//# sourceMappingURL=analyst-tui.d.ts.map