nexus-ai-pro 1.9.0 → 1.10.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 (Unreleased)
+
+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,6 +277,19 @@ 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()`.
 
+`compile()` without a checkpointer uses an in-process `MemoryGraphCheckpointer` capped at 1,000
+threads (Unreleased; earlier releases created none). `checkpointer: false` disables checkpointing. A
+run started without a `threadId` reports its generated id on the result.
+
+Also Unreleased:
+
+- 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. 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

package/CHANGELOG.md

@@ -4,7 +4,115 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
-## [Unreleased]
+## [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 +565,8 @@ 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.10.0...HEAD
+[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

package/README.md

@@ -921,9 +921,123 @@ console.log(image.assets[0]?.location);
 
 `ImageProvider` is independent from completion providers. Explicit options are negotiated against the
 selected provider's declared capabilities, so unsupported formats, delivery kinds, masks, seeds, or
-dimensions fail before a provider call. The OpenAI adapter supports one-shot generation and
-reference-based editing through byte assets. Masked OpenAI edits remain disabled until a transformer can
-verify dimensions and convert the neutral mask contract to OpenAI's alpha-channel semantics.
+dimensions fail before a provider call rather than being silently dropped.
+
+### Three backends, one contract
+
+The same request runs against OpenAI, Google Imagen, or a self-hosted ComfyUI server. Each adapter is
+its own subpath, so an application loads only the backends it registers.
+
+```ts
+import { ComfyUIImageProvider } from 'nexus-ai-pro/images/comfyui';
+import { GoogleImageProvider } from 'nexus-ai-pro/images/google';
+
+const portable = new NexusAI({
+  providers: {},
+  images: {
+    defaultProvider: 'google',
+    providers: {
+      openai: openaiImages,
+      google: new GoogleImageProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+      local: new ComfyUIImageProvider({ baseUrl: 'http://127.0.0.1:8188' }),
+    },
+  },
+});
+```
+
+The backends really do differ, and negotiation says so instead of hiding it. Imagen sizes output by
+aspect ratio and refuses `dimensions`. It honours `seed` and `negativePrompt`, which OpenAI refuses, and
+setting a seed turns its watermark off, which the result reports as a warning. When Imagen filters some
+images in a batch, you get the ones that passed plus a withheld finding for each missing one. ComfyUI
+queues work and polls for it, records the seed it used so any run can be reproduced, and removes an
+abandoned prompt from the server queue. Its graph is yours: pass a `workflow` builder, or use the bundled
+`comfyTextToImageWorkflow` and `comfyInpaintWorkflow`.
+
+### Masked edits
+
+Draw the mask once, with either polarity. Each adapter converts it to what its backend expects:
+OpenAI's alpha channel, or Imagen's and ComfyUI's white-is-editable greyscale.
+
+```ts
+const edited = await portable.images.edit({
+  provider: 'openai',
+  prompt: 'Replace the sky with a sunset',
+  input: { location: { kind: 'bytes', data: photo }, mimeType: 'image/png' },
+  mask: {
+    location: { kind: 'bytes', data: maskPng },
+    mimeType: 'image/png',
+    polarity: 'white-is-editable',
+    resizeMode: 'reject', // or 'stretch' | 'contain' | 'cover'
+  },
+});
+```
+
+A mask whose size differs from the image is refused unless `resizeMode` allows resampling.
+Partly transparent mask pixels count as non-editable, so a soft brush edge never widens the edit.
+The PNG codec behind the bundled `PngMaskTransformer` loads on the first masked request, so an
+application that never masks never loads it. To accept JPEG or WebP masks, pass your own
+`maskTransformer`.
+
+### Validating inputs
+
+Byte uploads, remote URLs, and stored assets all go through the same checks before any provider sees
+them:
+
+```ts
+import { createImageInputResolver } from 'nexus-ai-pro/images/inputs';
+
+const guarded = new NexusAI({
+  providers: {},
+  images: {
+    providers: { google: googleImages },
+    inputResolver: createImageInputResolver({
+      maxBytes: 10 * 1024 * 1024,
+      maxPixels: 16_000_000,
+      allowedDomains: ['cdn.example.com'],
+    }),
+  },
+});
+```
+
+The file's own bytes decide its type. A declared or served MIME type that disagrees is refused. Pixel
+limits are checked from the header before decoding, so a small file that claims a huge canvas costs
+nothing. Remote URLs use the same SSRF protection as the web connector: pinned DNS, redirect
+revalidation, and blocking of private networks and cloud metadata endpoints. A refusal is an
+`ImageInputError` whose `reason` is machine-readable (`too-large`, `mime-mismatch`, `blocked-url`, and
+so on). Without a resolver, nothing runs and nothing is loaded.
+
+### Visual moderation
+
+```ts
+import { combineSafetyPolicies, createOpenAIVisualModeration } from 'nexus-ai-pro/images/moderation';
+
+const safety = combineSafetyPolicies(
+  createOpenAIVisualModeration({ apiKey: process.env.OPENAI_API_KEY!, reviewThreshold: 0.4 }),
+  myBrandPolicy,
+);
+```
+
+Visual moderation screens the prompt, the input and reference images, and every generated image. An
+innocuous prompt can still produce an unsafe image, so text-only checks are not enough. Scores map to
+`block` or `review` findings, with per-category thresholds. If the moderation call itself fails, the
+request is blocked unless you set `failOpen`.
+
+### Evaluating media
+
+`MediaEvalRunner` from `nexus-ai-pro/images/evals` scores what a string golden file cannot:
+
+- prompt alignment, scored by your judge;
+- rendered text, through your OCR function and edit distance;
+- whether an edit preserved the rest of the image, through a perceptual hash that survives re-encoding;
+- whether content was blocked when it should have been, reported as false-positive and false-negative
+  rates.
+
+Each case runs several times and reports mean, spread, and a 95% interval. Scores inside a configured
+uncertainty band go to a `ReviewQueue` for a person to judge instead of being decided automatically.
+
+Image support is still marked experimental. The adapters are verified against recorded wire shapes
+and a shared conformance suite, which now includes a masked-edit case. The label comes off after the
+opt-in live conformance suite passes against each hosted backend.
 
 Use `submit()` for a cancellable local operation handle with replayable lifecycle events:
 
@@ -1615,6 +1729,12 @@ import { ImageManager } from 'nexus-ai-pro/images';
 import { MemoryAssetStore } from 'nexus-ai-pro/images/assets';
 import { MockImageProvider } from 'nexus-ai-pro/images/mock';
 import { OpenAIImageProvider } from 'nexus-ai-pro/images/openai';
+import { GoogleImageProvider } from 'nexus-ai-pro/images/google';
+import { ComfyUIImageProvider } from 'nexus-ai-pro/images/comfyui';
+import { PngMaskTransformer } from 'nexus-ai-pro/images/transform';
+import { createImageInputResolver } from 'nexus-ai-pro/images/inputs';
+import { createOpenAIVisualModeration } from 'nexus-ai-pro/images/moderation';
+import { MediaEvalRunner } from 'nexus-ai-pro/images/evals';
 import { createRealtimeSession } from 'nexus-ai-pro/realtime/session';
 import { OpenAIWebRTCTransport } from 'nexus-ai-pro/realtime/openai-webrtc';
 import { TelephonyManager } from 'nexus-ai-pro/telephony';
@@ -1633,12 +1753,12 @@ past its budget — so the numbers stay true rather than aspirational.
 <!-- size-table:start -->
 | Import | Size | Share of root |
 | --- | --- | --- |
-| `nexus-ai-pro` | 606 KB | 100% |
-| `nexus-ai-pro/config` | 465 KB | 77% |
-| `nexus-ai-pro/core` | 459 KB | 76% |
+| `nexus-ai-pro` | 612 KB | 100% |
+| `nexus-ai-pro/config` | 468 KB | 76% |
+| `nexus-ai-pro/core` | 462 KB | 75% |
 | `nexus-ai-pro/realtime` | 157 KB | 26% |
 | `nexus-ai-pro/batch` | 118 KB | 19% |
-| `nexus-ai-pro/realtime/session` | 94 KB | 16% |
+| `nexus-ai-pro/realtime/session` | 94 KB | 15% |
 | `nexus-ai-pro/embeddings` | 91 KB | 15% |
 | `nexus-ai-pro/providers/groq` | 79 KB | 13% |
 | `nexus-ai-pro/providers/mistral` | 79 KB | 13% |
@@ -1648,29 +1768,34 @@ past its budget — so the numbers stay true rather than aspirational.
 | `nexus-ai-pro/providers/llamacpp` | 77 KB | 13% |
 | `nexus-ai-pro/providers/lmstudio` | 77 KB | 13% |
 | `nexus-ai-pro/providers/openai` | 77 KB | 13% |
-| `nexus-ai-pro/providers/anthropic` | 70 KB | 12% |
+| `nexus-ai-pro/providers/anthropic` | 70 KB | 11% |
 | `nexus-ai-pro/providers/google` | 66 KB | 11% |
-| `nexus-ai-pro/images` | 63 KB | 10% |
-| `nexus-ai-pro/providers/ollama` | 58 KB | 10% |
-| `nexus-ai-pro/batch/openai` | 52 KB | 9% |
-| `nexus-ai-pro/batch/anthropic` | 52 KB | 9% |
+| `nexus-ai-pro/images` | 65 KB | 11% |
+| `nexus-ai-pro/providers/ollama` | 58 KB | 9% |
+| `nexus-ai-pro/batch/openai` | 52 KB | 8% |
+| `nexus-ai-pro/batch/anthropic` | 52 KB | 8% |
 | `nexus-ai-pro/operations` | 49 KB | 8% |
 | `nexus-ai-pro/batch/mock` | 47 KB | 8% |
 | `nexus-ai-pro/providers/cohere` | 46 KB | 8% |
 | `nexus-ai-pro/realtime/openai-webrtc` | 46 KB | 8% |
 | `nexus-ai-pro/security` | 40 KB | 7% |
 | `nexus-ai-pro/models` | 35 KB | 6% |
-| `nexus-ai-pro/graph` | 29 KB | 5% |
+| `nexus-ai-pro/graph` | 33 KB | 5% |
+| `nexus-ai-pro/images/inputs` | 31 KB | 5% |
 | `nexus-ai-pro/realtime/openai-websocket` | 29 KB | 5% |
 | `nexus-ai-pro/evals` | 23 KB | 4% |
+| `nexus-ai-pro/images/transform` | 22 KB | 4% |
 | `nexus-ai-pro/images/stores` | 22 KB | 4% |
 | `nexus-ai-pro/telephony/twilio` | 21 KB | 3% |
 | `nexus-ai-pro/telephony` | 20 KB | 3% |
+| `nexus-ai-pro/images/openai` | 19 KB | 3% |
 | `nexus-ai-pro/realtime/mock` | 19 KB | 3% |
 | `nexus-ai-pro/voice` | 18 KB | 3% |
-| `nexus-ai-pro/images/openai` | 18 KB | 3% |
+| `nexus-ai-pro/images/comfyui` | 17 KB | 3% |
 | `nexus-ai-pro/embeddings/adapters` | 17 KB | 3% |
 | `nexus-ai-pro/realtime/conversation` | 16 KB | 3% |
+| `nexus-ai-pro/images/google` | 15 KB | 2% |
+| `nexus-ai-pro/images/evals` | 15 KB | 2% |
 | `nexus-ai-pro/images/assets` | 14 KB | 2% |
 | `nexus-ai-pro/context` | 13 KB | 2% |
 | `nexus-ai-pro/operations/adapters` | 13 KB | 2% |
@@ -1683,6 +1808,7 @@ past its budget — so the numbers stay true rather than aspirational.
 | `nexus-ai-pro/providers/base` | 10 KB | 2% |
 | `nexus-ai-pro/embeddings/models` | 10 KB | 2% |
 | `nexus-ai-pro/voice/openai` | 9 KB | 1% |
+| `nexus-ai-pro/images/moderation` | 9 KB | 1% |
 | `nexus-ai-pro/ops/circuit-breaker` | 8 KB | 1% |
 | `nexus-ai-pro/realtime/openai-server` | 8 KB | 1% |
 | `nexus-ai-pro/capabilities` | 8 KB | 1% |
@@ -1760,13 +1886,16 @@ See [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMA
 shipped and what is planned. It is a design proposal, not a compatibility promise; the guarantees
 live in [API_STABILITY.md](./API_STABILITY.md).
 
-1.4.0 closed the completion-request gap: prompt caching, reasoning controls, tool and sampling
-controls, structured usage with numeric cost, and capability negotiation with registry provenance.
+Shipped so far:
+
+- completion controls and capability negotiation;
+- durable operations, provider batch tiers, and distributed resilience;
+- first-class embeddings and graphs;
+- per-entry-point size budgets.
 
-Next is durable execution — an operation state machine, provider batch APIs, distributed rate
-limiting and circuit breaking, first-class embeddings, and filesystem/S3 asset stores — followed by
-image portability and promotion out of experimental. See
-[ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md).
+The current work is image portability: three backends behind one contract, masked edits, validated
+inputs, visual moderation, and media evaluation. Promotion out of experimental waits on live
+conformance.
 
 ## Known Limitations
 

package/dist/agent/loop.d.ts

@@ -8,5 +8,4 @@ export declare class AgentLoop {
     private client;
     constructor(client: AgentModelClient);
     run(config: AgentConfig): Promise<AgentResult>;
-    private parseToolArgs;
 }

package/dist/agent/loop.js

@@ -41,13 +41,19 @@ export class AgentLoop {
                     content: response.content,
                     steps,
                     iterations: iteration,
+                    stopReason: 'completed',
                     response,
                     messages,
                 };
             }
             for (const toolCall of response.toolCalls) {
-                const args = this.parseToolArgs(toolCall.function.arguments);
-                const result = await executor.execute(toolCall.function.name, args);
+                const parsed = parseToolArgs(toolCall.function.arguments);
+                // Malformed arguments are reported back to the model rather than guessed at: running a tool
+                // with empty arguments could perform an action the model never asked for.
+                const result = parsed.ok
+                    ? await executor.execute(toolCall.function.name, parsed.args)
+                    : { ok: false, error: parsed.error };
+                const args = parsed.ok ? parsed.args : {};
                 const toolStep = {
                     iteration,
                     type: 'tool',
@@ -73,17 +79,24 @@ export class AgentLoop {
             content: lastResponse.content,
             steps,
             iterations: maxIterations,
+            stopReason: 'max_iterations',
             response: lastResponse,
             messages,
         };
     }
-    parseToolArgs(raw) {
-        try {
-            const parsed = JSON.parse(raw || '{}');
-            return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {};
-        }
-        catch {
-            return {};
-        }
+}
+function parseToolArgs(raw) {
+    // An absent argument string is a call with no arguments, which is legitimate.
+    if (!raw?.trim())
+        return { ok: true, args: {} };
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed))
+            return { ok: true, args: parsed };
+        return { ok: false, error: 'Tool arguments must be a JSON object; the tool was not run' };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `Tool arguments are not valid JSON (${reason}); the tool was not run` };
     }
 }

package/dist/connectors/web.d.ts

@@ -1,20 +1,10 @@
 import type { ToolDefinition } from '../types/messages.js';
-export type WebResolvedAddress = string | {
-    address: string;
-    family?: 4 | 6;
-};
-export interface WebConnectorOptions {
-    allowedDomains?: string[];
+import { type SafeFetchPolicy, type WebResolvedAddress } from '../utils/safe-fetch.js';
+export type { WebResolvedAddress };
+export interface WebConnectorOptions extends SafeFetchPolicy {
     timeoutMs?: number;
-    userAgent?: string;
     maxResponseBytes?: number;
     maxRedirects?: number;
-    /** Explicitly allow loopback/private targets, for example a trusted local development service. */
-    allowPrivateNetworks?: boolean;
-    /** Cloud metadata endpoints remain denied unless this separate high-risk opt-in is enabled. */
-    allowCloudMetadata?: boolean;
-    /** Optional resolver for split-horizon DNS or deterministic tests. Every returned address is validated. */
-    resolveHostname?: (hostname: string) => Promise<readonly WebResolvedAddress[]>;
 }
 export declare function createFetchUrlTool(options?: WebConnectorOptions): ToolDefinition;
 export declare function createSearchTool(search: (query: string) => Promise<unknown>, name?: string): ToolDefinition;