@assethub/cli 0.1.25 → 0.1.28

package/README.md

@@ -67,6 +67,8 @@ authentication. Existing workspace keys and user-token login remain supported.
 ```sh
 assethub --version
 assethub doctor --mcp --profile my-workspace
+assethub init --dry-run
+assethub init
 assethub mcp config --client cursor
 assethub mcp config --client codex
 ```
@@ -87,6 +89,19 @@ Use the same key as your CLI profile. Personal profiles include the selected
 For a different API origin, pass
 `--base-url https://your-host/prefix` (HTTP is accepted only for localhost).
 
+`init` sets up every supported coding agent found on this machine — Claude Code,
+Codex, and Cursor — in one step. It writes the hosted MCP entry into each agent's
+own configuration (merging with what is already there), installs the bundled
+`assethub` skill under `~/.agents/skills/assethub`, and links it into each agent's
+skill directory so the agent knows the correct command sequence, cost rules, and
+recovery steps without being told. Pass `--agent <name>` to choose agents
+explicitly, `--project` to write project-level MCP files into the current
+directory instead of your home, and `--dry-run` to see the plan without writing.
+`init` never stores a key: the MCP entries read `ASSETHUB_API_KEY` from the
+agent's environment. Directories that `init` did not create are left untouched.
+After a CLI upgrade, the next command refreshes the installed skill automatically.
+Set `ASSETHUB_CLI_HOME` to redirect all of these writes, for example in tests.
+
 Explicit `--profile` uses that profile's key and origin, ahead of environment
 variables, including user tokens and workspace MFA proofs. A missing profile fails.
 Without an explicit profile, a personal profile or a workspace selected with
@@ -247,8 +262,10 @@ has its own saved operation ID, with the execution linked to the analysis run.
 For Internal `V3.6.1` (`V3.6.1 Primary Images First`), `V3.6.3`
 (`V3.6.3 Fast Analysis`, CLI 0.1.16+), `V3.6.4`
 (`V3.6.4 Fast Analysis`, CLI 0.1.17+), `V3.6.5 Primary Images` and
-`Chibi Character (Pluffy) v3.1` (both CLI 0.1.20+), analysis runs the complete
-Artifact Graph split. `--all-ready` waits for that one receipt and does not start a
+`Chibi Character (Pluffy) v3.1` (both CLI 0.1.20+), `V3.7 Artist Skills`,
+`V3.7.1 Building Modules` (both CLI 0.1.23+/0.1.24+), `V3.0.9 Garment
+Boundaries`, and `Humanoid Assembly (internal)` (both CLI 0.1.26+), analysis
+runs the complete Artifact Graph split. `--all-ready` waits for that one receipt and does not start a
 second production execution. Resume an interrupted graph split with
 `runs resume <operation-id>`; `--task-id`, `--mission-id`,
 `--part-extraction-mode`, and classic `--order-id` continuation are unsupported.
@@ -259,6 +276,79 @@ or an `imageUrl` to import), `config`, and optional `maxCostCredits`.
 An uncertain Trigger acknowledgement remains recoverable as `needs_review` with
 pending history; retrying the same operation never silently launches another run.
 
+### One-shot: image to finished asset
+
+`production run --image <file|asset-id>` is the fastest path from a single image to
+a finished, composed asset. It is a thin wrapper around `production automation`
+(split, mesh generation per part, and — by default — server-side compose, all in
+one call) plus waiting, cost estimation and downloads. It never re-runs the manual
+split/mesh/compose sequence itself.
+
+```sh
+# Estimate cost first; nothing is submitted, nothing is billed.
+assethub production run --image ./character.png --estimate
+
+# Run it, wait for every part and the compose stage, download the result.
+assethub production run --image ./character.png --wait --download --out-dir ./out/asset
+
+# An existing asset id works the same way as a local file.
+assethub production run --image "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" --wait
+```
+
+`--image` auto-detects its argument: an existing local path is uploaded like
+`--file`; anything else is treated like `--source-id`. Do not combine `--image`
+with `--file`/`--source-id`/other source flags — it already resolves one.
+
+`--compose` controls the compose stage:
+
+- Omitted: automation's own server-side default applies, untouched.
+- `--compose none`: disables automation's compose stage (`config.autoCompose:
+  false`); the run stops once every part's mesh is generated.
+- `--compose v6`: requests an explicit Composer V6 pass via
+  `config.partComposerAgentVersion: "part_composer_v6_auto_assemble"`
+  (`autoCompose` is left at its default of `true` — sending both together is
+  rejected by the server). A server that has shipped this (assethub-web PR
+  #8179) does the V6 compose itself, in the same automation call, pairing
+  each part's mesh with its source image automatically. Against an older,
+  currently-deployed server (detected by the automation response lacking
+  `estimatedCostBreakdown`), the CLI instead reads the batch's own
+  `mesh.generate` executions itself, pairs each produced mesh with the part
+  image it was generated from, and runs an explicit `composer run` — same
+  end result, either way you never pair mesh and image assets by hand.
+
+`--mesh-model <id>` and `--max-parts <n>` (default 24, matching the server's
+own conservative constant for this math) only affect `--estimate`'s math (mesh
+unit cost x an assumed worst-case part count — the CLI cannot know the real
+part count before splitting runs); they do not cap or select anything on the
+real run. `--max-cost <credits>` refuses to run at all, before anything is
+submitted, once the best-effort estimate exceeds it, and is also sent to the
+server as `maxCostCredits` on the real run as a backstop. `--estimate`'s numbers
+come only from side-effect-free catalog reads (mesh model credit cost, compose
+quotes) shaped like the server's own `split`/`meshGeneration`/`compose`
+breakdown; part-extraction/split has no dry-run price today, so that line is
+reported as unknown rather than guessed. On a real (non-`--estimate`) run
+against a server that has shipped #8179, the printed output additionally
+includes the server's own `estimatedTotalCredits`/`estimatedCostBreakdown`
+in place of the CLI's own preflight guess.
+
+This depends on assethub-web PR #8179 for the `partComposerAgentVersion` field
+and the richer cost breakdown; it is not merged/deployed as of this writing.
+The CLI degrades gracefully against the currently-deployed API (see above).
+
+`runs get <run-id> --summary` prints a handful of plain-text lines (status, stage,
+credits, output asset, error) instead of the full JSON execution. `runs wait
+<run-id>` is `runs watch` under a name that matches a long-running wait; both
+accept `--interval-ms`/`--timeout-ms` and retry rate limits the same way every
+other poll loop in the CLI does.
+
+The one-shot command's stdout is always a single JSON object (`batchId`,
+`estimate`, `batchStatus`, `compose`, `execution`, and `downloads` when
+requested) — the same convention every other command in this CLI already
+follows. `--json` is accepted for compatibility with that convention but has
+no effect, since there is no alternate plain-text mode to opt out of (`runs
+get --summary` is the one deliberate exception, and it is opt-in by its own
+flag).
+
 `evaluate list` discovers server evaluators. Server evaluation dispatch is currently
 unavailable. Graph exports are bounded to 100 runs/evaluations and 1,000 nodes;
 truncated exports require `--allow-truncated`. Other commands, including production run/intervene, rig and retopology,
@@ -522,6 +612,13 @@ Part extraction uses the same names shown in the AssetHub product: `V1.5`,
 `V3.6.4` (`V3.6.4 Fast Analysis`), `V3.6.5` (`V3.6.5 Primary Images`),
 and `pluffy` (`Chibi Character (Pluffy) v3.1`). CLI 0.1.20 adds the latter two;
 `3.6.5`, `pluffy v3.1`, and `pluffy 3.1` are also accepted aliases.
+`V3.7 Artist Skills` (`v3.7`; also known as `V3.0.7 Artist Skills`) and
+`V3.7.1 Building Modules` (`v3.7.1`; also known as `V3.0.8 Building Modules`)
+support `--skill-mode`. `V3.0.9 Garment Boundaries` (`v3.0.9`) and
+`Humanoid Assembly (internal)` (`humanoid assembly`, `humanoid-assembly`,
+`humanoid_assembly_auto`; CLI 0.1.26+) are additional Internal-only graph
+extractors; use the exact quoted public name or one of its aliases with
+`--part-extractor`.
 Run `production agents` to check availability and `supportedOnGraphEndpoint`
 before selecting a graph version. These aliases do not change the V1.5 default
 or grant access to Internal models; the server still authorizes the account.
@@ -545,6 +642,11 @@ assethub canvas list
 assethub canvas use <canvas-id>
 assethub composer models
 assethub composer run --part <mesh-id> --part <mesh-id> --reference <image-id> --wait
+# Composer V6 (auto-assemble) requires each part's reference image; attach it
+# with `<mesh-id>:<part-image-asset-id>` (the image that mesh was generated
+# from) when the mesh has no other lineage the run can resolve it from.
+assethub composer run --part <mesh-id>:<part-image-id> --part <mesh-id>:<part-image-id> \
+  --reference <image-id> --model part_composer_v6_auto_assemble --wait
 assethub composer run --from-run <run-id> --transforms-json @transforms.json --wait
 assethub composer refine --list-modes
 assethub composer refine --from-run <run-id> --instruction "align the feet" \

package/dist/agentSetup.d.ts

@@ -0,0 +1,69 @@
+export declare const AGENT_IDS: readonly ["claude-code", "codex", "cursor"];
+export type AgentId = (typeof AGENT_IDS)[number];
+type AgentSpec = {
+    id: AgentId;
+    name: string;
+    /** Presence of this directory under home means the agent is installed. */
+    detectDir: string;
+    globalMcpPath: string;
+    projectMcpPath: string;
+    skillDir: string;
+    format: 'claude' | 'cursor' | 'codex';
+};
+/** `ASSETHUB_CLI_HOME` keeps tests and sandboxes from writing into the real home directory. */
+export declare const cliHome: () => string;
+export declare const packagedSkillDir: () => string;
+export declare const canonicalSkillDir: (home: string) => string;
+export declare const mcpServerEntry: (format: AgentSpec["format"], baseUrl: string, workspaceId?: string) => Record<string, unknown>;
+type WriteStatus = 'created' | 'updated' | 'unchanged';
+type SkillStatus = 'installed' | 'updated' | 'unchanged' | 'kept-existing';
+export declare const installSkill: ({ home, version, dryRun, }: {
+    home: string;
+    version: string;
+    dryRun: boolean;
+}) => Promise<{
+    path: string;
+    status: SkillStatus;
+    version?: string;
+}>;
+type LinkStatus = 'linked' | 'relinked' | 'unchanged' | 'kept-existing';
+/**
+ * Refresh an installed skill after a CLI upgrade. Runs before every command;
+ * the steady-state cost is one small file read. Never throws — a read-only or
+ * missing home must not fail the user's actual command.
+ */
+export declare const syncInstalledSkill: () => Promise<void>;
+export type InitOptions = {
+    baseUrl: string;
+    workspaceId?: string;
+    /** Agent ids to configure; defaults to every agent detected under home. */
+    agents?: string[];
+    /** Write project-level MCP config into the working directory instead of the user's home. */
+    project?: boolean;
+    dryRun?: boolean;
+    cwd?: string;
+    home?: string;
+};
+export type InitReport = {
+    version: string;
+    dryRun: boolean;
+    scope: 'global' | 'project';
+    skill: Awaited<ReturnType<typeof installSkill>>;
+    agents: {
+        id: AgentId;
+        name: string;
+        detected: boolean;
+        mcp: {
+            path: string;
+            status: WriteStatus;
+        };
+        skill: {
+            path: string;
+            status: LinkStatus;
+        };
+    }[];
+    next: string[];
+};
+export declare const initAgents: (options: InitOptions) => Promise<InitReport>;
+export {};
+//# sourceMappingURL=agentSetup.d.ts.map

package/dist/agentSetup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentSetup.d.ts","sourceRoot":"","sources":["../src/agentSetup.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,SAAS,6CAA8C,CAAA;AACpE,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAA;AAEhD,KAAK,SAAS,GAAG;IACf,EAAE,EAAE,OAAO,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;IACrB,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAA;CACtC,CAAA;AAoCD,+FAA+F;AAC/F,eAAO,MAAM,OAAO,QAAO,MAA4C,CAAA;AAEvE,eAAO,MAAM,gBAAgB,QAAO,MACiC,CAAA;AAErE,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,MACJ,CAAA;AA2B7C,eAAO,MAAM,cAAc,GACzB,QAAQ,SAAS,CAAC,QAAQ,CAAC,EAC3B,SAAS,MAAM,EACf,cAAc,MAAM,KACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAYxB,CAAA;AAED,KAAK,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAA;AA2EtD,KAAK,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,eAAe,CAAA;AAmC1E,eAAO,MAAM,YAAY,GAAU,4BAIhC;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;CAChB,KAAG,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAC,CAwBhE,CAAA;AAED,KAAK,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,eAAe,CAAA;AAkCvE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAa,OAAO,CAAC,IAAI,CAevD,CAAA;AAID,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC3B,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAA;IAC/C,MAAM,EAAE;QACN,EAAE,EAAE,OAAO,CAAA;QACX,IAAI,EAAE,MAAM,CAAA;QACZ,QAAQ,EAAE,OAAO,CAAA;QACjB,GAAG,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,WAAW,CAAA;SAAC,CAAA;QACxC,KAAK,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,UAAU,CAAA;SAAC,CAAA;KAC1C,EAAE,CAAA;IACH,IAAI,EAAE,MAAM,EAAE,CAAA;CACf,CAAA;AAED,eAAO,MAAM,UAAU,GAAU,SAAS,WAAW,KAAG,OAAO,CAAC,UAAU,CA4EzE,CAAA"}

package/dist/agentSetup.js

@@ -0,0 +1,311 @@
+/**
+ * `assethub init` and the skill sync that keeps its output current.
+ *
+ * Coding agents learn a tool from two local files: an MCP server entry in their
+ * own config, and a skill directory they read on demand. `init` writes both for
+ * every supported agent found on this machine, merging into existing config
+ * rather than replacing it, and never touching credentials — the MCP entries
+ * reference `ASSETHUB_API_KEY` from the agent's environment.
+ *
+ * The skill is copied once to `~/.agents/skills/assethub` and symlinked into
+ * each agent's skill directory. A version marker lets every later command
+ * refresh the copy when the CLI has been upgraded, so agents never read rules
+ * written for a version they are no longer running.
+ */
+import { cp, lstat, mkdir, readFile, readlink, rename, rm, stat, symlink, writeFile, } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { cwd as processCwd, env, pid } from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { cliVersion, mcpConfig, validatedBaseUrl } from './setup.js';
+export const AGENT_IDS = ['claude-code', 'codex', 'cursor'];
+const AGENTS = [
+    {
+        id: 'claude-code',
+        name: 'Claude Code',
+        detectDir: '.claude',
+        globalMcpPath: '.claude.json',
+        projectMcpPath: '.mcp.json',
+        skillDir: '.claude/skills',
+        format: 'claude',
+    },
+    {
+        id: 'codex',
+        name: 'Codex',
+        detectDir: '.codex',
+        globalMcpPath: '.codex/config.toml',
+        projectMcpPath: '.codex/config.toml',
+        skillDir: '.codex/skills',
+        format: 'codex',
+    },
+    {
+        id: 'cursor',
+        name: 'Cursor',
+        detectDir: '.cursor',
+        globalMcpPath: '.cursor/mcp.json',
+        projectMcpPath: '.cursor/mcp.json',
+        skillDir: '.cursor/skills',
+        format: 'cursor',
+    },
+];
+const SERVER_NAME = 'assethub';
+const SKILL_NAME = 'assethub';
+const VERSION_MARKER = '.assethub-cli-version';
+/** `ASSETHUB_CLI_HOME` keeps tests and sandboxes from writing into the real home directory. */
+export const cliHome = () => env.ASSETHUB_CLI_HOME || homedir();
+export const packagedSkillDir = () => fileURLToPath(new URL(`../skills/${SKILL_NAME}/`, import.meta.url));
+export const canonicalSkillDir = (home) => join(home, '.agents', 'skills', SKILL_NAME);
+const isEnoent = (error) => typeof error === 'object' &&
+    error !== null &&
+    error.code === 'ENOENT';
+const readText = async (path) => {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return undefined;
+        throw error;
+    }
+};
+const isDirectory = async (path) => {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return false;
+        throw error;
+    }
+};
+// ── MCP configuration ────────────────────────────────────────────────
+export const mcpServerEntry = (format, baseUrl, workspaceId) => {
+    const url = `${validatedBaseUrl(baseUrl)}/api/mcp`;
+    // Cursor expands `${env:NAME}`; Claude Code expands `${NAME}`. Neither file ever holds the key.
+    const key = format === 'cursor' ? '${env:ASSETHUB_API_KEY}' : '${ASSETHUB_API_KEY}';
+    return {
+        ...(format === 'claude' ? { type: 'http' } : {}),
+        url,
+        headers: {
+            Authorization: `Bearer ${key}`,
+            ...(workspaceId ? { 'X-AssetHub-Workspace': workspaceId } : {}),
+        },
+    };
+};
+const writeJsonServer = async (path, entry, dryRun) => {
+    const text = await readText(path);
+    let document = {};
+    if (text !== undefined) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`${path} is not valid JSON. Fix or move it, then rerun init.`);
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            throw new Error(`${path} must contain a JSON object.`);
+        document = parsed;
+    }
+    // A malformed `mcpServers` is the user's data too; refuse rather than replace it.
+    if (document.mcpServers !== undefined &&
+        (typeof document.mcpServers !== 'object' ||
+            document.mcpServers === null ||
+            Array.isArray(document.mcpServers)))
+        throw new Error(`${path} has a non-object "mcpServers" value. Fix or move it, then rerun init.`);
+    const servers = (document.mcpServers ?? {});
+    if (JSON.stringify(servers[SERVER_NAME]) === JSON.stringify(entry))
+        return 'unchanged';
+    const next = { ...document, mcpServers: { ...servers, [SERVER_NAME]: entry } };
+    if (!dryRun) {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, `${JSON.stringify(next, null, 2)}\n`);
+    }
+    return text === undefined ? 'created' : 'updated';
+};
+/** Replaces or appends one `[mcp_servers.assethub]` table; every other line is kept verbatim. */
+const writeTomlSection = async (path, section, dryRun) => {
+    const header = `[mcp_servers.${SERVER_NAME}]`;
+    const body = section.trimEnd();
+    const text = await readText(path);
+    const lines = (text ?? '').split('\n');
+    const start = lines.findIndex(line => line.trim() === header);
+    let next;
+    if (start === -1) {
+        const base = (text ?? '').trimEnd();
+        next = `${base ? `${base}\n\n` : ''}${body}\n`;
+    }
+    else {
+        const endOffset = lines
+            .slice(start + 1)
+            .findIndex(line => /^\s*\[/.test(line));
+        const end = endOffset === -1 ? lines.length : start + 1 + endOffset;
+        if (lines.slice(start, end).join('\n').trimEnd() === body)
+            return 'unchanged';
+        const before = lines.slice(0, start).join('\n').trimEnd();
+        const after = lines.slice(end).join('\n').trim();
+        next = `${before ? `${before}\n\n` : ''}${body}\n${after ? `\n${after}\n` : ''}`;
+    }
+    if (!dryRun) {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, next);
+    }
+    return text === undefined ? 'created' : 'updated';
+};
+const readMarker = async (dir) => (await readText(join(dir, VERSION_MARKER)))?.trim();
+/**
+ * Stage the new copy beside the target, then swap with two renames, so the
+ * installed skill is never deleted before its replacement is complete. A
+ * failed swap puts the previous copy back. Two CLIs syncing at the same
+ * moment use distinct staging names; whichever copy lands is complete, and
+ * the loser's error is swallowed by the caller.
+ */
+const replaceSkillDir = async (source, target, version) => {
+    const staging = `${target}.next-${pid}`;
+    const previous = `${target}.prev-${pid}`;
+    await rm(staging, { recursive: true, force: true });
+    await mkdir(dirname(target), { recursive: true });
+    await cp(source, staging, { recursive: true });
+    await writeFile(join(staging, VERSION_MARKER), `${version}\n`);
+    const hadTarget = await isDirectory(target);
+    if (hadTarget)
+        await rename(target, previous);
+    try {
+        await rename(staging, target);
+    }
+    catch (error) {
+        if (hadTarget)
+            await rename(previous, target).catch(() => undefined);
+        await rm(staging, { recursive: true, force: true });
+        throw error;
+    }
+    if (hadTarget)
+        await rm(previous, { recursive: true, force: true });
+};
+export const installSkill = async ({ home, version, dryRun, }) => {
+    const source = packagedSkillDir();
+    if (!(await isDirectory(source)))
+        throw new Error('This CLI installation does not include the packaged agent skill.');
+    const target = canonicalSkillDir(home);
+    const marker = await readMarker(target);
+    // A directory without our marker is the user's own; leave it alone.
+    const status = marker === undefined
+        ? (await isDirectory(target))
+            ? 'kept-existing'
+            : 'installed'
+        : marker === version
+            ? 'unchanged'
+            : 'updated';
+    if (!dryRun && (status === 'installed' || status === 'updated'))
+        await replaceSkillDir(source, target, version);
+    return {
+        path: target,
+        status,
+        ...(status === 'kept-existing' ? {} : { version }),
+    };
+};
+const linkSkill = async (agentSkillsDir, canonical, dryRun) => {
+    const link = join(agentSkillsDir, SKILL_NAME);
+    const relativeTarget = relative(agentSkillsDir, canonical);
+    let existing;
+    try {
+        existing = await lstat(link);
+    }
+    catch (error) {
+        if (!isEnoent(error))
+            throw error;
+    }
+    if (existing?.isSymbolicLink()) {
+        if (resolve(agentSkillsDir, await readlink(link)) === canonical)
+            return { path: link, status: 'unchanged' };
+        if (!dryRun) {
+            await rm(link);
+            await symlink(relativeTarget, link, 'dir');
+        }
+        return { path: link, status: 'relinked' };
+    }
+    if (existing)
+        return { path: link, status: 'kept-existing' };
+    if (!dryRun) {
+        await mkdir(agentSkillsDir, { recursive: true });
+        await symlink(relativeTarget, link, 'dir');
+    }
+    return { path: link, status: 'linked' };
+};
+let synced = false;
+/**
+ * Refresh an installed skill after a CLI upgrade. Runs before every command;
+ * the steady-state cost is one small file read. Never throws — a read-only or
+ * missing home must not fail the user's actual command.
+ */
+export const syncInstalledSkill = async () => {
+    if (synced)
+        return;
+    synced = true;
+    try {
+        const target = canonicalSkillDir(cliHome());
+        const installed = await readMarker(target);
+        if (installed === undefined)
+            return;
+        const version = await cliVersion();
+        if (installed === version)
+            return;
+        const source = packagedSkillDir();
+        if (!(await isDirectory(source)))
+            return;
+        await replaceSkillDir(source, target, version);
+    }
+    catch {
+        // best effort
+    }
+};
+export const initAgents = async (options) => {
+    const home = options.home ?? cliHome();
+    const cwd = options.cwd ?? processCwd();
+    const dryRun = options.dryRun ?? false;
+    const version = await cliVersion();
+    const requested = options.agents ?? [];
+    const unknown = requested.filter(id => !AGENT_IDS.includes(id));
+    if (unknown.length > 0)
+        throw new Error(`Unknown agent: ${unknown.join(', ')}. Use --agent ${AGENT_IDS.join('|')}.`);
+    const detected = new Map(await Promise.all(AGENTS.map(async (agent) => [agent.id, await isDirectory(join(home, agent.detectDir))])));
+    const selected = requested.length > 0
+        ? AGENTS.filter(agent => requested.includes(agent.id))
+        : AGENTS.filter(agent => detected.get(agent.id));
+    if (selected.length === 0)
+        throw new Error(`No supported coding agent found under ${home}. Pass --agent ${AGENT_IDS.join('|')} to choose one.`);
+    const skill = await installSkill({ home, version, dryRun });
+    const agents = [];
+    for (const spec of selected) {
+        const mcpPath = options.project
+            ? join(cwd, spec.projectMcpPath)
+            : join(home, spec.globalMcpPath);
+        const mcp = spec.format === 'codex'
+            ? await writeTomlSection(mcpPath, mcpConfig('codex', options.baseUrl, false, options.workspaceId), dryRun)
+            : await writeJsonServer(mcpPath, mcpServerEntry(spec.format, options.baseUrl, options.workspaceId), dryRun);
+        const link = await linkSkill(join(home, spec.skillDir), skill.path, dryRun);
+        agents.push({
+            id: spec.id,
+            name: spec.name,
+            detected: detected.get(spec.id) ?? false,
+            mcp: { path: mcpPath, status: mcp },
+            skill: link,
+        });
+    }
+    return {
+        version,
+        dryRun,
+        scope: options.project ? 'project' : 'global',
+        skill,
+        agents,
+        next: [
+            ...(env.ASSETHUB_API_KEY
+                ? []
+                : [
+                    "Provide ASSETHUB_API_KEY in each agent's environment; the MCP entries read it from there and never store it.",
+                ]),
+            'Restart the agent so it reloads MCP servers and skills.',
+            'Run `assethub doctor --mcp` to verify the connection.',
+        ],
+    };
+};

package/dist/execution.d.ts.map

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

package/dist/execution.js

@@ -43,6 +43,9 @@ export class CliExecutionError extends Error {
         this.runId = runId;
     }
 }
+/** A floor under `--interval-ms` for `waitForExecution`'s own poll cadence. */
+const MIN_POLL_INTERVAL_MS = 1_000;
+const POLL_JITTER_MS = 250;
 /** Kept only for SIGINT reporting; interrupting the client never cancels server work. */
 export const activeExecution = {};
 export const childOperationId = (parent, step) => {
@@ -247,6 +250,11 @@ export const waitForExecution = async (client, runId, options = {}) => {
     activeExecution.runId = runId;
     const deadline = Date.now() + (options.timeoutMs ?? 900_000);
     const timeout = () => new CliExecutionError(`Wait timed out; server execution continues. Use runs watch ${runId}.`, 3, activeExecution.operationId, activeExecution.execution, runId);
+    // A floor under --interval-ms and a touch of jitter on every poll: several
+    // `--wait` invocations started together (e.g. parallel `mesh generate`)
+    // otherwise poll in lockstep and collide on the same rate-limit window.
+    const pollIntervalMs = () => Math.max(options.intervalMs ?? 5_000, MIN_POLL_INTERVAL_MS) +
+        Math.floor(Math.random() * POLL_JITTER_MS);
     while (true) {
         const signal = AbortSignal.timeout(Math.max(1, deadline - Date.now()));
         let execution;
@@ -256,6 +264,16 @@ export const waitForExecution = async (client, runId, options = {}) => {
         catch (error) {
             if (signal.aborted)
                 throw timeout();
+            // The client already retries a 429 internally (Retry-After/backoff);
+            // one only reaches here once that budget is exhausted. Server work
+            // keeps running regardless, so a rate limit is never a wait failure —
+            // treat it like "no update yet" and keep polling within the deadline.
+            if (error instanceof AssetHubApiError && error.status === 429) {
+                if (Date.now() >= deadline)
+                    throw timeout();
+                await delay(Math.min(pollIntervalMs(), Math.max(0, deadline - Date.now())));
+                continue;
+            }
             throw new CliExecutionError(error instanceof Error ? error.message : String(error), error instanceof AssetHubApiError && error.status < 500 ? 2 : 1, activeExecution.operationId, activeExecution.execution, runId);
         }
         activeExecution.execution = execution;
@@ -267,6 +285,6 @@ export const waitForExecution = async (client, runId, options = {}) => {
             return execution;
         if (Date.now() >= deadline)
             throw timeout();
-        await delay(Math.min(options.intervalMs ?? 5_000, Math.max(0, deadline - Date.now())));
+        await delay(Math.min(pollIntervalMs(), Math.max(0, deadline - Date.now())));
     }
 };