nexus-ai-pro 0.8.1 → 0.9.0

package/API_STABILITY.md

@@ -0,0 +1,32 @@
+# API Stability Policy
+
+This policy describes compatibility guarantees for `nexus-ai-pro` beginning with version 0.9.0.
+
+## Release stages
+
+The package is pre-1.0. Minor releases may contain breaking changes when they are necessary, but those changes will be called out in the changelog with migration guidance. Patch releases are intended to remain backward compatible.
+
+The following surfaces are public and covered by this policy:
+
+- exports documented in the root package or an explicit `package.json` subpath;
+- exported TypeScript types and runtime symbols;
+- documented configuration keys, response shapes, and CLI commands.
+
+Source files, `dist` file paths, examples, test helpers that are not exported, and undocumented implementation details are not public API. Import only from `nexus-ai-pro` or one of its explicit subpaths.
+
+## Compatibility rules
+
+- A public symbol will not be removed or incompatibly changed in a patch release.
+- Deprecations will be documented before removal whenever practical.
+- New optional fields, providers, exports, error subclasses, and enum-like union members may be added in a minor release.
+- TypeScript improvements that expose previously invalid usage may arrive in a patch release.
+- Security fixes may tighten validation or blocking behavior in a patch release when preserving the old behavior would leave users exposed.
+- Provider behavior can change when an upstream API changes; Nexus will preserve its normalized request and response contracts where possible.
+
+The package is ESM-only and supports Node.js 22 or newer. CommonJS `require()` and deep imports into `dist` or `src` are not supported.
+
+## Deprecation process
+
+Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. During the 0.x series, removal will not normally occur earlier than the next minor release. After 1.0, removals will be reserved for major releases, except when an urgent security issue requires otherwise.
+
+Report accidental compatibility regressions through the project issue tracker. Security issues should follow [SECURITY.md](./SECURITY.md).

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+Notable changes to this project are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and releases use semantic versioning while accounting for the pre-1.0 stability policy.
+
+## [Unreleased]
+
+## [0.9.0] - 2026-07-15
+
+### Added
+
+- Full JSON Schema validation through Ajv and standard format validation through `ajv-formats`.
+- Node.js 22 and 24 CI gates for linting, builds, tests, consumer type checks, and packed-package installation.
+- OIDC trusted publishing with npm provenance for tagged releases.
+- API stability, security, and contribution policies.
+- Biome formatting/lint gates, test/example type checks, and built-in Node.js coverage thresholds.
+
+### Changed
+
+- The supported runtime is now Node.js 22 or newer and the package is explicitly ESM-only.
+- Provider, cache, and job entry points now use an explicit export map instead of wildcard exports.
+- Published tarballs contain the runtime and essential package documentation, excluding repository examples and marketing assets.
+- Provider peer dependency ranges are bounded to tested SDK lines.
+- Build and publish scripts always clean and rebuild `dist` before packing.
+- Security-enabled output streams validate the complete bounded response before yielding chunks.
+
+### Fixed
+
+- Blocking output policies now stop unsafe completions instead of returning blocked content as successful output.
+- Streaming redaction protects values that cross provider chunk boundaries.
+- Provider timeouts abort in-flight completion and streaming requests.
+- 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/v0.9.0...HEAD
+[0.9.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/releases/tag/v0.9.0

package/README.md

@@ -7,6 +7,7 @@ Use the whole pipeline for production AI features, or turn pieces off when you o
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
 - Full technical notes and manual test cases: [NEXUS.md](./NEXUS.md)
+- Planned image generation and infrastructure work: [ROADMAP.md](./ROADMAP.md)
 
 ## Install
 
@@ -14,6 +15,8 @@ Use the whole pipeline for production AI features, or turn pieces off when you o
 npm install nexus-ai-pro
 ```
 
+Requires Node.js 22 or newer. `nexus-ai-pro` is ESM-only: use `import` from an ES module rather than CommonJS `require()`.
+
 Install only the provider SDKs your app uses. The OpenAI SDK also powers OpenAI-compatible adapters such as OpenRouter, Groq, Mistral, DeepSeek, Azure OpenAI, LM Studio, and llama.cpp.
 
 ```bash
@@ -246,6 +249,12 @@ for await (const chunk of stream) {
 
 All providers normalize streaming chunks to `text`, `tool_call`, `done`, or `error`.
 
+When security is enabled, output streams are correctness-first: Nexus buffers and validates the
+complete output before yielding any chunk, up to 1 MiB or 100,000 chunks. This prevents secrets,
+PII, and blocked phrases split across provider chunks from leaking partially, at the cost of
+token-by-token latency. `security: 'off'` preserves immediate streaming when that trade-off is
+explicitly acceptable for the application.
+
 ### Tools and Agents
 
 ```ts
@@ -559,6 +568,12 @@ Useful helpers:
 - URL and tool allowlist checks
 - reusable policies through `guardrailPolicy(...)`
 - `hardenPrompt(...)` for clearly delimiting untrusted input
+- `createFetchUrlTool(...)` with DNS pinning, redirect validation, private-network blocking, and
+  bounded response reads
+
+CLI scans and audit records redact detected values by default. `nexus scan --reveal-values` is
+restricted to an interactive terminal; raw audit data requires both `includeSensitiveData: true`
+and an explicit custom sink.
 
 ## Caching, Jobs, and Evals
 
@@ -670,7 +685,7 @@ import { RedisCacheAdapter } from 'nexus-ai-pro/cache';
 import { DeepSeekProvider } from 'nexus-ai-pro/providers/deepseek';
 ```
 
-Provider SDKs are optional peer dependencies. The package is ESM-first and marked with `sideEffects: false`.
+Provider SDKs are optional peer dependencies. The package is ESM-only, supports Node.js 22+, and is marked with `sideEffects: false`. Only the entry points listed in the package export map are public; deep imports into `dist` or `src` are unsupported.
 
 ## Examples
 
@@ -686,7 +701,7 @@ npm run example:optimizer
 npm run example:agent
 ```
 
-Included example files cover:
+Repository example files cover:
 
 - OpenTelemetry with Node HTTP and Express
 - BullMQ workers
@@ -701,19 +716,27 @@ Included example files cover:
 
 ```bash
 npm install
-npm run build
-npm test
-npm run test:types
-npm run test:clean-install
-npm run test:conformance:mock
+npm run check
+npm run check:release
 ```
 
+`check` runs formatting and lint gates, source/test/example type checks, the build, unit and mock
+conformance tests, coverage thresholds, package import checks, and an external type-consumer test.
+`check:release` additionally verifies the dry-run tarball and a clean packed-package install.
+
 Real provider conformance is opt-in:
 
 ```bash
 npm run test:conformance:real
 ```
 
+## Roadmap
+
+The next recommended feature family is first-class image generation and editing through a
+provider-neutral `ImageManager`, portable asset types, durable operation handles, visual safety,
+asset storage, and media-specific evaluations. The design and prioritized infrastructure backlog
+are in [ROADMAP.md](./ROADMAP.md).
+
 ## Production Notes
 
 - Use direct or rules-based routing when model choice is already known.

package/ROADMAP.md

@@ -0,0 +1,188 @@
+# nexus-ai-pro Roadmap
+
+This roadmap is a design proposal, not a compatibility promise. Stable and experimental
+surfaces are defined in [API_STABILITY.md](./API_STABILITY.md).
+
+## Recommended next release: first-class image generation
+
+Image generation should be a separate operation family rather than another variation of
+`complete()`. Text completions and generated assets have different request shapes, response
+lifecycles, costs, safety checks, storage needs, and retry semantics.
+
+The first public surface could look like this:
+
+```ts
+const result = await ai.images.generate({
+  model: 'auto',
+  prompt: 'A clean product photograph of a red mechanical keyboard',
+  aspectRatio: '16:9',
+  quality: 'high',
+  delivery: { kind: 'bytes', format: 'png' },
+});
+
+await ai.images.edit({
+  model: 'auto',
+  prompt: 'Replace the background with a softly lit studio wall',
+  input: result.assets[0],
+  mask: {
+    location: { kind: 'bytes', data: maskBytes },
+    mimeType: 'image/png',
+    polarity: 'white-is-editable',
+  },
+  references: [styleReference],
+});
+```
+
+`auto` should resolve through versioned, verified aliases instead of making a model name part of
+the durable API. OpenAI currently supports one-shot generation and editing through the Image API,
+while the Responses API supports conversational, multi-turn image workflows. See the
+[official image generation guide](https://developers.openai.com/api/docs/guides/image-generation)
+and [GPT Image 2 model page](https://developers.openai.com/api/docs/models/gpt-image-2).
+
+### Recommended API boundary
+
+- Add a lightweight `ImageManager` in `nexus-ai-pro/images`, following the voice manager pattern.
+- Expose `ai.images.generate()`, `ai.images.edit()`, and `ai.images.submit()`.
+- Let `generate()` and `edit()` wait for a result. Let `submit()` return an
+  `OperationHandle<TResult>` with `status()`, `result()`, `cancel()`, and `events()`.
+- Add `registerImageProvider()`, `hasImageProvider()`, and `listImageProviders()`.
+- Keep provider-neutral types in the core export and optional integrations in exports such as
+  `nexus-ai-pro/images/openai` and `nexus-ai-pro/images/comfyui`.
+
+### Media types
+
+- Prefer `Uint8Array`, `Blob`, URLs, and web streams in public types; keep Node `Buffer` as a
+  convenience input rather than the portable core type.
+- Use discriminated asset locations instead of several optional fields:
+  `{ kind: 'bytes'; data: Uint8Array }`, `{ kind: 'url'; url; expiresAt? }`, or
+  `{ kind: 'stored'; uri; assetId }`.
+- Define `AssetInput`, `AssetDescriptor`, `ImageGenerateRequest`, `ImageEditRequest`,
+  `ImageResult`, `MediaUsage`, `MediaSafetyFinding`, `OperationEvent`, and
+  `OperationHandle<TResult>`.
+- Keep dimensions, MIME type, checksum, storage location, and provenance on each asset. Put
+  latency, cost, route, and usage in result-level `OperationMeta`.
+- Make `input`, `mask`, and `references` explicit for editing. Define mask polarity, sizing, and
+  resize rules so adapters cannot silently reinterpret a request.
+- Model generation, editing, masking/inpainting, variations, and background transparency as
+  explicit capabilities.
+- Split model capabilities into `inputModalities` and `outputModalities`, and retire the current
+  semantic overlap between `vision`, `image`, and `pdf`.
+
+### Provider architecture
+
+- Introduce `ImageProvider` independently of the completion-shaped `BaseProvider`.
+- Give every provider family a shared internal `ProviderCallContext` containing abort signal,
+  deadline, request ID, trace context, and idempotency key.
+- Start with a deterministic mock provider and one hosted provider supporting generation and edit.
+- Add a second cloud adapter and local ComfyUI before stabilizing the API; this exposes assumptions
+  around masks, seeds, negative prompts, polling, formats, and quality controls.
+- Negotiate operation, input MIME types, mask support, dimensions, aspect ratio, transparency,
+  output format, and count. Unsupported options must fail or produce an explicit warning.
+- Route by capability, latency, cost, quality, residency, and safety policy.
+
+### Asset and job pipeline
+
+- Add an `AssetStore` interface with `put`, `get`, `stat`, `delete`, `sign`, retention, tenant
+  ownership, checksums, and streaming. Start with bounded memory/filesystem adapters, then add
+  S3-compatible storage.
+- Treat provider URLs as temporary delivery locations, never as durable storage.
+- Resolve remote inputs with SSRF protection, MIME sniffing, byte/pixel limits,
+  decompression-bomb protection, and a redirect policy.
+- Put metadata stripping, provenance, and image transforms behind optional `AssetTransformer`
+  adapters so the core install stays small.
+- Add visual input and output moderation; text-only security checks are not sufficient.
+- Keep idempotency separate from generative caching. An idempotency key replays the same accepted
+  operation. Caching remains opt-in and keys on model version, policy version, parameters, and
+  source-asset hashes.
+- Build a real operation state machine: queued, running, succeeded, failed, cancelling, cancelled,
+  and expired. Add leases/heartbeats, progress events, delayed retry, dead-letter handling,
+  cancellation, timestamps, signed webhooks, and trace propagation.
+- Queue asset references only; never JSON-serialize binary media into job payloads.
+- Reserve and reconcile budget using provider-appropriate pricing such as per-image, megapixel, or
+  compute time. Ambiguous timeouts must not create duplicate assets or charges.
+
+### Image evaluation
+
+- Prompt/image semantic alignment and OCR accuracy for generated text.
+- Perceptual similarity for edit preservation.
+- Safety-policy pass rate and false-positive tracking.
+- Latency, cost, retry, and provider failover metrics.
+- Repeated-run statistical baselines for stochastic output, plus human-review queues.
+- Brand/style reference kits, campaign variant matrices, prompt presets, and reproducibility
+  manifests.
+- A generic evaluation target or parallel `MediaEvalRunner`; string-only golden-file tests are not
+  a useful image-quality gate.
+
+## Infrastructure improvements
+
+### One lifecycle for every operation
+
+Create an internal typed lifecycle and adapt existing operations to it incrementally:
+
+`validate -> authorize -> input policy -> resolve assets -> route -> reserve budget -> execute ->`
+`output policy -> persist -> reconcile cost -> audit`
+
+Completions, streams, embeddings, voice, images, and jobs should share the same authorization,
+budget, hooks, audit, metrics, and finalization stages, including cache hits. Transport-specific
+code should only perform the provider call and normalize its result.
+
+### Provider compatibility automation
+
+- Maintain provider contract tests for minimum and latest supported SDK versions.
+- Generate the model registry from versioned provider data with `verifiedAt` and source fields.
+- Mark aliases as stable, preview, or deprecated and emit opt-in deprecation warnings.
+- Record/replay provider fixtures so most conformance tests run without credentials.
+- Detect capability drift so provider option loss cannot happen silently.
+
+### Durable production primitives
+
+- Distributed rate-limit and circuit-breaker adapters.
+- Idempotency, request deduplication, cancellation, progress, and operation-event adapters.
+- Persistent conversation/session stores.
+- Webhook delivery with signatures, retries, and a dead-letter queue.
+- Resumable background operations for image/video generation and large eval runs.
+- GPU-aware local scheduling, leases, heartbeats, and backpressure.
+
+### Observability and governance
+
+- Standard operation spans and metrics across provider, model, modality, cache, retry, and cost.
+- Tenant/project budget policies with reservation and reconciliation of actual usage.
+- Redaction-safe audit records with stable finding IDs rather than sensitive values.
+- OpenTelemetry semantic conventions plus trace propagation through queues and webhooks.
+- An optional local control plane for approvals, traces, evals, costs, provider health, assets,
+  retention, and queued operations.
+
+### Smaller install surface
+
+- Keep a small provider-neutral core.
+- Move heavy or environment-specific integrations into optional exports or a future scoped package
+  family, including OpenTelemetry, BullMQ, image transforms, and provider adapters.
+- Make browser/edge compatibility explicit by isolating Node filesystem, crypto, DNS, and stream
+  dependencies behind adapters.
+
+## Additional feature backlog
+
+1. True mixed text/asset outputs and tool results that pass asset references without base64 JSON.
+2. OCR, captioning, visual question answering, image embeddings, and visual moderation.
+3. Realtime voice/video sessions with interruption handling, turn detection, and live tool calls.
+4. Video generation through the same asynchronous operation, job, and asset contracts.
+5. Media search and RAG using image embeddings.
+6. MCP client/server adapters with asset and tool interoperability.
+7. Human approval checkpoints for high-impact tools and generated-media publication.
+8. Policy-as-code presets versioned independently from the runtime.
+9. Prompt/workflow versioning with offline replay and A/B evaluation.
+10. Multi-tenant credential-vault adapters and per-provider residency routing.
+
+## Suggested delivery order
+
+1. Stabilize the shared operation lifecycle and provider conformance suite.
+2. Add portable media types, `ImageManager`, `ImageProvider`, and a deterministic mock provider.
+3. Ship one hosted generate/edit adapter, bounded local asset storage, and visual safety hooks as
+   experimental APIs.
+4. Add the production asset store and operation state machine with progress, cancellation,
+   idempotency, and cost reconciliation.
+5. Add a second cloud provider and local ComfyUI to validate portability.
+6. Add true multimodal outputs and media evaluation.
+7. Promote the media API only after packed-package tests, provider conformance, and image evals
+   cover the supported capability matrix.
+

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest published minor release. Users should upgrade to the newest `0.9.x` patch as fixes become available.
+
+## Reporting a vulnerability
+
+Please use [GitHub private vulnerability reporting](https://github.com/mkhitar-abrahamyan/nexus-ai/security/advisories/new). Do not open a public issue for an undisclosed vulnerability and do not include real credentials, personal data, or exploit targets in a report.
+
+Include the affected version, impact, a minimal reproduction, and any suggested mitigation. You can expect an acknowledgement within five business days. A confirmed issue will be coordinated privately until a fix and disclosure plan are ready.
+
+## Scope and safe operation
+
+Nexus guardrails reduce common AI application risks, but they are not a complete authorization or security boundary. Applications remain responsible for access control, provider-side safety controls, tool authorization, network egress policy, secret storage, and review of high-impact model actions.

package/dist/agent/tool.js

@@ -9,7 +9,9 @@ export function tool(definition) {
 export class ToolExecutor {
     tools = new Map();
     constructor(tools = []) {
-        tools.forEach((toolDefinition) => this.register(toolDefinition));
+        for (const toolDefinition of tools) {
+            this.register(toolDefinition);
+        }
     }
     register(toolDefinition) {
         this.tools.set(toolDefinition.name, toolDefinition);

package/dist/cache/adapters.js

@@ -64,7 +64,9 @@ export class SQLiteCacheAdapter {
         return JSON.parse(row.value);
     }
     set(key, value, ttlSeconds = 300) {
-        this.db.prepare(`INSERT OR REPLACE INTO ${this.table} (key, value, expires_at) VALUES (?, ?, ?)`).run?.(key, JSON.stringify(value), Date.now() + ttlSeconds * 1000);
+        this.db
+            .prepare(`INSERT OR REPLACE INTO ${this.table} (key, value, expires_at) VALUES (?, ?, ?)`)
+            .run?.(key, JSON.stringify(value), Date.now() + ttlSeconds * 1000);
     }
     delete(key) {
         this.db.prepare(`DELETE FROM ${this.table} WHERE key = ?`).run?.(key);

package/dist/cli.js

@@ -7,11 +7,12 @@ import { EvalRunner } from './evals/runner.js';
 import { NexusAI } from './core/nexus.js';
 import { listKnownModels, listModelsForProvider, getModelCapabilities } from './models/registry.js';
 import { SecurityPipeline } from './security/index.js';
+import { redactSensitiveText } from './security/output-guard.js';
 import { UploadScanner } from './security/upload-scanner.js';
 import { TokenOptimizer } from './optimizer/index.js';
 const DEFAULT_SCAN_MAX_BYTES = 1_000_000;
 const IGNORED_DIRS = new Set(['.git', 'node_modules', 'dist', 'coverage', '.next', '.turbo']);
-const BOOLEAN_FLAGS = new Set(['all', 'densify', 'fail', 'help', 'json', 'print']);
+const BOOLEAN_FLAGS = new Set(['all', 'densify', 'fail', 'help', 'json', 'print', 'reveal-values']);
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const parsed = parseArgs(rest);
@@ -37,6 +38,13 @@ async function main() {
     }
 }
 async function runScan({ positionals, flags }) {
+    const revealValues = flagBool(flags, 'reveal-values');
+    if (revealValues && flagBool(flags, 'json')) {
+        throw new Error('--reveal-values cannot be combined with --json because structured output is commonly persisted');
+    }
+    if (revealValues && !process.stdout.isTTY) {
+        throw new Error('--reveal-values requires an interactive terminal');
+    }
     const roots = positionals.length ? positionals : ['.'];
     const maxBytes = numberFlag(flags, 'max-bytes') ?? DEFAULT_SCAN_MAX_BYTES;
     const files = await collectFiles(roots, flagBool(flags, 'all'));
@@ -65,16 +73,20 @@ async function runScan({ positionals, flags }) {
         }
     }
     const ok = !findings.some((finding) => finding.severity === 'high' || finding.severity === 'critical');
+    const displayedFindings = revealValues ? findings : findings.map(sanitizeCliFinding);
     if (flagBool(flags, 'json')) {
-        writeJson({ ok, scannedFiles: files.length, findings });
+        writeJson({ ok, scannedFiles: files.length, findings: displayedFindings });
     }
     else {
         console.log(`Scanned ${files.length} file${files.length === 1 ? '' : 's'}.`);
-        if (!findings.length) {
+        if (!displayedFindings.length) {
             console.log('No secrets, PII, or prompt-injection risks found.');
         }
         else {
-            for (const finding of findings) {
+            if (revealValues) {
+                console.error('WARNING: displaying raw sensitive finding values in this interactive terminal.');
+            }
+            for (const finding of displayedFindings) {
                 const value = finding.value ? ` (${truncate(finding.value, 96)})` : '';
                 console.log(`${finding.severity.toUpperCase()} ${finding.type} ${finding.file}: ${finding.message}${value}`);
             }
@@ -249,9 +261,7 @@ async function readRequest(file, flags) {
     };
 }
 function isCompletionRequest(value) {
-    return isRecord(value)
-        && typeof value.model === 'string'
-        && Array.isArray(value.messages);
+    return isRecord(value) && typeof value.model === 'string' && Array.isArray(value.messages);
 }
 async function loadEvalFile(file) {
     const fullPath = path.resolve(file);
@@ -311,6 +321,14 @@ function isUsefulCliFinding(finding) {
     const digits = finding.value?.replace(/\D/g, '') || '';
     return digits.length >= 10;
 }
+function sanitizeCliFinding(finding) {
+    return {
+        ...finding,
+        file: redactSensitiveText(finding.file),
+        message: redactSensitiveText(finding.message),
+        value: finding.value === undefined ? undefined : '[REDACTED]',
+    };
+}
 function parseArgs(args) {
     const positionals = [];
     const flags = {};
@@ -385,10 +403,7 @@ function writeJson(value) {
     console.log(JSON.stringify(value, null, 2));
 }
 function printTable(rows, columns) {
-    const widths = Object.fromEntries(columns.map((column) => [
-        column,
-        Math.max(column.length, ...rows.map((row) => row[column].length)),
-    ]));
+    const widths = Object.fromEntries(columns.map((column) => [column, Math.max(column.length, ...rows.map((row) => row[column].length))]));
     console.log(columns.map((column) => column.padEnd(widths[column])).join('  '));
     console.log(columns.map((column) => '-'.repeat(widths[column])).join('  '));
     for (const row of rows) {
@@ -405,7 +420,7 @@ function printHelp() {
     console.log(`nexus-ai-pro CLI
 
 Usage:
-  nexus scan [paths...] [--json] [--max-bytes 1000000] [--no-fail]
+  nexus scan [paths...] [--json] [--max-bytes 1000000] [--no-fail] [--reveal-values]
   nexus models [--provider openai] [--json]
   nexus eval <eval.json|eval.mjs> [--json]
   nexus optimize [request.json|prompt.txt] [--model gpt-5-mini] [--max-input-tokens 4000] [--densify] [--json]
@@ -413,6 +428,7 @@ Usage:
 Eval files can export { cases, client } or { cases, config }. JSON cases may use "expected", "contains", and "match": "includes" | "exact" | "regex".`);
 }
 main().catch((error) => {
-    console.error(error instanceof Error ? error.message : error);
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(redactSensitiveText(message));
     process.exitCode = 1;
 });

package/dist/connectors/web.d.ts

@@ -1,8 +1,20 @@
 import type { ToolDefinition } from '../types/messages.js';
+export type WebResolvedAddress = string | {
+    address: string;
+    family?: 4 | 6;
+};
 export interface WebConnectorOptions {
     allowedDomains?: string[];
     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;