@assethub/cli 0.1.6 → 0.1.7

package/README.md

@@ -2,6 +2,318 @@
 
 Command line interface for AssetHub.
 
+## Agent generation with canvas history
+
+This release uses the Internal `api_canvas_execution` gate. Run `assethub capabilities`
+first. Image, mesh, parts split, and production analyze/execute/automation refuse to dispatch if canvas history is unavailable.
+The current public API remains compatible with clients that omit `executionContext`.
+
+```sh
+assethub image generate --prompt "small stylized robot" --agent my-agent --wait > image.json
+CANVAS_ID=$(jq -r '.execution.canvas.id' image.json)
+IMAGE_ASSET_ID=$(jq -r '.execution.outputs[0].assetId' image.json)
+IMAGE_RUN_ID=$(jq -r '.execution.runId' image.json)
+assethub mesh generate --source-id "$IMAGE_ASSET_ID" --canvas "$CANVAS_ID" \
+  --derived-from-run "$IMAGE_RUN_ID" --agent my-agent --wait > mesh.json
+assethub graph show --canvas "$CANVAS_ID"
+assethub runs list --canvas "$CANVAS_ID"
+assethub canvas open "$CANVAS_ID"
+```
+
+Without `--canvas`, the first generation creates one canvas per real working
+directory, API origin and organization. `canvas use <id>` changes the selection.
+An inaccessible selected canvas is an error; the CLI does not silently make another.
+`canvas open` prints JSON and opens a browser only in a terminal.
+
+Each generation returns `execution` with the canvas URL, run/job IDs, stable output
+asset IDs, history status, and credit usage when available. History persists while
+all browsers are closed. Uploaded images are promoted to owned durable assets.
+Use `--input-json @request.json` for a complete request, or the existing file/stdin/
+source flags. A `source create` or `files import` JSON response can be passed to
+`--source-json @source.json`; generated asset IDs can be passed to `--source-id`.
+
+The CLI saves each request before dispatch under `~/.assethub/state/operations`
+(or `ASSETHUB_CLI_STATE_DIR`). Those files contain inputs, never API keys. Keep the
+state directory private. `--operation-id <uuid>` supplies an operation identity;
+retries and `runs resume <operation-id>` reuse its identical body and key. A new
+candidate needs a new operation ID. `runs watch <run-id>` only reads status.
+
+stdout contains final JSON; stderr contains progress. Exit codes are 0 for accepted/
+completed, 1 for terminal failure/partial, 2 for input/auth/capability/budget errors,
+3 for timeout/history pending/needs review, and 130 for Ctrl-C. Timeout and Ctrl-C
+leave server execution running and return known identities.
+
+External agents can evaluate downloaded artifacts with their own tools and store
+an assessment without starting another model call:
+
+```sh
+assethub evaluations submit --canvas "$CANVAS_ID" --artifact "$IMAGE_ASSET_ID" \
+  --report ./evaluation.json --agent my-agent --require-pass
+assethub evaluations list --canvas "$CANVAS_ID"
+assethub graph lineage --canvas "$CANVAS_ID" --artifact "$IMAGE_ASSET_ID"
+assethub graph export --canvas "$CANVAS_ID" --out ./graph.json
+```
+
+`evaluation.json` requires the strict report fields `schemaVersion`,
+`rubric`, `verdict: pass|fail|needs_review`, `criteria`, `referenceAssetIds`, and
+`evidenceAssetIds` for comparable reports. The server records `agent_submission`
+and authenticated actor provenance. This never counts as human approval.
+`--require-pass` returns 1 for fail and 3 for missing/needs-review verdicts.
+
+For example, an agent that has not inspected the output yet can submit:
+
+```json
+{
+  "schemaVersion": "assethub.evaluation-submission.v1",
+  "rubric": {"id": "asset-quality", "version": "1"},
+  "verdict": "needs_review",
+  "criteria": [
+    {
+      "id": "visual-quality",
+      "verdict": "needs_review",
+      "reason": "Artifact inspection is pending."
+    }
+  ],
+  "referenceAssetIds": [],
+  "evidenceAssetIds": []
+}
+```
+
+Replace the verdict and reason with the actual assessment after inspecting the
+artifact; reference and evidence IDs must belong to the authenticated organization.
+
+Existing parts commands use the same canvas and durable operation storage:
+
+```sh
+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 V3.6.1 runs the complete graph 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
+assethub production automation --canvas "$CANVAS_ID" --input-json @batch.json --wait
+```
+
+`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`), 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.
+Automation runs the existing complete batch pipeline, including mesh generation;
+its `images[]` share the selected canvas. `batch.json` uses the existing automation
+request shape, including `agentVersion`, `images` (owned `imageAssetId`, `uploadId`,
+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.
+
+`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,
+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.
+
+## Storyboard project workflow
+
+These API-key commands work from the standalone CLI. Canvas/context commands use
+`api_canvas_execution`; native moodboards additionally require an internal actor
+with `moodboard_style_reference_enabled`. Select a key belonging to the intended
+workspace before uploading source material. API keys are never part of context.
+
+```sh
+# No API key is needed for local extraction. Optional dependencies are reported.
+assethub project ingest ./client-sources --out-dir ./extracted --exclude-dir generated
+assethub canvas create --name "Storyboard scene study" > canvas.json
+CANVAS_ID=$(jq -r .id canvas.json)
+assethub canvas import --canvas "$CANVAS_ID" --file ./extracted/storyboard.png > storyboard.json
+assethub canvas import --canvas "$CANVAS_ID" --file ./character-face.png > character.json
+assethub canvas import --canvas "$CANVAS_ID" --file ./primary-style.png > style.json
+
+# Supply prompt + source text + imageAssetIds in analysis-request.json.
+# Keep facts, uncertain identities and proposed backgrounds separate.
+assethub language vision --input-json @analysis-request.json \
+  --operation-id 61e3a99c-30b7-4f41-8d57-2789ccdc7c92 --out analysis.json
+
+# Prepare context.json from the inspected source facts and analysis.
+assethub canvas context put --canvas "$CANVAS_ID" --file ./context.json --if-version 0
+assethub canvas context get --canvas "$CANVAS_ID" --out ./recovered-context.json
+assethub moodboard create --input-json @moodboard.json > board.json
+BOARD_ID=$(jq -r .id board.json)
+assethub moodboard analyze "$BOARD_ID" --wait > revision.json
+REVISION_ID=$(jq -r .id revision.json)
+assethub image generate --canvas "$CANVAS_ID" --context "$CANVAS_ID" \
+  --moodboard-revision "$REVISION_ID" --prompt "Reconstruct this storyboard as a 3D scene" \
+  --wait --download --out-dir ./generated > generated.json
+SOURCE_ID=$(jq -r .assetId storyboard.json)
+OUTPUT_ID=$(jq -r '.execution.outputs[0].assetId' generated.json)
+assethub canvas compare --canvas "$CANVAS_ID" --source-id "$SOURCE_ID" \
+  --asset-id "$OUTPUT_ID" --out ./comparison.html
+assethub evaluations submit --canvas "$CANVAS_ID" --artifact "$OUTPUT_ID" \
+  --report ./review.json --agent my-agent
+```
+
+`project ingest` extracts PDF text/pages, workbook cells and embedded images,
+representative video frames, and image/text sources. It writes `summary.json`,
+`text.md` and `images.json` with source paths, hashes and extraction metadata.
+Dependencies (Poppler, ffmpeg and Python 3) are detected, never installed. Partial
+extraction exits 3 and reports missing dependencies; filenames do not establish
+whether a picture is a storyboard or a 3D reference. Original files stay unchanged.
+
+A context document is an extensible JSON object:
+
+```json
+{
+  "schemaVersion": 1,
+  "title": "EP013 s150",
+  "instructions": {
+    "must": ["Preserve the original character face and pose"],
+    "avoid": ["Generic replacement characters"]
+  },
+  "sources": [
+    {
+      "key": "storyboard",
+      "remoteAssetId": "<owned-image-uuid>",
+      "generationUse": "required"
+    }
+  ],
+  "generationPlan": {"requiredSourceKeys": ["storyboard"]},
+  "sourceFacts": [
+    "Facts established by the original storyboard and story text"
+  ],
+  "inferences": [
+    {"proposal": "Background inferred from story", "status": "proposed"}
+  ],
+  "reviewState": {"status": "awaiting_creator_review"}
+}
+```
+
+`context get --out` writes the document for editing and reuse; stdout contains its
+version/hash envelope. Updating changed content requires `--if-version N` from the
+last read. Image generation pins the current version by default; `--context-version`
+and repeated `--context-source` explicitly select a version and source keys. Required
+references, labelled instructions and source facts are added by the server, and their
+IDs/version/hash are recorded on the run. Retry an uncertain generation with
+`runs resume <operation-id>` to preserve the original pinned inputs.
+
+`moodboard.json` contains `name`, `assetIds` (maximum 12),
+`representativeAssetIds` (maximum 3, all included in assetIds), and optional
+`userNote`. `update <board-id> --input-json @file` creates a new immutable revision;
+`get`, `list`, and `archive` manage existing boards. Analysis uses the existing
+8-credit vision plan for a new attempt, resumes an active job, and reuses a ready
+revision. The combined generation limit is **6 content and style images**: Marza's
+5 required identity/storyboard references leave room for 1 style representative.
+
+Image import persists upload identity before registration and recovers the same
+asset after an uncertain response; `--upload-id` resumes a known completed upload.
+Identical moodboard creation input uses the same operation identity; supply a fresh
+`--operation-id` when intentionally creating another identical board. Language
+commands require a UUID operation ID: reuse it with the same input after a timeout.
+
+Comparisons are portable HTML with embedded image bytes and a SHA-256 provenance
+sidecar. They remain `awaiting_creator_review`; an agent evaluation is not creator
+approval. Native project assets and generation history are saved in AssetHub.
+`canvas layout` appends native image nodes and source/output edges through the
+authoritative canvas room (Internal rollout). It preserves matching existing nodes
+and rejects identity collisions. `canvas import` alone preserves an asset without
+changing layout. Use the owned asset IDs returned by import or generation, including `image_...` IDs.
+For example, create `layout.json` with those IDs:
+
+```json
+{
+  "images": [
+    {
+      "assetId": "<storyboard-asset-id>",
+      "role": "source",
+      "x": 0,
+      "y": 0,
+      "name": "Original storyboard"
+    },
+    {
+      "assetId": "<generated-asset-id>",
+      "role": "output",
+      "x": 600,
+      "y": 0,
+      "name": "Generated candidate — review pending"
+    }
+  ],
+  "connections": [
+    {
+      "sourceAssetId": "<storyboard-asset-id>",
+      "targetAssetId": "<generated-asset-id>"
+    }
+  ]
+}
+```
+
+```sh
+assethub canvas layout --canvas "$CANVAS_ID" --input-json @layout.json
+```
+
+Internal workspace preparation (monorepo checkout only):
+
+```sh
+infisical run --env=prod -- node --import tsx packages/assethub-cli/src/index.ts \
+  workspace prepare --internal --manifest ./workspace.json --state ./workspace-state.json
+```
+
+`workspace.json` provides `orgId`, `actorId`, `actorEmail`, `projectName`,
+`boardName`, `userNote`, and `references` / optional `inputs` and `outputs` arrays containing
+`path`, `name`, optional `section`, and optional `representative` (up to three
+references). An output can set `sourcePath` to an imported input path to retain a
+native canvas connection from storyboard to result. The internal actor must
+already belong to the selected workspace.
+This creates a native workflow canvas, owned image assets, and a native moodboard
+revision. `workspace sync` appends new images from the manifest; the original
+moodboard reference revision stays frozen. Preserve the state file for resuming.
+`workspace analyze` uses the native analysis model, prompt and parser with the
+existing OpenRouter environment, saving provider usage beside the state file.
+It uses only the saved revision's frozen references, checks the original owned
+assets again, and claims one analysis attempt before calling the provider.
+Resumed order and image identities, storage paths and source hashes are checked
+against owned records before reading storage or changing the canvas.
+`workspace verify` checks persisted native schema, ownership and uploaded hashes.
+Optional `contextNote` (up to 24,000 characters) adds a readable native text node
+beside the image groups. The full project context is saved separately below.
+`workspace self-check --internal` checks native schema, context roundtrips and
+conflict rejection without credentials.
+
+Save and recover a project's instructions without the local manifest/state:
+
+```sh
+assethub workspace context put --internal --org <workspace-uuid> --actor <internal-user-uuid> \
+  --canvas <canvas-id> --file ./project-context.json
+assethub workspace context get --internal --org <workspace-uuid> --actor <internal-user-uuid> \
+  --canvas <canvas-id> --out ./recovered-context.json
+# To replace changed content, use the version returned by the latest get:
+assethub workspace context put --internal --org <workspace-uuid> --actor <internal-user-uuid> \
+  --canvas <canvas-id> --file ./edited-context.json --if-version <current-version>
+```
+
+The document is a JSON object of at most 256 KiB, with `schemaVersion: 1`, a
+nonempty `title`, `instructions: {must: string[], avoid: string[]}` (at least one
+required instruction), and a nonempty `sources` object array. Other JSON fields
+are retained. Source entries can use `remoteAssetId: <uuid> | null`; every
+explicit `assetId` / `*AssetId` / `*AssetIds` reference must belong to the workspace.
+An unuploaded source may retain a null ID and its provenance.
+
+The native order's `metadata.projectContext` holds the document, version, content
+SHA-256, timestamp and actor. Other metadata is preserved. A changed existing
+document requires `--if-version`; identical-content retries do not create a new
+version. The write also compares the order's `updated_at`, which the native
+`model_workflow_update_updated_at` trigger advances on every update, refusing
+concurrent changes to any order metadata. Documents stay in the request body,
+so large contexts do not exceed URI limits. If multiple active orders belong to
+a canvas, supply `--order`.
+The actor must be an internal user with a writable workspace membership; both
+project and order ownership are checked. `get --out` writes the original document
+and stdout includes its stored envelope. It does not require local CLI state.
+
+These commands require the existing internal Supabase service environment and
+reuse native workspace, moodboard and context contracts separately from the
+public API commands. This internal command is unavailable in a standalone
+published CLI installation.
+
 ```sh
 export ASSETHUB_API_KEY=ah_live_xxx
 
@@ -13,8 +325,39 @@ assethub mesh generate --file ./input.png --wait
 assethub jobs watch job_123 --download --out-dir ./out/job
 assethub parts split --file ./input.png --part-extractor "V1.5" --wait --all-ready --download --out-dir ./out/parts
 assethub parts compare --file ./input.png --preprocess-prompt "clean white background, centered product photo" --part-extractor "V1.5" --wait --all-ready
+assethub runs upload ./out/pluffy-run-2026-07-30 --dry-run
 ```
 
+Uploading a local artifact-graph run:
+
+```sh
+# Validate the run folder without sending anything.
+assethub runs upload ./out/pluffy-run-2026-07-30 --dry-run
+
+# Upload it. Blobs go first, one at a time, then the snapshot.
+assethub runs upload ./out/pluffy-run-2026-07-30 --tag pluffy --description "V3 humanoid"
+```
+
+`<path>` is an `ag.graph-folder.v1` folder — the directory holding
+`manifest.json`, `nodes.jsonl`, `edges.jsonl` and `blobs/`. The wire format is
+`ag.registry.v1`, the same document the artifact-graph registry accepts, so one
+folder can be published to either destination without conversion.
+
+- `--dry-run` runs every local check and prints what _would_ be sent. A folder
+  whose manifest no longer matches its own `nodes.jsonl`, whose blob table
+  disagrees with the graph, or which exceeds the per-request size ceilings is
+  rejected here rather than halfway through an upload.
+- Uploads are resumable. Each blob is checked against the server before it is
+  sent, and blob storage is content-addressed, so re-running the identical
+  command after a failure sends only what is still missing.
+- `--graph-id` / `--stream-id` / `--rev` override the identity derived from the
+  folder name and `manifest.source`. Re-uploading the same revision with
+  different content is refused; bump `--rev` to publish a new revision.
+- `--skip-register` skips the graph-registration call for a graph that already
+  exists.
+- Requires an internal account whose org has the Production Control
+  entitlement; other keys get "cannot upload runs to Production Control".
+
 Configuration:
 
 - `ASSETHUB_API_KEY`: optional when a profile was saved with `auth login`.
@@ -79,12 +422,13 @@ is preferred. Use `--all-ready` rather than explicit `--task-id` values when
 preprocessing is enabled, because the generated-image split creates a separate
 production order.
 
-Image generation defaults to the deployed `v1` endpoint. Pass `--api-version v2`
-only when the `v2` image endpoint is available in the target environment.
+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 public names shown in the AssetHub product:
-`V1`, `V1.5 alpha`, `V1.5`, `V2.0 alpha`, and `V2.1 alpha`. Internal agent
-IDs are intentionally not part of the public CLI interface.
+Part extraction uses the same names shown in the AssetHub product: `V1.5`,
+`V2.0 alpha`, `V2.1 alpha`, and the Internal-only `V3.6.1` alias for
+`V3.6.1 Primary Images First`. Retired names are no longer accepted by the CLI.
+Internal agent IDs are intentionally not part of the CLI interface.
 
 The CLI only uses AssetHub's public API surface and is designed so this package
 can be published independently from the private application monorepo.

package/dist/autopilot.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `assethub autopilot` — drives the auto-split autopilot from the terminal,
+ * rendering the shared event stream coding-agent style.
+ *
+ * The CLI is the primary frontend for the autopilot brain; the in-app chat
+ * window is the same engine + event stream rendered inside the app. This
+ * command currently runs against the deterministic MockBackend (`--demo`); the
+ * real backend (AssetHub API / trigger.dev) is a drop-in AutopilotBackend.
+ */
+type Flags = Record<string, string | boolean | string[]>;
+export declare const commandAutopilot: (positionals: string[], flags: Flags) => Promise<void>;
+export {};
+//# sourceMappingURL=autopilot.d.ts.map

package/dist/autopilot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autopilot.d.ts","sourceRoot":"","sources":["../src/autopilot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAiBH,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC,CAAA;AAmHxD,eAAO,MAAM,gBAAgB,GAC3B,aAAa,MAAM,EAAE,EACrB,OAAO,KAAK,KACX,OAAO,CAAC,IAAI,CAgDd,CAAA"}

package/dist/autopilot.js

@@ -0,0 +1,158 @@
+/**
+ * `assethub autopilot` — drives the auto-split autopilot from the terminal,
+ * rendering the shared event stream coding-agent style.
+ *
+ * The CLI is the primary frontend for the autopilot brain; the in-app chat
+ * window is the same engine + event stream rendered inside the app. This
+ * command currently runs against the deterministic MockBackend (`--demo`); the
+ * real backend (AssetHub API / trigger.dev) is a drop-in AutopilotBackend.
+ */
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { AutopilotEngine, MockBackend, demoConfig, formatEventLine, } from '@assethub/autopilot-core';
+// --- tiny ANSI helpers (no dependency) ---
+const useColor = stdout.isTTY === true;
+const paint = (code, s) => (useColor ? `[${code}m${s}` : s);
+const dim = (s) => paint('2', s);
+const bold = (s) => paint('1', s);
+const green = (s) => paint('32', s);
+const yellow = (s) => paint('33', s);
+const red = (s) => paint('31', s);
+const cyan = (s) => paint('36', s);
+const flagStr = (flags, name) => {
+    const v = flags[name];
+    return typeof v === 'string' ? v : Array.isArray(v) ? v[0] : undefined;
+};
+const flagBool = (flags, name) => flags[name] != null;
+const flagNum = (flags, name) => {
+    const s = flagStr(flags, name);
+    if (s == null)
+        return undefined;
+    const n = Number(s);
+    return Number.isFinite(n) ? n : undefined;
+};
+/** Colorize the shared narration line for the terminal. */
+const colorize = (event, line) => {
+    switch (event.type) {
+        case 'run_started':
+            return bold(cyan(line));
+        case 'phase_changed':
+            return bold(line);
+        case 'log':
+            if (event.level === 'success')
+                return green(line);
+            if (event.level === 'warn')
+                return yellow(line);
+            if (event.level === 'error')
+                return red(line);
+            return dim(line);
+        case 'human_review_requested':
+            return yellow(line);
+        case 'human_review_resolved':
+            return cyan(line);
+        case 'credit_estimate':
+            return dim(line);
+        case 'run_finished':
+            return event.status === 'complete' ? bold(green(line)) : bold(red(line));
+        default:
+            return line;
+    }
+};
+const PLAN_GLYPH = {
+    pending: '○',
+    active: '◐',
+    done: '●',
+    skipped: '⊘',
+    failed: '✗',
+};
+const renderPlan = (plan, indent = 0) => {
+    const pad = '  '.repeat(indent);
+    return plan
+        .map((step) => {
+        const head = `${pad}${PLAN_GLYPH[step.status]} ${step.label}${step.detail ? dim(` — ${step.detail}`) : ''}`;
+        const kids = step.children?.length ? '\n' + renderPlan(step.children, indent + 1) : '';
+        return head + kids;
+    })
+        .join('\n');
+};
+/** Interactive resolver reading a choice from the TTY; falls back to a policy when not a TTY. */
+const makeResolver = (opts) => {
+    return async (request) => {
+        const autoChoice = autoPolicy(request);
+        if (opts.yolo || !opts.interactive) {
+            if (!opts.quiet)
+                stdout.write(dim(`      → auto: ${autoChoice}\n`));
+            return { requestId: request.requestId, choice: autoChoice };
+        }
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+            const answer = (await rl.question(cyan('      choose [1..] (enter = auto): '))).trim();
+            const idx = Number(answer);
+            if (Number.isInteger(idx) && idx >= 1 && idx <= request.options.length) {
+                return { requestId: request.requestId, choice: request.options[idx - 1].id };
+            }
+            return { requestId: request.requestId, choice: autoChoice };
+        }
+        finally {
+            rl.close();
+        }
+    };
+};
+/** Default non-interactive policy: accept fail parts, pick the first (top-scored) tie candidate. */
+const autoPolicy = (request) => {
+    if (request.kind === 'fail_part')
+        return 'accept';
+    return request.options[0].id;
+};
+const buildConfig = (flags) => {
+    const base = demoConfig();
+    return {
+        ...base,
+        maxRegenAttempts: flagNum(flags, 'max-regen') ?? base.maxRegenAttempts,
+        regenStallRounds: flagNum(flags, 'stall-rounds') ?? base.regenStallRounds,
+        tieEpsilon: flagNum(flags, 'tie-epsilon') ?? base.tieEpsilon,
+        multiviewGoalId: flagStr(flags, 'multiview') ?? base.multiviewGoalId,
+        abMode: flagStr(flags, 'ab-mode') === 'cross' ? 'cross' : base.abMode,
+        creditBudget: flagNum(flags, 'credit-budget') ?? base.creditBudget,
+    };
+};
+export const commandAutopilot = async (positionals, flags) => {
+    const sourceImage = positionals[1] ?? flagStr(flags, 'file') ?? flagStr(flags, 'source-url') ?? 'mock://demo-source.png';
+    const isDemo = flagBool(flags, 'demo');
+    const asJson = flagBool(flags, 'json');
+    if (!isDemo) {
+        stdout.write(yellow('autopilot: only --demo (deterministic MockBackend) is wired up in this build.\n' +
+            'The real backend (AssetHub API / trigger.dev) is a drop-in AutopilotBackend — pass --demo to run the mock end-to-end.\n'));
+        return;
+    }
+    const config = buildConfig(flags);
+    const events = [];
+    let lastPlan = [];
+    const emit = (event) => {
+        events.push(event);
+        if (asJson)
+            return; // collect only; print JSON at the end
+        if (event.type === 'plan_updated') {
+            lastPlan = event.plan;
+            return;
+        }
+        const line = formatEventLine(event);
+        if (line != null)
+            stdout.write(colorize(event, line) + '\n');
+    };
+    const engine = new AutopilotEngine(new MockBackend(), config, {
+        emit,
+        resolveHumanReview: makeResolver({
+            yolo: flagBool(flags, 'yolo'),
+            interactive: stdin.isTTY === true && !asJson,
+            quiet: asJson,
+        }),
+        runId: 'demo-run',
+    });
+    const summary = await engine.run(sourceImage);
+    if (asJson) {
+        stdout.write(`${JSON.stringify({ summary, events }, null, 2)}\n`);
+        return;
+    }
+    stdout.write('\n' + bold('Plan') + '\n' + renderPlan(lastPlan) + '\n');
+};

package/dist/canvas.d.ts

@@ -0,0 +1,27 @@
+import type { Canvas } from '@assethub/api-client';
+type CanvasScope = {
+    stateDir: string;
+    cwd: string;
+    baseUrl: string;
+    ownerId: string;
+};
+type CanvasClient = {
+    v2: {
+        createCanvas: (body: {
+            name: string;
+        }, options: {
+            idempotencyKey: string;
+        }) => Promise<Canvas>;
+        getCanvas: (id: number) => Promise<Canvas>;
+    };
+};
+export declare const writeState: (path: string, value: unknown) => Promise<void>;
+export declare const readState: (path: string) => Promise<unknown | undefined>;
+export declare const saveCanvasSelection: (scope: CanvasScope, canvasId: number) => Promise<void>;
+export declare const resolveCanvasSelection: (options: CanvasScope & {
+    client: CanvasClient;
+    canvasId?: number;
+    create?: boolean;
+}) => Promise<Canvas>;
+export {};
+//# sourceMappingURL=canvas.d.ts.map

package/dist/canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas.d.ts","sourceRoot":"","sources":["../src/canvas.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,sBAAsB,CAAA;AAEhD,KAAK,WAAW,GAAG;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACD,KAAK,YAAY,GAAG;IAClB,EAAE,EAAE;QACF,YAAY,EAAE,CACZ,IAAI,EAAE;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,EACpB,OAAO,EAAE;YAAC,cAAc,EAAE,MAAM,CAAA;SAAC,KAC9B,OAAO,CAAC,MAAM,CAAC,CAAA;QACpB,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;KAC3C,CAAA;CACF,CAAA;AAED,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,OAAO,OAAO,KACb,OAAO,CAAC,IAAI,CAWd,CAAA;AAED,eAAO,MAAM,SAAS,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAazE,CAAA;AAiBD,eAAO,MAAM,mBAAmB,GAC9B,OAAO,WAAW,EAClB,UAAU,MAAM,KACf,OAAO,CAAC,IAAI,CAOd,CAAA;AAED,eAAO,MAAM,sBAAsB,GACjC,SAAS,WAAW,GAAG;IACrB,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,KACA,OAAO,CAAC,MAAM,CA8ChB,CAAA"}

package/dist/canvas.js

@@ -0,0 +1,82 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, realpath, rename, unlink, writeFile, } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+export const writeState = async (path, value) => {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+        await rename(temporary, path);
+    }
+    finally {
+        await unlink(temporary).catch(error => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
+    }
+};
+export const readState = async (path) => {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+};
+const scopeHash = async (scope) => createHash('sha256')
+    .update(JSON.stringify([
+    scope.baseUrl.replace(/\/+$/, ''),
+    scope.ownerId,
+    await realpath(scope.cwd),
+]))
+    .digest('hex');
+/** A stable operation identity lets the server deduplicate even a crashed first invocation. */
+const creationId = (hash) => `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-8${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+export const saveCanvasSelection = async (scope, canvasId) => {
+    if (!Number.isSafeInteger(canvasId) || canvasId <= 0)
+        throw new Error('Canvas ID must be a positive integer');
+    await writeState(join(scope.stateDir, 'canvases', `${await scopeHash(scope)}.json`), { canvasId });
+};
+export const resolveCanvasSelection = async (options) => {
+    const { client } = options;
+    let canvasId = options.canvasId;
+    const hash = await scopeHash(options);
+    if (canvasId == null) {
+        const stored = await readState(join(options.stateDir, 'canvases', `${hash}.json`));
+        if (stored != null) {
+            if (typeof stored !== 'object' ||
+                !('canvasId' in stored) ||
+                !Number.isSafeInteger(stored.canvasId)) {
+                throw new Error('Invalid saved canvas selection; select one with canvas use <id>');
+            }
+            canvasId = Number(stored.canvasId);
+        }
+    }
+    if (canvasId != null) {
+        if (!Number.isSafeInteger(canvasId) || canvasId <= 0)
+            throw new Error('Canvas ID must be a positive integer');
+        const canvas = await client.v2.getCanvas(canvasId);
+        if (canvas.ownerId !== options.ownerId)
+            throw new Error('Canvas belongs to a different organization');
+        return canvas;
+    }
+    if (options.create === false)
+        throw new Error('No canvas selected; use --canvas <id> or canvas use <id>');
+    // Check local persistence before starting a remote mutation. The same scope
+    // always posts the same name and key, including after a lost response.
+    const directory = join(options.stateDir, 'canvases');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const probe = join(directory, `${hash}.${randomUUID()}.probe`);
+    await writeFile(probe, '', { mode: 0o600, flag: 'wx' });
+    await unlink(probe);
+    const canvas = await client.v2.createCanvas({ name: `CLI ${basename(await realpath(options.cwd))} ${hash.slice(0, 8)}` }, { idempotencyKey: creationId(hash) });
+    if (canvas.ownerId !== options.ownerId)
+        throw new Error('Created canvas belongs to a different organization');
+    await saveCanvasSelection(options, canvas.id);
+    return canvas;
+};