@koda-sl/baker-cli 0.123.0 → 0.124.0-dev.2ddde71d7

package/dist/engine/index.d.ts

@@ -15,12 +15,33 @@ type ExecRequest = {
     /** Run-scoped dedupe key: the backend replays the stored response for a
      * repeated key instead of re-dispatching to the provider (and re-charging). */
     idempotency_key?: string;
+    /** Run + node identity, so a completed async job can be mapped back to its
+     * frozen run's node by the backend stale-run reconciliation sweep. */
+    canvas_run_id?: string;
+    node_id?: string;
 };
 type ExecResponse = {
     outputs: Record<string, RawAssetOutput | RawAssetOutput[] | unknown>;
     credits_charged?: number;
     duration_ms?: number;
 };
+/** A resumable run as reported by `GET /api/canvas/runs/active`. */
+type ActiveRunInfo = {
+    runId: string;
+    status: "running" | "completed" | "failed";
+    interrupted?: boolean;
+    updatedAt?: number;
+    canvasSha?: string;
+    canvasSnapshotUrl?: string;
+};
+/** The newest snapshot-bearing run for a creative — `GET /api/canvas/runs/latest`. */
+type SnapshotRunInfo = {
+    runId: string;
+    status: "running" | "completed" | "failed";
+    interrupted?: boolean;
+    canvasSha?: string;
+    canvasSnapshotUrl: string;
+};
 type ArtifactResponse = {
     artifact: {
         kind: string;
@@ -43,10 +64,37 @@ declare class BackendClient$1 {
     });
     exec(req: ExecRequest, signal?: AbortSignal): Promise<ExecResponse>;
     private pollJob;
-    presignAssetUpload(sha256: string, mime: string, signal?: AbortSignal): Promise<{
+    presignAssetUpload(sha256: string, mime: string, signal?: AbortSignal, purpose?: "output" | "source" | "blueprint"): Promise<{
         putUrl: string;
         publicUrl: string;
     }>;
+    /** Remote cache lookup. A miss (404) — or an old backend without the route — returns null. */
+    getCacheEntry<T>(cacheKey: string, signal?: AbortSignal): Promise<T | null>;
+    putCacheEntry(entry: {
+        cacheKey: string;
+    }, signal?: AbortSignal): Promise<void>;
+    /** Durable run-history record — POST /api/canvas/runs (idempotent server-side on runId). */
+    recordRun(payload: unknown, signal?: AbortSignal): Promise<void>;
+    /**
+     * Resumable-run lookup — GET /api/canvas/runs/active. Returns the newest
+     * still-running/interrupted run for the creative (pinned to the exact canvas
+     * sha), so a fresh sandbox can adopt its run id and re-attach billed
+     * in-flight jobs. Null on no active run — or an older backend without the
+     * route (both 404).
+     */
+    getActiveRun(creativeSlug: string, canvasSha?: string, signal?: AbortSignal): Promise<ActiveRunInfo | null>;
+    /**
+     * Portable-rerun lookup — GET /api/canvas/runs/latest. The newest run for
+     * the creative that recorded a canvas snapshot manifest; null when none
+     * exists (or the backend predates the route — both 404).
+     */
+    getLatestSnapshotRun(creativeSlug: string, signal?: AbortSignal): Promise<SnapshotRunInfo | null>;
+    /**
+     * Chat-scoped blueprint sync — POST /api/creatives/definition. Lets the
+     * dashboard draw a scaffolded creative's workflow graph BEFORE the first run.
+     * Additive on the backend (never archives siblings, never sets definitionPath).
+     */
+    syncCreativeDefinition(payload: unknown, signal?: AbortSignal): Promise<void>;
     getArtifact(kind: string, name: string, version?: string, signal?: AbortSignal): Promise<ArtifactResponse>;
 }
 
@@ -120,6 +168,7 @@ declare const CanvasSchema: z.ZodObject<{
         inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         when: z.ZodOptional<z.ZodUnknown>;
+        regenerate: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
     }, z.core.$strict>>;
     output: z.ZodOptional<z.ZodObject<{
         node: z.ZodString;
@@ -249,6 +298,14 @@ type ExecCtx = {
     /** Content-addressed cache key for this node execution. Remote delegation
      * derives its idempotency key from it so backend retries never double-charge. */
     cacheKey?: string;
+    /**
+     * Whether this node's outputs must be downloaded to the local content store.
+     * False when NO downstream consumer is a local (ffmpeg/magick) node — the
+     * backend already persisted the bytes to R2 with a durable sha256 URL, so the
+     * redundant R2→sandbox transfer is skipped and the ref is kept URL-only.
+     * Absent/true means download (the safe default for older call sites).
+     */
+    downloadOutputs?: boolean;
     client: BackendClient$1;
     assets: AssetStore;
     log: LogFn;
@@ -311,6 +368,12 @@ type NodeDefinition<I = unknown, P = unknown, O = unknown> = {
     outputs: z.ZodType<O>;
     /** "local" runs in-process; "remote" delegates to Convex via ctx.client */
     location: "local" | "remote";
+    /**
+     * Local node that only forwards asset refs and never reads their bytes
+     * (e.g. `collect`). Exempts its upstream producers from the forced R2→disk
+     * download local consumers otherwise trigger.
+     */
+    passthroughRefs?: true;
     cost?: CostFn<P>;
     validateExtra?: ValidateExtraFn;
     cacheKeyExtras?: CacheKeyExtrasFn;
@@ -339,6 +402,39 @@ type RunResult = {
         duration_ms: number;
     };
     outputs_dir: string;
+    node_runs: NodeRunRecord[];
+};
+type NodeRunRecord = {
+    node_id: string;
+    node_type: string;
+    cached: boolean;
+    duration_ms: number;
+    credits: number;
+};
+/**
+ * Live run telemetry: the plan (post-prune node list + dependency edges) fires
+ * once before any node executes, then start/settled/failed per node. Consumers
+ * stream these into run-history progress snapshots; a throwing consumer is
+ * swallowed — telemetry must never fail a paid run.
+ */
+type RunProgressEvent = {
+    kind: "plan";
+    nodes: Array<{
+        node_id: string;
+        node_type: string;
+        deps: string[];
+        params: unknown;
+    }>;
+} | {
+    kind: "node_start";
+    node_id: string;
+} | {
+    kind: "node_settled";
+    run: NodeRunRecord;
+    outputs: Record<string, unknown>;
+} | {
+    kind: "node_failed";
+    node_id: string;
 };
 type RunOptions = {
     signal?: AbortSignal;
@@ -346,6 +442,22 @@ type RunOptions = {
     cache_policy?: "read_write" | "bypass" | "read_only";
     /** Max nodes of one layer in flight at once; invalid or missing → 5. */
     concurrency?: number;
+    /**
+     * Credit ceiling (`--max-credits`). Enforced pre-flight against the deep
+     * validator's estimate (nothing billed) and at layer boundaries against
+     * actual spend — a boundary is the only point with no async job in flight,
+     * so aborting there strands nothing. Cached nodes cost 0, so a capped run
+     * retried with a higher cap loses no completed work.
+     */
+    max_credits?: number;
+    /**
+     * Node ids to force fresh for THIS run only (the `--regenerate` flag). Folds
+     * the run id into each named node's cache key so it re-renders regardless of
+     * the content cache, without editing the canvas. Persistent regeneration uses
+     * the per-node `regenerate` field instead.
+     */
+    regenerate?: ReadonlySet<string>;
+    onProgress?: (event: RunProgressEvent) => void;
 };
 type EngineOptions = {
     registry: NodeRegistry;
@@ -354,6 +466,13 @@ type EngineOptions = {
     cache: CacheStore;
     outputsDir: string;
     log?: LogFn;
+    /**
+     * Stamp durable canvas-assets URLs onto fresh node outputs before they are
+     * cached — the precondition for remote cache portability and run-history
+     * records. Best-effort: a failed upload logs a warning and keeps the entry
+     * local-only, never fails the node.
+     */
+    persistAssets?: boolean;
 };
 declare class Engine$1 {
     private readonly registry;
@@ -362,6 +481,7 @@ declare class Engine$1 {
     private readonly cache;
     private readonly outputsDir;
     private readonly log;
+    private readonly persistAssets;
     constructor(opts: EngineOptions);
     validate(canvas: unknown): {
         ok: true;
@@ -390,6 +510,8 @@ declare class Engine$1 {
     }>;
     run(input: unknown, opts?: RunOptions): Promise<RunResult>;
     private runLayers;
+    /** Progress consumers are observers only — an exception there must never fail the run. */
+    private emitProgress;
     /**
      * Dead-node elimination: when the canvas declares an `output`, execute only the
      * nodes that output transitively depends on. Orphaned nodes (left by an edit or
@@ -400,6 +522,13 @@ declare class Engine$1 {
     private writeFinal;
     private executeOne;
     private materializeNodeOutputs;
+    /**
+     * Download any URL-only asset ref reachable in a local node's inputs so the
+     * bytes are on disk before the local runner stages them. Returns a copy —
+     * refs are replaced, never mutated in place, so the producer's cached output
+     * (shared object) keeps its URL-only shape.
+     */
+    private materializeLocalInputs;
 }
 
 type ValidationResult = {
@@ -467,6 +596,13 @@ declare function createEngineFromEnv(opts?: {
     cacheDir?: string;
     outputsDir?: string;
     log?: (line: string) => void;
+    /**
+     * Layer the company-scoped remote cache over the local one (and stamp
+     * durable asset URLs onto fresh outputs) so a fresh sandbox re-runs an
+     * already-computed canvas at zero credits. Defaults to on; disable with
+     * `remoteCache: false` or env BAKER_CANVAS_REMOTE_CACHE=off.
+     */
+    remoteCache?: boolean;
 }): Engine$1;
 
 export { BackendClient, Engine, LocalAssetStore, LocalCacheStore, ValidationError, createEngineFromEnv, defaultRegistry, generateCatalog, validateCanvasDeep };

package/dist/engine/index.js

@@ -1,5 +1,5 @@
 import {
-  BackendClient,
+  BackendClient2 as BackendClient,
   Engine,
   LocalAssetStore,
   LocalCacheStore,
@@ -8,7 +8,7 @@ import {
   defaultRegistry,
   generateCatalog,
   validateCanvasDeep
-} from "../chunk-IWPAXJC3.js";
+} from "../chunk-TKL2CJ6G.js";
 import "../chunk-5WRI5ZAA.js";
 export {
   BackendClient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koda-sl/baker-cli",
-  "version": "0.123.0",
+  "version": "0.124.0-dev.2ddde71d7",
   "description": "AI-agent-first CLI for interacting with Baker, including the Baker creative canvas.",
   "type": "module",
   "bin": {