@testin-official/xagent 0.3.9 → 0.3.11

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { realpathSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { stdin as input, stdout as output } from "node:process";
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import { fileURLToPath } from "node:url";
 import { AuthoringDraftStore } from "./authoring/draft-store.js";
 import { buildDeviceActionRequest } from "./action/protocol.js";
@@ -29,9 +29,20 @@ const API_EXIT = {
     authoring_session_expired: 5, authoring_session_not_active: 5,
     test_failed: 1, infrastructure_failed: 6, invalid_response: 6, authoring_session_renewal_failed: 6, timeout: 7,
 };
+// `fail()` runs from the top-level catch, where the parsed options are out of
+// scope. It used to re-derive the output format from `process.argv` — a second
+// source of truth next to the `ctx.json` every other path uses, and the wrong
+// array entirely when `runCli()` is handed an explicit argv. Keep the resolved
+// flag, plus the argv actually parsed as a fallback for failures raised before
+// any command has built a Context.
+let parsedJsonMode;
+let parsedArgv = process.argv;
+function jsonOutputRequested() { return parsedJsonMode ?? parsedArgv.includes("--json"); }
 function context(command) {
     const options = command.optsWithGlobals();
-    return { json: Boolean(options.json), profile: options.profile, userConfig: options.userConfig, projectConfig: options.config, nonInteractive: Boolean(options.nonInteractive), config: new ConfigStore(options.userConfig) };
+    const json = Boolean(options.json);
+    parsedJsonMode = json;
+    return { json, profile: options.profile, userConfig: options.userConfig, projectConfig: options.config, nonInteractive: Boolean(options.nonInteractive), config: new ConfigStore(options.userConfig) };
 }
 function emit(ctx, data, human) {
     if (ctx.json)
@@ -59,23 +70,15 @@ function unexpected(error) {
 }
 function fail(error) {
     const known = error instanceof CliError || error instanceof XAgentApiError ? error : unexpected(error);
-    const json = process.argv.includes("--json");
+    const json = jsonOutputRequested();
     const payload = known.toJSON();
     if (json)
         process.stdout.write(`${JSON.stringify({ error: payload })}\n`);
     else
-        process.stderr.write(`Error: ${String(payload.message)}\n${payload.application_url ? `Apply at: ${payload.application_url}\n` : ""}`);
+        process.stderr.write(`Error: ${String(payload.message)}\n`);
     process.exit(API_EXIT[known.code] ?? (known instanceof CliError ? known.exitCode : 6));
 }
-function tokenApplicationUrl(baseUrl, tokenType) {
-    try {
-        const url = new URL(baseUrl);
-        return `${url.origin}/agent/developer-tokens/index.html?type=${encodeURIComponent(tokenType)}`;
-    }
-    catch {
-        return `${baseUrl.replace(/\/+$/, "")}/agent/developer-tokens/index.html?type=${encodeURIComponent(tokenType)}`;
-    }
-}
+const TOKEN_CONTACT_MESSAGE = "请联系云小宝并依据用户id获取相关token";
 async function readSecret(prompt) {
     if (!input.isTTY || typeof input.setRawMode !== "function")
         throw new CliError("authentication_required", "--token-stdin is required when no interactive terminal is available", 3);
@@ -122,7 +125,7 @@ async function authenticatedClient(ctx, uploadTimeoutMs) {
     }
     catch (error) {
         if (error instanceof CliError && error.code === "authentication_required")
-            throw new CliError(error.code, error.message, 3, { required_token_type: profile.data.expected_token_type, application_url: profile.data.token_apply_url });
+            throw new CliError(error.code, `${error.message}。${TOKEN_CONTACT_MESSAGE}`, 3, { required_token_type: profile.data.expected_token_type });
         throw error;
     }
     const client = new XAgentClient(profile.data.base_url, token, profile.data.upload_base_url, 30_000, uploadTimeoutMs ?? 900_000);
@@ -178,7 +181,26 @@ function billingText(value) {
 function emitRun(ctx, run, useStatusExit = true) { emit(ctx, run, `Run ${run.id} status=${run.status}${billingText(run)}`); if (!useStatusExit)
     return; process.exitCode = { failed: 1, cancelled: 4, infrastructure_failed: 6, timed_out: 7 }[run.status] ?? 0; }
 function progressReporter(ctx) { return createRunProgressReporter(ctx); }
+/** Human summary for `doctor`, derived from the same checks the JSON reports. */
+function doctorSummary(checks, profile) {
+    // `configuration` used to be a hardcoded "ok", so a machine with no user
+    // configuration file at all still reported a healthy configuration while every
+    // other field said not_configured.
+    if (checks.configuration !== "ok")
+        return "Local configuration is incomplete: no user configuration file was found";
+    if (checks.profile !== "ok")
+        return profile
+            ? `Local configuration is incomplete: Profile '${profile}' does not exist`
+            : "Local configuration is incomplete: no Profile is selected";
+    if (checks.credential_source !== "configured")
+        return `Local configuration is incomplete: Profile '${profile}' has no credential source`;
+    return `Local configuration is valid (Profile '${profile}')`;
+}
 const program = new Command().name("xagent").description("XAgent Developer CLI").showHelpAfterError();
+// Without this, commander prints parse errors itself and calls process.exit(1)
+// before `runCli` can see them. That exit code collides with `test_failed: 1`
+// and the plain-text output ignored `--json` entirely. Take over the exit path.
+program.exitOverride();
 program.option("--json", "Emit stable JSON output").option("--profile <name>", "Select a named authentication Profile").option("--config <path>", "Use a project xagent.yaml").option("--user-config <path>", "Use an explicit user Profile configuration").option("--non-interactive", "Disable interactive prompts");
 program.command("version").description("Show CLI and contract versions").action(async function () {
     const ctx = context(this);
@@ -187,15 +209,34 @@ program.command("version").description("Show CLI and contract versions").action(
 program.command("doctor").description("Check local configuration and credential source").action(async function () {
     const ctx = context(this);
     const payload = await ctx.config.load();
-    const profile = ctx.profile || payload.default_profile;
-    emit(ctx, { checks: { configuration: "ok", profile: profile ? "ok" : "not_configured", credential_source: profile && payload.profiles[profile] && (payload.profiles[profile].credential_env || payload.profiles[profile].credential_ref) ? "configured" : "not_configured", online_checks_performed: false } }, "Local configuration is valid");
+    const selected = ctx.profile || payload.default_profile;
+    // `ctx.profile` is not validated anywhere in this command, so a typo used to be
+    // reported as `profile: "ok"` while `credential_source` said not_configured.
+    const profileExists = typeof selected === "string" && Object.hasOwn(payload.profiles, selected);
+    const stored = profileExists ? payload.profiles[selected] : undefined;
+    const checks = {
+        // Whether the user configuration file is actually present. `ConfigStore.load()`
+        // treats ENOENT as an empty configuration rather than an error, so this field
+        // has to look at the filesystem to mean anything.
+        configuration: existsSync(ctx.config.filePath) ? "ok" : "not_configured",
+        profile: profileExists ? "ok" : "not_configured",
+        credential_source: stored && (stored.credential_env || stored.credential_ref) ? "configured" : "not_configured",
+        online_checks_performed: false,
+    };
+    // The summary used to be the constant "Local configuration is valid" and the
+    // exit code was always 0, so a fresh machine — or a mistyped --profile — read
+    // as healthy while the JSON said not_configured. That made the check useless
+    // as a gate.
+    emit(ctx, { checks }, doctorSummary(checks, profileExists ? String(selected) : selected ?? undefined));
+    if (checks.configuration !== "ok" || checks.profile !== "ok" || checks.credential_source !== "configured")
+        process.exitCode = 2;
 });
 const config = program.command("config");
 config.command("path").action(async function () { const ctx = context(this); emit(ctx, { path: ctx.config.filePath }, ctx.config.filePath); });
 config.command("validate").action(async function () { const ctx = context(this); await ctx.config.load(); emit(ctx, { valid: true, schema_version: CONFIG_SCHEMA_VERSION }, "Configuration is valid"); });
 config.command("show").action(async function () { const ctx = context(this); const payload = await ctx.config.load(); emit(ctx, { schema_version: payload.schema_version, default_profile: payload.default_profile, profiles: Object.fromEntries(Object.entries(payload.profiles).sort(([a], [b]) => a.localeCompare(b)).map(([name, item]) => [name, Profile.from(name, item).publicData()])) }); });
 const profiles = program.command("profiles");
-profiles.command("add").argument("<name>").requiredOption("--base-url <url>").requiredOption("--expected-token-type <type>").option("--token-env <name>").option("--token-apply-url <url>").option("--upload-base-url <url>").option("--use").action(async function (name, options) { const ctx = context(this); const data = { base_url: options.baseUrl, expected_token_type: options.expectedTokenType, ...(options.tokenEnv ? { credential_env: options.tokenEnv } : {}), ...(options.uploadBaseUrl ? { upload_base_url: options.uploadBaseUrl } : {}), token_apply_url: options.tokenApplyUrl ?? tokenApplicationUrl(options.baseUrl, options.expectedTokenType) }; const profile = Profile.from(name, data); await ctx.config.putProfile(profile); if (options.use)
+profiles.command("add").argument("<name>").requiredOption("--base-url <url>").requiredOption("--expected-token-type <type>").option("--token-env <name>").option("--upload-base-url <url>").option("--use").action(async function (name, options) { const ctx = context(this); const data = { base_url: options.baseUrl, expected_token_type: options.expectedTokenType, ...(options.tokenEnv ? { credential_env: options.tokenEnv } : {}), ...(options.uploadBaseUrl ? { upload_base_url: options.uploadBaseUrl } : {}) }; const profile = Profile.from(name, data); await ctx.config.putProfile(profile); if (options.use)
     await ctx.config.useProfile(name); emit(ctx, profile.publicData(), `Profile '${name}' added`); });
 profiles.command("list").action(async function () { const ctx = context(this); const payload = await ctx.config.load(); emit(ctx, { profiles: (await ctx.config.listProfiles()).map((profile) => ({ ...profile.publicData(), default: profile.name === payload.default_profile })) }); });
 profiles.command("show").argument("[name]").action(async function (name) { const ctx = context(this); const profile = await ctx.config.getProfile(name ?? ctx.profile); emit(ctx, profile.publicData()); });
@@ -205,18 +246,18 @@ const auth = program.command("auth");
 auth.command("status").action(async function () { const ctx = context(this); const { profile, client } = await authenticatedClient(ctx); const principal = await client.getPrincipal(); if (principal.token_type !== profile.data.expected_token_type)
     throw new CliError("token_type_mismatch", `Profile expects ${profile.data.expected_token_type}, server resolved ${principal.token_type}`, 3); emit(ctx, { profile: profile.name, principal }, `${profile.name}: ${principal.token_type} eid=${principal.eid} project=${principal.project_id}`); });
 auth.command("login").option("--save").option("--token-stdin").action(async function (options) { const ctx = context(this); const profile = await selectedProfile(ctx); if (!options.tokenStdin && !ctx.json)
-    process.stderr.write(`Token 申请地址：${profile.data.token_apply_url ?? tokenApplicationUrl(profile.data.base_url, profile.data.expected_token_type)}\n`); let token = ""; if (options.tokenStdin)
+    process.stderr.write(`${TOKEN_CONTACT_MESSAGE}\n`); let token = ""; if (options.tokenStdin)
     token = (await readFile(0, "utf8")).trim().replace(/^\uFEFF/, "");
 else if (ctx.nonInteractive)
-    throw new CliError("authentication_required", "--token-stdin is required in non-interactive mode", 3);
+    throw new CliError("authentication_required", `--token-stdin is required in non-interactive mode。${TOKEN_CONTACT_MESSAGE}`, 3);
 else
     token = (await readSecret("Developer Token: ")).trim(); if (!token)
-    throw new CliError("authentication_required", "Developer Token is required", 3); const client = new XAgentClient(profile.data.base_url, token); let principal; try {
+    throw new CliError("authentication_required", `Developer Token is required。${TOKEN_CONTACT_MESSAGE}`, 3); const client = new XAgentClient(profile.data.base_url, token); let principal; try {
     principal = await client.getPrincipal();
 }
 catch (error) {
     if (error instanceof XAgentApiError && ["token_invalid", "token_expired", "token_revoked"].includes(error.code))
-        throw new CliError(error.code, error.message, 3, { required_token_type: profile.data.expected_token_type, application_url: profile.data.token_apply_url });
+        throw new CliError(error.code, `${error.message}。${TOKEN_CONTACT_MESSAGE}`, 3, { required_token_type: profile.data.expected_token_type });
     throw error;
 } if (principal.token_type !== profile.data.expected_token_type)
     throw new CliError("token_type_mismatch", `Profile expects ${profile.data.expected_token_type}, server resolved ${principal.token_type}`, 3); let saved = false; if (options.save) {
@@ -232,22 +273,22 @@ catch (error) {
     saved = true;
 } emit(ctx, { profile: profile.name, saved, principal }, `Authenticated Profile '${profile.name}'`); });
 auth.command("logout").action(async function () { const ctx = context(this); const profile = await selectedProfile(ctx); await new CredentialResolver().delete(profile); await ctx.config.setCredentialReference(profile.name); emit(ctx, { profile: profile.name, credential_removed: true }, `Profile '${profile.name}' logged out`); });
-program.command("init").requiredOption("--base-url <url>").option("--token-type <type>", undefined, "personal").option("--name <name>", undefined, "default").option("--token-env <name>").option("--token-apply-url <url>").option("--upload-base-url <url>").action(async function (options) { const ctx = context(this); const profile = Profile.from(options.name, { base_url: options.baseUrl, expected_token_type: options.tokenType, ...(options.tokenEnv ? { credential_env: options.tokenEnv } : {}), ...(options.uploadBaseUrl ? { upload_base_url: options.uploadBaseUrl } : {}), token_apply_url: options.tokenApplyUrl ?? tokenApplicationUrl(options.baseUrl, options.tokenType) }); await ctx.config.putProfile(profile); await ctx.config.useProfile(profile.name); emit(ctx, profile.publicData(), `Profile '${profile.name}' initialized`); if (!ctx.json)
-    process.stderr.write(`Token 申请地址：${profile.data.token_apply_url}\n`); });
+program.command("init").requiredOption("--base-url <url>").option("--token-type <type>", undefined, "personal").option("--name <name>", undefined, "default").option("--token-env <name>").option("--upload-base-url <url>").action(async function (options) { const ctx = context(this); const profile = Profile.from(options.name, { base_url: options.baseUrl, expected_token_type: options.tokenType, ...(options.tokenEnv ? { credential_env: options.tokenEnv } : {}), ...(options.uploadBaseUrl ? { upload_base_url: options.uploadBaseUrl } : {}) }); await ctx.config.putProfile(profile); await ctx.config.useProfile(profile.name); emit(ctx, profile.publicData(), `Profile '${profile.name}' initialized`); if (!ctx.json)
+    process.stderr.write(`${TOKEN_CONTACT_MESSAGE}\n`); });
 program.command("validate").argument("<scriptFile>").action(async function (file) { const ctx = context(this); const parsed = await loadScript(file); emit(ctx, { valid: true, schema_version: parsed.inputSchemaVersion ?? parsed.script.schema_version, execution_schema_version: parsed.script.schema_version, source_hash: parsed.sourceHash, step_count: parsed.script.steps.length }, `${file}: valid (${parsed.script.steps.length} steps)`); });
-const skills = program.command("skills");
-skills.command("list").action(async function () { const ctx = context(this); emit(ctx, await (await authenticatedClient(ctx)).client.listEffectiveSkills()); });
-skills.command("show").argument("<name>").action(async function (name) { const ctx = context(this); emit(ctx, await (await authenticatedClient(ctx)).client.getEffectiveSkill(name)); });
-skills.command("reference").argument("<name>").argument("<path>").action(async function (name, reference) { const ctx = context(this); emit(ctx, await (await authenticatedClient(ctx)).client.getEffectiveSkillReference(name, reference)); });
-const packaged = skills.command("packaged");
-packaged.command("list").action(async function () { const ctx = context(this); emit(ctx, { skills: listSkills() }); });
-packaged.command("show").argument("<name>").action(async function (name) { const ctx = context(this); try {
+const skills = program.command("skills").description("Inspect the Skills the XAgent service serves for the current Principal");
+skills.command("list").description("List the Skills effective for the current Principal").action(async function () { const ctx = context(this); emit(ctx, await (await authenticatedClient(ctx)).client.listEffectiveSkills()); });
+skills.command("show").argument("<name>").description("Show a service-side Skill's effective content").action(async function (name) { const ctx = context(this); emit(ctx, await (await authenticatedClient(ctx)).client.getEffectiveSkill(name)); });
+skills.command("reference").argument("<name>").argument("<path>").description("Show one reference document of a service-side Skill").action(async function (name, reference) { const ctx = context(this); emit(ctx, await (await authenticatedClient(ctx)).client.getEffectiveSkillReference(name, reference)); });
+const packaged = skills.command("packaged").description("Inspect the Skills bundled with this local CLI (no service call)");
+packaged.command("list").description("List locally packaged Skills").action(async function () { const ctx = context(this); emit(ctx, { skills: listSkills() }); });
+packaged.command("show").argument("<name>").description("Show a locally packaged Skill's content").action(async function (name) { const ctx = context(this); try {
     emit(ctx, { name, content: await readSkill(name) });
 }
 catch {
     throw new XAgentApiError("resource_not_found", "Skill was not found");
 } });
-packaged.command("references").argument("<name>").action(async function (name) { const ctx = context(this); try {
+packaged.command("references").argument("<name>").description("List the reference documents of a locally packaged Skill").action(async function (name) { const ctx = context(this); try {
     emit(ctx, { name, references: await listSkillReferences(name) });
 }
 catch {
@@ -271,47 +312,65 @@ function domainArgument(value) {
     return value;
 }
 const integrations = program.command("integrations").description("Install and verify the XAgent Agent Host Skill");
-integrations.command("detect").option("--host <host>").action(async function (options) {
+integrations.command("detect").description("Report which Agent Hosts have the XAgent Skill installed").option("--host <host>").action(async function (options) {
     const ctx = context(this);
-    emit(ctx, { hosts: await detectHost(options.host ? hostArgument(options.host) : undefined) });
+    const hosts = await detectHost(options.host ? hostArgument(options.host) : undefined);
+    const installed = hosts.filter((item) => item.installed).map((item) => String(item.host));
+    emit(ctx, { hosts }, installed.length ? `XAgent Skill installed for: ${installed.join(", ")}` : "XAgent Skill is not installed for any Agent Host");
 });
 integrations.command("install").argument("<host>").option("--force", "Overwrite the existing XAgent Skill only").action(async function (host, options) {
     const ctx = context(this);
     emit(ctx, await installHost(hostArgument(host), Boolean(options.force)), `Installed xagent-skill for ${host}`);
 });
-integrations.command("doctor").option("--host <host>").action(async function (options) {
+integrations.command("doctor").description("Check whether an installed XAgent Skill needs syncing").option("--host <host>").action(async function (options) {
     const ctx = context(this);
-    emit(ctx, { checks: await doctorHost(options.host ? hostArgument(options.host) : undefined) });
+    const checks = await doctorHost(options.host ? hostArgument(options.host) : undefined);
+    // `action_required` was reported in the payload but never reflected in the exit
+    // code, so a Host whose Skill still needs syncing exited 0. `verify-skill`
+    // already gates on 2; keep the same contract here.
+    const pending = checks.filter((check) => String(check.action_required ?? "none") !== "none");
+    emit(ctx, { checks }, pending.length ? `XAgent Skill needs attention: ${pending.map((check) => `${String(check.host)}: ${String(check.action_required)}`).join(", ")}` : "XAgent Skill is up to date");
+    if (pending.length)
+        process.exitCode = 2;
 });
-integrations.command("sync").option("--host <host>").action(async function (options) {
+integrations.command("sync").description("Reinstall the XAgent Skill for every Agent Host that has it").option("--host <host>").action(async function (options) {
     const ctx = context(this);
-    emit(ctx, { synced: await syncHost(options.host ? hostArgument(options.host) : undefined) });
+    const synced = await syncHost(options.host ? hostArgument(options.host) : undefined);
+    emit(ctx, { synced }, synced.length ? `Synced xagent-skill for: ${synced.map((item) => String(item.host)).join(", ")}` : "No installed Agent Host needed syncing");
 });
 integrations.command("uninstall").argument("<host>").requiredOption("--force", "Confirm removal of the XAgent Skill directory").action(async function (host, options) {
     const ctx = context(this);
     emit(ctx, await uninstallHost(hostArgument(host), Boolean(options.force)), `Removed xagent-skill for ${host}`);
 });
-integrations.command("verify-skill").argument("<directory>").action(async function (directory) {
+integrations.command("verify-skill").description("Validate that a Skill directory is structurally compatible").argument("<directory>").action(async function (directory) {
     const ctx = context(this);
     const result = await verifySkillDirectory(directory);
     emit(ctx, result, result.valid ? "XAgent Skill is compatible" : "XAgent Skill is incompatible");
     if (!result.valid)
         process.exitCode = 2;
 });
-integrations.command("route").argument("<domain>").option("--profile <name>", "Profile name to include in the MCP command").action(async function (domain, options) {
+// No local `--profile` here. Redefining the global option made two values mean
+// the same thing: the local copy silently won over the global one, so
+// `xagent --profile A integrations route action --profile B` dropped A with no
+// warning. The global option is accepted after the subcommand name, so a single
+// definition covers both placements.
+integrations.command("route").argument("<domain>").description("Show the MCP command for a user behavior domain").action(async function (domain) {
     const ctx = context(this);
     const selected = domainArgument(domain);
     routeForDomain(selected);
-    emit(ctx, routeOutput(selected, options.profile ?? ctx.profile));
+    const output = routeOutput(selected, ctx.profile);
+    const command = output.mcp_command;
+    emit(ctx, output, `${String(output.domain)}: skill=${String(output.skill)} mode=${String(output.mcp_mode)} side_effects=${String(output.side_effects)}; MCP: ${command.command} ${command.args.join(" ")}`);
 });
-integrations.command("options").action(async function () {
+integrations.command("options").description("List the user behavior domains this CLI can route").action(async function () {
     const ctx = context(this);
+    const choices = USER_WORKFLOW_ROUTES.map(({ domain, mode, skill, side_effects, description }) => ({ domain, mode, skill, side_effects, description }));
     emit(ctx, {
         default_domain: DEFAULT_WORKFLOW_DOMAIN,
         default_mode: routeForDomain(DEFAULT_WORKFLOW_DOMAIN).mode,
-        choices: USER_WORKFLOW_ROUTES.map(({ domain, mode, skill, side_effects, description }) => ({ domain, mode, skill, side_effects, description })),
+        choices,
         selection_required_before_side_effects: false,
-    });
+    }, `Default domain: ${DEFAULT_WORKFLOW_DOMAIN}; domains: ${USER_WORKFLOW_DOMAINS.join(", ")}`);
 });
 const authoring = program.command("authoring");
 authoring.command("start").requiredOption("--device-id <id>").requiredOption("--idempotency-key <key>").action(async function (options) { const ctx = context(this); const result = await (await authenticatedClient(ctx)).client.authoring.createSession(options.deviceId, options.idempotencyKey); emit(ctx, result, `Authoring Session ${result.id} status=${result.status}${billingText(result)}`); });
@@ -351,7 +410,9 @@ device.command("keepalive").argument("<sessionId>").option("--poll-interval <sec
     const ctx = context(this);
     const { client } = await authenticatedClient(ctx);
     const manager = new SessionLeaseManager(client.action, { onEvent: (event) => emit(ctx, event, event.type === "renewed" ? `Device Session ${event.session_id} renewed until ${event.expires_at ?? "unknown"}` : undefined) });
-    const deregister = onInterrupt(async () => { manager.unregister(sessionId); });
+    // Ctrl+C must release the device, not just forget the local lease: leaving it
+    // until expiry keeps billing the session for time the user already stopped using.
+    const deregister = onInterrupt(async () => { await manager.releaseAll(); });
     try {
         await manager.keepAlive(sessionId, { pollMs: Number(options.pollInterval) * 1000 });
         emit(ctx, { session_id: sessionId, status: "TERMINAL", lease: manager.getLease(sessionId) ?? null }, `Device Session ${sessionId} is terminal`);
@@ -388,6 +449,7 @@ program.command("run")
     .option("--timeout-ms <milliseconds>", undefined, "600000")
     .option("--wait")
     .option("--wait-timeout <seconds>", undefined, "900")
+    .option("--poll-interval <seconds>", "Seconds between Run status checks while --wait is active", "2")
     .option("--upload-timeout <seconds>", undefined, "900")
     .action(async function (scriptFile, options) {
     const ctx = context(this);
@@ -401,6 +463,36 @@ program.command("run")
     const packageId = options.packageId ? Number(options.packageId) : script.package_id;
     if (packageId !== undefined && (!Number.isInteger(Number(packageId)) || Number(packageId) < 1))
         throw new CliError("invalid_request", "--package-id must be a positive integer");
+    // contracts/developer/v1/run-create.schema.json requires an integer in
+    // 1000..28800000. Without this check `--timeout-ms abc` shipped
+    // `"timeout_ms":null` and `--timeout-ms -1` / `1500.7` went out verbatim,
+    // all with exit code 0.
+    const timeoutMs = Number(options.timeoutMs);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1_000 || timeoutMs > 28_800_000)
+        throw new CliError("invalid_request", "--timeout-ms must be an integer from 1000 to 28800000");
+    // `--upload-timeout abc` reached AbortSignal.timeout(NaN) deeper in the SDK,
+    // which surfaced the reason as an infrastructure failure instead of a bad
+    // argument.
+    const uploadTimeoutSeconds = Number(options.uploadTimeout);
+    if (!Number.isFinite(uploadTimeoutSeconds) || uploadTimeoutSeconds <= 0)
+        throw new CliError("invalid_request", "--upload-timeout must be a positive number of seconds");
+    // Checked before createRun on purpose: failing afterwards would leave the Run
+    // created but never waited on, and the finally block does not cancel it — an
+    // orphan Run holding a device.
+    const waitTimeoutSeconds = Number(options.waitTimeout);
+    if (!Number.isFinite(waitTimeoutSeconds) || waitTimeoutSeconds < 0)
+        throw new CliError("invalid_request", "--wait-timeout must be a non-negative number of seconds");
+    // `runs wait` already exposed this; `run --wait` had it hardcoded to 2, so the
+    // same polling behavior had two different parameter surfaces.
+    const pollIntervalSeconds = Number(options.pollInterval);
+    if (!Number.isFinite(pollIntervalSeconds) || pollIntervalSeconds <= 0)
+        throw new CliError("invalid_request", "--poll-interval must be a positive number of seconds");
+    // One definition for "was a key supplied, and does it carry anything": the
+    // personal branch tested the raw value while the project_ci branch tested the
+    // trimmed one, so `--idempotency-key ""` slipped past the first check.
+    const suppliedIdempotencyKey = options.idempotencyKey === undefined ? undefined : String(options.idempotencyKey).trim();
+    if (options.idempotencyKey !== undefined && !suppliedIdempotencyKey)
+        throw new CliError("invalid_request", "--idempotency-key must not be blank");
     const hasInstall = script.steps.some((step) => step.action === "install");
     if (packageId === undefined && !options.appUploadId && !options.apk && hasInstall)
         throw new CliError("invalid_request", "package_id or --app-upload-id is required when the script contains install");
@@ -413,24 +505,24 @@ program.command("run")
             throw new CliError("invalid_request", "--apk requires an APK file");
         if (!options.deviceId)
             throw new CliError("invalid_request", "--device-id is required for a personal Profile");
-        if (options.idempotencyKey)
+        if (suppliedIdempotencyKey)
             throw new CliError("invalid_request", "--idempotency-key is only valid for a project_ci Profile");
-        request = { schema_version: "xagent-run-create/v1", script, device_id: options.deviceId, timeout_ms: Number(options.timeoutMs), source_hash: parsed.sourceHash };
+        request = { schema_version: "xagent-run-create/v1", script, device_id: options.deviceId, timeout_ms: timeoutMs, source_hash: parsed.sourceHash };
     }
     else {
         if (options.apk)
             throw new CliError("token_type_mismatch", "project_ci Profile must use apps upload and --app-upload-id", 3);
         if (options.deviceId)
             throw new CliError("token_type_mismatch", "project_ci Profile cannot use --device-id", 3);
-        if (!String(options.idempotencyKey ?? "").trim())
+        if (!suppliedIdempotencyKey)
             throw new CliError("invalid_request", "--idempotency-key is required for a project_ci Run");
         const target = (await loadProjectConfig(ctx.projectConfig)).resolveTarget(options.target);
-        request = { schema_version: "xagent-run-create/v2", script, target_name: target.name, target_hash: target.targetHash, target: target.definition, timeout_ms: Number(options.timeoutMs), source_hash: parsed.sourceHash };
+        request = { schema_version: "xagent-run-create/v2", script, target_name: target.name, target_hash: target.targetHash, target: target.definition, timeout_ms: timeoutMs, source_hash: parsed.sourceHash };
     }
     const variables = parseVariables(options.var ?? []);
     if (Object.keys(variables).length)
         request.variables = variables;
-    const { client } = await authenticatedClient(ctx, Number(options.uploadTimeout) * 1000);
+    const { client } = await authenticatedClient(ctx, uploadTimeoutSeconds * 1000);
     let uploadedId;
     let primaryError;
     let run;
@@ -438,7 +530,10 @@ program.command("run")
     // and a Run occupying a device allocated until each expires on its own.
     let createdRunId;
     const waiting = new AbortController();
-    const releaseOnInterrupt = onInterrupt(async () => {
+    // `onInterrupt()` registers a cleanup and hands back its deregistration
+    // function, so this is "detach", not "release" — calling it does not release
+    // anything on its own.
+    const detachInterruptHandler = onInterrupt(async () => {
         // Stop the poll loop first so it cannot keep issuing requests while we release.
         waiting.abort();
         // Both releases are independent: a failed cancel must not skip the APK release.
@@ -472,10 +567,10 @@ program.command("run")
             request.package_id = Number(packageId);
         if (options.appUploadId)
             request.app_upload_id = options.appUploadId;
-        run = await client.createRun(request, options.idempotencyKey?.trim());
+        run = await client.createRun(request, suppliedIdempotencyKey);
         createdRunId = String(run.id ?? "") || undefined;
         if (options.wait) {
-            run = await client.waitRun(run.id, Number(options.waitTimeout), 2, progressReporter(ctx), waiting.signal);
+            run = await client.waitRun(run.id, waitTimeoutSeconds, pollIntervalSeconds, progressReporter(ctx), waiting.signal);
             createdRunId = undefined; // reached a terminal state, nothing left to cancel
         }
     }
@@ -496,7 +591,7 @@ program.command("run")
                     throw error;
             }
         }
-        releaseOnInterrupt();
+        detachInterruptHandler();
     }
     emitRun(ctx, run);
 });
@@ -507,10 +602,27 @@ runs.command("cancel").argument("<runId>").action(async function (runId) { const
 program.command("mcp").option("--mode <mode>", `Isolated Tool surface: ${MCP_MODES.join(", ")}`, "action").action(async function (options) { const ctx = context(this); if (!MCP_MODES.includes(options.mode))
     throw new CliError("invalid_request", `mcp --mode must be one of: ${MCP_MODES.join(", ")}`); await runStdioServer(ctx.profile, ctx.userConfig, undefined, options.mode); });
 export async function runCli(argv = process.argv) {
+    parsedArgv = argv;
+    parsedJsonMode = undefined;
+    // When the caller asked for JSON, commander must not write its own human text to
+    // stderr — the structured error below is the whole contract. `--json` is a global
+    // option, so the argv being parsed is the single source for this decision.
+    program.configureOutput({ writeErr: argv.includes("--json") ? () => { } : (text) => process.stderr.write(text) });
     try {
         await program.parseAsync(argv);
     }
     catch (error) {
+        if (error instanceof CommanderError) {
+            // `--help` already printed to stdout; keep the conventional success code.
+            if (error.exitCode === 0)
+                return;
+            const known = new CliError("invalid_request", error.message, 2);
+            // Human mode: commander has already explained the problem on stderr (plus the
+            // usage block from showHelpAfterError), so do not repeat it through fail().
+            if (jsonOutputRequested())
+                fail(known);
+            process.exit(API_EXIT[known.code]);
+        }
         fail(error);
     }
 }