Skip to content

fix(telemetry): align client with unified contract, stop firing collection_completed on data arrival#98

Closed
tnunamak wants to merge 1 commit intomainfrom
fix/telemetry-client-alignment
Closed

fix(telemetry): align client with unified contract, stop firing collection_completed on data arrival#98
tnunamak wants to merge 1 commit intomainfrom
fix/telemetry-client-alignment

Conversation

@tnunamak
Copy link
Copy Markdown
Member

@tnunamak tnunamak commented Apr 4, 2026

Summary

Two fixes bundled because they touch the same files:

1. collection_completed no longer fires when data arrives (real bug)

The export-complete handler in useEvents.ts was calling markCollectionCompleted whenever the connector emitted data via setData('result'). For multi-step connectors that stream partial results (e.g., ChatGPT), this marked the run as complete mid-execution — the UI showed success while the connector was still running, and the COMPLETE status event that fired later was deduped away.

Fix: Split responsibilities cleanly.

  • connector-status: COMPLETE is the authoritative terminal signal. It fires when the connector process exits and is the only place markCollectionCompleted gets called during a connector run.
  • export-complete now handles persistence only. It continues to write data to the personal server when it arrives, without touching run status or telemetry.
  • persistedRunIds dedupes across both paths so simple connectors that attach data to the COMPLETE payload still persist correctly.

This matches the state machine described in the new telemetry contract (see context-gateway PR).

2. Align contract types with the server

Updates src/lib/telemetry/contracts.ts to match the unified contract in the server.

Source of truth: https://github.com/vana-com/context-gateway/blob/main/packages/contracts/src/telemetry.ts

Because @opendatalabs/contracts can't be published to npm (private repo, no license), the types are copied with a header comment pointing at the source. When the server contract changes, this file must be updated to match. The server validates events against its own copy — a mismatch will cause events from this client to be rejected.

Notable contract changes

  • Added grant_flow_started and grant_flow_expired to the event name list
  • Removed needs_input from the error class whitelist; use abandoned_waiting_for_input for real timeouts
  • Removed the outcome field (rollups use eventName + errorClass, never a free-form string)
  • Added detail (free-form debugging context) and recordCount fields
  • Added trackGrantFlowStarted and trackGrantFlowExpired helpers
  • trackCollectionNeedsInput no longer sets errorClass (it's intermediate, not a failure); added optional interactionKind metadata

Test plan

  • tsc -b --noEmit passes (only unrelated errors from missing @tauri-apps/plugin-updater type deps)
  • Run ChatGPT connector end-to-end, verify the run shows "running" through all 3 steps and transitions to "success" only after the connector process finishes
  • Run LinkedIn connector with login required, verify the run transitions through needs_input → success, with needsInput: true on the telemetry rollup
  • Verify data still persists to personal server after the export-complete fires

Depends on

  • vana-com/context-gateway#38 (the unified telemetry contract)

…ction_completed on data arrival

Two fixes bundled because they touch the same files:

1. collection_completed no longer fires when data arrives

The export-complete handler was calling markCollectionCompleted whenever
the connector emitted data via setData('result'). For multi-step
connectors that stream partial results, this marked the run as complete
mid-execution — the UI showed success while the connector was still
running, and the COMPLETE status event that fired later was deduped away.

The fix splits responsibilities:

- connector-status COMPLETE is the authoritative terminal signal. It
  fires when the connector process exits and is the only place
  markCollectionCompleted gets called during a connector run.
- export-complete now handles persistence only. It continues to write
  data to the personal server when it arrives, without touching run
  status or telemetry.

persistedRunIds dedupes across both paths so simple connectors that
attach data to the COMPLETE payload still persist correctly.

2. Align contract types with the server

Updates src/lib/telemetry/contracts.ts to match the unified contract
at https://github.com/vana-com/context-gateway/blob/main/packages/contracts/src/telemetry.ts

Notable changes:

- Added grant_flow_started and grant_flow_expired to the event name list
- Removed needs_input from the error class whitelist; use
  abandoned_waiting_for_input for real timeouts
- Removed the outcome field (rollups use eventName + errorClass, never
  a free-form string)
- Added detail (free-form debugging) and recordCount fields
- Added trackGrantFlowStarted and trackGrantFlowExpired helpers
- trackCollectionNeedsInput no longer sets errorClass (it's intermediate,
  not a failure); added optional interactionKind metadata

See TELEMETRY.md in context-gateway for the state machine, outcome
priority rules, and migration notes.
@tnunamak
Copy link
Copy Markdown
Member Author

Superseded by #104. The useEvents terminal/persistence fix is already included there, and #104 carries the newer honest-telemetry runtime work plus follow-up fixes. Closing this to avoid competing telemetry branches.

@tnunamak tnunamak closed this Apr 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant