nexus-ai-pro 1.0.0 → 1.2.0

package/API_STABILITY.md

@@ -1,10 +1,13 @@
 # API Stability Policy
 
-This policy describes compatibility guarantees for `nexus-ai-pro` beginning with version 0.9.0.
+This policy describes compatibility guarantees for `nexus-ai-pro`. The 1.x compatibility guarantees
+apply beginning with version 1.0.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 package follows semantic versioning. Within the 1.x line, incompatible changes to stable public
+APIs require a major release. Minor releases may add backward-compatible features, and patch releases
+are intended to remain backward compatible.
 
 The following surfaces are public and covered by this policy:
 
@@ -33,11 +36,12 @@ explicit `realtime/session`, `realtime/tools`, `realtime/conversation`, `realtim
 normalized event names, configuration fields, and conversation/export shapes follow the same patch
 compatibility rules as the rest of the package.
 
-The realtime surface is still pre-1.0. Provider-specific wire events returned by `openai-events`, values
+The realtime surface follows the 1.x compatibility rules for its normalized public API. Provider-specific
+wire events returned by `openai-events`, values
 under `raw`, SDP/ICE behavior, and upstream model or voice availability are controlled by the provider
 and are not normalized compatibility guarantees. New normalized event variants or optional metrics may
-be added in a minor release. A necessary incompatible change during 0.x will be documented in a minor
-release with migration guidance.
+be added in a minor release. Incompatible normalized API changes require a major release unless an urgent
+security fix makes preserving the old behavior unsafe.
 
 Platform interfaces for WebRTC and WebSocket are structural so applications can inject browser, server,
 mobile, or test adapters without a framework dependency. A documented structural member is public;
@@ -48,8 +52,22 @@ turn-oriented transcription/completion/speech workflow. `RealtimeSession` owns a
 live events, interruption, and normalized realtime conversation state. Neither is a compatibility alias
 for the other.
 
+## Image API stage
+
+The `nexus-ai-pro/images` family is experimental in production-readiness, but published normalized
+types, manager methods, operation events, and explicit subpath exports still follow the 1.x semantic
+versioning rules. The experimental label does not permit an incompatible minor or patch release.
+
+Provider payloads under `raw`, provider-specific error metadata, temporary delivery URLs, upstream model
+availability, and generative output are not normalized compatibility guarantees. The current local
+operation handle is process-bound and does not promise durable recovery, distributed cancellation, or
+exactly-once provider execution. Those capabilities will use additive adapters and contracts when added.
+`MemoryAssetStore` is likewise process-local and does not promise cross-process durability or shared
+tenant state.
+
 ## 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.
+Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals
+are 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

@@ -1,9 +1,52 @@
 # 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.
+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.
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-08-10
+
+### Added
+
+- A `telephony/realtime-bridge` subpath joining a provider media stream to a realtime session:
+  inbound-only caller audio forwarding, outbound audio framing in emission order, barge-in that clears
+  provider-queued audio before cancelling the response, playback marks that resolve
+  `markAudioPlayed()`, stream lifecycle, and custom stream parameters for tenant routing.
+- `twilioRealtimeAudioOptions()` pinning both directions to 8 kHz G.711 mu-law so telephony audio
+  reaches the model without transcoding.
+- Call control and usage metering on `TelephonyProvider` and the Twilio adapter: `getCall`, `endCall`,
+  and `parseStatusCallback`, surfaced on `NexusAI` as `getCall`, `endCall`, and
+  `parseTelephonyStatusCallback`. Status callbacks carry the authoritative billable call duration.
+- Phone-number management on `TelephonyProvider` and the Twilio adapter: `listPhoneNumbers` and
+  `updatePhoneNumber`, so an app can point a number at its own voice webhook and status callback.
+
+### Changed
+
+- The package now ships parallel ESM and CommonJS builds. Every export subpath gained a `require`
+  condition, so NestJS and other `"module": "commonjs"` consumers can load it without a dynamic-import
+  shim. Types stay shared between both builds, and the packed-size guards were raised to account for the
+  duplicated JS payload.
+
+## [1.1.0] - 2026-07-28
+
+### Added
+
+- An experimental provider-neutral image operation family with portable asset locations,
+  `ImageManager`, generation/editing, strict capability negotiation, runtime provider registration,
+  visual-safety hooks, and cancellable local operation handles.
+- Opt-in `images`, `images/assets`, `images/mock`, and `images/openai` subpaths with a deterministic
+  mock provider and an OpenAI Image API adapter for one-shot generation and reference-based editing.
+- An image-provider conformance harness covering normalized assets, metadata, generation, editing, and
+  pre-aborted calls.
+- A bounded tenant-isolated `MemoryAssetStore` with retention, defensive byte copies, computed SHA-256
+  checksums, capacity enforcement, and optional HTTP(S) signing.
+
+### Changed
+
+- Reconciled the changelog and API stability policy with the tagged 1.0.0 release.
+
+## [1.0.0] - 2026-07-17
+
 ### Added
 
 - An opt-in realtime package family with `realtime`, `realtime/session`, `realtime/tools`,
@@ -55,5 +98,6 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 - 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
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/releases/tag/v1.0.0
 [0.9.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/releases/tag/v0.9.0

package/README.md

@@ -7,7 +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)
+- Image generation status and remaining infrastructure work: [ROADMAP.md](./ROADMAP.md)
 
 ## Install
 
@@ -15,7 +15,9 @@ 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()`.
+Requires Node.js 22 or newer. The package is authored as ESM and ships both an ESM and a CommonJS build,
+so `import` and `require()` both work — including from NestJS and other apps compiled with
+`"module": "commonjs"`. Types are shared between both builds.
 The main Nexus pipeline is Node-oriented; the isolated realtime subpaths use portable structural
 interfaces and can be bundled for modern browsers.
 
@@ -307,6 +309,63 @@ const response = await ai.completeVerified(
 );
 ```
 
+## Image Generation and Editing (Experimental)
+
+Image operations use a separate provider-neutral manager because generated assets have different
+capabilities, delivery modes, safety checks, and lifecycles from text completions.
+
+```ts
+import { NexusAI } from 'nexus-ai-pro';
+import { OpenAIImageProvider } from 'nexus-ai-pro/images/openai';
+
+const openaiImages = new OpenAIImageProvider({
+  apiKey: process.env.OPENAI_API_KEY!,
+});
+
+const mediaAi = new NexusAI({
+  providers: {},
+  images: {
+    defaultProvider: 'openai',
+    providers: { openai: openaiImages },
+  },
+});
+
+const image = await mediaAi.images.generate({
+  model: 'auto',
+  prompt: 'A clean product photograph of a red mechanical keyboard',
+  dimensions: { width: 1536, height: 1024 },
+  quality: 'high',
+  delivery: { kind: 'bytes', format: 'png' },
+});
+
+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.
+
+Use `submit()` for a cancellable local operation handle with replayable lifecycle events:
+
+```ts
+const operation = mediaAi.images.submit('generate', {
+  prompt: 'A minimal blue geometric poster',
+  delivery: { kind: 'bytes', format: 'png' },
+});
+
+for await (const event of operation.events()) {
+  console.log(event.type);
+}
+```
+
+For deterministic tests, register `MockImageProvider` from `nexus-ai-pro/images/mock`. The current
+`submit()` handle is in-process; durable leases, recovery, distributed deduplication, and webhooks remain
+future infrastructure work. `nexus-ai-pro/images/assets` includes a bounded, tenant-isolated
+`MemoryAssetStore` for local development and single-process workloads; it computes SHA-256 checksums,
+copies bytes at its boundaries, enforces retention and capacity, and never silently evicts live assets.
+
 ## Voice Integrations
 
 Voice support is optional and split into small imports.
@@ -734,6 +793,80 @@ const call = await ai.createCall({
 
 For smaller apps, skip Twilio entirely and register your own `TelephonyProvider`.
 
+### Phone Agents: Bridging a Call to a Realtime Session
+
+A phone agent needs the telephony media stream and a realtime session joined together. The bridge owns
+that audio path — caller audio in, assistant audio out, barge-in, playback marks, and stream lifecycle —
+while session configuration, tools, and authorization stay in application code.
+
+```ts
+import { createTelephonyRealtimeBridge, twilioRealtimeAudioOptions } from 'nexus-ai-pro/telephony/realtime-bridge';
+import { OpenAIWebSocketTransport } from 'nexus-ai-pro/realtime/openai-websocket';
+import { createRealtimeSession } from 'nexus-ai-pro/realtime/session';
+
+// One socket per call, from your WebSocket server.
+function handleCallSocket(socket: AppWebSocket) {
+  const session = createRealtimeSession({
+    provider: 'openai',
+    model: 'gpt-realtime',
+    transport: new OpenAIWebSocketTransport({ apiKey: process.env.OPENAI_API_KEY!, webSocketFactory }),
+    modalities: ['audio'],
+    instructions: 'You are a scheduling assistant.',
+    tools: [checkAvailability, createBooking],
+    // Telephony audio is 8 kHz G.711 mu-law; this passes it through untranscoded.
+    audio: twilioRealtimeAudioOptions({ output: { voice: 'alloy' } }),
+  });
+
+  const bridge = createTelephonyRealtimeBridge({
+    session,
+    telephony,
+    send: (message) => socket.send(message.body),
+    onStart: (event) => logger.info(`call ${event.callId} started for ${event.parameters?.tenant}`),
+    onStop: () => persistTranscript(session.export('json')),
+    onError: (error) => logger.error(error),
+  });
+
+  socket.on('message', (raw) => bridge.handleMessage(String(raw)));
+  socket.on('close', () => bridge.close());
+}
+```
+
+The bridge feeds only inbound caller audio to the model, so an echoed outbound track never loops back.
+On caller speech it clears audio already queued at the provider and cancels the in-flight response, which
+is what stops the assistant talking over an interruption. Custom `<Parameter>` values from the stream
+instruction are exposed as `bridge.parameters` for tenant and worker routing.
+
+Pass `bargeIn: false` to keep queued audio playing, `autoConnect: false` to connect the session yourself,
+and `await bridge.flush()` when you need outstanding sends to settle.
+
+### Call Control and Usage Metering
+
+Meter billable time from the provider's own record rather than from stream lifecycle events, which do not
+account for ring time or provider-side teardown:
+
+```ts
+// From your status webhook.
+const status = ai.parseTelephonyStatusCallback('twilio', requestBody);
+if (status?.status === 'completed') {
+  await usage.recordCallMinutes({ callId: status.callId, seconds: status.durationSeconds ?? 0 });
+}
+
+// Or read it directly, and hang up from a tool.
+const details = await ai.getCall({ callId });
+await ai.endCall({ callId });
+```
+
+### Pointing a Number at Your Webhook
+
+```ts
+const [number] = await ai.listPhoneNumbers({ phoneNumber: '+15557650000' });
+await ai.updatePhoneNumber({
+  id: number.id,
+  voiceUrl: 'https://api.example.com/voice/incoming',
+  statusCallbackUrl: 'https://api.example.com/voice/status',
+});
+```
+
 ## Security
 
 Security is enabled by default with `standard` mode.
@@ -892,11 +1025,18 @@ import { ContextWindowManager } from 'nexus-ai-pro/context';
 import { guardrailPolicy } from 'nexus-ai-pro/security';
 import { RedisCacheAdapter } from 'nexus-ai-pro/cache';
 import { DeepSeekProvider } from 'nexus-ai-pro/providers/deepseek';
+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 { createRealtimeSession } from 'nexus-ai-pro/realtime/session';
 import { OpenAIWebRTCTransport } from 'nexus-ai-pro/realtime/openai-webrtc';
+import { TelephonyManager } from 'nexus-ai-pro/telephony';
+import { TwilioTelephonyProvider } from 'nexus-ai-pro/telephony/twilio';
+import { createTelephonyRealtimeBridge } from 'nexus-ai-pro/telephony/realtime-bridge';
 ```
 
-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.
+Provider SDKs are optional peer dependencies. The package ships ESM and CommonJS builds, 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`, `dist-cjs`, or `src` are unsupported.
 
 ## Examples
 
@@ -946,10 +1086,10 @@ 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).
+The experimental image foundation now includes portable asset types, `ImageManager`, provider
+capability negotiation, local operation handles, visual-safety hooks, deterministic conformance, and an
+opt-in OpenAI adapter. Durable operations, production asset storage, additional providers, and
+media-specific evaluations remain planned in [ROADMAP.md](./ROADMAP.md).
 
 ## Production Notes
 

package/ROADMAP.md

@@ -36,7 +36,23 @@ Current limitations are intentional and should remain visible:
 - Realtime video tracks, SIP transports, durable cost accounting beyond the configurable local estimate,
   and a published latency benchmark methodology remain follow-on work.
 
-## Recommended next release: first-class image generation
+## Current next-release work: first-class image generation
+
+The experimental foundation is now implemented in the current development line:
+
+- portable byte, URL, and stored asset locations plus image request/result, usage, safety, provenance,
+  provider-call context, and operation-handle types;
+- a provider-neutral `ImageManager` with generation, editing, provider registration, strict capability
+  negotiation, visual-safety hooks, and cancellable in-process submissions;
+- a deterministic network-free mock and a parallel image-provider conformance harness;
+- an opt-in OpenAI Image API adapter for one-shot generation and reference-based editing;
+- a bounded tenant-aware in-memory asset store with retention, defensive byte copies, computed SHA-256
+  checksums, capacity rejection, and optional signed-URL integration.
+
+This surface remains experimental. OpenAI masks are intentionally disabled until a transformer can
+verify dimensions and convert neutral mask polarity into provider alpha semantics. Durable operations,
+filesystem/S3-compatible asset stores, a second cloud provider, ComfyUI, and media evaluation are still
+required before promotion.
 
 Image generation should be a separate operation family rather than another variation of
 `complete()`. Text completions and generated assets have different request shapes, response

package/dist/core/config-builder.d.ts

@@ -1,6 +1,7 @@
 import { NexusAI } from './nexus.js';
 import type { AnthropicProviderConfig, AuditLogConfig, AzureOpenAIProviderConfig, CacheConfig, CohereProviderConfig, CostBudgetConfig, CustomProviderConfig, DeepSeekProviderConfig, GoogleProviderConfig, GroqProviderConfig, LMStudioProviderConfig, LlamaCppProviderConfig, LoggerConfig, MistralProviderConfig, NexusAIConfig, OllamaProviderConfig, OpenAIProviderConfig, OpenRouterProviderConfig, ProvidersConfig, RateLimitConfig, ResponseFormatConfig, RetryConfig, RoutingConfig, RoutingStrategy } from '../types/config.js';
 import type { ContextWindowConfig } from '../types/context-window.js';
+import type { ImageConfig } from '../types/images.js';
 import type { SecurityConfig, SecurityLevel } from '../types/security.js';
 import type { TokenOptimizerConfig } from '../types/optimizer.js';
 import type { PipelineConfig } from '../pipeline/types.js';
@@ -53,6 +54,8 @@ export declare class NexusConfigBuilder {
     security(config: SecurityLevel | SecurityConfig): this;
     /** Sets context-window compaction behavior. */
     contextWindow(config: ContextWindowConfig): this;
+    /** Sets image-provider defaults and registrations. */
+    images(config: ImageConfig): this;
     /** Sets token optimization behavior. */
     tokenOptimizer(config: TokenOptimizerConfig): this;
     /** Sets exact, semantic, or hybrid cache behavior. */

package/dist/core/config-builder.js

@@ -98,6 +98,11 @@ export class NexusConfigBuilder {
         this.config.contextWindow = config;
         return this;
     }
+    /** Sets image-provider defaults and registrations. */
+    images(config) {
+        this.config.images = config;
+        return this;
+    }
     /** Sets token optimization behavior. */
     tokenOptimizer(config) {
         this.config.tokenOptimizer = config;

package/dist/core/nexus.d.ts

@@ -4,10 +4,12 @@ import type { NexusPlan } from '../types/planning.js';
 import type { NexusResponse, NexusStream } from '../types/response.js';
 import type { AgentConfig, AgentResult } from '../types/agent.js';
 import type { SpeechRequest, SpeechResponse, TranscriptionRequest, TranscriptionResponse, VoiceProvider, VoiceSessionConfig, VoiceTurnRequest, VoiceTurnResponse } from '../types/voice.js';
-import type { CreateCallRequest, CreateCallResponse, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyProvider, TelephonyResponseRequest, TelephonyWebhookResponse, TelephonyWebhookValidationRequest } from '../types/telephony.js';
+import type { ImageProvider } from '../types/images.js';
+import type { CreateCallRequest, CreateCallResponse, EndCallRequest, GetCallRequest, ListPhoneNumbersRequest, TelephonyCallDetails, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyPhoneNumber, TelephonyProvider, TelephonyResponseRequest, TelephonyStatusCallback, TelephonyWebhookResponse, TelephonyWebhookValidationRequest, UpdatePhoneNumberRequest } from '../types/telephony.js';
 import type { PipelineStep } from '../pipeline/types.js';
 import type { BaseProvider } from '../providers/base.js';
 import { type VoiceSession } from '../voice/index.js';
+import { ImageManager } from '../images/manager.js';
 import { type VerificationOptions } from '../hallucination/verification.js';
 import { type SelfConsistencyOptions } from '../hallucination/consistency.js';
 import { type BatchOptions, type BatchItemResult } from '../jobs/batch.js';
@@ -20,6 +22,8 @@ import { type SummarizeVerifyFormatOptions, type WorkflowResult } from '../workf
  * Use `new NexusAI(config)` when you want full control, or `createNexus()` for the beginner shorthand.
  */
 export declare class NexusAI {
+    /** Provider-neutral image generation and editing operations. */
+    readonly images: ImageManager;
     private config;
     private providers;
     private router;
@@ -104,6 +108,27 @@ export declare class NexusAI {
         event?: 'media' | 'mark' | 'clear';
         markName?: string;
     }): TelephonyOutboundAudioMessage;
+    /**
+     * Reads a call's current provider-side state, including the duration usage metering bills on.
+     */
+    getCall(request: GetCallRequest): Promise<TelephonyCallDetails>;
+    /**
+     * Hangs up a live call through the provider's call-control API.
+     */
+    endCall(request: EndCallRequest): Promise<TelephonyCallDetails>;
+    /**
+     * Parses a provider status webhook into a normalized record. Prefer this over media-stream
+     * lifecycle events when metering usage.
+     */
+    parseTelephonyStatusCallback(providerName: string, body: string | URLSearchParams | Record<string, string | number | boolean | undefined>): TelephonyStatusCallback | undefined;
+    /**
+     * Lists phone numbers owned by the provider account.
+     */
+    listPhoneNumbers(request?: ListPhoneNumbersRequest): Promise<TelephonyPhoneNumber[]>;
+    /**
+     * Points a phone number at a voice webhook and/or status callback.
+     */
+    updatePhoneNumber(request: UpdatePhoneNumberRequest): Promise<TelephonyPhoneNumber>;
     /**
      * Registers a custom text provider at runtime.
      */
@@ -112,18 +137,24 @@ export declare class NexusAI {
      * Registers a custom voice provider at runtime.
      */
     registerVoiceProvider(name: string, provider: VoiceProvider): this;
+    /**
+     * Registers a custom image provider at runtime.
+     */
+    registerImageProvider(name: string, provider: ImageProvider): this;
     /**
      * Registers a custom telephony provider at runtime.
      */
     registerTelephonyProvider(name: string, provider: TelephonyProvider): this;
     hasProvider(name: string): boolean;
     hasVoiceProvider(name: string): boolean;
+    hasImageProvider(name: string): boolean;
     hasTelephonyProvider(name: string): boolean;
     /**
      * Lists configured text providers.
      */
     listProviders(): string[];
     listVoiceProviders(): string[];
+    listImageProviders(): string[];
     listTelephonyProviders(): string[];
     /**
      * Adds a custom pipeline step.

package/dist/core/nexus.js

@@ -15,6 +15,7 @@ import { Logger } from '../utils/logger.js';
 import { SecurityPipeline } from '../security/index.js';
 import { ContextWindowManager } from '../context/index.js';
 import { VoiceManager } from '../voice/index.js';
+import { ImageManager } from '../images/manager.js';
 import { TelephonyManager } from '../telephony/index.js';
 import { TokenOptimizer } from '../optimizer/index.js';
 import { AgentLoop } from '../agent/loop.js';
@@ -41,6 +42,8 @@ import { summarizeVerifyFormat } from '../workflow/chains.js';
  * Use `new NexusAI(config)` when you want full control, or `createNexus()` for the beginner shorthand.
  */
 export class NexusAI {
+    /** Provider-neutral image generation and editing operations. */
+    images;
     config;
     providers = new Map();
     router = new Router();
@@ -73,6 +76,7 @@ export class NexusAI {
         this.security = new SecurityPipeline(this.config.security || 'standard');
         this.contextWindow = new ContextWindowManager(this.config.contextWindow || {});
         this.voiceManager = new VoiceManager(this.config.voice || {});
+        this.images = new ImageManager(this.config.images || {});
         this.telephonyManager = new TelephonyManager(this.config.telephony || {});
         this.optimizer = new TokenOptimizer(this.config.tokenOptimizer || {});
         this.cache = new MemoryCache(this.config.cache?.maxEntries || 500);
@@ -439,6 +443,37 @@ export class NexusAI {
     formatTelephonyAudioMessage(providerName, streamId, payload, options) {
         return this.telephonyManager.formatAudioMessage(providerName, streamId, payload, options);
     }
+    /**
+     * Reads a call's current provider-side state, including the duration usage metering bills on.
+     */
+    async getCall(request) {
+        return this.telephonyManager.getCall(request);
+    }
+    /**
+     * Hangs up a live call through the provider's call-control API.
+     */
+    async endCall(request) {
+        return this.telephonyManager.endCall(request);
+    }
+    /**
+     * Parses a provider status webhook into a normalized record. Prefer this over media-stream
+     * lifecycle events when metering usage.
+     */
+    parseTelephonyStatusCallback(providerName, body) {
+        return this.telephonyManager.parseStatusCallback(providerName, body);
+    }
+    /**
+     * Lists phone numbers owned by the provider account.
+     */
+    async listPhoneNumbers(request) {
+        return this.telephonyManager.listPhoneNumbers(request);
+    }
+    /**
+     * Points a phone number at a voice webhook and/or status callback.
+     */
+    async updatePhoneNumber(request) {
+        return this.telephonyManager.updatePhoneNumber(request);
+    }
     /**
      * Registers a custom text provider at runtime.
      */
@@ -453,6 +488,13 @@ export class NexusAI {
         this.voiceManager.registerProvider(name, provider);
         return this;
     }
+    /**
+     * Registers a custom image provider at runtime.
+     */
+    registerImageProvider(name, provider) {
+        this.images.registerImageProvider(name, provider);
+        return this;
+    }
     /**
      * Registers a custom telephony provider at runtime.
      */
@@ -466,6 +508,9 @@ export class NexusAI {
     hasVoiceProvider(name) {
         return this.voiceManager.hasProvider(name);
     }
+    hasImageProvider(name) {
+        return this.images.hasImageProvider(name);
+    }
     hasTelephonyProvider(name) {
         return this.telephonyManager.hasProvider(name);
     }
@@ -478,6 +523,9 @@ export class NexusAI {
     listVoiceProviders() {
         return this.voiceManager.listProviders();
     }
+    listImageProviders() {
+        return this.images.listImageProviders();
+    }
     listTelephonyProviders() {
         return this.telephonyManager.listProviders();
     }

package/dist/images/assets.d.ts

@@ -0,0 +1,115 @@
+import type { AssetBytesLocation, AssetDescriptor, AssetInput, AssetProvenance } from '../types/images.js';
+/** An asset input whose payload is already available locally as bytes. */
+export interface ByteAssetInput extends Omit<AssetInput, 'location'> {
+    location: AssetBytesLocation;
+}
+/** A retrieved asset descriptor whose byte payload is available to the caller. */
+export interface ByteAssetDescriptor extends Omit<AssetDescriptor, 'location'> {
+    location: AssetBytesLocation;
+}
+export interface AssetPutOptions {
+    /** Tenant that owns the asset. This value is required for every later access. */
+    tenantId: string;
+    provenance: AssetProvenance;
+    width?: number;
+    height?: number;
+    /** Relative retention period. Mutually exclusive with `expiresAt`. */
+    ttlSeconds?: number;
+    /** Absolute retention deadline. Mutually exclusive with `ttlSeconds`. */
+    expiresAt?: Date | string;
+}
+export interface AssetStat {
+    assetId: string;
+    tenantId: string;
+    /** Metadata-only descriptor. Its location points back to this store, not to the byte payload. */
+    descriptor: AssetDescriptor;
+    createdAt: string;
+    expiresAt?: string;
+}
+export interface AssetSignOptions {
+    /** Requested signed-URL lifetime. Enforcement is delegated to the configured signer. */
+    expiresInSeconds?: number;
+}
+export interface AssetSignerContext extends AssetStat {
+    now: string;
+    expiresInSeconds?: number;
+}
+export type AssetSigner = (context: AssetSignerContext) => string | URL | Promise<string | URL>;
+export type AssetStoreResult<T> = T | Promise<T>;
+/**
+ * Provider-neutral asset persistence contract.
+ *
+ * A store must treat a missing asset and an asset owned by another tenant identically. Implementations
+ * may complete synchronously or asynchronously so the same contract can cover memory and remote stores.
+ */
+export interface AssetStore {
+    put(input: ByteAssetInput, options: AssetPutOptions): AssetStoreResult<AssetStat>;
+    get(assetId: string, tenantId: string): AssetStoreResult<ByteAssetDescriptor | undefined>;
+    stat(assetId: string, tenantId: string): AssetStoreResult<AssetStat | undefined>;
+    delete(assetId: string, tenantId: string): AssetStoreResult<true | undefined>;
+    sign(assetId: string, tenantId: string, options?: AssetSignOptions): AssetStoreResult<string | undefined>;
+    purgeExpired(): AssetStoreResult<number>;
+}
+export interface MemoryAssetStoreOptions {
+    maxEntries?: number;
+    maxTotalBytes?: number;
+    maxAssetBytes?: number;
+    defaultTtlSeconds?: number;
+    createAssetId?: () => string;
+    now?: () => Date;
+    signer?: AssetSigner;
+}
+export interface MemoryAssetStoreSnapshot {
+    entries: number;
+    totalBytes: number;
+    maxEntries: number;
+    maxTotalBytes: number;
+    maxAssetBytes: number;
+}
+export declare class AssetStoreError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: string, cause?: unknown | undefined);
+}
+export declare class AssetStoreValidationError extends AssetStoreError {
+    constructor(message: string, cause?: unknown);
+}
+export type AssetCapacityConstraint = 'maxEntries' | 'maxTotalBytes' | 'maxAssetBytes';
+export declare class AssetStoreCapacityError extends AssetStoreError {
+    readonly constraint: AssetCapacityConstraint;
+    readonly maximum: number;
+    readonly current: number;
+    readonly requested: number;
+    constructor(constraint: AssetCapacityConstraint, maximum: number, current: number, requested: number);
+}
+export declare class AssetStoreSigningError extends AssetStoreError {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Process-local, bounded asset storage. Capacity exhaustion rejects the write; live entries are never
+ * silently evicted. Expired entries are purged before capacity and access decisions.
+ */
+export declare class MemoryAssetStore implements AssetStore {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly maxTotalBytes;
+    private readonly maxAssetBytes;
+    private readonly defaultTtlSeconds?;
+    private readonly createAssetId;
+    private readonly clock;
+    private readonly signer?;
+    private totalBytes;
+    constructor(options?: MemoryAssetStoreOptions);
+    put(input: ByteAssetInput, options: AssetPutOptions): AssetStat;
+    get(assetId: string, tenantId: string): ByteAssetDescriptor | undefined;
+    stat(assetId: string, tenantId: string): AssetStat | undefined;
+    delete(assetId: string, tenantId: string): true | undefined;
+    sign(assetId: string, tenantId: string, options?: AssetSignOptions): Promise<string | undefined>;
+    purgeExpired(): number;
+    snapshot(): MemoryAssetStoreSnapshot;
+    private assertCapacity;
+    private ownedEntry;
+    private purgeExpiredAt;
+    private removeEntry;
+    private nowMs;
+}