Skip to content

AIML-361: Support multiple session metadata filters with JSON parameter - #66

Merged
ChrisEdwards merged 8 commits into
mainfrom
AIML-361-multiple-session-metadata-filters
Jan 9, 2026
Merged

ChrisEdwards merged 8 commits into
mainfrom
AIML-361-multiple-session-metadata-filters

Conversation

@ChrisEdwards

@ChrisEdwards ChrisEdwards commented Jan 9, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Adds new sessionMetadataFilters JSON parameter to search_app_vulnerabilities tool
  • Replaces the single-field sessionMetadataName/sessionMetadataValue parameters with flexible JSON-based filtering
  • Supports AND logic across different fields and OR logic within array values
  • Removes ~275 lines of in-memory filtering code in favor of server-side filtering

Why

AI agents need to filter vulnerabilities by multiple session metadata criteria simultaneously. The previous API supported only single field filtering (sessionMetadataName + sessionMetadataValue), which was insufficient for real-world use cases like:

  • "Show me vulnerabilities from the main branch where the developer was Ellen or Sam"
  • "Filter by both commit hash AND developer name"

This is a breaking change that removes the old parameters in favor of a more powerful JSON-based approach.

What

New parameter: sessionMetadataFilters - JSON object mapping field names to values

  • String value for single filter: {"branch":"main"}
  • Array value for OR within field: {"developer":["Ellen","Sam"]}
  • Multiple fields for AND across fields: {"branch":"main","developer":"Ellen"}
  • Combined: {"developer":["Ellen","Sam"],"branch":"main"}

Removed parameters:

  • sessionMetadataName
  • sessionMetadataValue

Removed code (~275 lines):

  • In-memory session filtering logic (executeWithInMemorySessionFiltering)
  • Multi-page fetching with early termination (fetchTracesWithEarlyTermination)
  • Session filter predicate building (buildSessionFilterPredicate)
  • SessionFilteringResult record and related pagination logic
  • maxTracesForSessionFiltering configuration property

Supporting changes:

  • Migrated both vulnerability search tools to POST /ng/orgId/traces/appId/filter endpoint
  • Added ExtendedTraceFilterBody for session metadata filtering support
  • Added MetadataJsonFilterSpec for JSON validation with helpful error messages
  • Fixed tracked/untracked defaults to return ALL vulnerabilities (not just untracked)

How

Architecture

  1. JSON Parsing & Validation (MetadataJsonFilterSpec.java):

    • Parses JSON to Map<String, Object> where values are String or List<String>
    • Handles Gson's quirk of parsing integers as doubles (42 → "42", not "42.0")
    • Produces clear error messages for malformed JSON
    • Returns null for empty JSON objects {}
  2. Field Name Resolution (SearchAppVulnerabilitiesTool.java):

    • Fetches session metadata schema from API to get numeric field IDs
    • Translates human-readable field names ("branch") to numeric IDs (12345)
    • Field names are case-insensitive, but values are case-sensitive
    • Reports validation errors if field names don't exist
  3. TraceMetadataFilter Construction (ExtendedTraceFilterBody.java):

    • Builds SDK TraceMetadataFilter objects for each field
    • Single values get one filter entry; arrays get multiple (OR logic)
    • Multiple fields combined in list (AND logic)
  4. POST Endpoint Migration:

    • Both SearchVulnerabilitiesTool and SearchAppVulnerabilitiesTool now use POST
    • Enables complex filter bodies that don't fit in query parameters
    • Session ID filtering applied via POST body

Key Implementation Decisions

  • Breaking change over backwards compatibility: JSON parameter is cleaner than layering on additional parameters
  • Server-side filtering over in-memory: Let the server handle filtering - eliminates complex pagination logic, memory pressure, and MAX_PAGES limits
  • Field name resolution at query time: Validates field names exist and translates to IDs
  • Mutually exclusive with useLatestSession: Keeps filtering logic clear

Step-by-Step Walkthrough

Core changes:

  1. SearchAppVulnerabilitiesParams.java (lines 64, 81-82, 136-146):

    • Replaced sessionMetadataName/sessionMetadataValue with sessionMetadataFilters map
    • Added mutual exclusivity validation with useLatestSession
  2. MetadataJsonFilterSpec.java (new file):

    • Fluent validation spec for JSON metadata filters
    • Handles string, number, and array values
    • Produces actionable error messages
  3. SearchAppVulnerabilitiesTool.java (lines 196-260):

    • resolveSessionMetadataFilters(): Translates field names to numeric IDs
    • buildMetadataFilters(): Constructs TraceMetadataFilter list for API
    • Integrated into session filtering execution path
  4. ExtendedTraceFilterBody.java (new file):

    • Extends SDK's TraceFilterBody to add session metadata filter support
    • withMetadataFilters() method for fluent construction

Refactoring (non-functional):

  1. Both search tools now use POST endpoint via SDKExtension.getTraces() / getTracesInOrg()
  2. Removed deprecated toTraceFilterForm() methods
  3. Renamed execution methods to be self-documenting
  4. Added TraceExpandValue enum instead of magic strings

Test infrastructure:

  1. TracesJsonFixture.java (new file): Shared test fixtures for API responses
  2. AnonymousTraceBuilder pattern used for clean test setup

Testing

Unit tests: 597 tests passing

  • SearchAppVulnerabilitiesToolTest.java: 35 tests covering JSON parsing, field resolution, filtering logic
  • MetadataJsonFilterSpecTest.java: 13 tests for JSON validation edge cases
  • SearchAppVulnerabilitiesParamsTest.java: Parameter validation tests
  • ExtendedTraceFilterBodyTest.java: Filter body construction tests

Integration tests: Require credentials

  • SearchAppVulnerabilitiesToolIT.java: Tests for:
    • Invalid JSON rejection
    • Invalid field name detection
    • Combined with other filters

Manual testing:

  • Verified JSON parameter works via Claude Desktop MCP client
  • Tested field name validation errors
  • Confirmed backwards compatibility with useLatestSession

Add new validation spec for parsing JSON filter parameters with:
- String and string array value support
- Number to string conversion (integers formatted without decimals)
- Rejection of complex/nested objects
- Clear error messages for invalid JSON

Also add mutuallyExclusive() method to ToolValidationContext for
validating exclusive parameter combinations.
BREAKING CHANGE: sessionMetadataName and sessionMetadataValue parameters removed.
Use sessionMetadataFilters JSON parameter instead.

The new parameter supports:
- Single filter: {"branch":"main"}
- Multiple filters (AND logic): {"developer":"Ellen","commit":"100"}
- Multiple values (OR logic): {"developer":["Ellen","Sam"]}

Implementation changes:
- SearchAppVulnerabilitiesParams: Replace old params with sessionMetadataFilters
- ExtendedTraceFilterBody: Replace fromWithSession with withSessionFilters
- SearchAppVulnerabilitiesTool: Update to build List<TraceMetadataFilter>
- Integration tests: Update to use new JSON format

Resolves AIML-361
Prevents NullPointerException if caller passes null source.
@ChrisEdwards
ChrisEdwards force-pushed the AIML-361-multiple-session-metadata-filters branch from 8469a7f to c50eab2 Compare January 9, 2026 17:23
@ChrisEdwards
ChrisEdwards marked this pull request as ready for review January 9, 2026 18:16
Remove needsSessionFiltering() and merge executeWithServerSidePagination
into unified doExecute(). The in-memory filtering methods remain but are
now unreachable (to be deleted next commit).
Remove all in-memory session filtering infrastructure:
- executeWithInMemorySessionFiltering() method
- SessionFilteringResult record
- fetchTracesWithEarlyTermination() method
- buildSessionFilterPredicate() method
- maxTracesForSessionFiltering config field

Keep normalizeFilterValue(), resolveSessionMetadataFilters(), and
buildFieldNameToIdMapping() which are still used for server-side filtering.
Remove outdated notes about multi-page fetching and partial results
since session filtering now uses server-side API exclusively.
- Remove integration test that used empty string for "any value" filtering
  (this behavior no longer works with new JSON format)
- Handle empty JSON object {} explicitly by returning null
- Clarify in tool description that field values are case-sensitive
  (while field names remain case-insensitive)

@JacobMagesHaskinsContrast JacobMagesHaskinsContrast left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. I rebuilt it locally and ran it. My demo project didn't have any session_metadata, but Copilot still tried to get some with the MCP server anyways.
Screenshot 2026-01-09 at 3 05 16 PM

@ChrisEdwards
ChrisEdwards merged commit f16dda3 into main Jan 9, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants