nanoodle 0.8.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/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";
@@ -39,14 +39,30 @@ function throwIfAborted(signal) {
39
39
  }
40
40
 
41
41
  /** The outcome of Workflow.run(). Media values are MediaRef; text values plain strings. */
42
+ /** Internal: thrown by a node skipped behind a closed gate, so ITS dependents skip too. Never surfaced. */
43
+ class GateSkip extends Error {
44
+ constructor(gatedBy) { super("skipped — a gate upstream said no"); this.gatedBy = gatedBy; }
45
+ }
46
+
42
47
  export class RunResult {
43
- constructor({ outputs, nodes, errors, costUsd, costExact, remainingBalance }) {
44
- /** { [friendlyKey | nodeId]: value } — sink node primary outputs */
48
+ constructor({ outputs, nodes, errors, gated = [], costUsd, costExact, remainingBalance }) {
49
+ /** { [friendlyKey | nodeId]: value } — sink node primary outputs (a sink skipped by a closed gate has none) */
45
50
  this.outputs = outputs;
46
- /** per-node { status: "done"|"error"|"skipped", out, error, costUsd, ms } */
51
+ /**
52
+ * per-node { status: "done"|"error"|"gated"|"skipped", out, error, costUsd, ms }.
53
+ * "gated": a ⚖️ Decide yes/no gate that answered no — it ran and billed, `out` holds its answer
54
+ * ({ text: "no", decision }), and it carries `gate: { yes, message }`. Not an error.
55
+ * "skipped" + `gatedBy: <decide node id>`: downstream of a closed gate — never ran, never billed.
56
+ * (Annotation notes are "skipped" with no gatedBy.)
57
+ */
47
58
  this.nodes = nodes;
48
- /** [{ nodeId, name, message }] for every node that failed (incl. non-sink warnings) */
59
+ /** [{ nodeId, name, message }] for every node that failed (incl. non-sink warnings) — never gates */
49
60
  this.errors = errors;
61
+ /**
62
+ * [{ nodeId, name, message, yes, skipped: [nodeId…] }] — every Decide gate that closed this run.
63
+ * A closed gate is a deliberate, successful outcome: run() resolves, it never throws for one.
64
+ */
65
+ this.gated = gated;
50
66
  /** summed USD cost of all calls that reported one */
51
67
  this.costUsd = costUsd;
52
68
  /** false when any network call omitted its price (total is a floor) */
@@ -63,6 +79,8 @@ export class RunResult {
63
79
  for (const k of Object.keys(this.outputs)) {
64
80
  if (k.toLowerCase() === norm) return this.outputs[k];
65
81
  }
82
+ const g = (this._gatedOutputs || []).find((o) => o.key.toLowerCase() === norm || o.nodeId.toLowerCase() === norm);
83
+ if (g) throw new NanoodleError(`output "${g.key}" was skipped — the gate "${g.gateName}" answered no, so it never ran (see result.gated)`, { code: "gated" });
66
84
  throw new NanoodleError(`no output "${key}" — available outputs: ${Object.keys(this.outputs).map((k) => `"${k}"`).join(", ") || "(none)"}`);
67
85
  }
68
86
  }
@@ -177,6 +195,13 @@ export class Workflow {
177
195
  const settingAssignments = [];
178
196
  for (const [key, value] of Object.entries(settings)) {
179
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
+ }
180
205
  settingAssignments.push({ entry, value });
181
206
  }
182
207
 
@@ -255,17 +280,22 @@ export class Workflow {
255
280
  const promises = new Map();
256
281
  const mediaFetch = this.client.fetch;
257
282
 
258
- 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) => {
259
288
  const onCost = (c) => {
260
- if (!c) return;
289
+ if (!c || frozen(rec)) return;
261
290
  if (c.usd != null) { rec.costUsd = (rec.costUsd || 0) + c.usd; cost.total += c.usd; }
262
291
  else cost.exact = false;
263
292
  if (c.balance != null) cost.balance = c.balance;
264
293
  };
265
- const onPoll = (info) => emit({ type: "poll", nodeId: node.id, name: displayName(node), ...info });
266
- 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 };
267
296
  return {
268
297
  chat: (messages, model, opts) => this.client.chat(messages, model, opts, io),
298
+ decide: (body) => this.client.decide(body, io),
269
299
  image: (args) => this.client.image(args, io),
270
300
  video: (model, prompt, opts, imageDataUrl) => this.client.video(model, prompt, opts, imageDataUrl, io),
271
301
  audio: (model, input, extra) => this.client.audio(model, input, extra, io),
@@ -273,31 +303,69 @@ export class Workflow {
273
303
  fetchMedia: (url) => this.client.fetchMediaDataUrl(url, io),
274
304
  // local media (resize/combine/…) — same fetch + signal as network I/O
275
305
  fetch: mediaFetch,
276
- signal: ac.signal,
306
+ signal: nodeSignal,
277
307
  catalog: this.catalog,
278
- 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 }),
279
309
  };
280
310
  };
281
311
 
312
+ const gated = [];
313
+ // a node whose upstream settled as a closed gate (or was itself skipped by one) → that gate's id
314
+ const gateOf = (id) => {
315
+ const r = nodesRec[id];
316
+ if (!r) return null;
317
+ if (r.status === "gated") return id;
318
+ if (r.status === "skipped" && r.gatedBy) return r.gatedBy;
319
+ return null;
320
+ };
282
321
  const execNode = async (n) => {
283
322
  const rec = nodesRec[n.id];
323
+ let nodeTimer = null, unlinkNode = null;
284
324
  try {
285
325
  throwIfAborted(ac.signal);
286
326
  const inbound = graph.links.filter((l) => l.to.node === n.id);
287
327
  const inp = {};
288
328
  let fields = effFields.get(n.id);
289
- let upstreamFail = null;
329
+ let upstreamFail = null, gatedBy = null, skippedIn = 0;
290
330
  for (const l of inbound) {
291
331
  let srcOut;
292
- try { srcOut = await promises.get(l.from.node); }
293
- catch { if (!upstreamFail) upstreamFail = displayName(byId.get(l.from.node)); continue; }
332
+ try {
333
+ srcOut = await promises.get(l.from.node);
334
+ if (nodesRec[l.from.node] && nodesRec[l.from.node].skippedOnError) { skippedIn++; continue; }
335
+ }
336
+ catch {
337
+ const g = gateOf(l.from.node);
338
+ if (g) { if (!gatedBy) gatedBy = g; } else if (!upstreamFail) upstreamFail = displayName(byId.get(l.from.node));
339
+ continue;
340
+ }
294
341
  const v = srcOut[l.from.port];
295
342
  if (isInputPort(n, l.to.port)) inp[l.to.port] = v;
343
+ // Custom endpoint url/mode: a Choice path like "/post" must ride inp so
344
+ // endpointResolveTarget can join it onto the typed host. Overwriting
345
+ // fields.url with "/post" rejects the joined URL.
346
+ else if (n.type === "endpoint" && (l.to.port === "url" || l.to.port === "mode")) {
347
+ if (v != null) inp[l.to.port] = v;
348
+ }
296
349
  // wired textarea port = field override; a missing upstream port (degraded save) must
297
350
  // NOT clobber the typed field with undefined — the app only applies v != null
298
351
  else if (v != null) fields = { ...fields, [l.to.port]: v };
299
352
  }
353
+ // a real failure upstream wins over a gate (the browser runners agree): that is an error
300
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
+ }
361
+ if (gatedBy) {
362
+ rec.status = "skipped";
363
+ rec.gatedBy = gatedBy;
364
+ const gr = gated.find((x) => x.nodeId === gatedBy);
365
+ if (gr) gr.skipped.push(n.id);
366
+ emit({ type: "node-skipped", nodeId: n.id, name: displayName(n), reason: "gated", gatedBy });
367
+ throw new GateSkip(gatedBy);
368
+ }
301
369
  throwIfAborted(ac.signal);
302
370
  // Prompt length caps (see prompt-caps.mjs). Many image/video models reject an over-long
303
371
  // prompt at the route, and in a graph the prompt is WRITTEN by an upstream LLM — so a
@@ -305,6 +373,7 @@ export class Workflow {
305
373
  // and report it below. The graph's own prompts are never rewritten to avoid this.
306
374
  const fit = withFittedPrompt(n, fields, { catalog: this.catalog, learned: this._promptCaps });
307
375
  fields = fit.fields;
376
+ rec.started = true;
308
377
  emit({ type: "node-start", nodeId: n.id, name: displayName(n) });
309
378
  // A fitted prompt changed what this run pays for — never silent, even headless.
310
379
  if (fit.trimmed) {
@@ -313,25 +382,71 @@ export class Workflow {
313
382
  `${fields.model} rejects prompts over ${fit.trimmed.cap}`);
314
383
  }
315
384
  const t0 = Date.now();
316
- 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);
317
407
  throwIfAborted(ac.signal);
408
+ rec.final = true;
318
409
  rec.status = "done";
319
410
  rec.out = out;
320
411
  rec.ms = Date.now() - t0;
321
412
  emit({ type: "node-done", nodeId: n.id, name: displayName(n), ms: rec.ms, costUsd: rec.costUsd });
322
413
  return out;
323
414
  } catch (e) {
415
+ rec.final = true;
416
+ if (e instanceof GateSkip) throw e;
417
+ // ⚖️ Decide gate answered no: a settled, billed decision — not an error. Downstream skips.
418
+ if (e && e.gate === true && !ac.signal.aborted) {
419
+ rec.status = "gated";
420
+ rec.out = e.out || null;
421
+ rec.gate = { yes: e.decision && typeof e.decision.yes === "number" ? e.decision.yes : null, message: e.message };
422
+ gated.push({ nodeId: n.id, name: displayName(n), message: e.message, yes: rec.gate.yes, skipped: [] });
423
+ emit({ type: "node-gated", nodeId: n.id, name: displayName(n), message: e.message, yes: rec.gate.yes, costUsd: rec.costUsd });
424
+ throw e;
425
+ }
324
426
  // A prompt-length rejection is free (nothing generated) and, once banked, preventable: the
325
427
  // next run budgets the LLM above this node and fits whatever is left. Say that, rather than
326
428
  // relaying "please shorten it" about a prompt the caller never wrote.
327
429
  if (learnPromptCap(this._promptCaps, n, e.message)) {
328
430
  e.message = e.message + " — noted: nanoodle keeps this model's prompt inside that limit from now on, so running again should succeed";
329
431
  }
330
- rec.status = "error";
331
432
  rec.error = e.message;
332
- 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";
333
445
  emit({ type: "node-error", nodeId: n.id, name: displayName(n), error: e.message });
334
446
  throw e;
447
+ } finally {
448
+ if (nodeTimer) clearTimeout(nodeTimer);
449
+ if (unlinkNode) unlinkNode();
335
450
  }
336
451
  };
337
452
 
@@ -343,15 +458,24 @@ export class Workflow {
343
458
  }
344
459
  await Promise.allSettled([...promises.values()]);
345
460
  } finally {
461
+ runSettled = true;
346
462
  if (timer) clearTimeout(timer);
347
463
  if (signal) signal.removeEventListener("abort", onOuterAbort);
348
464
  }
349
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
+ }
350
474
  // ---- result ----
351
475
  const outputsMap = {};
352
476
  for (const o of this.outputs) {
353
477
  const rec = nodesRec[o.nodeId];
354
- if (!rec || rec.status !== "done") continue;
478
+ if (!rec || !(rec.status === "done" || (rec.status === "gated" && rec.out))) continue;
355
479
  const primary = o.ports[0];
356
480
  const value = this._wrapValue(rec.out[primary.name], primary.type);
357
481
  outputsMap[o.key] = value;
@@ -361,10 +485,17 @@ export class Workflow {
361
485
  outputs: outputsMap,
362
486
  nodes: nodesRec,
363
487
  errors,
488
+ gated,
364
489
  costUsd: cost.total,
365
490
  costExact: cost.exact,
366
491
  remainingBalance: cost.balance,
367
492
  });
493
+ // sinks a closed gate skipped: get() names the gate instead of "no output"
494
+ Object.defineProperty(result, "_gatedOutputs", {
495
+ enumerable: false,
496
+ value: this.outputs.filter((o) => nodesRec[o.nodeId] && nodesRec[o.nodeId].gatedBy)
497
+ .map((o) => ({ key: o.key, nodeId: o.nodeId, gateName: displayName(byId.get(nodesRec[o.nodeId].gatedBy)) })),
498
+ });
368
499
 
369
500
  // timeout/abort must fail the run even when local media finished after the deadline
370
501
  // (or nodes never observed the signal). Prefer the abort reason when present.
@@ -396,6 +527,12 @@ export class Workflow {
396
527
  }
397
528
  throw new RunError("run failed — " + detail, result);
398
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
+ }
399
536
  return result;
400
537
  }
401
538