The Public Story And The Private Path
ImpactRoom works by separating a simple public story from a more careful private execution path. On the public side, an agent connects, reads state, discovers actions, posts short Public Observations before intent actions, and submits only the guided requests it has been given. On the private side, the system evaluates those requests against state and policy, admits work when the conditions are met, validates claimed work against the earlier binding, and then either materializes a visible change or returns no-impact feedback. That separation is the point of the demo.
The Guided Public Entry
At the center of the experience is the guided Agent Surface. An external agent does not begin by constructing a raw internal request. It begins by calling /connect. The response returns a session, the state URL, and the public move, intent, and observation routes. This is important because ImpactRoom is meant to teach correct integration habits. A good public surface does not assume that an agent already knows the private shape of the runtime. It gives the agent a small, explicit public entry point and then keeps the rest of the interaction grounded in public state.
Public State And Affordance Discovery
The first thing the agent does after connecting is read /agent/state. That state is not a dump of everything the adapter knows. It is a guided public view with the current station, visible stations, visible objects, and the actions the agent may attempt. The key word is attempt. These are affordances, not guaranteed-success instructions. The public surface is self-describing in the sense that it tells the agent what kind of action it can submit next and how to submit it. It does not flatten the room into a single always-correct sequence.
That distinction matters because ImpactRoom is designed to teach exploration with constraints. The agent may see Admin Override from the start, but it cannot use that intent from anywhere in the room. It must move to the correct station first. It may later see that opening the door is relevant, but the door-open intent only makes sense from the station where the current model says that interaction can happen. This keeps the public surface readable without pretending that visibility and authority are the same thing.
Public Observation Before Intent
Before any intent action, the agent must post a short Public Observation. The current route name is /agent/thought, but the public meaning is a visible agent note. This note is intentionally small. It is not a hidden reasoning channel and it is not a private control surface. It is a short public sentence that says, in effect, “I see this, and I am about to try that.” Movement does not require the observation step. State reads do not require it either. The requirement exists specifically to keep impact-oriented intent attempts visible in the public story.
The canonical request field for that note is text. The public route also accepts observation as an alias because external agents naturally use that word for the same public note.
Returned Submit Metadata
Once the agent has current state and, when needed, a fresh Public Observation, it submits actions through the returned submit metadata. That metadata tells the agent the method, URL, and public request body. This removes guesswork without leaking internal request fields. The guided surface can also reject requests locally when the error is clearly owned by that surface. If the agent tries a station-bound intent from the wrong station, the public surface can return a wrong-station response before any raw boundary submit. If the agent skips the observation step, the public surface can return an observation required response without involving deeper machinery. This is not an optimization trick. It is part of making the public contract coherent.
The Boundary And Materialization Path
From there, the path moves into the private execution model. At a high level, the current architecture looks like this:
The staged operation step matters because the public action is not itself the visible effect. The public request becomes a bounded operation that is tied to the relevant state evidence for that moment. The adapter host then calls the adapter’s state and policy paths privately. The state view says what the system currently knows in the authorized scope. The policy step evaluates whether the requested operation fits that state and policy context. If the work is admitted, it still has not yet become a visible change in the room.
Admitted Work, Claimed Work, And No-Impact
That next distinction is the one many demos hide. In ImpactRoom, admitted work and materialized impact are separate events. A worker later claims the admitted work and validates it against the earlier binding. The validation includes the state evidence, the expected revision, and the specific operation mapping. If the current state no longer matches the earlier conditions, the adapter does not silently pretend the action succeeded. This is where stale capability and no-impact behavior become visible.
Stale Capability And Fresh Capability
The key story in ImpactRoom makes this easy to see. After approval, the agent can obtain a scoped key. That key is bound to the public door state at the time it was issued. If the relevant state changes and the key is no longer fresh, the later door-open attempt does not produce a visible door change. The public feedback makes that clear, and the observer ledger can show the evidence in a compact public-safe way. This is more instructive than a generic failure message, because it teaches the difference between possessing a capability and having a capability that still matches current trusted state.
A fresh key changes that outcome. Once the agent refreshes the capability so it matches current public state, the door-open intent can materialize. Visible change appears in the room only after the implemented boundary path and the adapter materialization path say the action is valid for the current moment. That is the public meaning of materialization in this demo. It is not “the agent asked for a change.” It is “the system accepted the work, validated the binding, and applied the change.”
Observer Projection And Operator Approval
The observer side reinforces the same lesson. The browser does not drive the agent path by reading private adapter state or calling raw write endpoints. It reads sanitized observer projection. The map updates when confirmed public state changes. The ledger records compact public events and evidence. The latest agent note appears near the agent marker. That means the observer story stays grounded in the same bounded path instead of drifting into a separate hidden control flow.
Operator approval remains separate throughout this flow. The agent may request the scoped key, but it cannot approve that request for itself. During approval wait, the agent sees a waiting phase and no attemptable actions. The correct behavior is to keep polling state until operator action occurs. Once approval has been granted, actions appear again and the agent continues through the same public surface. This reinforces a central architectural point: authority is not collapsed into a single actor just because the scenario is small.
Why The Flow Matters
Seen end to end, ImpactRoom works because each layer does a clear job. The public surface teaches the agent how to participate without guessing internal details. The private boundary path decides whether work can proceed under the current state and policy. The adapter keeps ownership of domain state and only materializes visible impact after the claimed work still matches the earlier binding. The observer projection turns the result back into a public story that people can understand. That is what makes the demo more than a room with a door. It is a compact example of how bounded agent impact can be made visible, testable, and teachable.