ReadonlyagentNicknames of every agent in the room, in room order.
ReadonlycallerReadonlyroomReadonlyroomThe named artifact, or undefined. Viewer scoping is not applied.
The names of every artifact in the room, including ones the caller cannot view.
Creates or overwrites an artifact. A new artifact is credited to the calling agent and defaults to being viewable by every agent in the room; an existing one keeps its creator, and keeps its viewers unless new ones are given.
The artifact name (the room's primary key for artifacts)
The new body; must not be empty
Optionaloptions: ArtifactWriteOptions
Viewers and authorship — see ArtifactWriteOptions
The stored artifact
If body is empty — that would delete the artifact; use remove.
True if an artifact was found and deleted.
Renames an agent, and everything in the room that named it.
A room routes by nickname and nothing else, so an agent whose character is called something different gives every other agent two names for one person: the game master addresses the character, the room has never heard of them, and the message goes nowhere useful. Renaming the agent to its character is how a pack collapses the two back into one name.
The artifacts the agent created or can view are repointed with it, which is
the part that fails silently otherwise — a player keeps their character sheet
only because viewers was updated too.
As expensive as setDescription and for the same reason: the roster sits in every agent's cached prompt prefix. Do it at character creation, when play has not started, rather than mid-scene.
The agent to rename, matched the way messages are routed
The character's name; the routing nickname is its first word
What happened, including why when nothing did
Sets how an agent in this room is described to the others.
The description is every agent's public identity: it is rendered into the roster of every other agent's cached prompt prefix, ahead of their attached documents. So a write invalidates the cached prefix for everyone in the room, and a tool that rewrites a description regularly will cost far more than it looks. Use it for facts that will not change again — who a character is, not what state they are in.
The agent to describe; must be in this room
The new description; trimmed, and capped at 500 characters
True if the agent was found and updated
Reads, mutates and writes an artifact without yielding to the event loop.
The artifact name
Receives the current artifact (or undefined if absent) and returns the new body, or null to leave the artifact untouched. Must not await.
Optionaloptions: ArtifactWriteOptions
Viewers and authorship — see ArtifactWriteOptions
The stored artifact, or undefined if mutate returned null
Read/write access to the artifacts of the room a tool is executing in, plus the identity of the agent that called it. Lets a tool hold durable state that the agents can also read, instead of every tool having to be stateless or reach outside Briyah for storage.
Every method is synchronous on purpose. The underlying store is synchronous (Room.publishArtifact -> ArtifactStoreService.saveArtifact -> writeFileSync), so a read-modify-write performed inside a single update call cannot be interleaved by the event loop. Handlers must therefore use
updaterather thanget... await ...put: concurrent tool calls do happen, since commissioned agents run their turns under Promise.allSettled.