Changelog

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Each entry's BREAKING items are surfaced inline. PR links point at the GitHub PR that landed the change.

[0.12.0] - 2026-06-04

First release since 0.11.0 — bundles the previously-unreleased 0.11.1 work (per-action guardrails, @AuditLog wiring, pure-orphan annotation removals) with a round of dogfood fixes. Includes breaking annotation/type renames; see Migration.

Added

• tnsai-llm: OllamaEmbeddingProvider — keyless EmbeddingProvider over Ollama /api/embed (nomic-embed-text default; OLLAMA_BASE_URL / OLLAMA_API_KEY; batch input) via the shared HttpClientFactory (TAN-3794).
• tnsai-core: AuthorityScope.permanent() — no-expiry authority scope (nullable validFor); expiresAt() → Instant.MAX, isExpired() → false. Removes the Duration.ofDays(3650) workaround for long-lived beans (TAN-3797).
• tnsai-core: Per-action guardrails — ActionConfig.withInputGuardrail(...) / withOutputGuardrail(...) (TNS-643, follow-up to TNS-561) — a builder-added action (RoleBuilder.addAction(ActionConfig...)) can now carry its own input/output guardrail, the programmatic equivalent of a method-level @InputGuardrail/@OutputGuardrail. The config rides on ActionMetadata (mirroring how ContractSpec/TNS-637 is carried, since builder actions have no reflective Method), and the enforcers resolve it at method-level precedence: method annotation > per-action config > role builder config > class annotation. Reflective (@ActionSpec) actions are unaffected (they keep reading their method annotation). Defaults to none, so existing builder actions behave identically. The agent-level guardrail tier remains in TNS-643 (blocked on agent-context wiring; see issue).
• tnsai-core: OutputGuardrailConfig + RoleBuilder.outputGuardrail(...) (TNS-561) — the output-side mirror of InputGuardrailConfig (below). New com.tnsai.guardrails.OutputGuardrailConfig record mirrors the runtime-enforced subset of @OutputGuardrail (maxChars/minChars/onFailure/fallback/logFailures) with from(@OutputGuardrail), defaults()/NONE, and a fluent builder; the annotation's not-yet-wired scaffold fields are deliberately excluded (note maxRetries is inert because Phase-1 RETRY degrades to REJECT). OutputGuardrailEnforcer now resolves and enforces this record, with the annotation path adapting through from(...). Resolution precedence: method @OutputGuardrail > RoleBuilder.outputGuardrail(...) (via Role.getOutputGuardrailConfig()) > class @OutputGuardrail. Existing annotation behaviour is unchanged. Both guardrail config records now also reject a contradictory bound pair (maxChars/maxLength < minChars/minLength when both are non-zero) at construction — such a config makes every value unsatisfiable, so it fails fast.
• tnsai-core: InputGuardrailConfig + RoleBuilder.inputGuardrail(...) (TNS-561) — the programmatic counterpart of a class-level @InputGuardrail, so a builder-built role (which has no annotation to read) can opt into input guardrails. New com.tnsai.guardrails.InputGuardrailConfig record mirrors the runtime-enforced subset (maxLength/minLength/blockPatterns/allowPatterns/onFailure/ errorMessage/logFailures) with from(@InputGuardrail), defaults()/NONE, and a fluent builder; the annotation's not-yet-wired scaffold fields are deliberately excluded to avoid inert surface. InputGuardrailEnforcer now resolves and enforces this record, with the annotation path adapting through from(...). Resolution precedence: method @InputGuardrail > RoleBuilder.inputGuardrail(...) (via Role.getInputGuardrailConfig()) > class @InputGuardrail. Existing annotation behaviour is unchanged (the prior enforce(@InputGuardrail, …) entry point is preserved as a thin adapter).
• tnsai-core: @AgentSpec.toolCallFilter declarative tool-call filter (TNS-611) — the top-level annotation counterpart of AgentBuilder.toolCallFilter(ToolCallFilter). The supplied Class<? extends ToolCallFilter> is instantiated via its public no-arg constructor at agent init (AGENT-V009 on failure, same as @AgentSpec.roles) and wired into the orchestrator before the first tool call. New public com.tnsai.agents.execution.AllowAllToolFilter doubles as the annotation default and the "not set" sentinel — the extractor surfaces it as null so the historical no-filter behaviour is preserved and the AGENT-V006 approval gate keeps warning about confirmation-required tools without an explicit filter. Precedence: AgentBuilder.toolCallFilter(...) / Agent.setToolCallFilter(...) wins over the annotation (applyInitializationResult only adopts the resolved filter when no pending filter was set).
• tnsai-core: @AgentSpec.maxContextTokens declarative context budget (TNS-609) — the top-level annotation counterpart of AgentBuilder.maxContextTokens(int). Setting it (> 0) prunes the agent's conversation history to the budget before each LLM call (the same pruning the builder shortcut and @MemorySpec.maxContextTokens already drive). AgentInitializer resolves it with precedence: template > @AgentSpec.maxContextTokens (top-level shortcut) > @MemorySpec.maxContextTokens (nested). 0 (the default) keeps the previous behaviour, so existing agents are unaffected.
• tnsai-mcp: MCP tool annotations map onto TnsAI safety hints (TNS-641, follow-up to TNS-556) — McpToolBridge.toDynamicToolMethod(...) (the in-process MCP bridge, the documented McpToolBridge.stdio(...).toTnsAITools() path) now reads the MCP 2025-03-26 tool annotations: destructiveHint=true → requiresConfirmation=true (so a destructive MCP tool registered without a ToolCallFilter raises AGENT-V006 instead of dispatching unattended) and idempotentHint=true → idempotent=true (was hardcoded false). Both default to false when the annotation is absent, so tools with no annotations behave exactly as before. readOnlyHint/openWorldHint are not mapped (their counterpart sideEffect is not yet modelled — see TNS-556). The tnsai-server WebSocket path (McpProxyTool) is unchanged: its wire record WsProtocol.McpToolDef carries no annotations field, so propagating them there needs a protocol extension + client support (deferred).
• tnsai-core: dynamic tools can opt into the AGENT-V006 approval gate (TNS-556) — DynamicToolMethod (the runtime tool form fronting MCP servers) gained requiresConfirmation + keywords, mirroring @Tool(requiresConfirmation=…, keywords=…) on the annotated path. AgentBuilder's confirmation scan now inspects registered dynamic tools too, so a confirmation-gated MCP/dynamic tool with no ToolCallFilter wired raises AGENT-V006 — previously only @Tool POJOs were scanned and dynamic tools silently escaped the check. Non-breaking: the pre-existing 5-arg shape is preserved as DynamicToolMethod.of(...) and a delegating 5-arg constructor (both default the new fields to the safe "no claim" values); a fluent DynamicToolMethod.builder(name) sets them. (sideEffect/idempotencyHint from @Tool are intentionally not modelled yet — no runtime consumer reads them off a ToolMethod, so they'd be no-op surface.)
• tnsai-core: programmatic role resilience (TNS-567) — RoleBuilder.resilience(ResilienceConfig) lets a builder-built role carry a retry/timeout policy without subclassing, the counterpart of class-level @Resilience. ActionExecutor applies it when no @Resilience annotation is present. Scoped to the runtime-enforced subset (retry + timeout); circuit-breaker / rate-limit / bulkhead await TNS-565 Phase 2. #430
• tnsai-core: programmatic MemoryConfig (TNS-546) — AgentBuilder.memoryConfig(...) closes the @MemorySpec parity gap (8 fields, only maxContextTokens had a builder shortcut before). MemoryConfig record mirrors @MemorySpec with from()/defaults()/ builder(); MemoryStoreFactory.create(MemoryConfig) is the canonical factory the annotation path now delegates through. #429
• tnsai-core: programmatic ContractSpec (TNS-637) — the builder-path form of @Contract. ActionConfig.withContract(ContractSpec.builder()…build()) attaches Design-by-Contract gates (pre/post/invariants) to a RoleBuilder.addAction(...) action, enforced identically to the annotation. ContractValidator now operates on ContractSpec for both paths (the annotation adapts via ContractSpec.from). #428
• tnsai-core: build-time @Contract expression validation (TNS-637, AGENT-V013). AgentBuilder.build() now parses every JEXL clause of each action's @Contract (preconditions/postconditions/invariants) and reports a malformed expression as a suppressible warning, instead of failing on first invocation. Suppress with .relaxValidation("AGENT-V013"). #427

Changed

• tnsai-core: com.tnsai.identity.AgentSpec record renamed to AgentDescriptor (TAN-3795). BREAKING: resolves the simple-name collision with the @com.tnsai.annotations.AgentSpec annotation (which keeps its name, per the @*Spec = annotations convention). All referrers updated.
• tnsai-core: @com.tnsai.roles.annotations.RoleIdentity renamed to @RoleDeclaration (TAN-3796). BREAKING: resolves the collision with the com.tnsai.models.role.RoleIdentity class (unchanged).
• tnsai-core: role export reads @RoleSpec.llm() (@LLMSpec) instead of @LLM (TNS-642, follow-up to TNS-568). BREAKING: the RoleSpecExtractor.LLMSpec nested record is renamed to RoleSpecExtractor.LLMExportSpec (it collided on simple name with the @LLMSpec annotation), and RoleSpecExtractor.hasLLMAnnotation(...) is renamed to hasLLMConfig(...). The role-export subsystem (ExportedRole, YamlRoleExporter, JsonRoleExporter) now sources LLM config from the nested @LLMSpec a role actually declares — so roles using @RoleSpec(llm=@LLMSpec(...)) now export their LLM config (previously the exporter only read the unused TYPE-level @LLM). @LLMSpec.endpoint populates the export record's baseUrl. #435
• tnsai-llm: canonical providerId() for error-mapper resolution (TNS-624). The ProviderErrorMapper SPI lookup keyed off the lower-cased executeRequest display name, which drifts from the mapper's clean token ("Together.ai" → together.ai never matched together), so mappers loaded but never resolved for ~half the providers. AbstractLLMClient.providerId() now supplies a single canonical id per provider as the lookup key (display label kept for logs); all 29 executeRequest-based clients override it. Foundation for the missing-mapper fix. No public-API change. #423
• tnsai-llm: OpenRouter / Mistral / HuggingFace folded onto AbstractOpenAICompatibleClient (TNS-636, follow-up to TNS-621), net −629 LOC. Each kept only its real divergence: OpenRouter's ranking / Claude-beta headers move to addProviderHeaders(), HuggingFace keeps a parseChatResponse override for usage tokens, Mistral has zero overrides. OpenAI, ZhipuAI and MiniMax stay bespoke (JsonCapableLLMClient + per-call response_format). No public-API change. #425

Removed

• tnsai-core: @SystemPrompt, @ChannelSpec, @Pipeline, @PipelineStep removed (TNS-569/573/577). BREAKING: four more pure-orphan annotations with no runtime consumer (verified: zero reflection readers, zero production/test/Sona usage). Their canonical counterparts are untouched: the SystemPromptBuilder, the channel Channel interface, and PipelineBuilder (tnsai-coordination) — these were always the wired surfaces; the annotations only mirrored their names. @Pipeline/@PipelineStep referenced only each other (Javadoc). Migration: none — delete any stray applications. #439
• tnsai-core: more pure-orphan annotations removed (TNS-566/576/578/589). BREAKING: deleted @RateLimited (566 — superseded conceptually by @Resilience, but never wired), the channel-hook markers @OnConnect/@OnDisconnect/@OnMessage (576), the FSM family @FSMState/@FSMTransition/@FSMStates/@FSMTransitions (578 — defined but no FSM engine reads them), and @RequiresPairing (589). Each was source-verified as a pure orphan (no reflection reader, no production/test/Sona usage); the FSM annotations referenced only each other (@Repeatable containers). Stale Javadoc references in kept files were cleaned (ChannelSpec, resilience/package-info). Migration: none — these had no runtime consumer; delete any stray applications. #438
• tnsai-core: 9 pure-orphan annotations removed (TNS-590, Section 13 cleanup). BREAKING: deleted @ContextCompaction, @SlashCommand, @WorkspaceSpec, @Property, @ConfigProperty, @Trigger, @Delegate, @Sanitize, @ContentFilter from com.tnsai.annotations. Each had no runtime consumer, no reflection reader, and zero production/Sona usage (verified by source-trace) — they were unwired scaffolding that only added surface area and "is this wired?" confusion. Migration: none needed — removing a no-op annotation cannot change runtime behaviour; delete any stray applications. (@NormType is intentionally retained — it is the value enum for the @Norm/@Norms deontic-logic wiring tracked under TNS-591.) #437
• tnsai-core: @LLM annotation removed (TNS-642, follow-up to TNS-568). BREAKING: the TYPE-level com.tnsai.annotations.LLM is gone — it was a parallel, export-only LLM-config surface with zero production usage that never instantiated an LLMClient and shadowed the live, integrated @LLMSpec (nested in @RoleSpec/@AgentSpec, which all four integration examples use). Migrate any @LLM(provider=…, model=…) on a role to @RoleSpec(llm=@LLMSpec(provider=Provider.…, model=…)). Resolves the LLMSpec simple-name collision and unblocks TNS-570 (@LLMSpec field wiring) + TNS-571 (programmatic LLMConfig). #435

Fixed

• tnsai-llm: dangling EmbeddingProvider javadoc — EmbeddingProvider, CachedLLMClient, and SemanticCache referenced a non-existent OpenAIEmbeddingProvider; examples now use the real OllamaEmbeddingProvider (TAN-3794).
• tnsai-quality: @AuditLog is now wired into AuditLogger (TNS-579) — the annotation was declared on tnsai-core but never read, so marking an action @AuditLog(action = "...") produced no audit trail. SecurityEnforcer.audit(...) (already invoked per action via the SecurityEnforcerHandle SPI) now also reads the method's @AuditLog and emits a declarative named-action entry through the new AuditLogger.auditAction(...). It is independent of @Security (an action with only @AuditLog is audited) and complementary (an action with both emits both records). includeArgs/includeResult gate whether args/result are logged, and both honour @Security masking — includeArgs routes through the same maskForLogging (so @Security(maskFields = …) fields are masked) and the result is masked when @Security(sensitive = true), matching the level-audit so neither path leaks. No tnsai-core change (the annotation already existed; the wiring lives entirely in tnsai-quality).
• tnsai-core: @LLMSpec.topP is now honored by @RoleSpec-driven role LLM init (TNS-570, partial). Role.initializeLLMFromAnnotation() — the live path that builds a role's LLMClient from @RoleSpec(llm=@LLMSpec(...)) — passed null for the topP argument of LLMClientProvider.create(...) even though the whole client layer accepts it, so a role's configured nucleus-sampling value was silently dropped. It now passes @LLMSpec.topP() (the model-default 1.0f maps to null, matching the LLMClientFactory convention). The remaining @LLMSpec fields (frequencyPenalty/presencePenalty/timeoutMs/endpoint/apiKeyEnv) are not yet honored — they need a client-layer config change (the LLM clients' constructors take only model/temperature/topP/maxTokens[/baseUrl/apiKey]); tracked under TNS-570's corrected scope.
• tnsai-llm: BedrockClient.streamChat() now works (TNS-626) — it was an UnsupportedOperationException("Streaming not yet implemented") placeholder in production. Implemented against the Anthropic Messages event stream via a lazily-built BedrockRuntimeAsyncClient (the sync client has no event-stream API); content_block_delta events are parsed to text and returned as a Stream<String>. Buffered for now (gathered before the stream is consumed); true per-token delivery is a follow-up. Claude-3-only, same as chat(). #421
• tnsai-llm: typed errors for the remaining 18 providers (TNS-622). Only 13 of the ~31 wired providers shipped a ProviderErrorMapper; the other 18 (Cerebras, DashScope, Databricks, DeepInfra, DeepSeek, Fireworks.ai, Hunyuan, llama.cpp, LM Studio, NVIDIA NIM, Perplexity, Replicate, Together.ai, Vertex AI, vLLM, Watsonx, xAI Grok, Yi) fell back to an untyped LLMException (UNKNOWN, no ProviderDetails), so OnHttpStatus / OnErrorType fallback rules never matched and the chain couldn't fail over on rate-limit/5xx for them. Each now has a mapper (15 share a new AbstractOpenAICompatibleErrorMapper; Vertex AI shares AbstractGoogleErrorMapper with Gemini; Watsonx/Replicate parse their own envelopes), resolved by the canonical providerId() from #423. #424
• tnsai-llm: AbstractOpenAICompatibleClient no longer double-wraps typed errors (TNS-636). chat()/streamChat() re-wrapped every exception into a generic LLMException (UNKNOWN, no ProviderDetails), discarding the typed exception a ProviderErrorMapper had produced — latent since TNS-621, it meant the 16 migrated OpenAI-compatible clients silently lost the typed errors #424 added. Typed LLMExceptions now propagate unchanged. #425
• tnsai-llm: OpenAI-compatible clients now report real usage tokens (TNS-639). AbstractOpenAICompatibleClient.parseChatResponse didn't read the usage block, so the ~18 clients on the base returned empty token counts and CostAwareLLMClient fell back to a character-count estimate. It now parses prompt_tokens/completion_tokens; cost tracking uses the provider's actual counts. HuggingFaceClient's bespoke parse override (its only one) is removed. #426

Migration

• Replace com.tnsai.identity.AgentSpec → com.tnsai.identity.AgentDescriptor (the @AgentSpec annotation is unaffected).
• Replace @com.tnsai.roles.annotations.RoleIdentity → @RoleDeclaration (the com.tnsai.models.role.RoleIdentity class is unaffected).
• The 0.11.1-era orphan-annotation and @LLM removals (see Removed) are also breaking; migrate per those notes.

[0.11.0] - 2026-05-27

Additive release. Closes a batch of annotation ↔ programmatic parity gaps (@AgentSpec/@RoleSpec builder methods), implements the @Contract Design-by-Contract safety primitive (JEXL pre/postconditions + old(expr)), consolidates 16 OpenAI-compatible LLM clients onto a shared base (~-3,300 LOC), and adds the tnsai diagnose bug-report reproducer CLI. No breaking changes — purely additive on the public API surface.

Added

• tnsai-core: @AgentSpec annotation-parity on AgentBuilder (TNS-534). Six @AgentSpec metadata fields had a runtime consumer but no builder counterpart, so programmatic agents silently fell back to defaults. Builder now exposes description, version, autoStart, idleTimeoutMs, did(DIDConfig), groupMembership(GroupMemberSpec), with precedence builder explicit > annotation > default applied in AgentInitializer via new InitializerContext override hooks. #411
• tnsai-core: DIDConfig (com.tnsai.identity) — programmatic counterpart of @DIDSpec (from(annotation), of(method, domain, agentId), toDid(fallbackId)), so the builder and annotation paths derive identical DIDs. #411
• tnsai-core: GroupMemberSpec.of(String...) convenience factory for builder-side group membership. #411
• tnsai-core: RoleBuilder.addAction(ActionConfig) — programmatic role actions (TNS-551). Builder-built roles can now register dispatchable actions; previously only @ActionSpec-annotated methods on a Role subclass worked, so ConfigurableRole was capability-less. New ActionConfig + ActionHandler (com.tnsai.metadata); ActionExecutor dispatches the handler lambda and Role.discoverActions merges them with annotation-discovered actions (duplicate names error). Scoped to LOCAL actions. #414
• tnsai-core: @AgentSpec.roles (TNS-536) — declare an agent's role classes (Class<? extends Role>[]) in the annotation, the counterpart of AgentBuilder.role(...). Instantiated via public no-arg constructor at init; precedence is programmatic > annotation. A missing no-arg ctor fails with an actionable AGENT-V009 message. #415
• tnsai-tools: tnsai diagnose CLI (TNS-525) — com.tnsai.tools.diagnostics prints a paste-ready environment report for bug reports: tnsai_version (lockstep), jdk (version/vendor/GC/max heap), os, and providers_configured (known LLM provider env vars as set/missing, never the value). Flags --json (default), --issue-template (GitHub markdown block), --minimal, --no-redact (secret redaction via the framework PatternRedactor is on by default). Adds .github/ISSUE_TEMPLATE/bug.md + README "run this first" section. Scoped to the static environment; runtime state (MCP reachability, checkpoint store, OTel traces, log lines) needs a live agent and is a follow-up. #416
• tnsai-core: @Contract Design-by-Contract enforcement (TNS-552) — the scaffold annotation (preconditions/postconditions/invariants, zero readers since 2.18.0) is now enforced at action dispatch via a JEXL evaluator. Preconditions reject hallucinated input before the method runs with an LLM-friendly "precondition violated: <expr>"; postconditions bind result and resolve old(expr) to the pre-execution value; invariants run before and after. Honors validate/strict/message. New com.tnsai.actions.contracts (ContractEvaluator, ContractValidator, ContractViolationException); adds commons-jexl3. Additive to the existing ActionContract / @ActionSpec.precondition / @State.invariants paths. Programmatic ContractSpec + build-time syntax validation are follow-ups. #418

Changed

• tnsai-core: removed the dead, unused AgentSpecExtractor.DIDInfo record (0 callers, verified across the full reactor) — its role is now served by DIDConfig, and AgentSpecExtractor.generateDID is DRYed through DIDConfig.toDid. Internal cleanup; no consumer impact. #411
• tnsai-llm: collapsed 16 duplicated OpenAI-compatible provider clients into a new AbstractOpenAICompatibleClient (TNS-621). Each carried a byte-identical ~225-line copy of the chat-completions mapping (buildChatRequest / parseChatResponse / extractStreamContent / chat / streamChat); a fix had to be applied 16× by hand. Now they shrink to a constructor + base-URL/env-var. Migrated: DeepSeek, Groq, Together.ai, Fireworks.ai, DeepInfra, Cerebras, Databricks, NVIDIA NIM, Perplexity, DashScope, Hunyuan, xAI Grok, Yi, LM Studio, vLLM, llama.cpp. Clients with a divergent wire format (OpenAI, OpenRouter, Mistral, HuggingFace, ZhipuAI, MiniMax) stay on AbstractLLMClient — follow-up. No public-API change; net ~-3,290 LOC; 1644 tests green. #417

[0.10.5] - 2026-05-18

Same-day follow-up to 0.10.4 — ships the TNS-449 x402 micropayments stack (tnsai-payments umbrella + HttpInterceptor primitive + end-to-end X402PaymentBroker + EnvKeystoreWallet + mandate enforcement + liability records) and a batch of dependency bumps. Purely additive on the public API front; tnsai-payments is a new optional module that consumers opt into. No migration required.

Added

• tnsai-mcp: HttpInterceptor primitive for HttpTransport (TNS-449 P1). Composable interceptor chain on the framework's HTTP transport — auth, rate limit, retry, tracing, and (the immediate driver) x402 payment-aware request mutation. 11 tests pin ordering / short-circuit / chain composition; no new dependency, no API break on HttpTransport callers. #374
• tnsai-payments: new umbrella module + PaymentBroker SPI skeleton (TNS-449 P2). New optional module — tnsai-payments carries the PaymentBroker SPI (quote, settle, verify) plus the x402 protocol-specific package skeleton. Module-graph dep: tnsai-payments → tnsai-core. Consumers opt in by adding it to their classpath; core ships with the no-op broker via #305 (0.10.0). #375
• tnsai-payments: X402PaymentBroker end-to-end x402 settlement (TNS-449 P3). Implements the PaymentBroker SPI against the x402 HTTP-402 payments protocol over Base USDC. PaymentRequirement parses the 402-body wire format; TransferAuthorization builds EIP-3009 typed data with inline EIP-712 encoding (skips web3j's heavier StructuredDataEncoder for tighter hot-path); Web3jWallet wraps secp256k1 ECKeyPair.sign for 65-byte r||s||v signatures; X402PaymentBroker.quote() probes service.metadata["x402.resource"], parses the 402, picks the compatible PaymentRequirement, mints a Quote; settle() builds typed data, signs, replays the request with X-PAYMENT (base64-JSON header), returns a sealed Settlement variant. Idempotency: Quote.idempotencyKey maps deterministically (Keccak-256) to the EIP-3009 nonce, so retried settles return Settlement.AlreadySettled rather than double-charging. New dep: org.web3j:core-crypto (slice, ~1.5 MB — full web3j was 5 MB). 39 net-new tests, module coverage 87.3%. Stub HttpServer facilitator in-process; no live testnet calls in CI. #389 (rebased successor to #377)
• tnsai-payments: EnvKeystoreWallet + mandate enforcement + liability records (TNS-449 P4, partial). EnvKeystoreWallet.fromEnv(prefix, network) reads <PREFIX>_PRIVATE_KEY from env for a zero-config local wallet (encrypted JSON keystore decryption deferred — needs the full web3j-core artifact, kept opt-in for now). X402Config gains liabilitySink + authorityScope optional builder fields. X402PaymentBroker.settle() runs mandate enforcement before signing: sums prior x402.settle records from the configured LiabilitySink, rejects when projected spend > AuthorityScope.spendCeilingUSD. Conservative posture — ceiling-set with no sink configured = block. Each terminal Settlement emits one liability record (Settled=MEDIUM, Rejected=HIGH, Expired=LOW); idempotency replays skip emission. 21 net-new tests (9 EnvKeystoreWallet + 12 X402PaymentBroker mandate/liability), module coverage 88.1%. Held for separate PR with explicit approval: AgentBuilder.paymentBroker(PaymentBroker) Protected Change. #390 (rebased successor to #378)

Changed

• Dependency bumps (#388 batch + #333):

  • aws.sdk 2.44.4 → 2.44.7 (patch)
  • jsoup 1.22.1 → 1.22.2 (patch)
  • javalin 7.1.0 → 7.2.2 (minor)
  • slf4j 2.0.17 → 2.0.18 (patch)
  • junit 5.14.3 → 6.0.3 (major; we run JDK 21 so compatible)
  • telegram-bot-api 8.3.0 → 9.6.0 (major)
  • angus-mail 2.0.3 → 2.0.5 (patch)
  • greenmail-junit5 2.1.5 → 2.1.8 (patch)
  • opentelemetry-semconv 1.41.0 → 1.41.1 (patch)

  No code edits required — pure pom property changes. The two major bumps (junit 5 → 6, telegram-bot-api 8 → 9) ride the same mvn verify reactor; if either surfaces a test regression, the specific bump is reverted in a follow-up patch release.

Stats

• 12 PRs landed in the release window: TNS-449 stack (#374, #375, #389, #390) plus the dependency batch (#333, #388 — which closed 8 dependabot PRs).
• New optional module: tnsai-payments (~4250 LOC across the four-PR stack, +693 of that in EnvKeystoreWallet + mandate work).
• Module count: 11 → 12 (tnsai-payments joins the active set).

[0.10.4] - 2026-05-18

Channel-stack expansion (Slack/Discord/WhatsApp adapters bring shipped count to six), eighteen-provider LLM catalogue expansion completing the TNS-322 umbrella, WatsonxClient IAM-refresh hardening, a multi-agent WS tool-approval routing fix, and a tnsai-server Docker image with a multi-arch publish workflow. Monorepo README link cleanup. No public API breakage, no migration required.

Fixed

• tnsai-server: WS tool-approval routing in multi-agent sessions (TNS-308). WsHandler.handleToolApprove walked the session's approvalFilters map but called filter.handleApproval(toolCallId, decision) on the first entry and returned regardless of match. In single-agent sessions there is only one filter so the bug never surfaced; in multi-agent sessions (more than one WsToolApprovalFilter per session), an approval whose toolCallId belonged to a non-first filter was silently dropped and the pending future on the actual owning filter timed out unanswered — surfacing to the user as "I approved but nothing happened." WsToolApprovalFilter.handleApproval now returns boolean (true iff it owned the id and consumed it); WsHandler iterates every filter in the session until one returns true, then breaks. Added a package-private registerPendingForTesting seam so the routing contract is unit-testable without a live WS broadcast. Nine new tests cover the boolean return on match/miss/repeated-id, the multi-agent routing pattern itself, and a cancelAll regression guard.

Added

• tnsai-channels: WhatsAppChannel adapter (Cloud API) (TNS-352). Sixth channel adapter and the first one that embeds an HTTP server in tnsai-channels — WhatsApp Cloud API delivers inbound events via webhook only (no WebSocket or polling alternative), so the adapter binds a JDK com.sun.net.httpserver.HttpServer to a configurable port + path. Inbound: Meta GETs the path with hub.challenge at subscription time → we echo iff hub.verify_token matches; Meta POSTs JSON events signed with X-Hub-Signature-256: sha256=<hex> computed via HMAC-SHA256 of the body under the app secret → we verify in constant time before parsing. Outbound: POST /{phone_number_id}/messages to the Graph API with the access token as a Bearer header. Sender-id doubles as conversation-id (WhatsApp is 1:1, no channels). v1 deliberately scopes out media (image/document/audio/voice) because UnifiedResponse's attachment shape doesn't yet model Graph's media-id-then-download flow, and scopes out template messages + 24-hour-window enforcement because templates are a separate API surface with their own approval flow. Loopback bind by default; production runs behind a reverse proxy for TLS. Env: WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_VERIFY_TOKEN, WHATSAPP_APP_SECRET (all required) + WHATSAPP_GRAPH_BASE_URL, WHATSAPP_WEBHOOK_PORT, WHATSAPP_WEBHOOK_PATH, WHATSAPP_WEBHOOK_BIND_ADDRESS (all optional). Architectural note: the embedded HttpServer is per-adapter — each webhook-based channel binds its own port. If a future second webhook adapter lands (e.g. a Slack Events API variant), the right move is to extract a shared WebhookReceiver with path-based routing; YAGNI for now.

Changed

• tnsai-llm: WatsonxClient IAM token refresh hardening (TNS-501, follow-up to TNS-340 / PR #363). The IAM-token cache had the refresh logic from day one but the safety margin was only 60 seconds — acceptable for steady-state but tight under load. Bumped to 300 seconds so refresh fires at ~minute 55 of a 60-minute token lifetime, well ahead of expiry, matching the acceptance spec. Concurrent chat calls are guaranteed to collapse to a single exchange via the existing {@code synchronized} guard on {@code getIamToken()}. Token strings are never logged — only the expiry timestamp and the IAM URL appear in debug output. Added an {@code iamTokenUrl()} override seam so tests can route the exchange through {@link mockwebserver3.MockWebServer} without reflection on the cache fields, plus a {@code expireCachedIamTokenForTesting()} hook for deterministic expiry-driven refresh tests. Three new tests: expired-cache-forces-refresh, eight-thread concurrent-refresh collapses to one exchange, and a log-leak assertion that scans every TRACE-level log line for the token string. The refactor only touches {@code WatsonxClient.java} + its test; behaviour is strictly additive (no API changes).

Added

• tnsai-channels: DiscordChannel adapter (Gateway WebSocket) (TNS-351). Fifth channel after Telegram, CLI, Email, and Slack — and the second WebSocket adapter. Inbound: opens a Discord Gateway v10 connection via GET /gateway/bot → WSS, then handles the full handshake (HELLO → schedule heartbeats → IDENTIFY with token + intents → READY captures the bot user_id → MESSAGE_CREATE becomes UnifiedMessage). Heartbeats run on a single-threaded ScheduledExecutorService with the interval Discord supplies in HELLO, carrying the last observed s sequence number on each beat. Outbound: POST /channels/{channel_id}/messages with the Bot <token> header and a message_reference.message_id when the response targets a specific reply. Bot-echo filtering: messages authored by other bots (or our own bot once READY lands) are silently dropped. v1 scopes out slash commands (needs POST /applications/{id}/commands registration + INTERACTION_CREATE handling), embeds (UnifiedResponse doesn't carry an embed shape today), and streaming via message edits (PATCH per-token is gated by Discord's edit ratelimit) — all named in the issue but deferred to a follow-up so v1 stays focused on the text-DM-and-mention path. Env: DISCORD_BOT_TOKEN (required), DISCORD_APPLICATION_ID (optional, slash-command forward-compat), DISCORD_REST_BASE_URL (optional override), DISCORD_INTENTS (optional integer bitfield override; default covers DM + guild messages + the privileged MESSAGE_CONTENT intent).
• tnsai-channels: SlackChannel adapter (Socket Mode) (TNS-350). Fourth channel after Telegram, CLI, and Email — and the first one that speaks a real-time WebSocket protocol. Inbound: opens a Socket Mode WebSocket via POST /apps.connections.open with the xapp-... app token, then routes events_api envelopes (and app_mention events) into UnifiedMessage after acking with the matching envelope_id. Outbound: POST /chat.postMessage with the xoxb-... bot token; thread continuity preserved by carrying the inbound thread_ts forward into the response body. Bot-echo and bot-id-tagged messages are filtered to prevent feedback loops; Slack message subtypes (edits, joins, channel renames) are skipped so the agent only sees user-authored text. SlackChannelConfig reads SLACK_BOT_TOKEN (required) + SLACK_APP_TOKEN (required) + SLACK_WEB_API_BASE_URL (optional override for mirrors / proxies) from env or system properties, with an explicit programmatic constructor for Sona workspace YAML. Note on deviation from TNS-350 spec: the issue called for the HTTP Events API webhook with SLACK_SIGNING_SECRET; v1 chose Socket Mode instead because the framework has no embedded HTTP server in tnsai-channels and every existing adapter pulls from its platform — Socket Mode keeps that invariant and lets Sona run behind NAT without exposing a public URL. A signing-secret-verifying SlackWebhookChannel sibling can be added later if a use case needs it.
• tnsai-llm: WatsonxClient provider (TNS-340). Twenty-fifth LLM provider — talks to IBM watsonx.ai (enterprise LLM platform) via its /ml/v1/text/chat endpoint. The response is OpenAI-shaped but the request body uses IBM-specific fields (model_id instead of model, plus a required project_id), so the request construction diverges from the cookie-cutter OpenAI-shape providers. Auth via IBM Cloud IAM exchange: unlike the bearer-token cloud providers, watsonx requires an IAM access token obtained by exchanging an IBM Cloud API key. The client does the exchange lazily on first call against https://iam.cloud.ibm.com/identity/token, caches the resulting token until its expires_in window closes (minus a 60-second safety margin), and refreshes transparently. Catalog at time of writing: ibm/granite-3-8b-instruct, meta-llama/llama-3-3-70b-instruct, mistralai/mistral-large. Region default us-south; override WATSONX_BASE_URL for eu-de / jp-tok / etc. Required env: WATSONX_API_KEY, WATSONX_PROJECT_ID. Registered in LLMClientFactory under watsonx and ibm aliases.
• tnsai-llm: DeepInfraClient provider (TNS-329). DeepInfra's cost-leader open-model hosting — typically the cheapest hosted Llama-70B option. OpenAI-compatible chat-completions API at https://api.deepinfra.com/v1/openai (note the /v1/openai suffix — DeepInfra's native API lives at /v1/inference; we target the OpenAI shim so the wire format matches every other provider). Catalog includes Llama 3.x, Mixtral 8x7B, Qwen 2.5 72B, DeepSeek V3. Override base URL via DEEPINFRA_BASE_URL. Registered in LLMClientFactory under deepinfra and deep-infra aliases. API key via DEEPINFRA_API_KEY.
• tnsai-llm: FireworksAIClient provider (TNS-328). Fireworks.ai's open-model hosting + FireFunction (function-calling-tuned) — Llama 3.x, Mixtral, Qwen 2.5, DeepSeek V3, plus firefunction-v2. OpenAI-compatible chat-completions API at https://api.fireworks.ai/inference/v1 (override via FIREWORKS_BASE_URL for mirrors / proxies). Same wire format as every other OpenAI-shape provider — structurally identical client. Registered in LLMClientFactory under fireworks, fireworksai, and fireworks-ai aliases. API key via FIREWORKS_API_KEY.
• tnsai-llm: TogetherAIClient provider (TNS-326). Together.ai's open-model hosting — Llama 3.x (8B / 70B / 405B Turbo), Mixtral 8x7B, Mistral 7B, Qwen 2.5 72B, DeepSeek V3, Nemotron-tuned Llama, and the rest of the serverless catalogue. OpenAI-compatible chat-completions API at https://api.together.xyz/v1 (override via TOGETHER_BASE_URL for mirrors / proxies). Same wire format as GroqClient / NvidiaNIMClient / XAIGrokClient / CerebrasClient — structurally identical client. Registered in LLMClientFactory under together, togetherai, and together-ai aliases. API key via TOGETHER_API_KEY.
• tnsai-llm: CerebrasClient provider (TNS-327). Cerebras's WSE-3 hosted inference — top-of-industry token throughput (reportedly 1800+ tok/s on Llama 70B). OpenAI-compatible chat-completions API at https://api.cerebras.ai/v1 (override via CEREBRAS_BASE_URL for mirrors / proxies). Catalog at time of writing: llama-3.3-70b, llama3.1-8b, qwen-3-32b. Same wire format as GroqClient / NvidiaNIMClient / XAIGrokClient — structurally identical client. Registered in LLMClientFactory under cerebras. API key via CEREBRAS_API_KEY. Headline use case: latency-sensitive agent inner loops (tool-call coordination, REPL chat, realtime UI agents).
• tnsai-llm: VertexAIClient provider (TNS-325). Twenty-seventh LLM provider — completes the TNS-322 LLM provider expansion umbrella (18 new providers shipped across two sessions). Talks to Google Cloud Vertex AI (enterprise Gemini) via its native generateContent endpoint at https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/{MODEL}:generateContent. Wire format is the Gemini shape (contents[].parts[], systemInstruction, generationConfig) with OpenAI-style assistant history roles mapped to Gemini's model role. Auth (v1 scope): takes a pre-fetched OAuth access token via VERTEX_AI_API_KEY (e.g. gcloud auth print-access-token in dev, sidecar-managed in prod). Application Default Credentials (ADC) — service-account JWT signing, GCE metadata-server probe — is a deliberate follow-up since it pulls in google-auth-library-java or hand-rolled RS256 crypto. Required env: VERTEX_AI_API_KEY, VERTEX_AI_PROJECT_ID. Optional: VERTEX_AI_LOCATION (default us-central1; host derived from it), VERTEX_AI_BASE_URL (full override). Registered in LLMClientFactory under vertexai, vertex-ai, and vertex aliases.
• tnsai-llm: ReplicateClient provider (TNS-331). Twenty-sixth LLM provider — talks to Replicate (community model marketplace) via its native predict/poll HTTP API at https://api.replicate.com/v1. Unlike every other provider in this module, Replicate is not OpenAI-shaped — the request takes an arbitrary input object and the response is delivered through a submit-then-poll lifecycle. v1 scope: sync chat only, targeting the common chat-model case (Llama, DeepSeek, Mixtral). Model identifier owner/name auto-resolves the latest version; owner/name:version pins. System prompt + history + user message concatenated into a single {"prompt": "..."} input (de facto convention for chat models on Replicate). Output handles both single-string and string-array shapes. Polling uses exponential backoff (500ms → 30s, 10-minute overall timeout). Documented limitations: no streaming (streamChat emits the final answer as a single chunk), no tool calling. Env: REPLICATE_API_KEY (Replicate's docs call it REPLICATE_API_TOKEN; this module standardises on _API_KEY). Registered in LLMClientFactory under replicate alias.
• tnsai-llm: DeepSeekClient provider (TNS-324). Twenty-fourth LLM provider — talks to DeepSeek (Chinese frontier lab) via its OpenAI-compatible chat-completions endpoint at https://api.deepseek.com/v1. Catalog at time of writing: deepseek-chat (V3, ~$0.14/M input / $0.28/M output — very cost-efficient), deepseek-reasoner (R1, reasoning model). Known v1 limitation: when the model is deepseek-reasoner, responses include a reasoning_content field carrying R1's visible chain-of-thought trace alongside the standard content text. The shared ChatResponse/ChatChunk SPI doesn't yet carry a reasoning channel, so the trace is dropped — R1 still answers correctly, callers just don't see the trace. Plumbing reasoning content through is a follow-up SPI extension. Registered in LLMClientFactory under deepseek alias. API key via DEEPSEEK_API_KEY.
• tnsai-llm: LMStudioClient provider (TNS-333). Sixteenth LLM provider — talks to a locally-running LM Studio desktop server via its OpenAI-compatible chat-completions endpoint at http://localhost:1234/v1 (override via LMSTUDIO_BASE_URL for LAN rigs or proxies). Like OllamaClient, the API key is optional: when unset the Authorization header is omitted entirely, matching LM Studio's ungated-by-default local server; when set (e.g. for an LM-Studio instance behind a reverse-proxy with basic auth) the key is sent as Bearer <key>. Model name comes from the loaded model in the LM Studio UI — discover via GET /v1/models. Streaming, tool calls, and topP follow the same wire format as the other OpenAI-shape providers. Registered in LLMClientFactory under lmstudio and lm-studio aliases.
• tnsai-llm: PerplexityClient provider (TNS-330). Twenty-third LLM provider — talks to Perplexity's search-augmented Sonar family via its OpenAI-compatible chat-completions endpoint at https://api.perplexity.ai. Sonar models fetch web results inline and ground answers in real-time sources. Catalog at time of writing: sonar (fast / cheap), sonar-pro (higher quality), sonar-reasoning (chain-of-thought over search), sonar-deep-research (multi-hop). Known v1 limitation: Perplexity responses include a citations[] array alongside the standard OpenAI text content; the shared ChatResponse SPI doesn't yet carry citation metadata, so citations are dropped — text-only answer is returned. Surfacing citations is a follow-up ChatResponse extension. Registered in LLMClientFactory under perplexity and pplx aliases. API key via PERPLEXITY_API_KEY.
• tnsai-llm: DatabricksClient provider (TNS-339). Twenty-second LLM provider — talks to Databricks Mosaic AI Model Serving via its OpenAI-compatible Foundation Model API at the customer's workspace-scoped URL. Unlike the multi-tenant cloud providers, Databricks endpoints live per-customer at https://{workspace}.cloud.databricks.com/serving-endpoints, so there is no sensible default — every caller must supply DATABRICKS_BASE_URL (or the constructor baseUrl argument). Built-in catalog at time of writing: databricks-meta-llama-3-3-70b-instruct, databricks-meta-llama-3-1-405b-instruct, databricks-dbrx-instruct, databricks-mixtral-8x7b-instruct; customers can also point this client at their own fine-tuned endpoints by passing the endpoint name as model. Auth via DATABRICKS_API_KEY (PAT or service- principal OAuth token, both passed as opaque bearer); native service-principal OAuth flows can land as a follow-up. Registered in LLMClientFactory under databricks and mosaic aliases.
• tnsai-llm: QwenCloudClient provider (TNS-335). Twenty-first LLM provider — talks to Alibaba's DashScope service (the hosted API for the Qwen family) via its OpenAI-compatible chat-completions endpoint. Two regional defaults: international at https://dashscope-intl.aliyuncs.com/compatible-mode/v1 (the client's default) and China at https://dashscope.aliyuncs.com/compatible-mode/v1 (select via DASHSCOPE_BASE_URL env var or constructor baseUrl argument). Catalog at time of writing: qwen-max (frontier), qwen-plus (balanced), qwen-turbo (low-latency), qwen2.5-coder-32b-instruct (coding), qwen-vl-max (multimodal). Streaming, tool calls, and topP all follow the standard OpenAI-shape wire format. Registered in LLMClientFactory under qwen, dashscope, and alibaba aliases. API key via DASHSCOPE_API_KEY (single-token "DashScope" label in requireApiKey to satisfy the env-var pairing test).
• tnsai-llm: LlamaCppServerClient provider (TNS-334). Twentieth LLM provider — talks to llama-server (the HTTP server binary from the llama.cpp project) via its OpenAI-compatible chat-completions endpoint at http://localhost:8080/v1 (override via LLAMACPP_BASE_URL). Mirrors OllamaClient / LMStudioClient / VLLMClient: API key is optional — Authorization: Bearer <key> is sent only when LLAMACPP_API_KEY (or constructor apiKey) is set. Model name comes from the GGUF file that llama-server's --model flag loaded. llama.cpp's small footprint makes it the lightest possible LLM server — runs on Raspberry Pi 5-class ARM hardware and Apple Silicon laptops equally well; pairs naturally with edge-class sandbox profiles where Ollama and vLLM are too heavy. Registered in LLMClientFactory under llamacpp, llama-cpp, and llama.cpp aliases.
• tnsai-llm: VLLMClient provider (TNS-332). Nineteenth LLM provider — talks to a self-hosted vLLM inference server (typically invoked as python -m vllm.entrypoints.openai.api_server) via its OpenAI-compatible chat-completions endpoint at http://localhost:8000/v1 (override via VLLM_BASE_URL for remote inference rigs). Mirrors OllamaClient / LMStudioClient: API key is optional — Authorization: Bearer <key> is sent only when VLLM_API_KEY (or constructor apiKey) is set, supporting vLLM instances started with --api-key or behind auth proxies. Model name comes from vLLM's --model flag; discover via GET /v1/models. Streaming, tool calls, and topP follow the standard OpenAI-shape wire format. Registered in LLMClientFactory under vllm alias.
• tnsai-llm: TencentHunyuanClient provider (TNS-336). Eighteenth LLM provider — talks to Tencent's Hunyuan family via its OpenAI-compatible chat-completions endpoint at https://api.hunyuan.cloud.tencent.com/v1. Catalog at time of writing: hunyuan-pro (frontier), hunyuan-standard (balanced), hunyuan-lite (cheap / fast), hunyuan-vision (multimodal). Streaming, tool calls, and topP all follow the same wire format as the other OpenAI-shape providers. Registered in LLMClientFactory under hunyuan, tencent, and tencent-hunyuan aliases. API key via HUNYUAN_API_KEY. Tencent Cloud SigV3 signing on the parallel native API path is deliberately not implemented — the bearer-token OpenAI-compatible surface keeps the wire format identical to every other provider in this module.
• tnsai-llm: YiClient provider (TNS-337). Seventeenth LLM provider — talks to 01.AI (Kai-Fu Lee's lab) via its OpenAI-compatible chat-completions API at https://api.lingyiwanwu.com/v1. Catalog at time of writing: yi-large (frontier), yi-large-turbo (cheaper / faster variant), yi-lightning (low-latency small-batch), yi-vision (multimodal). Streaming, tool calls, and topP all follow the same wire format as the other OpenAI-shape providers — structurally identical client. Registered in LLMClientFactory under yi, 01ai, and 01.ai aliases. API key via YI_API_KEY.
• tnsai-llm: XAIGrokClient provider (TNS-323). Fifteenth LLM provider — talks to xAI's Grok models via the OpenAI-compatible chat-completions API at https://api.x.ai/v1 (override via XAI_BASE_URL for mirrors / proxies). Catalog at time of writing: grok-3, grok-3-mini, grok-2-vision, plus the gated grok-beta pre-release tier. Streaming, tool calls, and topP all follow the same wire format as GroqClient / NvidiaNIMClient — structurally identical client. Registered in LLMClientFactory under xai, grok, and xai-grok aliases. API key via XAI_API_KEY.
• tnsai-channels: EmailChannel adapter (IMAP poll + SMTP send) (TNS-354). Third channel after Telegram + CLI, the first async one. IMAP polling on a configurable interval (default 60s) marks UNSEEN messages SEEN as they're processed; thread continuity tracked through Message-ID / In-Reply-To / References headers — replies in the same thread land on the same conversationId. Outbound SMTP replies set In-Reply-To and Re:-prefix the subject. EmailChannelConfig is env-var-driven (EMAIL_IMAP_HOST, EMAIL_IMAP_USER, EMAIL_IMAP_PASSWORD, EMAIL_SMTP_HOST, …) with explicit programmatic override for Sona's per-workspace YAML. Sender allowlist is mandatory — empty allowlist drops everything, since email is the most spammable channel. Jakarta Mail deps declared <optional>true</optional> to match the Telegram pattern; consumers opt in by adding them to their classpath. GreenMail-backed integration tests cover allowlist, thread continuity, attachment parsing, and outbound headers.
• tnsai-llm: NvidiaNIMClient provider (TNS-338). Fourteenth LLM provider — talks to NVIDIA NIM (NVIDIA Inference Microservices) via the OpenAI-compatible chat-completions API on both deployment shapes: the hosted catalog at https://integrate.api.nvidia.com/v1 (default) and any self-hosted NIM container via the baseUrl constructor parameter or NVIDIA_BASE_URL env var. Cloud catalog covers Llama 3.1 (8B / 70B / 405B), Mixtral 8x7B, Mistral 7B, and NVIDIA's own Nemotron-4 340B + Llama-3.1-Nemotron-70B tunes. Streaming, tool calls, and topP follow the same wire format as GroqClient / OpenRouterClient. Registered in LLMClientFactory under nvidia, nvidia-nim, and nim aliases. API key via NVIDIA_API_KEY.

Added (ops)

• tnsai-server: Docker image + multi-arch publish workflow (TNS-520). Multi-stage Dockerfile (Maven 3.9 + Eclipse Temurin 21 → distroless gcr.io/distroless/java21-debian12:nonroot) ships a self-contained tnsai-server JAR runnable with docker run. The JVM is PID 1 so SIGTERM reaches the existing Runtime.addShutdownHook() drain path; image defaults to TNSAI_HOST=0.0.0.0 + TNSAI_ALLOW_PUBLIC=true but deliberately leaves TNSAI_TOKEN unset — operators must supply a token before exposing to anything other than a private network. New /healthz + /readyz route aliases (Kubernetes-conventional) added additively alongside the existing /health/live + /health/ready endpoints, sharing the same handler lambdas. maven-shade-plugin lives in an opt-in docker profile so mvn install for downstream consumers stays fast and Maven Central isn't polluted with a -shaded classifier. New .github/workflows/docker-publish.yml smoke-tests on every v* tag (boots the image, polls /healthz for 30s, verifies SIGTERM-driven graceful shutdown) then publishes multi-arch (linux/amd64 + linux/arm64) to Docker Hub. Skipped for forks. Requires DOCKERHUB_USERNAME + DOCKERHUB_TOKEN repo secrets. #385

Docs

• Monorepo consolidation link cleanup (TNS-513). Module READMEs still pointed at the deprecated split-repo URLs (TnsAI.Core, TnsAI.LLM, …) retired in the April 2026 consolidation — those repos no longer exist, so every reference rendered as a 404 on GitHub. Forty link refs + bare-prose mentions across nine module READMEs rewritten to monorepo paths (tnsai-core, tree/main/tnsai-X). External-repo refs (TnsAI.Docs, TnsAI.Web, TnsAI.Sona, TnsAI.Wiki, TnsAI.Papers) preserved. #386
• handoff/ vs context-snapshot disambiguation (TNS-117). Coordination module docs clarify the distinction between explicit agent handoffs (HandoffStrategy) and implicit context snapshots taken on session continuation — no behaviour change. #370

Internal

• tnsai-core: PaymentBroker SPI record test coverage (TNS-518). Three new test files in com.tnsai.payment (SettlementTest, QuoteTest, ServiceTest) pin every validation invariant on the shared SPI records — sealed-variant exhaustiveness on Settlement, null-checks + blank-string rejection + priceUSD ≥ 0 + expiresAt > issuedAt on Quote, defensive-copy isolation on Service.metadata. 31 tests, all green. No production code touched. #376

Sister-repo follow-ups

• TnsAI.Sona — TNS-507: tnsai.version bumped to 0.10.4; TNS-514: logback-test.xml added so mvn test no longer leaks log lines into ~/.sona/sona.log (production logback.xml shadowed during tests only).
• TnsAI.Web — TNS-512: Next 16.2.4 → 16.2.6 + React 19.2.5 → 19.2.6 to pick up GHSA-8h8q-6873-q5fj RSC DoS patch; TNS-517: non-security patch sweep across fumadocs / tailwind / postcss / typescript-eslint / lucide-react; framework references bumped 0.10.3 → 0.10.4.
• TnsAI.Docs — TNS-515: 45 broken internal links fixed + lychee CI gate added to prevent regression; payments documentation (payments/x402.md + payments/index.md) shipped to land alongside TNS-449.

Stats

• 9 PRs landed in the release window (#366, #367, #368, #369, #370, #371, #376, #385, #386). The bulk LLM-provider expansion that finishes the TNS-322 umbrella was already in Unreleased carried from the 0.10.3 window.

[0.10.3] - 2026-05-14

Same-week follow-up to 0.10.2 — extends ProjectTools with two new @Tool methods aligned to the agents.md spec so agents can route on structured project context (sections, intro) instead of an opaque blob, and can bootstrap a fresh AGENTS.md from a project's build system. Purely additive, no public API breakage, no migration required.

Added

• tnsai-tools: ProjectTools.agentsmdParse + agentsmdGenerate (TNS-399 axis 1). Two new @Tool methods on the PROJECT_TOOLS toolkit. agentsmd_parse returns a structured AgentsMdContent record (intro + ordered sections: [{level, title, body}]) parsed from AGENTS.md, with case-variant + CLAUDE.md + README.md fallback — letting agents route on individual sections (e.g. pull just "Setup") rather than treating the document as an opaque blob. agentsmd_generate produces a draft AGENTS.md by detecting the build system from pom.xml / package.json / pyproject.toml / Cargo.toml / go.mod and filling in language-appropriate setup + test commands — returns the markdown string, the caller decides whether to write it. #343

Sister-repo follow-ups

• TnsAI.Sona — TNS-484: project_dir workspace config + AGENTS.md auto-load consumed agentsmdParse to augment role prompts. Shipped ahead of this release (Sona builds the framework HEAD in CI).
• TnsAI.Docs — PR #133: agentsmd_parse + agentsmd_generate documented in capabilities/tools/catalog.md under PROJECT_TOOLS. PR #345 (this release window): same coverage in framework tnsai-tools/CODEBASE_MAP.md + README.md.

Stats

• 1 PR landed in the release window for new public surface (#343).
• 4 supporting doc PRs (#339, #340, #341, #342) refreshed module CLAUDE.md / README / per-module AGENTS.md without touching public API.

[0.10.2] - 2026-05-13

Same-week follow-up to 0.10.1 — adds a streaming-capable channel adapter mixin (the structural fix the TNS-438 Sona REPL polish workaround had been waiting on) plus a CI workflow defensive fix. Purely additive, no public API breakage, no migration required.

Added

• tnsai-channels: StreamingChannelAdapter mixin interface + UnifiedChunk record (TNS-440). Lets adapters opt into per-token delivery without changing the existing ChannelAdapter contract. UnifiedChunk carries conversationId, delta, done flag, free-form metadata (tool-call markers etc.), and timestamp. The mixin extends ChannelAdapter so any StreamingChannelAdapter is also a regular adapter — gateway code can instanceof-check and dispatch chunks via sendChunk(...) as they arrive, then still call send(UnifiedResponse) once with the assembled reply for non-streaming downstreams (logging, audit). Adapters that don't implement the mixin keep working unchanged. #335
• tnsai-channels: CliChannel now implements StreamingChannelAdapter with capabilities().streaming() = true. REPL mode emits the assistant: prefix once on the first chunk then concatenates deltas inline; JSON mode emits one {"type":"chunk","content":"...","done":...} record per chunk. The post-stream send(UnifiedResponse) is suppressed (the reply was already rendered chunk-by-chunk); the suppressNextSend state resets after one consumption so subsequent standalone send() calls render normally. #335

Fixed

• CI: artifact upload steps in .github/workflows/build.yml now use continue-on-error: true and 3-day retention (down from 7). Previously, a GitHub Actions free-tier storage quota hit would mark the whole Build & Test job red even though mvn verify had passed. Soft-fail makes the build status reflect code health, not artifact store availability. #336
• Release tooling: make release CHANGELOG extract now uses literal-substring match instead of regex, so versions with . (every version) extract correctly (TNS-419). #324

Stats

• tnsai-channels: 128 → 146 tests (+18). 2 new public types (StreamingChannelAdapter, UnifiedChunk).
• 3 PRs (#324, #335, #336). 1 additive feature + 2 infra fixes.
• Reactor mvn verify 13/13 PASS.

Sister-repo follow-ups (tracked in Linear)

• TnsAI.Sona — TNS-458: replace the CliChannel-bypass scaffolding in runChat with the new mixin so sona chat --json also streams.

[0.10.1] - 2026-05-08

Same-day follow-up to 0.10.0 — purely additive observability + evaluation surface and a second channel adapter. No public API breakage, no migration required. Released under the 0.x patch policy (0.X.Y → 0.X.Y+1 for additive + bugfix + chore).

Added

• tnsai-channels: CLI channel adapter (com.tnsai.channels.cli) — second ChannelAdapter after Telegram. Two modes: REPL (interactive > prompt with /exit /quit /clear local slash commands intercepted, everything else flows to the gateway as a UnifiedMessage) and JSON (newline-delimited {"text":"..."} in / {"type":"text","content":"..."} out for scripting). SPI-discoverable via META-INF/services, mode selected from a config string ("json" case-insensitive → JSON, default REPL). Closes TNS-353 Phase 1+2. #317, #318
• tnsai-quality: OTLP-native LLMCallLog exporter (OtlpLLMCallExporter implements LLMCallPublisher) — every captured LLMCallLog now flows to any OpenTelemetry collector (Langfuse, LangWatch, Phoenix, Honeycomb, Tempo, Loki) via the GenAI semconv wire shape. One CLIENT span per call (chat <model> / chat_stream <model>), three metrics (gen_ai.client.token.usage long counter partitioned by gen_ai.token.type, gen_ai.client.cost.usd + gen_ai.client.operation.duration histograms). Cardinality discipline: 7 ctx fields on the span, only tenant + role on the metric (others would explode the metric series). Retroactive timing — setStartTimestamp(call.startedAt()) + span.end(call.completedAt()) so dashboard duration matches captured elapsed even for post-hoc spans. Closes TNS-374. #319
• tnsai-quality: Sampling + Redacting decorators for LLMCallPublisher — companion to the existing Sampling* / Redacting*Publisher pair on AgentEventPublisher. SamplingLLMCallPublisher reuses the EventSamplingPolicy SPI by mapping each LLMCallLog into a SamplingInput (eventKind "llm.called", level ERROR when isFailure() else INFO so ErrorAlwaysPolicy passes failures regardless of nominal sample rate). RedactingLLMCallPublisher scrubs every leaky surface: prompt.systemPrompt / prompt.messages / prompt.parameters (LLM_PROMPT scope) and response.content / response.toolCalls[].arguments / response.reasoningContent / error.errorMessage / providerExtensions (LLM_RESPONSE scope). Tool names pass through (framework metadata). Composition: new SamplingLLMCallPublisher(new RedactingLLMCallPublisher(otlp, redactor), policy) — redaction inside, sampling outside, so dropped events skip the redactor cost. Closes TNS-417, completes TNS-374 acceptance #3. #321
• tnsai-evaluation: Agent-tier evaluators (com.tnsai.evaluation.evaluators.agent) — four new metrics that score the trace rather than just the final response. PlanAdherenceEvaluator (LLM judge, "did you stick to the declared plan?"), StepEfficiencyEvaluator (deterministic, expected / max(expected, actual), "did you reach the goal without burning extra tool calls?"), ToolCorrectnessEvaluator (LLM judge, "were the right tools picked?"), TaskCompletionEvaluator (LLM judge, "did the final response solve the task?"). Shared package-private JudgeScoreParser mirrors GEvalEvaluator.extractScore generalised to any [min, max] range; returns -1 on no match so callers fail explicitly instead of guessing a middle value. Closes TNS-373. #320

Fixed

• tnsai-quality: typo in two test method names — nullCallProapagates → nullCallPropagates. Cosmetic, JUnit method-name agnostic. #322
• tnsai-channels: stale @since 0.9.4 on CliChannel → @since 0.10.1. Author wrote the tag pre-0.10.0 cut; next release after 0.10.0 is 0.10.1. #318
• tnsai-evaluation + tnsai-quality: 8 stale @since 0.10.2 Javadoc tags → @since 0.10.1 (anticipated wrong version on TNS-373 and TNS-417). Cosmetic, no API change.

Stats

• 6 PRs (#317 → #322), purely additive — no BREAKING items, no Changed, no Removed.
• Reactor mvn verify 13/13 PASS — quality 1357 → ~1357, channels 106 → 128, evaluation 277 → 322. Test count up from 10357 → 10458 (+101).
• Module dep graph delta: tnsai-quality → tnsai-llm (new, TNS-374) — one-way edge, no cycle (tnsai-llm only depends on tnsai-core).

PR: release: 0.10.0 → 0.10.1

[0.10.0] - 2026-05-08

The reliability + safety platform release. Five new capability layers land together — durable idempotency stores, checkpoint/resume primitives, agent identity + accountability + payment SPIs, on-demand modular knowledge (skills), and unified sandbox execution — alongside framework-wide cost governance (rate-limit + budget hooks at the LLM boundary) and server-side hardening (five-layer security). Two BREAKING changes drive the minor bump per the 0.x breaking → minor policy: accountability wiring is now explicit (no silent no-op fallback in AgentBuilder), and logback-classic moves to test-scope only (consumers choose their own SLF4J binding). Process improvements ship in the same window: a nightly reactor build catches time-bomb tests + cross-module drift before consumers hit them, and the PR template enforces reactor verification when public surfaces change.

Added

• tnsai-quality: idempotency keys with pluggable persistence — Redis (Lettuce) and Postgres (JDBC) IdempotencyStore implementations, MCP idempotentHint flag wired through tool-call routing. Closes TNS-224. #301
• tnsai-quality: rate-limit + budget hooks at the LLM call boundary — token-bucket rate limiter, USD spend budget tracker, configurable per-agent / per-tenant. Closes TNS-210. #302
• tnsai-core: checkpoint + resume + idempotent retry primitives — CheckpointStore SPI, in-memory default, automatic snapshot on agent state transitions, replay-safe retry. Closes TNS-299. #303
• tnsai-quality: durable CheckpointStore implementations — Redis (Lettuce) for fast volatile checkpoints, S3 (AWS SDK v2) for cold long-term snapshots. Closes TNS-312. #304
• tnsai-core: agent identity + accountability + payment SPIs — AgentIdentity (DID + cryptographic key), AccountabilityLog (signed event chain), PaymentRail (x402 / settlement abstraction). Closes TNS-298. #305
• tnsai-core: on-demand modular knowledge layer — @Skill annotation, SkillActivationEvent (added to TnsAIEvent sealed hierarchy), lazy skill loading via SPI, runtime skill discovery. Closes TNS-289. #307
• tnsai-quality: unified file/doc guardrails — sandbox execution + size limits + extension whitelist, applied uniformly to file-write and document-export tools. Closes TNS-342. #308
• tnsai-quality: Sandbox SPI — isolated execution primitive (process / container / WASM strategies), pluggable resource limits. Closes TNS-296. #309
• tnsai-quality: code review pipeline harness — pluggable, idempotent, deepsec pattern; routes proposed code changes through configurable checks before commit. Closes TNS-291. #312
• tnsai-server: five-layer security hardening — auth, rate-limit, input validation, output redaction, audit log on every request. Closes TNS-302. #313
• CI: nightly reactor build (.github/workflows/nightly-reactor.yml) — mvn verify on main daily at 06:00 UTC, surfaces time-bomb tests and cross-module compile drift before consumers hit them. #314
• Process: PULL_REQUEST_TEMPLATE.md with mandatory reactor-build checkbox when Protected Changes / sealed-type permits are touched, plus Sister-PR section linking Docs / Wiki / Sona. #314

Changed

• BREAKING: tnsai-core: AgentBuilder.accountability(...) is now mandatory when @Accountable is on the agent — the silent no-op shim is removed. Builder fails fast with a configuration error if accountability isn't wired. Closes TNS-298 follow-up. #306
• tnsai-tools: Python and JavaScript execution tools migrated from per-tool isolation to the shared Sandbox SPI — single hardening surface, consistent resource limits across languages. Closes TNS-343. #311

Removed

• BREAKING: tnsai-core: logback-classic moved from compile-scope to test-scope only. Consumers now pick their own SLF4J binding (logback / log4j2 / slf4j-simple) — no transitive logback pulled into application classpaths. Closes TNS-309. #315
• tnsai-core: no-op accountability fallback shims (NoOpAccountabilityLog, NoOpPaymentRail) — replaced by explicit-wire failure mode. #306

Fixed

• tnsai-intelligence: ContradictionDetector time-bomb fixed — Clock is now injected so tests can pin time; the FUTURE = NOW + 30d constant no longer leaks wall-clock dependency into CI. Closes TNS-341 (CI broke 2026-05-07T12:00 UTC when the original constant expired). #310

Migration

Accountability (TNS-298 follow-up): if your agent declares @Accountable, wire the SPI explicitly in the builder:

AgentBuilder.create()
    .accountability(new MyAccountabilityLog())  // required — no implicit fallback
    .build();

If you don't need accountability, drop the @Accountable annotation. Builder will fail at build time with a clear error message if the annotation is present but no log is wired.

Logback (TNS-309): add an SLF4J binding to your application's runtime classpath. Logback consumers add it explicitly:

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.5.13</version>
    <scope>runtime</scope>
</dependency>

Or pick log4j2-slf4j2-impl / slf4j-simple if your stack uses those. The framework no longer assumes a binding.

Stats

• 15 PRs (#301 → #315), 5 new capability layers, +24449 / −629 LOC across 265 files in 13 modules.
• Reactor mvn verify 13/13 PASS — 0 failures, 0 errors.
• BREAKING change count: 2 (TNS-298 accountability strict wiring, TNS-309 logback test-scope).
• Process: nightly reactor + PR template land in this release; first nightly run scheduled 2026-05-09 06:00 UTC.

PR: release: 0.9.3 → 0.10.0

[0.9.3] - 2026-05-06

Closes the @ToolExample silent-drop chain across all LLM providers — examples now reach the model on Anthropic (input_examples field), OpenAI / Gemini / 8 OpenAI-passthrough providers (description fold with EXAMPLES: / AVOID: sections), Bedrock-Claude (via the extracted Anthropic converter), and Cohere (flat parameter shape + fold). System-prompt prose additionally renders examples under ## Available Actions so the model sees them when reasoning about a role overall, not only at tool-call time. Constraint rendering format also unified across the three prompt builders: positives-first, header-once (Must always: / Must never: blocks rather than repeated - Must always: / - Must never: prefix per rule). Purely additive — no API breakage, no migration required.

Added

• tnsai-llm: Bedrock (Claude 3 family) and Cohere now support @ToolExample end-to-end. Bedrock routes via the extracted AnthropicToolConverter; Cohere has its own CohereToolConverter (JSON-Schema → flat parameter_definitions shape, types translated string→str / integer→int / number→float / boolean→bool / array→list / object→dict). #297
• tnsai-core: @ToolExample now renders in the system-prompt prose under each action's ## Available Actions block. Positive examples appear under Examples:, negatives under Avoid (anti-patterns):. Wired through both RolePromptBuilder (in-process role) and SystemPromptBuilder (SCOP bridge). #299
• tnsai-core: ActionMetadata.getExamples() accessor — returns the combined positive + negative example list in declaration order. #299
• tnsai-core: com.tnsai.prompt.format.PromptFormat — shared formatter for prompt-building call sites. renderConstraints (mustAlways / mustNever) and renderExamples (@ToolExample). Used by RolePromptBuilder, RoleSpecReader, and SystemPromptBuilder (SCOP). #298, #299

Changed

• tnsai-core / tnsai-integration: constraint block rendering switched from per-bullet repeated prefix (- Must always: <rule> / - Must never: <rule>) to header-once (Must always: / Must never: block headers with indented bullets). Positives now render before negatives. User-observable in generated system prompts; the format change drops ~200 prompt tokens per typical 5-action × 4-rule role. The negatives-first ordering of 0.9.2 is gone — positives set the tone, negatives draw the boundary. #298

Fixed

• tnsai-llm: @ToolExample annotations on tool methods are no longer silently dropped on the Anthropic provider. Positives are mapped into the native input_examples field on each tool definition; negatives are folded into the tool description as an AVOID: section (Anthropic's tool API has no first-class anti-pattern field). #291
• tnsai-llm: @ToolExample annotations no longer silently dropped on OpenAI and Gemini. Both providers receive examples folded into the function description as EXAMPLES: (positives) and AVOID: (negatives) sections — neither provider has a native examples API. #292
• tnsai-llm: @ToolExample annotations no longer silently dropped on the 8 OpenAI-passthrough providers (Mistral, Groq, OpenRouter, Ollama, HuggingFace, Azure OpenAI, MiniMax, ZhipuAI — both chat and multimodal sites). Same description-fold strategy as OpenAI/Gemini. #296

Documentation

• @ToolExample Javadoc now cites the Anthropic source for the "72% → 90% accuracy on complex parameter handling" claim (Introducing advanced tool use) instead of a bare assertion. Also fixes outdated @since tag (2.14.0 template-artefact → 0.3.0) and a broken @see Action cross-reference (now @see ActionSpec). #295
• tnsai-core/README.md: annotation count refreshed 100+ → 98 (verified via grep -rh "public @interface") on both prose and feature-table sites. #293
• 8 module READMEs (core, llm, mcp, tools, intelligence, coordination, integration, quality): per-module LICENSE link now correctly resolves to the monorepo-root LICENSE file ((LICENSE) → (../LICENSE)) — submodules don't carry their own LICENSE files post-monorepo. #294

Stats

• 8 PRs, ~1900 lines added across tnsai-llm (Anthropic / Bedrock / Cohere / 8 passthrough converters), tnsai-core (PromptFormat helper), and Javadoc / README polish.
• 44+ new test cases — ToolExampleConverterTest (52 cases for Anthropic + OpenAI/Gemini fold), AnthropicToolConverterTest (8 cases), CohereToolConverterTest (9 cases), PromptFormatTest (16 cases — 10 constraints + 6 examples).
• All 13 modules build green (mvn verify reactor 13/13 PASS); no behavioural regressions.

[0.9.2] - 2026-05-06

Removes @ActionSpec.invariants[] — the vestigial third bucket that consistently became a misuse magnet for behavioral rules belonging in mustAlways / mustNever. Three buckets where two had clear semantic homes turned the third into a dumping ground; rules wound up double-rendered in system prompts (token waste + LLM ambiguity over which list to honour). With this cut the framework's per-action constraint surface collapses to two intents — do (mustAlways) and don't (mustNever) — plus the orthogonal Hoare-triple pair (precondition / postcondition) and state-level @State.invariants. Net delta: 12 files, +32 / -233 lines. BREAKING — released as a patch under user pragma rather than the strict 0.x breaking → minor rule (parent CLAUDE.md), given the removed field's low real-world usage and the trivial mechanical migration (drop the annotation parameter or move its strings into mustAlways / mustNever).

Removed

• BREAKING: @com.tnsai.annotations.ActionSpec.invariants() — the String[] field is gone. Move strings to mustAlways (positive obligations) or mustNever (negative prohibitions).
• BREAKING: ActionMetadata.invariants field + hasInvariants() + getInvariants() accessors.
• BREAKING: ContractConfig.invariants field — record arity drops 6 → 5.
• BREAKING: ActionExecutor before/after method-level invariants check; only checkPrecondition / checkPostcondition / checkStateInvariants remain on the action lifecycle.
• BREAKING: InvariantCheckerHandle.checkActionInvariants(Method) SPI method.
• BREAKING: InvariantChecker.checkActionInvariants(Method) impl + references in checkBeforeAction / checkAfterAction / collectViolations.
• BREAKING: RoleSpecReader.setInvariants(...) / getInvariants() + private field.
• BREAKING: RoleSpecExtractor.ResponsibilityInfo.invariants() record component + extraction line.
• BREAKING: SystemPromptBuilder.appendActionsSection "Invariant: ..." render block (the 5 lines added in 0.9.0 / PR #284 — that addition surfaced the misuse magnet, this removal closes it).
• Tests covering removed paths.

Kept (different concerns, valid use)

• @State.invariants — Gaia state predicates evaluated by InvariantChecker.checkStateInvariants() after any state change.
• @ActionSpec.precondition / postcondition — Hoare-triple Method contracts; still wired through ActionExecutor.
• @ActionSpec.fulfills / effects — planning subsystem coordinates.
• @Contract.invariants — different annotation, contract-by-design layer.

Migration

Mechanical sweep: grep -r "@ActionSpec(.*invariants\s*=" . should return 0 hits after migration.

Versioning note

Strict rule per parent CLAUDE.md (0.x breaking → minor) would have called for 0.10.0; user pragma chose 0.9.2 patch given the removed field's low real-world usage and the trivial migration. Future BREAKING removals will revert to the strict rule unless explicitly noted.

Stats

12 files changed · +32 / -233 lines · @ActionSpec.invariants consumer references in framework: 0 (sweep verified).

PR: #289.

[0.9.1] - 2026-05-06

Re-cut of 0.9.0 (which was rejected by Sonatype Central Portal as "component already exists" — earlier release.yml attempts had partially staged 0.9.0 artifacts that couldn't be cleared without manual portal UI work). Identical content to the originally-planned 0.9.0; version bumped to 0.9.1 as the cleanest forward path.

PR: #release-recovery.

[0.9.0] - 2026-05-06 (UNRELEASED — superseded by 0.9.1)

Consolidates three overlapping abstractions named "Responsibility" into per-action constraints on @ActionSpec. Every safety constraint now lives on the action it applies to — the action method becomes the natural locus for traceability, audit, and rendering. Action-attributed constraints flow into the system prompt as bullets under each action; downstream exporters (JSON / YAML / Jason) emit them with action attribution. BREAKING — bumps minor because the @Responsibility / @Responsibilities annotations, the Responsibility model interface, Role.getResponsibilities(), and RoleBuilder.responsibility(...) / mustNever(...) / mustAlways(...) are removed. Also lands LLM call granular capture (issue #79 phase 1) — typed LLMCallLog events with USD cost + stream metrics + EventContext attribution — so consumers can route per-call observability into LangFuse / Helicone / Phoenix or custom cost trackers.

Added

• @ActionSpec.mustNever() / mustAlways() — String[] arrays declaring per-action safety constraints. Rendered into the system prompt as - Must never: ... / - Must always: ... bullets under each action's signature, alongside its description and type marker. Closes #283.
• ActionMetadata.getMustNever() / getMustAlways() + hasMustNever() / hasMustAlways() — runtime accessors for the new constraints; consumed by RolePromptBuilder, RoleSpecExtractor.extractResponsibilitiesFromActions, and the SCOP SystemPromptBuilder.
• RoleSpecExtractor.ResponsibilityInfo.mustNever() / mustAlways() — extra fields on the auto-extracted record so exporters can render constraints with action attribution (actionName: constraint).
• LLM call granular capture — Phase 1 (#79) — typed LLMCallLog events emitted per LLM invocation, decoupled from the legacy raw-string LLMObserver. Wires the LLMCallLog record (already shipped as data-shape-only in 0.5.0) into a working publish path so consumers can route prompt + response + token usage + USD cost + stream metrics + EventContext into LangFuse / Helicone / Phoenix dashboards or custom cost trackers.
  • LLMCallPublisher (SPI) — single-method publish(LLMCallLog); NOOP is the framework default.
  • Slf4jLLMCallPublisher — default opt-in publisher; one structured SLF4J line per call (no raw prompt/response text — that is intentionally behind redaction SPI #80).
  • CapturingLLMClient — decorator wrapping any LLMClient. Captures success and failure paths; for streaming, captures TTFT + chunk count. Multimodal chat(List<ContentPart>) and streamChatWithSpec route through the delegate without capture in this PR — separate hot-path refactor.
  • JsonLLMPricingRegistry — loads rate cards from classpath JSON. Ships /pricing/2026-05.json with rates for openai/gpt-4o, openai/gpt-4o-mini, openai/o1-preview, anthropic/claude-sonnet-4, anthropic/claude-opus-4, and an ollama/* wildcard (zero — local). Other 7 framework providers' rate cards land incrementally.
  • ToolSurfaceHasher — single canonical entry point that turns the framework's raw List<Map<String,Object>> tool shape into a ToolSurface with a stable SHA-256 hash. Sorted-key Jackson serialisation so identical tool sets across calls correlate (prompt-cache friendly).
  • (provider, model) cost attribution via LLMCallLog.context() — every captured event carries the active EventContext (tenant / agent / role / capability / session / group), so consumers downstream can attribute USD cost along any dimension already wired by issue #78.
• 18 new tests covering CapturingLLMClient (success / error / streaming / cost / context paths) + JsonLLMPricingRegistry (default registry + wildcard + missing-resource).
• LLM rate cards — Phase 2 (#79) — pricing/2026-05.json expanded from 3 providers / 6 models to 7 providers / 13 models, so the cost field on LLMCallLog is populated for the major providers a TnsAI agent is likely to be wired against. Adds: anthropic/claude-haiku-4-5, google/gemini-2.0-flash, google/gemini-2.0-pro, mistral/mistral-large, mistral/mistral-small, groq/llama-3.3-70b-versatile, groq/mixtral-8x7b-32768, cohere/command-r-plus, cohere/command-r. Providers without prompt caching (groq, cohere) declare cached_per_1k: null. 10 new tests (1099 total in tnsai-llm).

Removed

• BREAKING: @com.tnsai.annotations.Responsibility annotation (used inside @RoleSpec.responsibilities).
• BREAKING: @com.tnsai.roles.annotations.Responsibilities annotation + nested Duty, SafetyConstraint, Severity types.
• BREAKING: com.tnsai.models.role.Responsibility model interface + CoreDuty / SafetyProperty / Responsibilities (container) implementations.
• BREAKING: com.tnsai.enums.role.SafetyType enum (only consumed by deleted classes).
• BREAKING: Role.getResponsibilities() abstract template method + Role.responsibilities() accessor + Role.getMustNeverConstraints() / getMustAlwaysConstraints().
• BREAKING: RoleBuilder.responsibility(...), responsibilities(...), duty(...), mustNever(...), mustAlways(...) — fluent API surface for role-level safety constraints. Use @ActionSpec annotations on a Role subclass instead.
• BREAKING: @RoleSpec.responsibilities() field.
• BREAKING: RolePromptBuilder.generateResponsibilitiesSection(...), the second buildMinimalRolePrompt(identity, responsibilities) overload (only identity is needed now).
• BREAKING: RoleSpecExtractor.extractResponsibilities(...) / hasResponsibilitiesAnnotation(...). Use extractResponsibilitiesFromActions(...) for the action-bound replacement.
• BREAKING: RoleSpecReader.RoleSpec.ResponsibilityMeta + getResponsibilities() / setResponsibilities(...).
• BREAKING: ExportedRole.responsibilities field + hasResponsibilities(). autoResponsibilities (per-action) is now the single source.

Changed

• RolePromptBuilder rendering — the ## Responsibilities markdown block is gone. Per-action Must never: / Must always: bullets render under each action in the ## Available Actions section.
• SystemPromptBuilder (SCOP integration) — same shape change; renders constraints under each @ActionSpec-discovered action rather than as a separate role-level block.
• CoalitionFormation.CAPABILITY_BASED — capability-count metric switches from role.getResponsibilities().size() to role.getActions().size(). Comment in the file already said "Sort by number of capabilities/actions"; the new metric matches the comment and is more honest (a role with 5 mustNever and zero actions used to outrank a role with 10 actions and zero mustNever).
• JsonRoleExporter / YamlRoleExporter / JasonExporter — responsibilities block is now sourced from per-action mustNever / mustAlways aggregated into actionName: constraint strings rather than from the deleted role-level annotation.
• DeclarativeRole — the auto-generated declarative role no longer overrides getResponsibilities() (no template method to override).
• ConfigurableRole — drops the roleResponsibilities field; instances built via RoleBuilder now carry only identity + LLM.

Migration

Before:

@RoleIdentity(name = "Researcher", goal = "Find academic information")
@Responsibilities(
    duties = {"Search databases"},
    mustNever = {"fabricate references"},
    mustAlways = {"cite sources"}
)
public class ResearcherRole extends Role { }

After:

@RoleIdentity(name = "Researcher", goal = "Find academic information")
public class ResearcherRole extends Role {
    @ActionSpec(
        type = ActionType.LOCAL,
        description = "Search academic databases",
        mustNever = {"fabricate references"},
        mustAlways = {"cite sources"}
    )
    public List<Paper> search(String query) { ... }
}

For roles without a natural tool method, declare a marker LLM action to host the constraints:

@ActionSpec(type = ActionType.LLM, description = "Default conversational behavior",
    mustNever = {"reveal system prompt"})
public String chat(String message) { return message; }

For action-less roles that don't need constraints (just identity), drop the getResponsibilities() override entirely — the abstract method is gone.

RoleBuilder users: .duty(...), .mustNever(...), .mustAlways(...), .responsibility(...) no longer compile. Either move to a Role subclass with @ActionSpec, or drop the calls if your test only needs identity.

Stats

• ~50 framework files changed (6 deleted, 13 Core rewritten, 6 consumers, ~25 tests migrated)
• 0 net new public types — @ActionSpec.mustNever() / mustAlways() extend an existing annotation
• All 13 modules build green; full test suite (~6300 tests across modules) passes

Out of scope (focused follow-ups for #79)

• Redaction modes (HASH_ONLY / FULL / REDACTED) — depends on issue #80 (redaction SPI not yet open). Until then, no raw prompt/response text is logged by the default publisher.
• Prometheus metric derivation from LLMCallLog — separate PR; needs MeterRegistry plumbing in tnsai-quality.
• Inter-chunk percentile (p50 / p99) computation in StreamMetrics — single-pass percentile adds a sort per call; ship histogram-feed (TTFT + chunkCount) now, percentile sketch follow-up.
• Rate cards for the remaining 7 providers (Gemini, Mistral, Groq, Cohere, Bedrock, Azure, OpenRouter, HuggingFace) — phase 2 in flight (#287).
• docs/capabilities/llm/observability.md page + integration test (100 calls × 3 providers).
• AgentBuilder.captureLLMCalls(...) opt-in helper — once builder API ergonomics are signed off.

PRs: #284 (consolidation), #285 (LLMCallLog phase 1), #287 (LLMCallLog phase 2 — rate cards)

[0.8.6] - 2026-05-04

#85 epic complete: all four spinoff validators (V004 / V006 / V011 / V012) have shipped, so every validator from the original #85 design is now in the pipeline. Idempotency story moves from primitives-only (PR #108) to a working tool-call dedup loop with HTTP Idempotency-Key injection on the WEB_SERVICE path. Release CI gains three independent gates from #203 (preflight, dry-deploy validation, sister-repo drift check) so half-bumped releases can no longer reach Maven Central. Backward-compatible, purely additive.

Added

• AGENT-V004 declarative capability check — @RoleSpec(requires = {LLMCapability.STREAMING, LLMCapability.VISION, ...}) field surfaces when a configured LLM doesn't support a capability the role declares. Severity WARNING (soft-launch). New com.tnsai.enums.LLMCapability enum (STREAMING / STRUCTURED_OUTPUT / VISION; FUNCTION_CALLING intentionally NOT here — already covered by V003 via tool-presence). Co-located with V003 in LLMCapabilityValidator (shared introspection prologue, independent emit). Closes #238. PR: #246.
• AGENT-V011 MCP server reachability check — opt-in (withReachabilityChecks(true)) reachability probe for every @MCPTool(serverUrl = ...) URL referenced by an agent's actions. Runs the actual MCP initialize handshake at build time. New com.tnsai.spi.McpClientFactory SPI in tnsai-core + DefaultMcpClientFactory adapter in tnsai-mcp (auto-discovered via META-INF/services). Validator graceful-degrades when the adapter is absent. Closes #237. PRs: #244, #252.
• AGENT-V012 tenant scope validator (Phase 1 + 2) — AgentBuilder.tenantId(String) declares per-tenant agent scope; com.tnsai.spi.TenantAware is a marker SPI consumers' MemoryStore implementations opt into to advertise tenant safety. TenantScopeValidator fires WARNING when tenantId is set but the wired store is not TenantAware (or is the build-time default InMemoryStore). Suppressible via .relaxValidation("AGENT-V012") (e.g. for one-process-per-tenant deployments). Closes #235. Runtime TenantContext propagation, tool-side hook, and audit-event tenant id are intentionally split into separate follow-up issues (Phase 3+4 — protected-API territory). PRs: #248, #250.
• @Idempotent wired into ToolMethodDispatcher — the primitives shipped in PR #108 (annotation, SPI, key derivation, in-memory store, exception) now have an active call site. New IdempotencyResolver orchestrator handles all four KeyStrategy values + all three RetryBehavior policies + failure caching opt-in + store unavailability. New IdempotencyKeySupplier opt-in interface for KeyStrategy.EXPLICIT. Tools without @Idempotent bypass the resolver entirely (zero overhead, per-Method cache for reflection-free dispatch). PR: #251.
• Idempotency-Key HTTP header injection on WEB_SERVICE actions — WebServiceExecutor injects the same key the resolver uses internally onto outgoing POST / PUT / PATCH / DELETE requests when the action is @Idempotent. Stripe / SendGrid / Twilio / GitHub upstream-side dedup activates alongside the framework's client-side cache. Safe methods (GET / HEAD / OPTIONS) get the cache but not the header. IdempotencyResolver.deriveKey promoted to public static so the header path and the cache path land on the same key (EXPLICIT suppliers must be deterministic — called twice per call). PR: #253.
• Release CI hardening (3 of 7 #203 items) — `release.yml` now runs three independent gates before the Maven Central deploy step:
  • Preflight (#254, #203 item 2) — same scripts/release-preflight.sh make preflight VERSION=X.Y.Z runs locally; verifies tag exists, root pom version matches tag, all 13 poms lockstep, CHANGELOG section header present, no duplicate tag at the same commit.
  • Dry-deploy validation (#255, #203 item 4) — mvn deploy -P release to a local file repo + per-module artifact validation (poms + jars + sources + javadocs + signatures) before the immutable Central deploy.
  • Sister-repo drift check (#256, #203 item 7) — clones TnsAI.Docs / TnsAI.Web / TnsAI.Sona / TnsAI.Wiki and grep-scans for stale-version markers; surfaces "shipped 0.8.6 but TnsAI.Web still says 0.8.5" before the release advances.

Changed

• tnsai-core/agent_docs/validation.md — "Spinoffs" section narrowed to "Resolved spinoffs" (all four originally-spun-off validators now ship); shipped-validators table goes from 9 to 12 entries; LLMCapabilityValidator row clarified "(FC head)" / "(declared head)" to disambiguate V003 + V004 sharing one class. PRs: #244, #246, #250.
• IdempotencyResolver.deriveKey — promoted from private to public static. Necessary so the HTTP header injection path in WebServiceExecutor derives the same key the resolver's internal cache lookup uses; otherwise the header value and the cache lookup would diverge for KeyStrategy.HASH_INPUT. PR: #253.

Fixed

• Bare <NNN patterns escaped in 0.8.5 CHANGELOG entry — <100ms and <500ms parsed as MDX tag-opens by fumadocs-mdx in TnsAI.Web's changelog sync, breaking the Next.js build for the entire 0.8.5 sister-repo PR. Wrapped in backticks; consumer-side render now matches plain-Markdown intent. Future-proofing: this CHANGELOG entry follows the same backtick discipline for any threshold expressions. PR: #249.

Stats

• 11 commits since v0.8.5
• All 12 #85 design validators now shipped (was 9): AGENT-V004, AGENT-V006, AGENT-V011, AGENT-V012 previously deferred, all in
• 1 new tnsai-core SPI (McpClientFactory)
• 1 new tnsai-core SPI marker (TenantAware)
• 1 new tnsai-core enum (LLMCapability, 3 values)
• 1 new tnsai-mcp adapter (DefaultMcpClientFactory via ServiceLoader)
• 4 new AgentBuilder setters (tenantId, toolCallFilter was 0.8.5 — adding tenantId here)
• 3 new release-pipeline gates (preflight + dry-deploy + drift)
• ~150 new tests across IdempotencyResolverTest (24) + ToolMethodDispatcherIdempotencyTest (14) + WebServiceExecutorIdempotencyTest (14) + LLMCapabilityValidatorV004Test (14) + MCPServerReachabilityValidatorTest + integration tests + AgentBuilderTenantIdTest (9) + TenantScopeValidatorTest (6) + TenantScopeIntegrationTest (7) + DefaultMcpClientFactoryTest (10)

[0.8.5] - 2026-05-04

AGENT validator family one step closer to #85 acceptance: V006 (ToolApproval gate) ships alongside the @Tool.requiresConfirmation + AgentBuilder.toolCallFilter primitives it gates on. Phase 3 closeout for #85 ships the Set<String> relaxValidation overload, the <100ms SLA pinning perf test, and first-class validator docs. Also contains a transitive slf4j-simple leak from tnsai-evaluation that was hijacking consumer-side logback configuration. Backward-compatible, purely additive.

Added

• AGENT-V006 ToolApprovalValidator — fires when at least one registered @Tool POJO has requiresConfirmation = true AND no ToolCallFilter has been wired through AgentBuilder. Suppressible via .relaxValidation("AGENT-V006"). Severity WARNING (soft-launch). Closes #234. PR: #243.
• @Tool.requiresConfirmation() — boolean annotation field for tool authors to declare a runtime safety gate. Independent of @Tool.idempotent() (retry hint) and ToolRiskLevel (gradient classification) — the existing ToolRiskLevel javadoc already pre-referenced this field as "the boolean gate". PR: #243.
• AgentBuilder.toolCallFilter(ToolCallFilter) — pre-build setter parallel to the existing post-build Agent.setToolCallFilter(). Wired via the same pending-pattern used for KnowledgeBase so build() stays lazy. Null filter clears the slot symmetrically with the post-build setter. PR: #243.
• AgentBuilder.relaxValidation(Set<String>) — bulk suppression overload for the common CI pattern of skipping multiple validation codes in one call. Eager null-entry rejection so typos surface at the configuration site, not silently passing every issue through. PR: #241.
• ValidationPipelinePerformanceTest — pins the <100ms SLA from #85 acceptance ("typical agent validates in <100ms (static checks only)"). Asserts <500ms with 5× margin for CI runner jitter; locally completes in 10–30ms. PR: #241.
• tnsai-core/agent_docs/validation.md — first-class consumer-facing docs covering all 9 shipped validators, the Healthcheckable SPI with implementation contract, opt-in reachability + per-probe timeout, suppression model (single + bulk), performance SLA, AgentValidationException shape, and the 3 deferred validators with their blocker issues. PR: #241.

Fixed

• slf4j-simple no longer leaks at compile scope from tnsai-evaluation to consumers. The dep was declared without an explicit <scope>, defaulting to compile and racing the consumer's logback binding for the SLF4J "one binding per JVM" slot. Now <scope>test</scope> — test JVM still has a binding (277 evaluation tests stay green), the published artifact's transitive graph no longer carries it. Inline <!-- ... --> comment added explaining the regression context so a future copy-paste / cleanup doesn't silently undo the fix. Closes #240. PR: #242.

Stats

• 3 commits since v0.8.4
• 1 new public annotation field (@Tool.requiresConfirmation)
• 1 new AgentBuilder setter (toolCallFilter)
• 1 new AgentBuilder overload (relaxValidation(Set<String>))
• 1 new AGENT validator (V006); 9 of 12 #85 validators now shipped (was 8) — 3 spinoffs remaining: V004 (#238), V011 (#237), V012 (#235)
• 1 perf test pinning #85's <100ms SLA
• ~25 new tests across V006 + relaxValidation overload
• 1 published-artifact regression contained (slf4j-simple at compile scope)

[0.8.4] - 2026-05-03

Multimodal toolkit completion + safety-gate plumbing + AGENT validator expansion. Backward-compatible, purely additive — no removals, no behaviour changes. Headlines: image generation (DALL-E 3 / FLUX / Stability), audio generation (ElevenLabs / Cartesia / Deepgram + Whisper alternatives), ChannelScopedId typed identity, prompt-injection scanning for project-context files, and two new build-time validators (AGENT-V003 / V005).

Added

• Image generation toolkit — single function-shape POJO ImageGenTools with three @Tool methods (dalle3_generate, flux_generate, stability_generate) so the LLM can pick provider at call time by cost/latency/quality. Uniform {provider, model, urls[, revised_prompt]} envelope; Stability binary response decoded to data:image/png;base64,… URI for shape parity. New BuiltInTool.IMAGE_GEN_TOOLS enum entry. PR: #221 (closes #93 Phase 1).
• Audio generation toolkits — two POJOs (TextToSpeechTools + SpeechToTextTools) covering the canonical non-OpenAI alternatives to MediaTools. TTS: ElevenLabs Multilingual v2/Turbo/Flash, Cartesia Sonic-2 (latency leader), Deepgram Aura (cheapest). STT: Deepgram Nova-2 (sync), AssemblyAI Universal-2 (async with internal poll loop, 5-min hard cap), OpenAI Whisper large-v3 hosted on Replicate (FLUX-key reuse). New BuiltInTool.TEXT_TO_SPEECH_TOOLS + SPEECH_TO_TEXT_TOOLS entries. PR: #222 (closes #93 Phase 2).
• ChannelScopedId value type in tnsai-channels — typed (channelId, senderId) record replacing the ad-hoc channelId + ":" + senderId string concat. Compact constructor refuses a separator-bearing channelId; parse() splits on the first colon so a senderId with internal colons (Slack T123:U456) round-trips losslessly. UnifiedMessage.scopedId() convenience helper added (parallel to existing sessionKey() — sender-scope vs conversation-scope). PR: #224 (closes #19 Phase 1).
• Prompt-injection scan for project-context files — PromptInjectionDetector.detectInProjectContext(content, source) adds a context-only pattern set targeting attack vectors that don't make sense in regular chat: SSH-key dumps, .env reads, ~/.aws/credentials reads, env-var dumps, curl POSTs of secret files, display:none/visibility:hidden/white-on-white HTML, zero-width-character payloads, HTML-comment overrides. New ContextFileSource enum (TNSAI_MD / CLAUDE_MD / AGENTS_MD / README_MD / OTHER) tags audit-log entries. New InjectionType enum values: CREDENTIAL_EXFILTRATION and HIDDEN_INSTRUCTION. PR: #228 (closes #35).
• AGENT validator family expansion — LLMCapabilityValidator (AGENT-V003, function-calling capability check) and Healthcheckable SPI + reachability validation infra (AGENT-V005). PRs: #233, #236 (advances #85).
• Release-pipeline hardening Phase A — make preflight (5-check gate: tag exists, root pom version, 13 module poms lockstep, CHANGELOG section, no duplicate tag), make drift-check (sister-repo stale-version scan), japicmp Maven plugin in the quality profile. PR: #206 (closes #203 Phase A).

Changed

• Surefire migrated to explicit Mockito -javaagent — Java 24+ removes the silent agent-loading path, so the test runner now declares the agent jar by full path. Standardises across all 13 modules. PR: #225.
• JaCoCo coverage gate added for #9 protected classes — five test-coverage waves landed (FormatAwareOutputParser, CompositeResilienceStrategy + ComposedResilienceStrategy, InMemoryMessageBroker + Message factories, ContextSnapshot + Builder, GroupTask record + Builder + lifecycle), and the gate ratchets coverage so it cannot regress. PRs: #226, #227, #229, #230, #231, #232 (advances #9).
• Dependency bumps (Dependabot wave) — jackson group (3 updates), micrometer-registry-prometheus 1.3.1 → 1.16.5, mongodb-driver-sync 5.2.1 → 5.7.0, jakarta.mail-api 2.1.3 → 2.1.5, playwright 1.58.0 → 1.59.0, graalvm 25.0.2 → 25.0.3, jacoco-maven-plugin 0.8.12 → 0.8.14, spotbugs-maven-plugin 4.8.6.5 → 4.9.8.3, central-publishing-maven-plugin 0.7.0 → 0.10.0, maven-plugins group (6 updates), ci-actions (checkout 4→6, setup-java 4→5, upload-artifact 4→7, action-gh-release 2→3).

Stats

• 29 commits since v0.8.3
• 5 new public types (ChannelScopedId, ImageGenTools, TextToSpeechTools, SpeechToTextTools, ContextFileSource)
• 9 new @Tool methods (3 image + 6 audio) + 2 new AGENT validators (V003, V005)
• 3 new BuiltInTool enum entries
• 2 new InjectionType enum values
• 4 issues closed via PR (#19, #35, #93, #203 Phase A) + #9 advanced through 5 phases + #85 advanced through phases 1/2a
• ~115 new tests across the new toolkits and detector

[0.8.3] - 2026-05-02

Two bug fixes batched together — both surfaced during open-issue triage. Backward-compatible, additive: AuthType.API_KEY is a new enum constant the framework's javadoc has documented since the annotation landed but never actually defined.

Fixed

• StdioTransport.shouldHandleProcessExit flaky test (#205): the startup race in waitForProcessStart() polled process.isAlive() in a 50 ms loop, treating "alive" as a proxy for "started". Wrong for fast-exiting processes — a one-shot like echo writes its line and exits between two polls, so isAlive() returns false even though the process started, ran, and produced output successfully (pipe data persists in the kernel buffer after the writer exits). Replaced the loop with return process != null — ProcessBuilder.start() is synchronous on POSIX/macOS, so by the time we hold a Process reference exec(2) has succeeded. Test also migrated from Thread.sleep(500) to a CountDownLatch(1) synchronisation point, removing the timing assumption. 5× sequential local runs all PASS (was: failing once every ~3-5 CI runs).

Added

• AuthType.API_KEY (#175): the @WebService javadoc has documented this auth type since the annotation landed, but the enum only defined NO_AUTH / BEARER / BASIC. A consumer copy-pasting from the javadoc got a compile error with no clear hint that the documented value didn't exist. Added the enum constant + a matching switch arm in WebServiceExecutor.addAuthHeaders that reads from @WebService.authTokenEnv and uses @WebService.apiKeyHeader for the header name (defaulting to X-API-Key when empty). The orphan apiKeyHeader annotation field — previously reachable from no code path — is now wired in.

Stats

4 source files, +49/-22 LOC across tnsai-mcp + tnsai-core. 1 test rewritten for determinism (StdioTransportTest$RealProcessTests .shouldHandleProcessExit). 13/13 modules build, 9 083 tests pass.

PRs: #205, #175

[0.8.2] - 2026-05-01

Fixes a prompt-rendering bug in SystemPromptBuilder (the SCOP-bridge prompt path) where @Responsibility.invariants was emitted as a single comma-joined line. Long natural-language rules with internal commas (e.g. "…a real-sounding name, a real city, a real job, real numbers") collapsed into prose under that join, hurting the LLM's ability to extract individual rules. Now rendered as a bullet list, one rule per line — restoring per-rule saliency.

Fixed

• SystemPromptBuilder.buildFromAnnotations(...) rendered @Responsibility.invariants[] as Invariants: rule1, rule2, rule3 (single comma-joined line). Fix emits each rule on its own bullet:

  Invariants:
      - rule1
      - rule2
      - rule3

  @State.invariants is intentionally unchanged — those are short technical predicates (e.g. count >= 0) that read cleanly in the existing inline [constraints: …] tag and don't suffer the same collapse problem.

Stats

1 source file (SystemPromptBuilder.java, +6/-1 LOC) + 1 test case (SystemPromptBuilderPromptTemplatesTest, +35 LOC). 13/13 modules build; 9 083 tests pass.

PR: #205

[0.8.1] - 2026-04-30

Adds a typed-input overload to Agent.executeAction so consumers can replace Map.of("path", "…", "question", "…") call sites with a Java record. The new overload reflects the record's components into a parameter map and forwards to the existing untyped dispatch path — existing Map<String, Object> callers are unchanged thanks to Java's overload resolution preferring the more specific Map parameter.

This matches the dominant 2024–2025 industry pattern (LangChain args_schema, Vercel AI SDK + Mastra inputSchema: z.object(...), Spring AI FunctionToolCallback.inputType(...), LangChain4j typed @Tool parameters, Embabel @Action records) — typed input + string action name. No new annotations, no new mental model: write a record, pass an instance.

Added

• com.tnsai.actions.ParamBeanMapper — utility that reflects a Java record, a POJO with getX/isX accessors, or a class with public fields into a Map<String, Object>. Maps are passed through unchanged. Null values are preserved as map entries so the framework's parameter binding can decide how to treat them.
• Agent.executeAction(String actionName, Object input) — typed-input overload that delegates to ParamBeanMapper.toMap(input) then to the existing executeAction(String, Map<String, Object>).
• Agent.executeActionOnRole(String roleId, String actionName, Object input) — symmetric typed-input overload for role-scoped dispatch.

Stats

3 files added/modified in tnsai-core (~330 LOC), 11 new ParamBeanMapperTest cases covering records, POJOs, public-field beans, map pass-through, null handling, and unsupported bean shapes. 13/13 modules build, 9 082 tests pass.

PR: #204

[0.8.0] - 2026-04-29

Finishes the RFC #188 cleanup by deleting the residual @LLMTool / @ToolBinding cookbook layer. The annotations were a metadata surface for a tool-calling executor (LLMToolsExecutor) that was already removed in 0.6.0 — the configuration was being silently ignored at runtime. Per-action LLM overrides (llmSystemPrompt, llmTemperature) move directly onto @ActionSpec. Tool exposure is purely agent-level via AgentBuilder.builtInTools(...) / .toolPojos(...); the agent's ToolMethodDispatcher is the single dispatch path for any @Tool methods the LLM emits. One annotation, one runtime path, no dead config carriers.

Added

• @ActionSpec.llmSystemPrompt() : String — per-action system-prompt override (replaces @LLMTool.systemPrompt())
• @ActionSpec.llmTemperature() : float — per-action temperature override (replaces @LLMTool.temperature())
• AgentBuilder.builtInTools(BuiltInTool... tools) — compile-time-safe shortcut that reflectively instantiates each shipped POJO toolkit and registers it through the same pipeline as .toolPojos(...)
• BuiltInToolInstantiationException — surfaced when a BuiltInTool entry's backing class is missing from the classpath (typically because tnsai-tools is not a dependency)
• BuiltInTool enum: per-entry getClassName() accessor + instantiate() reflective constructor

Changed

• BuiltInTool enum rewritten from 33 dangling entries (post-SPI delete in 0.5.7 they had no backing classes) to 59 POJO-aligned entries that map each shipped toolkit's FQCN. Each entry's Javadoc lists every @Tool method the toolkit exposes
• BuiltInTool.AI_TOOLS renamed → VISION_TOOLS (the backing AiTools POJO ships only image_analyze; the previous name was misleading)
• LLMRoleExecutor now reads llmTemperature / llmSystemPrompt from @ActionSpec directly (was @LLMTool nested annotation)
• ActionExecutor LLM-branch routing simplified — every ActionType.LLM action now goes through LLMRoleExecutor regardless of (former) availableTools content; tool calls are dispatched by the agent-level ToolMethodDispatcher

Removed

• BREAKING: @com.tnsai.annotations.LLMTool annotation (every field: tools, customTools, maxToolCalls, parallelToolCalls, systemPrompt, temperature, maxIterations, stopSequences, includeToolHistory, mcpServers, bindings, returnKey)
• BREAKING: @com.tnsai.annotations.ToolBinding annotation + @LLMTool.bindings() field — the SCOP-side dispatcher that consumed them was deleted in 0.6.0; the ${param} template + text-protocol pattern is superseded by typed @Tool method parameters that the LLM populates directly from its function-call arguments
• BREAKING: @ActionSpec.llmTool() : LLMTool annotation field
• BREAKING: com.tnsai.metadata.LLMToolConfig record (use the @ActionSpec.llmSystemPrompt() / .llmTemperature() accessors on ActionMetadata directly)
• BREAKING: ActionMetadata.llmToolConfig() accessor
• BREAKING: ActionMetadata.getBuiltInTools(), getCustomToolNames(), getAvailableTools(), getMaxToolCalls(), isParallelToolCalls(), getMaxIterations(), getStopSequences(), isIncludeToolHistory(), getMcpServers(), hasMcpServers(), isRequireToolUse() — all dead since 0.6.0
• BREAKING: Reference examples tnsai-integration/.../scop/examples/DataAnalystRole, CsvLoaderRole, and the DataAnalystRoleAnnotationRoundTripTest — they demonstrated the deleted cookbook against an executor that no longer existed
• LLMToolConfigTest test class
• 7 stale LLMToolsExecutor Javadoc references in actions/executors/package-info, actions/package-info, TypedActionExecutor, and assorted other source files (the class was deleted in 0.6.0 but the comments lingered)

Fixed

• The Fumadocs static-export search on tnsai.dev was hitting /api/search with no static index materialised; now wires createFromSource(source).staticGET() to a static.json route handler and passes search={ options: { type: 'static', api: '/static.json' } } to RootProvider. ~10 600 docs entries indexed at build time
• tnsai-tools/README.md, tnsai-core/README.md, tnsai-tools/CLAUDE.md, tnsai-tools/CODEBASE_MAP.md, the root CLAUDE.md, tnsai-core/.../annotations/{ActionSpec,LLMTool,ToolBinding}.java Javadoc, and the entire TnsAI.Docs capabilities/tools/ + tutorials/
  • Quick-Start surface — all rewritten against the post-RFC-#188 reality (no Tool interface, no *Tool classes, no @LLMTool, no LLM_TOOL/LLM_ROLE action types, accurate tool counts)
• ActionSpec.java Javadoc: action-types table + @LLMTool-using example swapped for the new llmSystemPrompt / llmTemperature shape

Migration

The compile-time fix for any consumer using @LLMTool:

// before (compile error in 0.8.0)
@ActionSpec(
    type = ActionType.LLM,
    description = "...",
    llmTool = @LLMTool(
        systemPrompt = "You are concise.",
        temperature = 0.2f,
        tools = { BuiltInTool.CSV_TOOLS }   // never dispatched anyway since 0.6.0
    )
)
public String summarise(String text) { ... }

// after
@ActionSpec(
    type = ActionType.LLM,
    description = "...",
    llmSystemPrompt = "You are concise.",
    llmTemperature = 0.2f
)
public String summarise(String text) { ... }

Tool exposure moves to the agent-build call site, where it has always been the only working path:

Agent agent = AgentBuilder.create()
    .id("data-analyst")
    .llm(llmClient)
    .role(new MyRole())
    .builtInTools(BuiltInTool.CSV_TOOLS, BuiltInTool.PDF_TOOLS)   // or .toolPojos(new MyOwnTools())
    .build();

Anyone leaning on @ToolBinding(tool = "csv_parser", inputTemplate = "${path}|||command") ports to typed @Tool parameters on the receiving toolkit method — the LLM populates them directly from its function-call arguments, no text-protocol substitution layer.

Stats

~870 lines net delete across tnsai-core + tnsai-integration. 13/13 modules build green, 9 071 tests pass.

PR: #203

[0.7.0] - 2026-04-29

Closes RFC #188 by retiring the legacy Tool interface entirely. ToolMethod is now a sealed interface with two variants: StaticToolMethod (POJO @Tool methods) and DynamicToolMethod (runtime-defined via Handler callback, e.g. MCP proxies). One registry, one dispatcher.

Added

• DynamicToolMethod record — runtime-defined tool variant for proxies and plugin systems
• StaticToolMethod record — extracted reflection-dispatch logic from ToolMethodDispatcher
• AgentBuilder.dynamicTool(DynamicToolMethod) and .dynamicTools(List<DynamicToolMethod>)
• AutoTeamBuilder.dynamicTool(...) / .dynamicTools(...) mirror APIs
• McpProxyTool.toDynamicToolMethod(...) static factory — replaces implements Tool
• ToolMethodDispatcher.lookup(name) and .registry() accessors
• TnsAIToolProvider.fromDynamic(DynamicToolMethod...) and .from(pojos, dynamicTools) factories

Changed

• ToolMethod is now a sealed interface (was a record); permits StaticToolMethod, DynamicToolMethod
• McpToolBridge.toTnsAITools() returns List<DynamicToolMethod> directly (no wrapper)
• ActionExecutor constructor now takes ToolMethodDispatcher (was List<Tool>)
• ActionExecutor.executeExternalTool(String, Map<String, Object>) (was (String, String))
• UnifiedContextAssembler.tools(List<ToolMethod>) (was List<Tool>)

Removed

• BREAKING: com.tnsai.tools.Tool interface
• BREAKING: AgentBuilder.tool(Tool), .tools(List<Tool>), .getToolsList()
• BREAKING: ConfigurableAgent.getExternalTools()
• BREAKING: ToolSchemaGenerator.generateToolSchema(Tool)
• BREAKING: McpToolBridge.TnsAIToolWrapper adapter class
• BREAKING: TnsAIToolProvider.fromTools(Tool...) factory + legacy dispatch branch
• BREAKING: AutoTeamBuilder.tool(Tool) / .tools(List<Tool>)
• ToolMethodAdapter bridge class (no consumers left after migration)
• ToolFailureMode annotation + ToolFailureModeReader helper
• Orphan tnsai-integration/.../CsvLoaderRoleBindingTest (referenced llmtools deleted in 0.6.0)

Fixed

• CancellationToken concurrency race: concurrent cancel() + onCancel() could fire a callback twice. Now exactly-once via per-registration AtomicBoolean guard.

Migration

Consumers using AgentBuilder.toolPojos(...) are unaffected — recommended path unchanged. Direct Tool implementers move to either:

• A POJO with @Tool-annotated methods, registered via .toolPojos(new MyTool())
• A DynamicToolMethod constructed via factory, registered via .dynamicTool(myTool)

ChatRequest.tools is still List<Map<String, Object>> (unchanged since 0.6.0).

Stats

35 files, ~733 lines net delete. Combined with 0.6.0: ~14k lines removed from the legacy tool stack.

PR: #202

[0.6.0] - 2026-04-29

Continues the RFC #188 legacy-tool-stack delete that started in 0.5.7. tnsai-core shrinks to a leaner spine. Tool interface stays as a slim registration surface for one more release; full removal in 0.7.0.

Changed

• BREAKING: ChatRequest.tools type changed List<ToolDefinition> → List<Map<String, Object>> (JSON-Schema fragments, Anthropic-style tool-use format)
• Tool interface slimmed (369L → 138L) — kept core contract + safety/policy hints

Removed

• BREAKING: ToolDefinition record + builder + fromMap / toMaps helpers
• BREAKING: ToolSchemaGenerator.generateToolDefinition* methods (3 overloads)
• BREAKING: Tool interface metadata-discovery surface — 12 default methods removed: getCategory, getUsageExamples, getMetadata, getSearchKeywords, getPriority, canHandle, getAllowedCallers, isParallelizable, getReturnFormat, getLatencyCategory, getShortDescription, executeAsync
• BREAKING: ToolMetadata, ToolCategory, ToolLatency types
• Legacy actions/llmtools/ subsystem
• @ToolSpec and @ToolAction annotations + reflective extractor
• Hooks/policy/validators ecosystem (Pre/Post/Error/Register ToolUse events, ToolPolicy*, ToolApprovalValidator, LLMCapabilityValidator)
• ToolMetrics (628L) + ToolExecutionMetric
• ToolRegistry (225L) + ToolProvider SPI
• AgentBuilder.tool(String name) lookup overload
• Dead ToolCallProcessor (264L, no consumers)

Migration

Custom ChatRequest callers swap ToolDefinition.of("name", "desc") for Map.<String, Object>of("name", "name", "description", "desc", "parameters", Map.of()). Direct Tool implementers can drop the deleted-method overrides — they no longer compile but no consumer reads them.

Stats

~10.4k lines removed from the runtime.

PRs: #194, #195, #196, #197, #198, #199, #200

[0.5.7] - 2026-04-29

RFC #188 Phase 2 + 3a + 3b: full migration of the tool catalog to the function-shape POJO pattern (LangChain / Spring AI / CrewAI / Mastra style). Replaces 130+ extends AbstractTool legacy implementations with 60 typed POJOs exposing ~190 @Tool-annotated methods across 28 categories.

Added

• ToolMethodRegistry — reflection-based @Tool discovery, duplicate-name fail-fast
• ToolMethodDispatcher — Jackson type-aware coercion + Method.invoke dispatch
• JsonSchemaGenerator — derives JSON Schema fragments from @Tool/@ToolParam metadata
• ToolMethodAdapter — bridges function-shape ToolMethod to legacy Tool interface (deleted in 0.7.0)
• AgentBuilder.toolPojos(Object...) registration path
• TnsAIToolProvider.fromPojos(Object...) for MCP server integration
• 60 function-shape POJOs across 28 categories (file, search, database, communication, fintech, utility, etc.)
• 3 server-tool POJOs: ServerFileTools, ServerShellTools, ServerGitTools

Removed

• 134 *Tool.java legacy implementations under tnsai-tools
• 32 *ToolProvider.java SPI factory classes
• 18 framework infrastructure files (AbstractTool, AbstractCategoryToolProvider, validation/health/manifest/enhancement helpers)
• 152 corresponding *Test.java files
• tnsai-tools SPI registration

Migration

Consumers extending AbstractTool move to a POJO with @Tool-annotated methods. Pattern documented in tnsai-core/CLAUDE.md. Most consumers don't touch this — they use built-in tools through tnsai-tools, which is now backed by the new POJOs transparently.

Stats

+27,160 / −85,000 lines (~58k net smaller). The biggest single cleanup in TnsAI history.

PRs: #190, #191, #192, #193

[0.5.6] - 2026-04-28

Patch release. Broadens the FileToolProvider optional-dep isolation introduced in 0.5.5 to also cover JSONQueryTool and CSVParserTool, which the first pass missed.

Fixed

• FileToolProvider — JSONQueryTool (com.jayway.jsonpath optional dep) and CSVParserTool (com.opencsv optional dep) were still on the eager toolSuppliers() list. Same LinkageError failure mode as 0.5.5 (#184) — taking the whole provider down when a consumer pulled tnsai-tools without those transitives. Moved both to reflectiveToolClassNames() so missing optional deps are isolated per tool.

Changed

• FileToolProvider.toolSuppliers() now lists ONLY 3 pure-JDK tools (FileReadTool, FileWriteTool, XMLParserTool)
• FileToolProvider.reflectiveToolClassNames() now lists 8 optional-dep tools (JSONQueryTool, CSVParserTool, MarkItDownTool, 5× PDF*Tool)
• AbstractCategoryToolProviderIsolationTest updated for new split (controls = pure-JDK FQNs, base assertion ≥3)

Migration

None — pure bug fix. Behaviour-changing only when an optional dep is missing (failure now isolated as ToolLoadFailure, was complete provider crash).

PR: #186

[0.5.5] - 2026-04-28

Patch release. Fixes an all-or-nothing failure mode in FileToolProvider when a consumer pulls tnsai-tools without the optional Apache PDFBox or MarkItDown transitive dependencies.

Fixed

• FileToolProvider — eager XYZTool::new method-references in toolSuppliers() resolved their MethodHandle at List.of(...) evaluation time, outside the per-tool try/catch. Missing PDFBox or MarkItDown transitive → LinkageError from list construction → entire provider unloaded → 8 unrelated File tools (JSON, CSV, file IO, XML) became unavailable.

Added

• AbstractCategoryToolProvider.reflectiveToolClassNames() load path — Class.forName(name) defers linkage until inside the per-tool try/catch
• AbstractCategoryToolProviderIsolationTest (6 cases): pins the contract that missing FQN does not break a present sibling, and PDF failures are captured without propagating

Changed

• FileToolProvider: 6 optional-dep tools (MarkItDownTool, 5× PDF*Tool) moved from toolSuppliers() to reflectiveToolClassNames(). toolSuppliers() keeps the 5 base-JDK + opencsv tools.

Migration

None — pure bug fix. Behaviour-changing only when an optional dep is missing.

PR: #184

[0.5.4] - 2026-04-28

Minor-feature release. Annotation-driven runtime resolution sprint closing most of the umbrella tracked under [#169]. All additive (Phase 1 boundaries: no external storage / SPI deps); existing call sites unchanged for code that doesn't opt into the new annotations.

Added

• @LLMTool runtime path surfaced via LLMToolsExecutor ([#167]) + DataAnalystRole reference + BuiltInToolEnumAuditTest
• @WebService runtime path surfaced via WebServiceExecutor ([#174]) + WeatherRole reference
• com.tnsai.guardrails package — @InputGuardrail / @OutputGuardrail enforcement with minLength / maxLength / blockPatterns / allowPatterns + onFailure ∈ {REJECT, WARN, SANITIZE, REVIEW} ([#176])
• Optional RetrievalSpi in tnsai-core + default impl in tnsai-intelligence (RoleRagBinding, LocalFileSourceLoader, DefaultRetrievalSpi) — wires @KnowledgeSource / @Retrieval end-to-end ([#178])
• @ToolBinding declarative tool-input mapping with ${param} / ${role.name} / ${action.name} / ${env:VAR} substitution ([#179])
• com.tnsai.resilience decorators — @Traced (MDC trace-id), @Metered (in-memory ResilienceMetrics), @Fallback (forAction binding + immediate-retry) ([#182])
• 6 reference roles in tnsai-integration/scop/examples/: DataAnalystRole, WeatherRole, UserInputRole, ResearchRole, CsvLoaderRole, PaymentRole — each with its own integration test exercising the live ActionExecutor pipeline
• ActionParams.firstStringValueInDeclarationOrder shared helper

Changed

• @ToolBinding simplified to single-field tool() (was two mutually-exclusive builtIn + custom fields with BuiltInTool.NONE sentinel) — single source, identical syntax for built-in and custom tools ([#181] refactor of [#179])
• FallbackResolver.tryRecover and RetryCallback.invoke() narrowed catch (Throwable) → catch (Exception) (caught by SourceHygieneTest.noBroadThrowableCatches from #41)
• LLMToolsExecutor non-deterministic parameters.values().iterator().next() (HashMap iteration order is per-JVM) replaced with the new shared helper

Stats

• Tests: tnsai-core 2992 → 3047 (+55), tnsai-integration 78 → 129 (+51)
• Why not 0.6.0: every gap closed was a runtime path that was documented but unenforced — no API removals, no behaviour changes for non-opt-in code

Deferred to Phase 2+ (separate issues)

• @Sanitize / @ContentFilter standalone enforcement (#171 follow-up)
• InputValidator / InputSanitizer SPI for custom Class[] hooks
• @MemorySpec resolver (Persistence.REDIS / DATABASE / FILE)
• KnowledgeType source loaders (URL / VECTOR_DB / DATABASE / WEB_SEARCH)
• Embedding SPI replacing HashEmbeddingFunction
• @RateLimited, @Resilience(circuitBreaker), @Idempotent keyed cache (need distributed-state SPI)
• OpenTelemetry SPI for @Traced; Micrometer/Prometheus sink for @Metered
• Build-time validation (fail-fast on @ToolBinding typos)
• AuthType.API_KEY enum value ([#175])

PRs: #167, #174, #176, #178, #179, #181, #182

[0.5.3] — 2026-04-27

Patch release. 4 PRs (#156, #157, #158, #165) since v0.5.2. All additive — no public API removals, no behaviour regressions. Single theme: closing the ProviderErrorMapper SPI matrix at 13/13 shipping LLM providers (issue #87 fully resolved).

Added — Nine new ProviderErrorMappers (closes #87)

v0.5.2 shipped 4 mappers (OpenAI + Anthropic + Gemini + Ollama). This release adds the remaining 9 to complete coverage of every provider in tnsai-llm:

• MistralProviderErrorMapper (PR #156) — OpenAI-compatible envelope plus Mistral-specific code routing. Handles requests_too_many (alongside rate_limit_exceeded) → MODEL_OVERLOADED and Mistral's stricter model_quota_exceeded semantics. MistralAIClient.chat / streamChat refactored to executeRequest("Mistral").

• BedrockProviderErrorMapper (PR #157) — first mapper that works against AWS SDK exceptions, not HTTP responses. BedrockClient.mapAwsException extracts the AWS error code, reconstructs an AWS-shape envelope, propagates x-amzn-requestid via headers, and feeds the SPI mapper's HTTP-style API. Same SPI contract handles both code paths so consumers see typed LLMException regardless of transport.

• GroqProviderErrorMapper (PR #158) — OpenAI-compatible at the envelope level (Groq mirrors OpenAI's API by design); maps Groq's low-latency-specific codes (requests_too_many, queue saturation variants) to MODEL_OVERLOADED so consumer fallback chains treat them as transient. Captures groq-region header for routing-issue triage.

• OpenRouterProviderErrorMapper (in PR #165) — aggregator envelope. Surfaces the upstream provider name via metadata.provider_name so consumers triaging an OpenRouter failure can see which downstream provider actually misbehaved.

• AzureOpenAIProviderErrorMapper (in PR #165) — OpenAI-compat body, Azure deployment-id model field, captures apim-request-id / x-ms-region headers for Azure-specific triage. Distinguishes Azure's content_filter (Azure's responsible AI gating) from OpenAI's lexical codes.

• CohereProviderErrorMapper (in PR #165) — Cohere's RAG-focused API. Maps the command-r* model family appropriately; handles Cohere's distinct streaming JSON-lines envelope.

• HuggingFaceProviderErrorMapper (in PR #165) — covers both Inference API and custom Inference Endpoints. Critical: routes the model-loading-503 case to SERVER_ERROR (retryable) so cold models don't kill consumer requests on first hit.

• MiniMaxProviderErrorMapper (in PR #165) — handles two error envelopes simultaneously: OpenAI-compatible at /chat/completions (used by MiniMaxClient) AND native base_resp.status_code at /text/chatcompletion_v2 (used by partner-routed proxies). Native channel routes failures through HTTP 200 — the only signal is the JSON status code — so the mapper inspects base_resp first.

• ZhipuAIProviderErrorMapper (in PR #165) — closes the matrix at 13/13. Numeric-string codes clustered by family: 100x (auth/billing) → AUTHENTICATION_FAILED, 11xx (rate) → MODEL_OVERLOADED, 12xx (input/context) → INVALID_REQUEST / MODEL_NOT_FOUND / CONTEXT_TOO_LONG, 13xx (server) → SERVER_ERROR. Code shape normalisation handles both string and numeric JSON variants.

Refactor — every LLM client routes through executeRequest

All 13 clients now share the same error-translation entry point (AbstractLLMClient.executeRequest), eliminating per-client handleError / formatApiError divergence. Each client's chat / streamChat (and chat(List<ContentPart>) for vision-capable clients) is wrapped with a catch (LLMException) { throw e; } guard before the generic catch (Exception) translator so typed exceptions aren't double-wrapped.

Why patch (not minor)

• All 9 mappers are SPI-discovered (zero API surface change for consumers that don't read LLMException.getProviderDetails())
• Refactored chat / streamChat paths preserve identical ChatResponse returns; the only observable difference is that failures throw typed LLMException instead of the legacy generic wrapper
• Tests added (~150 new mapper test cases) without touching any existing passing test

Test coverage

195+ mapper-specific test cases across the 13 mappers. Aggregate mvn -pl tnsai-llm test reports 1072+ tests green.

Triggers release.yml on tag push. Sister-repo sync (Docs / Web / Sona / Wiki) follows the rule codified in CLAUDE.md (PR #149) — separate PRs in the same session.

[0.5.2] — 2026-04-27

Patch release. 4 PRs (#150–#154) since v0.5.1. Pure additive — no public API removals, no behaviour regressions. Themes: hardening the error-report pipeline shipped in #86 with a deduplicating decorator, and finally connecting the ProviderErrorMapper infrastructure that had been dead in the tree since 0.5.0.

Added — DedupingErrorReportPublisher (#86 follow-up, PR #150)

Decorator that wraps any ErrorReportPublisher and suppresses repeats of the same ErrorReport.fingerprint() within a configurable time window. First occurrence per window emits, rest are dropped and counted. Standard usage:

ErrorReports.setPublisher(
    DedupingErrorReportPublisher.wrap(new Slf4jErrorReportPublisher())
);

Default 5-minute window matches Sentry / Rollbar's standard. Surfaces "suppressed N duplicates in the previous window" log line on window roll. getSuppressedCount(fingerprint) exposes per-fingerprint counts as a Prometheus gauge.

Wired — ProviderErrorMapper SPI lookup (#87, PR #151)

Closes the wiring gap that left ErrorEmitter, ProviderErrorMapper SPI, and the OpenAI + Anthropic mappers (all shipped 0.5.0) entirely dead. AbstractLLMClient.executeRequest now snapshots HTTP error headers + body, looks up the SPI mapper for the provider, and throws the typed LLMException directly with ProviderDetails attached. Falls back to the legacy IOException path when no mapper is registered.

OpenAIClient and AnthropicClient catch blocks now catch (LLMException) { throw e; } before the generic catch so a mapper-derived exception isn't double-wrapped (ProviderDetails would have ended up on ex.getCause() otherwise).

AnthropicClient.chat / streamChat refactored from inline response.isSuccessful() handling to executeRequest("Anthropic") so the SPI mapper is actually reached — same applies to follow-ups below.

Added — Two new ProviderErrorMappers

• GeminiProviderErrorMapper (PR #152) — Google API-Gateway envelope (error.{code,message,status}). Routes the canonical google.rpc.Code strings (RESOURCE_EXHAUSTED → MODEL_OVERLOADED, UNAUTHENTICATED / PERMISSION_DENIED → AUTHENTICATION_FAILED, INVALID_ARGUMENT → INVALID_REQUEST with token-hint demotion to CONTEXT_TOO_LONG, etc.). Captures x-goog-* + retry-after headers. GeminiClient.chat / streamChat refactored to use executeRequest.

• OllamaProviderErrorMapper (PR #154) — heuristic on the free-text error string (Ollama has no structured codes): "not found" / "no such model" / "try pulling" → MODEL_NOT_FOUND; "context" / "exceeds" / "token" → CONTEXT_TOO_LONG; "out of memory" / "VRAM" / "OOM" → MODEL_OVERLOADED. HTTP fallback with 503 → MODEL_OVERLOADED (daemon temporarily unavailable). No headers captured — local Ollama doesn't carry diagnostic headers worth keeping. Defensive on envelope shape (handles both error as plain string and as object with message field). OllamaClient.chat / streamChat refactored to use executeRequest.

Provider mapper coverage

Sona's full default model lineup (anthropic / openai / gemini / ollama) now has typed error mapping for 4/4 providers.

Out of scope (follow-up issues)

Nine remaining ProviderErrorMappers (Bedrock, Azure, Cohere, Groq, HuggingFace, OpenRouter, MiniMax, ZhipuAI, Mistral). Each follows the established pattern — one mapper class + one SPI registry line

• unit tests + (if the client uses inline error handling) the executeRequest refactor.

[0.5.1] — 2026-04-27

Patch release. 6 PRs (#139–#147) since v0.5.0. Pure additive — no public API removals, no behaviour regressions. Themes: completing the build-time validation pipeline started in #85, wiring agent context capture for exception enrichment (#90), and shipping the error-report emission pipeline (#86).

Added — build-time validators (tnsai-core / agents/validation/validators/)

Four new validators land in AgentBuilder.VALIDATORS, each running during build() against a ValidationContext snapshot:

• AGENT-V006 ToolApprovalValidator — WARNING when a registered tool reports requiresConfirmation()==true but the agent has no built-in confirmation channel wired (the operator must call agent.setToolCallFilter(...) post-build, otherwise calls block indefinitely waiting for a confirmation that never arrives).
• AGENT-V007 CapabilityClasspathValidator — ERROR when a @Capability interface implemented by a role can't be fully reflected on (parameter / return type or annotation value references a class missing from the runtime classpath).
• AGENT-V008 ActionNameCollisionValidator — ERROR when two roles declare @ActionSpec methods with the same name; today the framework's name → action map silently keeps whichever role was registered last.
• AGENT-V009 ResilienceConfigValidator — ERROR for clearly invalid @Resilience numerics (negative timeout / maxAttempts / backoff, multiplier < 1.0, failureRateThreshold outside 0–100); WARNING for configured-but-effectively-disabled subsystems (@Retry with non-default fields but maxAttempts==0, @CircuitBreaker(enabled=true) with non-positive failureThreshold, @RateLimit(enabled=true) with maxRequests<=0).

Suppress any individual issue with AgentBuilder.relaxValidation("AGENT-V0xx").

Added — error context capture wiring (tnsai-core / agents/Agent.java)

Agent.java's 11 public chat / stream / executeAction entry points now wrap their delegation in try (var ignored = AgentContext.enter(buildEntryContext(op))).

Net effect: any TnsAIException thrown deep inside the orchestrator auto-captures the current agent + role + traceId via AgentContext.currentOptional(), so getMessage() / getContext() surface attribution without consumer plumbing. Top-level entries get a fresh trace id; nested entries (agent-from-tool, agent-from- hook) inherit upstream tenantId / sessionId / traceId / spanId while overwriting agentId / role.

The entry op ("chat", "executeAction:summarize", …) lands in EventContext.extensions["agent.entry.op"] for log filtering.

Added — error report emission pipeline (tnsai-core / observability/errors/)

The ErrorEmitter factory shipped with 0.5.0 had no companion publisher — consumers could construct an ErrorReport but had nowhere to send it. This release ships the pipeline mirroring the AgentEventPublisher pattern from #78:

• ErrorReportPublisher — single-method SPI. Discovered via ServiceLoader; consumers add Sentry / Loki / custom sinks by dropping a JAR with a META-INF/services/com.tnsai.observability.errors.ErrorReportPublisher entry.
• Slf4jErrorReportPublisher (default, SPI-registered) — JSON-serializes the report via Jackson + Jdk8Module (so Optional<T> unwraps to value-or-null) + JavaTimeModule. Logs at WARN for TRANSIENT / RESOURCE / EXTERNAL categories (self-healing or expected backpressure), ERROR for everything else.
• CompositeErrorReportPublisher — fan-out over multiple publishers with per-publisher failure isolation (one throwing publisher doesn't stop the others).
• CapturingErrorReportPublisher — in-memory test workhorse, not SPI-registered. Wire via ErrorReports.setPublisher(...) and tear down via ErrorReports.resetForTesting().
• ErrorReports — static facade with lazy SPI discovery. The one-line emit entry point:

  ErrorReports.publish(throwable, ErrorCategory.TRANSIENT,
          Map.of("provider", "openai", "model", "gpt-4o"));

Tests

+30 new tests (4 validators × ~10, 5 entry-point context, 11 error report pipeline). Full tnsai-core suite green except for a pre-existing CancellationTokenTest$Concurrency.registerWhileCancellingStillFires flake (passes in isolation; unrelated to this release).

Out of scope (follow-up issues)

• #144 — AGENT-V003 code collision (ToolNameUniquenessValidator and LLMCapabilityValidator both report under V003); rename pending operator approval (Protected Change per CLAUDE.md).
• #145 — AGENT-V004 LLM streaming/structured/vision capability validator needs a builder capability-declaration API first.
• #146 — AGENT-V012 tenant-scope validator + #92 per-tenant error budget both blocked on a multi-tenant runtime feature that doesn't exist yet.
• DedupingErrorReportPublisher decorator (TTL'd fingerprint suppression) — natural #86 successor; deferred.
• Wiring TnsAIException.<init> to auto-publish — would double-publish for caught-and-rethrown chains; needs a different attach point.

[0.5.0] — 2026-04-26

Feature-batch release. 19 PRs (#119–#137) since v0.4.0. Major themes: agent lifecycle FSM, cooperative cancellation, tool-policy + risk-metadata SPI, Anthropic ephemeral prompt-caching wire format, Telegram retry-on-transient transport, build-time validation pipeline (one new validator), @ToolFailureMode annotation, ModelFamily / TimeoutPolicy / DestructiveCommandDetector standalones, and a SCOPBridge prompt-rendering overhaul that closes 4 drift bugs against RolePromptBuilder.

Added — types

• AgentState enum extended to the full lifecycle FSM (CREATED → STARTING → RUNNING → STOPPING → STOPPED, plus terminal FAILED). The seed value READY from 0.4.0 is removed — see Removed.
• Agent.getState() — new public accessor on every Agent.
• com.tnsai.tools.ToolRiskLevel + SideEffect enums.
• com.tnsai.tools.policy package: ToolPolicy (ALLOW_ALL / DENY_ALL / SAFE_ONLY), ToolPolicyDecision, ToolPolicyEvaluator, plus com.tnsai.hooks.policy.ToolPolicyHook consuming it via Hook<PreToolUse>.
• com.tnsai.cancellation package: CancellationToken interface, CancellationException, DefaultCancellationToken (one-shot CAS), NoopCancellationToken (singleton no-op).
• com.tnsai.timeout.TimeoutPolicy record with Category enum (LLM_CALL / TOOL_CALL / MCP_CALL / CHANNEL_SEND) and UNBOUNDED sentinel.
• com.tnsai.prompt.ModelFamily enum + fromModelId(String) best-effort mapper covering Claude / GPT / Gemini / Llama naming conventions.
• com.tnsai.tools.spi.ToolFailureMode annotation + ToolFailureModeReader resolver — tool authors declare retryable / non-retryable exception classes; nonRetryable beats retryable in conflict resolution.
• com.tnsai.security.DestructiveCommandDetector in tnsai-quality: content-level ToolCallFilter with a 21-pattern catalogue (rm -rf, git reset --hard, dd to /dev/, mkfs, chmod 777/000, kill -9 broadcasts, redirects to /etc/* / ~/.ssh/*, sudo rm/dd, shutdown / reboot --force, shred -ru, wipefs --force).
• LLMCapabilityValidator — fourth validator in the AgentBuilder pre-flight pipeline (issue #85 slice). Catches the canonical "tools registered + LLM doesn't support function-calling" misconfiguration at build time with stable code AGENT-V003.
• DiscoveredRoleActions.getActions() — public list accessor.

Added — interface extensions (default methods, additive)

• Tool.getRiskLevel() → ToolRiskLevel.MEDIUM, getRequiredSecrets() → empty Set<String>, getTimeout() → Duration.ofSeconds(30), getSideEffects() → empty Set<SideEffect>.
• AgentPromptBuilder.buildSystemPrompt(..., ModelFamily) overload — Claude gets a softer suggestive register; GPT / Gemini / Llama / OTHER share the historical imperative wording byte-for-byte.
• AnthropicClient.Builder.enableEphemeralCaching(boolean) + cacheLastNTurns(int) — wires cache_control: ephemeral markers into system + last N user messages (capped at the 4-per-request Anthropic limit).
• OpenRouterClient.setFineGrainedToolStreaming(boolean) with auto-detection from model id — adds x-anthropic-beta: fine-grained-tool-streaming-2025-05-14 on the wire when routing to Claude.

Added — infrastructure & tests

• PIT mutation-testing pilot (-Pmutation-testing profile in tnsai-core/pom.xml) — baselines 74% mutation coverage. Doc: tnsai-core/agent_docs/mutation-testing.md.
• SourceHygieneTest in tnsai-core — regression gate forbidding catch (Exception ignored) and catch (Throwable t) in main sources (issue #10).
• ProviderEnvVarConsistencyTest in tnsai-llm — drift gate for requireApiKey call sites + README env-var matrix.
• Harness evolution audit doc at tnsai-core/agent_docs/harness-audit.md.

Changed — behaviour

• Agent.chat() rejects calls when the agent is STOPPING, STOPPED, or FAILED with IllegalStateException.
• Agent.stop() is idempotent.
• ExternalScriptHook.apply() narrowed catch (Throwable t) → catch (IOException | RuntimeException t). JVM-fatal Error subclasses propagate now.
• TelegramAdapter.send() retries 429 / 5xx with exponential backoff (1s, 2s) up to 3 attempts.
• BridgeLLMClient.streamChat() throws LLMCapabilityException (was silent degrade to single-element synthetic stream).
• BridgeLLMClient.chat() throws typed LLMException (was raw RuntimeException).
• BridgeLLMClient.getCapabilities() overrides model-id guess with honest transport-bound limits.
• SystemPromptBuilder state + action sections aligned byte-for-byte with RolePromptBuilder. @PromptTemplates + @State.template + @State.invariants honoured.
• LLMConfiguration env lookups switched from raw System.getenv() to Core's EnvLoader.get() (3 sites).

Removed

• AgentState.READY — the 0.4.0 seed value (placeholder for the lifecycle FSM that landed in this release). Migrate to AgentState.RUNNING. No @Deprecated shim per project rule.

Migration notes

• AgentState.READY → AgentState.RUNNING (search-and-replace).
• Agent.chat() after stop() now throws IllegalStateException.
• BridgeLLMClient.streamChat() now throws — install tnsai-llm for real streaming, or call chat() for buffered single-shot.
• BridgeLLMClient.chat() failures: catch LLMException (or parent TnsAIException) instead of RuntimeException.
• SCOP-rendered prompts changed format. Pinned-format tests should update to the canonical RolePromptBuilder shape.

For Consumers

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.tansuasici</groupId>
            <artifactId>tnsai-bom</artifactId>
            <version>0.5.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

[0.4.0] — 2026-04-22

Major: Monorepo migration

The framework's 11 modules (previously hosted as 11 separate GitHub repositories) have been consolidated into a single TnsAI-Framework/TnsAI monorepo. Each module's full commit history is preserved under its subdirectory via git filter-repo.

Added

• tnsai-parent — root POM aggregating all modules with shared plugin/dependency configuration, release profile, GPG signing, and Maven Central publishing.
• tnsai-bom — Bill of Materials artifact that pins every tnsai-* module to a single coherent version. Consumers import once and use modules without version declarations.
• @Capability pattern (from former TnsAI.Core 0.3.1 pre-release work): reusable action contracts as interfaces with default bodies that throw Actions.dispatchedByFramework(). See tnsai-core/src/main/java/com/tnsai/capabilities/Capability.java.
• ActionDiscovery two-pass scanning: walks role class methods first, then capability interface chains (including super-interfaces). Class-declared methods win de-duplication; role can override any capability's default with a concrete ActionType.LOCAL implementation.

Changed

• Framework is now released as a single lockstep version. Bumping the version touches only the root pom.xml; children inherit via <parent>.
• CI consolidated into one .github/workflows/build.yml plus release.yml. Cross-repo clone / DEPS_PAT pattern retired.
• Each child pom.xml shrinks from ~400 lines to ~50–100 lines.

For Consumers

Depend on the framework via the BOM:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.tansuasici</groupId>
            <artifactId>tnsai-bom</artifactId>
            <version>0.4.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.github.tansuasici</groupId>
        <artifactId>tnsai-core</artifactId>
    </dependency>
    <!-- pick any module you need — versions come from the BOM -->
</dependencies>

[0.3.0] - 2026-04-18

First coordinated release across all 11 modules. Published to Maven Central via Central Portal. Previous 0.2.x releases were development-only (per-module Maven snapshots, never on Central).

Added

• All 11 framework modules (tnsai-core, tnsai-llm, tnsai-intelligence, tnsai-coordination, tnsai-quality, tnsai-evaluation, tnsai-mcp, tnsai-tools, tnsai-channels, tnsai-integration, tnsai-server) published to Maven Central under io.github.tansuasici

Notes

For change details prior to this coordinated release, see per-module git history under each tnsai-*/ subdirectory in the monorepo (history was preserved during the 0.4.0 monorepo migration).