@field/cascade 0.11.0 → 0.12.0

package/dist/cli/chunk-YH637PDL.js

@@ -0,0 +1,317 @@
+// server/src/pythonWorker.ts
+import { spawn } from "child_process";
+import os from "node:os";
+import path from "node:path";
+import readline from "readline";
+var REQUEST_TIMEOUT_MS = 12e4;
+var CANCEL_GRACE_MS = 3e3;
+var StageCancelledError = class extends Error {
+  constructor(stage) {
+    super(`stage "${stage}" was cancelled`);
+    this.cancelled = true;
+    this.name = "StageCancelledError";
+  }
+};
+var liveWorkers = /* @__PURE__ */ new Set();
+function pythonWorkerStatuses() {
+  return [...liveWorkers].map((worker) => worker.status);
+}
+function shutdownAllPythonWorkers() {
+  for (const worker of [...liveWorkers]) worker.shutdown();
+}
+var PythonWorker = class {
+  constructor(project, entrypoint, python = "python3", env = process.env, options = {}) {
+    this.proc = null;
+    this.nextId = 1;
+    this.queue = [];
+    /** The request the worker is running, or one it was told to abandon and has
+     *  not yet answered. Nothing else is written until it answers or exits. */
+    this.inFlight = null;
+    /** Set once the in-flight request has been cancelled: its answer is
+     *  discarded whatever it says. */
+    this.inFlightCancelled = false;
+    this.killTimer = null;
+    /** The code hash the running process started with. */
+    this.spawnedCodeHash = null;
+    /** Set by a restart, cleared by the answer that follows it. */
+    this.restartPending = false;
+    /** How many times the worker restarted because its code changed. */
+    this.restarts = 0;
+    this.project = project;
+    this.entrypoint = entrypoint;
+    this.python = python;
+    this.env = env;
+    this.cancelGraceMs = options.cancelGraceMs ?? CANCEL_GRACE_MS;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
+    this.sources = options.sources ?? null;
+    this.onStderr = options.onStderr ?? ((text) => console.error("[python-worker]", text));
+    liveWorkers.add(this);
+  }
+  get status() {
+    const pid = this.pid;
+    return {
+      entrypoint: this.entrypoint,
+      pid,
+      state: pid === null ? "stopped" : this.inFlight ? "busy" : "idle",
+      queued: this.queue.length,
+      codeHash: this.spawnedCodeHash,
+      restarts: this.restarts
+    };
+  }
+  /** Requests sent or waiting: what a pool balances on. */
+  get pending() {
+    return (this.inFlight ? 1 : 0) + this.queue.length;
+  }
+  /** The code hash the running worker started with; null before the first
+   *  request or when sources are not watched. */
+  get codeHash() {
+    return this.spawnedCodeHash;
+  }
+  /** The worker's process id, or null when none is running. For tests and
+   *  diagnostics: a cancelled stage must not leave an orphan behind. */
+  get pid() {
+    return this.proc?.pid ?? null;
+  }
+  ensureStarted() {
+    if (this.proc && this.proc.exitCode === null && this.proc.signalCode === null) return this.proc;
+    this.spawnedCodeHash = this.sources?.codeHash() ?? null;
+    const scriptPath = this.project.resolve(this.entrypoint);
+    const proc = spawn(this.python, [scriptPath], { cwd: this.project.root, env: this.spawnEnv() });
+    readline.createInterface({ input: proc.stdout }).on("line", (line) => this.handleLine(proc, line));
+    proc.stderr.on("data", (chunk) => this.onStderr(chunk.toString().trimEnd()));
+    proc.stdin.on("error", () => {
+    });
+    proc.on("error", (error) => {
+      if (this.proc !== proc) return;
+      this.proc = null;
+      const current = this.inFlight;
+      this.inFlight = null;
+      this.inFlightCancelled = false;
+      if (current) this.settle(current, new Error(`python worker could not start (${this.python}): ${error.message}`));
+      else this.onStderr(`python worker could not start (${this.python}): ${error.message}`);
+    });
+    proc.on("exit", (code, signal) => {
+      if (this.proc !== proc) return;
+      this.proc = null;
+      this.clearKillTimer();
+      const current = this.inFlight;
+      const cancelled = this.inFlightCancelled;
+      this.inFlight = null;
+      this.inFlightCancelled = false;
+      if (current && !cancelled) {
+        console.warn(`[python-worker] exited (${signal ?? `code ${code}`}) \u2014 will respawn on next call`);
+        this.settle(current, new Error(`python worker exited (${signal ?? `code ${code}`}) before responding`));
+      }
+      this.pump();
+    });
+    this.proc = proc;
+    return proc;
+  }
+  /**
+   * The environment for a new process. With sources watched, Python's bytecode
+   * cache is moved to a folder named by the code hash.
+   *
+   * Without that a restart is not enough: Python validates a `.pyc` by the
+   * source's size and its mtime in whole seconds, so an edit that keeps the
+   * length (`VALUE = 1` to `VALUE = 2`) within the same second is served from
+   * the old bytecode by the fresh process. Found by the respawn test.
+   */
+  spawnEnv() {
+    if (!this.spawnedCodeHash) return this.env;
+    const prefix = path.join(os.tmpdir(), "cascade-pycache", this.spawnedCodeHash);
+    return { ...this.env, PYTHONPYCACHEPREFIX: prefix };
+  }
+  handleLine(proc, line) {
+    if (this.proc !== proc) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      console.error("[python-worker] non-JSON line from worker:", line);
+      return;
+    }
+    const current = this.inFlight;
+    if (!current || msg.id !== current.id) return;
+    const cancelled = this.inFlightCancelled;
+    this.inFlight = null;
+    this.inFlightCancelled = false;
+    this.clearKillTimer();
+    if (!cancelled) {
+      const restarted = this.restartPending;
+      this.restartPending = false;
+      if (msg.ok) {
+        this.settle(current, null, {
+          result: msg.result,
+          codeHash: this.spawnedCodeHash,
+          restarted,
+          ...typeof msg.cache === "string" ? { projectCache: msg.cache } : {}
+        });
+      } else this.settle(current, new Error(msg.error || "python worker reported an error"));
+    }
+    this.pump();
+  }
+  settle(request, error, answer) {
+    if (request.timer) clearTimeout(request.timer);
+    request.timer = null;
+    if (error) request.reject(error);
+    else request.resolve(answer);
+  }
+  /**
+   * Stop a running worker whose code changed since it started. Only ever
+   * called with nothing in flight, so no request is lost: the exit handler
+   * finds no current request, and the next `ensureStarted` spawns afresh.
+   */
+  restartIfCodeChanged() {
+    if (!this.sources || !this.proc) return;
+    const now = this.sources.codeHash();
+    if (now === this.spawnedCodeHash) return;
+    console.warn(`[python-worker] stage code changed (${this.spawnedCodeHash} -> ${now}), restarting`);
+    const stale = this.proc;
+    this.proc = null;
+    stale.kill();
+    this.restarts += 1;
+    this.restartPending = true;
+  }
+  clearKillTimer() {
+    if (this.killTimer) clearTimeout(this.killTimer);
+    this.killTimer = null;
+  }
+  /** Send the next queued request if the worker is free. */
+  pump() {
+    if (this.inFlight) return;
+    const next = this.queue.shift();
+    if (!next) return;
+    this.restartIfCodeChanged();
+    const proc = this.ensureStarted();
+    this.inFlight = next;
+    this.inFlightCancelled = false;
+    proc.stdin.write(next.line);
+  }
+  /**
+   * Start the process now rather than on the first call, so its interpreter
+   * start and imports (4.7 s for cloud-plots) overlap other work. A render
+   * worker warms while the probe frames run. A no-op when one is running.
+   */
+  warm() {
+    if (this.inFlight || this.queue.length) return;
+    this.restartIfCodeChanged();
+    this.ensureStarted();
+  }
+  /** Run a stage and return its result. */
+  async call(stage, args, options = {}) {
+    return (await this.callWithMeta(stage, args, options)).result;
+  }
+  /** Run a stage and return its result with the code hash that produced it. */
+  callWithMeta(stage, args, options = {}) {
+    const { signal, cascade } = options;
+    if (signal?.aborted) return Promise.reject(new StageCancelledError(stage));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const onAbort = () => this.cancel(id);
+      const request = {
+        id,
+        stage,
+        line: JSON.stringify(cascade ? { id, stage, args, cascade } : { id, stage, args }) + "\n",
+        resolve: (r) => {
+          signal?.removeEventListener("abort", onAbort);
+          resolve(r);
+        },
+        reject: (e) => {
+          signal?.removeEventListener("abort", onAbort);
+          reject(e);
+        },
+        timer: null
+      };
+      request.timer = setTimeout(() => {
+        this.cancel(id, new Error(`python worker timed out after ${this.requestTimeoutMs}ms on stage "${stage}"`));
+      }, this.requestTimeoutMs);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      this.queue.push(request);
+      this.pump();
+    });
+  }
+  /**
+   * Withdraw a request. A queued one is dropped without ever reaching Python;
+   * the one in flight is interrupted, and its answer — whenever it comes — is
+   * discarded, so a superseded result is never delivered.
+   */
+  cancel(id, reason) {
+    const queued = this.queue.findIndex((request) => request.id === id);
+    if (queued >= 0) {
+      const [request] = this.queue.splice(queued, 1);
+      this.settle(request, reason ?? new StageCancelledError(request.stage));
+      return;
+    }
+    const current = this.inFlight;
+    if (!current || current.id !== id || this.inFlightCancelled) return;
+    this.inFlightCancelled = true;
+    this.settle(current, reason ?? new StageCancelledError(current.stage));
+    const proc = this.proc;
+    if (!proc) return;
+    proc.kill("SIGINT");
+    this.clearKillTimer();
+    this.killTimer = setTimeout(() => {
+      this.killTimer = null;
+      if (this.proc === proc && this.inFlight === current) proc.kill("SIGKILL");
+    }, this.cancelGraceMs);
+  }
+  shutdown() {
+    liveWorkers.delete(this);
+    this.clearKillTimer();
+    for (const request of this.queue.splice(0)) this.settle(request, new Error("python worker shut down"));
+    const current = this.inFlight;
+    this.inFlight = null;
+    this.inFlightCancelled = false;
+    if (current) this.settle(current, new Error("python worker shut down"));
+    const proc = this.proc;
+    this.proc = null;
+    proc?.kill();
+  }
+};
+function defaultStageWorkerCount(cores = os.availableParallelism?.() ?? os.cpus().length, memoryBytes = os.totalmem()) {
+  const byCores = Math.floor(cores / 4);
+  const byMemory = Math.floor(memoryBytes / (8 * 1024 ** 3));
+  return Math.max(2, Math.min(4, byCores, byMemory));
+}
+var PythonWorkerPool = class {
+  constructor(size, create) {
+    this.size = size;
+    this.create = create;
+    this.workers = [];
+  }
+  /** The workers started so far. */
+  get members() {
+    return this.workers;
+  }
+  /** Start the first worker now (see `PythonWorker.warm`). */
+  warm() {
+    if (!this.workers.length) this.workers.push(this.create());
+    this.workers[0].warm();
+  }
+  callWithMeta(stage, args, options = {}) {
+    return this.pick().callWithMeta(stage, args, options);
+  }
+  pick() {
+    const idle = this.workers.find((worker) => worker.pending === 0);
+    if (idle) return idle;
+    if (this.workers.length < Math.max(1, this.size)) {
+      const worker = this.create();
+      this.workers.push(worker);
+      return worker;
+    }
+    return this.workers.reduce((best, worker) => worker.pending < best.pending ? worker : best);
+  }
+  shutdown() {
+    for (const worker of this.workers.splice(0)) worker.shutdown();
+  }
+};
+
+export {
+  StageCancelledError,
+  pythonWorkerStatuses,
+  shutdownAllPythonWorkers,
+  PythonWorker,
+  defaultStageWorkerCount,
+  PythonWorkerPool
+};
+//# sourceMappingURL=chunk-YH637PDL.js.map

package/dist/cli/chunk-ZSCUZE6I.js

@@ -0,0 +1,112 @@
+// src/nodes/definition/studioImages.ts
+var STUDIO_IMAGE_ROOT = ".cascade-studio/";
+var PER_NAME = 3;
+var BUDGET_BYTES = 512 * 1024 * 1024;
+var kept = /* @__PURE__ */ new Map();
+var bytes = 0;
+var sequence = 0;
+function clean(path) {
+  return path.replace(/^\.\//, "");
+}
+function drop(path) {
+  const entry = kept.get(path);
+  if (!entry) return;
+  kept.delete(path);
+  bytes -= entry.pixels.data.byteLength;
+}
+function keepStudioImage(pixels, name = "image.png") {
+  const safe = name.replace(/[^A-Za-z0-9._-]/g, "_") || "image.png";
+  const path = `${STUDIO_IMAGE_ROOT}${++sequence}-${safe}`;
+  kept.set(path, { pixels, name: safe });
+  bytes += pixels.data.byteLength;
+  const siblings = [...kept].filter(([, entry]) => entry.name === safe).map(([key]) => key);
+  for (const old of siblings.slice(0, Math.max(0, siblings.length - PER_NAME))) drop(old);
+  for (const old of kept.keys()) {
+    if (bytes <= BUDGET_BYTES || old === path) break;
+    drop(old);
+  }
+  return path;
+}
+function isStudioImage(path) {
+  return kept.has(clean(path));
+}
+function studioImagePixels(path) {
+  return kept.get(clean(path))?.pixels;
+}
+function draw(pixels) {
+  const globals = globalThis;
+  if (!globals.ImageData) throw new Error("Studio cannot draw a kept image: no ImageData here");
+  let canvas;
+  if (globals.document) {
+    canvas = globals.document.createElement("canvas");
+    canvas.width = pixels.width;
+    canvas.height = pixels.height;
+  } else if (globals.OffscreenCanvas) {
+    canvas = new globals.OffscreenCanvas(pixels.width, pixels.height);
+  } else {
+    throw new Error("Studio cannot draw a kept image: no canvas here");
+  }
+  canvas.getContext("2d").putImageData(new globals.ImageData(pixels.data, pixels.width, pixels.height), 0, 0);
+  return canvas;
+}
+async function studioImageBytes(path) {
+  const entry = kept.get(clean(path));
+  if (!entry) return void 0;
+  const canvas = draw(entry.pixels);
+  const blob = canvas.convertToBlob ? await canvas.convertToBlob({ type: "image/png" }) : await new Promise((resolve) => canvas.toBlob(resolve, "image/png"));
+  if (!blob) throw new Error(`Studio could not encode ${path}`);
+  return new Uint8Array(await blob.arrayBuffer());
+}
+function studioImageUrl(path) {
+  const entry = kept.get(clean(path));
+  if (!entry) return void 0;
+  entry.url ??= draw(entry.pixels).toDataURL("image/png");
+  return entry.url;
+}
+
+// src/nodes/definition/browserCapabilities.ts
+function assetUrl(path) {
+  const clean2 = path.replace(/^\.\//, "");
+  return `/api/media/${clean2.split("/").map(encodeURIComponent).join("/")}?raw=1`;
+}
+var browserAssetCapability = {
+  async read(ref, { signal }) {
+    const kept2 = await studioImageBytes(ref.path);
+    if (kept2) return kept2;
+    const response = await fetch(assetUrl(ref.path), { signal });
+    if (!response.ok) throw new Error(`Could not read asset ${ref.path} (${response.status})`);
+    return new Uint8Array(await response.arrayBuffer());
+  },
+  async write(data, metadata, { signal }) {
+    const name = metadata.suggestedName?.trim() || "asset.bin";
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(data)], { type: metadata.mediaType }), name);
+    const response = await fetch("/api/assets", {
+      method: "POST",
+      body: form,
+      signal
+    });
+    if (!response.ok) throw new Error(`Could not write asset ${name} (${response.status})`);
+    const result = await response.json();
+    if (!result.path) throw new Error(`Asset upload returned no path for ${name}`);
+    return { path: result.path, ...metadata.mediaType ? { mediaType: metadata.mediaType } : {} };
+  },
+  imagePixels(ref) {
+    return studioImagePixels(ref.path);
+  },
+  async resolveUrl(ref) {
+    return { value: isStudioImage(ref.path) ? studioImageUrl(ref.path) : assetUrl(ref.path), release: () => {
+    } };
+  }
+};
+var studioImageAssetCapability = {
+  ...browserAssetCapability,
+  async keepImage(pixels, metadata) {
+    return { path: keepStudioImage(pixels, metadata.suggestedName), mediaType: "image/png" };
+  }
+};
+
+export {
+  browserAssetCapability
+};
+//# sourceMappingURL=chunk-ZSCUZE6I.js.map

package/dist/cli/{cliCommands-UQSFGEHF.js → cliCommands-JJN5Z3ZC.js}

@@ -2,26 +2,28 @@ import {
   formatCompactJSON
 } from "./chunk-OWWBYLHC.js";
 import {
-  PythonWorker,
-  StageCancelledError,
-  callStage,
   compileEmbedded,
   compileProjectModule,
-  compileProjectPanel,
-  formatStageTrace,
-  pythonWorkerStatuses,
-  shutdownAllPythonWorkers,
-  stageSources
-} from "./chunk-MIIEFUGG.js";
+  compileProjectPanel
+} from "./chunk-EU4ZFZ7Y.js";
 import {
-  writeFileAtomic,
-  writeFileAtomicSync
-} from "./chunk-WPUDGEFY.js";
+  PythonWorker,
+  StageCancelledError,
+  pythonWorkerStatuses,
+  shutdownAllPythonWorkers
+} from "./chunk-YH637PDL.js";
 import {
   readStageConfig,
   runProjectStage
-} from "./chunk-VVGSLVSF.js";
+} from "./chunk-X566FWBV.js";
 import "./chunk-WD62JIP6.js";
+import {
+  callStage,
+  formatStageTrace,
+  stageSources,
+  writeFileAtomic,
+  writeFileAtomicSync
+} from "./chunk-5ORUQ6ES.js";
 import {
   CredentialStore,
   PathSafetyError,
@@ -32,10 +34,10 @@ import {
   resolveWithinRoot,
   secretValue,
   writeProjectManifest
-} from "./chunk-RQZ4SX5R.js";
-import "./chunk-A4OAMOZH.js";
+} from "./chunk-2JEU3MGB.js";
+import "./chunk-NJFMDXHR.js";
 import "./chunk-J7VK7MNF.js";
-import "./chunk-BIJO5OFS.js";
+import "./chunk-FWMSGKEH.js";
 
 // server/src/cliCommands.ts
 import fs13 from "node:fs";
@@ -2306,6 +2308,10 @@ Read \`node_modules/cascade/AGENTS.md\` for the framework itself. What follows i
 Do not start another Cascade process on an occupied port. Remote access requires
 both the explicit bind address and the exact trusted browser hostname.
 
+## Choosing a variant
+
+\`npx --no-install cascade ladder index.cascade <node> --name <name> --seeds 1,2,3\` cooks the variants side by side; \`cascade pick <ladder id> <n>\` locks the approved one. To let Marcus pick on his phone in the Cairn web chat, add \`--cairn <Substrate vault>/<space>/_attachments/ladders/<ladder id> --json\`, post \`data.cairnChoice\` (a \`cairn:choice\` fence, at most 8 pictures) in the reply as is, and when "Picked: <label> (pick:<id>:<n>)" comes back run \`cascade pick <id> <n>\` and reply with that locked image. See \`node_modules/cascade/doc/CLI_REFERENCE.md\`, "Picking a ladder variant in Cairn".
+
 ## The \`.cascade\` document format
 
 Hand-editing is supported. Preserve metadata, source fields, IDs, and valid connection endpoints, then run the static checks. This example uses the node below; save it at \`nodes/Multiply/index.ts\` before running the graph.
@@ -3461,4 +3467,4 @@ export {
   resolveProjectTarget,
   runStudioCli
 };
-//# sourceMappingURL=cliCommands-UQSFGEHF.js.map
+//# sourceMappingURL=cliCommands-JJN5Z3ZC.js.map