What the agent always sees: a live map of its workspace
The native KDCube ReAct Agent gets a live map of its disposable, distributed workspace: what is local now and what survives as a durable ref, so it can read, pull, or checkout by intent.
KDCube is an agentic platform — an app can run many agents: build your own, bring Claude Code, or mix them. The native KDCube ReAct Agent is the agent we ship and run ourselves, built to work robustly in a distributed, isolated runtime with its own skills, tools, and a real file workspace. Today's entry is about how that agent understands and controls its workspace.
Inside a conversation it works in turns, and inside a turn it takes small steps: act, see the result, then decide the next move. To do real work it reads files, edits them, and runs code. Two facts make its workspace tricky, and three intent-specific operations make it usable without making local disk durable by accident.
Fact 1 — the workspace is rebuilt every turn
Every turn can start on a different machine with an empty workspace. The only thing carried in is the conversation timeline (which we cache). So nothing you produced last turn is sitting on disk now — only a reference to it survives across turns.
Fact 2 — the workspace is semantically rich, not a flat folder
The agent doesn't see one undifferentiated folder. It understands kinds of workspace — each with its own meaning, storage, and lifecycle — and puts each thing where it belongs:
Knowing that a project belongs in versioned git/projects/ while a one-off export
belongs in files/ is part of the agent's competence — that's
control, not just storage.
Choose the operation by intent
A durable object locator does not imply that its bytes are already on this worker. The agent chooses what it needs to do with the object; the shared workspace machinery resolves the same authorized source for each operation:
A materializable locator such as conv:fi:… or an authorized owner ref can
be passed directly to all three operations. read projects bounded text, images,
or document content into model-visible blocks without creating a workspace copy.
pull creates a collision-safe read-only local materialization for
inspection or code. checkout creates or resets an editable copy
under the current turn's files/ or git/projects/; directory checkout
can deliberately replace or overlay. Code execution then works on the returned relative
path. Durable publication remains a separate, explicit step.
An event occurrence is different. A conv:ev:… event_ref
identifies what happened and is readable as an event envelope; it is not itself a byte
locator. When the event also carries an object_ref, that separate ref is what
the agent reads, pulls, or checks out. An event without an object ref still has useful
identity and metadata, but no attached bytes to materialize.
The live view — always in front of the agent
For the native KDCube ReAct Agent, the persisted timeline is the durable model-input projection, and its stable prefix can be cached. But some things change every single round and must not be cached: the budget, live user interrupts, and what is in the workspace right now. So the agent keeps a small, always-on live view in front of it — a designated area of heightened attention for the immediate, volatile signals it must not lose track of, recomputed each round.
Where the live view sits
Everything the agent sees arrives as one ordered input. First a stable envelope: its instructions, then the catalog of tools it can call and the skills it can run. Then the timeline of events, oldest → newest — history, this turn's request, and the progress so far. And always at the very tail, the live view.
The agent knows its attention board — the volatile, immediate signals — lives there, last, on every round. The front of the input is stable and cacheable; the live view is recomputed each round, so it can change between rounds, not just between turns.
What we improved today
The live view now shows the agent a live map of its workspace, in two halves:
- LOCAL — exactly what is materialized on disk this turn, including read-only pulls and editable checkout/output areas.
- REMOTE — durable projects and refs that can be read, pulled, or checked out according to intent, with a single anchor that precisely addresses the latest committed project state.
Before, the agent could see a reference to a file it made last turn and wrongly assume it was still on disk — then fail the moment it tried to use it. Now it can tell at a glance what is already local versus what survives as a durable source, then read it into context, pull a read-only copy, or checkout an editable copy according to the work it intends to do.
Documentation on GitHub
The live docs behind this entry: