nexus-ai-pro 1.9.0 → 1.11.0

package/API_STABILITY.md

@@ -106,6 +106,41 @@ exactly-once provider execution. Those capabilities will use additive adapters a
 `MemoryAssetStore` is likewise process-local and does not promise cross-process durability or shared
 tenant state.
 
+### Image portability (1.10.0)
+
+The following are public under the same 1.x rules. None is exported from the root or from
+`nexus-ai-pro/images`:
+
+- `nexus-ai-pro/images/google`
+- `nexus-ai-pro/images/comfyui`
+- `nexus-ai-pro/images/transform`, which re-exports the PNG codec and header helpers
+- `nexus-ai-pro/images/inputs`
+- `nexus-ai-pro/images/moderation`
+- `nexus-ai-pro/images/evals`
+
+The following changes are additive:
+
+- `ImageConfig.inputResolver` and `ImageConfig.tenantId` are optional. With no resolver, requests are
+  handled exactly as before.
+- `ImageAssetResolver` and `ImageAssetResolverContext` are new types.
+- Output from the new modules is still generative. Backend wire shapes such as Imagen `:predict` and
+  the ComfyUI queue API are upstream contracts outside this policy, like `raw`.
+
+Behaviour that changed:
+
+- **OpenAI masks and transparency.** `OpenAIImageProvider` now declares `supportsMask: true` and
+  `supportsTransparency: true`, and accepts masked edits. A mask whose size differs from the input is
+  still refused unless `resizeMode` allows resampling. `background: 'transparent'` is refused only with
+  JPEG output.
+- **Withheld outputs.** A provider finding with `source: 'output'`, `action: 'block'`, and
+  `metadata.withheld: true` describes an image the provider removed before responding. The manager
+  accepts one fewer asset per such finding, and does not let that finding block the images that were
+  returned. Any other blocking finding still blocks the whole result.
+- **Masked-edit conformance case.** `runImageProviderConformance` adds a `masked-image-edit` case for
+  providers that declare `supportsMask`. Pass `testMask: false` to skip it.
+- **`UrlPolicyError`.** Safe-fetch policy refusals are now this subclass of `Error`. Their messages are
+  unchanged.
+
 ## Embeddings API stage
 
 The `nexus-ai-pro/embeddings` family is public and follows the 1.x rules, including the explicit
@@ -242,10 +277,41 @@ to Redis is not a checkpoint.
 and threading the schema through it would force an annotation on every construction for no benefit.
 The graph casts at that boundary and hands typed state back through `state()` and `history()`.
 
-Scheduling within a superstep is not a guarantee. Nodes in a fan-out currently run in edge order and
-sequentially; running them concurrently is a valid future change, so a node must not depend on
-observing another node's write within the same superstep — that is what channels are for. The default
-`maxSteps` may change; pass it explicitly when a run depends on the bound.
+`compile()` without a checkpointer uses an in-process `MemoryGraphCheckpointer` capped at 1,000
+threads (since 1.10.0; earlier releases created none). `checkpointer: false` disables checkpointing. A
+run started without a `threadId` reports its generated id on the result.
+
+Also since 1.10.0:
+
+- A paused or failed superstep records its already finished nodes in the optional `completed` field.
+  Those nodes are not run again, and their edges still count when the step completes.
+- Writing checkpoint N drops any stored checkpoints at or after N, so a rewound thread has one
+  timeline. Keeping several branches is planned work (forks), not current behaviour.
+- A subgraph interrupt surfaces as an interrupt of the parent node.
+- `onProgress` receives `context.report()` calls.
+
+Scheduling within a superstep is not a guarantee, and 1.11.0 makes use of that: tasks in a
+superstep now run concurrently, bounded by `maxConcurrency` (default 16, settable per compile and per
+run; `1` is strictly sequential). A node still must not depend on observing another node's write
+within the same superstep — that is what channels are for. What is guaranteed is that writes are
+reduced in task order rather than completion order, so a replay of the same decisions produces the
+same state. The default `maxSteps` and `maxConcurrency` may change; pass them explicitly when a run
+depends on the bound.
+
+Also since 1.11.0, all additive:
+
+- `Send` creates one task per value, with the task's input on `context.input`. Task ids are derived
+  from the step and the order produced, and appear in the checkpoint's optional `tasks` field, which
+  is written only when it says more than `next` does.
+- `NodeOptions` on `addNode` carries `retry`, `timeoutMs`, and `ends`; `compile({ retry })` sets the
+  default policy. Retrying is off unless asked for. A timeout raises `GraphNodeTimeoutError`.
+- `onNodeError` chooses `fail-fast` (default) or `settle` for the siblings of a failed task.
+- A paused checkpoint and result carry `interrupts`, every question the step asked;
+  `interrupt` remains the first of them. `resumeInterrupts()` and `resumeInterruptsWith()` answer any
+  subset by interrupt id. Interrupt ids are keyed by task, so ids written by earlier releases for
+  ordinary nodes still resolve.
+- `context.taskId` and `context.attempt` are new. Step events carry `tasks` and `attempts` when there
+  is something to report.
 
 ## Deprecation process
 

package/CHANGELOG.md

@@ -4,7 +4,164 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
-## [Unreleased]
+## [1.11.0] - 2026-09-18
+
+Parallel graphs. A fan-out that looks parallel now runs in parallel, a graph can fan out over data it
+discovers at run time, and a node can retry or time out on its own.
+
+### Added
+
+- **Concurrent supersteps.** Every task in a superstep starts together: four branches of 300 ms
+  finish in about 310 ms, where they used to take 1,253 ms. `npm run bench:graph` measures it and
+  fails if the gain disappears.
+  - `maxConcurrency` bounds how many run at once. It defaults to 16, is settable per compile and per
+    run, and `1` restores strictly sequential execution.
+  - Writes are reduced in task order, never completion order, so timing cannot change the state a
+    replay produces.
+  - A superstep with a single task skips the scheduler, so a linear graph pays nothing for this.
+- **`Send`, for fan-out over run-time data.** A router can return `new Send(node, input)` values,
+  creating one task per value, each reading its own `context.input`. Fifty-seven URLs become
+  fifty-seven tasks of one node in one superstep.
+  - Each copy is checkpointed separately, so a resume re-runs only the copies that did not finish.
+  - Task ids come from the step and the order produced, so a replay rebuilds the same tasks.
+  - `addNode(name, fn, { ends })` declares `Send` targets, keeping reachability checks exact.
+- **Per-node retries and timeouts.** `addNode(name, fn, { retry, timeoutMs })`, with
+  `compile({ retry })` as the default for every node.
+  - Retrying is off unless asked for, because only the application knows whether a node is
+    idempotent. Interrupts, aborts, and validation errors are never retried.
+  - `context.attempt` tells a node which try it is on, and step events report the attempts a task
+    needed.
+  - A timeout aborts the node's signal and fails that attempt with `GraphNodeTimeoutError`, even if
+    the node ignores its signal.
+- **`onNodeError`.** When a task fails, its siblings are aborted (`fail-fast`, the default) or left to
+  finish (`settle`). Either way, what they already wrote is kept.
+- **Several questions at once.** Parallel tasks can each interrupt. Paused checkpoints and results
+  carry `interrupts`, and `resumeInterrupts()` answers any subset by id. A single question still works
+  exactly as before through `resume()`.
+- **Install weight is now measured honestly.** The size table only ever counted this package's own
+  files, so a small entry point could quietly force a large dependency on the consumer.
+  - `npm run size:check` follows bare imports too, and the README table gains a column for what each
+    entry point makes you install. Most entry points force nothing: `/graph`, `/operations`,
+    `/batch`, `/embeddings`, and every image subpath import no third-party package at all. The root
+    import, `/core`, `/config`, and `/security` pull in 3.4 to 4.7 MB, because JSON-schema and Zod
+    validation live there.
+  - The clean-install test now measures and bounds the whole production install: 10.0 MB of
+    `node_modules`, of which 3.0 MB is this package.
+
+### Fixed
+
+- **A retry no longer lets the process exit while it waits.** The backoff timer was unref'd, so a run
+  waiting to retry could be abandoned by an otherwise idle process.
+
+## [1.10.0] - 2026-09-16
+
+Image portability. Three image backends now sit behind one contract: OpenAI, Google Imagen, and a
+self-hosted ComfyUI server. Masked edits work on all three, and every input is validated before any
+provider sees it. Visual moderation inspects both the request and the generated images. Image output
+can be evaluated for alignment, rendered text, preservation, and safety. Each piece is its own subpath,
+and none is loaded by the root import.
+
+### Added
+
+- **Google Imagen adapter** (`nexus-ai-pro/images/google`). It calls the `:predict` protocol on the
+  Gemini API with an API key, or on Vertex AI with a bearer token, for generation and masked
+  inpainting.
+  - It differs from OpenAI, and negotiation says so. Output is sized by aspect ratio, so `dimensions`
+    is refused. `seed` and `negativePrompt` are supported.
+  - A seed disables the watermark, and the result reports that as a warning.
+  - When Imagen filters some images in a batch, the images that passed are still returned.
+- **ComfyUI adapter** (`nexus-ai-pro/images/comfyui`) for a self-hosted server.
+  - It uploads inputs, queues a workflow, polls with backoff, and downloads saved outputs.
+  - It records the seed it used, even when the caller chose none, so a good run can be reproduced.
+  - It removes an abandoned or failed prompt from the queue and interrupts it, so the GPU is not left
+    working on a result nobody is waiting for.
+  - The workflow graph belongs to the application. Stock text-to-image and inpainting builders are
+    included.
+- **Mask conversion** (`nexus-ai-pro/images/transform`). You draw a mask once, with either polarity, and
+  it becomes OpenAI's alpha channel or the white-is-editable greyscale that Imagen and ComfyUI read.
+  - A size mismatch is refused unless `resizeMode` allows `stretch`, `contain`, or `cover`. Resampling
+    is nearest-neighbour, so a binary mask gains no grey fringe, and `contain` padding is never
+    editable.
+  - Partly transparent pixels count as non-editable, so a soft brush edge never widens an edit.
+  - The PNG codec loads on the first masked request. An application that never masks never pays for
+    it.
+  - `AssetTransformer` is an injection seam for applications that want JPEG or WebP masks.
+- **Validated inputs** (`nexus-ai-pro/images/inputs`). `ImageInputResolver` applies the same checks to
+  byte uploads, remote URLs, and stored assets, and plugs into `ImageConfig.inputResolver`.
+  - The type is decided by the bytes. A declared or served MIME type that disagrees is refused rather
+    than corrected.
+  - Byte and pixel limits are enforced. The pixel limit is read from the header before decoding, so a
+    small file claiming a huge canvas is refused without allocating anything.
+  - Remote fetches get the web connector's SSRF protection: pinned DNS, redirect revalidation, and
+    blocking of private networks and cloud metadata.
+  - Refusals are `ImageInputError`s with a machine-readable `reason`.
+- **Visual moderation** (`nexus-ai-pro/images/moderation`). `createOpenAIVisualModeration` screens the
+  prompt, input and reference images, and every generated image, because an innocuous prompt can
+  still produce an unsafe image.
+  - Block and review thresholds can be set per category.
+  - If the moderation call fails, the request is blocked unless `failOpen` is set.
+  - A stored output that cannot be sent for moderation is routed to review.
+  - `combineSafetyPolicies` runs several policies and keeps every finding.
+- **Media evaluation** (`nexus-ai-pro/images/evals`). `MediaEvalRunner` checks four things:
+  - prompt alignment, using an injected judge;
+  - rendered text, using OCR and edit distance;
+  - edit preservation, using a perceptual hash that survives re-encoding;
+  - blocking behaviour, reported as false-positive and false-negative rates.
+
+  Every case runs repeatedly and reports mean, spread, and a 95% interval, plus latency, cost, error,
+  and failover figures. Scores inside a configured uncertainty band go to a `ReviewQueue` instead of
+  being decided automatically.
+- **A masked-edit conformance case.** It runs for every provider that declares `supportsMask`. The
+  fixture is a literal PNG, so the testing entry point does not load the codec.
+
+### Changed
+
+- **OpenAI masked edits and transparency are enabled.** `OpenAIImageProvider` now declares
+  `supportsMask` and `supportsTransparency`. `background: 'transparent'` is refused only with JPEG
+  output.
+- **A provider can explain missing images.** A blocking output finding marked `metadata.withheld`
+  counts toward the requested image count, and it does not block the images that were returned. Any
+  other blocking finding still blocks the whole result.
+- **SSRF protection is shared.** It moved out of the web connector into one module that the connector
+  and image inputs both use. The web connector behaves the same, and its security tests pass
+  unchanged. Policy refusals are now a `UrlPolicyError`, with the same messages.
+- **Graphs checkpoint by default, as the documentation always said.** `compile()` now uses an
+  in-process `MemoryGraphCheckpointer` when none is given, so `interrupt()`, `state()`, and
+  `history()` work without setup. The default keeps at most 1,000 threads, dropping the least recently
+  written one, so a service that never resumes cannot grow without limit. `maxThreads` is configurable,
+  and `checkpointer: false` turns checkpointing off. Before this fix, `compile()` created no
+  checkpointer and `interrupt()` threw.
+- **The whole-package size limit is higher.** The new modules are about 200 KB unpacked across both
+  builds, so the tarball limit rose from 460 KB to 500 KB packed and from 2.85 MB to 3.1 MB unpacked.
+  No existing import got heavier because of them. Each new module has its own per-subpath budget, and
+  the root import loads none of them.
+
+### Fixed
+
+- **A failed graph step no longer re-runs the siblings that finished.** The failed checkpoint used to
+  discard their writes, so `continue()` ran them again and repeated their side effects. It now keeps
+  those writes, and `continue()` retries only the nodes that did not finish.
+- **Finished siblings still route onward after a paused or failed step resumes.** The checkpoint
+  carried only the unfinished nodes, so the outgoing edges of siblings that had already finished were
+  lost. A new optional `completed` field on the checkpoint records those siblings.
+- **A subgraph that asks a question now pauses its parent.** `asNode()` used to treat an interrupted
+  subgraph as finished: the parent merged its partial state and carried on. The parent now interrupts
+  with the same question, and resuming the parent passes the answer into the subgraph, which continues
+  where it stopped. A subgraph that asks several questions works across several resumes.
+- **Rewinding no longer leaves checkpoints from the abandoned timeline.** After `resumeFrom(step)`,
+  both checkpointers kept the later steps, so `state()` could return a step that no longer existed.
+  Writing a step now drops any stored steps at or after it.
+- **`context.report()` works.** It did nothing. Progress now reaches the new
+  `GraphRunOptions.onProgress` callback, and a callback that throws does not fail the node.
+- **`CompileOptions.name` is used.** It was documented but never read. It is now recorded on every
+  checkpoint as `metadata.graph`.
+- **An unnamed graph run now reports its thread id.** `invoke()` without a `threadId` returned
+  `threadId: ''` even though it had generated one, so the run could not be inspected or resumed.
+- **`AgentLoop` no longer runs a tool with arguments the model did not send.** Malformed tool-call
+  JSON, or arguments that are not an object, used to become `{}` and the tool ran anyway. The tool is
+  now skipped, and the parse error goes back to the model as the tool result.
+- **`AgentLoop` says why it stopped.** `AgentResult.stopReason` is `completed` or `max_iterations`, so
+  a caller can tell a final answer from a run that hit the iteration limit.
 
 ## [1.9.0] - 2026-09-15
 
@@ -457,7 +614,9 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.9.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.11.0...HEAD
+[1.11.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.10.0...v1.11.0
+[1.10.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.9.0...v1.10.0
 [1.9.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.8.0...v1.9.0
 [1.8.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.7.0...v1.8.0
 [1.7.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.6.0...v1.7.0