fix(core): accept usage_recorded in AgentRun event schema (desktop fails to start) - #1945
Merged
Astro-Han merged 2 commits intoAug 3, 2026
Merged
Conversation
The agent runtime writes a 'usage_recorded' event after each provider request completes, but 'usage_recorded' was missing from AGENT_RUN_EVENT_TYPES. Strict AgentRun ledger reads (used at desktop startup) throw 'Invalid AgentRun event schema' for any event with an unknown type, so a single normal run bricked the whole app on next launch. Add the missing event type to the enum. Token-usage data on these events is free-form (Record<string, unknown>), and projection handling is generic, so no other changes are required. Fixes apache#1942 Signed-off-by: pi + deepseek-v4-flash
Contributor
|
Hi @Astro-Han, would you mind taking a look when you have a chance? I know this is mostly a schema compatibility issue, but it’s currently blocking me from using Desktop—the app can no longer start after a normal run. If the fix looks right to you, could you help get it merged? Thanks! |
Contributor
|
@me2seeks Happy to do it! will merge this fix asap. |
Astro-Han
added a commit
that referenced
this pull request
Aug 3, 2026
An AgentRun ledger is append-only and outlives the build that wrote it, but `decodeAgentRunEvent` rejected any event whose type was absent from `AGENT_RUN_EVENT_TYPES` — conflating "this build does not write it" with "this record is damaged". #1755 retired the `usage_recorded` writer and dropped the enum entry in one step, which is correct for the writer and retroactively illegal for every ledger already on disk: v0.1.3 then refused to start on any machine that had run v0.1.2 (#1942). Decode now accepts any non-empty string type and keeps validating the envelope, so strict recovery still rejects genuinely damaged records while tolerating both retired types and types from a newer build a user downgraded away from — a direction no enum discipline can cover. `AGENT_RUN_EVENT_TYPES` becomes what this build emits rather than what it can read, and the `usage_recorded` entry added by #1945 is dropped as the dead entry it now is. Fixes #1942
Astro-Han
added a commit
that referenced
this pull request
Aug 3, 2026
`AGENT_RUN_EVENT_TYPES` was both the set this build writes and the set a reader accepts. The ledger is append-only and outlives the build that wrote it, so retiring a writer and deleting its entry in one commit (#1755) left the next build unable to decode records the previous one had persisted, and the desktop app failed to start (#1942). Only the write side can be a closed set. Reads take `type` as an open string with the envelope around it still validated, so a damaged record is still rejected; appends take `EmittedAgentRunEvent`, so a misspelled or retired type fails to compile at the call that would persist it. That makes retiring a writer safe, which is why `usage_recorded` is gone again: #1945 could only fix the crash by adding a type nothing writes back to the catalogue this build writes from. A copy drops an event this build does not emit rather than carrying its unrewritten source-owned ids into the target, since the rewriters cannot inspect a payload they do not know.
Astro-Han
added a commit
that referenced
this pull request
Aug 3, 2026
`AGENT_RUN_EVENT_TYPES` was both the set this build writes and the set a reader accepts. The ledger is append-only and outlives the build that wrote it, so retiring a writer and deleting its entry in one commit (#1755) left the next build unable to decode records the previous one had persisted, and the desktop app failed to start (#1942). Only the write side can be a closed set. Reads take `type` as an open string with the envelope around it still validated, so a damaged record is still rejected; appends take `EmittedAgentRunEvent`, so a misspelled or retired type fails to compile at the call that would persist it. That makes retiring a writer safe, which is why `usage_recorded` is gone again: #1945 could only fix the crash by adding a type nothing writes back to the catalogue this build writes from. A copy drops an event this build does not emit rather than carrying its unrewritten source-owned ids into the target, since the rewriters cannot inspect a payload they do not know.
Astro-Han
added a commit
that referenced
this pull request
Aug 3, 2026
`AGENT_RUN_EVENT_TYPES` was both the set this build writes and the set a reader accepts. The ledger is append-only and outlives the build that wrote it, so retiring a writer and deleting its entry in one commit (#1755) left the next build unable to decode records the previous one had persisted, and the desktop app failed to start (#1942). Only the write side can be a closed set. Reads take `type` as an open string with the envelope around it still validated, so a damaged record is still rejected; appends take `EmittedAgentRunEvent`, so a misspelled or retired type fails to compile at the call that would persist it. That makes retiring a writer safe, which is why `usage_recorded` is gone again: #1945 could only fix the crash by adding a type nothing writes back to the catalogue this build writes from. A copy drops an event this build does not emit rather than carrying its unrewritten source-owned ids into the target, since the rewriters cannot inspect a payload they do not know.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Desktop app fails to start after any normal run:
The run event ledger (
workspaces/<ws>/sessions/<session>/runs/<run>/events.jsonl) containstype: "usage_recorded"events, butusage_recordedis not inAGENT_RUN_EVENT_TYPESinpackages/core/src/agent-run.ts. The strict read path in@maka/storage(readEventswithstrict=true) throws on any event whose type is not in the enum, which blocks app startup.Verified: all 4 runs on a real machine contained a
usage_recordedevent, i.e. every run that completes a turn with token usage writes one — so this is a guaranteed recurrence, not one-off corruption. The event JSON itself is valid; the failure is purely schema-level.Fix
Add
usage_recordedtoAGENT_RUN_EVENT_TYPES.AgentRunEvent.dataisRecord<string, unknown>and projection handling is generic, so no other changes are required.Verification
packages/coretypecheck + build pass (tsc).node --test dist/__tests__/agent-run-*.test.js→ 9/9 pass.decodeAgentRunEventagainst the original on-disk ledger from the failing machine (backup of 4 runs, 62 events including 4usage_recorded): all 62 decode successfully, 0 failures.Fixes #1942