@just-every/design 0.1.21 → 0.1.23

package/README.md

@@ -122,6 +122,7 @@ Current tools are focused on runs + artifacts:
 - `design.watch`
 - `design.extractAssets` (opt-in: extract assets for interface/html runs)
 - `design.generateHtml` (opt-in: generate HTML/CSS + assets for html runs)
+- `design.iterate` (iterate on a run using screenshot feedback)
 - `design.refineDraft` (non-fork: refine a specific draft within a run)
 - `design.uploadTarget` (upload an image and set it as the run target)
 - `design.setTarget` (select which draft should be treated as the run target)
@@ -146,7 +147,7 @@ CLI helper commands (non-MCP):
 - `every-design set-target --json '{...}'`
 - `every-design clear-target --json '{...}'`
 - `every-design screenshot <url>`
-- `every-design critique --json '{...}'`
+- `every-design iterate --json '{"runId":"<run-id>","render":[...],"concerns":"..."}'`
 
 ## Output kinds (CLI/MCP)
 

package/dist/artifacts-cli.d.ts

@@ -0,0 +1,11 @@
+type RunArtifactRef = {
+    runId: string;
+    artifactId: string;
+};
+export declare function parseRunArtifactRef(value: string): RunArtifactRef | null;
+export declare function parseArtifactsListPositional(args: string[]): {
+    runId: string;
+} | null;
+export declare function parseArtifactsDownloadPositional(args: string[]): RunArtifactRef | null;
+export {};
+//# sourceMappingURL=artifacts-cli.d.ts.map

package/dist/artifacts-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts-cli.d.ts","sourceRoot":"","sources":["../src/artifacts-cli.ts"],"names":[],"mappings":"AAAA,KAAK,cAAc,GAAG;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAkBF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAgBxE;AAED,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAUrF;AAED,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,GAAG,IAAI,CAUtF"}

package/dist/artifacts-cli.js

@@ -0,0 +1,53 @@
+const UUID_RE = /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g;
+function extractUuids(value) {
+    const matches = value.match(UUID_RE);
+    return matches ? matches.map((m) => m) : [];
+}
+function normalizeToken(value) {
+    return String(value ?? '').trim();
+}
+function looksLikeJsonObject(value) {
+    const trimmed = value.trim();
+    return trimmed.startsWith('{');
+}
+export function parseRunArtifactRef(value) {
+    const raw = normalizeToken(value);
+    if (!raw)
+        return null;
+    if (looksLikeJsonObject(raw))
+        return null;
+    const uuids = extractUuids(raw);
+    if (uuids.length >= 2) {
+        return { runId: uuids[0], artifactId: uuids[1] };
+    }
+    const parts = raw.split('/').map((p) => p.trim()).filter(Boolean);
+    if (parts.length === 2) {
+        return { runId: parts[0], artifactId: parts[1] };
+    }
+    return null;
+}
+export function parseArtifactsListPositional(args) {
+    const tokens = args.map(normalizeToken).filter(Boolean);
+    if (tokens.length !== 1)
+        return null;
+    const token = tokens[0];
+    if (looksLikeJsonObject(token))
+        return null;
+    const uuids = extractUuids(token);
+    if (uuids.length >= 1)
+        return { runId: uuids[0] };
+    return { runId: token };
+}
+export function parseArtifactsDownloadPositional(args) {
+    const tokens = args.map(normalizeToken).filter(Boolean);
+    if (tokens.length === 1) {
+        return parseRunArtifactRef(tokens[0]);
+    }
+    if (tokens.length === 2) {
+        if (looksLikeJsonObject(tokens[0]) || looksLikeJsonObject(tokens[1]))
+            return null;
+        return { runId: tokens[0], artifactId: tokens[1] };
+    }
+    return null;
+}
+//# sourceMappingURL=artifacts-cli.js.map

package/dist/artifacts-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts-cli.js","sourceRoot":"","sources":["../src/artifacts-cli.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,GAAG,8EAA8E,CAAC;AAE/F,SAAS,YAAY,CAAC,KAAa;IACjC,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC;AAED,SAAS,cAAc,CAAC,KAAa;IACnC,OAAO,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACpC,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAa;IACxC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,MAAM,GAAG,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,mBAAmB,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAE1C,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC;IACrD,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC;IACrD,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,IAAc;IACzD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;IACzB,IAAI,mBAAmB,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5C,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC;IAEnD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,gCAAgC,CAAC,IAAc;IAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QACpF,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAE,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAE,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cli.js

@@ -5,13 +5,14 @@
 import { createInterface } from 'node:readline/promises';
 import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { existsSync, statSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runApprovalLinkLoginFlow } from './auth.js';
 import { refreshLoginSession } from './auth.js';
 import { pickAccountSlug } from './account-picker.js';
+import { parseArtifactsDownloadPositional, parseArtifactsListPositional } from './artifacts-cli.js';
 import { clearConfig, readConfig, resolveConfigPath, writeConfig } from './config.js';
 import { DesignAppClient } from './design-client.js';
 import { parseJsonOrThrow } from './json.js';
@@ -66,7 +67,8 @@ function printHelp() {
     console.error('  extract-assets            Trigger asset extraction for a run (CLI helper)');
     console.error('  generate-html             Trigger HTML generation for a run (CLI helper)');
     console.error('  screenshot <url>          Screenshot a URL (CLI helper)');
-    console.error('  critique                  Critique a target vs current screenshot (CLI helper)');
+    console.error('  iterate                   Iterate on a run using screenshot feedback (CLI helper)');
+    console.error('  critique                  Alias for `iterate`');
     console.error('  watch                     Watch a design run (CLI helper)');
     console.error('  share status              Get run share link status (CLI helper)');
     console.error('  share enable              Enable (or rotate) a share link (CLI helper)');
@@ -74,8 +76,8 @@ function printHelp() {
     console.error('  get                       Fetch a run by id (CLI helper)');
     console.error('  list                      List recent runs (CLI helper)');
     console.error('  events                    Fetch run events (CLI helper)');
-    console.error('  artifacts list            List run artifacts (CLI helper)');
-    console.error('  artifacts download        Download an artifact (CLI helper)');
+    console.error('  artifacts list <runId>    List run artifacts (CLI helper)');
+    console.error('  artifacts download <runId>/<artifactId>  Download an artifact (CLI helper)');
     console.error('  auth login                Login via approval-link flow and save config');
     console.error('  auth status               Check current auth against /api/me');
     console.error('  auth logout               Delete the saved config file');
@@ -175,7 +177,7 @@ async function runScreenshotCommand(args) {
     try {
         const waitMs = Number.isFinite(args.waitMs) ? Math.max(0, Math.min(120_000, Math.round(args.waitMs))) : 4000;
         const timeoutMs = Math.max(15_000, Math.min(180_000, waitMs + 30_000));
-        const res = spawnSync(browser, [
+        const argsList = [
             '--headless=new',
             '--disable-gpu',
             '--hide-scrollbars',
@@ -192,26 +194,124 @@ async function runScreenshotCommand(args) {
             `--virtual-time-budget=${waitMs || 0}`,
             `--screenshot=${outPath}`,
             url,
-        ], {
-            encoding: 'utf8',
-            timeout: timeoutMs,
-            // Hard kill; some Chrome headless runs can hang after producing a screenshot.
-            killSignal: 'SIGKILL',
-        });
-        const screenshotOk = (() => {
+        ];
+        const screenshotOk = () => {
             try {
                 return statSync(outPath).size > 0;
             }
             catch {
                 return false;
             }
-        })();
-        // `spawnSync` returns `error.code === 'ETIMEDOUT'` when the timeout triggers.
-        // Chrome may still have produced a valid screenshot before hanging, so treat that as success.
-        if (!screenshotOk) {
-            const detail = (res.stderr || res.stdout || '').trim();
-            const errorText = res.error instanceof Error ? res.error.message : '';
-            throw new Error(`Screenshot failed (exit ${res.status ?? 'unknown'}, signal ${res.signal ?? 'none'}): ${detail || errorText || 'no output'}`);
+        };
+        const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+        const waitForScreenshotStable = async (signal) => {
+            const start = Date.now();
+            // Chrome writes the screenshot file as a single operation most of the time, but we've seen
+            // occasional flakiness where the file exists briefly at size=0. Wait for a stable >0 size.
+            let lastSize = -1;
+            let stableTicks = 0;
+            while (Date.now() - start < timeoutMs) {
+                if (signal.aborted)
+                    return false;
+                let size = -1;
+                try {
+                    size = statSync(outPath).size;
+                }
+                catch {
+                    size = -1;
+                }
+                if (size > 0) {
+                    if (size === lastSize)
+                        stableTicks += 1;
+                    else
+                        stableTicks = 0;
+                    lastSize = size;
+                    if (stableTicks >= 2)
+                        return true;
+                }
+                await sleep(100);
+            }
+            if (signal.aborted)
+                return false;
+            throw new Error('Timed out waiting for screenshot file to be produced.');
+        };
+        // Use an isolated process group on Unix so we can reliably kill Chrome + its helpers.
+        const child = spawn(browser, argsList, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: process.platform !== 'win32',
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        const killChild = (signal) => {
+            if (!child.pid)
+                return;
+            try {
+                if (process.platform !== 'win32') {
+                    // Kill the whole process group (negative PID) when detached.
+                    process.kill(-child.pid, signal);
+                }
+                else {
+                    process.kill(child.pid, signal);
+                }
+            }
+            catch {
+                // ignore
+            }
+        };
+        const exitPromise = new Promise((resolve, reject) => {
+            child.once('error', reject);
+            child.once('exit', (code, signal) => resolve({ code, signal }));
+        });
+        const abort = new AbortController();
+        const screenshotPromise = waitForScreenshotStable(abort.signal)
+            .then((ok) => ({ type: 'screenshot', ok }))
+            .catch((error) => ({ type: 'screenshot_error', error }));
+        const exitPromiseHandled = exitPromise
+            .then((r) => ({ type: 'exit', ...r }))
+            .catch((error) => ({ type: 'exit_error', error }));
+        // Hard-kill after the timeout budget; Chrome can hang even after producing a screenshot.
+        const timeout = setTimeout(() => {
+            killChild('SIGKILL');
+        }, timeoutMs);
+        try {
+            const first = await Promise.race([screenshotPromise, exitPromiseHandled]);
+            abort.abort();
+            if (first.type === 'exit_error') {
+                const message = first.error instanceof Error ? first.error.message : String(first.error);
+                throw new Error(`Screenshot failed (spawn error): ${message}`);
+            }
+            if (first.type === 'screenshot_error') {
+                // Still allow a best-effort success if Chrome produced a screenshot before hanging.
+                killChild('SIGKILL');
+                await Promise.race([exitPromise.catch(() => undefined), sleep(1_500)]);
+            }
+            // If the screenshot is ready but Chrome is still running, kill it immediately instead of
+            // waiting for the timeout (which is often ~waitMs+30s).
+            if (first.type === 'screenshot' && first.ok) {
+                killChild('SIGKILL');
+                // Don't await indefinitely; cleanup is best-effort.
+                await Promise.race([exitPromise.catch(() => undefined), sleep(1_500)]);
+            }
+            const ok = screenshotOk();
+            if (!ok) {
+                // Chrome may exit without producing a screenshot; include output to help debug.
+                const detail = (stderr || stdout).trim();
+                const exit = first.type === 'exit' ? first : await exitPromise.catch(() => ({ code: null, signal: null }));
+                throw new Error(`Screenshot failed (exit ${exit.code ?? 'unknown'}, signal ${exit.signal ?? 'none'}): ${detail || 'no output'}`);
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+            // Ensure Chrome isn't left running in the background.
+            killChild('SIGKILL');
         }
         return {
             screenshotPath: outPath,
@@ -866,6 +966,7 @@ async function main() {
         || verb === 'clear-target'
         || verb === 'extract-assets'
         || verb === 'generate-html'
+        || verb === 'iterate'
         || verb === 'critique'
         || verb === 'watch'
         || verb === 'share'
@@ -972,69 +1073,89 @@ async function main() {
                 console.log(pretty(progressed));
                 process.exit(0);
             }
-            if (verb === 'critique') {
+            if (verb === 'iterate' || verb === 'critique') {
                 const input = await readJsonArgs(command.slice(1), flags);
-                const originalPrompt = String(input.originalPrompt ?? '').trim();
-                if (!originalPrompt)
-                    throw new Error('Missing required argument: originalPrompt');
+                if (verb === 'critique') {
+                    console.error('[every-design] `critique` is deprecated; use `iterate` instead.');
+                }
+                const runId = String(input.runId ?? '').trim();
+                if (!runId)
+                    throw new Error('Missing required argument: runId');
                 const concerns = typeof input.concerns === 'string' ? input.concerns.trim() : '';
-                const target = Array.isArray(input.target) ? input.target : [];
                 const render = Array.isArray(input.render) ? input.render : [];
-                if (target.length === 0)
-                    throw new Error('Missing required argument: target (array of images)');
                 if (render.length === 0)
                     throw new Error('Missing required argument: render (array of images)');
+                const target = Array.isArray(input.target) ? input.target : [];
                 const viewportInput = input.viewport && typeof input.viewport === 'object' ? input.viewport : null;
                 const viewport = {
                     width: Number(viewportInput?.width) || 1696,
                     height: Number(viewportInput?.height) || 2528,
                 };
-                const targetRefs = await client.uploadSourceImages(target);
                 const renderRefs = await client.uploadSourceImages(render);
-                const created = await client.createRun({
-                    prompt: originalPrompt,
-                    config: {
-                        output: { designKind: 'interface', render: { viewport } },
-                        critique: {
-                            originalPrompt,
-                            concerns,
-                            target: targetRefs,
-                            render: renderRefs,
-                        },
-                    },
+                const targetRefs = target.length > 0 ? await client.uploadSourceImages(target) : [];
+                const created = await client.createRunOperation(runId, {
+                    type: 'iterate',
+                    ...(concerns ? { concerns } : {}),
+                    viewport,
+                    render: renderRefs,
+                    ...(targetRefs.length > 0 ? { target: targetRefs } : {}),
                 });
-                const runId = String(created?.run?.id ?? '').trim();
-                if (!runId)
-                    throw new Error('Critique run created but missing run id');
+                const operationId = String(created?.operation?.id ?? '').trim();
+                if (!operationId)
+                    throw new Error('Iterate operation created but missing operation id');
                 const timeoutSeconds = typeof input.timeoutSeconds === 'number' ? input.timeoutSeconds : 900;
                 const intervalSeconds = typeof input.intervalSeconds === 'number' ? input.intervalSeconds : 5;
-                await watchRun(client, runId, {
-                    timeoutSeconds,
-                    intervalSeconds,
-                    log: (line) => console.error(line),
-                });
+                const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+                const deadlineMs = Date.now() + Math.max(1, timeoutSeconds) * 1000;
+                while (true) {
+                    const op = await client.getOperation(operationId);
+                    const status = String(op?.operation?.status ?? '').trim().toLowerCase();
+                    if (status === 'completed' || status === 'failed' || status === 'cancelled') {
+                        break;
+                    }
+                    if (Date.now() > deadlineMs) {
+                        throw new Error(`Timed out waiting for iterate operation (${operationId})`);
+                    }
+                    await sleep(Math.max(1, intervalSeconds) * 1000);
+                }
                 const detail = await client.getRun(runId);
                 const outputs = Array.isArray(detail?.run?.outputs) ? detail.run.outputs : [];
-                const critiqueArtifact = outputs.find((a) => a?.artifactType === 'critique') ?? null;
-                const generatedAssets = outputs.filter((a) => a?.artifactType === 'critique-asset');
+                const getOperationId = (artifact) => {
+                    const meta = artifact?.metadata;
+                    if (meta && typeof meta === 'object') {
+                        const candidate = meta.operationId ?? meta.operation_id;
+                        return typeof candidate === 'string' ? candidate.trim() : '';
+                    }
+                    return '';
+                };
+                const critiqueArtifacts = outputs
+                    .filter((a) => a?.artifactType === 'critique')
+                    .sort((a, b) => String(a?.createdAt || '').localeCompare(String(b?.createdAt || '')));
+                const critiqueArtifact = critiqueArtifacts.find((a) => getOperationId(a) === operationId)
+                    ?? (critiqueArtifacts.length ? critiqueArtifacts[critiqueArtifacts.length - 1] : null);
+                const generatedAssets = outputs.filter((a) => a?.artifactType === 'critique-asset' && getOperationId(a) === operationId);
                 if (!critiqueArtifact) {
                     console.log(pretty({
                         runId,
+                        operationId,
                         status: 'completed',
+                        iterate: null,
                         critique: null,
                         generatedAssets,
-                        error: 'Missing critique artifact',
+                        error: 'Missing critique artifact for iterate operation',
                     }));
                     process.exit(0);
                 }
                 const url = typeof critiqueArtifact?.url === 'string' ? String(critiqueArtifact.url) : '';
                 if (!url)
-                    throw new Error('Critique output is missing a download url');
-                const downloaded = await client.downloadUrlToCache(runId, critiqueArtifact.id, url, { fileNameHint: 'critique.json' });
+                    throw new Error('Critique artifact is missing a download url');
+                const downloaded = await client.downloadUrlToCache(runId, critiqueArtifact.id, url, { fileNameHint: 'iterate.json' });
                 const raw = await readFile(downloaded.filePath, 'utf8');
                 const parsed = parseJsonOrThrow(raw);
                 console.log(pretty({
                     runId,
+                    operationId,
+                    iterate: parsed,
                     critique: parsed,
                     artifact: { id: critiqueArtifact.id, filePath: downloaded.filePath },
                     generatedAssets,
@@ -1191,7 +1312,8 @@ async function main() {
                 process.exit(0);
             }
             if (verb === 'artifacts' && sub === 'list') {
-                const input = await readJsonArgs(command.slice(2), flags);
+                const positional = parseArtifactsListPositional(command.slice(2));
+                const input = positional ? { runId: positional.runId } : await readJsonArgs(command.slice(2), flags);
                 const runId = String(input.runId ?? '').trim();
                 if (!runId)
                     throw new Error('Missing required argument: runId');
@@ -1201,7 +1323,8 @@ async function main() {
                 process.exit(0);
             }
             if (verb === 'artifacts' && sub === 'download') {
-                const input = await readJsonArgs(command.slice(2), flags);
+                const positional = parseArtifactsDownloadPositional(command.slice(2));
+                const input = positional ? { runId: positional.runId, artifactId: positional.artifactId } : await readJsonArgs(command.slice(2), flags);
                 const runId = String(input.runId ?? '').trim();
                 const artifactId = String(input.artifactId ?? '').trim();
                 if (!runId)
@@ -1211,26 +1334,49 @@ async function main() {
                 const detail = await client.getRun(runId);
                 const outputs = Array.isArray(detail?.run?.outputs) ? detail.run.outputs : [];
                 const found = outputs.find((entry) => String(entry?.id ?? '') === artifactId) || null;
-                const url = typeof found?.url === 'string' ? found.url : '';
-                if (!url)
-                    throw new Error(`Artifact not found in standard outputs: ${artifactId}`);
-                const hint = (() => {
+                const hint = await (async () => {
+                    const url = typeof found?.url === 'string' ? found.url.trim() : '';
+                    if (url) {
+                        try {
+                            const u = url.startsWith('http://') || url.startsWith('https://')
+                                ? new URL(url)
+                                : new URL(url, 'https://example.invalid');
+                            return u.pathname.split('/').filter(Boolean).pop() || undefined;
+                        }
+                        catch {
+                            return url.split('/').filter(Boolean).pop() || undefined;
+                        }
+                    }
                     try {
-                        const u = url.startsWith('http://') || url.startsWith('https://')
-                            ? new URL(url)
-                            : new URL(url, 'https://example.invalid');
-                        return u.pathname.split('/').filter(Boolean).pop() || undefined;
+                        const artifacts = await client.listArtifacts(runId);
+                        const record = Array.isArray(artifacts?.artifacts)
+                            ? artifacts.artifacts.find((a) => String(a?.id ?? '') === artifactId)
+                            : null;
+                        const storageKey = typeof record?.storageKey === 'string' ? record.storageKey.trim() : '';
+                        return storageKey ? storageKey.split('/').filter(Boolean).pop() || undefined : undefined;
                     }
                     catch {
-                        return url.split('/').filter(Boolean).pop() || undefined;
+                        return undefined;
+                    }
+                })();
+                const downloaded = await (async () => {
+                    try {
+                        return await client.downloadArtifactToCache(runId, artifactId, { fileNameHint: hint });
+                    }
+                    catch (error) {
+                        const url = typeof found?.url === 'string' ? found.url.trim() : '';
+                        if (url) {
+                            return await client.downloadUrlToCache(runId, artifactId, url, { fileNameHint: hint });
+                        }
+                        throw error;
                     }
                 })();
-                const downloaded = await client.downloadUrlToCache(runId, artifactId, url, { fileNameHint: hint });
                 console.log(pretty(downloaded));
                 process.exit(0);
             }
             if (verb === 'artifacts') {
-                throw new Error('Usage: artifacts list|download');
+                throw new Error('Usage: artifacts list <runId> | artifacts download <runId>/<artifactId>\n' +
+                    'Tip: you can still use --json or pipe a JSON object via stdin.');
             }
             // Should be unreachable due to the verb guard.
             throw new Error(`Unknown command: ${verb}`);