attune/work-summary/sessions/2026-01-18-execution-search-enhancement.md

Work Summary: Execution Search Enhancement

Date: 2026-01-18
Session: 7 (continued)
Status: ✅ Complete

Overview

Enhanced the execution search capabilities in both the API and CLI to support filtering by pack name and searching within execution results. This makes it much easier for users to find specific executions based on their output or organizational structure.

Objectives

• Add pack-based filtering for executions
• Enable searching within execution result JSON
• Maintain backward compatibility with existing API
• Update CLI with new filter options
• Document new capabilities

Implementation Details

API Changes

1. Updated ExecutionQueryParams (crates/api/src/dto/execution.rs)

Added two new optional query parameters:

pub struct ExecutionQueryParams {
    // ... existing fields ...
    
    /// Filter by pack name
    #[param(example = "core")]
    pub pack_name: Option<String>,

    /// Search in result JSON (case-insensitive substring match)
    #[param(example = "error")]
    pub result_contains: Option<String>,
    
    // ... other fields ...
}

2. Updated list_executions Handler (crates/api/src/routes/executions.rs)

Added filtering logic:

Pack Name Filter:

if let Some(pack_name) = &query.pack_name {
    filtered_executions.retain(|e| {
        // action_ref format is "pack.action"
        e.action_ref.starts_with(&format!("{}.", pack_name))
    });
}

Result Search Filter:

if let Some(result_search) = &query.result_contains {
    let search_lower = result_search.to_lowercase();
    filtered_executions.retain(|e| {
        if let Some(result) = &e.result {
            // Convert result to JSON string and search case-insensitively
            let result_str = serde_json::to_string(result).unwrap_or_default();
            result_str.to_lowercase().contains(&search_lower)
        } else {
            false
        }
    });
}

CLI Changes

1. Updated Execution List Command (crates/cli/src/commands/execution.rs)

Added new command-line options:

List {
    /// Filter by pack name
    #[arg(short, long)]
    pack: Option<String>,

    /// Filter by action name
    #[arg(short, long)]
    action: Option<String>,

    /// Filter by status
    #[arg(short, long)]
    status: Option<String>,

    /// Search in execution result (case-insensitive)
    #[arg(short, long)]
    result: Option<String>,

    /// Limit number of results
    #[arg(short, long, default_value = "50")]
    limit: i32,
}

2. Updated Query String Building

Fixed and enhanced query parameter construction:

• Changed limit to per_page to match API
• Changed action to action_ref to match API
• Added URL encoding for search terms
• Added new pack_name and result_contains parameters

3. Added URL Encoding Dependency

Added urlencoding = "2.1" to properly encode query parameters with special characters.

Usage Examples

CLI Usage

# Filter by pack
attune execution list --pack core

# Filter by action within pack
attune execution list --pack monitoring --action health_check

# Search in results
attune execution list --result "error"
attune execution list --result "timeout"

# Combine multiple filters
attune execution list --pack monitoring --status failed --result "connection refused"

# With limit
attune execution list --pack core --status succeeded --limit 100

API Usage

# Filter by pack
curl "http://localhost:8080/api/v1/executions?pack_name=core"

# Search in results
curl "http://localhost:8080/api/v1/executions?result_contains=error"

# Combine filters
curl "http://localhost:8080/api/v1/executions?pack_name=monitoring&status=failed&result_contains=timeout"

Scripting Example

#!/bin/bash
# Find all failed monitoring executions with timeout errors

attune execution list \
  --pack monitoring \
  --status failed \
  --result timeout \
  --output json | \
  jq -r '.[] | "\(.id): \(.action_name) - \(.created)"'

Use Cases

1. Troubleshooting Pack Issues

Quickly find all failed executions from a specific pack:

attune execution list --pack monitoring --status failed

2. Error Pattern Analysis

Search for specific error messages across all executions:

attune execution list --result "connection refused"
attune execution list --result "timeout"

3. Pack-Specific Monitoring

Monitor execution results for a specific pack:

attune execution list --pack core --limit 100 --output json | \
  jq '[.[] | {id, status, result}]'

4. Debugging Workflows

Find executions with specific result patterns:

attune execution list --result "workflow_step_3" --status failed

Technical Details

Pack Name Extraction

Pack names are extracted from the action_ref field which follows the format pack_name.action_name:

• core.echo → pack: core
• monitoring.health_check → pack: monitoring

The filter uses starts_with() to match the pack prefix efficiently.

Result Search Implementation

Result searching is case-insensitive and performs substring matching:

1. Convert result JSON to string representation
2. Convert both search term and result to lowercase
3. Check if result contains the search term

Important Notes:

• Searches the entire JSON structure (keys and values)
• Case-insensitive for user convenience
• Returns false if execution has no result

Query Parameter Alignment

Fixed inconsistencies between CLI and API:

• CLI --action → API action_ref
• CLI --limit → API per_page
• Added URL encoding for special characters

Testing

Manual Testing

# Build and test
cargo build -p attune-cli
cargo check -p attune-api

# Test help text
./target/debug/attune execution list --help

# Verify new options appear
# - Should show --pack option
# - Should show --result option

Build Status

• ✅ API compiles successfully
• ✅ CLI compiles successfully
• ✅ No new warnings introduced
• ✅ Help text displays correctly

Documentation Updates

Updated Files

1. CLI README (crates/cli/README.md)

   • Added pack filtering examples
   • Added result search examples
   • Added combined filter examples

2. CLI Docs (docs/cli.md)

   • Updated execution list section
   • Added Python scripting example with new filters
   • Updated performance best practices

3. API Docs (docs/api-executions.md)

   • Added pack_name parameter
   • Added result_contains parameter
   • Updated examples with new filters

4. Main README (README.md)

   • Added execution search examples
   • Updated feature highlights

Benefits

For Users

1. Faster Troubleshooting: Quickly filter to relevant executions
2. Better Observability: Find patterns in execution results
3. Pack-Level Monitoring: Track pack-specific execution health
4. Flexible Queries: Combine multiple filters for precise searches

For Operations

1. Incident Response: Quickly find failures with specific error messages
2. Pack Debugging: Isolate issues to specific packs
3. Pattern Detection: Identify recurring error patterns
4. Audit Trail: Search executions by result content

Performance Considerations

Current implementation:

• Filtering happens in-memory after database query
• Suitable for current scale
• May need optimization for large datasets

Future optimizations could include:

1. Database-level JSON search (PostgreSQL JSONB operators)
2. Full-text search indexing for results
3. Caching for common pack filters
4. Query result streaming for large datasets

Future Enhancements

Potential improvements:

1. Advanced JSON Querying: Use JSONPath or JQ-like syntax
2. Result Field Filtering: Search specific fields only
3. Regular Expression Support: More powerful pattern matching
4. Date Range Filtering: Filter by execution time
5. Duration Filtering: Find long-running executions
6. Parent/Child Filtering: Search workflow hierarchies
7. Tag-Based Search: If tags are added to executions

Metrics

• Files Modified: 6
• Lines Added: ~100
• New CLI Options: 2 (--pack, --result)
• New API Parameters: 2 (pack_name, result_contains)
• Documentation Updates: 4 files
• Development Time: ~30 minutes

Backward Compatibility

✅ Fully Backward Compatible

• New parameters are optional
• Existing queries continue to work
• No breaking changes to API or CLI
• Default behavior unchanged

Files Changed

Modified Files

• crates/api/src/dto/execution.rs: Added query parameters
• crates/api/src/routes/executions.rs: Added filtering logic
• crates/cli/src/commands/execution.rs: Added CLI options and query building
• crates/cli/Cargo.toml: Added urlencoding dependency
• crates/cli/README.md: Updated documentation
• docs/cli.md: Updated documentation
• docs/api-executions.md: Updated API documentation
• README.md: Updated examples

Conclusion

Successfully enhanced execution search capabilities with pack and result filtering. The implementation:

• Provides powerful search capabilities
• Maintains backward compatibility
• Follows existing patterns
• Is well-documented
• Enables better operational workflows

Users can now efficiently find executions by pack, search through results, and combine filters for precise queries. This significantly improves troubleshooting and monitoring capabilities.

Related Documents

• CLI README
• CLI Documentation
• API Executions Documentation
• CLI Implementation Work Summary