tripo-cli 0.6.1 → 0.7.1

package/README.md

@@ -105,12 +105,25 @@ tripo batch run assets.yaml --concurrency 2
 | `TRIPO_API_BASE_URL` / `TRIPO_PLATFORM_BASE_URL` | endpoint overrides |
 | `TRIPO_HOME` | config/history directory (default `~/.tripo`) |
 | `TRIPO_NO_UPDATE_CHECK` | disable the startup "new version available" hint (also off when `CI` is set, headless, or `--json`) |
+| `TRIPO_ANALYTICS_ENABLED` | set to `0` to turn off usage analytics and the account lookup (see [Telemetry](#telemetry)) |
 | `TRIPO_NPM_REGISTRY` | npm registry used by `tripo update` and the version check (default `https://registry.npmjs.org`; e.g. a mirror) |
 | `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | standard proxy variables, honored for all CLI traffic (plain Node fetch ignores them) |
 | `TRIPO_LLM_BASE_URL` / `TRIPO_LLM_API_KEY` / `TRIPO_LLM_MODEL` | optional OpenAI-compatible LLM for `tripo ai` conversation mode |
 
 Setting `TRIPO_API_KEY` per shell — bash/zsh: `export TRIPO_API_KEY=tsk_...` · PowerShell: `$env:TRIPO_API_KEY = "tsk_..."` (persist for future sessions with `setx TRIPO_API_KEY "tsk_..."`) · CMD: `set TRIPO_API_KEY=tsk_...`
 
+## Telemetry
+
+Since 0.7.0 the CLI sends usage events to Tripo (`https://sshu-api.tripo3d.ai`) for calls to the international API (`openapi.tripo3d.ai`). It is on by default, needs no setup, prints nothing, and never changes stdout, exit codes, or credit behavior.
+
+- **Sent:** command or MCP tool name and its result, sign-in method and result, error category with HTTP status / API code, task id (and parent task id for chains), task type, model, status, credits consumed, durations, downloaded format and file count, CLI version, and the calling agent with its version — `codex` / `workbuddy` / `zcode` / `kimi` (otherwise `unknown`), from `TRIPO_CLIENT_APP` / `TRIPO_DISTRIBUTION_CHANNEL` (set by agent plugins) or the MCP host's client info.
+- **Identity:** a random installation id (`analytics_distinct_id` in `~/.tripo/config.json`) and, since 0.7.1, your Tripo account id (`platform_user_id`) when it can be resolved. It is looked up for the API key actually in use with `POST https://apiplatform.tripo3d.ai/verify`, once per command or MCP tool call, alongside the first API request rather than before it; the lookup gives up after 1 second, is never retried, and the id is never written to disk — on failure events simply go without it. No email or billing details are sent.
+- **Never sent:** prompts, file paths, input images or models, API keys, download URLs (the key itself only goes to `/verify` for the account lookup).
+- **Nothing is sent, and no account lookup is made, for:** China-region (`cn`) calls, custom API endpoints, `--dry-run`, help/version, `docs`, `completion`, `config`, `update`, `use`, `logout`, and the bare `tripo` home screen.
+- **Opt out:** `TRIPO_ANALYTICS_ENABLED=0` (also skips the account lookup).
+
+Delivery is best-effort: each send (including the flush on exit) is capped at 2 seconds, the in-memory queue holds at most 100 events, and nothing is retried or written to disk. Maintainers can redirect or tag events with `TRIPO_ANALYTICS_SERVER_URL`, `TRIPO_ANALYTICS_APP_ID`, and `TRIPO_ANALYTICS_ENVIRONMENT=production|pre|development`; tests send nothing unless `TRIPO_ANALYTICS_ENABLED=1` and a local receiver are both set.
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 import { installProxyFromEnv } from './core/proxy.js';
 import { runCli } from './program.js';
-process.on('SIGINT', () => {
-    process.stderr.write('\n');
-    process.exit(130);
-});
+import { finishOperation } from './core/analytics.js';
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => {
+        process.stderr.write('\n');
+        void finishOperation('interrupted').finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
+    });
+}
 await installProxyFromEnv();
 void runCli(process.argv);

package/dist/commands/login.js

@@ -11,6 +11,7 @@
 import * as p from '@clack/prompts';
 import { activeProfileName, DEFAULT_PROFILE, deleteProfile, describeKeySource, isValidProfileName, listProfiles, loadConfig, maskKey, REGION_DEFAULTS, resolveApiKey, resolvePlatformBaseUrl, resolveRegion, setActiveProfile, updateProfile, } from '../config/config.js';
 import { TripoClient } from '../core/client.js';
+import { trackEvent } from '../core/analytics.js';
 import { DeviceAuthUnavailableError, requestDeviceCode, waitForDeviceApproval, } from '../core/device-auth.js';
 import { AuthError, CliError, NetworkError, UsageError } from '../core/errors.js';
 import { detectRegionForKey } from '../core/region.js';
@@ -220,8 +221,11 @@ async function runHeadlessLogin(region, profile, paste) {
     }
     if (!region) {
         throw new UsageError(t({
-            zh: '非交互登录请指定 --region ov(海外站)或 cn(国内站),例如: tripo login --region ov;或改用 TRIPO_API_KEY / tripo login --key tsk_...',
-            en: 'non-interactive login needs an explicit --region ov (international) or cn (China mainland), e.g. "tripo login --region ov" — or use TRIPO_API_KEY / "tripo login --key tsk_..."',
+            zh: `非交互登录需要 --region:先问用户账号在哪个站,不要猜(授权只在该站有效)— cn = ${siteLabel('cn')};ov = ${siteLabel('ov')};还没有账号:中国大陆选 cn,其它地区选 ov`,
+            en: `non-interactive login needs --region: ask the human which site their account is on, do not guess (authorization only works on that site) — cn = ${siteLabel('cn')}; ov = ${siteLabel('ov')}; no account yet: mainland China → cn, elsewhere → ov`,
+        }), t({
+            zh: 'tripo login --region cn|ov;已有 Key 时用 tripo login --key tsk_...(自动识别站点)',
+            en: '"tripo login --region cn|ov" — or, with a key in hand: "tripo login --key tsk_..." (site auto-detected)',
         }));
     }
     let grant;
@@ -273,6 +277,12 @@ async function runHeadlessLogin(region, profile, paste) {
     const saved = await validateAndSave(result.apikey, region, profile);
     emitResult({ status: 'logged_in', profile, region: saved.region, key: maskKey(result.apikey), balance: saved.balance }, t({ zh: `登录完成(profile=${profile}, region=${saved.region})`, en: `logged in (profile=${profile}, region=${saved.region})` }));
 }
+/** What a human recognizes a console by — they know their sign-in method and how they pay, rarely the region code. */
+function siteLabel(region) {
+    return region === 'cn'
+        ? t({ zh: '国内站 developers.tripo3d.com(手机号登录,支付宝)', en: 'China mainland site developers.tripo3d.com (phone/SMS sign-in, Alipay)' })
+        : t({ zh: '海外站 developers.tripo3d.ai(邮箱登录,Stripe)', en: 'international site developers.tripo3d.ai (email sign-in, Stripe)' });
+}
 /**
  * Preferred path: RFC 8628 device flow — the browser does the sign-in and a
  * one-click approve, the key arrives over the CLI↔console-API channel, and
@@ -494,6 +504,7 @@ function finishSave(key, region, balance, profile) {
     // Saving activates the profile: "the account I just logged into is the
     // account I am using" — no second command needed for the common case.
     updateProfile(profile, { api_key: key, region });
+    trackEvent('agent_auth_result', { result: 'success', auth_method: 'login' }, region, REGION_DEFAULTS[region].api);
     const where = profile === DEFAULT_PROFILE ? '~/.tripo/config.json' : `~/.tripo/config.json · profile "${profile}"`;
     // "mode 0600" is only true where POSIX modes exist; on Windows the file
     // relies on the user profile's NTFS ACLs, so the claim would be wrong.

package/dist/commands/mcp.js

@@ -16,6 +16,7 @@ import { parseThenExpression } from '../knowledge/chains.js';
 import { scenarioIds } from '../knowledge/scenarios.js';
 import { executeMake, planMake } from '../pipeline/make.js';
 import { cliVersion } from '../version.js';
+import { beginOperation, finishOperation } from '../core/analytics.js';
 const TOOLS = [
     {
         name: 'tripo_make',
@@ -77,6 +78,7 @@ export function registerMcpCommand(program) {
     });
 }
 async function serveMcp() {
+    let clientInfo = {};
     const rl = createInterface({ input: process.stdin, terminal: false });
     const write = (message) => {
         process.stdout.write(JSON.stringify(message) + '\n');
@@ -96,11 +98,22 @@ async function serveMcp() {
             continue; // notification — nothing to answer
         }
         try {
+            if (request.method === 'initialize' && request.params?.clientInfo && typeof request.params.clientInfo === 'object') {
+                clientInfo = request.params.clientInfo;
+            }
+            if (request.method === 'tools/call')
+                beginOperation(String(request.params?.name ?? 'unknown'), false, clientInfo);
             const result = await dispatch(request.method, request.params ?? {});
             if (result !== SKIP)
                 write({ jsonrpc: '2.0', id: request.id, result });
+            if (request.method === 'tools/call') {
+                const failed = typeof result === 'object' && result !== null && 'isError' in result && result.isError === true;
+                await finishOperation(failed ? 'failed' : 'success');
+            }
         }
         catch (err) {
+            if (request.method === 'tools/call')
+                await finishOperation('failed', err);
             write({
                 jsonrpc: '2.0',
                 id: request.id,
@@ -179,7 +192,7 @@ async function callTool(params) {
             }
             case 'tripo_history': {
                 const limit = typeof args.limit === 'number' ? args.limit : 10;
-                return asText(readHistory().slice(-limit));
+                return asText(readHistory().slice(-limit).map(({ analytics_origin: _origin, analytics_finished: _finished, ...entry }) => entry));
             }
             default:
                 return { content: [{ type: 'text', text: `unknown tool: ${params.name}` }], isError: true };

package/dist/commands/task.js

@@ -119,7 +119,7 @@ export function registerTaskCommands(program) {
         .description('recent tasks created by this CLI (@name references)')
         .option('--limit <n>', 'rows', (v) => Number(v), 20)
         .action((opts) => {
-        const entries = readHistory().slice(-opts.limit);
+        const entries = readHistory().slice(-opts.limit).map(({ analytics_origin: _origin, analytics_finished: _finished, ...entry }) => entry);
         const human = entries
             .map((e) => `${e.created_at.slice(0, 19)}  ${(e.name ?? '').padEnd(24)} ${e.type.padEnd(22)} ${e.status.padEnd(9)} ${e.task_id}`)
             .join('\n');

package/dist/core/analytics.js

@@ -0,0 +1,302 @@
+/** Agent analytics. Collection must never change a business result. */
+import { createHash, randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { loadConfig, updateConfig, resolveApiBaseUrl, resolveRegion, REGION_DEFAULTS } from '../config/config.js';
+import { readHistory, updateHistoryStatus } from '../config/history.js';
+import { cliVersion } from '../version.js';
+import { ApiError, AuthError, NetworkError, TaskFailedError, UsageError } from './errors.js';
+export const ANALYTICS_SERVER_URL = "https://sshu-api.tripo3d.ai";
+export const ANALYTICS_APP_ID = "2908364badd34996a1cd44a5f7a71223";
+const operations = new AsyncLocalStorage();
+let activeOperation;
+let installationId;
+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),
+            distinctId: randomUUID(), operation_id: randomUUID(), integration_mode: info ? "local_mcp" : "cli",
+        } };
+    operations.enterWith(activeOperation);
+}
+export function analyticsContext() { return currentOperation()?.context; }
+/** Resolve only the key actually used by this operation, without delaying its requests; never persist account identities. */
+export function identifyUser(apiKey, region, apiUrl) {
+    const operation = currentOperation();
+    const analytics = collector(region, apiUrl);
+    if (!operation || !analytics?.identityEnabled)
+        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) };
+}
+function collector(region = currentOperation()?.regionHint ?? resolveRegion(), apiUrl = resolveApiBaseUrl()) {
+    const operation = currentOperation();
+    if (!operation || operation.disabled)
+        return undefined;
+    const key = `${region}:${apiUrl}`;
+    let analytics = operation.collectors.get(key);
+    if (!analytics) {
+        analytics = new Analytics("tripo-cli", cliVersion(), region, apiUrl);
+        operation.collectors.set(key, analytics);
+    }
+    if (analytics.enabled && !installationId) {
+        try {
+            const config = loadConfig();
+            installationId = typeof config.analytics_distinct_id === "string" && /^[a-f0-9-]{36}$/.test(config.analytics_distinct_id)
+                ? config.analytics_distinct_id : randomUUID();
+            if (config.analytics_distinct_id !== installationId)
+                updateConfig({ analytics_distinct_id: installationId });
+        }
+        catch {
+            installationId = randomUUID();
+        }
+    }
+    if (installationId)
+        operation.context.distinctId = installationId;
+    return analytics;
+}
+export function errorProperties(error) {
+    const category = error instanceof TaskFailedError ? error.status === 'timeout' ? 'waiting_timeout' : 'task_failed'
+        : error instanceof ApiError ? error.apiCode === 2010 ? 'balance' : 'upstream'
+            : error instanceof AuthError ? 'authorization' : error instanceof NetworkError ? 'network'
+                : error instanceof UsageError ? 'validation' : 'internal';
+    return { error_category: category, ...(error instanceof ApiError ? { http_status: error.httpStatus, api_code: error.apiCode } : {}) };
+}
+export function trackEvent(event, properties = {}, region, apiUrl) {
+    const operation = currentOperation();
+    // At most one authorization outcome per operation; later reports are dropped.
+    if (operation && event === 'agent_auth_started')
+        operation.authMethod = properties.auth_method;
+    if (operation && event === 'agent_auth_result') {
+        if (operation.authReported)
+            return;
+        operation.authReported = true;
+    }
+    const analytics = collector(region, apiUrl);
+    const context = analyticsContext();
+    if (analytics && context)
+        analytics.track(event, context, properties, operation?.identity?.value);
+}
+export async function flushAnalytics() {
+    const operation = currentOperation();
+    if (operation)
+        await Promise.all([...operation.collectors.values()].map((analytics) => analytics.flush()));
+}
+export async function finishOperation(result, error) {
+    const operation = currentOperation();
+    if (!operation || operation.finished)
+        return;
+    operation.finished = true;
+    if (operation.command === 'login' && result !== 'success') {
+        trackEvent('agent_auth_result', { result, auth_method: operation.authMethod ?? 'login', ...(error ? errorProperties(error) : {}) });
+    }
+    trackEvent('agent_tool_result', { command: operation.command,
+        ...(operation.context.integration_mode === 'local_mcp' ? { tool_name: operation.command } : {}),
+        result, duration_ms: Date.now() - operation.started, ...(error ? errorProperties(error) : {}) });
+    await flushAnalytics();
+}
+export function taskOrigin(model) {
+    const context = analyticsContext();
+    return context ? { creation_client_app: context.client_app, creation_distribution_channel: context.distribution_channel,
+        creation_integration_mode: context.integration_mode, ...(typeof model === 'string' ? { model } : {}) } : undefined;
+}
+const observed = new Set();
+export function observeTask(task, region, apiUrl) {
+    if (!collector(region, apiUrl)?.enabled || !['success', 'failed', 'cancelled', 'banned', 'expired'].includes(task.status))
+        return;
+    const key = `${region}:${task.task_id}`;
+    const history = readHistory().find((entry) => entry.task_id === task.task_id);
+    if (observed.has(key) || history?.analytics_finished)
+        return;
+    observed.add(key);
+    // Bound this cache for long-lived stdio hosts; history preserves known task markers.
+    if (observed.size > 1000)
+        observed.delete(observed.values().next().value);
+    trackEvent('agent_task_finished', { ...history?.analytics_origin,
+        creation_client_app: history?.analytics_origin?.creation_client_app ?? 'unknown',
+        creation_distribution_channel: history?.analytics_origin?.creation_distribution_channel ?? 'unknown',
+        origin_known: Boolean(history?.analytics_origin), task_id: task.task_id, task_type: task.type,
+        status: task.status, credits_consumed: task.credits_consumed,
+        generation_duration_ms: task.created_at && task.completed_at ? Math.max(0, Date.parse(task.completed_at) - Date.parse(task.created_at)) : undefined,
+    }, region, apiUrl);
+    if (history) {
+        try {
+            updateHistoryStatus(task.task_id, task.status, { analytics_finished: true });
+        }
+        catch { /* best effort marker */ }
+    }
+}
+function platformUserId(value) {
+    if (typeof value === 'number')
+        return Number.isSafeInteger(value) && value > 0 ? String(value) : undefined;
+    return typeof value === 'string' && /^[1-9]\d{0,18}$/.test(value) ? value : undefined;
+}
+export function clientApp(value) {
+    if (typeof value !== "string")
+        return "unknown";
+    const name = value.trim().toLowerCase();
+    for (const app of ["codex", "workbuddy", "zcode", "kimi"]) {
+        if (new RegExp(`(^|[\\s_./-])${app}($|[\\s_./-])`).test(name))
+            return app;
+    }
+    return "unknown";
+}
+export function attribution(explicit, distribution, info, oauthName) {
+    const tagged = clientApp(explicit);
+    const initialized = clientApp(info?.name);
+    const oauth = clientApp(oauthName);
+    const chosen = tagged !== "unknown" ? tagged : initialized !== "unknown" ? initialized : oauth;
+    const channels = ["codex_plugin", "workbuddy_plugin", "zcode_plugin", "kimi_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),
+        ...(typeof info?.version === "string" && /^[a-zA-Z0-9._+-]{1,64}$/.test(info.version) && !/tsk_|bearer|token/i.test(info.version) ? { client_version: info.version } : {}),
+    };
+}
+const FIELDS = new Set([
+    "tool_name", "command", "result", "status", "task_id", "parent_task_id", "model", "task_type",
+    "duration_ms", "generation_duration_ms", "credits_consumed", "error_category", "http_status", "api_code",
+    "auth_flow_id", "auth_method", "observation_source", "creation_client_app", "creation_distribution_channel",
+    "creation_integration_mode", "origin_known", "model_downloaded", "file_count", "format", "interrupted",
+]);
+export class Analytics {
+    app;
+    version;
+    enabled;
+    identityEnabled;
+    testing;
+    url;
+    appId;
+    environment;
+    queue = [];
+    pending;
+    scheduled = false;
+    stats = { sent: 0, failed: 0, dropped: 0 };
+    constructor(app, version, region, apiUrl, env = process.env) {
+        this.app = app;
+        this.version = version;
+        const receiver = env.TRIPO_ANALYTICS_SERVER_URL ?? ANALYTICS_SERVER_URL;
+        this.appId = env.TRIPO_ANALYTICS_APP_ID ?? ANALYTICS_APP_ID;
+        const environment = env.TRIPO_ANALYTICS_ENVIRONMENT ?? (env.NODE_ENV === "production" ? "production" : app === "tripo-cli" ? "production" : "development");
+        this.environment = ["production", "pre", "development"].includes(environment) ? environment : "development";
+        this.url = "";
+        let officialApi = false;
+        let localApi = false;
+        let testReceiver = false;
+        try {
+            const url = new URL(receiver);
+            this.url = new URL("sync_json", url.href.endsWith("/") ? url : `${url.href}/`).href;
+            const api = new URL(apiUrl);
+            officialApi = api.protocol === "https:" && api.hostname === "openapi.tripo3d.ai";
+            localApi = ["localhost", "127.0.0.1", "[::1]"].includes(api.hostname);
+            testReceiver = (url.protocol === "http:" || url.protocol === "https:") && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+            if (url.username || url.password || url.search || url.hash || !["http:", "https:"].includes(url.protocol))
+                this.url = "";
+        }
+        catch { /* invalid analytics configuration is disabled, never fatal */ }
+        const testing = this.testing = env.NODE_ENV === "test" || Boolean(env.VITEST);
+        this.enabled = region === "ov" && Boolean(this.url && this.appId) && env.TRIPO_ANALYTICS_ENABLED !== "0"
+            && (testing ? env.TRIPO_ANALYTICS_ENABLED === "1" && testReceiver : officialApi || testReceiver);
+        this.identityEnabled = this.enabled && (testing ? localApi : officialApi);
+    }
+    async identify(apiKey, consoleApi) {
+        if (!this.identityEnabled)
+            return undefined;
+        try {
+            const url = new URL(`${consoleApi.replace(/\/$/, '')}/verify`);
+            const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+            if (url.username || url.password || url.search || url.hash || !["http:", "https:"].includes(url.protocol)
+                || (this.testing ? !local : url.protocol !== "https:" || url.hostname !== "apiplatform.tripo3d.ai"))
+                return undefined;
+            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),
+            });
+            if (!response.ok)
+                return undefined;
+            const body = await response.json();
+            return body?.code === 0 && body.data?.valid === true ? platformUserId(body.data.detail?.owner) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    track(event, context, properties = {}, identity) {
+        if (!this.enabled || !/^agent_[a-z_]+$/.test(event))
+            return;
+        if (this.queue.length >= 100) {
+            this.stats.dropped++;
+            return;
+        }
+        const safe = {};
+        for (const [key, value] of Object.entries(properties)) {
+            if (!FIELDS.has(key))
+                continue;
+            if (typeof value === "number" && Number.isFinite(value) || typeof value === "boolean")
+                safe[key] = value;
+            else if (typeof value === "string" && /^[a-zA-Z0-9_.:-]{1,128}$/.test(value) && !/tsk_|bearer|token/i.test(value))
+                safe[key] = value;
+        }
+        this.queue.push({ identity, event: { appid: this.appId, data: {
+                    "#type": "track", "#event_name": event, "#distinct_id": context.distinctId,
+                    "#time": new Date().toISOString().replace("T", " ").replace("Z", ""),
+                    properties: {
+                        ...safe, ...attribution(context.client_app, context.distribution_channel, { version: context.client_version }),
+                        attribution_method: context.attribution_method, attribution_conflict: context.attribution_conflict ?? false,
+                        app: this.app, event_source: this.app === "tripo-mcp" ? "server" : "cli", site_region: "global",
+                        environment: this.environment, schema_version: 2, agent_schema_version: 1, app_version: this.version,
+                        integration_mode: context.integration_mode, operation_id: context.operation_id, event_id: randomUUID(),
+                        identity_type: this.app === "tripo-mcp" ? "authorization" : "installation", observation_source: "client", "#zone_offset": 0,
+                    },
+                } } });
+        if (!this.scheduled) {
+            this.scheduled = true;
+            queueMicrotask(() => { this.scheduled = false; void this.flush(); });
+        }
+    }
+    async flush() {
+        if (this.pending)
+            return this.pending;
+        if (!this.queue.length)
+            return;
+        // ponytail: bounded best-effort delivery; no persistent spool or retries in v1.
+        const send = async () => {
+            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.
+                await Promise.all(batch.map(async ({ event, identity }) => {
+                    const userId = await identity;
+                    if (userId)
+                        event.data.properties.platform_user_id = userId;
+                }));
+                try {
+                    const response = await fetch(this.url, {
+                        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(batch.map(({ event }) => event)),
+                        signal: AbortSignal.timeout(Math.max(1, deadline - Date.now())),
+                    });
+                    const body = await response.json();
+                    if (!response.ok || body.code !== 0)
+                        throw new Error("analytics rejected");
+                    this.stats.sent += batch.length;
+                }
+                catch {
+                    this.stats.failed += batch.length;
+                }
+            }
+            this.stats.dropped += this.queue.length;
+            this.queue = [];
+        };
+        this.pending = send();
+        try {
+            await this.pending;
+        }
+        finally {
+            this.pending = undefined;
+        }
+    }
+}

package/dist/core/client.js

@@ -8,7 +8,10 @@ import { activeProfileName, DEFAULT_PROFILE, listProfiles, loadConfig, resolveAp
 import { t } from '../i18n.js';
 import { EXIT } from '../knowledge/error-catalog.js';
 import { ApiError, AuthError, NetworkError } from './errors.js';
+import { identifyUser, observeTask, trackEvent, taskOrigin } from './analytics.js';
+import { resolveRegion } from '../config/config.js';
 export class TripoClient {
+    region = resolveRegion();
     baseUrl;
     apiKey;
     timeoutMs;
@@ -52,6 +55,7 @@ export class TripoClient {
         return this.send('POST', '/v3/files', { body: form });
     }
     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) {
@@ -117,9 +121,11 @@ export class TripoClient {
         return envelope.data;
     }
     // ---- typed convenience wrappers ----
-    getTask(taskId, step = false) {
+    async getTask(taskId, step = false) {
         const suffix = step ? '?step=1' : '';
-        return this.request('GET', `/v3/tasks/${encodeURIComponent(taskId)}${suffix}`);
+        const task = await this.request('GET', `/v3/tasks/${encodeURIComponent(taskId)}${suffix}`);
+        observeTask(task, this.region, this.baseUrl);
+        return task;
     }
     /**
      * Batch task query. The server returns `{tasks: {id: detail}, missed: [id]}`
@@ -128,6 +134,8 @@ export class TripoClient {
     async listTasks(taskIds) {
         const data = await this.request('POST', '/v3/tasks/list', { task_ids: taskIds });
         const byId = data.tasks ?? {};
+        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 }));
@@ -140,9 +148,11 @@ export class TripoClient {
         return this.request('GET', '/v3/account/usage');
     }
     /** Create a task; returns its id. Response may be {task_id} or a full detail. */
-    async createTask(endpoint, payload) {
+    async createTask(endpoint, payload, taskType) {
         try {
             const data = await this.request('POST', endpoint, payload, { idempotent: false });
+            trackEvent('agent_task_created', { ...taskOrigin(payload.model), task_id: data.task_id, task_type: taskType,
+                ...([payload.original_model_task_id, payload.task_id, payload.input].some((value) => typeof value === 'string' && /^[a-f0-9-]{36}$/.test(value)) ? { parent_task_id: [payload.original_model_task_id, payload.task_id, payload.input].find((value) => typeof value === 'string' && /^[a-f0-9-]{36}$/.test(value)) } : {}) }, this.region, this.baseUrl);
             return data.task_id;
         }
         catch (err) {

package/dist/core/device-auth.js

@@ -13,6 +13,7 @@ import { hostname } from 'node:os';
 import { join } from 'node:path';
 import { REGION_DEFAULTS, tripoHome } from '../config/config.js';
 import { sleep } from './client.js';
+import { trackEvent } from './analytics.js';
 export const DEVICE_CODE_EXPIRED = 4290;
 export const DEVICE_CODE_SLOW_DOWN = 4291;
 export const DEVICE_CODE_DENIED = 4292;
@@ -79,6 +80,7 @@ export function deviceKeyName(profile, host = hostname(), id = deviceId()) {
     return `${prefix} - ${shownHost} ${id}`.replace(/\s+/g, ' ').slice(0, 32).trim();
 }
 export async function requestDeviceCode(region, profile) {
+    trackEvent('agent_auth_started', { auth_method: 'device' }, region, REGION_DEFAULTS[region].api);
     const body = await post(`${consoleApiBaseUrl(region)}/cli/device/code`, { name: deviceKeyName(profile) });
     const grant = body.data;
     if (!grant ||
@@ -138,9 +140,12 @@ export async function waitForDeviceApproval(region, grant, onTick) {
             intervalMs += 5000;
             continue;
         }
-        if (poll.status !== 'pending')
+        if (poll.status !== 'pending') {
+            trackEvent('agent_auth_result', { result: poll.status === 'approved' ? 'success' : poll.status, auth_method: 'device' }, region, REGION_DEFAULTS[region].api);
             return poll;
+        }
     }
+    trackEvent('agent_auth_result', { result: 'expired', auth_method: 'device' }, region, REGION_DEFAULTS[region].api);
     return { status: 'expired' };
 }
 /**

package/dist/core/download.js

@@ -10,6 +10,7 @@ import { basename, extname, join } from 'node:path';
 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 IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp']);
 /** Collect every downloadable URL in the output map (string or {url} object). */
@@ -59,48 +60,57 @@ async function downloadOne(url, dest) {
 }
 /** Download all artifacts of a finished task + write task.json. */
 export async function downloadArtifacts(task, outputDir, historyEntry, options = {}) {
-    await mkdir(outputDir, { recursive: true });
-    const urls = collectOutputUrls(task.output);
-    const files = [];
-    let modelFile;
-    let preview;
-    for (const { field, url } of urls) {
-        const name = fileNameFor(field, url);
-        const dest = join(outputDir, name);
-        options.onFile?.(name);
-        await downloadOne(url, dest);
-        files.push(dest);
-        const ext = extname(name).toLowerCase();
-        if (!modelFile && MODEL_EXTS.has(ext))
-            modelFile = dest;
-        // uv_render (mesh/uv) is a flat UV atlas, not a render of the model.
-        if (!preview && !/uv_render/.test(field) && (IMAGE_EXTS.has(ext) || /rendered|preview/i.test(field)))
-            preview = dest;
-    }
-    // Normalize the preview name so agents can rely on preview.png existing.
-    if (preview && basename(preview) !== 'preview.png') {
-        const { copyFile } = await import('node:fs/promises');
-        const canonical = join(outputDir, 'preview.png');
-        try {
-            await copyFile(preview, canonical);
-            files.push(canonical);
-            preview = canonical;
+    const started = Date.now();
+    try {
+        await mkdir(outputDir, { recursive: true });
+        const urls = collectOutputUrls(task.output);
+        const files = [];
+        let modelFile;
+        let preview;
+        for (const { field, url } of urls) {
+            const name = fileNameFor(field, url);
+            const dest = join(outputDir, name);
+            options.onFile?.(name);
+            await downloadOne(url, dest);
+            files.push(dest);
+            const ext = extname(name).toLowerCase();
+            if (!modelFile && MODEL_EXTS.has(ext))
+                modelFile = dest;
+            // uv_render (mesh/uv) is a flat UV atlas, not a render of the model.
+            if (!preview && !/uv_render/.test(field) && (IMAGE_EXTS.has(ext) || /rendered|preview/i.test(field)))
+                preview = dest;
+        }
+        // Normalize the preview name so agents can rely on preview.png existing.
+        if (preview && basename(preview) !== 'preview.png') {
+            const { copyFile } = await import('node:fs/promises');
+            const canonical = join(outputDir, 'preview.png');
+            try {
+                await copyFile(preview, canonical);
+                files.push(canonical);
+                preview = canonical;
+            }
+            catch { }
         }
-        catch { }
+        const record = {
+            task_id: task.task_id,
+            type: task.type,
+            status: task.status,
+            input: task.input ?? historyEntry?.payload ?? {},
+            output_fields: urls.map((u) => u.field),
+            credits_consumed: task.credits_consumed,
+            created_at: task.created_at,
+            completed_at: task.completed_at,
+            files: files.map((f) => basename(f)),
+        };
+        await writeFile(join(outputDir, 'task.json'), JSON.stringify(record, null, 2) + '\n');
+        trackEvent('agent_download_result', { task_id: task.task_id, result: 'success', model_downloaded: Boolean(modelFile),
+            file_count: files.length, duration_ms: Date.now() - started, format: modelFile ? extname(modelFile).slice(1) : undefined });
+        return { outputDir, files, modelFile, preview };
+    }
+    catch (error) {
+        trackEvent('agent_download_result', { task_id: task.task_id, result: 'failed', duration_ms: Date.now() - started, ...errorProperties(error) });
+        throw error;
     }
-    const record = {
-        task_id: task.task_id,
-        type: task.type,
-        status: task.status,
-        input: task.input ?? historyEntry?.payload ?? {},
-        output_fields: urls.map((u) => u.field),
-        credits_consumed: task.credits_consumed,
-        created_at: task.created_at,
-        completed_at: task.completed_at,
-        files: files.map((f) => basename(f)),
-    };
-    await writeFile(join(outputDir, 'task.json'), JSON.stringify(record, null, 2) + '\n');
-    return { outputDir, files, modelFile, preview };
 }
 /** Default output directory: ./tripo-out/<slug>-<id8>/ */
 export function defaultOutputDir(baseDir, slug, taskId) {

package/dist/core/task-service.js

@@ -13,6 +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 { taskOrigin } from './analytics.js';
 import { ApiError, CliError, TaskFailedError, UsageError, balanceSuggestion } from './errors.js';
 import { isQuiet, log, warn } from './output.js';
 import { uploadLocalFile } from './upload.js';
@@ -85,9 +86,10 @@ export async function runTask(options) {
     const { client, request, taskType } = options;
     if (options.precheckBalance !== false)
         await precheckBalance(client);
-    const taskId = await client.createTask(request.endpoint, request.payload);
+    const taskId = await client.createTask(request.endpoint, request.payload, taskType);
     const name = uniqueName(slugify(options.name));
     const entry = {
+        analytics_origin: taskOrigin(request.payload.model),
         task_id: taskId,
         type: taskType,
         name,

package/dist/program.js

@@ -25,6 +25,7 @@ import { configureOutput, errorLine, isJsonMode } from './core/output.js';
 import { setLocale, t } from './i18n.js';
 import { EXIT } from './knowledge/error-catalog.js';
 import { cliVersion } from './version.js';
+import { beginOperation, finishOperation } from './core/analytics.js';
 export function buildProgram() {
     const program = new Command();
     program
@@ -56,11 +57,18 @@ export function buildProgram() {
         const lang = loadConfig().language;
         if (lang)
             setLocale(lang);
+        const path = [];
+        for (let command = actionCommand; command && command !== program; command = command.parent)
+            path.unshift(command.name());
+        const excluded = ['mcp', 'docs', 'completion', 'config', 'update', 'use', 'logout', 'home'];
+        if (actionCommand.name() !== 'mcp')
+            beginOperation(path.join(':'), path.length === 0 || excluded.includes(path[0]) || actionCommand.opts().dryRun === true, undefined, actionCommand.opts().region === 'cn' || actionCommand.opts().region === 'ov' ? actionCommand.opts().region : undefined);
         // Startup version hint (cached, non-blocking). `update` reports on its
         // own; `mcp` speaks JSON-RPC over stdio and must stay silent.
         if (actionCommand.name() !== 'update' && actionCommand.name() !== 'mcp')
             notifyIfOutdated();
     });
+    program.hook('postAction', async () => { await finishOperation('success'); });
     registerMakeCommand(program);
     registerAiCommand(program);
     registerViewCommands(program);
@@ -134,6 +142,7 @@ export async function runCli(argv) {
         await program.parseAsync(argv);
     }
     catch (err) {
+        await finishOperation('failed', err);
         handleError(err);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tripo-cli",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "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

@@ -9,13 +9,20 @@ One command turns a text prompt or an image into local files: a 3D model (glb/fb
 npm install -g tripo-cli        # or: npx tripo-cli ...
 export TRIPO_API_KEY=tsk_...    # highest-priority auth; no interaction needed
                                 # (PowerShell: $env:TRIPO_API_KEY = "tsk_...")
+                                # China-site key? also export TRIPO_REGION=cn (env keys default to ov)
 tripo doctor                    # verify key, network, balance
 ```
 
-If there is no key, run the device login **yourself** — it works without a TTY:
+If there is no key, run the device login **yourself** — it works without a TTY.
+First ask the human which Tripo site their account is on, and do not guess: the
+login only works on the site it was started for.
+
+- `cn` — China mainland site developers.tripo3d.com (phone/SMS sign-in, Alipay)
+- `ov` — international site developers.tripo3d.ai (email sign-in, Stripe)
+- no account yet: mainland China → `cn`, everywhere else → `ov`
 
 ```bash
-tripo login --region ov      # ov = international, cn = China mainland
+tripo login --region <cn|ov>    # the site the human named
 ```
 
 It prints a verification URL and a one-time code, then blocks until the human
@@ -24,9 +31,10 @@ and code to the human and tell them: sign in on that page first if it asks
 (sign-up gives free credits), enter the code, pick an API key if the account has
 several (one is created automatically if there are none), click Authorize. The
 key is then saved locally; never ask the human to paste a key into the chat. If
-the code expires (exit 3), just run the same command again.
+the code expires (exit 3), just run the same command again; if the human says
+the page is the wrong site, stop it and rerun with the other `--region`.
 
-Regions (ov = international, cn = China mainland) share one CLI: `tripo login --key tsk_...` auto-detects which region the key belongs to. On exit code 3 (auth), run `tripo doctor` — it diagnoses key-vs-region mismatches and prints the exact fix (`tripo config set region cn|ov`).
+Regions (ov = international, cn = China mainland) share one CLI: `tripo login --key tsk_...` auto-detects which region the key belongs to. Already logged into the wrong site? `tripo login --region <other>` replaces the active profile's key and region. On exit code 3 (auth), run `tripo doctor` — it diagnoses key-vs-region mismatches and prints the exact fix (`tripo config set region cn|ov`).
 
 ## Behavior rules (read first)