Skip to content

duration-tracking

Generated from plugins/duration-tracking/README.md.

Package documentation: browse guides and development docs.

Generic, provider-agnostic duration tracking plugin for the Crystal Lattice platform.

The timestamp extension's duration feature (DurationExtension) measures each provider call and stamps the duration facts onto its native response owner, including a function/custom tool call when the response has no assistant text. This plugin records one row per measured provider call (LLM round) into a SQLite store under the Crystal data directory, renders the store-backed session totals in the chat status bar (aggregated by workspace + session id), and exposes session actions for a duration report and a non-destructive per-project report reset. The status display has three compact choices for the primary duration (LLM or LLM + tools), separate tool/human fields, and counts/averages. Duration is factual history: status totals remain all-time even when the report has been reset.

It also tracks human time: frontends report user-activity spans ({session_id|null, from, to} — the frontend computes the durations) in batches through the record_human_time_spans application action; the plugin dedups by request id, resolves range overlaps so no two stored rows ever overlap, and surfaces the per-session human time total in the status bar (Human time: …) and the report. The report also includes compact human-time diagnostics, current-project totals and rankings since that project's latest reset, and reset-independent seven-day views: daily LLM/tool/human breakdowns for the current project, current session, and all projects, each with a seven-day total row; the top 10 sessions across projects; and the top 3 projects. Rankings are based on human time while also showing LLM and tool time; the current-project LLM-ranked session table is retained. Project tables include session-less human time separately. All frontend spans use the application plugin's server-level working directory, defaulted from runtime WORKING_DIR, and its shared database; ingestion stores session ids without loading sessions or resolving their agents. The mobile app collects the spans behind an opt-in Time tracking toggle with a frontend-owned telemetry plugin id (default duration_tracking_app). See docs/development/overview.md for the store schema, recording seams, the human-time span contract (including the frontend collection notes), configuration, and the completed-turn human-time delta. The delta is stored on the final assistant message without tool calls and compares the cumulative uploaded human time with the previous completed turn. Intermediate tool-call assistant messages carry machine-duration totals but no human-time metadata. Native tool-call flags and nonterminal turn markers are recognized even when the tool calls are separate response items. Retained history projection repairs old human-time deltas from the completed turns' saved uploaded totals.

To recover missing LLM rounds from local session histories, preview an explicit project and database:

python -m duration_tracking_plugins.recovery \
  --db ~/.crystal/duration-tracking/duration-tracking.sqlite3 \
  --project /absolute/path/to/project \
  --session "session-id"

Add --apply to backfill rows and repair saved duration metadata. The command backs up the database and changed session files under the database directory's backups/ folder. It uses measured native stamps, deduplicates existing rounds, and only recovers sessions and time windows already represented in that database. It does not need the session's original agent configuration. The optional --session argument limits both database recovery and metadata repair to that session within the selected project. Omit it to recover all tracked sessions in the project. Multiple projects can be supplied with repeated --project arguments. Files changed during recovery are left for a later run. The append-only summary CSV is not rewritten by recovery; the SQLite reports and saved session metadata are repaired.

Development

python -m pip install -e "plugins/duration-tracking[dev]"
pytest plugins/duration-tracking/tests -q

The integration tests run real AgentApplication requests against the local echo provider with the production duration feature and tracking feature (pytest plugins/duration-tracking/tests -m integration -q).