Module utils 

Utility functions for building custom observability tools.

These are stateless, pure functions that power the CLI and can be used by external tool developers to replicate or extend agtrace functionality.

When to use this module

• Building custom TUIs or dashboards that need event stream processing
• Writing tests that need to compute project hashes
• Implementing custom project detection logic

Examples

Event Processing

use agtrace_sdk::{Client, utils};
use agtrace_sdk::watch::{StreamEvent, WorkspaceEvent};

let client = Client::connect("~/.agtrace")?;
let stream = client.watch().all_providers().start()?;

for workspace_event in stream.take(10) {
    if let WorkspaceEvent::Stream(StreamEvent::Events { events, .. }) = workspace_event {
        for event in events {
            let updates = utils::extract_state_updates(&event);
            if updates.is_new_turn {
                println!("New turn started!");
            }
            if let Some(usage) = updates.usage {
                println!("Token usage: {:?}", usage);
            }
        }
    }
}

Project Hash Computation

use agtrace_sdk::utils;

let project_root = utils::discover_project_root(None)?;
let hash = utils::project_hash_from_root(&project_root.to_string_lossy());
println!("Project hash: {}", hash);

Functions

discover_project_root

Discover project root based on priority:

extract_state_updates

Extract state updates from a single event without performing I/O or side effects.

project_hash_from_root

Calculate project_hash from project_root using SHA256

resolve_effective_project_hash

Resolve effective project hash based on explicit hash or all_projects flag