nanoodle 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -188,6 +188,38 @@ result.get("Image") // throws NanoodleError code "gated": the gate "Decide" an
188
188
  the CLI exits 0 with `gated` in its JSON summary. A node fed by both a closed
189
189
  gate and a real failure is still an error.
190
190
 
191
+ ### Per-node timeout, skip on failure, locked nodes
192
+
193
+ Three optional keys inside a node's `fields` (saved with the graph, no format change):
194
+
195
+ - **`timeoutMs`**: a deadline for this node alone. The node gets its own abort
196
+ signal, linked to the run's, and fails with a `NanoodleError` of code
197
+ `"timeout"` (`result.errors[i].code === "timeout"`). The run-level
198
+ `run(inputs, { timeoutMs })` still applies on top.
199
+ - **`onError: "skip"`**: if the node fails or times out, it gets
200
+ `status: "skipped"` (with `error`), the failure is still recorded in
201
+ `result.errors`, and progress emits `node-skipped` with `reason: "error"`.
202
+ Its ports come out `undefined`, so dependents just ignore it: a `join` keeps
203
+ the surviving inputs, and a decider reads only the writers that finished. A
204
+ node whose **every** input was skipped fails with "all inputs were skipped
205
+ after failing", and the run still fails if a non-skipped output fails or if
206
+ every output was skipped. A run-level abort is never skipped.
207
+ A network node that started but was skipped, timed out or aborted without
208
+ reporting a price makes `result.costExact` false. Once a node is finalized
209
+ (and once the run settles), late cost, progress or output callbacks from a
210
+ runner that ignored its abort signal are ignored, so `result.nodes` and the
211
+ cost totals don't change afterwards.
212
+ - **`locked: true`**: none of the node's fields become inputs (`wf.inputs`,
213
+ CLI `--input`, MCP tool args). An input key aimed at a locked field is
214
+ rejected, and so is any `run(…, { settings })` override that targets the
215
+ locked node (`NanoodleError` code `"locked"`). Inputs and settings can't
216
+ change a locked node's stored fields. Wires into its ports still deliver
217
+ data as usual, and editing the graph file itself still changes it.
218
+
219
+ ```js
220
+ { id: "w1", type: "llm", fields: { model: "…", system: "…", timeoutMs: 60000, onError: "skip", locked: true } }
221
+ ```
222
+
191
223
  ### Prompt length caps
192
224
 
193
225
  Many image and video models reject an over-long prompt at NanoGPT's route
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "nanoodle",
3
- "version": "0.9.0",
3
+ "version": "0.11.0",
4
4
  "description": "Run nanoodle visual AI workflows from JavaScript — zero-dependency executor for saved noodle-graph.json files",
5
5
  "type": "module",
6
6
  "main": "./src/index.mjs",
package/src/client.mjs CHANGED
@@ -159,6 +159,27 @@ export class NanoClient {
159
159
  });
160
160
  if (cr.ok) {
161
161
  const ct = ((cr.headers && cr.headers.get && cr.headers.get("content-type")) || "");
162
+ const mime = ct.split(";")[0].trim().toLowerCase();
163
+ // A binary 2xx IS the replayed result: TTS (/api/v1/audio/speech) replays raw audio bytes,
164
+ // typed audio/* or a generic application/octet-stream. It's the only paid call that answers
165
+ // binary — images, video, chat and decisions all answer JSON — so image/* and video/* are
166
+ // not accepted here. The payment is now completed and can't be reused, so dropping this
167
+ // body and re-POSTing only gets a 402.
168
+ if (mime.startsWith("audio/") || mime === "application/octet-stream") {
169
+ return { paymentId: invoice.paymentId, statusUrl: invoice.statusUrl, response: cr };
170
+ }
171
+ // Any other non-JSON 2xx (a text/plain settlement ack, a text/html error page) is neither
172
+ // the result nor a settle receipt we can act on. The complete call may already have
173
+ // consumed the payment, so re-POSTing could get a second 402 and paying again would
174
+ // double-charge: fail with the payment id instead. No second payment, no re-POST.
175
+ if (mime && !mime.includes("json")) {
176
+ const snippet = String(await cr.text().catch(() => "")).replace(/\s+/g, " ").trim().slice(0, 160);
177
+ throw new NanoodleError(
178
+ "payment " + invoice.paymentId + " was sent, but the complete call answered HTTP " + cr.status +
179
+ " with " + mime + " instead of a result" + (snippet ? " (" + snippet + ")" : "") +
180
+ " — check " + (invoice.statusUrl || "the payment status") + " before paying again",
181
+ { code: "x402", status: cr.status, paymentId: invoice.paymentId });
182
+ }
162
183
  let cj = null;
163
184
  if (ct.includes("json")) { try { cj = await cr.json(); } catch { /* treat as settle-only */ } }
164
185
  if (looksLikeResult(cj)) {
package/src/graph.mjs CHANGED
@@ -90,6 +90,12 @@ export function optionalNode(node) {
90
90
  return v === true || v === "true";
91
91
  }
92
92
 
93
+ /** Author-locked node: fields.locked keeps every field at its stored value (no inputs derived). */
94
+ export function lockedNode(node) {
95
+ const v = node && node.fields && node.fields.locked;
96
+ return v === true || v === "true";
97
+ }
98
+
93
99
  /** Is a wire landing on `port` of `node` a data input (vs a field override)? */
94
100
  export function isInputPort(node, port) {
95
101
  const t = NODE_TYPES[node.type];
package/src/io.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { NanoodleError } from "./errors.mjs";
2
- import { NODE_TYPES, displayName, optionalNode, topoSort, wiredFramesFloor, MAX_FRAMES } from "./graph.mjs";
2
+ import { NODE_TYPES, displayName, lockedNode, optionalNode, topoSort, wiredFramesFloor, MAX_FRAMES } from "./graph.mjs";
3
3
  import { endpointOutPort } from "./endpoint.mjs";
4
4
 
5
5
  /* ============================== INPUTS ============================== */
@@ -41,6 +41,9 @@ export function deriveInputs(graph) {
41
41
  };
42
42
  for (const n of graph.nodes) {
43
43
  if (n.unknown) continue;
44
+ // fields.locked: the node's fields are fixed by the graph — never surfaced as inputs,
45
+ // so runs use the stored values.
46
+ if (lockedNode(n)) continue;
44
47
  if (n.type === "inpaint") {
45
48
  if (!fed(n.id, "prompt")) entries.push(mk(n, "prompt", "What to paint in", "textarea", false));
46
49
  // image and/or mask surface whenever not wired (SPEC-io). The app's combined brush widget
package/src/nodes.mjs CHANGED
@@ -181,7 +181,9 @@ function loraKind(type) { return (type === "image" || type === "edit" || type ==
181
181
  function imageTakesLora(id) {
182
182
  id = String(id || "");
183
183
  if (/inpaint/i.test(id)) return false;
184
- if (/klein/i.test(id)) return true;
184
+ // flux-2-klein-* only (lora-capable per catalog); FLUX.3 Klein (blackforestlabs/flux-3/klein/…)
185
+ // takes no lora_url — twin of the app's imageTakesLora (nanoodle #732)
186
+ if (/flux-2-klein/i.test(id)) return true;
185
187
  if (/minimax-h3\/(text-to-image|image-edit)/i.test(id)) return true;
186
188
  return /(^|[-\/])lora($|[-\/])/i.test(id);
187
189
  }
@@ -719,7 +721,12 @@ export const RUNNERS = {
719
721
  },
720
722
 
721
723
  async lipsync(n, inp, ctx) {
722
- if (!inp.image) throw new NanoodleError("no image input");
724
+ // Portrait required only for image_to_video avatars. Preset-only talking avatars (audio→video,
725
+ // catalog image_to_video false — e.g. HeyGen Avatar V) run from the preset + audio alone, and a
726
+ // wired image is NOT forwarded. Catalog miss / no catalog keeps the portrait requirement.
727
+ // Twin of play's built-in lipsync runner (nanoodle #733).
728
+ const needsPortrait = avatarNeedsPortrait(ctx && ctx.catalog, String((n.fields && n.fields.model) || "").trim());
729
+ if (needsPortrait && !inp.image) throw new NanoodleError("no image input");
723
730
  if (!inp.audio) throw new NanoodleError("no audio input");
724
731
  const prompt = promptOf(n, inp);
725
732
  // Avatar models cap audio length (LongCat = 30s) and the cap isn't reliably in the catalog,
@@ -731,7 +738,7 @@ export const RUNNERS = {
731
738
  // ctx.trimAudio lets a browser host inject its Web Audio trimmer so the retry bytes match
732
739
  // its built-in runner exactly; default is the local-media trimmer (pure-JS WAV, ffmpeg).
733
740
  const trim = ctx.trimAudio || ((url, start, len, rate) => trimAudioToWav(url, start, len, rate, mediaOpts(ctx)));
734
- const img = await fitImage(inp.image, ctx, "portrait image");
741
+ const img = needsPortrait ? await fitImage(inp.image, ctx, "portrait image") : null;
735
742
  let trimSec = null;
736
743
  for (let attempt = 0; attempt < 2; attempt++) {
737
744
  let opts;
@@ -836,6 +843,17 @@ export const RUNNERS = {
836
843
  },
837
844
  };
838
845
 
846
+ /**
847
+ * Does this avatar/lipsync model need a portrait image? True unless the model is in the
848
+ * opt-in catalog and is preset-only (no image_to_video — audio→video talking avatars such as
849
+ * HeyGen Avatar V). Catalog miss → true (the long-standing portrait requirement).
850
+ * Mirrors play's built-in lipsync runner: raw `capabilities.image_to_video` or a normalized `i2v`.
851
+ */
852
+ function avatarNeedsPortrait(catalog, model) {
853
+ const m = catItem(catalog, "video", model);
854
+ return !m || !!((m.capabilities || {}).image_to_video) || !!m.i2v;
855
+ }
856
+
839
857
  // Image→3D (Tripo) takes a photo only. Hunyuan Rapid takes text and an optional image.
840
858
  // Anything else, including a catalog miss, accepts either — the editor's same fallback.
841
859
  const MODEL3D_IMAGE_DEFAULT = "tripo3d/v2.5";
package/src/workflow.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { NanoodleError, RunError, UnsupportedNodeError } from "./errors.mjs";
2
- import { NODE_TYPES, displayName, isInputPort, materialize, topoSort, wiredFramesFloor, MAX_FRAMES } from "./graph.mjs";
2
+ import { NODE_TYPES, displayName, isInputPort, lockedNode, materialize, topoSort, wiredFramesFloor, MAX_FRAMES } from "./graph.mjs";
3
3
  import { deriveInputs, deriveOutputs, deriveSettings, resolveInputKey, resolveSettingKey } from "./io.mjs";
4
4
  import { NanoClient } from "./client.mjs";
5
5
  import { MediaRef, coerceMediaInput } from "./media.mjs";
@@ -195,6 +195,13 @@ export class Workflow {
195
195
  const settingAssignments = [];
196
196
  for (const [key, value] of Object.entries(settings)) {
197
197
  const entry = resolveSettingKey(graph, this.settings, key);
198
+ const target = graph.nodes.find((x) => x.id === entry.nodeId);
199
+ if (lockedNode(target)) {
200
+ throw new NanoodleError(
201
+ `setting "${key}" targets locked node ${entry.nodeId} (${displayName(target)}) — ` +
202
+ `a locked node always runs with its stored fields, so settings can't override ${entry.nodeId}.${entry.field}`,
203
+ { code: "locked" });
204
+ }
198
205
  settingAssignments.push({ entry, value });
199
206
  }
200
207
 
@@ -273,15 +280,19 @@ export class Workflow {
273
280
  const promises = new Map();
274
281
  const mediaFetch = this.client.fetch;
275
282
 
276
- const ctxFor = (node, rec) => {
283
+ // Once a node is finalized (done / skipped / error) or the run has settled, late
284
+ // callbacks from a runner that ignored its abort signal must not mutate anything.
285
+ let runSettled = false;
286
+ const frozen = (rec) => runSettled || rec.final === true;
287
+ const ctxFor = (node, rec, nodeSignal = ac.signal) => {
277
288
  const onCost = (c) => {
278
- if (!c) return;
289
+ if (!c || frozen(rec)) return;
279
290
  if (c.usd != null) { rec.costUsd = (rec.costUsd || 0) + c.usd; cost.total += c.usd; }
280
291
  else cost.exact = false;
281
292
  if (c.balance != null) cost.balance = c.balance;
282
293
  };
283
- const onPoll = (info) => emit({ type: "poll", nodeId: node.id, name: displayName(node), ...info });
284
- const io = { onCost, onPoll, signal: ac.signal };
294
+ const onPoll = (info) => frozen(rec) ? undefined : emit({ type: "poll", nodeId: node.id, name: displayName(node), ...info });
295
+ const io = { onCost, onPoll, signal: nodeSignal };
285
296
  return {
286
297
  chat: (messages, model, opts) => this.client.chat(messages, model, opts, io),
287
298
  decide: (body) => this.client.decide(body, io),
@@ -292,9 +303,9 @@ export class Workflow {
292
303
  fetchMedia: (url) => this.client.fetchMediaDataUrl(url, io),
293
304
  // local media (resize/combine/…) — same fetch + signal as network I/O
294
305
  fetch: mediaFetch,
295
- signal: ac.signal,
306
+ signal: nodeSignal,
296
307
  catalog: this.catalog,
297
- progress: (msg) => emit({ type: "node-progress", nodeId: node.id, name: displayName(node), message: msg }),
308
+ progress: (msg) => frozen(rec) ? undefined : emit({ type: "node-progress", nodeId: node.id, name: displayName(node), message: msg }),
298
309
  };
299
310
  };
300
311
 
@@ -309,15 +320,19 @@ export class Workflow {
309
320
  };
310
321
  const execNode = async (n) => {
311
322
  const rec = nodesRec[n.id];
323
+ let nodeTimer = null, unlinkNode = null;
312
324
  try {
313
325
  throwIfAborted(ac.signal);
314
326
  const inbound = graph.links.filter((l) => l.to.node === n.id);
315
327
  const inp = {};
316
328
  let fields = effFields.get(n.id);
317
- let upstreamFail = null, gatedBy = null;
329
+ let upstreamFail = null, gatedBy = null, skippedIn = 0;
318
330
  for (const l of inbound) {
319
331
  let srcOut;
320
- try { srcOut = await promises.get(l.from.node); }
332
+ try {
333
+ srcOut = await promises.get(l.from.node);
334
+ if (nodesRec[l.from.node] && nodesRec[l.from.node].skippedOnError) { skippedIn++; continue; }
335
+ }
321
336
  catch {
322
337
  const g = gateOf(l.from.node);
323
338
  if (g) { if (!gatedBy) gatedBy = g; } else if (!upstreamFail) upstreamFail = displayName(byId.get(l.from.node));
@@ -337,6 +352,12 @@ export class Workflow {
337
352
  }
338
353
  // a real failure upstream wins over a gate (the browser runners agree): that is an error
339
354
  if (upstreamFail) throw new NanoodleError("upstream failed: " + upstreamFail);
355
+ // onError:"skip" upstreams leave their ports undefined (ignored above). A node whose
356
+ // EVERY wire comes from a skipped node has nothing left to work with — fail clearly.
357
+ if (inbound.length && skippedIn === inbound.length) {
358
+ throw new NanoodleError("all inputs were skipped after failing: " +
359
+ [...new Set(inbound.map((l) => displayName(byId.get(l.from.node))))].join(", "));
360
+ }
340
361
  if (gatedBy) {
341
362
  rec.status = "skipped";
342
363
  rec.gatedBy = gatedBy;
@@ -352,6 +373,7 @@ export class Workflow {
352
373
  // and report it below. The graph's own prompts are never rewritten to avoid this.
353
374
  const fit = withFittedPrompt(n, fields, { catalog: this.catalog, learned: this._promptCaps });
354
375
  fields = fit.fields;
376
+ rec.started = true;
355
377
  emit({ type: "node-start", nodeId: n.id, name: displayName(n) });
356
378
  // A fitted prompt changed what this run pays for — never silent, even headless.
357
379
  if (fit.trimmed) {
@@ -360,14 +382,37 @@ export class Workflow {
360
382
  `${fields.model} rejects prompts over ${fit.trimmed.cap}`);
361
383
  }
362
384
  const t0 = Date.now();
363
- const out = await RUNNERS[n.type]({ ...n, fields }, inp, ctxFor(n, rec));
385
+ // Per-node timeout (fields.timeoutMs): a child controller linked to the run signal.
386
+ // The race guarantees the deadline even if a runner never observes its signal.
387
+ const timeoutMs = Number(fields.timeoutMs);
388
+ let nodeSignal = ac.signal, deadline = null;
389
+ if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
390
+ const nac = new AbortController();
391
+ const onRunAbort = () => nac.abort(ac.signal.reason);
392
+ ac.signal.addEventListener("abort", onRunAbort, { once: true });
393
+ unlinkNode = () => ac.signal.removeEventListener("abort", onRunAbort);
394
+ nodeSignal = nac.signal;
395
+ deadline = new Promise((_, reject) => {
396
+ nodeTimer = setTimeout(() => {
397
+ const err = new NanoodleError(`node timed out after ${timeoutMs}ms`, { code: "timeout" });
398
+ nac.abort(err);
399
+ reject(err);
400
+ }, timeoutMs);
401
+ });
402
+ deadline.catch(() => {});
403
+ }
404
+ const work = RUNNERS[n.type]({ ...n, fields }, inp, ctxFor(n, rec, nodeSignal));
405
+ const out = deadline ? await Promise.race([work, deadline]) : await work;
406
+ if (deadline) throwIfAborted(nodeSignal);
364
407
  throwIfAborted(ac.signal);
408
+ rec.final = true;
365
409
  rec.status = "done";
366
410
  rec.out = out;
367
411
  rec.ms = Date.now() - t0;
368
412
  emit({ type: "node-done", nodeId: n.id, name: displayName(n), ms: rec.ms, costUsd: rec.costUsd });
369
413
  return out;
370
414
  } catch (e) {
415
+ rec.final = true;
371
416
  if (e instanceof GateSkip) throw e;
372
417
  // ⚖️ Decide gate answered no: a settled, billed decision — not an error. Downstream skips.
373
418
  if (e && e.gate === true && !ac.signal.aborted) {
@@ -384,11 +429,24 @@ export class Workflow {
384
429
  if (learnPromptCap(this._promptCaps, n, e.message)) {
385
430
  e.message = e.message + " — noted: nanoodle keeps this model's prompt inside that limit from now on, so running again should succeed";
386
431
  }
387
- rec.status = "error";
388
432
  rec.error = e.message;
389
- errors.push({ nodeId: n.id, name: displayName(n), message: e.message });
433
+ errors.push({ nodeId: n.id, name: displayName(n), message: e.message, ...(e && e.code ? { code: e.code } : {}) });
434
+ // fields.onError:"skip" — a failed (or timed-out) node is recorded and skipped; its
435
+ // dependents see undefined ports. A run-level abort/timeout is never skipped.
436
+ const onError = (effFields.get(n.id) || {}).onError;
437
+ if (onError === "skip" && !ac.signal.aborted) {
438
+ rec.status = "skipped";
439
+ rec.skippedOnError = true;
440
+ rec.out = {};
441
+ emit({ type: "node-skipped", nodeId: n.id, name: displayName(n), reason: "error", error: e.message });
442
+ return {};
443
+ }
444
+ rec.status = "error";
390
445
  emit({ type: "node-error", nodeId: n.id, name: displayName(n), error: e.message });
391
446
  throw e;
447
+ } finally {
448
+ if (nodeTimer) clearTimeout(nodeTimer);
449
+ if (unlinkNode) unlinkNode();
392
450
  }
393
451
  };
394
452
 
@@ -400,10 +458,19 @@ export class Workflow {
400
458
  }
401
459
  await Promise.allSettled([...promises.values()]);
402
460
  } finally {
461
+ runSettled = true;
403
462
  if (timer) clearTimeout(timer);
404
463
  if (signal) signal.removeEventListener("abort", onOuterAbort);
405
464
  }
406
465
 
466
+ // A network node that started but was skipped, timed out or aborted without ever reporting
467
+ // a price may still have been billed: the total can't be exact.
468
+ for (const n of order) {
469
+ const rec = nodesRec[n.id];
470
+ const t = NODE_TYPES[n.type];
471
+ if (!rec || !rec.started || rec.status === "done" || rec.costUsd != null || (t && t.local)) continue;
472
+ cost.exact = false;
473
+ }
407
474
  // ---- result ----
408
475
  const outputsMap = {};
409
476
  for (const o of this.outputs) {
@@ -460,6 +527,12 @@ export class Workflow {
460
527
  }
461
528
  throw new RunError("run failed — " + detail, result);
462
529
  }
530
+ // onError:"skip" never makes a run succeed with nothing: if every output skipped, fail.
531
+ const skippedSinks = this.outputs.filter((o) => nodesRec[o.nodeId] && nodesRec[o.nodeId].skippedOnError);
532
+ if (this.outputs.length && skippedSinks.length === this.outputs.length) {
533
+ throw new RunError("run failed — every output was skipped after failing: " +
534
+ skippedSinks.map((o) => `"${o.key}": ${nodesRec[o.nodeId].error}`).join("; "), result);
535
+ }
463
536
  return result;
464
537
  }
465
538