Required updates for Watcher
The LiteLLM integration validates one conversation ID before generating a reply. The Analyzer filters sessions by the integrations that delivered them.
The native Copilot gateway
can link a new child session to the parent task call that started it. This
works for sync and background children across the supported inference formats
when the task prompt has one exact match.
When the Watcher client and the Aperture gateway hook both record the same Claude Code or Codex conversation, Watcher stores both copies in one session and reads them as one reconciled transcript, so every tool call appears once. Sessions with a single recorder are unchanged.
What's new?
- A supplied
x-watcher-session-idtakes priority over native conversation IDs. Without it, LiteLLM uses the native Claude Code, Codex or OpenCode ID. Missing, invalid or conflicting selected IDs return HTTP 400 before model generation. See the identity contract. - Source badges and filters use delivery history. The Gateway category includes Aperture; select a named integration to narrow the results. Saved links using the previous Source filter no longer keep that selection.
- The parent's trajectory can list each matched child with its spawning call.
- Unknown or duplicate prompts retain the parent link without a spawning call.
- The gateway database stores task-prompt digests and call IDs, but no prompt text or GitHub credentials.
- Both copies are stored in one session, whichever recorder delivers first. Each recording keeps its own trajectories.
- The Analyzer, the API's trajectory routes, the tool-call list, Deep Review and fresh session summaries read the reconciled transcript: the client's copy, with each tool call only Aperture saw inserted where it belongs. While the session is active, a summary refresh continues the last Triage call and describes the copy that call read; the summary written once the session goes idle reads the reconciled transcript. Any trajectory ID of either copy opens a reconciled transcript, including one naming a message partway through a copy (such as a link to one tool call). The API has no option to read one copy as stored.
- On-demand grading reads the reconciled transcript too. When a requested
trajectory ID names a message partway through either copy, the returned
grade's
trajectory_hashnames the transcript's current endpoint instead. A batch grades each transcript once per grader, even when several requested IDs resolve to it. Those extra IDs do not appear innot_found_ids. - In these sessions, a message's
indexis its position in the reconciled transcript, and the trajectory list shows one entry per conversation branch rather than one per stored copy. Session list and detail responses count the same way:trajectory_countcounts reconciled transcripts andmessage_countthe longest one's messages. Eval exports hold one sample per conversation branch. - Reading one message by its
message_reftakes an optionaltrajectory_id, the transcript it is shown in, and returns the message with that transcript's reading position. A message the transcript leaves out, such as Aperture's copy of a message the client also recorded, returns 404. Each tool-call list entry'smessage_refnames the message the transcript shows that call on, which may differ from the message its decision was recorded against. - Where Watcher cannot tell which part of the client's copy an Aperture branch belongs to, that branch stays a trajectory of its own rather than being placed by guess. The details are under Trajectories.
Required upgrade steps
LiteLLM identities and saved Source filters
These steps apply to teams using the LiteLLM integration or saved Analyzer Source filters, on self-hosted deployments and Watcher Cloud.
- Upgrade Watcher before deploying the updated LiteLLM callback. Self-hosted operators follow Update Watcher. Teams using Watcher Cloud deploy the callback after the server update is available there.
- Check that each LiteLLM request supplies a valid native conversation ID
or a stable
x-watcher-session-id. Keep the same selected ID across turns. If you supply custom IDs, use a different one for each child you want recorded as a separate session. Changing between custom and native IDs can start a separate session; existing session identities are not rewritten. - Recreate saved Source-filter links using the Analyzer's current Source controls. Select LiteLLM or Aperture to keep results limited to that integration, rather than the whole Gateway category.
- Verify that two turns in one LiteLLM conversation appear in the same session. If you use child sessions, check that their distinct IDs produce separate sessions. Open each replacement bookmark and confirm its Source selection and results.
Native Copilot child-session links
These steps apply to self-hosted installations using the native Copilot gateway. Other deployments need no action for this change.
- Before starting new gateway replicas, apply the gateway migration to its
existing shared PostgreSQL database. The gateway Helm chart runs this Job
during upgrades. For a direct launch, run
watcher-litellm-copilot-migratefrom the updated gateway environment. - Wait for the migration to finish before completing the gateway rollout. Existing data remains intact, and old replicas can use the updated schema.
- After every gateway replica has been upgraded, start a new Copilot session with a sync child and a background child, each using a different task prompt. Check that the parent's trajectory lists both children with their spawning calls.
Use the normal update procedure for the Watcher components you are upgrading.
Conversations recorded twice read as one transcript
These steps apply to API integrations that read, or send hook requests for, conversations both the Watcher client and the Aperture gateway hook record, on self-hosted deployments and Watcher Cloud alike. No deployment configuration or developer-machine changes are needed. Self-hosted operators apply the server update using Update Watcher; on Watcher Cloud, only the integration changes below apply.
- If your integration keeps message
indexvalues, trajectory or message counts, ormessage_refvalues from these sessions, treatindexas a position in the reconciled transcript and expect one trajectory per conversation branch. Re-read the transcript rather than reusing numbering or references read before the upgrade, and pass the transcript'strajectory_idwhen reading one of its messages. - If your integration requests grades, use each returned
trajectory_hashto identify the graded transcript. Do not match results to requested IDs by position or expect one result per requested ID. - If your integration sends gateway-hook deltas with
append_afterfor these conversations, continue from theappend_afteranchor your last successful append returned. A trajectory read returns the reconciled transcript, not the stored chain your delta continues, so it cannot confirm the prefix. Without an anchor, send full requests. See Send only new messages. - To verify, open a session both recorders delivered to. Its trajectory list shows one entry per conversation branch, and each tool call appears once in the transcript.