Module agent_registry 

Per-principal roster of software agents.

The chat graph is primarily human↔human. A software agent is never a free-standing chat actor — it is always defined under a human principal and is invoked into a conversation on that principal’s behalf (see crate::chat_agents, which binds a sub-agent DID to a session). This module is the durable roster of the agents a principal has configured: their persona, backend, tool allowlist, sensitivity ceiling, and outcome-sharing posture.

Agents are diverse in backend (see AgentBackendSpec):

• AgentBackendSpec::LocalEngine — runs in-process on the native p64/q42 engine. No outbound traffic; preferred for all work, and the only backend suitable for the most sensitive material.
• AgentBackendSpec::RemoteMcp — reached over an external provider’s MCP interface (e.g. a hosted Claude / Google / X model). This is opt-in and costly, and by default handles only non-sensitive material. Only the configuration lives here — the actual MCP client (transport, calls) lives in the sibling remote_mcp.rs; this module never performs network I/O.

Persistence

The roster is stored as pretty-printed JSON at <storage_root>/Agents/roster.json, mirroring the load/save-under-a-dir pattern used by crate::social_peers and crate::node_identity. The filesystem functions take an explicit storage_root: &Path so they are testable against a temporary directory. A missing or empty roster is treated as un-initialised and yields a roster seeded with a single default local agent (default_local_agent); the roster is therefore never observed empty, and a pure load_roster never writes to disk.

Re-exports

pub use crate::chat_agents::OutcomeSharingPolicy as OutcomeSharing;

Structs

AgentContextPolicy

Directional context contract for a named agent.

AgentDataPolicy

Per-agent data boundary. An empty allowlist means the agent may use only the ontology scopes already admitted to its chat session; a non-empty list further intersects that session scope. It never widens access.

AgentDefinition

A single agent in a principal’s roster.

AgentExecutionPolicy

Per-agent scheduler and placement policy. It describes a preference, not a reservation: the runtime may decline a pinned/keep-warm request when the caller’s device budget cannot safely admit it.

AgentSemanticProfile

Ontology-linked profile used to narrow routing and disclose an agent’s declared scope. The profile may recommend tools/datasets but permissions and tool allowlists remain separately authoritative.

AgentSemanticTag

An ontology-addressable point in the agent’s declared study graph. broader_iri links a specialization to its selected parent, giving a bounded path such as Researcher → History → Australian History.

Enums

AgentBackendSpec

Which inference backend an agent uses.

AgentJobPriority

Scheduler priority for work requested through an agent.

AgentSemanticFacet

The role played by a semantic tag in an agent’s pointed study graph. Tags are declarative grounding hints and never confer data/tool authority.

AttachmentAccess

Whether files selected in the conversation may enter an agent context manifest.

ContextVisibility

Default visibility of an agent’s completed answer.

ConversationAccess

Conversation material an agent is permitted to receive for a turn.

McpTransport

How a AgentBackendSpec::RemoteMcp agent’s MCP server is reached.

ModelResidencyPreference

Residency preference for a local model selected by an agent.

RemoteConsentPolicy

Consent required before an agent may use its configured remote backend.

RetrievalAccess

Whether graph/retrieval results may be included in an agent context manifest.

Constants

SENSITIVITY_LOCAL_DEFAULT

Default sensitivity ceiling for a fully-local agent.

SENSITIVITY_PUBLIC

Sensitivity scale floor: public / non-sensitive material only.

Functions

bind_agent_did

Derive the deterministic sub-agent DID under which an agent acts in a session, scoped to principal_did + session_id.

default_local_agent

The default local agent that seeds an un-initialised roster.

get_agent

Fetch a single agent by slug, if present in the (possibly seeded) roster.

load_roster

Load the principal’s agent roster from <storage_root>/Agents/roster.json.

remove_agent

Remove the agent with the given slug from the stored roster, then persist.

save_roster

Persist roster to <storage_root>/Agents/roster.json as pretty JSON, creating the Agents directory if needed.

upsert_agent

Insert or update agent in the stored roster, keyed by slug, then persist.

upsert_agent_at

upsert_agent with an explicit now_unix timestamp, for deterministic testing and callers that already hold a clock reading.

validate_agent

Validate values that cross the roster/UI boundary. This is intentionally a cold-path check: it protects stable mention keys and prevents a malformed execution preference from becoming a scheduler ambiguity.