Part of Stem. The "Agents and notifications" frame on the Seed Resources board held one question, whether the whole set of notifications could be a tree owned by the account or by the server, and an open request to sketch how an agent system and its notifications would be represented as resources and links. This page answers in Stem vocabulary. It is the Stem thesis applied: new concepts arrive as kinds, grants and policy rules, and the protocol does not change.
Prior work this builds on
Agent permissions on the Hypermedia network: scoped, revocable, verifiable capabilities for agent servers, with a reader role, expiry and revocation by tombstone.
Portable agent sessions: signed, content-addressed session logs any server can verify and sync.
Agents and permanent data: how agent server state maps onto signed data, and the case for sessions as comments.
Seed Agents: the hosted runtime as it exists today.
Agents are keys with grants
An agent is a key. The owner gives it authority with a Grant: subject the node or subtree the agent should work in, audience key(agent), access write (or read for an agent that only answers questions), and expires set, because an agent's authority should lapse without anyone remembering to revoke it. The agent then signs Node, Change and Snapshot blobs with its own key and names the grant as proof, so every edit it makes is attributable to the agent and to the owner's decision to let it. Revoking the grant stops the agent at once, and blobs it signs afterwards are stashed, not applied.
This replaces today's AGENT role, which let a key act as the owner across the whole space with no scope and no expiry, and it removes the asymmetry noted in the roadmap that agent delegations need care because reading and syncing are the same permission: an agent's write grant on a subtree gives it exactly that subtree's blobs over sync, and nothing else. An agent server holding several agents' keys is an ordinary peer that authenticates as each agent and follows each agent's scopes under its policy.
The three-key chain from the agent permissions note (owner to server key to per-agent key) is two grants: the owner grants the server key admin on the agents' working subtree, and the server key grants each agent key write on its part of it, with the server's grant as proof. Revoking the server's grant cuts every agent under it in one step, which is the two-pass evaluation doing what it is for.
The agent as a resource
An agent's definition is a resource of a kind agent, published in the owner's space under a folder of the owner's choosing. The kind is not part of Stem's core and is sketched here as a descriptor that the agents runtime would publish.
Kind field | Value |
|---|---|
|
|
| an attributes schema with the agent's display name, its key, its instructions, the tools it may call as links to tool definitions, and the model it runs on |
|
|
|
|
|
|
|
|
|
|
Nothing about this is special to the daemon. A reader that may read the agent node sees its definition; a writer that may write it changes the instructions; the runtime that holds the agent's key follows the node and acts on it. Moving an agent between servers is moving which peer holds the key, with no data migration, which is the portable-sessions goal.
Sessions
A session is a resource. Its kind, session, has state: any: a session may be a Change graph when it is edited like a document, or a Snapshot chain where each Snapshot is the log so far and prev names the previous one, which is the append-only signed log the portable-sessions note describes. Its parent is the agent node, so sessions are listed under their agent and move with it. Its default access is own, and the owner's grant to themselves is implicit (the owner is a permanent admin), so a session is readable by the owner and by the agent key that writes it, and by nobody else unless the owner grants it. A public session for trustless audit is one grant to everyone.
Each event in the log (a user message, a model response, a tool call, a tool result) is an element of the state, not a resource. The exception is a tool result that is itself a document write: it produces a Change in the target document with a mention link back to the session node, which is the provenance that lets a reader ask which agent run edited a paragraph. The team's earlier question, whether a session is a comment on the agent or a resource of its own, is answered the same way as for comments: it is a resource, because it has identity and a lifetime, and it is unnamed and target-like, which its Kind descriptor says.
Triggers
A trigger is a rule, not permanent data: "when a comment appears on resource X, run agent A". Conditions such as "a comment appears on X" are exactly the scope sets of The sync protocol with the comments facet, and the agent server observes them by holding a Watch on the scope, the same way a client does. Where a trigger should survive the server, it is stored as a resource of a kind trigger under the agent node with the owner as its audience, so another server that takes over the agent's key finds its triggers by following the agent. Nothing about triggers needs a protocol change.
Notifications
Who owns the notification set? The account. A notification is a derived fact with provenance derived: "resource R changed in a way account A has said it cares about", computed by a peer from the mention and target links whose target is A or a node A owns, from the comments facet of the scopes A follows, and from A's policy. Each of A's devices derives its own set from the blobs it holds, with no server involved.
A notification server is a peer that does this derivation on A's behalf and keeps the result available while A's devices are offline. It needs to see everything A would see, so A grants the server's account sync on the resources it follows (today the server is expected to see "everything" because it sends the emails; in Stem that expectation is a grant the owner can inspect and revoke). The server's derived set is written as a resource of kind notifications in A's space with audience key(A), so it travels only to A's devices through ordinary sync, and A's devices treat it as a cache: if a device's locally derived set disagrees, the local set wins. Read state (seen or unseen) is a second resource of the same shape written by A's devices, which the server never needs to write.
The board asked whether the notification set could be a Prolly tree. It could: it is a sorted key and value set partitioned by a single audience, and a device coming back online would diff it against its own. Stem does not need to decide that here, because the set is a resource like any other and its internal layout is the kind's business. The team's earlier note on notification reconciliation observed that the client must be able to generate its own notifications without the server, and that a consistent notification id is needed; Stem's id is the pair (source blob CID, the fact it triggered), which every peer derives identically.
What this needs from the core
Node, Grant and Snapshot. Nothing agent-specific.
Kind descriptors for agent, session, trigger and notifications, published by the agents runtime, and schemas for their states.
The key audience and expires on grants, so that agent authority is scoped and lapses.
The sync level and the Watch RPC, so a notification server can observe without being a reader of anything beyond what the owner granted.
The mention link kind, so provenance from a document edit back to the session that caused it is a derived fact every peer can compute.
Every item is already on this site. That is the test the Stem landing page sets: new concepts arrive as schemas and linked records, and the protocol does not change.
Open questions
Open: whether an agent's key should be allowed to hold admin over its own sessions so it can grant a collaborator read access to one, or whether only the owner should.
Open: whether notifications derived from public content should be computed by the account's site rather than a dedicated notification server, now that a site is an authority peer with a sync grant.
See also
Authority: grants, expires, delegation and the two-pass evaluation.
Privacy: the key audience and what a sync grant discloses.
Resource kinds: how a runtime publishes new kinds.
Links: mention and target.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime