Human time telemetry
The mobile app measures foreground time while a session is open and reports those durations to the duration-tracking plugin on the connected backend. Collection is opt-in and off by default.
What is collected
A span starts when the Messages surface has a selected session while the app is in the foreground and tracking is enabled. It closes when the app leaves the foreground, the user leaves Messages, selects another session or connection, disables tracking, or selects Upload now. Returning to the foreground with the session still open starts a new span.
Typing and scrolling are not individual collection signals. Submitting a composed message through Send, Append, or Append As splits the foreground-session span at that moment and immediately starts its replacement. The submission does not wait for persistence or upload. Mobile does not create session-less spans.
Settings
Both settings live in the global settings modal and persist through
clc_mobile_global_preferences_v1:
Time tracking(timeTrackingEnabled, default off) — the opt-in toggle. Turning it off stops collection; pending spans stay cached and upload only while tracking is enabled.Telemetry plugin(timeTrackingPluginId, defaultduration_tracking_app) — the frontend-owned plugin id the uploads target. The app does not discover the plugin; a wrong id produces a one-time warning (below), not silent loss.
Upload behavior
The headless pipeline is shared from
packages/frontend-rn-components/src/humanTimeTelemetry/. The mobile
src/humanTimeTelemetry/ directory provides thin AsyncStorage adapters and
the app-specific provider:
- mobile
spanCache.ts— binds the shared durable cache to AsyncStorage (clc_human_time_spans_v1, 5000-span soft cap). Spans persist until the backend confirms their batch, so restarts and failed uploads do not lose data. - shared
uploader.ts— batched drain overexecuteAction(record_human_time_spans,actionOwner: "application", up to 100 spans per call, content-derivedrequest_idstable across retries). Flushes debounce 2s after a span closes and run immediately when a connection becomes usable or the app returns to the foreground. Uploads do not wait for agent work on the connection. - shared
warning.ts— the failure banner. HumanTimeTelemetryProvider.tsx— foreground/session lifecycle tracking, mounted inConnectedRoot.
Transient failures (network errors, HTTP 5xx) retain the spans and retry
after 30 seconds while the app can run.
Definitive failures (HTTP 404/400, e.g. an unknown plugin id) also retain
the spans, and the app shows a one-time dismissible warning banner on the
connection banner rail; changing either setting re-arms the warning.
When a successful action response reports skipped spans, the uploader
isolates that batch into individual span requests. Confirmed spans are removed
by value and continue uploading even when a rejected span appeared before
them. A singleton span that the server confirms it cannot accept is removed
from the active queue and shown as Failed in diagnostics, so it cannot poison
later uploads. A rejected span does not emit the unavailable-plugin banner.
Backgrounding closes and durably queues the open span. Mobile runtimes may suspend the two-second debounce, so returning to the foreground waits for that cache write and then flushes pending spans immediately.
A composed-message split uses the same normal debounced upload path. It is a best-effort turn boundary: a sufficiently fast assistant response can still finalize before the closed span reaches the plugin, and sending is never delayed to prevent that race.
The backend resolves overlaps and dedups by request id; the session total
surfaces in the chat status bar (Human time: …) after the next request
finalizes. See plugins/duration-tracking/docs/development/overview.md
for the ingestion contract.
Diagnostics
Global Settings has a compact Show diagnostics section under the telemetry plugin setting. It shows whether collection and the connection are active, the open and most recently collected surfaces, the durable pending count, the latest upload result and server counts, and the ten most recent collected entries. Each entry shows upload status, session id (or Sessions list), end time, and duration. A partially accepted drain is labeled Some entries rejected. Pending entries are restored from the durable cache; uploaded entry history covers the current app run.
Upload now closes the current span, waits for its durable cache write, flushes the connection, and starts a fresh span if the session remains open in the foreground. Refresh reloads the pending count. Diagnostics do not show message content or filesystem paths.
End-to-end verification
Human time uses two touching verification tiers. Stored SQLite span rows are their shared boundary.
The real-backend Jest tier starts a server with the deterministic stream,
timestamp, and duration-tracking plugins. It seeds deterministic spans
into the real frontend cache and uploads them through
RestAgentBackend/FetchTransport. It verifies cache draining, stored
session totals surfacing on the next request, request-id retry dedup, and
definitive-failure retention:
npm run test:integration -- \
--runTestsByPath __integration__/humanTimeSpanUpload.realBackend.integration.test.ts
The focused Detox tier proves collection. It launches the real release app without harness arguments, spawns the same real backend in a hermetic workspace, connects through the production manual-address flow, and enables tracking through the real settings UI. It opens a real session, sends through the production composer, leaves Messages to close the foreground span, and requires a positive-duration row for that session. This remains the single native collection scenario; lifecycle scheduling and diagnostics are covered deterministically by provider/uploader and real-backend integration tests.
Build a current release app when production mobile sources have changed, then run the focused suite:
npm run detox:build:ios
npm run detox:test:human-time:ios
npm run detox:build:android
npm run detox:test:human-time:android # prepares the emulator first
The frontend-sdk backend harness resolves Python from PYTHON, then the
repository .venv, then python. The local timestamp and
duration-tracking plugin checkouts must be loadable by that interpreter.