@moda-ai/cli 1.20.1 → 1.22.0

package/dist/init/sdk-protocol.d.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+export declare const SDK_RESULT_SCHEMA_VERSION = "moda.sdk_integration_result.v1";
+export declare const SDK_RESULT_JSON_BEGIN = "MODA_SDK_RESULT_JSON_BEGIN";
+export declare const SDK_RESULT_JSON_END = "MODA_SDK_RESULT_JSON_END";
+export declare const SDK_RESULT_FILE = ".moda/sdk-integration-result.json";
+export declare const SdkAgentResultSchema: z.ZodObject<{
+    schema_version: z.ZodPipeline<z.ZodString, z.ZodLiteral<"moda.sdk_integration_result.v1">>;
+    status: z.ZodEffects<z.ZodEnum<["integrated", "needs_human_input", "repository_checks_failed", "smoke_execution_failed", "nothing_to_integrate", "failed"]>, "failed" | "integrated" | "needs_human_input" | "repository_checks_failed" | "smoke_execution_failed" | "nothing_to_integrate", unknown>;
+    summary: z.ZodEffects<z.ZodString, string, unknown>;
+    skills_consulted: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, unknown>, "many">, string[], unknown>>;
+    skills_used: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, unknown>, "many">, string[], unknown>>;
+    packages_installed: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, unknown>, "many">, string[], unknown>>;
+    files_changed: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, unknown>, "many">, string[], unknown>>;
+    call_sites_instrumented: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodUnion<[z.ZodEffects<z.ZodEffects<z.ZodString, string, unknown>, {
+        file: string;
+    }, unknown>, z.ZodObject<{
+        file: z.ZodEffects<z.ZodString, string, unknown>;
+        detail: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, unknown>;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+        detail?: string | undefined;
+    }, {
+        file?: unknown;
+        detail?: unknown;
+    }>]>, "many">, ({
+        file: string;
+    } | {
+        file: string;
+        detail?: string | undefined;
+    })[], unknown>>;
+    commands_run: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodObject<{
+        command: z.ZodEffects<z.ZodString, string, unknown>;
+        exit_code: z.ZodEffects<z.ZodUnion<[z.ZodNumber, z.ZodNull]>, number | null, unknown>;
+        kind: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, unknown>;
+    }, "strip", z.ZodTypeAny, {
+        command: string;
+        exit_code: number | null;
+        kind?: string | undefined;
+    }, {
+        command?: unknown;
+        kind?: unknown;
+        exit_code?: unknown;
+    }>, "many">, {
+        command: string;
+        exit_code: number | null;
+        kind?: string | undefined;
+    }[], unknown>>;
+    smoke: z.ZodDefault<z.ZodEffects<z.ZodNullable<z.ZodObject<{
+        method: z.ZodEffects<z.ZodString, string, unknown>;
+        command: z.ZodEffects<z.ZodOptional<z.ZodString>, string | undefined, unknown>;
+        verification_id: z.ZodEffects<z.ZodString, string, unknown>;
+    }, "strip", z.ZodTypeAny, {
+        method: string;
+        verification_id: string;
+        command?: string | undefined;
+    }, {
+        command?: unknown;
+        method?: unknown;
+        verification_id?: unknown;
+    }>>, {
+        method: string;
+        verification_id: string;
+        command?: string | undefined;
+    } | null, unknown>>;
+    remaining_actions: z.ZodDefault<z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, unknown>, "many">, string[], unknown>>;
+    failure: z.ZodDefault<z.ZodEffects<z.ZodNullable<z.ZodObject<{
+        class: z.ZodEffects<z.ZodString, string, unknown>;
+        detail: z.ZodEffects<z.ZodString, string, unknown>;
+    }, "strip", z.ZodTypeAny, {
+        detail: string;
+        class: string;
+    }, {
+        detail?: unknown;
+        class?: unknown;
+    }>>, {
+        detail: string;
+        class: string;
+    } | null, unknown>>;
+}, "strip", z.ZodTypeAny, {
+    schema_version: "moda.sdk_integration_result.v1";
+    summary: string;
+    status: "failed" | "integrated" | "needs_human_input" | "repository_checks_failed" | "smoke_execution_failed" | "nothing_to_integrate";
+    skills_consulted: string[];
+    skills_used: string[];
+    packages_installed: string[];
+    files_changed: string[];
+    call_sites_instrumented: ({
+        file: string;
+    } | {
+        file: string;
+        detail?: string | undefined;
+    })[];
+    commands_run: {
+        command: string;
+        exit_code: number | null;
+        kind?: string | undefined;
+    }[];
+    smoke: {
+        method: string;
+        verification_id: string;
+        command?: string | undefined;
+    } | null;
+    remaining_actions: string[];
+    failure: {
+        detail: string;
+        class: string;
+    } | null;
+}, {
+    schema_version: string;
+    summary?: unknown;
+    status?: unknown;
+    skills_consulted?: unknown;
+    skills_used?: unknown;
+    packages_installed?: unknown;
+    files_changed?: unknown;
+    call_sites_instrumented?: unknown;
+    commands_run?: unknown;
+    smoke?: unknown;
+    remaining_actions?: unknown;
+    failure?: unknown;
+}>;
+export type SdkAgentResult = z.infer<typeof SdkAgentResultSchema>;
+export type ExtractSdkAgentResult = {
+    result: SdkAgentResult;
+    source: 'file' | 'markers';
+} | {
+    error: string;
+    detail?: string;
+};
+export declare function extractSdkAgentResult(opts: {
+    cwd: string;
+    stdout: string;
+    stderr: string;
+}): ExtractSdkAgentResult;
+//# sourceMappingURL=sdk-protocol.d.ts.map

package/dist/init/sdk-protocol.js

@@ -0,0 +1,152 @@
+// src/init/sdk-protocol.ts — Versioned result protocol used by the coding
+// agent that performs SDK integration.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+export const SDK_RESULT_SCHEMA_VERSION = 'moda.sdk_integration_result.v1';
+export const SDK_RESULT_JSON_BEGIN = 'MODA_SDK_RESULT_JSON_BEGIN';
+export const SDK_RESULT_JSON_END = 'MODA_SDK_RESULT_JSON_END';
+export const SDK_RESULT_FILE = '.moda/sdk-integration-result.json';
+const nonemptyString = z.preprocess((value) => {
+    if (typeof value === 'string')
+        return value.trim();
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    return value;
+}, z.string().min(1));
+const optionalString = z.preprocess((value) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed || undefined;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    return undefined;
+}, z.string().min(1).optional());
+function tolerantArray(itemSchema) {
+    return z.preprocess((value) => {
+        if (!Array.isArray(value))
+            return [];
+        const accepted = [];
+        for (const item of value) {
+            const parsed = itemSchema.safeParse(item);
+            if (parsed.success)
+                accepted.push(parsed.data);
+        }
+        return accepted;
+    }, z.array(itemSchema)).default([]);
+}
+const callSiteSchema = z.union([
+    nonemptyString.transform((file) => ({ file })),
+    z.object({
+        file: nonemptyString,
+        detail: optionalString,
+    }),
+]);
+const exitCodeSchema = z.preprocess((value) => {
+    if (value === null)
+        return null;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const numeric = Number(value);
+        return Number.isFinite(numeric) ? numeric : value;
+    }
+    return value;
+}, z.union([z.number().finite(), z.null()]));
+const commandSchema = z.object({
+    command: nonemptyString,
+    exit_code: exitCodeSchema,
+    kind: optionalString,
+});
+const smokeSchema = z.object({
+    method: nonemptyString,
+    command: optionalString,
+    verification_id: nonemptyString,
+});
+const failureSchema = z.object({
+    class: nonemptyString,
+    detail: nonemptyString,
+});
+export const SdkAgentResultSchema = z.object({
+    schema_version: z.string().trim().pipe(z.literal(SDK_RESULT_SCHEMA_VERSION)),
+    status: z.preprocess((value) => typeof value === 'string' ? value.trim() : value, z.enum([
+        'integrated',
+        'needs_human_input',
+        'repository_checks_failed',
+        'smoke_execution_failed',
+        'nothing_to_integrate',
+        'failed',
+    ])),
+    summary: nonemptyString,
+    skills_consulted: tolerantArray(nonemptyString),
+    skills_used: tolerantArray(nonemptyString),
+    packages_installed: tolerantArray(nonemptyString),
+    files_changed: tolerantArray(nonemptyString),
+    call_sites_instrumented: tolerantArray(callSiteSchema),
+    commands_run: tolerantArray(commandSchema),
+    smoke: z.preprocess((value) => value ?? null, smokeSchema.nullable()).default(null),
+    remaining_actions: tolerantArray(nonemptyString),
+    failure: z.preprocess((value) => value ?? null, failureSchema.nullable()).default(null),
+});
+export function extractSdkAgentResult(opts) {
+    const diagnostics = [];
+    const resultPath = join(opts.cwd, SDK_RESULT_FILE);
+    if (existsSync(resultPath)) {
+        try {
+            const parsed = parseCandidate(readFileSync(resultPath, 'utf8'));
+            if (parsed.result)
+                return { result: parsed.result, source: 'file' };
+            diagnostics.push(`result file: ${parsed.detail}`);
+        }
+        catch (error) {
+            diagnostics.push(`result file: ${errorMessage(error)}`);
+        }
+    }
+    const output = [opts.stdout, opts.stderr].filter(Boolean).join('\n');
+    const candidates = markerCandidates(output);
+    for (const [index, candidate] of candidates.entries()) {
+        const parsed = parseCandidate(candidate);
+        if (parsed.result)
+            return { result: parsed.result, source: 'markers' };
+        diagnostics.push(`marker block ${index + 1}: ${parsed.detail}`);
+    }
+    if (candidates.length === 0) {
+        diagnostics.push(`no ${SDK_RESULT_JSON_BEGIN}/${SDK_RESULT_JSON_END} marker block found`);
+    }
+    return {
+        error: 'SDK integration result protocol violation.',
+        detail: diagnostics.join('; '),
+    };
+}
+function markerCandidates(output) {
+    const pattern = new RegExp(`${SDK_RESULT_JSON_BEGIN}\\s*([\\s\\S]*?)\\s*${SDK_RESULT_JSON_END}`, 'g');
+    const candidates = [];
+    for (const match of output.matchAll(pattern)) {
+        if (match[1])
+            candidates.push(match[1]);
+    }
+    return candidates;
+}
+function parseCandidate(candidate) {
+    let value;
+    try {
+        value = JSON.parse(candidate.trim());
+    }
+    catch (error) {
+        return { detail: `invalid JSON (${errorMessage(error)})` };
+    }
+    const parsed = SdkAgentResultSchema.safeParse(value);
+    if (parsed.success)
+        return { result: parsed.data };
+    const detail = parsed.error.issues
+        .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
+        .join(', ');
+    return { detail: `validation failed (${detail})` };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=sdk-protocol.js.map

package/dist/init/sdk-verification.d.ts

@@ -0,0 +1,27 @@
+export interface VerificationEvidence {
+    observed: boolean;
+    verification_id: string;
+    total_spans: number;
+    llm_spans: number;
+    tool_spans: number;
+    trace_ids: string[];
+    orphan_count: number;
+    duplicate_count: number;
+    ingest_rows: number;
+    elapsed_ms: number;
+    polls: number;
+    last_error?: string;
+}
+export declare function generateVerificationId(): string;
+export declare function isModaVerificationId(value: string): boolean;
+export declare function verifyExactTrace(opts: {
+    verificationId: string;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    fetchAudit?: (id: string) => Promise<unknown>;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}): Promise<VerificationEvidence>;
+/** Fetch audit data for SDK verification using an explicit provisioned API key. */
+export declare function fetchAuditWithApiKey(id: string, apiKey: string, baseUrl: string): Promise<unknown>;
+//# sourceMappingURL=sdk-verification.d.ts.map

package/dist/init/sdk-verification.js

@@ -0,0 +1,123 @@
+// src/init/sdk-verification.ts — Poll the Data API for an exact, freshly
+// generated conversation id and require evidence of an observed LLM span.
+import { randomBytes } from 'node:crypto';
+const DEFAULT_TIMEOUT_MS = 90_000;
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const MIN_TIMEOUT_MS = 10_000;
+const MAX_TIMEOUT_MS = 600_000;
+export function generateVerificationId() {
+    return `moda-verify-${randomBytes(16).toString('hex')}`;
+}
+export function isModaVerificationId(value) {
+    return /^moda-verify-[0-9a-f]{32}$/.test(value);
+}
+export async function verifyExactTrace(opts) {
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    // Verification MUST poll with the provisioned key (fetchAuditWithApiKey) so an
+    // ambient MODA_API_KEY pointing at another tenant cannot skew the result.
+    // Fail explicitly rather than silently falling back to ambient credentials.
+    const fetchAudit = opts.fetchAudit;
+    const timeoutMs = opts.timeoutMs === undefined || !Number.isFinite(opts.timeoutMs)
+        ? resolveTimeoutFromEnv()
+        : Math.max(0, opts.timeoutMs);
+    const requestedPollInterval = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const pollIntervalMs = Number.isFinite(requestedPollInterval)
+        ? Math.max(1, requestedPollInterval)
+        : DEFAULT_POLL_INTERVAL_MS;
+    const startedAt = now();
+    const deadline = startedAt + Math.max(0, timeoutMs);
+    let polls = 0;
+    let lastError;
+    let counts = {
+        total_spans: 0,
+        llm_spans: 0,
+        tool_spans: 0,
+        trace_ids: [],
+        orphan_count: 0,
+        duplicate_count: 0,
+        ingest_rows: 0,
+    };
+    if (!fetchAudit) {
+        lastError = 'verification requires an explicit audit fetcher bound to the provisioned API key';
+        return buildEvidence(false);
+    }
+    while (true) {
+        polls++;
+        try {
+            const response = await fetchAudit(opts.verificationId);
+            const parsed = readAuditCounts(response);
+            if (parsed) {
+                counts = parsed;
+                if (counts.total_spans >= 1 && counts.llm_spans >= 1) {
+                    return buildEvidence(true);
+                }
+            }
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        const currentTime = now();
+        if (currentTime >= deadline)
+            return buildEvidence(false);
+        await sleep(Math.min(pollIntervalMs, deadline - currentTime));
+    }
+    function buildEvidence(observed) {
+        return {
+            observed,
+            verification_id: opts.verificationId,
+            ...counts,
+            elapsed_ms: Math.max(0, now() - startedAt),
+            polls,
+            ...(lastError ? { last_error: lastError } : {}),
+        };
+    }
+}
+function resolveTimeoutFromEnv() {
+    const raw = process.env.MODA_SDK_VERIFY_TIMEOUT_MS;
+    if (!raw)
+        return DEFAULT_TIMEOUT_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return DEFAULT_TIMEOUT_MS;
+    return Math.min(MAX_TIMEOUT_MS, Math.max(MIN_TIMEOUT_MS, Math.trunc(parsed)));
+}
+function readAuditCounts(value) {
+    if (!isRecord(value) || !isRecord(value.summary))
+        return undefined;
+    const summary = value.summary;
+    if (!isNonNegativeNumber(summary.total_spans) || !isRecord(summary.by_type))
+        return undefined;
+    return {
+        total_spans: summary.total_spans,
+        llm_spans: isNonNegativeNumber(summary.by_type.llm) ? summary.by_type.llm : 0,
+        tool_spans: isNonNegativeNumber(summary.by_type.tool) ? summary.by_type.tool : 0,
+        trace_ids: Array.isArray(summary.trace_ids)
+            ? summary.trace_ids.filter((item) => typeof item === 'string')
+            : [],
+        orphan_count: isNonNegativeNumber(summary.orphan_count) ? summary.orphan_count : 0,
+        duplicate_count: isNonNegativeNumber(summary.duplicate_count) ? summary.duplicate_count : 0,
+        ingest_rows: isNonNegativeNumber(summary.ingest_rows) ? summary.ingest_rows : 0,
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonNegativeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+/** Fetch audit data for SDK verification using an explicit provisioned API key. */
+export async function fetchAuditWithApiKey(id, apiKey, baseUrl) {
+    const url = `${baseUrl}/api/v1/data/audit/${encodeURIComponent(id)}?kind=conversation`;
+    const response = await fetch(url, {
+        method: 'GET',
+        headers: { 'x-api-key': apiKey },
+        signal: AbortSignal.timeout(10_000),
+    });
+    const body = await response.text();
+    if (!response.ok) {
+        throw new Error(`Audit fetch failed (${response.status}): ${body.slice(0, 200)}`);
+    }
+    return JSON.parse(body);
+}
+//# sourceMappingURL=sdk-verification.js.map

package/dist/manifest.js

@@ -32,6 +32,7 @@ export function buildManifest(commands) {
             'MODA_AGENT_MAX_OUTPUT_BYTES',
             'MODA_CLI_TELEMETRY',
             'MODA_CLI_UPDATE_CHECK',
+            'MODA_CLI_TIPS',
         ],
         exit_codes: [
             { code: 0, name: 'ok', meaning: 'Command completed successfully.' },

package/dist/output.d.ts

@@ -2,6 +2,14 @@ import { type AgentAuthRequest, type AgentInputRequest } from './errors.js';
 export type CliOutputMode = 'human' | 'json' | 'agent' | 'agent-stream';
 export declare const AGENT_SCHEMA_VERSION = "moda.agent.v1";
 export declare const AGENT_EVENT_SCHEMA_VERSION = "moda.agent_event.v1";
+/**
+ * One-line feedback nudge stamped into every non-feedback success envelope's
+ * `meta.tip` (agents are the CLI's most common callers, and the envelope is
+ * where they actually look). Deliberately conditional wording so agents flag
+ * genuine observations instead of habitually running the command. The
+ * human-TTY twin is printed on stderr by the dispatcher in cli.ts.
+ */
+export declare const FEEDBACK_TIP = "Help us improve! If a result in this response looks wrong or is missing data, flag it: moda feedback \"<describe what looked wrong>\" [--category=...] [--conversation-id=... | --cluster-id=... | --tool-name=...]. Only submit genuine observations.";
 /**
  * Stable process exit codes that an external agent can branch on:
  *   0  ok        — grounded answer from Moda Cloud intelligence.

package/dist/output.js

@@ -3,6 +3,14 @@ import { CliAccessError, CliAuthError, CliCancellationError, CliInputError, CliI
 import { redactDeep } from './redact.js';
 export const AGENT_SCHEMA_VERSION = 'moda.agent.v1';
 export const AGENT_EVENT_SCHEMA_VERSION = 'moda.agent_event.v1';
+/**
+ * One-line feedback nudge stamped into every non-feedback success envelope's
+ * `meta.tip` (agents are the CLI's most common callers, and the envelope is
+ * where they actually look). Deliberately conditional wording so agents flag
+ * genuine observations instead of habitually running the command. The
+ * human-TTY twin is printed on stderr by the dispatcher in cli.ts.
+ */
+export const FEEDBACK_TIP = 'Help us improve! If a result in this response looks wrong or is missing data, flag it: moda feedback "<describe what looked wrong>" [--category=...] [--conversation-id=... | --cluster-id=... | --tool-name=...]. Only submit genuine observations.';
 /**
  * Stable process exit codes that an external agent can branch on:
  *   0  ok        — grounded answer from Moda Cloud intelligence.
@@ -214,6 +222,9 @@ export function createCliOutput(options) {
             meta: {
                 ...(writeOptions.meta ?? {}),
                 run_id: state.runId,
+                // No tip on the feedback command itself; it would point at the
+                // command that just ran.
+                ...(options.command === 'feedback' ? {} : { tip: FEEDBACK_TIP }),
             },
             summary: writeOptions.summary,
             findings: writeOptions.findings,

package/dist/schemas.d.ts

@@ -188,4 +188,38 @@ export declare const SearchSchema: z.ZodObject<{
     user_id?: string | undefined;
     include_tool_io?: boolean | undefined;
 }>;
+export declare const FEEDBACK_CATEGORIES: readonly ["bad_cluster_label", "mismatched_frustration", "missing_data", "noisy_data", "wrong_tool_failure", "incorrect_loop", "api_quirk", "other"];
+export declare const FEEDBACK_SEVERITIES: readonly ["info", "low", "medium", "high"];
+/**
+ * moda feedback "<note>": flag wrong/missing data or CLI quirks to the Moda
+ * team. The handler builds this input from raw flag strings (NOT flagsToArgs,
+ * whose numeric coercion would turn "--conversation-id=873459" into a number
+ * that z.string() rejects). max(4000) on note mirrors the backend
+ * @MaxLength(4000); the capped id fields become the POST body's `refs`.
+ */
+export declare const FeedbackSchema: z.ZodObject<{
+    note: z.ZodString;
+    category: z.ZodOptional<z.ZodDefault<z.ZodEnum<["bad_cluster_label", "mismatched_frustration", "missing_data", "noisy_data", "wrong_tool_failure", "incorrect_loop", "api_quirk", "other"]>>>;
+    severity: z.ZodOptional<z.ZodDefault<z.ZodEnum<["info", "low", "medium", "high"]>>>;
+    conversation_id: z.ZodOptional<z.ZodString>;
+    cluster_id: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodOptional<z.ZodString>;
+    run_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    note: string;
+    run_id?: string | undefined;
+    severity?: "high" | "medium" | "low" | "info" | undefined;
+    category?: "bad_cluster_label" | "mismatched_frustration" | "missing_data" | "noisy_data" | "wrong_tool_failure" | "incorrect_loop" | "api_quirk" | "other" | undefined;
+    conversation_id?: string | undefined;
+    tool_name?: string | undefined;
+    cluster_id?: string | undefined;
+}, {
+    note: string;
+    run_id?: string | undefined;
+    severity?: "high" | "medium" | "low" | "info" | undefined;
+    category?: "bad_cluster_label" | "mismatched_frustration" | "missing_data" | "noisy_data" | "wrong_tool_failure" | "incorrect_loop" | "api_quirk" | "other" | undefined;
+    conversation_id?: string | undefined;
+    tool_name?: string | undefined;
+    cluster_id?: string | undefined;
+}>;
 //# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.js

@@ -93,4 +93,34 @@ export const SearchSchema = z.object({
     limit: z.number().min(1).max(100).default(20).optional(),
     include_tool_io: z.boolean().default(false).optional(),
 });
+// Enums mirror the backend FeedbackBodyDto (VALID_FEEDBACK_CATEGORIES /
+// VALID_FEEDBACK_SEVERITIES) so a bad value fails locally instead of
+// round-tripping a 400.
+export const FEEDBACK_CATEGORIES = [
+    'bad_cluster_label',
+    'mismatched_frustration',
+    'missing_data',
+    'noisy_data',
+    'wrong_tool_failure',
+    'incorrect_loop',
+    'api_quirk',
+    'other',
+];
+export const FEEDBACK_SEVERITIES = ['info', 'low', 'medium', 'high'];
+/**
+ * moda feedback "<note>": flag wrong/missing data or CLI quirks to the Moda
+ * team. The handler builds this input from raw flag strings (NOT flagsToArgs,
+ * whose numeric coercion would turn "--conversation-id=873459" into a number
+ * that z.string() rejects). max(4000) on note mirrors the backend
+ * @MaxLength(4000); the capped id fields become the POST body's `refs`.
+ */
+export const FeedbackSchema = z.object({
+    note: z.string().min(1).max(4000),
+    category: z.enum(FEEDBACK_CATEGORIES).default('other').optional(),
+    severity: z.enum(FEEDBACK_SEVERITIES).default('low').optional(),
+    conversation_id: z.string().min(1).max(256).optional(),
+    cluster_id: z.string().min(1).max(256).optional(),
+    tool_name: z.string().min(1).max(256).optional(),
+    run_id: z.string().min(1).max(256).optional(),
+});
 //# sourceMappingURL=schemas.js.map

package/package.json

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

package/skills/integration/index.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "moda.skill_index.v1",
-  "bundled_at": "2026-07-12T01:43:29.789Z",
-  "cli_version": "1.20.1",
+  "bundled_at": "2026-07-14T06:44:35.511Z",
+  "cli_version": "1.22.0",
   "skills": [
     {
       "id": "integration-node-anthropic",

package/skills/moda-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: moda-cli
-version: 2.1.0
+version: 2.2.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, 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.
 ---
 
@@ -680,6 +680,33 @@ done
 moda tool-failures | jq '.tools[] | {tool: .tool_name, failures: .failure_count}'
 ```
 
+## Feedback: help us improve
+
+Successful agent envelopes carry a `meta.tip` reminding you of this. When a
+response looks wrong (a cluster label that doesn't match its conversations,
+a frustration whose causes don't match the transcript, an empty result that
+should not be empty, an API quirk), flag it with `moda feedback`. The Moda
+team reads these to fix data quality issues. Only submit genuine
+observations; never run the command with placeholder text.
+
+```bash
+moda feedback "cluster 'billing' is mostly refund conversations" \
+  --category=bad_cluster_label --cluster-id=<node_id>
+moda feedback "search finds nothing for a conversation I can open" \
+  --category=missing_data --conversation-id=<id>
+moda feedback "a cancelled call is counted as a tool failure" \
+  --category=wrong_tool_failure --tool-name=<tool>
+```
+
+- `<note>` is required (max 4000 chars). Say what looked wrong and why.
+- `--category`: `bad_cluster_label | mismatched_frustration | missing_data |
+  noisy_data | wrong_tool_failure | incorrect_loop | api_quirk | other`
+  (default `other`).
+- `--severity`: `info | low | medium | high` (default `low`).
+- Attach ids when you have them: `--conversation-id`, `--cluster-id`,
+  `--tool-name`, `--run-id`; they let the team reproduce what you saw.
+- Never include secrets or full transcripts in the note.
+
 ## Validation — how to know it worked
 
 - Every successful command exits 0 and prints valid JSON to stdout.
@@ -748,6 +775,7 @@ npx: `npx -p @moda-ai/cli moda <command>`.
 | `moda frustrations` | User frustration detections with evidence |
 | `moda tool-failures` | Tool failure overview |
 | `moda tool-failure-detail <tool_name>` | Per-tool failure breakdown + examples |
+| `moda feedback "<note>"` | Flag wrong/missing data or CLI quirks to the Moda team |
 | `moda prompts status` | Read-only local prompt status |
 | `moda prompts diff` | Read-only local prompt diff/status |
 | `moda prompts sync` | Upload changed prompt versions and update lockfile |

package/dist/init/skill-resolver.d.ts

@@ -1,19 +0,0 @@
-import type { SdkGuideContext } from './sdk-guide.js';
-type Language = 'node' | 'python';
-type Framework = 'vercel-ai-sdk' | 'langchain' | 'claude-agent-sdk';
-type Provider = 'openai' | 'anthropic';
-interface ResolutionRow {
-    language: Language;
-    framework?: Framework;
-    provider?: Provider;
-    skillId: string;
-}
-/** The §2.3 resolution table, encoded as data. Order matters. */
-export declare const RESOLUTION_TABLE: readonly ResolutionRow[];
-/**
- * Resolve the detected context to a bundled skill id, or null when no
- * language was detected (callers fall back to the slim generic guide).
- */
-export declare function resolveIntegrationSkillId(context: SdkGuideContext): string | null;
-export {};
-//# sourceMappingURL=skill-resolver.d.ts.map