TypeScript SDK Changelog
Release notes for the Solwyn TypeScript SDK, from the 0.1.0-rc.1 candidate through the current 0.4.0 release.
All notable public changes to @solwyn/sdk are documented here. The package follows Semantic
Versioning. During 0.x, breaking changes are called out here and in the
corresponding release notes before users upgrade.
0.4.0 — Current release
Status: published to npm on 2026-11-05 as the latest release.
API keys are account keys scoped to projects, and every request names its project. Breaking:
old sk_proj_ keys and SOLWYN_PROJECT_ID no longer work. This release needs a Solwyn API that
supports scoped keys.
Breaking
- New key format. API keys are
solwyn_sk_followed by 64 lowercase hex characters. An oldsk_proj_key fails at construction withConfigurationError(field: "api_key"). - A project is required. Pass
project(a project name or itsproj_id) or setSOLWYN_PROJECT, onnew Solwyn(...),createSolwynMiddleware(...)andnew BudgetEnforcer(...). The option wins over the environment. Without one, construction fails withConfigurationError(field: "project").SOLWYN_PROJECT_IDis not read; when it is set, the error says to rename it. PassingprojectIdfails withConfigurationError(field: "project_id"). - Every control-plane request sends
Solwyn-Project. The SDK sends the configured value until it validates, then the pinnedproj_id, so renaming the project does not break a running app. - Read-only keys are refused. A read-only key fails validation and blocks every wrapped call
with
ApiKeyRefusedError; it no longer logs a diagnostic and carries on. - Testing double.
FakeControlPlanerequires the key andSolwyn-Projecton every request and servesGET /api/v1/auth/key. ItsapiKeyis asolwyn_sk_key,projectIdmust be aproj_id, andprojectis a reservedwrap()option. Every contract probe takesprojectin its options.
Added
validate()on the wrapped client and on the AI SDK middleware handle checks the key and project now. It resolves with the key's details, resolvesnullwhen Solwyn cannot be reached, and throwsApiKeyRefusedErroron any refusal. Without it, the first call that needs Solwyn validates lazily; construction makes no network request.ApiKeyRefusedError, aConfigurationErrorwithcodeandfield, for every refusal of the key or the project.- Refusals never fall back to
failOpen. Every401from Solwyn is a refusal. A stored refusal is checked before cached allows, held leases, the control-plane breaker and the outage posture. An expired or revoked key on a project with no hard limits lets calls run unmetered (loggingsolwyn.api_key_refusedat error on each call), but only after the client has validated once; every other refusal blocks. While a refusal is stored, the SDK sends Solwyn nothing except the key check.
0.3.1
Status: published to npm on 2026-11-03.
Patch release with hard_deny fixes: hard_deny now also covers failover hops and
decisions.create.
Fixed
- hard_deny now also covers failover hops. When a call admitted by a hard_deny per-call check is
about to fail over to a different provider or model, Solwyn first runs a new check for that hop at
its own model, output bound and cap. A hop that does not fit fails with
BudgetExceededErrorand is never called. Every attempt after a possibly billed one gets its own check. - hard_deny records unmeasured, possibly billed calls at their reserved amount, marked estimated, for streams closed, cancelled or stopped before the provider's final usage and for failures after the request was sent (unless the provider rejected the call or the request provably never left). Lasting records need Solwyn API support that is live from 2026-11-02.
- hard_deny now covers
decisions.create. It takes no output cap, so on a hard_deny project it fails before it is sent withOutputBoundUnenforceableError(reason: "no_output_cap"). On an alert-only project it runs as an untracked surface. - The allow cache never answers a hard_deny check, a local refusal leaves no hold, lease coverage matches (provider, model) pairs, and a response body that fails to decode counts as a possibly completed call.
0.3.0
Status: published to npm on 2026-10-31.
This minor release makes hard_deny bound a call's output. Before it, a per-call budget check
priced output as equal to input, so one call with a large output cap could spend far past the
remaining budget before later calls were refused. It needs a Solwyn Cloud API that accepts
estimated_output_bound on the budget check, which Solwyn Cloud does. An older API rejects every
per-call check, and the SDK then applies its outage posture (failOpen). On hard-deny admissions,
uncapped requests now carry an output cap; review Changed before upgrading. See
what hard_deny bounds.
Added
- Output bound on the per-call budget check. Every text check (chat, Responses, messages,
Google, Bedrock Converse, and the AI SDK middleware) sends
estimated_output_bound, the most output tokens the call can produce. Solwyn Cloud reserves input cost plus that bound at the model's output rate, so hard-deny refuses a call before dispatch when its bound does not fit the remaining budget, and alert-only reservations get more accurate. The bound is the per-candidate cap (a positive caller ordefaultParamscap, orleaseOutputBoundDefault, default4096) times the candidate count (OpenAIn, GooglecandidateCount), plus Qwen'sthinking_budgetper candidate, and the largest across failover hops. A bound above 100,000,000 is sent as 100,000,000. Media checks do not send it. OutputBoundUnenforceableError. On hard-deny admissions, a call that could produce more output than its bound, and that the SDK cannot cap, fails (normally before it reaches the provider) withcode: "output_bound_unenforceable", areason(malformed_cap_container,malformed_candidate_count,reasoning_without_budget,unsupported_override,azure_api_version,bound_exceeded, ormulti_generation_loop), and ahintsaying what to change. Lease reservations are released; a per-call Cloud reservation stays held until it expires. See typed errors.BudgetCheckResult.hardDenyAdmitted. Results report whether hard-deny authority admitted the call.
Changed
- Uncapped calls on hard-deny admissions get an output cap. When a hard-deny check allows a text
call, or the call draws on a lease with a hard-deny posture, a request with no positive output
cap is sent with
leaseOutputBoundDefault(default4096, configurable) as its per-candidate cap. Set your own cap to choose a different limit. The cap goes in the dialect's own field:max_tokens, ormax_completion_tokensfor OpenAI o-series and GPT-5 models and for every Azure OpenAI deployment, Responsesmax_output_tokens, Anthropicmax_tokens, Googleconfig.maxOutputTokens, BedrockinferenceConfig.maxTokens, and AI SDKmaxOutputTokens. A zero, negative, non-integer, or null cap is replaced. A positive cap is never changed. - Refusals on hard-deny admissions. A call fails with
OutputBoundUnenforceableErrorwhen Qwen thinking has no positivethinking_budget, when the model is an xAI reasoning model, when a candidate count or settings container is malformed, when a body extension carries a key Solwyn cannot count in the bound (includingmodel), when an AI SDK call sets areasoningeffort outside OpenAI or Azure OpenAI, when an uncapped Azure call uses an api-version older than 2024-09-01, when the final request can still exceed its bound, or when the provider SDK would generate more than once (Google automatic continuation or function calling, Anthropicfallbacks). Unset Google loops are turned off for the call. Nothing changes for calls admitted in alert-only mode (the check's effective mode, which is hard-deny when a hard-deny scoped rule or per-run cap applies, even on an alert-only project), and SDK-local outage decisions never add a cap. A refusal normally comes before dispatch and returns lease reservations; a per-call Cloud reservation stays held until it expires. The Google backstop can refuse after a first generation already succeeded, so that call reports a possibly-succeeded error and keeps its reservation at the bound. - Azure OpenAI caps keep their key. A deployment name no longer selects the cap parameter, and
an explicit
max_completion_tokensis never rewritten tomax_tokens. When defaults and the call set different cap keys, the call's key wins. - Allow cache. A cached allow is reused only for a check with the same output bound, so an allow for a small bound never admits a larger one.
- Provider detection. Alibaba's Hong Kong, Coding Plan, and Model Studio hosts
(
*.dashscope.aliyuncs.com,*.maas.aliyuncs.com) are detected as Qwen, and xAI regional hosts (*.api.x.ai) as xAI. On hard-deny admissions, a detected provider with no reasoning rule of its own applies the Qwen rule toqwen*andqwq*models and the xAI rule togrok*models, after any vendor prefix. An explicit provider setting opts out.
Known limitations
- The release notes list a scoped hard-deny rule on an alert-only project as invisible in the
check's
mode. Solwyn Cloud now reports the effective mode on the check,hard_denywhenever an enforcing cap applies, so the SDK caps those calls too. See effective mode. - A Qwen model that thinks even with
enable_thinking: falseis bounded without its reasoning. - DeepSeek, Groq, Mistral, Z.ai, Perplexity, and Fireworks are treated as counting reasoning inside the cap; their docs do not say so explicitly.
- The bound limits output tokens, not dollars. The reservation prices the primary model with a length-based input estimate, so a call that fails over to a more expensive model, or whose input was underestimated, can settle above what it reserved.
0.2.0
Status: published to npm on 2026-10-21.
This minor release adds content-free attribution for LangChain.js / LangGraph.js and OpenAI Agents
JS, plus OpenTelemetry trace correlation on metadata events. The new optional peers can cause npm
ERESOLVE in applications that already pin out-of-range framework versions, and coverage
fingerprints for several providers change; review Changed before upgrading. The new framework
entries and trace correlation read no prompt or response content.
Added
- OpenAI Agents JS attribution. The
@solwyn/sdk/openai-agentsentry adds content-free workflow and stable per-agent run scopes for the Node.js 22+ Chat Completions and Responses HTTP recipe. Function-tool turns, handoffs, and hand-backs reuse the correct agent identity; the wrapped client alone owns enforcement and settlement. Nested agent-as-tool calls, unexpected models, missing hierarchy, and concurrent attempts fail closed with typed errors. Tool-code and guardrail denials and stops surface the original Solwyn error fromrun, streamed iteration, andcompletedwhen Agents preserves it. InvalidOpenAIProvideroptions raiseConfigurationError. See TypeScript SDK OpenAI Agents. - LangChain.js and LangGraph.js attribution. The
@solwyn/sdk/langchainentry supplies a content-free run-scope handler and a guarded Chat Completions leaf for the documented Node.js 22+ OpenAI recipe. Stable graph-node scopes preserve lease reuse, velocity history, and exact-run stops across iterations. Responses and non-streaming JSON-schema parsing are refused. Early stream termination and Node.js 22 abort-and-drain require an invocation-local handler. InvalidnamePrefixvalues are rejected eagerly. See TypeScript SDK LangChain. - OpenTelemetry trace correlation. Metadata events from wrapped clients and the AI SDK
middleware include the caller's active OpenTelemetry
trace_id,span_id, andtrace_sampledwhen the application already has an active span. The values are captured once at call start and carried by every event of the call. Solwyn adds no OpenTelemetry dependency and creates no spans. Disable capture withtraceCorrelation: falseorSOLWYN_TRACE_CORRELATION=false. See TypeScript SDK Privacy.
Changed
- Compatibility: the new optional
@openai/agents >=0.20.0 <1and@langchain/core >=1.2.14 <2peers can cause npmERESOLVEwhen an application already installs an out-of-range version, even when it does not use the integration. Upgrade that dependency or stay on0.1.1. The Agents recipe requiresopenai >=7.2.0 <8andzod4. - Background work no longer joins the caller's trace. Reporter flushes, close-time delivery, lease renewals and surrenders, and untracked-surface advisories run without the active span and baggage of the call that started them. Budget checks and lease grants still run in the caller's context.
- Compatibility: legacy raw-request and client escapes on native OpenAI, Azure
OpenAI, Anthropic, and Together clients, OpenAI Realtime session and client-secret creation and
call acceptance, and Google GenAI Live and
ApiClienttransports now reportunmetered_spendwith explicit scopes instead ofunknown. Bedrock coverage listsInvokeModelWithBidirectionalStreamCommandasblocked, matching its existing runtime refusal. TheonUnmeteredposture is unchanged, and existingacknowledgeUntrackedtokens remain valid. Refresh pinnedcoverage(client).expect(...)fingerprints for OpenAI, Azure, Anthropic, Together, Google GenAI, and Bedrock when upgrading.
Fixed
- Additional Anthropic streaming cache writes are attributed using the served request's TTL when it agrees with the initial usage split. Mixed-TTL requests mark inferred cache-write growth as estimated.
- Settlement after per-call streaming errors. Mid-stream provider errors on streams that used a
per-call budget check now settle the provider-reported usage observed before the error and
include those tokens in the error event, so Cloud spend can increase for such calls.
Lease-funded streams still report zero usage and release the local claim. Deferred
responses.streamhelpers report a zero-token error event with no confirmation.
0.1.1 — Documentation patch
Status: published to npm on 2026-10-17.
Fixed
- Reorganized the package README so the npm package page shows it in full, with reference material
moved to the SDK repository's
docs/directory. There are no package behavior changes.
0.1.0 — First stable public preview
Status: published to npm on 2026-10-17.
Added
BudgetEnforcer.checkBudget()returns the effectivecallId, including one minted when the caller omits it, and accepts a callersignal.
Changed
- OpenAI 7 support. The optional
openaipeer range is>=4.41.0 <8. OpenAI 7 requires Node.js 22 or later; the provider-free core still runs on Node.js 20 with a compatible older provider SDK. - Reviewed provider surfaces. Coverage rules were refreshed for
@anthropic-ai/sdk@0.135.0,openai@7.36.0,together-ai@0.58.0, and@google/genai@2.30.0. Newly reviewed operations, including credential-client and raw-request escapes, are explicitly unmetered and followonUnmetered. Refresh strict coverage fingerprints when upgrading. - Google automatic continuation. With
@google/genai@2.30.0, automatic continuation on the metered generate-content methods takes one budget check and settles cumulative usage once, bounded by Solwyn-owned request deadlines. - Run leases. Leases widen in the background to model chains a run starts using, recover from a 409 refusal or ineligible renewal within 150 seconds, surrender finished runs through a bounded dispatcher, and report only their own spend.
- Reporting.
reporterMaxInFlightnow limits concurrent settlement confirmations while metadata batches stay serial, and retries honorRetry-Afterwith bounded jittered backoff. - Run tracking on demand. Importing
@solwyn/sdk/nodeno longer installs a process-wide async hook. - Breaking: raw JSON-schema Responses parse formats produce
unknownparsed types; narrow the value, use a branded schema helper, or pass explicit type arguments. - Breaking: once
close()begins, intercepted calls reject withSolwynError("client is closed"), and open streams settle once from usage observed so far. Finish or cancel streams before closing, and create a new client for later calls. The AI SDK middleware handle follows the same rule. - Breaking: when a plan suppresses custom failover tuning, the SDK keeps a stricter requested idempotency policy, failover window, and retry count instead of loosening them to defaults.
- Breaking: the per-call
solwynIdempotentfield only tightens policy;trueno longer escalates to"always". - Breaking: numeric configuration is range-checked. Durations must be finite and at most
2,147,483.647 seconds,
budgetCheckTimeoutmust be at least0.1seconds,reporterBatchSizeis capped at 1000, andbreakerReportHeartbeatat 60 seconds. DirectBudgetEnforcerdurations are validated the same way. - Breaking: loggers must supply all four methods and a
selectionPolicymust supplyorder(); partial objects raiseConfigurationErrorsynchronously. - Breaking:
createTokenDetails()andTokenDetailsSchema.parse()reject cache buckets that exceedinput_tokens. - Breaking: velocity history is kept for up to 4096 runs, so configured loop denials can fire
for high-concurrency runs. Use
velocityMode: "warn"to observe flags first. - Breaking: key, membership, and descriptor reflection no longer apply untracked-spend posture; coverage is enforced when a guarded operation is invoked.
- Breaking:
coverage()throwsConfigurationErrorwithfield: "client"instead ofTypeErrorfor an object that is not a Solwyn wrapper. - Breaking: refused, overflowing, or expired lease surrenders are dropped and reported in
lease.surrenders_droppedwarnings instead of being retried on every call. - Breaking: ingest responses require a strict
duplicateslist, and lease renewals require model and provider together. Update custom control-plane fixtures accordingly. - Breaking:
FakeControlPlaneallows project overruns inalert_onlymode, useshard_denyfor scoped and run denials, defaults lease timers to 120 seconds with a 15-second refresh, stores only accepted ingest events, and enforces batch, body, and project limits.stopRun()accepts only the"manual_kill"reason. - Breaking: cancelling an established stream settles the usage observed so far instead of
refunding the whole reservation; cancellation before connection reports
possibly_succeeded: true. - Breaking: status-less provider errors after a stream connects count toward the provider breaker unless caused by caller cancellation; non-429 HTTP 4xx errors are health-neutral.
- Breaking: a lease attempt and its per-call fallback share one preflight deadline. With less
than 50 milliseconds remaining, preflight skips network I/O and applies local policy. Caller
AbortSignals cancel preflight without counting as a control-plane outage.
Fixed
- Abandoned drop-in and AI SDK middleware streams settle observed usage once on garbage
collection, and clients dropped without
close()can be collected. - Run stops retain the usage carried by the chunk pulled at the stop boundary, and an iterator
throw()settles observed usage likereturn(). - Anthropic streaming usage follows cumulative
message_deltacounters, including server-tool usage and cache TTL splits. Google preflight estimates include contentpartsandsystemInstruction. - The AI SDK middleware refuses dispatch after a concurrent run stop, aborts in-flight streams at the next chunk boundary, and adds attribution for Vertex Anthropic, LM Studio, vLLM, generic compatible providers, and Alibaba models.
- Caller aborts end same-provider
Retry-Afterwaits immediately, and already-aborted calls skip velocity detection and budget I/O. failoverHopReadTimeoutis documented accurately: for OpenAI, OpenAI-compatible, and Anthropic clients it covers connecting and receiving response headers only, superseding the0.1.0-rc.1limitation below that described it as a whole-request bound.
0.1.0-rc.1 — Public preview candidate
Status: published to npm on 2026-09-13 as the first public-preview candidate.
Added
- A drop-in
Solwynproxy for existing provider clients, preserving their request types,instanceofbehavior, reflection, property mutation, and provider shutdown behavior. - Duck-typed support for native OpenAI, Azure OpenAI, Anthropic, Google Gemini, Amazon Bedrock, Together AI, named OpenAI-compatible providers, and a generic compatible fallback. The core has no runtime provider-SDK imports.
- Native OpenAI and Azure OpenAI Responses metering for
responses.create,responses.parse, and the deferredresponses.streamhelper. - Buffered and streaming usage settlement across supported provider dialects. A completed compatible text call with missing or incomplete provider usage falls back to a marked, length-based token estimate instead of silent zero usage.
- Pre-flight budget enforcement, automatic settlement, fail-open and local-enforcement outage behavior, retained hard-deny authority, denial receipts, and bounded aggregate replay.
- Run-scoped local token leases for eligible untagged text calls, with generation-fenced renewal and surrender during shutdown. See TypeScript SDK Budgets.
- Ordered provider failover, per-provider circuit breakers, same-provider
Retry-Afterretries, deadlines, idempotency policy, same-dialect passthrough, and fail-loud minimal cross-dialect translation. See TypeScript SDK Failover. - Request-scoped Cloud price hints for
CostPolicy; the hints do not create mutable client-wide pricing state. - Provider-surface controls:
onUnmetered, exactacknowledgeUntrackedtokens, content-free advisory reporting, localcoverage(), and reviewed surface fingerprints. - Node-only callback
run()and detachedcreateRun()/RunHandle.activate()/finish()APIs, including parent-run attribution and inherited tag layers. See TypeScript SDK Runs. - Exact-ID cooperative run control through server directives and bounded local velocity detection.
Later dispatches and active drop-in streams stop with
RunStoppedError; clearing a termination affects future work only. - Primary-only metering for supported embedding, image, audio, and video methods, using observable token or structural media quantities.
- Vercel AI SDK language-model middleware from
@solwyn/sdk/ai-sdk, including AI Gateway vendor attribution. See TypeScript SDK AI SDK Middleware. - An edge-safe
@solwyn/sdkcore, a Node-specific@solwyn/sdk/nodeentry, and dual ESM/CommonJS builds with declarations. - A framework-neutral
@solwyn/sdk/testingentry withFakeControlPlane, scripted scenarios, seven reserved magic models, reusable contract probes, and a denial-only provider sentinel. See TypeScript SDK Testing. - Typed
SolwynErrorsubclasses and strict zod wire schemas. - A path-restricted privacy firewall. Only content-free usage and operational metadata, plus explicit caller-provided tags, cross the Solwyn control-plane boundary. See TypeScript SDK Privacy.
Changed before the public preview
- Live Cloud response mode governs live budget blocking. The constructor's
budgetModedescribes SDK-local outage results rather than overriding the control plane. - Explicit provider pins bypass detection and synchronously validate the pinned client family.
- Tag precedence is explicit: per-call values override run values, which override client defaults. Tagged calls bypass run leases so tag-scoped rules remain authoritative.
- Project-period hard denials are retained globally during an outage. Run denials and stops are retained only for the exact run; tag-period denials are not retained for future calls.
RunStoppedErrorderives directly fromSolwynError, notBudgetExceededError.- Reporter shutdown is bounded, retry backoff is capped, and per-event ingest rejections are surfaced.
Fixed before the public preview
- Native stream
tee()and readable conversion now share metering, translation, run-stop, and settlement state; cancelling an unread native OpenAI or Anthropic stream closes the underlying request. - Usage paid before a structural response-translation failure remains accounted for.
- Provider wrappers preserve overloads and generic inference while mixed ESM/CommonJS imports share run enforcement, error identity, and wrapper identity.
- AI SDK middleware includes explicit run tags, conservatively accounts for unknown paid usage, and settles each logical buffered or streaming call once.
- Run stops cover native Responses subscriptions and late event waiters; stream cancellation closes the original iterator once.
- Admission checks the exact structural request sent to a provider. Unsupported payload overrides fail before provider or control-plane I/O.
- Distinct metadata events receive deduplication-safe timestamps, while retries retain stable event identity.
- Translation diagnostics use fixed structural labels rather than caller-controlled content.
Removed before the public preview
- The public
BudgetEnforcer.confirmCost()method. Settlement is owned by the client and reporter. - The public
updatePriceHints()mutation API and client-wide price-hint store. - Exact-tokenizer loading and the tokenizer dependency. Estimation is always heuristic and length-based; provider-reported usage remains settlement truth.
Known limitations
- Lease-backed calls currently carry no price hints, so
CostPolicyuses health-tier ordering and preserves configured order within equal tiers until lease grants include hints. - JavaScript provider SDKs expose one per-request timeout carrier.
failoverHopReadTimeoutbounds the provider request rather than a distinct read phase, and Bedrock request timeouts cannot universally hard-abort every Converse stream handler. - Intercepted OpenAI and Anthropic calls return plain promises rather than provider-specific
APIPromisevalues, so.withResponse()and.asResponse()are unavailable on those calls. - The AI SDK middleware meters the single model supplied by the AI SDK. It does not perform provider-client failover or cross-dialect translation.