suzi-cli 0.1.28 → 0.1.30

package/dist/commands/run.js

@@ -3,59 +3,76 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDynamicArgs = parseDynamicArgs;
+exports.validateParamsAgainstSchema = validateParamsAgainstSchema;
+exports.maybeHandleRunActionHelp = maybeHandleRunActionHelp;
+exports.executeRunCommand = executeRunCommand;
 exports.registerRunCommand = registerRunCommand;
+const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const api_1 = require("../lib/api");
+const api_errors_1 = require("../lib/api-errors");
+const actions_cache_1 = require("../lib/actions-cache");
 const ui_1 = require("../utils/ui");
 const tty_1 = require("../utils/tty");
-const actions_cache_1 = require("../lib/actions-cache");
-// Options that belong to the `run` command itself, not to the action params
-const KNOWN_OPTIONS = new Set(['json', 'output', 'dry-run']);
-const KNOWN_WITH_VALUE = new Set(['json', 'output']);
+const KNOWN_OPTIONS = new Set(['params', 'json', 'output', 'dry-run', 'no-input', 'help']);
+const KNOWN_WITH_VALUE = new Set(['params', 'output']);
+const TRUTHY = new Set(['true', 'yes', 'on']);
+const FALSY = new Set(['false', 'no', 'off']);
 /**
- * Convert kebab-case to camelCase.  Passthrough if no hyphens.
- * e.g. "token-id" → "tokenId", "tokenID" → "tokenID"
+ * Convert kebab-case to camelCase. Passthrough if no hyphens.
+ * e.g. "token-id" -> "tokenId", "tokenID" -> "tokenID"
  */
 function kebabToCamel(str) {
     return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
+function camelToKebab(str) {
+    return str.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+}
 /**
  * Resolve a param key against the action's JSON Schema property names.
  * Uses case-insensitive matching so "tokenid" resolves to "tokenID".
  */
 function resolveParamKey(inputKey, schemaProps) {
-    // Exact match
     if (schemaProps.includes(inputKey))
         return inputKey;
-    // Case-insensitive match
     const lower = inputKey.toLowerCase();
-    const match = schemaProps.find((p) => p.toLowerCase() === lower);
+    const match = schemaProps.find((prop) => prop.toLowerCase() === lower);
     if (match)
         return match;
     return inputKey;
 }
-const TRUTHY = new Set(['true', 'yes', 'on']);
-const FALSY = new Set(['false', 'no', 'off']);
+function getSchemaVariants(schema) {
+    if (Array.isArray(schema.anyOf)) {
+        return schema.anyOf.filter((variant) => Boolean(variant) && typeof variant === 'object' && !Array.isArray(variant));
+    }
+    if (Array.isArray(schema.oneOf)) {
+        return schema.oneOf.filter((variant) => Boolean(variant) && typeof variant === 'object' && !Array.isArray(variant));
+    }
+    if (Array.isArray(schema.type)) {
+        return schema.type
+            .filter((type) => typeof type === 'string')
+            .map((type) => ({ type }));
+    }
+    return [schema];
+}
 /**
  * Heuristic type coercion for CLI string values.
  */
 function coerceValue(raw) {
-    // JSON objects/arrays
     if ((raw.startsWith('{') && raw.endsWith('}')) || (raw.startsWith('[') && raw.endsWith(']'))) {
         try {
             return JSON.parse(raw);
         }
         catch {
-            /* keep as string */
+            // Keep as string.
         }
     }
-    // Numbers first — "1" and "0" should be numbers, not booleans
     if (/^-?\d+(\.\d+)?$/.test(raw) && raw.length <= 15) {
         const num = Number(raw);
-        if (!isNaN(num) && isFinite(num))
+        if (!Number.isNaN(num) && Number.isFinite(num))
             return num;
     }
-    // Booleans (only non-numeric truthy/falsy values)
     if (TRUTHY.has(raw.toLowerCase()))
         return true;
     if (FALSY.has(raw.toLowerCase()))
@@ -63,106 +80,371 @@ function coerceValue(raw) {
     return raw;
 }
 /**
- * Schema-aware type coercion: uses the JSON Schema type to decide.
+ * Schema-aware type coercion: uses the JSON Schema type (and anyOf/oneOf) to decide.
  */
 function coerceWithSchema(raw, propSchema) {
-    const type = propSchema.type;
-    if (type === 'number' || type === 'integer') {
-        const num = Number(raw);
-        return isNaN(num) ? raw : num;
-    }
-    if (type === 'boolean')
-        return !FALSY.has(raw.toLowerCase());
-    if (type === 'string')
-        return raw;
-    if (type === 'object' || type === 'array') {
-        try {
-            return JSON.parse(raw);
+    const variants = getSchemaVariants(propSchema);
+    for (const variant of variants) {
+        const type = variant.type;
+        if (type === 'number' || type === 'integer') {
+            const num = Number(raw);
+            if (!Number.isNaN(num)) {
+                return type === 'integer' ? Math.trunc(num) : num;
+            }
+            continue;
         }
-        catch {
+        if (type === 'boolean') {
+            const lower = raw.toLowerCase();
+            if (TRUTHY.has(lower))
+                return true;
+            if (FALSY.has(lower))
+                return false;
+            continue;
+        }
+        if (type === 'object' || type === 'array') {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+        }
+        if (type === 'string') {
             return raw;
         }
     }
     return coerceValue(raw);
 }
+function isNumericToken(token) {
+    return /^-?\d+(\.\d+)?$/.test(token);
+}
+function isOptionToken(token) {
+    if (!token.startsWith('-'))
+        return false;
+    return !isNumericToken(token);
+}
 /**
- * Parse dynamic --key value params from process.argv, skipping known run-command options.
+ * Parse dynamic params from process.argv, skipping run-command options.
+ * Supports both `--amount 1` and `amount 1`.
  */
 function parseDynamicArgs(argv) {
     const runIdx = argv.indexOf('run');
-    if (runIdx === -1)
-        return {};
-    // Skip 'run' and the '<action>' argument
+    if (runIdx === -1) {
+        return { params: {}, positionalPairs: [], strayTokens: [] };
+    }
     const args = argv.slice(runIdx + 2);
     const params = {};
+    const positionalPairs = [];
+    const strayTokens = [];
     let i = 0;
     while (i < args.length) {
         const arg = args[i];
-        if (!arg.startsWith('--')) {
+        if (arg === '--') {
             i++;
             continue;
         }
-        const rawKey = arg.slice(2);
-        // Skip known run-command options
-        if (KNOWN_OPTIONS.has(rawKey)) {
-            i++;
-            if (KNOWN_WITH_VALUE.has(rawKey) && i < args.length && !args[i].startsWith('--')) {
+        if (arg.startsWith('--')) {
+            const rawKey = arg.slice(2);
+            if (KNOWN_OPTIONS.has(rawKey)) {
                 i++;
+                if (KNOWN_WITH_VALUE.has(rawKey) &&
+                    i < args.length &&
+                    !isOptionToken(args[i])) {
+                    i++;
+                }
+                continue;
+            }
+            const camelKey = kebabToCamel(rawKey);
+            const nextArg = args[i + 1];
+            if (nextArg === undefined || isOptionToken(nextArg)) {
+                params[camelKey] = true;
+                i++;
+            }
+            else {
+                params[camelKey] = coerceValue(nextArg);
+                i += 2;
             }
             continue;
         }
-        const camelKey = kebabToCamel(rawKey);
-        const nextArg = args[i + 1];
-        if (nextArg === undefined || nextArg.startsWith('--')) {
-            params[camelKey] = true;
+        if (arg.startsWith('-')) {
+            strayTokens.push(arg);
             i++;
+            continue;
         }
-        else {
-            params[camelKey] = coerceValue(nextArg);
-            i += 2;
+        const nextArg = args[i + 1];
+        if (nextArg === undefined || isOptionToken(nextArg)) {
+            strayTokens.push(arg);
+            i++;
+            continue;
         }
+        const camelKey = kebabToCamel(arg);
+        params[camelKey] = coerceValue(nextArg);
+        positionalPairs.push({ key: camelKey, value: nextArg });
+        i += 2;
     }
-    return params;
+    return { params, positionalPairs, strayTokens };
 }
 /**
  * Apply schema-aware key resolution and type coercion to params.
  */
 function refineParamsWithSchema(params, action) {
     const schemaProps = (0, actions_cache_1.getSchemaProperties)(action);
-    if (schemaProps.length === 0)
-        return params;
+    if (schemaProps.length === 0) {
+        return { params, unknownKeys: [] };
+    }
     const paramSchema = action.parameters;
     const refined = {};
-    for (const [key, val] of Object.entries(params)) {
+    const unknownKeys = [];
+    const allowsAdditionalProperties = paramSchema.additionalProperties === true;
+    for (const [key, value] of Object.entries(params)) {
         const resolvedKey = resolveParamKey(key, schemaProps);
         const propDef = paramSchema.properties?.[resolvedKey];
-        if (propDef && typeof val === 'string') {
-            refined[resolvedKey] = coerceWithSchema(val, propDef);
+        if (!propDef) {
+            if (allowsAdditionalProperties) {
+                refined[key] = value;
+            }
+            else {
+                unknownKeys.push(key);
+            }
+            continue;
+        }
+        if (typeof value === 'string') {
+            refined[resolvedKey] = coerceWithSchema(value, propDef);
         }
         else {
-            refined[resolvedKey] = val;
+            refined[resolvedKey] = value;
         }
     }
-    return refined;
+    return { params: refined, unknownKeys };
 }
-/**
- * Suggest similar action names when the user's input doesn't match.
- */
-function suggestActions(input, actions) {
-    const lower = input.toLowerCase();
-    return actions
-        .filter((a) => {
-        if (a.name.toLowerCase().includes(lower))
-            return true;
-        const actionPart = a.name.split('.')[1]?.toLowerCase();
-        return actionPart ? lower.includes(actionPart) : false;
+function uniqueStrings(values) {
+    return Array.from(new Set(values));
+}
+function schemaTypeLabel(schema) {
+    const enumValues = Array.isArray(schema.enum) ? schema.enum : undefined;
+    if (enumValues && enumValues.length > 0) {
+        return uniqueStrings(enumValues.map((value) => JSON.stringify(value))).join(' | ');
+    }
+    if (Object.prototype.hasOwnProperty.call(schema, 'const')) {
+        return JSON.stringify(schema.const);
+    }
+    const labels = getSchemaVariants(schema)
+        .map((variant) => {
+        const type = variant.type;
+        if (type)
+            return type;
+        if (variant.properties && typeof variant.properties === 'object')
+            return 'object';
+        if (variant.items)
+            return 'array';
+        return 'unknown';
     })
-        .slice(0, 5)
-        .map((a) => a.name);
+        .filter(Boolean);
+    return uniqueStrings(labels).join(' | ') || 'unknown';
+}
+function schemaConstraintLabel(schema) {
+    const variants = getSchemaVariants(schema);
+    const parts = [];
+    const numericVariant = variants.find((variant) => {
+        const type = variant.type;
+        return type === 'number' || type === 'integer';
+    });
+    if (numericVariant) {
+        if (typeof numericVariant.exclusiveMinimum === 'number') {
+            parts.push(`> ${numericVariant.exclusiveMinimum}`);
+        }
+        else if (typeof numericVariant.minimum === 'number') {
+            parts.push(`>= ${numericVariant.minimum}`);
+        }
+        if (typeof numericVariant.exclusiveMaximum === 'number') {
+            parts.push(`< ${numericVariant.exclusiveMaximum}`);
+        }
+        else if (typeof numericVariant.maximum === 'number') {
+            parts.push(`<= ${numericVariant.maximum}`);
+        }
+    }
+    const stringVariant = variants.find((variant) => variant.type === 'string');
+    if (stringVariant) {
+        if (typeof stringVariant.minLength === 'number') {
+            parts.push(`min length ${stringVariant.minLength}`);
+        }
+        if (typeof stringVariant.maxLength === 'number') {
+            parts.push(`max length ${stringVariant.maxLength}`);
+        }
+    }
+    const arrayVariant = variants.find((variant) => variant.type === 'array');
+    if (arrayVariant) {
+        if (typeof arrayVariant.minItems === 'number') {
+            parts.push(`min items ${arrayVariant.minItems}`);
+        }
+        if (typeof arrayVariant.maxItems === 'number') {
+            parts.push(`max items ${arrayVariant.maxItems}`);
+        }
+    }
+    return parts.length > 0 ? parts.join(', ') : undefined;
+}
+function getActionParameterFields(action) {
+    const paramSchema = action.parameters;
+    const required = new Set(paramSchema.required ?? []);
+    return Object.entries(paramSchema.properties ?? {}).map(([name, schema]) => ({
+        name,
+        required: required.has(name),
+        typeLabel: schemaTypeLabel(schema),
+        constraints: schemaConstraintLabel(schema),
+        schema,
+    }));
+}
+function exampleValueForSchema(schema) {
+    const enumValues = Array.isArray(schema.enum) ? schema.enum : undefined;
+    if (enumValues && enumValues.length > 0) {
+        return enumValues[0];
+    }
+    if (Object.prototype.hasOwnProperty.call(schema, 'const')) {
+        return schema.const;
+    }
+    const variants = getSchemaVariants(schema).sort((left, right) => {
+        const order = ['integer', 'number', 'boolean', 'object', 'array', 'string'];
+        const leftIndex = order.indexOf(left.type ?? 'string');
+        const rightIndex = order.indexOf(right.type ?? 'string');
+        return (leftIndex === -1 ? order.length : leftIndex) - (rightIndex === -1 ? order.length : rightIndex);
+    });
+    for (const variant of variants) {
+        switch (variant.type) {
+            case 'number':
+            case 'integer':
+                return 1;
+            case 'boolean':
+                return true;
+            case 'object':
+                return {};
+            case 'array':
+                return [];
+            case 'string':
+                return 'value';
+            default:
+                break;
+        }
+    }
+    return 'value';
+}
+function formatExampleCliValue(value) {
+    if (typeof value === 'string')
+        return value;
+    return JSON.stringify(value);
+}
+function buildExampleObject(fields) {
+    return Object.fromEntries(fields.map((field) => [field.name, exampleValueForSchema(field.schema)]));
+}
+function buildActionExamples(action, command = 'suzi run') {
+    const fields = getActionParameterFields(action);
+    const requiredFields = fields.filter((field) => field.required);
+    const primaryFields = requiredFields.length > 0 ? requiredFields : fields.slice(0, 1);
+    const examples = [];
+    if (primaryFields.length === 0) {
+        examples.push(`${command} ${action.name}`);
+        return examples;
+    }
+    const flagArgs = primaryFields
+        .map((field) => `--${camelToKebab(field.name)} ${formatExampleCliValue(exampleValueForSchema(field.schema))}`)
+        .join(' ');
+    examples.push(`${command} ${action.name} ${flagArgs}`);
+    const positionalArgs = primaryFields
+        .map((field) => `${field.name} ${formatExampleCliValue(exampleValueForSchema(field.schema))}`)
+        .join(' ');
+    examples.push(`${command} ${action.name} ${positionalArgs}`);
+    const paramsJson = JSON.stringify(buildExampleObject(primaryFields));
+    examples.push(`${command} ${action.name} --params '${paramsJson}'`);
+    return uniqueStrings(examples);
+}
+function primitiveEquals(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function matchesSchema(value, schema) {
+    const variants = getSchemaVariants(schema);
+    if (variants.length > 1) {
+        return variants.some((variant) => matchesSchema(value, variant));
+    }
+    const variant = variants[0] ?? schema;
+    if (Array.isArray(variant.enum)) {
+        return variant.enum.some((candidate) => primitiveEquals(candidate, value));
+    }
+    if (Object.prototype.hasOwnProperty.call(variant, 'const')) {
+        return primitiveEquals(variant.const, value);
+    }
+    const type = variant.type;
+    if (!type)
+        return true;
+    switch (type) {
+        case 'number':
+            return (typeof value === 'number' &&
+                Number.isFinite(value) &&
+                (typeof variant.minimum !== 'number' || value >= variant.minimum) &&
+                (typeof variant.maximum !== 'number' || value <= variant.maximum) &&
+                (typeof variant.exclusiveMinimum !== 'number' || value > variant.exclusiveMinimum) &&
+                (typeof variant.exclusiveMaximum !== 'number' || value < variant.exclusiveMaximum));
+        case 'integer':
+            return (typeof value === 'number' &&
+                Number.isInteger(value) &&
+                (typeof variant.minimum !== 'number' || value >= variant.minimum) &&
+                (typeof variant.maximum !== 'number' || value <= variant.maximum) &&
+                (typeof variant.exclusiveMinimum !== 'number' || value > variant.exclusiveMinimum) &&
+                (typeof variant.exclusiveMaximum !== 'number' || value < variant.exclusiveMaximum));
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'string':
+            return (typeof value === 'string' &&
+                (typeof variant.minLength !== 'number' || value.length >= variant.minLength) &&
+                (typeof variant.maxLength !== 'number' || value.length <= variant.maxLength));
+        case 'object':
+            return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+        case 'array':
+            return Array.isArray(value);
+        case 'null':
+            return value === null;
+        default:
+            return true;
+    }
+}
+function describeExpectedValue(schema, key) {
+    const typeLabel = schemaTypeLabel(schema);
+    const constraints = schemaConstraintLabel(schema);
+    const base = constraints ? `${typeLabel} (${constraints})` : typeLabel;
+    if (typeLabel === 'boolean') {
+        return 'boolean (true or false)';
+    }
+    if (typeLabel.includes('object') || typeLabel.includes('array')) {
+        return `${base}; pass JSON via --${camelToKebab(key)} '${JSON.stringify(exampleValueForSchema(schema))}' or --params '{...}'`;
+    }
+    return base;
+}
+function validateParamsAgainstSchema(params, action) {
+    const paramSchema = action.parameters;
+    const properties = paramSchema.properties ?? {};
+    const required = new Set(paramSchema.required ?? []);
+    const missingRequired = Array.from(required).filter((key) => params[key] === undefined);
+    const invalidFields = [];
+    for (const [key, value] of Object.entries(params)) {
+        const schema = properties[key];
+        if (!schema)
+            continue;
+        if (!matchesSchema(value, schema)) {
+            invalidFields.push({
+                key,
+                message: `Expected ${describeExpectedValue(schema, key)}.`,
+            });
+        }
+    }
+    return { missingRequired, invalidFields };
+}
+function printCliApiIssues(issues) {
+    if (issues.length === 0)
+        return;
+    console.log();
+    console.log(ui_1.colors.error('  Issues:'));
+    for (const issue of issues) {
+        console.log(`    ${ui_1.colors.error('✕')} ${(0, api_errors_1.formatCliApiErrorIssue)(issue)}`);
+    }
 }
-/**
- * Pretty-print the action result.
- */
 function formatPretty(actionName, result) {
     (0, ui_1.header)(`Result: ${actionName}`);
     console.log();
@@ -183,137 +465,486 @@ function formatPretty(actionName, result) {
         return;
     }
     const obj = result;
-    for (const [key, val] of Object.entries(obj)) {
-        if (val === null || val === undefined)
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null || value === undefined)
             continue;
-        if (typeof val === 'object') {
-            console.log(`  ${ui_1.colors.muted(key + ':')} ${JSON.stringify(val, null, 2).split('\n').join('\n  ')}`);
+        if (typeof value === 'object') {
+            console.log(`  ${ui_1.colors.muted(key + ':')} ${JSON.stringify(value, null, 2).split('\n').join('\n  ')}`);
         }
         else {
-            (0, ui_1.label)(key, String(val));
+            (0, ui_1.label)(key, String(value));
         }
     }
 }
-function registerRunCommand(program) {
-    program
-        .command('run <action>')
-        .description('Execute an action directly (e.g. suzi run polymarket.get_market_price --tokenID 0x123)')
-        .allowUnknownOption()
-        .allowExcessArguments(true)
-        .option('--json <params>', 'Pass all parameters as a JSON string')
-        .option('--output <format>', 'Output format: pretty (default) or json', 'pretty')
-        .option('--dry-run', 'Preview the request payload without executing')
-        .action(async (action, opts) => {
-        const isJson = opts.output === 'json';
-        if (isJson) {
-            console.error('Warning: --output json is deprecated. Use suzi agents run instead.');
+function getCanonicalRunCommand() {
+    return 'suzi run';
+}
+function getRunHelpPayload(action) {
+    const fields = getActionParameterFields(action);
+    return {
+        action: action.name,
+        description: action.description,
+        usage: `${getCanonicalRunCommand()} ${action.name} [--param value] [--params '{"key":"value"}'] [--json]`,
+        parameters: fields.map((field) => ({
+            name: field.name,
+            required: field.required,
+            type: field.typeLabel,
+            ...(field.constraints ? { constraints: field.constraints } : {}),
+        })),
+        examples: buildActionExamples(action),
+    };
+}
+function printActionParameters(action) {
+    const fields = getActionParameterFields(action);
+    if (fields.length === 0) {
+        (0, ui_1.info)(`Action ${chalk_1.default.cyan(action.name)} takes no parameters.`);
+        return;
+    }
+    console.log(chalk_1.default.bold('Parameters:'));
+    for (const field of fields) {
+        const requiredText = field.required ? chalk_1.default.yellow('required') : ui_1.colors.muted('optional');
+        const constraintText = field.constraints ? ` ${ui_1.colors.muted(`(${field.constraints})`)}` : '';
+        console.log(`  ${chalk_1.default.cyan(field.name)}  ${ui_1.colors.muted(field.typeLabel)} ${requiredText}${constraintText}`);
+    }
+}
+function printActionExamples(action) {
+    console.log();
+    console.log(chalk_1.default.bold('Examples:'));
+    for (const example of buildActionExamples(action)) {
+        console.log(`  ${ui_1.colors.primary('$')} ${chalk_1.default.white(example)}`);
+    }
+}
+function printRunActionHelp(action, jsonMode, sourceCommand) {
+    if (jsonMode) {
+        (0, tty_1.outputJson)({ success: true, data: getRunHelpPayload(action) });
+        return;
+    }
+    if (sourceCommand === 'agents run') {
+        (0, ui_1.warn)('`suzi agents run` is deprecated. Use `suzi run` instead.');
+        console.log();
+    }
+    (0, ui_1.header)(`Run ${action.name}`);
+    console.log();
+    console.log(`  ${action.description}`);
+    console.log();
+    console.log(chalk_1.default.bold('Usage:'));
+    console.log(`  ${ui_1.colors.primary(getCanonicalRunCommand())} ${chalk_1.default.white(action.name)} ${ui_1.colors.muted('[options]')}`);
+    console.log();
+    printActionParameters(action);
+    printActionExamples(action);
+    console.log();
+    (0, ui_1.info)(`Use ${chalk_1.default.cyan(`suzi list-actions --protocol ${action.protocol} --schema ${action.name.split('.')[1]}`)} to inspect the raw schema.`);
+    console.log();
+}
+function printGenericRunExamples() {
+    console.log();
+    console.log(chalk_1.default.bold('Examples:'));
+    console.log(`  ${ui_1.colors.primary('$')} ${chalk_1.default.white('suzi run polymarket.deposit --amount 1')}`);
+    console.log(`  ${ui_1.colors.primary('$')} ${chalk_1.default.white('suzi run polymarket.deposit amount 1')}`);
+    console.log(`  ${ui_1.colors.primary('$')} ${chalk_1.default.white(`suzi run polymarket.deposit --params '{"amount":1}'`)}`);
+}
+function emitRunFailure(message, options) {
+    const code = options.code ?? 'VALIDATION_FAILED';
+    if (options.jsonMode) {
+        (0, tty_1.outputJson)({
+            success: false,
+            error: { code, message },
+            ...(options.data ? { data: options.data } : {}),
+        });
+        return;
+    }
+    (0, ui_1.emitCliError)(message, code, false);
+    options.printTextDetails?.();
+}
+function emitSchemaAwareFailure(message, action, options) {
+    const helpPayload = getRunHelpPayload(action);
+    const notes = options.notes ?? [];
+    const extraIssues = options.extraIssues ?? [];
+    emitRunFailure(message, {
+        jsonMode: options.jsonMode,
+        code: options.code,
+        data: {
+            action: helpPayload.action,
+            parameters: helpPayload.parameters,
+            examples: helpPayload.examples,
+            ...(notes.length > 0 ? { notes } : {}),
+            ...(extraIssues.length > 0 ? { issues: extraIssues } : {}),
+        },
+        printTextDetails: () => {
+            console.log();
+            printActionParameters(action);
+            if (extraIssues.length > 0) {
+                console.log();
+                console.log(ui_1.colors.error('Issues:'));
+                for (const issue of extraIssues) {
+                    console.log(`  ${ui_1.colors.error('✕')} ${issue.key}: ${issue.message}`);
+                }
+            }
+            if (notes.length > 0) {
+                console.log();
+                for (const note of notes) {
+                    (0, ui_1.info)(note);
+                }
+            }
+            printActionExamples(action);
+        },
+    });
+}
+function suggestActions(input, actions) {
+    const lower = input.toLowerCase();
+    return actions
+        .filter((action) => {
+        if (action.name.toLowerCase().includes(lower))
+            return true;
+        const actionPart = action.name.split('.')[1]?.toLowerCase();
+        return actionPart ? lower.includes(actionPart) : false;
+    })
+        .slice(0, 5)
+        .map((action) => action.name);
+}
+function looksLikeJsonLiteral(value) {
+    return ((value.startsWith('{') && value.endsWith('}')) ||
+        (value.startsWith('[') && value.endsWith(']')));
+}
+function buildStrayTokenNotes(strayTokens) {
+    if (strayTokens.length === 0)
+        return [];
+    if (strayTokens.length === 1 && looksLikeJsonLiteral(strayTokens[0])) {
+        return [
+            `Unexpected JSON argument ${strayTokens[0]}. --json controls output; use --params '${strayTokens[0]}' for input.`,
+        ];
+    }
+    if (strayTokens.length === 1) {
+        return [
+            `Could not interpret "${strayTokens[0]}". If it is a parameter name, pass a value after it or use --params '{...}'.`,
+        ];
+    }
+    return [
+        `Could not interpret these extra tokens: ${strayTokens.join(' ')}.`,
+        'Use --param value pairs or --params \'{...}\' for action input.',
+    ];
+}
+function hasLegacyJsonOutputFlag(args) {
+    return args.some((arg, index) => arg === '--output' && args[index + 1] === 'json');
+}
+async function loadActionForHelp(actionName) {
+    const cached = (0, actions_cache_1.getCachedActionByName)(actionName);
+    if (cached)
+        return cached;
+    try {
+        return await (0, actions_cache_1.getActionByName)(actionName);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function maybeHandleRunActionHelp(argv = process.argv) {
+    const args = argv.slice(2);
+    const helpRequested = args.includes('--help') || args.includes('-h');
+    if (!helpRequested)
+        return false;
+    let action;
+    let sourceCommand;
+    if (args[0] === 'run' && args[1] && !args[1].startsWith('-')) {
+        action = args[1];
+        sourceCommand = 'run';
+    }
+    else if (args[0] === 'agents' && args[1] === 'run' && args[2] && !args[2].startsWith('-')) {
+        action = args[2];
+        sourceCommand = 'agents run';
+    }
+    if (!action || !sourceCommand) {
+        return false;
+    }
+    const jsonMode = args.includes('--json') || hasLegacyJsonOutputFlag(args);
+    const actionMeta = await loadActionForHelp(action);
+    if (!actionMeta) {
+        emitRunFailure(`Action "${action}" was not found.`, {
+            jsonMode,
+            code: 'NOT_FOUND',
+            data: {
+                action,
+            },
+            printTextDetails: () => {
+                (0, ui_1.info)(`Run ${chalk_1.default.cyan('suzi list-actions')} to see all available actions.`);
+            },
+        });
+        return true;
+    }
+    printRunActionHelp(actionMeta, jsonMode, sourceCommand);
+    return true;
+}
+async function executeRunCommand(action, opts, argv = process.argv, sourceCommand = 'run') {
+    const jsonMode = Boolean(opts.json || opts.output === 'json');
+    if (sourceCommand === 'agents run' && !jsonMode) {
+        (0, ui_1.warn)('`suzi agents run` is deprecated. Use `suzi run` instead.');
+    }
+    if (!action) {
+        emitRunFailure(`Missing action. Expected ${getCanonicalRunCommand()} <protocol.action>.`, {
+            jsonMode,
+            code: 'INPUT_REQUIRED',
+            data: {
+                examples: [
+                    'suzi run polymarket.deposit --amount 1',
+                    'suzi run polymarket.deposit --params \'{"amount":1}\'',
+                ],
+            },
+            printTextDetails: () => {
+                printGenericRunExamples();
+                console.log();
+                (0, ui_1.info)(`Run ${chalk_1.default.cyan('suzi list-actions')} to see all available actions.`);
+            },
+        });
+        return;
+    }
+    const [protocol, actionName] = action.split('.', 2);
+    if (!protocol || !actionName) {
+        emitRunFailure('Action name must be in "protocol.action" format (e.g. polymarket.deposit).', {
+            jsonMode,
+            code: 'VALIDATION_FAILED',
+            data: {
+                action,
+            },
+            printTextDetails: () => {
+                printGenericRunExamples();
+                console.log();
+                (0, ui_1.info)(`Run ${chalk_1.default.cyan('suzi list-actions')} to see all available actions.`);
+            },
+        });
+        return;
+    }
+    if (!(0, ui_1.requireAuth)(jsonMode))
+        return;
+    const rawParams = parseDynamicArgs(argv);
+    let params;
+    if (opts.params) {
+        if (Object.keys(rawParams.params).length > 0 || rawParams.strayTokens.length > 0) {
+            const notes = [
+                'Do not mix --params with individual action arguments.',
+                'Choose either --params \'{...}\' or --param value pairs.',
+            ];
+            if (rawParams.strayTokens.length > 0) {
+                notes.push(...buildStrayTokenNotes(rawParams.strayTokens));
+            }
+            emitRunFailure('Conflicting action input: received --params together with additional action arguments.', {
+                jsonMode,
+                code: 'VALIDATION_FAILED',
+                data: {
+                    action,
+                    notes,
+                },
+                printTextDetails: () => {
+                    for (const note of notes) {
+                        (0, ui_1.info)(note);
+                    }
+                },
+            });
+            return;
         }
-        if (!(0, ui_1.requireAuth)(isJson))
+        try {
+            params = JSON.parse(opts.params);
+        }
+        catch (err) {
+            emitRunFailure(`Invalid JSON in --params: ${err instanceof Error ? err.message : String(err)}`, {
+                jsonMode,
+                code: 'VALIDATION_FAILED',
+                data: {
+                    action,
+                    example: `${getCanonicalRunCommand()} ${action} --params '{"amount":1}'`,
+                },
+                printTextDetails: () => {
+                    (0, ui_1.info)('Pass a JSON object to --params, for example --params \'{"amount":1}\'.');
+                },
+            });
             return;
-        // Validate action name format
-        const [protocol, actionName] = action.split('.', 2);
-        if (!protocol || !actionName) {
-            (0, ui_1.error)('Action name must be in "protocol.action" format (e.g. polymarket.place_order).');
-            (0, ui_1.info)(`Run ${chalk_1.default.cyan('suzi list-actions')} to see all available actions.`);
+        }
+        if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+            emitRunFailure('--params must be a JSON object (e.g. \'{"key":"value"}\').', {
+                jsonMode,
+                code: 'VALIDATION_FAILED',
+            });
             return;
         }
-        // Build params
-        let params;
-        if (opts.json) {
-            try {
-                params = JSON.parse(opts.json);
-            }
-            catch (err) {
-                (0, ui_1.error)(`Invalid JSON in --json flag: ${err instanceof Error ? err.message : String(err)}`);
-                return;
+    }
+    else {
+        params = rawParams.params;
+    }
+    let actionMeta;
+    try {
+        actionMeta = await (0, actions_cache_1.getActionByName)(action);
+    }
+    catch {
+        // Proceed without local schema metadata.
+    }
+    if (rawParams.strayTokens.length > 0) {
+        const notes = buildStrayTokenNotes(rawParams.strayTokens);
+        if (actionMeta) {
+            emitSchemaAwareFailure('Could not parse one or more action parameters.', actionMeta, {
+                jsonMode,
+                code: 'VALIDATION_FAILED',
+                notes,
+            });
+        }
+        else {
+            emitRunFailure('Could not parse one or more action parameters.', {
+                jsonMode,
+                code: 'VALIDATION_FAILED',
+                data: {
+                    action,
+                    notes,
+                },
+                printTextDetails: () => {
+                    for (const note of notes) {
+                        (0, ui_1.info)(note);
+                    }
+                },
+            });
+        }
+        return;
+    }
+    if (actionMeta) {
+        const refined = refineParamsWithSchema(params, actionMeta);
+        params = refined.params;
+        if (refined.unknownKeys.length > 0) {
+            emitSchemaAwareFailure(`Unknown parameter(s): ${refined.unknownKeys.map((key) => `--${key}`).join(', ')}`, actionMeta, {
+                jsonMode,
+                code: 'VALIDATION_FAILED',
+                notes: [
+                    `Use suzi list-actions --protocol ${protocol} --schema ${actionName} to inspect the raw schema.`,
+                ],
+            });
+            return;
+        }
+        const validation = validateParamsAgainstSchema(params, actionMeta);
+        if (validation.missingRequired.length > 0 || validation.invalidFields.length > 0) {
+            const messageParts = [];
+            if (validation.missingRequired.length > 0) {
+                messageParts.push(`Missing required parameter(s): ${validation.missingRequired.join(', ')}`);
             }
-            if (typeof params !== 'object' || params === null || Array.isArray(params)) {
-                (0, ui_1.error)('--json must be a JSON object (e.g. \'{"key":"value"}\').');
-                return;
+            if (validation.invalidFields.length > 0) {
+                messageParts.push(...validation.invalidFields.map((issue) => `${issue.key}: ${issue.message}`));
             }
+            emitSchemaAwareFailure(messageParts.join('. '), actionMeta, {
+                jsonMode,
+                code: 'VALIDATION_FAILED',
+                notes: rawParams.positionalPairs.length > 0
+                    ? ['Bare key/value pairs are supported, but the canonical form is --param value or --params \'{...}\'.']
+                    : undefined,
+                extraIssues: validation.invalidFields,
+            });
+            return;
         }
-        else {
-            params = parseDynamicArgs(process.argv);
+    }
+    if (!actionMeta) {
+        if (!jsonMode) {
+            (0, ui_1.warn)(`Action "${action}" not found in local cache. Attempting execution anyway.`);
         }
-        // Look up action metadata for key resolution and coercion
-        let actionMeta;
         try {
-            actionMeta = await (0, actions_cache_1.getActionByName)(action);
+            const allActions = await (0, actions_cache_1.getActions)();
+            const suggestions = suggestActions(action, allActions);
+            if (!jsonMode && suggestions.length > 0) {
+                (0, ui_1.info)(`Did you mean: ${suggestions.map((suggestion) => chalk_1.default.cyan(suggestion)).join(', ')}?`);
+            }
         }
         catch {
-            // Cache fetch failed — proceed without schema refinement
+            // Ignore suggestion failures.
         }
-        if (actionMeta && !opts.json) {
-            params = refineParamsWithSchema(params, actionMeta);
+    }
+    if (opts.dryRun) {
+        if (jsonMode) {
+            (0, tty_1.outputJson)({
+                success: true,
+                data: {
+                    action,
+                    ...(actionMeta ? { description: actionMeta.description } : {}),
+                    request: { name: action, params },
+                },
+            });
+            return;
         }
-        if (!actionMeta) {
-            // Action not in cache — warn but don't block
-            (0, ui_1.warn)(`Action "${action}" not found in local cache. Attempting execution anyway.`);
-            try {
-                const allActions = await (0, actions_cache_1.getActions)();
-                const suggestions = suggestActions(action, allActions);
-                if (suggestions.length > 0) {
-                    (0, ui_1.info)(`Did you mean: ${suggestions.map((s) => chalk_1.default.cyan(s)).join(', ')}?`);
-                }
-            }
-            catch {
-                // Ignore suggestion failures
-            }
+        (0, ui_1.header)('Dry Run');
+        console.log();
+        (0, ui_1.label)('action', action);
+        if (actionMeta) {
+            (0, ui_1.label)('description', actionMeta.description);
         }
-        // Dry-run: show what would be sent
-        if (opts.dryRun) {
-            (0, ui_1.header)('Dry Run');
-            console.log();
-            (0, ui_1.label)('action', action);
-            if (actionMeta) {
-                (0, ui_1.label)('description', actionMeta.description);
+        console.log();
+        console.log(`  ${ui_1.colors.muted('Request payload:')}`);
+        console.log(JSON.stringify({ name: action, params }, null, 2));
+        return;
+    }
+    const spinner = (0, tty_1.createSpinner)(`Executing ${chalk_1.default.bold(action)}...`, jsonMode);
+    try {
+        const resp = await (0, api_1.post)('/api/actions/execute', { name: action, params });
+        if (!resp.ok || !resp.data?.ok) {
+            spinner?.fail('Action failed');
+            const parsed = (0, api_errors_1.parseCliApiError)(resp.data);
+            const summary = parsed.summary || `API returned status ${resp.status}`;
+            if (jsonMode) {
+                (0, tty_1.outputJson)({
+                    success: false,
+                    error: {
+                        code: resp.status === 400 ? 'VALIDATION_FAILED' : 'INTERNAL_ERROR',
+                        message: summary,
+                    },
+                    data: {
+                        error: parsed.raw,
+                        ...(parsed.issues.length > 0 ? { issues: parsed.issues } : {}),
+                        ...(parsed.detailsText ? { details: parsed.detailsText } : {}),
+                    },
+                });
             }
-            console.log();
-            console.log(`  ${ui_1.colors.muted('Request payload:')}`);
-            console.log(JSON.stringify({ name: action, params }, null, 2));
-            return;
-        }
-        // Execute
-        const spinner = (0, tty_1.createSpinner)(`Executing ${chalk_1.default.bold(action)}...`, isJson);
-        try {
-            const resp = await (0, api_1.post)('/api/actions/execute', { name: action, params });
-            if (!resp.ok || !resp.data?.ok) {
-                spinner?.fail(`Action failed`);
-                const msg = resp.data?.message || resp.data?.error || `API returned status ${resp.status}`;
-                if (isJson) {
-                    (0, tty_1.outputJson)({ success: false, error: msg });
+            else {
+                (0, ui_1.emitCliError)(summary, resp.status === 400 ? 'VALIDATION_FAILED' : 'INTERNAL_ERROR', false);
+                if (parsed.issues.length > 0) {
+                    printCliApiIssues(parsed.issues);
                 }
-                else {
-                    (0, ui_1.error)(msg);
-                    if (resp.status === 400) {
-                        (0, ui_1.info)(`Run ${chalk_1.default.cyan(`suzi list-actions --protocol ${protocol} --schema ${actionName}`)} to see the expected parameters.`);
-                    }
+                else if (parsed.detailsText) {
+                    console.log(ui_1.colors.muted(`  ${parsed.detailsText}`));
+                }
+                if (resp.status === 400) {
+                    console.log();
+                    (0, ui_1.info)(`Run ${chalk_1.default.cyan(`${getCanonicalRunCommand()} ${action} --help`)} for parameters and examples.`);
                 }
-                return;
-            }
-            if (isJson) {
-                (0, tty_1.outputJson)({ success: true, data: resp.data.result });
-            }
-            else {
-                spinner?.succeed(`${action} executed successfully`);
-                console.log();
-                formatPretty(action, resp.data.result);
             }
+            return;
         }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            if (isJson) {
-                (0, tty_1.outputJson)({ success: false, error: { code: 'NETWORK_ERROR', message } });
-            }
-            else {
-                spinner?.fail('Request failed');
-                (0, ui_1.error)(message);
-            }
+        if (jsonMode) {
+            (0, tty_1.outputJson)({ success: true, data: resp.data.result });
         }
-        if (!isJson) {
+        else {
+            spinner?.succeed(`${action} executed successfully`);
             console.log();
-            (0, ui_1.divider)();
+            formatPretty(action, resp.data.result);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (jsonMode) {
+            (0, tty_1.outputJson)({ success: false, error: { code: 'NETWORK_ERROR', message } });
         }
+        else {
+            spinner?.fail('Request failed');
+            (0, ui_1.emitCliError)(message, 'NETWORK_ERROR', false);
+        }
+    }
+    if (!jsonMode) {
+        console.log();
+        (0, ui_1.divider)();
+    }
+}
+function registerRunCommand(program) {
+    program
+        .command('run [action]')
+        .description('Execute an action directly (e.g. suzi run polymarket.deposit --amount 1)')
+        .allowUnknownOption()
+        .allowExcessArguments(true)
+        .option('--params <json>', 'Pass action parameters as a JSON object')
+        .option('--json', 'Output as JSON')
+        .addOption(new commander_1.Option('--output <format>', 'Deprecated output format alias').choices(['pretty', 'json']).hideHelp())
+        .option('--dry-run', 'Preview the request payload without executing')
+        .action(async (action, opts) => {
+        await executeRunCommand(action, opts, process.argv, 'run');
     });
 }
 //# sourceMappingURL=run.js.map