tripo-cli 0.5.1 → 0.5.2

package/README.md

@@ -91,7 +91,7 @@ tripo batch run assets.yaml --concurrency 2
 
 - `make`/`watch` are blocking: run them, wait for exit, read the single JSON line on stdout. Do not poll yourself.
 - The plan card on stderr lists every call before it runs; the final JSON carries `credits_consumed` (total for the run) plus `credits_breakdown` (per task) when a chain ran.
-- Exit codes: `0` ok · `2` usage · `3` auth · `4` insufficient credits · `5` content policy · `6` task failed (credits auto-refunded) · `7` network · `8` not found · `9` rate limit.
+- Exit codes: `0` ok · `2` usage · `3` auth · `4` insufficient credits · `5` content policy · `6` task failed (credits auto-refunded; a `timeout` means it is still running) · `7` network (a failed submit is never resent — check `tripo balance` before re-running) · `8` not found · `9` rate limit.
 - `preview.png` in every output directory is your eyes: look at it, then decide to `tripo redo` or continue the chain.
 - Full behavior rules: `tripo docs --llm`, per-command docs via `tripo docs --topic commands/make`.
 

package/dist/core/client.js

@@ -1,10 +1,12 @@
 /**
  * Lightweight V3 API client on top of global fetch (Node 20+).
  * Handles the response envelope, error translation, timeouts, and
- * exponential-backoff retries for transient failures (429/5xx/network).
+ * exponential-backoff retries for transient failures (429/5xx/network;
+ * task creation is only resent on 429).
  */
 import { activeProfileName, DEFAULT_PROFILE, listProfiles, loadConfig, resolveApiBaseUrl, resolveApiKey } from '../config/config.js';
 import { t } from '../i18n.js';
+import { EXIT } from '../knowledge/error-catalog.js';
 import { ApiError, AuthError, NetworkError } from './errors.js';
 export class TripoClient {
     baseUrl;
@@ -37,10 +39,11 @@ export class TripoClient {
         this.maxRetries = options.maxRetries ?? 3;
         this.onRetry = options.onRetry;
     }
-    async request(method, path, body) {
+    async request(method, path, body, options = {}) {
         return this.send(method, path, {
             headers: { 'Content-Type': 'application/json' },
             body: body === undefined ? undefined : JSON.stringify(body),
+            idempotent: options.idempotent,
         });
     }
     async uploadFile(fileName, data) {
@@ -61,7 +64,11 @@ export class TripoClient {
             }
             catch (err) {
                 lastError = err;
-                const retryable = err instanceof NetworkError || (err instanceof ApiError && err.retryable);
+                // A create that timed out or hit a 5xx may already be accepted (and
+                // billed); only a rate-limit rejection proves the server did nothing.
+                const retryable = init.idempotent === false
+                    ? err instanceof ApiError && err.exitCode === EXIT.RATE_LIMIT
+                    : err instanceof NetworkError || (err instanceof ApiError && err.retryable);
                 if (!retryable || attempt === this.maxRetries)
                     throw err;
             }
@@ -134,8 +141,19 @@ export class TripoClient {
     }
     /** Create a task; returns its id. Response may be {task_id} or a full detail. */
     async createTask(endpoint, payload) {
-        const data = await this.request('POST', endpoint, payload);
-        return data.task_id;
+        try {
+            const data = await this.request('POST', endpoint, payload, { idempotent: false });
+            return data.task_id;
+        }
+        catch (err) {
+            if (err instanceof NetworkError || (err instanceof ApiError && err.exitCode === EXIT.NETWORK)) {
+                err.suggestion = t({
+                    zh: '任务可能已在服务端创建并冻结积分;重试前先用 tripo balance 查看冻结额或到控制台确认,避免重复扣费',
+                    en: 'the task may already exist server-side (credits frozen); check "tripo balance" or the console before retrying, to avoid a duplicate charge',
+                });
+            }
+            throw err;
+        }
     }
 }
 export function sleep(ms) {

package/dist/core/errors.js

@@ -45,13 +45,17 @@ export class NetworkError extends CliError {
 }
 export class TaskFailedError extends CliError {
     taskId;
+    status;
     constructor(taskId, status, detail) {
         const refundNote = t({
             zh: '预扣积分已自动退还',
             en: 'frozen credits have been refunded automatically',
         });
-        super(`task ${taskId} ${status}${detail ? `: ${detail}` : ''} (${refundNote})`, EXIT.TASK_FAILED);
+        super(
+        // A timed-out task is still running server-side: nothing has been refunded.
+        `task ${taskId} ${status}${detail ? `: ${detail}` : ''}${status === 'timeout' ? '' : ` (${refundNote})`}`, EXIT.TASK_FAILED);
         this.taskId = taskId;
+        this.status = status;
     }
 }
 /** Decorate insufficient-balance errors with the topup path and the gap. */

package/dist/core/task-service.js

@@ -13,7 +13,7 @@ import { detectInput } from '../util/input-detect.js';
 import { notifyDone } from '../util/notify.js';
 import { createSpinner } from '../util/spinner.js';
 import { defaultOutputDir, downloadArtifacts } from './download.js';
-import { ApiError, UsageError, balanceSuggestion } from './errors.js';
+import { ApiError, CliError, TaskFailedError, UsageError, balanceSuggestion } from './errors.js';
 import { isQuiet, log, warn } from './output.js';
 import { uploadLocalFile } from './upload.js';
 /** Placeholder `input` value for a local file that a dry run would upload. */
@@ -115,7 +115,15 @@ export async function runTask(options) {
     }
     catch (err) {
         spinner.fail(`${taskType} · ${taskId}`);
-        updateHistoryStatus(taskId, 'failed');
+        if (err instanceof TaskFailedError && err.status !== 'timeout') {
+            updateHistoryStatus(taskId, 'failed');
+        }
+        else if (err instanceof CliError) {
+            err.suggestion = t({
+                zh: `任务仍在服务端运行,成功后照常扣费;用 tripo task watch ${taskId} --download 继续等待,不要重新提交`,
+                en: `the task keeps running server-side and is billed if it succeeds; resume with "tripo task watch ${taskId} --download" instead of resubmitting`,
+            });
+        }
         throw err;
     }
     updateHistoryStatus(taskId, 'success', { credits_consumed: task.credits_consumed });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tripo-cli",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Tripo 3D intelligent CLI — turn a prompt or an image into engine-ready 3D assets from your terminal (Tripo V3 API)",
   "keywords": [
     "tripo",

package/skill/SKILL.md

@@ -34,7 +34,7 @@ Regions (ov = international, cn = China mainland) share one CLI: `tripo login --
 2. **stdout is the contract; stderr is commentary.** With `--json` (auto-enabled when piped), stdout carries exactly one final JSON line. Progress/logs go to stderr.
 3. **Artifacts are local files.** The result JSON has `output_dir`, `model_file`, `preview`. Look at `preview.png` to judge quality; re-roll with `tripo redo` if needed.
 4. **Exit codes are stable** — branch on them:
-   - 0 success · 2 usage/params · 3 auth · 4 insufficient credits (tell the human to run `tripo topup`) · 5 content policy · 6 task failed (credits auto-refunded) · 7 network · 8 not found · 9 rate limit (retry with backoff)
+   - 0 success · 2 usage/params · 3 auth · 4 insufficient credits (tell the human to run `tripo topup`) · 5 content policy · 6 task failed (credits auto-refunded; on `timeout` it is still running — `tripo task watch <id>`, never redo) · 7 network (a failed submit is never resent and may already exist — check `tripo balance` before re-running) · 8 not found · 9 rate limit (retry with backoff)
 5. **Never invent parameters.** Unknown `--param key=value` pairs pass through to the API; stick to documented ones. The full parameter/model/preset reference from the official API docs is bundled: `tripo docs --topic commands/generate` (3D + image generation) and `tripo docs --topic commands/process` (texture/convert/rig/retarget/mesh) — read those instead of browsing the website.
 6. **Validate before spending: `--dry-run --json`.** Same command plus `--dry-run` prints the plan as JSON with zero network calls and no credits: the chosen `model`, the completed `steps[].payload` for every API call, `warnings` (auto-adjustments) and `errors` (blocking; exit 2). When `valid` is true, re-run without `--dry-run`. Details: `tripo docs --topic commands/make` § "Dry run".
 7. **Don't pick legacy model versions.** The CLI auto-selects `tripo-v3.1` (high fidelity) or `tripo-p1` (low-poly, face budget ≤ 20000). Only override `--model` when the human asks (e.g. `--model tripo-p2` for the P-series **Preview** with quad support, or `tripo-v3.0` / `tripo-v2.5` for reproducing old projects). `tripo-*` names are CLI aliases — the CLI sends the dated wire value (`tripo-p2` → `P2-20260801`); the API rejects the alias itself with 1004. Alias ↔ wire ↔ status table: `tripo docs --topic commands/generate` ("Models & Versions").

package/skill/commands/task.md

@@ -12,7 +12,7 @@ tripo task get @last --download --json
 
 Block until the task finishes. In `--json` mode, progress streams as NDJSON events on stdout (`{"event":"progress",...}` lines) and the final task detail is the last line. `--download` grabs artifacts on success. `--timeout <seconds>` (default 1800).
 
-Rules for agents: treat `watch` as synchronous; read lines until process exit; exit code 6 means the task failed (credits refunded).
+Rules for agents: treat `watch` as synchronous; read lines until process exit; exit code 6 means the task failed (credits refunded) — or, if the error says `timeout`, that it is still running (watch it again; do not resubmit).
 
 ## tripo task list [ids...]
 

package/skill/common-errors.md

@@ -19,9 +19,9 @@
 | 2 | 2018 | too complex to remesh | lower `face_limit` or simplify the input model |
 | 8 | 2019 | file not found (token expired?) | re-upload; file tokens are short-lived |
 | 2 | 2020/2021/2022 | bad image URL / file too large / image too large | fix the URL or shrink the file |
-| 7 | 1000/1001 | server-side error | 1000 auto-retries; if persistent, contact support with the `request_id` |
-| 6 | — | task failed server-side | frozen credits auto-refund; `tripo redo` often succeeds with a new seed |
-| 7 | — | network/5xx | auto-retried 3×; check `tripo doctor`; region mismatch (ov/cn) is a common cause |
+| 7 | 1000/1001 | server-side error | queries auto-retry on 1000, task creation does not (the task may already exist and be billed — check `tripo balance` frozen credits before re-running); if persistent, contact support with the `request_id` |
+| 6 | — | task failed server-side, or the watch timed out | failed: frozen credits auto-refund; `tripo redo` often succeeds with a new seed. `timeout`: the task is still running and is billed if it succeeds — `tripo task watch <id> --download`, never redo |
+| 7 | — | network/5xx | queries auto-retried 3×, task creation is not (follow the `suggestion`: check `tripo balance` before re-running); check `tripo doctor`; region mismatch (ov/cn) is a common cause |
 
 ## Concurrency pools (default per account; error 2000 when full)