@assethub/cli 0.1.17 → 0.1.19

package/dist/index.js

@@ -2,6 +2,8 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { cliVersion, diagnose, mcpConfig } from './setup.js';
 import { ingestProjectSources } from './projectSources.js';
+import { downloadCanvas } from './canvasDownload.js';
+import { executeNodeMeshBatch, resumeNodeMeshBatch, } from './nodeMeshBatch.js';
 import { writeCanvasComparison } from './canvasComparison.js';
 import { importCanvasAssetWithState } from './canvasAssetImport.js';
 import { execFile, spawn } from 'node:child_process';
@@ -15,7 +17,7 @@ import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 import { AssetHubApiError, WorkspaceClientError, createWorkspaceClient, createAssetHubClient, } from '@assethub/api-client';
 import { resolveCanvasSelection, saveCanvasSelection } from './canvas.js';
-import { activeExecution, CliExecutionError, executeRecorded, hasRecordedOperation, openExecutionSession, resumeRecorded, waitForExecution, } from './execution.js';
+import { activeExecution, childOperationId, CliExecutionError, executeRecorded, hasRecordedOperation, openExecutionSession, resumeRecorded, waitForExecution, } from './execution.js';
 import { buildRunUploadPlan, formatBytes } from './runsUpload/buildRunUpload.js';
 import { readGraphFolder } from './runsUpload/graphFolder.js';
 import { uploadRun } from './runsUpload/uploadRun.js';
@@ -90,7 +92,8 @@ Usage:
   assethub auth login --access-token-stdin [--base-url <url>] [--profile <name>]
   assethub auth status [--profile <name>]
   assethub auth logout [--profile <name>]
-  assethub workspace list|get
+  assethub workspace list [--query <text>] [--limit <1-100>] [--cursor <cursor>]
+  assethub workspace get
   assethub workspace create --name <name> [--operation-id <uuid>]
   assethub workspace use <workspace-id>
   assethub workspace members [--workspace <id>]
@@ -103,6 +106,8 @@ Usage:
   assethub workspace context get --internal --org <uuid> --actor <uuid> --canvas <id> [--out <json>] [--order <uuid>]
   assethub project ingest <source-dir> --out-dir <directory> [--exclude-dir <relative-path>...]
   assethub language text|vision --input-json @<json> --operation-id <uuid> [--out <json>]
+  assethub canvas download --canvas <id> --out-dir <directory> [--mesh <mesh_asset_id>]
+  assethub canvas nodes --canvas <id>
   assethub canvas import --canvas <id> --file <image> [--name <name>]
   assethub canvas context get --canvas <id> [--out <json>]
   assethub canvas context put --canvas <id> --file <json> [--if-version <n>]
@@ -125,6 +130,7 @@ Usage:
   assethub composer run --part <mesh-asset-id> [--part <mesh-asset-id>...] --reference <image-asset-id> [--model <id>] [--mode quick|quality] [--transforms-json <json|@file>] [--canvas <id>] [--wait]
   assethub composer run --input-json <json|@file> [--canvas <id>] [--operation-id <uuid>] [--wait] [--download --out-dir <dir>]
   assethub composer run --from-run <run-id> [--transforms-json <json|@file>] [--mode quick|quality] [--wait]
+  assethub composer run --node <shape:id> --canvas <id> [--model <id>] [--mode quick|quality] [--operation-id <uuid>] [--wait]
   assethub canvas create [--name <name>] [--operation-id <uuid>]
   assethub canvas list [--cursor <cursor>] [--limit <n>]
   assethub canvas get|use|open [<id>]
@@ -140,6 +146,7 @@ Usage:
   assethub evaluations get <evaluation-id>
   assethub image generate --input-json <json|@file|@-> [--canvas <id>] [--operation-id <uuid>] [--agent <name>] [--derived-from-run <run-id>] [--from-node <graphId/nodeId> --graph-revision <rev>] [--wait]
   assethub mesh generate --input-json <json|@file|@-> [--canvas <id>] [--operation-id <uuid>] [--agent <name>] [--derived-from-run <run-id>] [--from-node <graphId/nodeId> --graph-revision <rev>] [--wait]
+  assethub mesh generate --node <shape:id> --canvas <id> [--model-id <id>] [--params-json <json|@file>] [--operation-id <uuid>] [--wait]
   assethub mesh list [--query <text>] [--cursor <cursor>] [--limit <n>]
   assethub mesh get <mesh-asset-id>
   assethub mesh download <mesh-asset-id> --out-dir <directory>
@@ -171,6 +178,7 @@ Global options:
   --api-key <key>       Overrides saved auth and ASSETHUB_API_KEY.
   --base-url <url>      Override the selected API origin. Default: ${defaultBaseUrl}.
   --profile <name>      Select this saved profile ahead of environment credentials and origin.
+  --workspace <id>      Select workspace scope for this command without changing saved selection.
   --config <path>       Auth config path. Defaults to ~/.assethub/config.json.
   --version             Show installed package version.
   --help                Show help.
@@ -432,7 +440,7 @@ const resolveAuth = async (flags) => {
         : undefined;
     const profile = explicitProfile ?? config?.defaultProfile ?? defaultProfileName;
     const storedProfile = config?.profiles?.[profile];
-    const selected = Boolean(explicitProfile || storedProfile?.workspaceId);
+    const selected = Boolean(explicitProfile || storedProfile?.workspaceId || storedProfile?.apiKey?.startsWith('ah_pat_'));
     if (selected && (!storedProfile || (!storedProfile.apiKey && !overrideKey)))
         throw new Error('Selected profile has no workspace API key. Use workspace use <id> or auth login --api-key-stdin --profile <name>.');
     const baseUrl = getFlag(flags, 'base-url') ??
@@ -440,17 +448,17 @@ const resolveAuth = async (flags) => {
             ? storedProfile.baseUrl
             : env.ASSETHUB_API_BASE_URL ?? storedProfile?.baseUrl ?? defaultBaseUrl);
     if (overrideKey)
-        return { apiKey: overrideKey, baseUrl, profile, source: 'flag' };
+        return { apiKey: overrideKey, baseUrl, profile, source: 'flag', workspaceId: getFlag(flags, 'workspace') };
     if (selected && storedProfile?.apiKey) {
-        if (storedProfile.workspaceId &&
+        if ((storedProfile.workspaceId || storedProfile.apiKey.startsWith('ah_pat_')) &&
             new URL(baseUrl).origin !== new URL(storedProfile.baseUrl).origin)
             throw new Error('Selected workspace belongs to another API origin; select a workspace for this origin or supply an explicit API key');
-        return { apiKey: storedProfile.apiKey, baseUrl, profile, source: 'profile' };
+        return { apiKey: storedProfile.apiKey, baseUrl, profile, source: 'profile', workspaceId: getFlag(flags, 'workspace') ?? storedProfile.workspaceId };
     }
     if (env.ASSETHUB_API_KEY?.trim())
-        return { apiKey: env.ASSETHUB_API_KEY, baseUrl, profile, source: 'env' };
+        return { apiKey: env.ASSETHUB_API_KEY, baseUrl, profile, source: 'env', workspaceId: getFlag(flags, 'workspace') };
     if (storedProfile?.apiKey)
-        return { apiKey: storedProfile.apiKey, baseUrl, profile, source: 'profile' };
+        return { apiKey: storedProfile.apiKey, baseUrl, profile, source: 'profile', workspaceId: getFlag(flags, 'workspace') ?? storedProfile.workspaceId };
     throw new Error('Missing workspace API key. Use "workspace use <id>" after user login, "auth login --api-key-stdin", or ASSETHUB_API_KEY.');
 };
 const createContext = async (flags, args) => {
@@ -462,6 +470,7 @@ const createContext = async (flags, args) => {
         client: createAssetHubClient({
             apiKey: auth.apiKey,
             baseUrl: auth.baseUrl,
+            workspaceId: auth.workspaceId,
         }),
     };
 };
@@ -1241,12 +1250,25 @@ const commandModels = async (subcommand, positionals, ctx) => {
     }
     throw new Error('Unknown models command. Use "models list" or "models get".');
 };
-const workspaceAuth = async (flags) => {
+const workspaceAuth = async (flags, allowPersonal = false) => {
     const configPath = getConfigPath(flags);
     const config = await readAuthConfig(configPath);
     const explicitProfile = hasFlag(flags, 'profile') ? requireFlag(flags, 'profile') : undefined;
     const profile = explicitProfile ?? config.defaultProfile ?? defaultProfileName;
     const stored = config.profiles?.[profile];
+    const preferredKey = getFlag(flags, 'api-key') ??
+        (explicitProfile || stored?.workspaceId || stored?.apiKey?.startsWith('ah_pat_')
+            ? stored?.apiKey
+            : env.ASSETHUB_API_KEY?.trim() || stored?.apiKey);
+    if (allowPersonal && preferredKey?.startsWith('ah_pat_')) {
+        const auth = await resolveAuth(flags);
+        return {
+            configPath, config, profile, accessToken: auth.apiKey,
+            workspaceMfaToken: undefined, baseUrl: auth.baseUrl,
+            selectedWorkspaceId: auth.workspaceId, personal: true,
+            client: createWorkspaceClient({ accessToken: auth.apiKey, baseUrl: auth.baseUrl, workspaceId: auth.workspaceId }),
+        };
+    }
     const environmentToken = explicitProfile ? undefined : env.ASSETHUB_ACCESS_TOKEN?.trim();
     const accessToken = environmentToken || stored?.accessToken;
     if (!accessToken)
@@ -1270,6 +1292,7 @@ const workspaceAuth = async (flags) => {
         workspaceMfaToken,
         baseUrl,
         selectedWorkspaceId: environmentToken ? undefined : stored?.workspaceId,
+        personal: false,
         client: createWorkspaceClient({ accessToken, workspaceMfaToken, baseUrl }),
     };
 };
@@ -1279,7 +1302,7 @@ const commandWorkspace = async (subcommand, positionals, flags) => {
         : hasFlag(flags, 'profile')
             ? undefined
             : env.ASSETHUB_API_KEY?.trim();
-    const auth = await workspaceAuth(flags);
+    const auth = await workspaceAuth(flags, ['list', 'get', 'use'].includes(subcommand ?? ''));
     if (['members', 'invite', 'set-role', 'remove-member'].includes(subcommand ?? '')) {
         let workspaceId = getFlag(flags, 'workspace') ?? auth.selectedWorkspaceId;
         if (!workspaceId)
@@ -1303,10 +1326,21 @@ const commandWorkspace = async (subcommand, positionals, flags) => {
         return;
     }
     if (subcommand === 'list') {
-        print(await auth.client.list());
+        print(await auth.client.list({
+            query: getFlag(flags, 'query'),
+            cursor: getFlag(flags, 'cursor'),
+            limit: hasFlag(flags, 'limit') ? parsePositiveIntegerFlag(flags, 'limit', 100) : undefined,
+        }));
         return;
     }
     if (subcommand === 'get') {
+        if (auth.personal && auth.selectedWorkspaceId) {
+            const selected = await auth.client.select(auth.selectedWorkspaceId);
+            if (!selected.workspace)
+                throw new Error('Workspace API returned no selected workspace');
+            print(selected.workspace);
+            return;
+        }
         const account = await auth.client.list();
         const selected = auth.selectedWorkspaceId;
         const workspace = account.workspaces.find(item => selected ? item.id === selected : item.active);
@@ -1331,18 +1365,34 @@ const commandWorkspace = async (subcommand, positionals, flags) => {
         throw new Error('Use workspace list|get|create|use');
     const workspaceId = requirePositional(positionals, 2, 'workspace-id');
     const selected = await auth.client.select(workspaceId);
+    if (selected.workspaceId !== workspaceId)
+        throw new Error('Workspace API returned an invalid selection scope');
     if (selected.mfa.status === 'setup_required' ||
         selected.mfa.status === 'verify_required')
         throw new Error('Workspace requires MFA. Complete verification in AssetHub, then provide the signed ah_workspace_mfa cookie through ASSETHUB_WORKSPACE_MFA together with your user access token');
     const account = await auth.client.list();
-    const workspace = account.workspaces.find(item => item.id === workspaceId);
+    const workspace = selected.workspace ?? account.workspaces.find(item => item.id === workspaceId);
     if (!workspace)
         throw new Error('Workspace is not available to this authenticated user');
     const profiles = auth.config.profiles ?? {};
+    if (auth.personal) {
+        if (account.authentication !== 'personal')
+            throw new Error('Workspace API did not verify personal authentication');
+        profiles[auth.profile] = {
+            apiKey: auth.accessToken,
+            userId: account.userId,
+            workspaceId,
+            baseUrl: auth.baseUrl,
+            updatedAt: new Date().toISOString(),
+        };
+        await writeAuthConfig(auth.configPath, { ...auth.config, defaultProfile: auth.profile, profiles });
+        print({ workspaceId, workspace, profile: auth.profile, selected: true, baseUrl: auth.baseUrl });
+        return;
+    }
     const cached = Object.entries(profiles).find(([, entry]) => entry.userId === account.userId &&
         entry.workspaceId === workspaceId &&
         new URL(entry.baseUrl).origin === new URL(auth.baseUrl).origin &&
-        entry.apiKey);
+        entry.apiKey && !entry.apiKey.startsWith('ah_pat_'));
     let apiKey;
     for (const candidate of new Set([cached?.[1].apiKey, suppliedKey])) {
         if (!candidate)
@@ -1445,7 +1495,13 @@ const commandAuth = async (subcommand, flags) => {
             throw new Error('API key is empty. Pass --api-key, use --api-key-stdin, or set ASSETHUB_API_KEY.');
         }
         const baseUrl = getFlag(flags, 'base-url') ?? env.ASSETHUB_API_BASE_URL ?? defaultBaseUrl;
-        if (!hasFlag(flags, 'skip-verify')) {
+        const personal = apiKey.startsWith('ah_pat_');
+        const account = personal
+            ? await createWorkspaceClient({ accessToken: apiKey, baseUrl }).list()
+            : undefined;
+        if (personal && account?.authentication !== 'personal')
+            throw new Error('Workspace API did not verify personal authentication');
+        if (!personal && !hasFlag(flags, 'skip-verify')) {
             const client = createAssetHubClient({ apiKey, baseUrl });
             await client.v2.listModels();
         }
@@ -1454,6 +1510,7 @@ const commandAuth = async (subcommand, flags) => {
         profiles[profile] = {
             apiKey,
             baseUrl,
+            ...(account ? { userId: account.userId } : {}),
             updatedAt: new Date().toISOString(),
         };
         await writeAuthConfig(configPath, {
@@ -1466,15 +1523,19 @@ const commandAuth = async (subcommand, flags) => {
             profile,
             baseUrl,
             configPath,
-            verified: !hasFlag(flags, 'skip-verify'),
+            verified: personal || !hasFlag(flags, 'skip-verify'),
+            ...(account ? { authentication: 'personal', userId: account.userId } : {}),
         });
         return;
     }
     if (subcommand === 'status') {
         const config = await readAuthConfig(configPath);
         const current = config.profiles?.[getFlag(flags, 'profile') ?? config.defaultProfile ?? profile];
-        if ((!hasFlag(flags, 'profile') && env.ASSETHUB_ACCESS_TOKEN?.trim()) ||
-            (current?.accessToken && !current.apiKey)) {
+        if (!hasFlag(flags, 'api-key') &&
+            !current?.apiKey?.startsWith('ah_pat_') &&
+            (hasFlag(flags, 'profile') || !env.ASSETHUB_API_KEY?.startsWith('ah_pat_')) &&
+            ((!hasFlag(flags, 'profile') && env.ASSETHUB_ACCESS_TOKEN?.trim()) ||
+                (current?.accessToken && !current.apiKey))) {
             const auth = await workspaceAuth(flags);
             const account = await auth.client.list();
             print({
@@ -1491,7 +1552,18 @@ const commandAuth = async (subcommand, flags) => {
         const client = createAssetHubClient({
             apiKey: auth.apiKey,
             baseUrl: auth.baseUrl,
+            workspaceId: auth.workspaceId,
         });
+        if (auth.apiKey.startsWith('ah_pat_')) {
+            const account = await createWorkspaceClient({ accessToken: auth.apiKey, baseUrl: auth.baseUrl, workspaceId: auth.workspaceId }).list();
+            if (account.authentication !== 'personal')
+                throw new Error('Workspace API did not verify personal authentication');
+            if (auth.workspaceId)
+                await client.v2.getCapabilities();
+            print({ authenticated: true, authentication: 'personal', userId: account.userId, workspaceId: auth.workspaceId,
+                profile: auth.profile, source: auth.source, baseUrl: auth.baseUrl });
+            return;
+        }
         const models = await client.v2.listModels();
         print({
             authenticated: true,
@@ -1637,6 +1709,134 @@ const printRecorded = async (ctx, queued) => {
     });
     process.exitCode = executionExitCode(execution);
 };
+const canvasNodeFlag = (flags) => {
+    if (!hasFlag(flags, 'node'))
+        return undefined;
+    const nodeId = requireFlag(flags, 'node');
+    if (!nodeId.startsWith('shape:') || nodeId.length <= 6)
+        throw new Error('--node must be a native shape:<id> from canvas nodes');
+    if (sourceInputCount(flags) ||
+        [
+            'input-json',
+            'upload-id',
+            'from-node',
+            'graph-revision',
+            'from-run',
+            'part',
+            'reference',
+            'transforms-json',
+        ].some(name => hasFlag(flags, name)))
+        throw new Error('--node cannot be combined with explicit sources, parts, reference, input JSON, or another node/run selector');
+    return nodeId;
+};
+const printNodeMeshBatch = async (ctx, batch) => {
+    const executions = [...batch.executions];
+    if (hasFlag(ctx.flags, 'wait')) {
+        try {
+            for (let i = 0; i < executions.length; i++)
+                executions[i] = await waitForExecution(ctx.client, executions[i].runId, watchOptions(ctx.flags));
+        }
+        catch (error) {
+            if (!(error instanceof CliExecutionError))
+                throw error;
+            throw new CliExecutionError(error.message, error.exitCode, batch.operationId, error.execution, error.runId);
+        }
+    }
+    const downloads = await maybeDownloadUrls(ctx.flags, executions.flatMap(execution => execution.outputs));
+    print({ ...batch, executions, ...(downloads ? { downloads } : {}) });
+    process.exitCode = Math.max(0, ...executions.map(executionExitCode));
+};
+const commandNodeMesh = async (ctx, nodeId) => {
+    const body = {};
+    const modelId = getFlag(ctx.flags, 'model-id');
+    if (modelId)
+        body.modelId = modelId;
+    const name = getFlag(ctx.flags, 'name');
+    if (name)
+        body.name = name;
+    if (hasFlag(ctx.flags, 'face-limit'))
+        body.faceLimit = parsePositiveIntegerFlag(ctx.flags, 'face-limit', 1);
+    if (hasFlag(ctx.flags, 'low-poly'))
+        body.isLowPoly = parseBooleanFlag(ctx.flags, 'low-poly');
+    if (hasFlag(ctx.flags, 'params-json')) {
+        const params = await readJsonArgument(requireFlag(ctx.flags, 'params-json'), '--params-json');
+        if (Object.values(params).some(value => typeof value !== 'string' &&
+            typeof value !== 'boolean' &&
+            !(typeof value === 'number' && Number.isFinite(value))))
+            throw new Error('--params-json values must be strings, booleans, or finite numbers');
+        body.params = params;
+    }
+    const operationId = getFlag(ctx.flags, 'operation-id');
+    const canvasId = selectedCanvasId(ctx.flags);
+    const resumeOptions = {
+        ...stateOptions(ctx),
+        expectedCanvasId: canvasId,
+        expectedCanvasNodeId: nodeId,
+        expectedBody: body,
+    };
+    if (operationId) {
+        const batch = await resumeNodeMeshBatch({ ...resumeOptions, operationId });
+        if (batch) {
+            await printNodeMeshBatch(ctx, batch);
+            return;
+        }
+        if (await hasRecordedOperation(resumeOptions.stateDir, operationId)) {
+            await printRecorded(ctx, await resumeRecorded({
+                ...resumeOptions,
+                operationId,
+                expectedOperation: 'mesh.generate',
+            }));
+            return;
+        }
+    }
+    const session = await openExecutionSession({
+        ...stateOptions(ctx),
+        canvasId,
+        operation: 'mesh.generate',
+        create: false,
+    });
+    const { items } = await ctx.client.v2.listCanvasNodes(session.canvas.id);
+    const target = items.find(item => item.nodeId === nodeId);
+    if (!target)
+        throw new Error('Canvas node is unavailable; read canvas nodes again');
+    const finishedOrBusy = (status) => ['complete', 'completed', 'generating'].includes(status ?? '');
+    if (target.type === 'production-3d') {
+        if (!target.actions.includes('mesh.generate'))
+            throw new Error('Mesh generation is unavailable for this node');
+        const children = items.filter(item => item.sourceNodeId === nodeId &&
+            ['mesh-gen', 'preview-asset', 'part-group'].includes(item.type));
+        if (!children.length)
+            throw new Error('Production node has no saved part nodes to generate');
+        const pending = children.filter(item => item.actions.includes('mesh.generate') &&
+            !finishedOrBusy(item.meshStatus));
+        const batchId = operationId ?? randomUUID();
+        stderr.write(`[nodes] batch ${batchId}\n`);
+        await printNodeMeshBatch(ctx, await executeNodeMeshBatch(session, {
+            ...executionOptions(ctx.flags),
+            operationId: batchId,
+            nodeId,
+            body,
+            children: pending.map(item => item.nodeId),
+            skipped: children
+                .filter(item => !pending.includes(item))
+                .map(({ nodeId, meshStatus }) => ({ nodeId, meshStatus })),
+        }));
+        return;
+    }
+    if (!['mesh-gen', 'preview-asset', 'part-group'].includes(target.type))
+        throw new Error('This canvas node cannot generate a mesh');
+    if (target.meshStatus === 'generating' ||
+        (target.type !== 'mesh-gen' && finishedOrBusy(target.meshStatus))) {
+        print({ nodeId, skipped: true, meshStatus: target.meshStatus });
+        return;
+    }
+    if (!target.actions.includes('mesh.generate'))
+        throw new Error('Mesh generation is unavailable for this node');
+    await printRecorded(ctx, await executeRecorded(session, 'mesh.generate', body, {
+        ...executionOptions(ctx.flags),
+        canvasNode: { nodeId },
+    }));
+};
 const commandImage = async (subcommand, ctx) => {
     if (subcommand !== 'generate')
         throw new Error('Unknown image command. Use "image generate".');
@@ -1744,6 +1944,54 @@ const refinementModeInfo = (capabilities, mode) => {
         throw new Error(`Refinement mode ${mode} is unavailable${info.reason ? `: ${info.reason}` : ''}`);
     return info;
 };
+/** Reuse the frozen sources and latest editable scene, never replay server-only receipt fields. */
+const composerInputFromRun = (previous, operation) => {
+    const source = previous.resolvedInput ?? previous.input ?? previous.requestedInput ?? {};
+    const fields = operation === 'mesh.compose'
+        ? [
+            'fullBodyImageAssetId',
+            'agentVersion',
+            'agentRuntime',
+            'mode',
+            'targetCharacterHeightM',
+            'projectName',
+            'decimateRatio',
+            'quickRunId',
+            'quickScene',
+        ]
+        : ['fullBodyImageAssetId', 'agentRuntime', 'mode', 'instruction', 'maxRounds'];
+    const input = Object.fromEntries(fields
+        .filter(key => source[key] !== undefined)
+        .map(key => [key, source[key]]));
+    const parts = previous.composition?.parts ?? source.parts;
+    const partFields = operation === 'mesh.compose'
+        ? ['assetId', 'name', 'canonicalKey', 'partImageAssetId', 'partTaskId']
+        : [
+            'assetId',
+            'name',
+            'canonicalKey',
+            'volumeCentroid',
+            'sourceAssetId',
+            'transform',
+        ];
+    input.parts = Array.isArray(parts)
+        ? parts.map(part => part && typeof part === 'object'
+            ? Object.fromEntries(Object.entries(part).filter(([key]) => partFields.includes(key)))
+            : part)
+        : parts;
+    const transforms = previous.composition?.transforms ?? source.transforms;
+    if (transforms != null)
+        input.transforms = transforms;
+    if (operation === 'mesh.refine') {
+        const referenceTransform = previous.composition?.referenceTransform ?? source.referenceTransform;
+        if (referenceTransform != null)
+            input.referenceTransform = referenceTransform;
+        // Compose modes are not refinement modes; preserve a prior refinement's mode only.
+        if (previous.operation !== 'mesh.refine')
+            delete input.mode;
+    }
+    return input;
+};
 const commandComposerRefine = async (ctx) => {
     const capabilities = await ctx.client.v2.getMeshRefinementModes();
     if (hasFlag(ctx.flags, 'list-modes')) {
@@ -1767,20 +2015,7 @@ const commandComposerRefine = async (ctx) => {
     const input = json
         ? await readJsonArgument(json, '--input-json')
         : previous
-            ? {
-                ...(previous.requestedInput ?? previous.input),
-                ...(previous.operation === 'mesh.refine' &&
-                    (previous.requestedInput?.mode ?? previous.input.mode)
-                    ? { mode: previous.requestedInput?.mode ?? previous.input.mode }
-                    : { mode: undefined }),
-                parts: previous.composition?.parts ??
-                    previous.requestedInput?.parts ??
-                    previous.input.parts,
-                transforms: previous.composition?.transforms,
-                referenceTransform: previous.composition?.referenceTransform ??
-                    previous.requestedInput?.referenceTransform ??
-                    previous.input.referenceTransform,
-            }
+            ? composerInputFromRun(previous, 'mesh.refine')
             : {
                 parts: parts.map(assetId => ({
                     assetId: assertFlagHasValue(assetId, '--part <asset-id>'),
@@ -1848,6 +2083,9 @@ const commandComposerRefine = async (ctx) => {
         mode,
         instruction,
         ...(maxRounds != null ? { maxRounds } : {}),
+        ...(input.agentRuntime
+            ? { agentRuntime: input.agentRuntime }
+            : {}),
     };
     await printRecorded(ctx, await executeRecorded(session, 'mesh.refine', body, {
         ...executionOptions(ctx.flags),
@@ -1865,6 +2103,7 @@ const commandComposer = async (subcommand, ctx) => {
     }
     if (subcommand !== 'run')
         throw new Error('Use composer models|run');
+    const nodeId = canvasNodeFlag(ctx.flags);
     const fromRun = getFlag(ctx.flags, 'from-run');
     const json = getFlag(ctx.flags, 'input-json');
     const parts = getFlagValues(ctx.flags, 'part');
@@ -1874,20 +2113,23 @@ const commandComposer = async (subcommand, ctx) => {
     const previous = fromRun ? await ctx.client.v2.getRun(fromRun) : undefined;
     if (previous && previous.operation !== 'mesh.compose')
         throw new Error('--from-run must identify a mesh.compose execution');
-    const input = previous
-        ? { ...(previous.requestedInput ?? previous.input) }
-        : json
-            ? await readJsonArgument(json, '--input-json')
-            : {
-                parts: parts.map(assetId => ({
-                    assetId: assertFlagHasValue(assetId, '--part <asset-id>'),
-                })),
-                fullBodyImageAssetId: requireFlag(ctx.flags, 'reference'),
-            };
+    const input = nodeId
+        ? {}
+        : previous
+            ? composerInputFromRun(previous, 'mesh.compose')
+            : json
+                ? await readJsonArgument(json, '--input-json')
+                : {
+                    parts: parts.map(assetId => ({
+                        assetId: assertFlagHasValue(assetId, '--part <asset-id>'),
+                    })),
+                    fullBodyImageAssetId: requireFlag(ctx.flags, 'reference'),
+                };
     delete input.executionContext;
-    if (!Array.isArray(input.parts) ||
-        !input.parts.length ||
-        !input.fullBodyImageAssetId)
+    if (!nodeId &&
+        (!Array.isArray(input.parts) ||
+            !input.parts.length ||
+            !input.fullBodyImageAssetId))
         throw new Error('Composer requires parts[] and fullBodyImageAssetId');
     const mode = getFlag(ctx.flags, 'mode');
     if (mode != null && mode !== 'quick' && mode !== 'quality')
@@ -1903,17 +2145,48 @@ const commandComposer = async (subcommand, ctx) => {
     const transforms = getFlag(ctx.flags, 'transforms-json');
     if (transforms)
         input.transforms = await readJsonArgument(transforms, '--transforms-json');
+    if (previous && input.transforms) {
+        delete input.quickRunId;
+        delete input.quickScene;
+    }
     const canvasId = selectedCanvasId(ctx.flags) ?? previous?.canvas.id;
     if (previous && canvasId !== previous.canvas.id)
         throw new Error('Recomposition must use the original canvas to retain lineage');
+    const operationId = getFlag(ctx.flags, 'operation-id');
+    if (nodeId && operationId) {
+        const resumeOptions = {
+            ...stateOptions(ctx),
+            operationId,
+            expectedCanvasId: canvasId,
+            expectedCanvasNodeId: nodeId,
+            expectedOperation: 'mesh.compose',
+            expectedBody: input,
+        };
+        // A mesh batch reserves its root key even though its paid requests have child keys.
+        await resumeNodeMeshBatch(resumeOptions);
+        if (await hasRecordedOperation(resumeOptions.stateDir, operationId)) {
+            await printRecorded(ctx, await resumeRecorded(resumeOptions));
+            return;
+        }
+    }
     const session = await openExecutionSession({
         ...stateOptions(ctx),
         canvasId,
         operation: 'mesh.compose',
+        ...(nodeId ? { create: false } : {}),
     });
+    if (nodeId) {
+        const { items } = await ctx.client.v2.listCanvasNodes(session.canvas.id);
+        const target = items.find(item => item.nodeId === nodeId);
+        if (!target ||
+            !['production-3d', 'part-composer'].includes(target.type) ||
+            !target.actions.includes('mesh.compose'))
+            throw new Error('Composition is unavailable for this canvas node');
+    }
     const queued = await executeRecorded(session, 'mesh.compose', input, {
         ...executionOptions(ctx.flags),
         ...(previous ? { parentRunId: previous.runId } : {}),
+        ...(nodeId ? { canvasNode: { nodeId } } : {}),
     });
     await printRecorded(ctx, queued);
 };
@@ -1937,6 +2210,11 @@ const commandMesh = async (subcommand, positionals, ctx) => {
         return;
     }
     if (subcommand === 'generate') {
+        const nodeId = canvasNodeFlag(ctx.flags);
+        if (nodeId) {
+            await commandNodeMesh(ctx, nodeId);
+            return;
+        }
         const inputJson = getFlag(ctx.flags, 'input-json');
         const input = inputJson
             ? await readJsonArgument(inputJson, '--input-json')
@@ -2567,12 +2845,6 @@ const productionSession = (ctx, operation) => openExecutionSession({
     canvasId: selectedCanvasId(ctx.flags),
     operation,
 });
-const childOperationId = (parent, step) => {
-    const hash = createHash('sha256')
-        .update(JSON.stringify([parent, step]))
-        .digest('hex');
-    return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-8${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
-};
 const commandProduction = async (subcommand, positionals, ctx) => {
     if (subcommand === 'agents') {
         print(sanitizeProductionOutput(await ctx.client.v1.getProductionAgents()));
@@ -2812,7 +3084,7 @@ const commandParts = async (subcommand, ctx) => {
                     ...stateOptions(ctx),
                     operationId: executeOperationId,
                     expectedCanvasId: session.canvas.id,
-                    expectedBody: {
+                    expectedBodySubset: {
                         partExtractionMode: getFlag(ctx.flags, 'part-extraction-mode'),
                         ...(getFlagValues(ctx.flags, 'task-id').length
                             ? { confirmedTaskIds: getFlagValues(ctx.flags, 'task-id') }
@@ -3023,6 +3295,28 @@ const canvasForRead = (ctx) => openExecutionSession({
     create: false,
 });
 const commandCanvas = async (subcommand, positionals, ctx) => {
+    if (subcommand === 'nodes') {
+        const { canvas } = await canvasForRead(ctx);
+        print(await ctx.client.v2.listCanvasNodes(canvas.id));
+        return;
+    }
+    if (subcommand === 'download') {
+        const outDir = requireFlag(ctx.flags, 'out-dir');
+        const { canvas } = await canvasForRead(ctx);
+        const mesh = getFlag(ctx.flags, 'mesh');
+        if (mesh && !/^mesh_[1-9]\d*$/.test(mesh))
+            throw new Error('--mesh must be a mesh_<id> asset ID');
+        const result = await downloadCanvas({
+            client: ctx.client,
+            canvasId: canvas.id,
+            mesh,
+            outDir,
+            progress: message => process.stderr.write(`${message}\n`),
+        });
+        print(result);
+        process.exitCode = result.exitCode;
+        return;
+    }
     if (subcommand === 'context' ||
         subcommand === 'import' ||
         subcommand === 'compare' ||
@@ -3338,6 +3632,14 @@ const commandRuns = async (subcommand, positionals, ctx) => {
         return;
     }
     if (subcommand === 'resume') {
+        const batch = await resumeNodeMeshBatch({
+            ...stateOptions(ctx),
+            operationId: requirePositional(positionals, 2, 'operation-id'),
+        });
+        if (batch) {
+            await printNodeMeshBatch(ctx, batch);
+            return;
+        }
         const result = await resumeRecorded({
             ...stateOptions(ctx),
             operationId: requirePositional(positionals, 2, 'operation-id'),
@@ -3370,6 +3672,7 @@ const commandRuns = async (subcommand, positionals, ctx) => {
         plan,
         baseUrl: ctx.auth.baseUrl,
         apiKey: ctx.auth.apiKey,
+        workspaceId: ctx.auth.workspaceId,
         skipRegister: args.skipRegister,
         onProgress: event => {
             if (event.kind === 'register') {
@@ -3490,7 +3793,17 @@ const run = async () => {
     if (command === 'mcp') {
         if (subcommand !== 'config')
             throw new Error('Use mcp tools [tool-name] or mcp config --client cursor|codex');
-        stdout.write(mcpConfig(requireFlag(parsed.flags, 'client'), getFlag(parsed.flags, 'base-url') ?? env.ASSETHUB_API_BASE_URL ?? defaultBaseUrl, hasFlag(parsed.flags, 'account')));
+        const config = await readAuthConfig(getConfigPath(parsed.flags));
+        const explicitProfile = getFlag(parsed.flags, 'profile');
+        const stored = config.profiles?.[explicitProfile ?? config.defaultProfile ?? defaultProfileName];
+        if (explicitProfile && !stored)
+            throw new Error('Selected profile does not exist');
+        const selected = explicitProfile || stored?.workspaceId || stored?.apiKey?.startsWith('ah_pat_');
+        const baseUrl = getFlag(parsed.flags, 'base-url') ??
+            (selected ? stored?.baseUrl : env.ASSETHUB_API_BASE_URL ?? stored?.baseUrl) ?? defaultBaseUrl;
+        const workspaceId = getFlag(parsed.flags, 'workspace') ??
+            (stored && new URL(baseUrl).origin === new URL(stored.baseUrl).origin ? stored.workspaceId : undefined);
+        stdout.write(mcpConfig(requireFlag(parsed.flags, 'client'), baseUrl, hasFlag(parsed.flags, 'account'), workspaceId));
         return;
     }
     if (command === 'doctor') {