feat(client): StateBus observer + tag API#203
Open
runyaga wants to merge 1 commit into
Open
Conversation
Adds an additive `addObserver` hook on `StateBus` that fires after every successful commit, plus an optional `tag` argument on `setAgentState` and `update` so writers can label the source of each write. Observers receive `(tag, snapshot)`; the snapshot is the frozen post-commit map already exposed via `agentState`. `addObserver` returns a disposer for symmetric tear-down. Detaching during dispatch is safe (siblings still fire). Adding to a disposed bus is a no-op. Pure additive: existing call sites continue to work without modification, and the new `BusObserver` typedef is exported via the existing `application` barrel. 11 tests cover the observer dispatch ordering, dispose semantics, self-detaching observers, tag preservation, and disposed-bus safety. Foundation for an upcoming Bus Inspector debug surface that needs to record every state commit on a per-thread basis without forcing a bus dependency on the agent layer's diagnostics.
This was referenced May 1, 2026
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
1 participant
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.
Part of #202 (1 of 4 stacked PRs). Merge first — base for the other three.
What this changes
StateBus(insoliplex_client) gains:void Function() addObserver(BusObserver observer)— register acallback that fires after every successful commit. Returns a
disposer for symmetric tear-down. Detaching during dispatch is
safe (siblings still fire). Adding to a disposed bus is a no-op.
String? tagargument onsetAgentStateandupdate—writers can label the source of each commit, observers receive it.
Why this shape
The upcoming Bus Inspector (#202) needs to record every state commit
with thread context. Putting the recording logic on a per-bus
observer keeps the bus pure (no inspector dependency) and lets any
future diagnostic plug in without modifying core code.
The
tagargument is optional so existing callers don't change; theagent layer will set it explicitly only at the seed paths
(
seed.initial,seed.history).Testing
11 new unit tests cover dispatch ordering, dispose semantics, the
self-detaching-during-dispatch case, tag preservation, and disposed-bus
safety. Existing tests unchanged.
Stack