@assethub/cli 0.1.30 → 0.1.32

package/README.md

@@ -2,6 +2,35 @@
 
 Command line interface for AssetHub.
 
+## Quick setup
+
+Connect Claude Code and Codex to AssetHub in one step:
+
+```sh
+assethub setup                      # prompts for your API key and workspace
+printf '%s' "$KEY" | assethub setup --api-key-stdin --workspace <id> --yes
+assethub setup --dry-run            # show every command and file change, change nothing
+```
+
+Setup logs in (reusing a saved key), selects a workspace, registers the
+`assethub` MCP server in Claude Code (`claude mcp add-json ... --scope user`, run
+again safely), merges an `[mcp_servers.assethub]` section into
+`$CODEX_HOME/config.toml` (default `~/.codex`, original saved as
+`config.toml.bak-<timestamp>`), then runs `doctor --mcp` and prints a checklist
+(`--json` for machine output). Use `--client claude|codex|both` to limit the
+targets.
+
+MCP does not need the CLI. Setup is only a shortcut: both clients call the hosted
+`/api/mcp` server directly and read the key from the `ASSETHUB_API_KEY`
+environment variable. The Claude Code entry is
+`claude mcp add-json assethub '{"type":"http","url":"https://app.assethub.io/api/mcp","headers":{"Authorization":"Bearer ${ASSETHUB_API_KEY}","X-AssetHub-Workspace":"<id>"}}' --scope user`,
+so the key is never written to Claude Code's config or passed on a command line,
+and removing the CLI does not disconnect MCP. Codex uses `bearer_token_env_var`.
+Setup never writes the key to a shell profile; run `assethub setup --print-env` to
+print the `export ASSETHUB_API_KEY=...` line, and export it in the shell that
+starts Claude Code or Codex. The key is redacted
+(`ah_…last4`) everywhere else.
+
 ## API discovery and Workspace Skills
 
 Use `api search [query]` to discover the authenticated server catalog and
@@ -27,6 +56,56 @@ are required together; `--context` also selects the execution canvas and must
 match `--canvas` when supplied. Stale revisions and unsupported engines fail
 before generation. Guidance does not expand the model's supported part boundaries.
 
+Body-aware graph runs accept `--base-body <mesh-asset-id>`. The server verifies
+that the GLB belongs to the selected workspace, renders front/oblique/side/back
+references from that exact mesh, and supplies them to preparation and splitting:
+
+```sh
+assethub parts split --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" \
+  --part-extractor 'V3.0.7 Artist Skills' --base-body mesh_42 \
+  --skill-mode auto --auto-repair true \
+  --skill-planner-model openai/gpt-5.6-luna --wait
+```
+
+`--skill-planner-model` changes only workspace Skill selection for that run.
+Allowed models are `openai/gpt-5.6-sol`, `openai/gpt-5.6-luna`, and
+`anthropic/claude-opus-5.5`; omitting it keeps the current SOL default.
+
+Character assembly Alpha is an explicit option on the existing graph entry:
+
+```sh
+assethub production analyze --source-id <owned-image> --canvas <id> \
+  --part-extractor 'V3.0.9 Garment Boundaries' --pipeline-depth composition \
+  --assembly-policy concept-to-character-v1 \
+  --mesh-generation-json '{"modelId":"meshGen.tripo_p2_preview","faceLimit":10000,"params":{"quad":true,"texture":true,"pbr":true,"textureQuality":"standard"}}' \
+  --operation-id <uuid>
+```
+
+It selects the existing Quick assembly (V3) composer, which returns measured part
+pivots for the native review handoff. Explicit incompatible composer selections
+are rejected before dispatch; omitted policy preserves existing defaults.
+It requires existing Internal graph access and Composer body-first/background
+capabilities; a Max plan alone does not grant graph access. The selected policy
+is stored with the graph. Existing production and mesh charges apply. Outputs
+are reviewable candidates, not approved characters; detailed finishing remains
+an explicit follow-up. This option does not add a finishing fee or authorize
+paid regeneration. Omit it to preserve the existing production flow. Reuse the
+same operation ID after an uncertain response rather than starting another run.
+
+`--mesh-generation-json` supplies one explicit graph mesh provider and its options.
+The server applies the existing strict `mesh.generate` model contract before any
+graph credit hold; graph-unsupported options are rejected, never silently substituted.
+P2 Quad has a maximum faceLimit of 25000. Graph settings do not support
+`isLowPoly`, `generateParts`, `ultraMode`, `outputQuality`, or `poseMode`.
+The selected settings are frozen for first generation and retries. Omit the
+option to preserve the legacy provider defaults. P2 Quad retains original FBX;
+the composed GLB is a triangulated preview, not proof of Quad topology.
+
+There is no aggregate credit cap on this graph operation. The production fee,
+each part's mesh generation and composition use their existing billing. Choose
+`--pipeline-depth parts` without `--assembly-policy` to inspect parts before
+authorizing mesh generation. The new settings do not bypass that stopping point.
+
 ## Personal API keys
 
 Log in once with a personal key, then select its workspace:
@@ -111,6 +190,28 @@ explicit overrides. `auth logout` removes the selected saved profile (or the
 saved default); environment credentials remain under your shell’s control.
 Diagnostics omit API keys and raw server error bodies.
 
+## Updating the CLI
+
+```sh
+assethub update --check    # report the latest published version; installs nothing
+assethub update --dry-run  # print the install command it would run
+assethub update            # install the latest version (asks first in a terminal)
+assethub update --yes      # install without asking
+```
+
+`update` reads the latest `@assethub/cli` version with `npm view` (so your
+`.npmrc` registry, auth token and proxy apply; it reads the registry directly
+only when npm is unavailable), finds which package manager installed the
+running CLI globally (npm, pnpm, yarn, bun or Volta), and runs that manager's
+global install pinned to the exact version. Your saved login in
+`~/.assethub/config.json` lives outside the package and is never touched, so you
+do not log in again. Afterwards it runs the updated `assethub doctor` with the
+same `--profile`/`--config` and reports `auth` as `pass`, `fail`, or
+`not_configured`; it fails if the `assethub` on your PATH still reports the old
+version. It never downgrades. A CLI run through `npx`, installed as a project
+dependency, or built from a source checkout is not updated in place; the error
+says what to do instead.
+
 ## Historical meshes and artifact graphs
 
 Lists are scoped to the selected workspace, including assets created in the UI. Mesh search
@@ -248,23 +349,104 @@ Existing parts commands use the same canvas and durable operation storage:
 assethub parts split --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" --part-extractor V1.5 --wait
 # Select only the parts to execute; --all-ready selects all ready tasks.
 assethub parts split --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" --part-extractor V1.5 --all-ready --wait
-# Internal graph versions run the complete split through one analyze receipt.
+# Graph versions run the complete split through one analyze receipt.
 assethub production agents
 assethub parts split --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" --part-extractor V3.6.1 --all-ready --wait
-# CLI 0.1.20+: existing Internal V3.6.5 and Pluffy models; check server availability first.
+# CLI 0.1.20+: V3.6.5 and Pluffy models; check server availability first.
 assethub parts split --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" --part-extractor V3.6.5 --all-ready --wait
 assethub production analyze --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" --part-extractor pluffy --wait
 assethub production automation --canvas "$CANVAS_ID" --input-json @batch.json --wait
 ```
 
+### V4 Character Assembly: image to assembled 3D character
+
+One command runs the whole pipeline (parts, meshes, Blender assembly and review) and
+saves the assembled character GLB:
+
+```sh
+assethub production analyze --file ./concept.png --part-extractor v4 \
+  --name "My character" --canvas "$CANVAS_ID" --wait --download --out-dir ./character
+```
+
+A run takes about an hour, so `--wait` defaults to a 2 hour limit for V4
+(override with `--timeout-ms`). The run finishes `completed` when the assembly
+passes review, and `needs_review` (exit code 3) when it stops with the best
+assembly it made; both return that assembly as a mesh output. `failed` means no
+assembly was made. Follow a run started without `--wait` with
+`runs watch <run-id> --timeout-ms 7200000`.
+
+While a V4 run works, `--wait`, `runs watch` and `runs get` show where it is.
+The receipt's `progress` field has the phase, a one-line summary, each part's
+state and the Blender assembly rounds, in the words of the canvas Part Composer
+card. `--wait` and `runs watch` print a stderr line only when it changes:
+
+```text
+[run] 557d2a58-… running · Step 3 of 4 · Making the parts · 3 of 9 meshes ready · 4 redoing, 2 checking
+```
+
+```sh
+assethub runs watch <run-id> --timeout-ms 7200000 --download --out-dir ./character
+assethub runs get <run-id>                                   # JSON receipt, progress included
+assethub runs get <run-id> --download --out-dir ./character  # save the assembled GLB
+```
+
+A finished run keeps its `progress`. A failed one also carries
+`error.code: CHARACTER_ASSEMBLY_NOT_ACCEPTED` with the reason it stopped.
+
+Pick a stopped run back up (no new charge) with its run ID; `--wait`
+follows the same run until the resumed attempt finishes:
+
+```sh
+assethub production resume <run-id> --wait --download --out-dir ./character
+```
+
+`runs get <run-id>` then reads it as `running` again, and its result is replaced
+by the resumed run's own when it finishes. An order ID still works without
+`--wait`. The API
+contract is in `docs/api-character-assembly-progress.md`.
+
+### Batch runs: many images, or one image many times
+
+`production batch` starts one `production analyze` per image, and per `--repeat`,
+with the same agent and options on one canvas. Use it to run V4 over several
+concepts, or to repeat one concept and compare how consistent the results are:
+
+```sh
+assethub production batch --file ./harpy.png --file ./satyr.png --repeat 2 \
+  --part-extractor v4 --yes --wait --concurrency 2 --download --out-dir ./batch
+assethub production batch --files-dir ./concepts --part-extractor v4 --yes
+```
+
+- Images: `--file` (repeatable), `--files-dir` (its .png/.jpg/.jpeg/.webp files by
+  name), `--source-id` and `--source-url` (repeatable). At most 20 runs per batch.
+- More than one run needs `--yes`: each one is a paid run (V4 takes about an hour).
+- Without `--canvas`, the batch gets one new canvas. Orders are named
+  `<--name> <image> #<repeat>`.
+- Every other `production analyze` option applies to each run.
+- The command prints the batch `--operation-id` first. Rerun the same command
+  with it to resume: started runs are read back, not started or charged again,
+  and different inputs under that ID are refused.
+- When the workspace is at its active agent-run limit, an image is `deferred`,
+  not failed. With `--wait`, it is started once one of the batch's runs finishes.
+  Without `--wait`, rerun the command later to start it.
+- `--wait` keeps at most `--concurrency` (default 2) of the batch's runs going.
+  It prints a stderr line per change and saves each run's outputs under
+  `<out-dir>/<image>/run-<repeat>/`.
+
+The JSON output lists every item with its `status` (`dispatched`, `deferred`,
+`failed`, `pending`, or the finished run's status), `runId` and receipt. Exit
+code 0 means every run started (or, with `--wait`, completed). 3 means some
+are deferred, pending or `needs_review`. 1 means one failed. MCP clients get the
+same behaviour from the `production_analyze_batch` tool.
+
 `parts split` keeps separate analysis and selected-part execution phases. Each phase
 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`
+For `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+), `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
+Boundaries`, and `Humanoid Assembly` (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`,
@@ -354,6 +536,79 @@ truncated exports require `--allow-truncated`. Other commands, including product
 retain their existing API behavior and do not yet create these receipts.
 `autopilot --demo` is an experimental demo requiring the AssetHub monorepo and its unpublished development dependency `@assethub/autopilot-core`. Standalone project workflow commands do not require or install it. Autonomous budgeted improvement is a later stage.
 
+## Trajectory memory
+
+Internal-only. `memorize` captures a canvas as a reusable recipe; `replay`
+re-runs a memory's recipe onto a new image.
+
+```sh
+# Whole canvas, or just the shapes you name (max 256 tldraw shape ids).
+assethub memory memorize --canvas "$CANVAS_ID" --wait
+assethub memory memorize --canvas "$CANVAS_ID" --nodes shape:a,shape:b --wait
+
+# Replay one memory onto a registered asset.
+assethub memory replay "<graphId>:<nodeId>" --source ast_x --wait
+```
+
+`--source` must be an asset your workspace owns — an `outputs[].assetId` from an
+earlier job, or a generation `resourceId`. A `url` is refused with 400
+`UNSUPPORTED_SOURCE`, because a replay needs a registered image rather than a
+link; bring a remote one in with `files import` first.
+
+`memorize` reserves credit for up to 100 trajectory summaries and settles the
+number actually indexed. If a selection has more than 100 candidates, none are
+automatically indexed; use `--nodes` to select a smaller history. Check
+`job.indexKnown` and `job.trajectoriesIndexed` after completion: saving a graph
+alone does not make its recipes searchable. `--canvas` takes a positive integer.
+Personal-key commands use the selected profile workspace or `--workspace`.
+The replay walk itself meters per step through each model's own consume plan as
+it runs, so a replay costs the sum of its executable steps and there is no
+route-level hold.
+
+Three behaviours worth knowing before scripting against it:
+
+- **A replay that fails is a finished run.** `status` is the walk's verdict, not
+  the state of the machinery — a walk whose every step failed reports `failed`
+  having completed normally. Read `steps[]` for what actually happened;
+  `skipped` and `blocked` are steps the recipe could not run.
+- **A match with no prepared memory is a result, not an error.** It means the
+  organization has curated nothing. Exit 0, empty result.
+- **A canvas you do not own answers 404, not 403** — the same answer a canvas
+  that does not exist gets. That is deliberate: canvas ids are sequential enough
+  that a distinguishable 403 would let a caller learn which ones exist. Both
+  exit 2 with the server's message, and the CLI does not tell them apart.
+
+Exit codes follow the usual convention: `0` completed, `1` terminal failure,
+`2` input/auth/capability, `3` timeout or still pending when `--wait` gave up.
+
+## Canvas export (artifact-graph zips)
+
+Internal-only. Export an organization's workflow canvases as `ag.graph-folder.v1`
+zips — the same exporter the dev dashboard's canvas-export panel drives, without
+a browser. A non-internal key gets 404 from every call here, printed as-is with
+exit 2.
+
+```sh
+# Find the org by name or by a member's email, then list its workflow canvases.
+assethub org search acme
+assethub org canvases --org "$ORG_ID"
+
+# Queue exports (chunked into POSTs of 50), wait for every job, download the zips.
+assethub graph export-canvas --org "$ORG_ID" --canvas 30917,30918 --wait --out-dir ./exports
+```
+
+Without `--wait` the command prints the queued `jobs` and returns. With it, every
+job is polled every 5 seconds until `ready` or `failed` (default `--timeout`
+1800 s), each ready zip is streamed to `<out-dir>/<projectId>-rev<rev>.zip` with
+its `sha256` and `bytes` recorded, and the output is
+`{jobs, omitted, downloaded, failed}` (the signed archive URLs are never printed
+— the zip is on disk). A canvas that already has an export in flight is answered
+with that job rather than a second one.
+Exit codes: 0 success, 1 a job failed, a download failed, or a requested id was
+`omitted` (not a workflow canvas owned by `--org` — the API drops it and the
+command names it rather than reporting a partial batch as success), 2 caller
+error, 3 `--wait` timed out (the partial job list is still printed).
+
 ## Storyboard project workflow
 
 These API-key commands work from the standalone CLI. Canvas/context commands use
@@ -606,7 +861,7 @@ Image generation uses the `v2` endpoint with mandatory canvas history.
 `--api-version v1` is rejected; run `assethub capabilities` to check availability.
 
 Part extraction uses the same names shown in the AssetHub product: `V1.5`,
-`V2.0 alpha`, `V2.1 alpha`, and the Internal-only aliases `V3.6.1`
+`V2.0 alpha`, `V2.1 alpha`, and the graph aliases `V3.6.1`
 (`V3.6.1 Primary Images First`), `V3.6.3` (`V3.6.3 Fast Analysis`),
 `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;
@@ -614,9 +869,9 @@ and `pluffy` (`Chibi Character (Pluffy) v3.1`). CLI 0.1.20 adds the latter two;
 `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
+`Humanoid Assembly` (`humanoid-assembly`, `humanoid_assembly_auto`; CLI 0.1.26+)
+are additional graph extractors; which extractors your account can run is
+decided by the server; 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
@@ -660,6 +915,25 @@ expired proof by logging in again. Explicit `--profile` uses its saved proof and
 ignores environment credentials; an explicit `--api-key` can supply the workspace
 key. Generation uses normal workspace credits.
 
+`composer run --model V6` selects Auto assemble (`part_composer_v6_auto_assemble`).
+`composer run --model V5.1` runs Skill assembly: the CLI sends it as a codex
+`mesh.refine` with `skillAssembly: "assemble-character"` because the server runs
+the bundled Character Assembly skill in the Blender sandbox, not as a compose
+model. It uses identity starting transforms unless you pass `--transforms-json`,
+accepts only Agents API `--agent-model` values and an optional
+`--reasoning low|medium|high`. `composer refine --from-run <run-id> --skill-assembly`
+does the same from a finished compose run's placement. Both models follow their
+release gates. Without `--timeout-ms`, `--wait` allows 95 minutes for V6 and 125
+minutes for V5.1.
+
+`composer run --optimize off|light|medium|heavy` is the Part Composer node's
+Optimize output preset. Assembly always works on its own shrunk parts; the final
+bake uses the original full-resolution meshes and then keeps ~75% (`light`),
+~50% (`medium`) or ~25% (`heavy`) of the geometry with WebP textures, or all of
+it (`off`, also clearing a ratio saved on a `--from-run` or `--input-json`
+input). It is refused with a base body and with `--node`, where the node's own
+Optimize output setting applies.
+
 `composer refine --from-run` accepts a `mesh.compose` or prior `mesh.refine` run
 and uses that receipt's final `composition.transforms` and any replacement
 `composition.parts` on the same canvas, preserving `parentRunId` lineage. If the

package/dist/appEnv.d.ts

@@ -0,0 +1,20 @@
+export declare const LAUNCH_AGENT_LABEL = "io.assethub.env";
+export declare const API_KEY_ENV = "ASSETHUB_API_KEY";
+type Run = (file: string, args: string[]) => Promise<{
+    code: number;
+    output: string;
+}>;
+export declare const launchAgentPath: (home: string) => string;
+/** ProgramArguments for the login agent: `assethub <args>` via this node and CLI, or the login shell's. */
+export declare const launchAgentProgram: (node: string, cli: string, args: string[]) => string[];
+export declare const launchAgentPlist: (program: string[]) => string;
+/** The ASSETHUB_API_KEY that apps started now would receive, if any. */
+export declare const readLaunchdKey: (run: Run) => Promise<string | undefined>;
+export declare const loadKeyIntoLaunchd: (key: string, run: Run) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+    detail: string;
+}>;
+export {};
+//# sourceMappingURL=appEnv.d.ts.map

package/dist/appEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appEnv.d.ts","sourceRoot":"","sources":["../src/appEnv.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,kBAAkB,oBAAoB,CAAA;AACnD,eAAO,MAAM,WAAW,qBAAqB,CAAA;AAG7C,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC,CAAA;AAEpF,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,MACuB,CAAA;AActE,2GAA2G;AAC3G,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,MAAM,EAAE,KAAG,MAAM,EAQpF,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,EAAE,KAAG,MAiBvC,CAAA;AAEd,wEAAwE;AACxE,eAAO,MAAM,cAAc,GAAU,KAAK,GAAG,KAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAIzE,CAAA;AAID,eAAO,MAAM,kBAAkB,GAC7B,KAAK,MAAM,EACX,KAAK,GAAG,KACP,OAAO,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAC,GAAG;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAKlD,CAAA"}

package/dist/appEnv.js

@@ -0,0 +1,62 @@
+import { join } from 'node:path';
+// macOS apps started from the Dock or Finder (Claude, Codex) do not read shell
+// profiles, so an exported ASSETHUB_API_KEY never reaches them and the MCP
+// header `Bearer ${ASSETHUB_API_KEY}` goes out empty (HTTP 401). launchd's user
+// environment does reach them: `launchctl setenv` covers apps started from now
+// on, and a LaunchAgent repeats it at every login by running `assethub env load`,
+// which reads the key from the CLI's own config. The key is never written to the
+// plist or to any other new file.
+export const LAUNCH_AGENT_LABEL = 'io.assethub.env';
+export const API_KEY_ENV = 'ASSETHUB_API_KEY';
+const LAUNCHCTL = '/bin/launchctl';
+export const launchAgentPath = (home) => join(home, 'Library', 'LaunchAgents', `${LAUNCH_AGENT_LABEL}.plist`);
+const xml = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+// launchd's PATH has neither nvm's node nor a global `assethub`, so the agent
+// runs the node and CLI that ran setup. Once that node version is removed or
+// the CLI moves, it asks the user's login shell for `assethub` instead.
+const LAUNCH_AGENT_SCRIPT = [
+    'node="$1"; cli="$2"; shift 2',
+    'if [ -x "$node" ] && [ -f "$cli" ]; then exec "$node" "$cli" "$@"; fi',
+    'exec "${SHELL:-/bin/zsh}" -lic \'exec assethub "$@"\' assethub "$@"',
+].join('\n');
+/** ProgramArguments for the login agent: `assethub <args>` via this node and CLI, or the login shell's. */
+export const launchAgentProgram = (node, cli, args) => [
+    '/bin/sh',
+    '-c',
+    LAUNCH_AGENT_SCRIPT,
+    'assethub-env',
+    node,
+    cli,
+    ...args,
+];
+export const launchAgentPlist = (program) => [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <key>Label</key>',
+    `  <string>${LAUNCH_AGENT_LABEL}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    ...program.map(arg => `    <string>${xml(arg)}</string>`),
+    '  </array>',
+    '  <key>RunAtLoad</key>',
+    '  <true/>',
+    '</dict>',
+    '</plist>',
+    '',
+].join('\n');
+/** The ASSETHUB_API_KEY that apps started now would receive, if any. */
+export const readLaunchdKey = async (run) => {
+    const result = await run(LAUNCHCTL, ['getenv', API_KEY_ENV]);
+    const value = result.code === 0 ? result.output.trim() : '';
+    return value || undefined;
+};
+// `launchctl setenv` only takes the value as an argument, so the key is briefly
+// visible to local `ps` while it runs; the result never echoes it.
+export const loadKeyIntoLaunchd = async (key, run) => {
+    const result = await run(LAUNCHCTL, ['setenv', API_KEY_ENV, key]);
+    return result.code === 0
+        ? { ok: true }
+        : { ok: false, detail: `launchctl setenv exited ${result.code}: ${result.output.split(key).join('[key]').trim().slice(0, 200)}` };
+};

package/dist/canvasGraphDownload.d.ts

@@ -0,0 +1,11 @@
+export type DownloadedCanvasGraphZip = {
+    path: string;
+    bytes: number;
+    sha256: string;
+};
+export declare const downloadCanvasGraphZip: ({ url, destinationPath, timeoutMs, }: {
+    url: string;
+    destinationPath: string;
+    timeoutMs?: number;
+}) => Promise<DownloadedCanvasGraphZip>;
+//# sourceMappingURL=canvasGraphDownload.d.ts.map

package/dist/canvasGraphDownload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasGraphDownload.d.ts","sourceRoot":"","sources":["../src/canvasGraphDownload.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf,CAAA;AAiDD,eAAO,MAAM,sBAAsB,GAAU,sCAI1C;IACD,GAAG,EAAE,MAAM,CAAA;IACX,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,KAAG,OAAO,CAAC,wBAAwB,CAuCnC,CAAA"}

package/dist/canvasGraphDownload.js

@@ -0,0 +1,108 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, rename, unlink } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+/** Refuse anything past this — an artifact-graph zip is capped server-side at
+ *  400 MiB of retained blobs, so a larger body is not the file we asked for. */
+const MAX_ZIP_BYTES = 1024 * 1024 * 1024;
+/** The only error messages that leave this module verbatim. A network error
+ *  can carry the signed URL, so anything else collapses to a fixed string. */
+const SAFE_MESSAGES = new Set([
+    'Invalid download URL',
+    'Empty file response',
+    'File exceeds 1 GiB',
+    'Too many redirects',
+]);
+/**
+ * Stream one signed artifact-graph zip to disk.
+ *
+ * The signed URL is used WITHOUT API credentials — it authenticates itself —
+ * and follows up to five redirects, because the storage signer may answer with
+ * one; each hop is checked (no HTTPS-to-HTTP, no public-to-private host). Bytes
+ * go through a sha256/byte meter into a temp file beside the destination and
+ * are renamed into place only once the body ended cleanly, so a half-written
+ * zip never sits under the final name. Errors are bounded to a fixed set of
+ * messages so a signed URL never lands in the CLI's JSON output.
+ */
+const MAX_REDIRECTS = 5;
+const isPrivateHost = (hostname) => {
+    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (host === 'localhost' || host.endsWith('.localhost') || host === '::1' || host === '0.0.0.0')
+        return true;
+    if (/^(fc|fd|fe8|fe9|fea|feb)/.test(host) && host.includes(':'))
+        return true;
+    const octets = host.split('.').map(Number);
+    if (octets.length !== 4 || octets.some(n => !Number.isInteger(n)))
+        return false;
+    const [a, b] = octets;
+    return a === 10 || a === 127 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+};
+const checkedUrl = (value, from) => {
+    const parsed = new URL(value);
+    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password)
+        throw new Error('Invalid download URL');
+    // A redirect may not downgrade to plain HTTP or move from a public host into
+    // a private network or this machine.
+    if (from?.protocol === 'https:' && parsed.protocol !== 'https:')
+        throw new Error('Invalid download URL');
+    if (from && !isPrivateHost(from.hostname) && isPrivateHost(parsed.hostname))
+        throw new Error('Invalid download URL');
+    return parsed;
+};
+/** The storage signer may answer with a redirect; every hop is checked before it is followed. */
+const fetchFollowingSafeRedirects = async (url, signal) => {
+    let current = checkedUrl(url);
+    for (let hop = 0;; hop++) {
+        const response = await fetch(current.toString(), { signal, redirect: 'manual' });
+        const location = response.headers.get('location');
+        if (response.status < 300 || response.status >= 400 || !location)
+            return response;
+        if (hop >= MAX_REDIRECTS)
+            throw new Error('Too many redirects');
+        await response.body?.cancel();
+        current = checkedUrl(new URL(location, current).toString(), current);
+    }
+};
+export const downloadCanvasGraphZip = async ({ url, destinationPath, timeoutMs = 120_000, }) => {
+    const destination = resolve(destinationPath);
+    const directory = dirname(destination);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = join(directory, `.${randomUUID()}.tmp`);
+    try {
+        const response = await fetchFollowingSafeRedirects(url, AbortSignal.timeout(timeoutMs));
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        if (!response.body)
+            throw new Error('Empty file response');
+        const hash = createHash('sha256');
+        let bytes = 0;
+        const meter = new Transform({
+            transform(chunk, _encoding, callback) {
+                bytes += chunk.length;
+                if (bytes > MAX_ZIP_BYTES)
+                    return callback(new Error('File exceeds 1 GiB'));
+                hash.update(chunk);
+                callback(null, chunk);
+            },
+        });
+        await pipeline(Readable.fromWeb(response.body), meter, createWriteStream(temporary, { flags: 'wx', mode: 0o600 }));
+        if (bytes === 0)
+            throw new Error('Empty file response');
+        await rename(temporary, destination);
+        return { path: destination, bytes, sha256: hash.digest('hex') };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : '';
+        throw new Error(SAFE_MESSAGES.has(message) || /^HTTP \d{3}$/.test(message)
+            ? message
+            : 'File download failed');
+    }
+    finally {
+        await unlink(temporary).catch(error => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
+    }
+};

package/dist/execution.d.ts

@@ -38,7 +38,9 @@ export declare class CliExecutionError extends Error {
     readonly operationId?: string | undefined;
     readonly execution?: CanvasExecution | undefined;
     readonly runId: string | undefined;
-    constructor(message: string, exitCode?: number, operationId?: string | undefined, execution?: CanvasExecution | undefined, runId?: string | undefined);
+    constructor(message: string, exitCode?: number, operationId?: string | undefined, execution?: CanvasExecution | undefined, runId?: string | undefined, options?: {
+        cause?: unknown;
+    });
 }
 /** Kept only for SIGINT reporting; interrupting the client never cancels server work. */
 export declare const activeExecution: {
@@ -47,9 +49,9 @@ export declare const activeExecution: {
     runId?: string;
     execution?: CanvasExecution;
 };
-export declare const childOperationId: (parent: string, step: string) => string;
 export declare const executeRecorded: (session: Session, operation: Operation, body: RequestBody, options?: SubmitOptions) => Promise<{
     execution: CanvasExecution;
+    workspaceSkillAdmission?: import("@assethub/api-client").WorkspaceSkillAdmissionDecision;
     jobId: string;
     imageGenId: string;
     status: "queued";
@@ -118,6 +120,7 @@ export declare const resumeRecorded: (options: Omit<SessionOptions, "canvasId" |
     expectedBodySubset?: Record<string, unknown>;
 }) => Promise<{
     execution: CanvasExecution;
+    workspaceSkillAdmission?: import("@assethub/api-client").WorkspaceSkillAdmissionDecision;
     jobId: string;
     imageGenId: string;
     status: "queued";

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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"}