tripo-cli 0.7.2 → 0.7.3

package/dist/core/analytics.js

@@ -10,10 +10,12 @@ export const ANALYTICS_APP_ID = "2908364badd34996a1cd44a5f7a71223";
 const operations = new AsyncLocalStorage();
 let activeOperation;
 let installationId;
+/** Account lookups held only in this process's memory: at most one per key per CLI command or MCP session. */
+const identities = new Map();
 const currentOperation = () => operations.getStore() ?? activeOperation;
 export function beginOperation(command, disabled = false, info, regionHint) {
     activeOperation = { command, started: Date.now(), disabled, finished: false, collectors: new Map(), regionHint, context: {
-            ...attribution(process.env.TRIPO_CLIENT_APP, process.env.TRIPO_DISTRIBUTION_CHANNEL, info),
+            ...attribution(process.env.TRIPO_CLIENT_APP, process.env.TRIPO_DISTRIBUTION_CHANNEL, info, undefined, hostClientApp()),
             distinctId: randomUUID(), operation_id: randomUUID(), integration_mode: info ? "local_mcp" : "cli",
         } };
     operations.enterWith(activeOperation);
@@ -27,8 +29,15 @@ export function identifyUser(apiKey, region, apiUrl) {
         return;
     const consoleApi = process.env.TRIPO_CONSOLE_API_BASE_URL ?? REGION_DEFAULTS[region].consoleApi;
     const key = createHash('sha256').update(JSON.stringify([region, apiUrl, consoleApi, apiKey])).digest('hex');
-    if (operation.identity?.key !== key)
-        operation.identity = { key, value: analytics.identify(apiKey, consoleApi) };
+    if (operation.identity?.key === key)
+        return;
+    let value = identities.get(key);
+    if (!value) {
+        // A CLI command ends its lookup when it finishes; an MCP session lets it outlive the tool call, for at most 10 s.
+        const signal = operation.context.integration_mode === 'local_mcp' ? AbortSignal.timeout(10_000) : (operation.lookups ??= new AbortController()).signal;
+        identities.set(key, value = analytics.identify(apiKey, consoleApi, signal));
+    }
+    operation.identity = { key, value };
 }
 function collector(region = currentOperation()?.regionHint ?? resolveRegion(), apiUrl = resolveApiBaseUrl()) {
     const operation = currentOperation();
@@ -95,6 +104,7 @@ export async function finishOperation(result, error) {
         ...(operation.context.integration_mode === 'local_mcp' ? { tool_name: operation.command } : {}),
         result, duration_ms: Date.now() - operation.started, ...(error ? errorProperties(error) : {}) });
     await flushAnalytics();
+    operation.lookups?.abort();
 }
 export function taskOrigin(model) {
     const context = analyticsContext();
@@ -136,23 +146,35 @@ export function clientApp(value) {
     if (typeof value !== "string")
         return "unknown";
     const name = value.trim().toLowerCase();
-    for (const app of ["codex", "workbuddy", "zcode", "kimi", "deepseek"]) {
-        if (new RegExp(`(^|[\\s_./-])${app}($|[\\s_./-])`).test(name))
-            return app;
-    }
-    return "unknown";
+    if (name === "dsh")
+        return "deepseek";
+    const matches = ["codex", "workbuddy", "zcode", "kimi", "deepseek", "claude", "cursor", "chatgpt"]
+        .filter((app) => new RegExp(`(^|[\\s_./():-])${app}($|[\\s_./():-])`).test(name));
+    return matches.length === 1 ? matches[0] : "unknown";
+}
+function hostClientApp() {
+    // Session markers identify the caller; install paths and terminal names do not.
+    const hosts = [];
+    if (process.env.CODEX_THREAD_ID?.trim())
+        hosts.push("codex");
+    if (process.env.ZCODE_SESSION_ID?.trim())
+        hosts.push("zcode");
+    if (process.env.CODEBUDDY_HOST === "workbuddy-desktop")
+        hosts.push("workbuddy");
+    return hosts.length === 1 ? hosts[0] : "unknown";
 }
-export function attribution(explicit, distribution, info, oauthName) {
+export function attribution(explicit, distribution, info, oauthName, hostName) {
     const tagged = clientApp(explicit);
     const initialized = clientApp(info?.name);
     const oauth = clientApp(oauthName);
-    const chosen = tagged !== "unknown" ? tagged : initialized !== "unknown" ? initialized : oauth;
+    const host = clientApp(hostName);
+    const chosen = tagged !== "unknown" ? tagged : initialized !== "unknown" ? initialized : oauth !== "unknown" ? oauth : host;
     const channels = ["codex_plugin", "workbuddy_plugin", "zcode_plugin", "kimi_plugin", "deepseek_plugin"];
     return {
         client_app: chosen,
         distribution_channel: typeof distribution === "string" && channels.includes(distribution) ? distribution : "unknown",
-        attribution_method: tagged !== "unknown" ? "explicit_tag" : initialized !== "unknown" ? "mcp_client_info" : oauth !== "unknown" ? "oauth_client_name" : "unknown",
-        attribution_conflict: [tagged, initialized, oauth].some((app) => app !== "unknown" && chosen !== app),
+        attribution_method: tagged !== "unknown" ? "explicit_tag" : initialized !== "unknown" ? "mcp_client_info" : oauth !== "unknown" ? "oauth_client_name" : host !== "unknown" ? "host_environment" : "unknown",
+        attribution_conflict: [tagged, initialized, oauth, host].some((app) => app !== "unknown" && chosen !== app),
         ...(typeof info?.version === "string" && /^[a-zA-Z0-9._+-]{1,64}$/.test(info.version) && !/tsk_|bearer|token/i.test(info.version) ? { client_version: info.version } : {}),
     };
 }
@@ -202,7 +224,7 @@ export class Analytics {
             && (testing ? env.TRIPO_ANALYTICS_ENABLED === "1" && testReceiver : officialApi || testReceiver);
         this.identityEnabled = this.enabled && (testing ? localApi : officialApi);
     }
-    async identify(apiKey, consoleApi) {
+    async identify(apiKey, consoleApi, signal = AbortSignal.timeout(1000)) {
         if (!this.identityEnabled)
             return undefined;
         try {
@@ -214,7 +236,7 @@ export class Analytics {
             const response = await fetch(url, {
                 method: "POST", headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({ apikey: apiKey, with_detail: true }),
-                redirect: "error", signal: AbortSignal.timeout(1000),
+                redirect: "error", signal,
             });
             if (!response.ok)
                 return undefined;
@@ -268,9 +290,10 @@ export class Analytics {
             const deadline = Date.now() + 2000;
             while (this.queue.length && Date.now() < deadline) {
                 const batch = this.queue.splice(0, 100);
-                // Each lookup began before its event and gives up after 1 s, so this wait leaves the send at least 1 s of the budget.
+                // A lookup may outlive its events, so wait at most 1 s for it; that leaves the send at least 1 s of the budget.
+                const wait = new Promise((resolve) => setTimeout(() => resolve(undefined), 1000).unref());
                 await Promise.all(batch.map(async ({ event, identity }) => {
-                    const userId = await identity;
+                    const userId = await Promise.race([identity, wait]);
                     if (userId)
                         event.data.properties.platform_user_id = userId;
                 }));

package/dist/core/client.js

@@ -2,7 +2,8 @@
  * 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;
- * task creation is only resent on 429).
+ * task creation is only resent on 429). A 429 waits at least as long as the
+ * server's Retry-After / X-RateLimit-Reset hint, capped at 60s per wait.
  */
 import { activeProfileName, DEFAULT_PROFILE, listProfiles, loadConfig, resolveApiBaseUrl, resolveApiKey } from '../config/config.js';
 import { t } from '../i18n.js';
@@ -54,12 +55,35 @@ export class TripoClient {
         form.append('file', data, fileName);
         return this.send('POST', '/v3/files', { body: form });
     }
+    /**
+     * Large-file upload: presign, then PUT straight to storage. The PUT carries
+     * no Authorization header and no request timeout (files up to 150MB).
+     */
+    async uploadFileViaPresign(format, data) {
+        const { presigned_url, file_token } = await this.request('POST', '/v3/files/presign', { format });
+        let response;
+        try {
+            response = await fetch(presigned_url, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/octet-stream' },
+                body: data,
+            });
+        }
+        catch (err) {
+            throw new NetworkError(`presigned upload failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!response.ok)
+            throw new NetworkError(`presigned upload failed: HTTP ${response.status}`);
+        return { file_token };
+    }
     async send(method, path, init) {
         identifyUser(this.apiKey, this.region, this.baseUrl);
         let lastError;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
             if (attempt > 0) {
-                const delay = Math.min(1000 * 2 ** (attempt - 1), 8000);
+                const backoff = Math.min(1000 * 2 ** (attempt - 1), 8000);
+                const hint = lastError instanceof ApiError ? (lastError.retryAfterMs ?? 0) : 0;
+                const delay = Math.min(Math.max(backoff, hint), 60_000);
                 this.onRetry?.(attempt, delay, lastError?.message ?? 'retry');
                 await sleep(delay);
             }
@@ -99,13 +123,14 @@ export class TripoClient {
         finally {
             clearTimeout(timer);
         }
+        const retryAfterMs = response.status === 429 ? retryHintMs(response.headers) : undefined;
         let envelope;
         try {
             envelope = (await response.json());
         }
         catch {
             if (!response.ok) {
-                throw new ApiError({ httpStatus: response.status, message: `HTTP ${response.status} with non-JSON body` });
+                throw new ApiError({ httpStatus: response.status, message: `HTTP ${response.status} with non-JSON body`, retryAfterMs });
             }
             throw new NetworkError(`invalid JSON response from ${path}`);
         }
@@ -116,6 +141,7 @@ export class TripoClient {
                 message: envelope.message,
                 suggestion: envelope.suggestion,
                 requestId: envelope.request_id,
+                retryAfterMs,
             });
         }
         return envelope.data;
@@ -128,18 +154,23 @@ export class TripoClient {
         return task;
     }
     /**
-     * Batch task query. The server returns `{tasks: {id: detail}, missed: [id]}`
-     * (NOT an array — the public docs are wrong here; verified against production).
+     * Batch task query, at most 100 ids per request. The server returns
+     * `{tasks: {id: detail}, missed: [id]}`.
      */
     async listTasks(taskIds) {
-        const data = await this.request('POST', '/v3/tasks/list', { task_ids: taskIds });
-        const byId = data.tasks ?? {};
+        const byId = {};
+        const missed = [];
+        for (let i = 0; i < taskIds.length; i += 100) {
+            const data = await this.request('POST', '/v3/tasks/list', { task_ids: taskIds.slice(i, i + 100) });
+            Object.assign(byId, data.tasks ?? {});
+            missed.push(...(data.missed ?? []));
+        }
         for (const [id, task] of Object.entries(byId))
             observeTask({ ...task, task_id: task.task_id ?? id }, this.region, this.baseUrl);
         const tasks = taskIds
             .filter((id) => byId[id])
             .map((id) => ({ ...byId[id], task_id: byId[id].task_id ?? id }));
-        return { tasks, missed: data.missed ?? [] };
+        return { tasks, missed };
     }
     getBalance() {
         return this.request('GET', '/v3/account/balance');
@@ -169,3 +200,13 @@ export class TripoClient {
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/** Retry-After is in seconds; X-RateLimit-Reset is a unix timestamp in seconds. */
+function retryHintMs(headers) {
+    const after = Number(headers.get('retry-after') ?? NaN);
+    if (Number.isFinite(after))
+        return after * 1000;
+    const reset = Number(headers.get('x-ratelimit-reset') ?? NaN);
+    if (Number.isFinite(reset))
+        return Math.max(reset * 1000 - Date.now(), 0);
+    return undefined;
+}

package/dist/core/device-auth.js

@@ -8,7 +8,7 @@
  * /cli/device endpoints 404 and the caller falls back to paste login.
  */
 import { randomBytes } from 'node:crypto';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { join } from 'node:path';
 import { REGION_DEFAULTS, tripoHome } from '../config/config.js';
@@ -148,6 +148,54 @@ export async function waitForDeviceApproval(region, grant, onTick) {
     trackEvent('agent_auth_result', { result: 'expired', auth_method: 'device' }, region, REGION_DEFAULTS[region].api);
     return { status: 'expired' };
 }
+/** A single poll without waiting; slow_down only means "asked too soon", so it reads as pending. */
+export async function checkDeviceApproval(region, grant) {
+    const poll = await pollDeviceToken(region, grant.device_code);
+    if (poll.status === 'pending' || poll.status === 'slow_down')
+        return { status: 'pending' };
+    trackEvent('agent_auth_result', { result: poll.status === 'approved' ? 'success' : poll.status, auth_method: 'device' }, region, REGION_DEFAULTS[region].api);
+    return poll;
+}
+/**
+ * A headless login must outlive its process: a chat agent can only relay the
+ * code by ending its turn, and its shell may be killed or suspended before the
+ * human approves. The grant is parked here (0600, removed once redeemed,
+ * denied, or expired) so the next `tripo login` resumes the code the human
+ * already has. device_code redeems the key — it never goes to stdout or logs.
+ */
+function pendingGrantFile() {
+    return join(tripoHome(), 'pending-login.json');
+}
+export function savePendingGrant(region, profile, grant) {
+    mkdirSync(tripoHome(), { recursive: true, mode: 0o700 });
+    const file = pendingGrantFile();
+    writeFileSync(file, JSON.stringify({ region, profile, expires_at: Date.now() + grant.expires_in * 1000, grant }) + '\n', { mode: 0o600 });
+    chmodSync(file, 0o600);
+}
+/** The parked grant for this region + profile, with its remaining lifetime as expires_in. */
+export function loadPendingGrant(region, profile) {
+    let saved;
+    try {
+        saved = JSON.parse(readFileSync(pendingGrantFile(), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const left = Math.floor(((saved.expires_at ?? 0) - Date.now()) / 1000);
+    if (left <= 0 || typeof saved.grant?.device_code !== 'string') {
+        clearPendingGrant();
+        return undefined;
+    }
+    if (saved.region !== region || saved.profile !== profile)
+        return undefined;
+    return { ...saved.grant, expires_in: left };
+}
+export function clearPendingGrant() {
+    try {
+        unlinkSync(pendingGrantFile());
+    }
+    catch { }
+}
 /**
  * POST JSON and return the response envelope regardless of HTTP status —
  * device-auth errors (4290/4291/4292) arrive as HTTP 400/429 with a JSON

package/dist/core/download.js

@@ -11,7 +11,7 @@ import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { NetworkError } from './errors.js';
 import { trackEvent, errorProperties } from './analytics.js';
-const MODEL_EXTS = new Set(['.glb', '.gltf', '.fbx', '.obj', '.stl', '.3mf', '.usdz', '.zip', '.ply']);
+const MODEL_EXTS = new Set(['.glb', '.gltf', '.fbx', '.obj', '.stl', '.3mf', '.usdz', '.zip', '.ply', '.splat']);
 const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
 /** Collect every downloadable URL in the output map (string or {url} object). */
 export function collectOutputUrls(output) {
@@ -97,6 +97,7 @@ export async function downloadArtifacts(task, outputDir, historyEntry, options =
             status: task.status,
             input: task.input ?? historyEntry?.payload ?? {},
             output_fields: urls.map((u) => u.field),
+            normalize_scale: task.output?.normalize_scale,
             credits_consumed: task.credits_consumed,
             created_at: task.created_at,
             completed_at: task.completed_at,

package/dist/core/errors.js

@@ -25,8 +25,12 @@ export class ApiError extends CliError {
     httpStatus;
     requestId;
     retryable;
+    /** Server wait hint on 429 (Retry-After / X-RateLimit-Reset). */
+    retryAfterMs;
     constructor(opts) {
-        const info = opts.apiCode !== undefined ? lookupError(opts.apiCode) : undefined;
+        // HTTP 401 reads as an auth failure whatever code the body carries (see error-catalog).
+        const code = opts.httpStatus === 401 ? 1002 : opts.apiCode;
+        const info = code !== undefined ? lookupError(code) : undefined;
         const translated = info ? t(info) : undefined;
         const parts = [translated ?? opts.message ?? `API error (HTTP ${opts.httpStatus})`];
         if (translated && opts.message && opts.message !== translated)
@@ -36,6 +40,7 @@ export class ApiError extends CliError {
         this.httpStatus = opts.httpStatus;
         this.requestId = opts.requestId;
         this.retryable = isRetryable(opts.apiCode, opts.httpStatus);
+        this.retryAfterMs = opts.retryAfterMs;
     }
 }
 export class NetworkError extends CliError {
@@ -52,8 +57,8 @@ export class TaskFailedError extends CliError {
             en: 'frozen credits have been refunded automatically',
         });
         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);
+        // Only failed/cancelled tasks are refunded; a timed-out task is still running server-side.
+        `task ${taskId} ${status}${detail ? `: ${detail}` : ''}${status === 'failed' || status === 'cancelled' ? ` (${refundNote})` : ''}`, EXIT.TASK_FAILED);
         this.taskId = taskId;
         this.status = status;
     }

package/dist/core/requests.js

@@ -5,7 +5,7 @@
  * `parameters`), so new API options work without a CLI release.
  */
 import { getStep } from '../knowledge/chains.js';
-import { validateConvertParams, validateDecimateParams, validateGenerationParams, validateMeshEditParams, validateRetargetParams, } from '../knowledge/params.js';
+import { applyTextureV35, validateConvertParams, validateDecimateParams, validateGenerationParams, validateMeshEditParams, validateRetargetParams, } from '../knowledge/params.js';
 import { CAPABILITY_DEFAULTS, SEGMENT_MODELS, TEXTURE_MODELS, normalizeModel, normalizeRigModel, } from '../knowledge/models.js';
 import { UsageError } from './errors.js';
 function ensure(result) {
@@ -39,17 +39,26 @@ export function buildImageToModel(input, model, params) {
         warnings: validated.warnings,
     };
 }
-/** 3D generation: multiview-to-model. Views ordered [front, left, back, right]. */
+/**
+ * 3D generation: multiview-to-model. Views ordered [front, left, back, right],
+ * or `{task_id}` of an image-to-multiview / edit-multiview task to reuse its 4 views.
+ */
 export function buildMultiviewToModel(views, model, params) {
     const validated = validateGenerationParams(model, params);
     ensure(validated);
-    const inputs = ['front', 'left', 'back', 'right']
-        .filter((v) => views[v])
-        .map((v) => ({ [v]: views[v] }));
-    if (!views.front)
-        throw new UsageError('multiview requires a front view');
-    if (inputs.length < 2)
-        throw new UsageError('multiview requires at least 2 views');
+    let inputs;
+    if ('task_id' in views) {
+        inputs = [{ task_id: views.task_id }];
+    }
+    else {
+        inputs = ['front', 'left', 'back', 'right']
+            .filter((v) => views[v])
+            .map((v) => ({ [v]: views[v] }));
+        if (!views.front)
+            throw new UsageError('multiview requires a front view');
+        if (inputs.length < 2)
+            throw new UsageError('multiview requires at least 2 views');
+    }
     return {
         request: {
             endpoint: '/v3/generation/multiview-to-model',
@@ -72,11 +81,16 @@ export function buildTextToImage(prompt, params) {
         warnings: [],
     };
 }
-export function buildImageToImage(input, params) {
+/** One reference image goes as `input`, several as `inputs` (prompt cites them as image[1], image[2], ...). */
+export function buildImageToImage(inputs, params) {
     return {
         request: {
             endpoint: '/v3/generation/image-to-image',
-            payload: { input, model: params.model ?? CAPABILITY_DEFAULTS.imageToImage, ...omit(params, ['model']) },
+            payload: {
+                ...(inputs.length > 1 ? { inputs } : { input: inputs[0] }),
+                model: params.model ?? CAPABILITY_DEFAULTS.imageToImage,
+                ...omit(params, ['model']),
+            },
         },
         taskType: 'generate_image',
         warnings: [],
@@ -150,13 +164,18 @@ export function buildStepRequest(stepName, input, args) {
             break;
         }
         case 'texture': {
-            const model = params.model === undefined
-                ? CAPABILITY_DEFAULTS.texture
-                : normalizeModel(String(params.model));
-            if (!TEXTURE_MODELS.includes(model)) {
-                throw new UsageError(`texture model must be one of ${TEXTURE_MODELS.join('/')} (got "${String(params.model)}")`);
+            if (params.model !== undefined) {
+                const model = normalizeModel(String(params.model));
+                if (!TEXTURE_MODELS.includes(model)) {
+                    throw new UsageError(`texture model must be one of ${TEXTURE_MODELS.join('/')} (got "${String(params.model)}")`);
+                }
+                params.model = model;
             }
-            params.model = model;
+            const errors = [];
+            applyTextureV35(params, 'model', warnings, errors);
+            ensure({ params, warnings, errors });
+            if (params.model === undefined)
+                params.model = CAPABILITY_DEFAULTS.texture;
             break;
         }
         case 'segment': {

package/dist/core/task-service.js

@@ -139,6 +139,8 @@ export async function runTask(options) {
         status: task.status,
         credits_consumed: task.credits_consumed,
     };
+    if (typeof task.output?.normalize_scale === 'number')
+        result.normalize_scale = task.output.normalize_scale;
     if (!options.noDownload) {
         const baseDir = options.outDir ?? loadContext().output_dir ?? process.cwd();
         const dir = defaultOutputDir(baseDir, name, taskId);

package/dist/core/upload.js

@@ -5,6 +5,8 @@ import { UsageError } from './errors.js';
 import { IMAGE_EXTS, MODEL_EXTS } from '../util/input-detect.js';
 const IMAGE_MAX = 20 * 1024 * 1024;
 const MODEL_MAX = 150 * 1024 * 1024;
+/** Above this size the docs recommend the presigned direct upload. */
+const PRESIGN_THRESHOLD = 60 * 1024 * 1024;
 const MIME = {
     '.png': 'image/png',
     '.jpg': 'image/jpeg',
@@ -25,18 +27,34 @@ export async function uploadLocalFile(client, filePath) {
     if (!isImage && !isModel) {
         throw new UsageError(`unsupported file type "${ext}" for upload`);
     }
-    // The server's upload whitelist has no gltf: a .gltf references external
-    // .bin/texture files, so a single-file upload would be incomplete anyway.
-    if (ext === '.gltf') {
-        throw new UsageError('the upload API does not accept .gltf (it references external files) — export as .glb, or host it and pass the URL');
-    }
     const info = await stat(filePath);
     const limit = isImage ? IMAGE_MAX : MODEL_MAX;
     if (info.size > limit) {
         throw new UsageError(`${basename(filePath)} is ${(info.size / 1024 / 1024).toFixed(1)}MB, exceeding the ${limit / 1024 / 1024}MB ${isImage ? 'image' : 'model'} limit`);
     }
     const bytes = await readFile(filePath);
+    // .gltf goes through presign: the multipart whitelist has rejected it, the presign one lists it.
+    if (ext === '.gltf')
+        assertSelfContainedGltf(filePath, bytes);
+    if (ext === '.gltf' || info.size > PRESIGN_THRESHOLD) {
+        const { file_token } = await client.uploadFileViaPresign(ext.slice(1), new Blob([bytes]));
+        return file_token;
+    }
     const blob = new Blob([bytes], { type: MIME[ext] ?? 'application/octet-stream' });
     const { file_token } = await client.uploadFile(basename(filePath), blob);
     return file_token;
 }
+/** A single-file upload cannot carry a .gltf's external .bin/texture files. */
+function assertSelfContainedGltf(filePath, bytes) {
+    let doc;
+    try {
+        doc = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new UsageError(`${basename(filePath)} is not valid glTF JSON`);
+    }
+    const external = [...(doc.buffers ?? []), ...(doc.images ?? [])].some((ref) => typeof ref.uri === 'string' && !ref.uri.startsWith('data:'));
+    if (external) {
+        throw new UsageError(`${basename(filePath)} references external files (.bin/textures) — export as .glb, or host it and pass the URL`);
+    }
+}

package/dist/core/watch.js

@@ -36,6 +36,9 @@ export async function watchTask(client, taskId, options = {}) {
     }
 }
 function extractFailureReason(task) {
+    if (task.error_message) {
+        return task.error_code !== undefined ? `${task.error_message} (code ${task.error_code})` : task.error_message;
+    }
     const out = task.output ?? {};
     const candidate = out.message ?? out.error ?? out.reason;
     return typeof candidate === 'string' ? candidate : undefined;

package/dist/knowledge/chains.js

@@ -22,7 +22,6 @@ export const MODEL_PRODUCING_TYPES = new Set([
     'animate_retarget',
 ]);
 export const STEPS = [
-    { name: 'refine', endpoint: '/v3/models/refine', produces: 'refine_model', accepts: ['text_to_model'], acceptsFile: false, describe: { zh: '精修文生模型的几何细节', en: 'refine geometry of a text-to-model result' } },
     { name: 'texture', endpoint: '/v3/models/texture', produces: 'texture_model', accepts: 'any-model', acceptsFile: true, describe: { zh: '重新生成贴图 / PBR 材质', en: 'regenerate textures / PBR materials' } },
     { name: 'convert', endpoint: '/v3/models/convert', produces: 'convert_model', accepts: 'any-model', acceptsFile: true, describe: { zh: '转换输出格式 / 贴图尺寸 / 朝向', en: 'convert format / texture size / orientation' } },
     { name: 'import', endpoint: '/v3/models/import', produces: 'import_model', accepts: [], acceptsFile: true, describe: { zh: '导入本地模型文件作为加工起点', en: 'import a local model file as the chain source' } },
@@ -47,9 +46,10 @@ for (const s of STEPS) {
         stepIndex.set(a, s);
 }
 /**
- * `/v3/mesh/edit` is documented but not yet deployed (cn returns 4001). The
- * step stays hidden until the backend ships; set TRIPO_EXPERIMENTAL_MESH_EDIT=1
- * to opt in early. Flip this default once the endpoint is live.
+ * `/v3/mesh/edit` has a reference page that is still left out of the docs
+ * index, and cn returned 4001 when last checked. The step stays hidden; set
+ * TRIPO_EXPERIMENTAL_MESH_EDIT=1 to opt in. Flip this default once the
+ * endpoint is listed and live.
  */
 export function isMeshEditEnabled() {
     return process.env.TRIPO_EXPERIMENTAL_MESH_EDIT === '1';
@@ -171,7 +171,6 @@ export function validateChain(chain, sourceType) {
 }
 function hintFor(step) {
     const hints = {
-        refine: ' (refine only accepts a successful text-to-model task)',
         complete: ' (run "segment" first: complete only accepts mesh segmentation tasks)',
         retarget: ' (run "rig" first: retarget only accepts rigged tasks)',
     };

package/dist/knowledge/error-catalog.js

@@ -3,9 +3,9 @@
  * CLI exit code each error maps to.
  *
  * Source of truth: backend ErrorCode enum (platform-common .../error/ErrorCode.java,
- * itself aligned with openapi-server errors.gen.go). Note the public docs page
- * is stale for 1000/1001 — the server actually sends 1002 for auth failures;
- * 1000/1001 are 5xx server-side errors.
+ * itself aligned with openapi-server errors.gen.go). The public docs call
+ * 1000/1001 auth errors while the backend sends 1002 for auth failures and
+ * 1000/1001 for 5xx server errors — so HTTP 401 wins over the code table.
  */
 export const EXIT = {
     OK: 0,
@@ -29,9 +29,9 @@ export const ERROR_CATALOG = [
     { code: 1007, zh: '请求过于频繁,触发全局速率限制', en: 'Rate limit exceeded — too many requests in a short time', retryable: true, exitCode: EXIT.RATE_LIMIT },
     { code: 2000, zh: '触发生成并发上限,同系列任务共享并发池', en: 'Generation concurrency limit hit (task families share a pool)', retryable: true, exitCode: EXIT.RATE_LIMIT },
     { code: 2001, zh: '任务不存在(确认任务属于当前 Key、区域正确)', en: 'Task not found (same key that created it? right region?)', retryable: false, exitCode: EXIT.NOT_FOUND },
-    { code: 2002, zh: '该任务类型不受支持', en: 'This task type is not supported', retryable: false, exitCode: EXIT.USAGE },
-    { code: 2003, zh: '输入图片文件为空,请检查文件是否损坏', en: 'The image file is empty (corrupted upload?)', retryable: false, exitCode: EXIT.USAGE },
-    { code: 2004, zh: '不支持的图片文件类型', en: 'Unsupported image file type', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2002, zh: '不支持的请求参数,请检查字段名和取值', en: 'Unsupported request parameter (check field names and values)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2003, zh: '输入文件为空,请检查文件是否损坏', en: 'The input file is empty (corrupted upload?)', retryable: false, exitCode: EXIT.USAGE },
+    { code: 2004, zh: '不支持的文件类型', en: 'Unsupported file type', retryable: false, exitCode: EXIT.USAGE },
     { code: 2005, zh: 'draft 任务不是成功状态,请用成功的任务重试', en: 'The draft task is not a success; retry with a successful one', retryable: false, exitCode: EXIT.USAGE },
     { code: 2006, zh: '上游任务类型不受支持,请检查任务链', en: 'The original task type is not supported for this operation', retryable: false, exitCode: EXIT.USAGE },
     { code: 2007, zh: '上游任务不是成功状态', en: 'The original task has not succeeded', retryable: false, exitCode: EXIT.USAGE },
@@ -58,13 +58,13 @@ export function lookupError(code) {
 }
 /** Map an API error code + HTTP status to a stable CLI exit code. */
 export function exitCodeFor(apiCode, httpStatus) {
+    if (httpStatus === 401)
+        return EXIT.AUTH;
     if (apiCode !== undefined) {
         const info = byCode.get(apiCode);
         if (info)
             return info.exitCode;
     }
-    if (httpStatus === 401)
-        return EXIT.AUTH;
     if (httpStatus === 403)
         return EXIT.AUTH;
     if (httpStatus === 404)
@@ -78,6 +78,8 @@ export function exitCodeFor(apiCode, httpStatus) {
     return EXIT.FATAL;
 }
 export function isRetryable(apiCode, httpStatus) {
+    if (httpStatus === 401)
+        return false;
     if (apiCode !== undefined) {
         const info = byCode.get(apiCode);
         if (info)