@vinkius-core/mcp-fusion 1.6.0 → 1.6.2

package/CHANGELOG.md

@@ -4,6 +4,78 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.6.2] - 2026-02-23
+
+### 🧪 End-to-End Integration Test Suite
+
+Comprehensive integration test suite (`tests/integration/FullStack.test.ts`) covering **all modules working together** through the MCP Server mock — happy paths AND sad paths. Ensures the framework resolves developer mistakes gracefully without crashing.
+
+### Added
+
+- **37 integration tests** in `FullStack.test.ts` organized across 22 `describe` blocks:
+
+  **Happy paths (15 tests):**
+  - Builder → Registry → Server → ContextFactory
+  - Builder → Presenter → Server (auto-view composition)
+  - Builder → Middleware → Debug Observability (cross-layer events)
+  - Builder → Middleware → Tracing (OTel span lifecycle)
+  - Builder → StateSync → Server (cache-control + invalidation)
+  - PromptRegistry → Server (prompts/list + prompts/get)
+  - Builder → Flat Exposition → Server (atomic tool projection)
+  - Flat Exposition → Debug + Tracing (2 tests)
+  - Full Stack — ALL modules in a single server attachment
+  - Concurrent multi-tool calls (20 parallel + traced, 2 tests)
+  - Presenter → Tracing → Server
+  - Detach → Re-attach lifecycle
+  - defineMiddleware → defineTool → Server
+
+  **Sad paths (22 tests):**
+  - **Routing Failures (4):** Unknown tool (`UNKNOWN_TOOL` + suggestions), unknown action, missing/null/empty discriminator, unknown flat tool name
+  - **Validation Failures (3):** Wrong types, constraint violations (min/max/email), strict mode extra field rejection, flat mode validation
+  - **Handler Exceptions (3):** Handler `throw` → `isError=true` (grouped + flat), soft fail vs hard fail tracing distinction (`UNSET` vs `ERROR` + `recordException`)
+  - **Middleware Failures (3):** Middleware block + debug error event, middleware exception traced as system error, multi-middleware chain ordering (first blocker wins)
+  - **Concurrent Mixed Results (1):** 5 simultaneous calls — 2 success + 1 validation error + 1 throw + 1 unknown action — isolated
+  - **Debug + Tracing Error Correlation (2):** Debug error for unknown tool, traced validation error when both debug+tracing coexist
+  - **defineTool Param Descriptor Errors (2):** Constraint violations via descriptors, shared param missing/empty
+  - **StateSync Config Errors (2):** Invalid `cacheControl` directives rejected at attach time
+  - **Detach Error Handling (2):** Post-detach calls return error, tools/list returns empty, double detach is idempotent
+
+- **Mock strategy:** Only the MCP Server is mocked — no internal framework mocking. Tests exercise the full pipeline (routing → validation → middleware → handler → observability → response).
+
+### Test Suite
+
+- **1,492 tests** across 68 files, all passing.
+
+## [1.6.1] - 2026-02-23
+
+### 🛡️ XML Security & Error Protocol Hardening
+
+Comprehensive security audit of the XML error protocol. Prevents XML injection, hardens type safety, and upgrades the registry-level error to the structured `toolError()` protocol.
+
+### Security
+
+- **XML injection prevention:** Introduced `escapeXml()` (element content — escapes `&` and `<`) and `escapeXmlAttr()` (attribute values — escapes all 5 XML special characters). Applied across `response.ts`, `ExecutionPipeline.ts`, `ValidationErrorFormatter.ts`, and `PromptExecutionPipeline.ts`.
+- **Dual escaping strategy:** Element content preserves `>` for LLM readability (`>= 1`, `Must be > 0`). Attribute values use strict escaping.
+
+### Fixed
+
+- **Type safety in `parseDiscriminator`:** Replaced unsafe `as string` cast with runtime `typeof` check. Non-string discriminator values (numbers, booleans, objects) now return `MISSING_DISCRIMINATOR` instead of causing `TypeError: str.replace is not a function`.
+- **Structured `UNKNOWN_TOOL` error:** `ToolRegistry.routeCall()` now returns `toolError('UNKNOWN_TOOL', ...)` with structured XML (code, message, available tools, recovery hint) instead of a freeform `error()` string. Consistent with pipeline-level errors (`MISSING_DISCRIMINATOR`, `UNKNOWN_ACTION`).
+
+### Documentation
+
+- **error-handling.md:** Added `UNKNOWN_TOOL` to the Unified XML Protocol table. Added XML Security tip callout.
+- **llms.txt:** Added XML security note with pipeline error codes. Added `unknown_tool` to tracing error classification.
+
+### DX
+
+- **English error messages:** Translated remaining Portuguese error message in `defineTool.ts` to English.
+
+### Test Suite
+
+- **1,389 tests** across 417 suites, all passing.
+
 ## [1.6.0] - 2026-02-23
 
 ### 🔗 MVA-Driven Prompts — `PromptMessage.fromView()`

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <h1>⚡️ mcp-fusion</h1>
+  <h1>⚡️ **MCP Fusion**</h1>
   <p><b>The MVA (Model-View-Agent) framework for the Model Context Protocol.</b></p>
   <p>Structured perception for AI agents — validated data, domain rules, UI blocks, and action affordances in every response.</p>
   
@@ -21,7 +21,7 @@ npm install @vinkius-core/mcp-fusion zod
 
 ## Overview
 
-mcp-fusion introduces the **MVA (Model-View-Agent)** pattern — a Presenter layer between your data and the AI agent. Instead of passing raw JSON through `JSON.stringify()`, every response is a **structured perception package**: validated data, domain rules, rendered charts, action affordances, and cognitive guardrails.
+**MCP Fusion** introduces the **MVA (Model-View-Agent)** pattern — a Presenter layer between your data and the AI agent. Instead of passing raw JSON through `JSON.stringify()`, every response is a **structured perception package**: validated data, domain rules, rendered charts, action affordances, and cognitive guardrails.
 
 ```text
 Model (Zod Schema) → View (Presenter) → Agent (LLM)
@@ -258,10 +258,12 @@ return toolError('ProjectNotFound', {
 });
 ```
 
-```text
-[ProjectNotFound] Project 'xyz' does not exist.
-💡 Suggestion: Call projects.list first to get valid IDs.
-📋 Try: projects.list
+```xml
+<tool_error code="ProjectNotFound">
+<message>Project 'xyz' does not exist.</message>
+<recovery>Call projects.list first to get valid IDs.</recovery>
+<available_actions>projects.list</available_actions>
+</tool_error>
 ```
 
 ---

package/dist/{framework/client → client}/FusionClient.d.ts

@@ -25,7 +25,7 @@
  *
  * @module
  */
-import { type ToolResponse } from '../response.js';
+import { type ToolResponse } from '../core/response.js';
 /**
  * Transport interface for the fusion client.
  * This abstracts the MCP transport layer (stdio, HTTP, WebSocket, etc.)

package/dist/client/FusionClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FusionClient.d.ts","sourceRoot":"","sources":["../../src/client/FusionClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMxD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAChF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,YAAY,CAAC,OAAO,SAAS,SAAS;IACnD;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,SAAS,MAAM,OAAO,GAAG,MAAM,EAC1C,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GACvB,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,SAAS,EACxD,SAAS,EAAE,eAAe,GAC3B,YAAY,CAAC,OAAO,CAAC,CAqBvB"}

package/dist/{framework/client → client}/FusionClient.js

@@ -25,7 +25,7 @@
  *
  * @module
  */
-import {} from '../response.js';
+import {} from '../core/response.js';
 // ============================================================================
 // Factory
 // ============================================================================

package/dist/client/FusionClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FusionClient.js","sourceRoot":"","sources":["../../src/client/FusionClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAqB,MAAM,qBAAqB,CAAC;AAoDxD,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,kBAAkB,CAC9B,SAA0B;IAE1B,OAAO;QACH,KAAK,CAAC,OAAO,CACT,MAAe,EACf,IAAsB;YAEtB,mDAAmD;YACnD,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACrC,IAAI,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;gBAClB,OAAO,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC5C,CAAC;YAED,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YAC/C,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;YAElD,OAAO,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE;gBAChC,MAAM,EAAE,UAAU;gBAClB,GAAG,IAAI;aACV,CAAC,CAAC;QACP,CAAC;KACJ,CAAC;AACN,CAAC"}

package/dist/{framework/client → client}/InferRouter.d.ts

@@ -26,7 +26,8 @@
  *
  * @module
  */
-import { type GroupedToolBuilder } from '../builder/GroupedToolBuilder.js';
+import { type GroupedToolBuilder } from '../core/builder/GroupedToolBuilder.js';
+import { type ToolRegistry } from '../core/registry/ToolRegistry.js';
 /**
  * A typed wrapper around `ToolRegistry` that preserves builder types
  * for compile-time router inference.
@@ -40,7 +41,7 @@ import { type GroupedToolBuilder } from '../builder/GroupedToolBuilder.js';
  */
 export interface TypedToolRegistry<TContext, TBuilders extends readonly unknown[]> {
     /** The underlying ToolRegistry instance (for runtime use) */
-    readonly registry: import('../registry/ToolRegistry.js').ToolRegistry<TContext>;
+    readonly registry: ToolRegistry<TContext>;
     /** Branded field for type inference — never accessed at runtime */
     readonly _builders: TBuilders;
     /** Branded phantom type for context inference */

package/dist/client/InferRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InferRouter.d.ts","sourceRoot":"","sources":["../../src/client/InferRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAMrE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB,CAAC,QAAQ,EAAE,SAAS,SAAS,SAAS,OAAO,EAAE;IAC7E,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC1C,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC/B;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IACrB,CAAC,SAAS,iBAAiB,CAAC,MAAM,KAAK,EAAE,MAAM,SAAS,CAAC,GACnD,uBAAuB,CAAC,SAAS,CAAC,GAClC,CAAC,SAAS,SAAS,OAAO,EAAE,GACxB,uBAAuB,CAAC,CAAC,CAAC,GAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,KAAK,uBAAuB,CAAC,CAAC,IAC1B,CAAC,SAAS,SAAS,CAAC,MAAM,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,GACzC,gBAAgB,CAAC,KAAK,CAAC,GAAG,uBAAuB,CAAC,IAAI,CAAC,GACvD,CAAC,SAAS,SAAS,EAAE,GAEjB,EAAE,GACF,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEtD;;;;;;;GAOG;AACH,KAAK,gBAAgB,CAAC,CAAC,IACnB,CAAC,SAAS,kBAAkB,CAAC,MAAM,KAAK,EAAE,MAAM,QAAQ,EAAE,MAAM,MAAM,EAAE,MAAM,UAAU,CAAC,GACnF,UAAU,GACV,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC"}

package/dist/{framework/client → client}/InferRouter.js

@@ -26,5 +26,6 @@
  *
  * @module
  */
-import {} from '../builder/GroupedToolBuilder.js';
+import {} from '../core/builder/GroupedToolBuilder.js';
+import {} from '../core/registry/ToolRegistry.js';
 //# sourceMappingURL=InferRouter.js.map

package/dist/client/InferRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InferRouter.js","sourceRoot":"","sources":["../../src/client/InferRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAA2B,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAqB,MAAM,kCAAkC,CAAC"}

package/dist/{framework/client → client}/createTypedRegistry.d.ts

@@ -1,4 +1,4 @@
-import { type ToolBuilder } from '../types.js';
+import { type ToolBuilder } from '../core/types.js';
 import { type TypedToolRegistry } from './InferRouter.js';
 /**
  * Create a type-preserving tool registry.

package/dist/client/createTypedRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTypedRegistry.d.ts","sourceRoot":"","sources":["../../src/client/createTypedRegistry.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,MACvB,SAAS,SAAS,WAAW,CAAC,QAAQ,CAAC,EAAE,EACtD,GAAG,UAAU,SAAS,KACvB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAS5C"}

package/dist/{framework/client → client}/createTypedRegistry.js

@@ -36,8 +36,8 @@
  *
  * @module
  */
-import { ToolRegistry } from '../registry/ToolRegistry.js';
-import {} from '../types.js';
+import { ToolRegistry } from '../core/registry/ToolRegistry.js';
+import {} from '../core/types.js';
 import {} from './InferRouter.js';
 /**
  * Create a type-preserving tool registry.

package/dist/client/createTypedRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTypedRegistry.js","sourceRoot":"","sources":["../../src/client/createTypedRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAoB,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAA0B,MAAM,kBAAkB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,mBAAmB;IAC/B,OAAO,UACH,GAAG,QAAmB;QAEtB,MAAM,QAAQ,GAAG,IAAI,YAAY,EAAY,CAAC;QAC9C,QAAQ,CAAC,WAAW,CAAC,GAAG,QAAQ,CAAC,CAAC;QAClC,OAAO;YACH,QAAQ;YACR,SAAS,EAAE,QAAQ;YACnB,QAAQ,EAAE,SAAgC;SAC7C,CAAC;IACN,CAAC,CAAC;AACN,CAAC"}

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EACR,YAAY,EACZ,eAAe,EACf,SAAS,GACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAMvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/core/builder/ActionGroupBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionGroupBuilder.d.ts","sourceRoot":"","sources":["../../../src/core/builder/ActionGroupBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AACvD,OAAO,EACH,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EACpB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,iBAAiB,CAAC,QAAQ,EAAE,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAC3E,CAAC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAI3D;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAC5C,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,EAC9B,gBAAgB,EAAE,MAAM,EAAE,GAAG,SAAS,GACvC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAC5B,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,aAAa,GACvD,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CACzE,CAYA;AAID,qBAAa,kBAAkB,CAAC,QAAQ,EAAE,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IACrG,gBAAgB;IAChB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAM;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAgC;IAClE,OAAO,CAAC,gBAAgB,CAAgB;gBAE5B,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;IAKnD;;;;;;;;;;;;;;;;;;OAkBG;IACH,GAAG,CAAC,EAAE,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,IAAI;IAKrC;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAKrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,OAAO,SAAS,SAAS,CAAC,WAAW,CAAC,EAAE,KAAK,SAAS,MAAM,OAAO,GAAG,KAAK,EAAE,MAAM,EAAE;QACxF,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,OAAO,CAAC;QAChB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC;QACrB,OAAO,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;KACtG,GAAG,IAAI;IACR,gEAAgE;IAChE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,GAAG,IAAI;CAuB/C"}

package/dist/core/builder/ActionGroupBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionGroupBuilder.js","sourceRoot":"","sources":["../../../src/core/builder/ActionGroupBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAoC,MAAM,KAAK,CAAC;AACvD,OAAO,EAKN,MAAM,aAAa,CAAC;AAsBrB,4DAA4D;AAE5D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CACnC,MAA8B,EAC9B,gBAAsC;IAKtC,OAAO;QACH,UAAU,EAAE,MAAM,CAAC,IAAI;QACvB,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,SAAS;QAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,SAAS;QAClC,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,SAAS;QAC5C,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,SAAS;QAC1C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,SAAS;QACtC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,gBAAgB,EAAE,CAAC,gBAAgB,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS;QACpF,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,SAAS;KACvC,CAAC;AACN,CAAC;AAED,4DAA4D;AAE5D,MAAM,OAAO,kBAAkB;IAC3B,gBAAgB;IACP,QAAQ,GAA+B,EAAE,CAAC;IAClC,UAAU,CAAS;IACnB,iBAAiB,CAAS;IAC1B,iBAAiB,GAA6B,EAAE,CAAC;IAC1D,gBAAgB,GAAa,EAAE,CAAC;IAExC,YAAY,SAAiB,EAAE,WAAoB;QAC/C,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,iBAAiB,GAAG,WAAW,IAAI,EAAE,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,GAAG,CAAC,EAA0B;QAC1B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,GAAG,MAAgB;QAC1B,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IAChB,CAAC;IA6CD,MAAM,CAAC,MAA8B;QACjC,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACX,gBAAgB,MAAM,CAAC,IAAI,2BAA2B;gBACtD,oEAAoE,CACvE,CAAC;QACN,CAAC;QAED,qDAAqD;QACrD,MAAM,SAAS,GAAI,MAAoC,CAAC,UAAU,IAAI,EAAE,CAAC;QACzE,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,gBAAgB,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAE1E,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACf,GAAG,EAAE,GAAG,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,IAAI,EAAE;YACxC,SAAS,EAAE,IAAI,CAAC,UAAU;YAC1B,gBAAgB,EAAE,IAAI,CAAC,iBAAiB;YACxC,GAAG,uBAAuB,CAAC,MAAM,EAAE,UAAU,CAAC;YAC9C,WAAW,EAAE,IAAI,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC;gBAC1C,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,SAAS;SAChD,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ"}

package/dist/{framework → core}/builder/GroupedToolBuilder.d.ts

@@ -46,8 +46,8 @@
 import { type ZodObject, type ZodRawShape } from 'zod';
 import { type Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
 import { type ToolResponse, type ToolBuilder, type ActionMetadata, type InternalAction, type MiddlewareFn, type ActionConfig } from '../types.js';
-import { type DebugObserverFn } from '../observability/DebugObserver.js';
-import { type FusionTracer } from '../observability/Tracing.js';
+import { type DebugObserverFn } from '../../observability/DebugObserver.js';
+import { type FusionTracer } from '../../observability/Tracing.js';
 import { type ProgressSink } from '../execution/ProgressHelper.js';
 import { type GroupConfigurator } from './ActionGroupBuilder.js';
 export { ActionGroupBuilder } from './ActionGroupBuilder.js';
@@ -478,18 +478,26 @@ export declare class GroupedToolBuilder<TContext = void, TCommon extends Record<
      * ```
      */
     execute(ctx: TContext, args: Record<string, unknown>, progressSink?: ProgressSink): Promise<ToolResponse>;
-    /** Fast path: zero overhead — no conditionals, no timing, no allocations. */
-    private _executeFast;
-    /** Debug path: emit structured DebugEvent at each step (unchanged from pre-tracing). */
-    private _executeDebug;
     /**
-     * Traced path: OpenTelemetry-compatible span creation.
+     * Pipeline hooks for observability instrumentation.
+     *
+     * Each hook is called at the corresponding pipeline step.
+     * The fast path passes `undefined` (zero overhead).
+     * Debug and traced paths supply their hooks via factory methods.
+     */
+    private _executePipeline;
+    /**
+     * Build debug hooks: lightweight event emission.
+     */
+    private _buildDebugHooks;
+    /**
+     * Build traced hooks: OpenTelemetry-compatible span creation.
      *
      * Creates ONE span per tool call with events for pipeline steps.
-     * Uses `finally` for leak-proof span closure.
+     * Uses wrapResponse for leak-proof span closure.
      * AI errors → UNSET, system errors → ERROR.
      */
-    private _executeTraced;
+    private _buildTracedHooks;
     /** Get the tool name. */
     getName(): string;
     /** Get a copy of the capability tags. */

package/dist/core/builder/GroupedToolBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupedToolBuilder.d.ts","sourceRoot":"","sources":["../../../src/core/builder/GroupedToolBuilder.ts"],"names":[],"mappings":"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"}

package/dist/{framework → core}/builder/GroupedToolBuilder.js

@@ -47,11 +47,12 @@ import {} from 'zod';
 import {} from '@modelcontextprotocol/sdk/types.js';
 import { error } from '../response.js';
 import {} from '../types.js';
-import {} from '../observability/DebugObserver.js';
-import { SpanStatusCode } from '../observability/Tracing.js';
+import {} from '../../observability/DebugObserver.js';
+import { SpanStatusCode } from '../../observability/Tracing.js';
 import { getActionRequiredFields } from '../schema/SchemaUtils.js';
 import { parseDiscriminator, resolveAction, validateArgs, runChain, } from '../execution/ExecutionPipeline.js';
 import {} from '../execution/ProgressHelper.js';
+import { computeResponseSize } from '../execution/PipelineHooks.js';
 import { compileToolDefinition } from './ToolDefinitionCompiler.js';
 import { ActionGroupBuilder, mapConfigToActionFields, } from './ActionGroupBuilder.js';
 // ── Re-exports for Public API Compatibility ──────────────
@@ -515,87 +516,121 @@ export class GroupedToolBuilder {
         if (!execCtx) {
             return error(`Builder "${this._name}" failed to initialize.`);
         }
-        // Path 1: Tracing — full span hierarchy (enterprise)
+        // Traced path: wrap in try/catch for system error → graceful response
         if (this._tracer) {
-            return this._executeTraced(execCtx, ctx, args, progressSink);
+            const hooks = this._buildTracedHooks();
+            try {
+                return await this._executePipeline(execCtx, ctx, args, progressSink, hooks);
+            }
+            catch (err) {
+                // System failure caught here — hooks already recorded it on the span
+                const message = err instanceof Error ? err.message : String(err);
+                const response = error(`[${this._name}] ${message}`);
+                hooks.wrapResponse(response); // finalize span
+                return response;
+            }
         }
-        // Path 2: Debug — lightweight event emission (backward compat)
+        // Debug path: hooks with event emission
         if (this._debug) {
-            return this._executeDebug(execCtx, ctx, args, progressSink);
+            return this._executePipeline(execCtx, ctx, args, progressSink, this._buildDebugHooks());
         }
-        // Path 3: Fast — zero overhead (no observability)
-        return this._executeFast(execCtx, ctx, args, progressSink);
+        // Fast path: zero overhead (no hooks)
+        return this._executePipeline(execCtx, ctx, args, progressSink);
     }
     // ── Execution Paths (private) ────────────────────────
-    /** Fast path: zero overhead — no conditionals, no timing, no allocations. */
-    async _executeFast(execCtx, ctx, args, progressSink) {
-        const disc = parseDiscriminator(execCtx, args);
-        if (!disc.ok)
-            return disc.response;
-        const resolved = resolveAction(execCtx, disc.value);
-        if (!resolved.ok)
-            return resolved.response;
-        const validated = validateArgs(execCtx, resolved.value, args);
-        if (!validated.ok)
-            return validated.response;
-        return runChain(execCtx, resolved.value, ctx, validated.value, progressSink);
-    }
-    /** Debug path: emit structured DebugEvent at each step (unchanged from pre-tracing). */
-    async _executeDebug(execCtx, ctx, args, progressSink) {
-        const debug = this._debug;
-        const startTime = performance.now();
+    /**
+     * Pipeline hooks for observability instrumentation.
+     *
+     * Each hook is called at the corresponding pipeline step.
+     * The fast path passes `undefined` (zero overhead).
+     * Debug and traced paths supply their hooks via factory methods.
+     */
+    async _executePipeline(execCtx, ctx, args, progressSink, hooks) {
         // Step 1: Route
         const disc = parseDiscriminator(execCtx, args);
         if (!disc.ok) {
-            debug({ type: 'error', tool: this._name, action: '?', error: 'Missing discriminator', step: 'route', timestamp: Date.now() });
-            return disc.response;
+            hooks?.onRouteError?.();
+            return hooks?.wrapResponse?.(disc.response) ?? disc.response;
         }
         const actionName = disc.value;
-        debug({ type: 'route', tool: this._name, action: actionName, timestamp: Date.now() });
+        hooks?.onRouteOk?.(actionName);
         // Step 2: Resolve
         const resolved = resolveAction(execCtx, actionName);
         if (!resolved.ok) {
-            debug({ type: 'error', tool: this._name, action: actionName, error: `Unknown action "${actionName}"`, step: 'route', timestamp: Date.now() });
-            return resolved.response;
+            hooks?.onResolveError?.(actionName);
+            return hooks?.wrapResponse?.(resolved.response) ?? resolved.response;
         }
         // Step 3: Validate
         const validateStart = performance.now();
         const validated = validateArgs(execCtx, resolved.value, args);
-        const validateDuration = performance.now() - validateStart;
+        const validateMs = performance.now() - validateStart;
         if (!validated.ok) {
-            debug({ type: 'validate', tool: this._name, action: actionName, valid: false, error: 'Validation failed', durationMs: validateDuration, timestamp: Date.now() });
-            return validated.response;
+            hooks?.onValidateError?.(actionName, validateMs);
+            return hooks?.wrapResponse?.(validated.response) ?? validated.response;
         }
-        debug({ type: 'validate', tool: this._name, action: actionName, valid: true, durationMs: validateDuration, timestamp: Date.now() });
-        // Step 4: Middleware chain info (global + action-level)
+        hooks?.onValidateOk?.(actionName, validateMs);
+        // Step 4: Middleware info
         const actionMwCount = resolved.value.action.middlewares?.length ?? 0;
         const globalMwCount = this._middlewares.length;
         const chainLength = globalMwCount + actionMwCount;
         if (chainLength > 0) {
-            debug({ type: 'middleware', tool: this._name, action: actionName, chainLength, timestamp: Date.now() });
+            hooks?.onMiddleware?.(actionName, chainLength);
         }
         // Step 5: Execute
         try {
-            const response = await runChain(execCtx, resolved.value, ctx, validated.value, progressSink);
-            const totalDuration = performance.now() - startTime;
-            const isErr = response.isError === true;
-            debug({ type: 'execute', tool: this._name, action: actionName, durationMs: totalDuration, isError: isErr, timestamp: Date.now() });
-            return response;
+            const response = await runChain(execCtx, resolved.value, ctx, validated.value, progressSink, hooks?.rethrow);
+            hooks?.onExecuteOk?.(actionName, response);
+            return hooks?.wrapResponse?.(response) ?? response;
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            debug({ type: 'error', tool: this._name, action: actionName, error: message, step: 'execute', timestamp: Date.now() });
-            throw err;
+            hooks?.onExecuteError?.(actionName, err);
+            throw err; // only reached when rethrow=true (traced path handles it)
         }
     }
     /**
-     * Traced path: OpenTelemetry-compatible span creation.
+     * Build debug hooks: lightweight event emission.
+     */
+    _buildDebugHooks() {
+        const debug = this._debug;
+        const toolName = this._name;
+        const startTime = performance.now();
+        return {
+            onRouteError: () => {
+                debug({ type: 'error', tool: toolName, action: '?', error: 'Missing discriminator', step: 'route', timestamp: Date.now() });
+            },
+            onRouteOk: (action) => {
+                debug({ type: 'route', tool: toolName, action, timestamp: Date.now() });
+            },
+            onResolveError: (action) => {
+                debug({ type: 'error', tool: toolName, action, error: `Unknown action "${action}"`, step: 'route', timestamp: Date.now() });
+            },
+            onValidateError: (action, durationMs) => {
+                debug({ type: 'validate', tool: toolName, action, valid: false, error: 'Validation failed', durationMs, timestamp: Date.now() });
+            },
+            onValidateOk: (action, durationMs) => {
+                debug({ type: 'validate', tool: toolName, action, valid: true, durationMs, timestamp: Date.now() });
+            },
+            onMiddleware: (action, chainLength) => {
+                debug({ type: 'middleware', tool: toolName, action, chainLength, timestamp: Date.now() });
+            },
+            onExecuteOk: (action, response) => {
+                const isErr = response.isError === true;
+                debug({ type: 'execute', tool: toolName, action, durationMs: performance.now() - startTime, isError: isErr, timestamp: Date.now() });
+            },
+            onExecuteError: (action, err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                debug({ type: 'error', tool: toolName, action, error: message, step: 'execute', timestamp: Date.now() });
+            },
+        };
+    }
+    /**
+     * Build traced hooks: OpenTelemetry-compatible span creation.
      *
      * Creates ONE span per tool call with events for pipeline steps.
-     * Uses `finally` for leak-proof span closure.
+     * Uses wrapResponse for leak-proof span closure.
      * AI errors → UNSET, system errors → ERROR.
      */
-    async _executeTraced(execCtx, ctx, args, progressSink) {
+    _buildTracedHooks() {
         const tracer = this._tracer;
         const startAttrs = {
             'mcp.system': 'fusion',
@@ -609,77 +644,61 @@ export class GroupedToolBuilder {
         const startTime = performance.now();
         let statusCode = SpanStatusCode.UNSET;
         let statusMessage;
-        let response;
-        try {
-            // Route
-            const disc = parseDiscriminator(execCtx, args);
-            if (!disc.ok) {
+        const finalizeSpan = (response) => {
+            span.setAttribute('mcp.durationMs', performance.now() - startTime);
+            if (response) {
+                span.setAttribute('mcp.response_size', computeResponseSize(response));
+            }
+            span.setStatus(statusMessage !== undefined
+                ? { code: statusCode, message: statusMessage }
+                : { code: statusCode });
+            span.end();
+        };
+        return {
+            rethrow: true,
+            onRouteError: () => {
                 span.setAttribute('mcp.error_type', 'missing_discriminator');
                 span.setAttribute('mcp.isError', true);
-                return (response = disc.response);
-            }
-            span.setAttribute('mcp.action', disc.value);
-            span.addEvent?.('mcp.route');
-            // Resolve
-            const resolved = resolveAction(execCtx, disc.value);
-            if (!resolved.ok) {
+            },
+            onRouteOk: (action) => {
+                span.setAttribute('mcp.action', action);
+                span.addEvent?.('mcp.route');
+            },
+            onResolveError: () => {
                 span.setAttribute('mcp.error_type', 'unknown_action');
                 span.setAttribute('mcp.isError', true);
-                return (response = resolved.response);
-            }
-            // Validate
-            const validateStart = performance.now();
-            const validated = validateArgs(execCtx, resolved.value, args);
-            const validateMs = performance.now() - validateStart;
-            if (!validated.ok) {
+            },
+            onValidateError: (_action, durationMs) => {
                 span.setAttribute('mcp.error_type', 'validation_failed');
                 span.setAttribute('mcp.isError', true);
-                span.addEvent?.('mcp.validate', { 'mcp.valid': false, 'mcp.durationMs': validateMs });
-                return (response = validated.response);
-            }
-            span.addEvent?.('mcp.validate', { 'mcp.valid': true, 'mcp.durationMs': validateMs });
-            // Middleware info
-            const actionMwCount = resolved.value.action.middlewares?.length ?? 0;
-            const globalMwCount = this._middlewares.length;
-            const chainLength = globalMwCount + actionMwCount;
-            if (chainLength > 0) {
+                span.addEvent?.('mcp.validate', { 'mcp.valid': false, 'mcp.durationMs': durationMs });
+            },
+            onValidateOk: (_action, durationMs) => {
+                span.addEvent?.('mcp.validate', { 'mcp.valid': true, 'mcp.durationMs': durationMs });
+            },
+            onMiddleware: (_action, chainLength) => {
                 span.addEvent?.('mcp.middleware', { 'mcp.chainLength': chainLength });
-            }
-            // Execute — rethrow=true so handler exceptions propagate to our catch block
-            response = await runChain(execCtx, resolved.value, ctx, validated.value, progressSink, true);
-            const isErr = response.isError === true;
-            // AI error (handler returned error()) → UNSET, not ERROR
-            statusCode = isErr ? SpanStatusCode.UNSET : SpanStatusCode.OK;
-            if (isErr)
-                span.setAttribute('mcp.error_type', 'handler_returned_error');
-            span.setAttribute('mcp.isError', isErr);
-            return response;
-        }
-        catch (err) {
-            // System failure — THIS is a real SpanStatusCode.ERROR
-            const message = err instanceof Error ? err.message : String(err);
-            span.recordException(err instanceof Error ? err : message);
-            span.setAttribute('mcp.error_type', 'system_error');
-            span.setAttribute('mcp.isError', true);
-            statusCode = SpanStatusCode.ERROR;
-            statusMessage = message;
-            // Return graceful error response — don't throw (would crash MCP server)
-            return (response = error(`[${this._name}] ${message}`));
-        }
-        finally {
-            span.setAttribute('mcp.durationMs', performance.now() - startTime);
-            if (response) {
-                // Response size in bytes — useful for billing/quota dashboards
-                let size = 0;
-                for (const c of response.content) {
-                    if ('text' in c && typeof c.text === 'string')
-                        size += c.text.length;
-                }
-                span.setAttribute('mcp.response_size', size);
-            }
-            span.setStatus(statusMessage !== undefined ? { code: statusCode, message: statusMessage } : { code: statusCode });
-            span.end(); // leak-proof: always called
-        }
+            },
+            onExecuteOk: (_action, response) => {
+                const isErr = response.isError === true;
+                statusCode = isErr ? SpanStatusCode.UNSET : SpanStatusCode.OK;
+                if (isErr)
+                    span.setAttribute('mcp.error_type', 'handler_returned_error');
+                span.setAttribute('mcp.isError', isErr);
+            },
+            onExecuteError: (_action, err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                span.recordException(err instanceof Error ? err : message);
+                span.setAttribute('mcp.error_type', 'system_error');
+                span.setAttribute('mcp.isError', true);
+                statusCode = SpanStatusCode.ERROR;
+                statusMessage = message;
+            },
+            wrapResponse: (response) => {
+                finalizeSpan(response);
+                return response;
+            },
+        };
     }
     // ── Introspection ───────────────────────────────────
     /** Get the tool name. */