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};
use futures::stream::StreamExt;

let client = Client::connect_default().await?;
let mut stream = client.watch().all_providers().start()?;

let mut count = 0;
while let Some(workspace_event) = stream.next().await {
    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);
            }
        }
    }
    count += 1;
    if count >= 10 { break; }
}

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

default_token_limits

Create a TokenLimits instance with the default provider resolver.

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

resolve_workspace_path

Resolve the workspace data directory path based on priority: