@meshy-ai/cli 0.2.0 → 0.3.1

package/dist/cmd/inspect.js

@@ -0,0 +1,179 @@
+/**
+ * inspect faces — the face-count gate.
+ *
+ * Two mutually exclusive task sources: a saved task JSON (no network, no
+ * credential, no config directory) or exactly one GET of a task through the
+ * resource registry. The command never downloads a model and never creates a
+ * remesh task; a failing verdict only *describes* the remesh that would help.
+ *
+ * `--max-faces` is required on purpose: the rigging ceiling (300000) is one
+ * consumer's rule and uv-unwrap's is 40000 — there is no limit that belongs
+ * to every mesh, so none is assumed. Exit codes: pass 0, fail 12, unknown 13
+ * (D-009). Nothing printed here claims more than the face count.
+ */
+import { Command } from "commander";
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { findTaskResource, TASK_RESOURCES } from "../client/resource-registry.js";
+import { emitResult, openCommand, rejectOutputFlagForV1, saveRawJson } from "../internal/command-helpers.js";
+import { abortSignal } from "../internal/context.js";
+import { CliError, UsageError } from "../internal/errors.js";
+import { judgeTask, remeshSuggestion } from "../internal/inspect.js";
+import { buildLocalRuntime, buildRuntime } from "../internal/runtime.js";
+import { extractTaskObject } from "../internal/task-view.js";
+/** Engineering limit for a local task JSON (D-018); enforced while reading, never by truncation. */
+export const TASK_JSON_MAX_BYTES = 16 * 1024 * 1024;
+function errnoMessage(err) {
+    const code = err?.code;
+    return code ? code : err instanceof Error ? err.message : String(err);
+}
+/** `--max-faces` accepts a plain positive integer; "3.5", "0", "-1" and "abc" are usage errors. */
+export function parseMaxFaces(raw) {
+    const text = raw.trim();
+    if (!/^\d+$/.test(text))
+        throw new UsageError(`--max-faces must be a positive integer (got '${raw}')`);
+    const n = Number(text);
+    if (!Number.isSafeInteger(n) || n < 1)
+        throw new UsageError(`--max-faces must be a positive integer (got '${raw}')`);
+    return n;
+}
+function readBounded(fd, maxBytes, label) {
+    const chunks = [];
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    let total = 0;
+    for (;;) {
+        const n = readSync(fd, chunk, 0, chunk.length, null);
+        if (n === 0)
+            break;
+        total += n;
+        if (total > maxBytes) {
+            throw new UsageError(`--task-json: ${label} exceeds ${maxBytes} bytes (task JSON limit); refusing to read further`);
+        }
+        chunks.push(Buffer.from(chunk.subarray(0, n)));
+    }
+    return Buffer.concat(chunks, total).toString("utf8");
+}
+/**
+ * Read a task from a local JSON file in any shape the CLI writes or the API
+ * returns (API task, download meta.json, v1 envelope / result). Every problem
+ * with the file is a usage error: the caller named it, so a bad file is a
+ * mistake to report, not a fact about the model.
+ */
+export function readTaskJsonFile(path, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const maxBytes = opts.maxBytes ?? TASK_JSON_MAX_BYTES;
+    const abs = resolvePath(cwd, path);
+    let fd;
+    try {
+        fd = openSync(abs, "r");
+    }
+    catch (err) {
+        throw new UsageError(`--task-json: cannot open ${path} (${errnoMessage(err)})`);
+    }
+    let text;
+    try {
+        if (!fstatSync(fd).isFile())
+            throw new UsageError(`--task-json: not a regular file: ${path}`);
+        text = readBounded(fd, maxBytes, path);
+    }
+    finally {
+        closeSync(fd);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new UsageError(`--task-json: ${path} is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const extracted = extractTaskObject(parsed);
+    if (!extracted) {
+        throw new UsageError(`--task-json: ${path} does not contain a task (expected an API task object with id+status, a download meta.json with "task", or a v1 envelope with result.task)`);
+    }
+    return { path: abs, task: extracted.task, shape: extracted.source };
+}
+function resolveSource(opts) {
+    const hasFile = opts.taskJson !== undefined;
+    const hasApi = opts.resource !== undefined || opts.taskId !== undefined;
+    if (hasFile && hasApi) {
+        throw new UsageError("choose one task source: --task-json <file>, or --resource <id> with --task-id <id> — not both");
+    }
+    if (hasFile)
+        return { kind: "task-json", path: opts.taskJson };
+    if (opts.resource === undefined || opts.taskId === undefined) {
+        throw new UsageError("a task source is required: --task-json <file>, or --resource <id> together with --task-id <id>");
+    }
+    return { kind: "api", resource: opts.resource, taskId: opts.taskId };
+}
+function taskIdOf(task, fallback) {
+    if (typeof task["id"] === "string" && task["id"])
+        return task["id"];
+    if (typeof task["task_id"] === "string" && task["task_id"])
+        return task["task_id"];
+    return fallback;
+}
+/** Build a fresh `inspect` command tree (tests parse a new tree per run). */
+export function buildInspectCommand() {
+    const faces = new Command("faces")
+        .description("Face-count gate: pass (exit 0) | fail (exit 12) | unknown (exit 13). Answers only whether face_count <= --max-faces; " +
+        "a missing or malformed count is unknown, never 0. Never downloads a model or submits a remesh")
+        .option("--task-json <file>", "saved task JSON (API task, download meta.json or v1 envelope); no network, no credential")
+        .option("--resource <id>", "task resource id (see `meshy resources`), fetched once with --task-id")
+        .option("--task-id <id>", "task id to fetch once from the API (with --resource)")
+        .option("--max-faces <n>", "maximum accepted face count (required; e.g. 300000 for rigging, 40000 for uv-unwrap — no default)", parseMaxFaces)
+        .option("--save-json <file>", "API source only: save the task JSON as received (never overwrites)")
+        .action(async (opts, thisCmd) => {
+        const opened = openCommand(thisCmd, "inspect.faces", "v1");
+        rejectOutputFlagForV1(opened, opts.saveJson);
+        if (opts.maxFaces === undefined) {
+            throw new UsageError("--max-faces <n> is required: the limit belongs to the caller (rigging accepts up to 300000 faces, uv-unwrap up to 40000); no default is assumed");
+        }
+        const limit = opts.maxFaces;
+        const source = resolveSource(opts);
+        let task;
+        let sourceInfo;
+        let savedJson = null;
+        if (source.kind === "task-json") {
+            if (opts.saveJson) {
+                throw new UsageError("--save-json only applies to the API source (--resource/--task-id); the task JSON is already a file");
+            }
+            buildLocalRuntime(opened.flags);
+            const loaded = readTaskJsonFile(source.path);
+            task = loaded.task;
+            sourceInfo = { kind: "task-json", path: loaded.path, shape: loaded.shape };
+        }
+        else {
+            const descriptor = findTaskResource(source.resource);
+            if (!descriptor) {
+                throw new UsageError(`unknown --resource '${source.resource}'. Valid ids: ${TASK_RESOURCES.map((d) => d.id).join(", ")}`);
+            }
+            const runtime = await buildRuntime(opened.flags);
+            // Exactly one GET; the verdict is read from the raw JSON, not the Zod-defaulted object.
+            const { raw } = await runtime.client.endpointFor(descriptor).retrieveDetailed(source.taskId, { signal: abortSignal() });
+            const extracted = extractTaskObject(raw);
+            task = extracted?.task ?? raw;
+            savedJson = opts.saveJson ? saveRawJson(opts.saveJson, raw, { workspace: opened.flags.workspaceRoot }) : null;
+            sourceInfo = { kind: "api", resource: descriptor.id, task_id: source.taskId, endpoint: descriptor.legacyEndpoint, requests_made: 1 };
+        }
+        const verdict = judgeTask(task, limit);
+        const taskId = taskIdOf(task, source.kind === "api" ? source.taskId : null);
+        const result = {
+            ...verdict,
+            source: sourceInfo,
+            task_id: taskId,
+            status: typeof task["status"] === "string" ? task["status"] : null,
+            suggestion: verdict.verdict === "fail" ? remeshSuggestion(taskId, limit) : null,
+            saved_json: savedJson,
+        };
+        if (verdict.verdict === "fail") {
+            throw new CliError({ code: "check_failed", message: `face count check failed: ${verdict.reason}`, result: { ...result } });
+        }
+        if (verdict.verdict === "unknown") {
+            throw new CliError({ code: "check_unknown", message: `face count unknown: ${verdict.reason}`, result: { ...result } });
+        }
+        await emitResult(opened, result, result);
+    });
+    return new Command("inspect").description("Local checks on task results (face-count gate)").addCommand(faces);
+}
+export const inspectCommand = buildInspectCommand();
+//# sourceMappingURL=inspect.js.map

package/dist/cmd/inspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.js","sourceRoot":"","sources":["../../src/cmd/inspect.ts"],"names":[],"mappings":"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"}

package/dist/cmd/make.d.ts

@@ -14,12 +14,21 @@
  * someone else's credits on its own opinion. The resource commands remain the
  * way to compose anything else.
  *
- * When a later step fails, the error carries the finished step's task id and
- * the command that resumes from it, so a retry never re-runs — or re-bills —
- * work that already succeeded.
+ * Submission goes through the same journal → single POST → journal primitive
+ * as the resource commands (`submitCreate`), so there is one state machine for
+ * accepted / rejected / unknown and a local journal failure after acceptance is
+ * local_io with the known task id — never "unknown".
+ *
+ * Three ways to stop early, none of them a re-run:
+ *   --async             submit step 1 and return immediately (no polling);
+ *                       `pending_steps` lists what was not executed.
+ *   --stop-after-first  run step 1 to completion, then return the resume plan.
+ *   a failed later step keeps the finished step's task id and the command that
+ *                       resumes from it, so a retry never re-bills done work.
  */
 import { Command } from "commander";
 import { type MakePlan } from "../internal/make-plan.js";
+import { warning } from "../internal/result.js";
 import { type Runtime } from "../internal/runtime.js";
 export declare const makeCommand: Command;
 /**
@@ -28,4 +37,5 @@ export declare const makeCommand: Command;
  * consumes); the image route is a single task with nothing to resume.
  */
 export declare function resumeCommand(plan: MakePlan, completedTaskId: string, runtime: Runtime): string | undefined;
+export { warning as _makeWarning };
 //# sourceMappingURL=make.d.ts.map

package/dist/cmd/make.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make.d.ts","sourceRoot":"","sources":["../../src/cmd/make.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAK5C,OAAO,EAAY,KAAK,QAAQ,EAAiB,MAAM,0BAA0B,CAAC;AAIlF,OAAO,EAAiC,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAiBrF,eAAO,MAAM,WAAW,SAuCpB,CAAC;AAqGL;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,QAAQ,EACd,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,OAAO,GACf,MAAM,GAAG,SAAS,CAIpB"}
+{"version":3,"file":"make.d.ts","sourceRoot":"","sources":["../../src/cmd/make.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAM5C,OAAO,EAAY,KAAK,QAAQ,EAAiB,MAAM,0BAA0B,CAAC;AAMlF,OAAO,EAAc,OAAO,EAAgB,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAgB,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC;AA0BpE,eAAO,MAAM,WAAW,SAiDpB,CAAC;AAuSL;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,QAAQ,EACd,eAAe,EAAE,MAAM,EACvB,OAAO,EAAE,OAAO,GACf,MAAM,GAAG,SAAS,CAIpB;AAmFD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,CAAC"}

package/dist/cmd/make.js

@@ -14,21 +14,34 @@
  * someone else's credits on its own opinion. The resource commands remain the
  * way to compose anything else.
  *
- * When a later step fails, the error carries the finished step's task id and
- * the command that resumes from it, so a retry never re-runs — or re-bills —
- * work that already succeeded.
+ * Submission goes through the same journal → single POST → journal primitive
+ * as the resource commands (`submitCreate`), so there is one state machine for
+ * accepted / rejected / unknown and a local journal failure after acceptance is
+ * local_io with the known task id — never "unknown".
+ *
+ * Three ways to stop early, none of them a re-run:
+ *   --async             submit step 1 and return immediately (no polling);
+ *                       `pending_steps` lists what was not executed.
+ *   --stop-after-first  run step 1 to completion, then return the resume plan.
+ *   a failed later step keeps the finished step's task id and the command that
+ *                       resumes from it, so a retry never re-bills done work.
  */
 import { Command, Option } from "commander";
-import { HintedError, UsageError } from "../internal/errors.js";
+import { abortSignal, wasInterrupted } from "../internal/context.js";
+import { CliError, HintedError, UsageError } from "../internal/errors.js";
 import { parseInt10 } from "../internal/flags.js";
-import { resolveImageFields } from "../internal/file-input.js";
+import { normalizeMediaPayload } from "../internal/file-input.js";
 import { logger } from "../internal/logger.js";
 import { planMake } from "../internal/make-plan.js";
-import { emit } from "../internal/output.js";
-import { pollUntilTerminal } from "../internal/poll.js";
+import { emit, emitEnvelope } from "../internal/output.js";
+import { emitResult, openCommand } from "../internal/command-helpers.js";
+import { downloadArtifacts } from "../internal/download.js";
+import { parseTimeoutSeconds, pollUntilTerminal } from "../internal/poll.js";
 import { PRICING_DOCS } from "../internal/pricing.js";
-import { buildRuntime, readGlobalFlags } from "../internal/runtime.js";
-import { emitTerminalOutcome } from "../internal/task-command.js";
+import { okEnvelope, warning } from "../internal/result.js";
+import { buildRuntime } from "../internal/runtime.js";
+import { buildTaskResult, emitTerminalOutcome, preflightOutputPath, submitCreate, taskNextCommands, wrapWithResult, } from "../internal/task-command.js";
+import { requireTaskResource } from "../client/resource-registry.js";
 const DESCRIPTION = "Generate a 3D model in one command. A prompt runs the two-stage text flow " +
     "(preview then refine); an image runs the single textured image-to-3d task. " +
     "Use -o to download the result. Compose anything else from the resource commands";
@@ -38,11 +51,16 @@ export const makeCommand = new Command("make")
     .addOption(new Option("--dry-run", "print the planned steps and the estimate, then exit without calling the API").default(false))
     .addOption(new Option("--max-credits <n>", "refuse to start when the estimate exceeds this budget")
     .argParser(parseInt10))
-    .addOption(new Option("--async", "start the first step and return its task id instead of running the whole chain").default(false))
+    .addOption(new Option("--async", "submit the first step and return its task id immediately (no polling); later steps are reported as pending").default(false))
+    .addOption(new Option("--stop-after-first", "run the first step to completion, then return the resume plan instead of continuing").default(false))
     .addOption(new Option("--timeout <seconds>", "max seconds to poll each step").default("600"))
     .action(async (input, opts, thisCmd) => {
+    const opened = openCommand(thisCmd, "make", "legacy");
+    if (opts.async && opts.stopAfterFirst) {
+        throw new UsageError("--async and --stop-after-first are mutually exclusive (--async submits and returns; --stop-after-first waits for step 1)");
+    }
+    const timeoutSeconds = parseTimeoutSeconds(opts.timeout ?? "600");
     const plan = planMake(input);
-    const flags = readGlobalFlags(thisCmd);
     // Budget check before anything is created: refusing costs nothing, and a
     // refusal after step one has already billed is not a budget at all.
     if (opts.maxCredits !== undefined && plan.estimatedCredits > opts.maxCredits) {
@@ -50,41 +68,150 @@ export const makeCommand = new Command("make")
             `(${describeChain(plan)}). Nothing was started.`);
     }
     if (opts.dryRun) {
-        emit(planPayload(plan), { format: flags.format });
+        await emitResult(opened, planPayload(plan), { ...planPayload(plan), dry_run: true, requests_made: 0 });
         return;
     }
-    await runChain(plan, opts, await buildRuntime(flags));
+    await runChain(plan, opts, timeoutSeconds, await buildRuntime(opened.flags), opened);
 });
-async function runChain(plan, opts, runtime) {
-    const timeoutSeconds = Number(opts.timeout ?? 600);
+function pendingSteps(plan, from, parentTaskId, output) {
+    return plan.steps.slice(from).map((s) => ({
+        step: s.index,
+        resource: s.resource,
+        action: s.action,
+        estimated_credits: s.credits,
+        requires: `step ${s.index - 1} SUCCEEDED`,
+        command: s.resource === "text-to-3d" && s.action === "refine"
+            ? `meshy text-to-3d create --mode refine --preview-task-id ${parentTaskId ?? "<preview-task-id>"}${output ? ` -o ${output}` : ""}`
+            : null,
+    }));
+}
+async function runChain(plan, opts, timeoutSeconds, runtime, opened) {
     const payloadFor = await buildPayloads(plan);
+    // -o is checked before the first billable request: an unwritable or
+    // out-of-workspace target must refuse while the run is still free.
+    if (runtime.flags.output)
+        preflightOutputPath(runtime.flags.output, runtime.flags.workspaceRoot);
+    const executed = [];
+    const warnings = [];
     /** Task id of the last step that reached SUCCEEDED — what a resume hangs off. */
     let completedTaskId = "";
     for (const step of plan.steps) {
         const endpoint = endpointFor(step, runtime);
+        const descriptor = requireTaskResource(step.resource);
         const payload = payloadFor[step.index - 1]?.(completedTaskId) ?? {};
         logger.debug(`make step ${step.index} payload`, payload);
         // The id is announced before polling starts: an interrupted run leaves a
         // task progressing server-side, and the caller needs its id to exist
         // somewhere other than this process's memory.
-        const taskId = await endpoint.create(payload);
-        announceStart(plan, step, taskId);
-        const started = Date.now();
-        const { task, timedOut } = await pollUntilTerminal(endpoint, taskId, {
-            timeoutSeconds,
-            intervalMs: runtime.config.pollIntervalMs,
+        const submitted = await submitCreate(runtime, descriptor, endpoint, payload, null, {
+            label: `make: the ${step.label} request`,
+            extraResult: { step: step.index, route: plan.route, executed: [...executed] },
         });
-        const elapsed = (Date.now() - started) / 1000;
+        const { taskId, operationId } = submitted;
+        warnings.push(...submitted.warnings);
+        announceStart(plan, step, taskId);
+        executed.push({ step: step.index, resource: step.resource, action: step.action, task_id: taskId, status: null, operation_id: operationId });
+        const submission = { state: "accepted", operation_id: operationId, task_id: taskId };
+        if (opts.async) {
+            // Exactly one POST, zero polls: the caller owns the rest of the plan.
+            const pending = pendingSteps(plan, step.index, null, runtime.flags.output);
+            if (opened.schema === "v1") {
+                await emitEnvelope(okEnvelope("make", {
+                    route: plan.route,
+                    submitted: { step: step.index, resource: step.resource, action: step.action, task_id: taskId, operation_id: operationId },
+                    submission,
+                    task: null,
+                    executed,
+                    pending_steps: pending,
+                    estimated_credits: plan.estimatedCredits,
+                    next: taskNextCommands(descriptor, taskId),
+                }, warnings), opened.format);
+                return;
+            }
+            emit({
+                command: "make",
+                route: plan.route,
+                submitted: step.action,
+                task_id: taskId,
+                status: null,
+                operation_id: operationId,
+                pending_steps: pending,
+                hint: `meshy ${step.resource} wait ${taskId}`,
+            }, { format: runtime.flags.format });
+            return;
+        }
+        const started = performance.now();
+        let poll;
+        try {
+            poll = await pollUntilTerminal(endpoint, taskId, {
+                timeoutSeconds,
+                intervalMs: runtime.config.pollIntervalMs,
+                requestTimeoutMs: runtime.config.readTimeoutMs,
+                signal: abortSignal(),
+            });
+        }
+        catch (err) {
+            const context = {
+                route: plan.route,
+                executed,
+                task_id: taskId,
+                submission,
+                task: null,
+                pending_steps: pendingSteps(plan, step.index, null, runtime.flags.output),
+                next: taskNextCommands(descriptor, taskId),
+            };
+            if (wasInterrupted() || abortSignal().aborted) {
+                throw new CliError({
+                    code: "interrupted",
+                    message: `make: interrupted while waiting for ${step.label} (task ${taskId}); the server keeps running it`,
+                    recovery: { action: "wait", automatic: false, command: `meshy ${step.resource} wait ${taskId}` },
+                    result: context,
+                });
+            }
+            // A polling failure is not "no task": the id and the resume command travel with the error.
+            throw wrapWithResult(err, context);
+        }
+        const { task, raw, timedOut, aborted } = poll;
+        const elapsed = (performance.now() - started) / 1000;
+        executed[executed.length - 1].status = task?.status ?? null;
         announceOutcome(task, timedOut, elapsed);
-        if (timedOut || task.status !== "SUCCEEDED") {
-            throw stepFailure(plan, step, task, timedOut, completedTaskId, runtime);
+        if (aborted) {
+            throw new CliError({
+                code: "interrupted",
+                message: `make: interrupted while waiting for ${step.label} (task ${taskId}); the server keeps running it`,
+                recovery: { action: "wait", automatic: false, command: `meshy ${step.resource} wait ${taskId}` },
+                result: {
+                    route: plan.route,
+                    executed,
+                    task_id: taskId,
+                    submission,
+                    task: task ? buildTaskResult({ task, raw, descriptor, includeRaw: false, submission }).task : null,
+                    pending_steps: pendingSteps(plan, step.index, null, runtime.flags.output),
+                    next: taskNextCommands(descriptor, taskId),
+                },
+            });
+        }
+        if (timedOut || !task || task.status !== "SUCCEEDED") {
+            throw stepFailure(plan, step, task, taskId, raw, timedOut, completedTaskId, runtime, executed, opened);
         }
         if (step.index === plan.steps.length) {
-            await emitTerminalOutcome(task, false, elapsed, step.resource, runtime);
+            await finalOutcome(opened, runtime, plan, step, task, raw, elapsed, executed, warnings);
             return;
         }
         completedTaskId = task.id;
-        if (opts.async) {
+        if (opts.stopAfterFirst) {
+            const pending = pendingSteps(plan, step.index, task.id, runtime.flags.output);
+            if (opened.schema === "v1") {
+                await emitEnvelope(okEnvelope("make", {
+                    route: plan.route,
+                    stopped_after: { step: step.index, resource: step.resource, action: step.action, task_id: task.id, status: task.status },
+                    task: buildTaskResult({ task, raw, descriptor, includeRaw: false, submission }).task,
+                    executed,
+                    pending_steps: pending,
+                    resume: resumeCommand(plan, task.id, runtime) ?? null,
+                }, warnings), opened.format);
+                return;
+            }
             emit({
                 command: "make",
                 route: plan.route,
@@ -97,6 +224,64 @@ async function runChain(plan, opts, runtime) {
         }
     }
 }
+async function finalOutcome(opened, runtime, plan, step, task, raw, elapsed, executed, warnings) {
+    const descriptor = requireTaskResource(step.resource);
+    const submission = { state: "accepted", operation_id: executed[executed.length - 1]?.operation_id ?? null, task_id: task.id };
+    if (opened.schema !== "v1") {
+        // Legacy shape, same rule as the resource commands: a download failure
+        // after the chain succeeded still names the task, its submission and the
+        // command that fetches the assets again.
+        try {
+            await emitTerminalOutcome(task, false, elapsed, step.resource, runtime);
+        }
+        catch (err) {
+            const wrapped = wrapWithResult(err, { route: plan.route, executed, task_id: task.id, submission, next: taskNextCommands(descriptor, task.id) });
+            throw new CliError({
+                code: wrapped.code,
+                message: wrapped.message,
+                exitCode: wrapped.exitCode,
+                httpStatus: wrapped.httpStatus,
+                retryable: wrapped.retryable,
+                recovery: wrapped.recovery ?? { action: "download", automatic: false, command: `meshy download --resource ${step.resource} --task-id ${task.id} --all --output-dir <dir>` },
+                hint: wrapped.hint ?? wrapped.recovery?.command ?? `meshy download --resource ${step.resource} --task-id ${task.id} --all --output-dir <dir>`,
+                details: wrapped.details,
+                warnings: wrapped.warnings,
+                result: wrapped.result,
+                cause: err,
+            });
+        }
+        return;
+    }
+    const base = buildTaskResult({ task, raw, descriptor, includeRaw: false, submission });
+    let downloads = base.downloads;
+    if (runtime.flags.output) {
+        try {
+            const { files, metadataPath, materialLinks } = await downloadArtifacts(task, runtime.flags.output, step.resource, { root: runtime.flags.workspaceRoot, signal: abortSignal() });
+            if (materialLinks)
+                warnings.push(...materialLinks.warnings);
+            downloads = { state: "completed", files: files.map((f) => ({ key: f.key, path: f.path, status: f.status, bytes: f.bytes, sha256: f.sha256, error: f.error })), metadata_path: metadataPath, material_links: materialLinks };
+        }
+        catch (err) {
+            // Whatever the downloader already committed stays in the manifest; the
+            // failure keeps its own class (HTTP status, interrupted, local I/O).
+            const partial = err instanceof CliError && err.result && typeof err.result["downloads"] === "object" ? err.result["downloads"] : { state: "failed", files: [], metadata_path: null };
+            const interrupted = (err instanceof CliError && err.code === "interrupted") || wasInterrupted();
+            throw new CliError({
+                code: interrupted ? "interrupted" : err instanceof CliError ? err.code : "local_io",
+                message: `make finished (task ${task.id}) but downloading its assets ${interrupted ? "was interrupted" : "failed"}: ${err instanceof Error ? err.message : String(err)}`,
+                httpStatus: err instanceof CliError ? err.httpStatus : null,
+                retryable: err instanceof CliError ? err.retryable : false,
+                recovery: err instanceof CliError && err.recovery ? err.recovery : { action: "download", automatic: false, command: `meshy download --resource ${step.resource} --task-id ${task.id} --all --output-dir <dir>` },
+                hint: err instanceof CliError ? err.hint : undefined,
+                details: err instanceof CliError ? err.details : undefined,
+                warnings: [...warnings, ...(err instanceof CliError ? err.warnings : [])],
+                result: { route: plan.route, executed, task_id: task.id, task: base.task, submission: base.submission, downloads: partial, next: taskNextCommands(descriptor, task.id) },
+                cause: err,
+            });
+        }
+    }
+    await emitEnvelope(okEnvelope("make", { route: plan.route, executed, task: base.task, submission: base.submission, downloads, pending_steps: [] }, warnings), opened.format);
+}
 /**
  * One payload builder per step, taking the previous step's task id so the
  * chain stays a function of the plan plus what actually ran.
@@ -120,11 +305,10 @@ async function buildPayloads(plan) {
     }
     // Resolve the image before anything is created: a missing file or an
     // unreachable URL must fail while the run is still free.
-    const resolved = { imageUrl: plan.input };
-    await resolveImageFields(resolved);
+    const { payload } = await normalizeMediaPayload({ image_url: plan.input }, requireTaskResource("image-to-3d").mediaFields, { signal: abortSignal() });
     return [
         () => ({
-            image_url: resolved.imageUrl,
+            image_url: payload.image_url,
             should_texture: true,
             enable_pbr: true,
             texture_resolution: "4k",
@@ -147,22 +331,41 @@ export function resumeCommand(plan, completedTaskId, runtime) {
     const output = runtime.flags.output ? ` -o ${runtime.flags.output}` : "";
     return `meshy text-to-3d create --mode refine --preview-task-id ${completedTaskId}${output}`;
 }
-function stepFailure(plan, step, task, timedOut, completedTaskId, runtime) {
+function stepFailure(plan, step, task, taskId, raw, timedOut, completedTaskId, runtime, executed, opened) {
+    const descriptor = requireTaskResource(step.resource);
+    const taskView = task ? buildTaskResult({ task, raw, descriptor, includeRaw: false, submission: { state: "accepted", operation_id: null, task_id: taskId } }).task : null;
+    const resume = resumeCommand(plan, completedTaskId, runtime);
+    const status = task?.status ?? "unknown";
+    if (opened.schema === "v1") {
+        if (timedOut) {
+            return new CliError({
+                code: "timed_out",
+                message: `make: ${step.label} did not finish within the timeout — task ${taskId} is still running`,
+                recovery: { action: "wait", automatic: false, command: `meshy ${step.resource} wait ${taskId}` },
+                result: { route: plan.route, executed, task_id: taskId, task: taskView, pending_steps: pendingSteps(plan, step.index, null, runtime.flags.output), resume: resume ?? null, next: taskNextCommands(descriptor, taskId) },
+            });
+        }
+        return new CliError({
+            code: "task_failed",
+            message: task?.task_error?.message || `make: ${step.label} ended as ${status} — task ${taskId}`,
+            recovery: resume ? { action: "resume", automatic: false, command: resume } : null,
+            result: { route: plan.route, executed, task_id: taskId, task: taskView, pending_steps: pendingSteps(plan, step.index, completedTaskId || null, runtime.flags.output), resume: resume ?? null },
+        });
+    }
     if (timedOut) {
         return new HintedError({
-            message: `make: ${step.label} did not finish within the timeout — task ${task.id} is still running`,
+            message: `make: ${step.label} did not finish within the timeout — task ${taskId} is still running`,
             code: "step_timeout",
-            hint: `meshy ${step.resource} wait ${task.id}`,
+            hint: `meshy ${step.resource} wait ${taskId}`,
             exitCode: 8,
         });
     }
     // A resume is only offered when an earlier step actually succeeded; without
     // one, a suggested command would be a guess, and a wrong command is worse
     // than none.
-    const resume = resumeCommand(plan, completedTaskId, runtime);
     return new HintedError({
-        message: task.task_error?.message ||
-            `make: ${step.label} ended as ${task.status} — task ${task.id}`,
+        message: task?.task_error?.message ||
+            `make: ${step.label} ended as ${status} — task ${taskId}`,
         code: "step_failed",
         ...(resume ? { hint: `${resume}   # step ${step.index} failed; step ${step.index - 1} is kept` } : {}),
     });
@@ -189,7 +392,8 @@ function announceStart(plan, step, taskId) {
     process.stderr.write(`[${step.index}/${plan.steps.length}] ${step.label}  ${taskId}\n`);
 }
 function announceOutcome(task, timedOut, elapsed) {
-    const mark = timedOut ? "timed out" : task.status === "SUCCEEDED" ? "ok" : task.status;
+    const mark = timedOut ? "timed out" : task ? (task.status === "SUCCEEDED" ? "ok" : task.status) : "no status received";
     process.stderr.write(`      ${mark} in ${elapsed.toFixed(0)}s\n`);
 }
+export { warning as _makeWarning };
 //# sourceMappingURL=make.js.map