nexus-ai-pro 1.2.1 → 1.4.0

package/API_STABILITY.md

@@ -26,7 +26,48 @@ Source files, `dist` file paths, examples, test helpers that are not exported, a
 - 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.
+## Module formats
+
+Since 1.2.0 the package ships parallel ESM and CommonJS builds and supports Node.js 22 or newer.
+Both are covered by this policy:
+
+- every export subpath carries `import` and `require` conditions, each resolving to its own build and
+  its own declarations, so a CommonJS consumer never lands on ESM declarations;
+- `typesVersions` maps each subpath to its CommonJS declarations, so subpath types resolve under
+  `moduleResolution: "node10"` without a consumer migrating its `tsconfig.json`;
+- dropping either build, or removing a subpath from either condition, requires a major release.
+
+Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
+one of its explicit subpaths.
+
+## Capability negotiation stage
+
+`negotiateCompletionRequest()`, `NexusCapabilityError`, `CapabilityPolicy`, `CapabilityWarning`, and
+the `nexus-ai-pro/capabilities` subpath are public and follow the 1.x rules.
+
+Which options a given model accepts is registry data, not a compatibility guarantee. A model's
+declared capabilities, cache lifetimes, reasoning effort levels, and prices can change in a minor
+release when a provider changes its lineup, and new normalized warning entries may be added. What is
+guaranteed is the behavior of each policy: `strict` throws before the provider call, `warn` records a
+warning and continues, `off` sends the request unchanged, and an option a model does not mention is
+always passed through rather than refused.
+
+`ResponseMeta.usage` and `ResponseMeta.cost` are public normalized shapes. Reported token counts and
+prices originate with the provider or with bundled defaults and are not compatibility guarantees;
+`cost.basis` distinguishes the two. `ResponseMeta.estimatedCost` is deprecated in favor of
+`cost.amount` and will be removed in the next major release.
+
+## Telephony API stage
+
+The `nexus-ai-pro/telephony`, `telephony/twilio`, and `telephony/realtime-bridge` subpaths are public
+and follow the 1.x rules. This covers `TelephonyManager`, the `TelephonyProvider` contract, the
+normalized call, media-stream, status-callback, and phone-number types, the TwiML helpers, and the
+realtime bridge.
+
+Provider payloads under `raw`, TwiML markup details beyond the documented helper options, webhook
+signature formats, upstream call-status vocabularies, and carrier behavior are controlled by the
+provider and are not normalized guarantees. `TelephonyProvider` methods are optional by design, so a
+provider adapter may implement any subset; adding a new optional method is a minor change.
 
 ## Realtime API stage
 

package/CHANGELOG.md

@@ -4,6 +4,97 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-08-25
+
+Request parity and cost truth: the completion request can now express what current models actually
+do, and the response reports what the call really cost. Every addition is an optional field or a new
+union member, so existing code is unaffected.
+
+### Added
+
+- **Provider prompt caching.** `CompletionRequest.cache` selects `off`, `auto`, or `explicit` mode
+  with a `5m` or `1h` lifetime, and `Message.cache` / `ToolDefinition.cache` mark the end of a
+  cacheable prefix. The Anthropic adapter translates marks into `cache_control` breakpoints,
+  respecting the four-breakpoint limit by keeping the deepest marks, and every adapter reports what
+  the provider actually reused.
+- **Reasoning controls.** `CompletionRequest.reasoning` carries `effort`, `maxTokens`, and `summary`.
+  These map to OpenAI `reasoning_effort` and the Responses `reasoning` field, Anthropic extended
+  thinking with a token budget, and Gemini `thinkingConfig`. A new `'reasoning'` `StreamChunk`
+  variant carries reasoning summaries, kept separate from `'text'` so existing consumers that switch
+  on chunk type see no change.
+- **Tool and sampling controls.** `toolChoice`, `parallelToolCalls`, `seed`, `topK`,
+  `frequencyPenalty`, and `presencePenalty` on `CompletionRequest`, mapped per provider.
+- **Structured usage and numeric cost.** `ResponseMeta.usage` reports input, output, cached-read,
+  cached-write, and reasoning tokens; `ResponseMeta.cost` reports a numeric amount with a currency
+  and an `estimated` or `reported` basis. Cached reads and cache writes are priced at their own
+  rates, with a long-lived write costing more than a short-lived one. `models.cachePricing`
+  overrides the bundled multipliers.
+- **Capability negotiation.** `negotiateCompletionRequest()` reconciles a request against the routed
+  model under a `strict`, `warn`, or `off` policy, set through `capabilities.policy` or per request
+  through `capabilityPolicy`. Refused options are reported on `ResponseMeta.capabilityWarnings` and
+  in `plan()` warnings. An option the registry does not mention is passed through: absence means
+  unknown, not unsupported, so an application-registered model is never restricted by fields it does
+  not declare, and `off` guarantees a newer provider feature is never blocked by stale metadata.
+- **Registry provenance.** Model entries accept `verifiedAt` and `source`; `MODEL_ALIAS_METADATA`
+  reports each alias's stage and whether its target floats between releases. `describeModel()`,
+  `checkRegistryFreshness()`, and `assertRegistryFreshness()` make drift visible instead of silent.
+- **Streamed usage on OpenAI.** `stream_options.include_usage` is requested for OpenAI and Azure, so
+  a streamed response reports real tokens and cost rather than zeros. Other OpenAI-compatible
+  servers opt in with the new `streamUsage` provider option.
+- A `nexus-ai-pro/capabilities` subpath for the negotiation API.
+
+### Fixed
+
+- Claude 5 models were declared as non-reasoning. The registry decided extended-thinking support by
+  looking for a `4` in the family name, which is absent from `claude-sonnet-5.0`, `claude-haiku-5.0`,
+  and `claude-fable-5.0`. Support is now derived from the family version, so every release from 3.7
+  onward is reported correctly, together with the thinking budget each model can accept.
+- The Anthropic adapter priced every completion at a hardcoded $0.003/$0.015 per 1k tokens instead of
+  using the model registry, so cost was wrong for every Claude model except one. All adapters now
+  share one pricing path.
+- Streamed Anthropic and Google responses reported zero tokens and `$0.00`. Both now carry the
+  provider's own usage totals on the final chunk.
+- Google reasoning summaries could be concatenated into visible output. Parts marked `thought` are
+  excluded from content and emitted as `'reasoning'` chunks instead.
+- A chat stream that ended without a finish reason produced no `done` chunk, leaving consumers
+  without terminal metadata.
+
+### Changed
+
+- `ResponseMeta.estimatedCost` is deprecated in favor of the numeric `cost` object. It is still
+  populated and stays until the next major release. The metrics path no longer parses money out of
+  its own display string.
+- `ResponseMeta.tokensInput` keeps its original meaning of every prompt token; the uncached share
+  billed at the standard rate is `usage.inputTokens`. Adapters whose provider folds cached tokens
+  into one prompt total subtract them so no token is priced twice.
+- `resolveModel()` no longer merges the bundled and application registries into a new object on each
+  call. It reads both maps directly, which removes a per-request allocation from the hot path;
+  `getModelRegistry()` and `getModelAliases()` are unchanged as the merged views.
+- Coverage gates raised from 70/60/60 to 82% lines, 67% branches, and 73% functions, with new tests
+  for the agent loop, the rules router, the evaluation metric library, and the Google, Ollama, and
+  Cohere adapters. The gates sit a couple of points below the lowest figure the supported Node
+  versions report, because Node 22 and Node 24 do not count functions identically: the same suite
+  measures 78.7% on Node 22 and 75.9% on Node 24. A gate set from one version alone fails on the
+  other.
+
+### Notes
+
+Image operations keep their existing strict capability behavior. An unsupported image option changes
+the artifact that comes back, so silently dropping one is worse than refusing the request; the
+shared policy vocabulary is in place for a future release that revisits this.
+
+## [1.3.0] - 2026-08-17
+
+### Added
+
+- SMS routing on `updatePhoneNumber`. `UpdatePhoneNumberRequest` now carries `smsUrl`, `smsMethod`,
+  `smsFallbackUrl`, and `smsFallbackMethod`, and the Twilio provider maps them to `SmsUrl`,
+  `SmsMethod`, `SmsFallbackUrl`, and `SmsFallbackMethod`. Only the voice leg could be repointed
+  before, so an application holding SMS-enabled numbers had to drop to the provider SDK to say where
+  inbound messages should be delivered.
+- `TelephonyPhoneNumber` reports the number's current `smsUrl`, `smsMethod`, `smsFallbackUrl`, and
+  `smsFallbackMethod`, so message routing can be verified the same way voice routing already is.
+
 ## [1.2.1] - 2026-08-10
 
 ### Fixed
@@ -110,6 +201,11 @@ 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/v1.0.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.2.1...v1.3.0
+[1.2.1]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.0.0...v1.1.0
 [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

@@ -239,7 +239,112 @@ console.log(plan.fitsContext);
 console.log(plan.warnings);
 ```
 
-`plan()` does not call a provider. It estimates route, token use, context fit, cost, guardrail findings, and warnings.
+`plan()` does not call a provider. It estimates route, token use, context fit, cost, guardrail findings, and warnings, including any option the routed model cannot honor.
+
+### Reasoning
+
+```ts
+const response = await ai.complete({
+  model: 'auto',
+  messages: [{ role: 'user', content: 'Find the bug in this migration plan.' }],
+  reasoning: { effort: 'high', summary: 'auto' },
+});
+
+console.log(response.meta.usage?.reasoningTokens);
+```
+
+`effort` is the portable control. It maps to OpenAI `reasoning_effort` and the Responses `reasoning`
+field, Anthropic extended thinking, and Gemini `thinkingConfig`. Use `reasoning.maxTokens` when you
+want to set a thinking budget directly instead of by level.
+
+Requesting a summary emits `reasoning` stream chunks, which stay separate from visible output:
+
+```ts
+for await (const chunk of ai.stream({ model: 'auto', messages, reasoning: { summary: 'auto' } })) {
+  if (chunk.type === 'reasoning') process.stderr.write(chunk.content ?? '');
+  if (chunk.type === 'text') process.stdout.write(chunk.content ?? '');
+}
+```
+
+### Prompt Caching
+
+Providers charge far less for a prompt prefix they have already processed. `mode: 'auto'` is the
+default and reports whatever the provider reused on its own. `mode: 'explicit'` sends caller-placed
+breakpoints to providers that accept them, such as Anthropic:
+
+```ts
+const response = await ai.complete({
+  model: 'anthropic/best',
+  cache: { mode: 'explicit', ttl: '1h' },
+  messages: [
+    { role: 'system', content: longPolicyDocument, cache: true },
+    { role: 'user', content: 'Does clause 14 apply here?' },
+  ],
+});
+
+console.log(response.meta.usage?.cachedReadTokens);
+console.log(response.meta.cost?.amount);
+```
+
+Mark the end of the stable prefix, not every message. A provider caps how many breakpoints it
+accepts (Anthropic allows four); when there are more marks than slots, the deepest ones are kept,
+because a deeper breakpoint caches strictly more of the prompt.
+
+### Usage and Cost
+
+Every response carries a numeric cost and a full token breakdown:
+
+```ts
+const { usage, cost } = response.meta;
+
+console.log(usage?.inputTokens);        // billed at the standard input rate
+console.log(usage?.cachedReadTokens);   // served from the provider cache
+console.log(usage?.cachedWriteTokens);  // written into the provider cache
+console.log(usage?.reasoningTokens);    // share of output spent on reasoning
+console.log(cost?.amount, cost?.currency, cost?.basis);
+```
+
+`meta.tokensInput` keeps its original meaning of every prompt token, cached or not.
+`meta.estimatedCost` is deprecated in favor of `cost.amount`. Bundled prices are defaults, not
+financial truth; override them with `models.registry`, or adjust cache rates with
+`models.cachePricing`.
+
+### Capability Negotiation
+
+Requests are reconciled against the routed model before the provider is called:
+
+```ts
+const ai = new NexusAI({
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  capabilities: { policy: 'warn' }, // 'strict' | 'warn' (default) | 'off'
+});
+
+const response = await ai.complete({ model: 'auto', messages, seed: 7 });
+console.log(response.meta.capabilityWarnings);
+```
+
+- `strict` throws a `NexusCapabilityError` before spending anything.
+- `warn` drops or clamps the option and records it on `meta.capabilityWarnings`.
+- `off` sends the request exactly as written.
+
+An option a model does not declare is always passed through — absence means the registry does not
+know, not that the provider refuses — so a model you register yourself is never restricted by fields
+it omits. Set `capabilityPolicy: 'off'` on a single request to reach a provider feature that is
+newer than the bundled registry.
+
+Registry provenance is inspectable, and a release check can fail on stale data:
+
+```ts
+import { describeModel, assertRegistryFreshness } from 'nexus-ai-pro';
+
+console.log(describeModel('anthropic/best'));
+// { model: 'claude-opus-4-8', verifiedAt: '…', alias: { stage: 'stable', floating: true }, … }
+
+assertRegistryFreshness({ maxAgeDays: 120 });
+```
+
+A `floating` alias resolves by intent rather than to a pinned model, so its target can change between
+releases. Pin the resolved model when a run has to be reproducible.
 
 ### Streaming
 
@@ -254,7 +359,9 @@ for await (const chunk of stream) {
 }
 ```
 
-All providers normalize streaming chunks to `text`, `tool_call`, `done`, or `error`.
+All providers normalize streaming chunks to `text`, `reasoning`, `tool_call`, `done`, or `error`.
+Reasoning summaries only arrive when the request asks for them, so a consumer that switches on
+`chunk.type` keeps receiving visible output only.
 
 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,
@@ -1022,6 +1129,7 @@ import { NexusAI } from 'nexus-ai-pro/core';
 import { createNexusConfig } from 'nexus-ai-pro/config';
 import { TokenOptimizer } from 'nexus-ai-pro/optimizer';
 import { ContextWindowManager } from 'nexus-ai-pro/context';
+import { negotiateCompletionRequest } from 'nexus-ai-pro/capabilities';
 import { guardrailPolicy } from 'nexus-ai-pro/security';
 import { RedisCacheAdapter } from 'nexus-ai-pro/cache';
 import { DeepSeekProvider } from 'nexus-ai-pro/providers/deepseek';
@@ -1086,10 +1194,12 @@ npm run test:conformance:real
 
 ## Roadmap
 
-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).
+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.
+
+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](./ROADMAP.md).
 
 ## Production Notes