Module agents 

Agent subsystem — definitions, instances, and their lifecycle CRUD.

Covers agent_def_* methods (template + user-clone definitions), instance_* methods (per-launch instance rows, named-agent continuation, identity-bound active-for-block resolution), the AgentDefinition / AgentInstance structs, and the InstanceStatus enum.

This file holds the types and defaults; the methods are in definition (agent_def_*) and instance (instance_*), the shared column lists and row mappers in row, slugs and name-keyed rows in name_keys, and the delete cascade in purge.

Every method in both groups reads and writes db_agents only, as of the agent-concept consolidation’s definition flip (docs/specs/SPEC_AGENT_ARCHITECTURE_2026_05_27.md Phase 3d) — the instance side flipped first (Phase 3b, PR 2 of 4, #3080), the definition side followed once the six agent-child tables’ FK re-pointed to db_agents (Phase 3c, PR 3 of 4, #3088) removed the reason agent_def_get had to stay scoped to db_agent_definitions. Neither legacy table has a live writer left in this file; the old dual_write module, which used to mirror definition writes into db_agents, is gone — there is no second table left to mirror into one from.

db_agent_definitions and db_agent_instances are still physically present in the schema (dropped in a later PR) — do not read either as a live source anywhere in this file; every read here is db_agents.

Re-exports

pub use name_keys::AgentNameMatch;

Modules

definition 🔒

agent_def_*: the agent-definition catalog’s CRUD on db_agents.

instance 🔒

instance_*: per-launch instance rows, named-agent continuation, and identity-bound active-for-block resolution, on db_agents.

name_keys 🔒

Slugs and the name-keyed rows (KEY_NAMEs) an agent’s names map to: collision-free slugs, tombstoning a renamed agent’s keys, and finding agents by name.

purge 🔒

Removing an agent’s dependent rows when the agent itself is deleted.

row 🔒

The db_agents column lists and row mappers the definition and instance reads share.

Structs

AgentDefinition

A user-defined AI agent in the user’s agent-definition catalog.

AgentInstance

One row per running/historical execution of an agent definition. block_id / session_id / github_context are modelled as empty strings on the wire rather than Option<String> to match the existing schema conventions (NOT NULL DEFAULT ''). Callers that need structured absence can use .is_empty().

InstanceUpdate

Partial-update payload for Store::instance_update_partial. Each Some field is written; None leaves the column untouched. Mirrors the mutable subset of CommandUpdateAgentInstanceData (block_id/session_id/status/github_context/ended_at) — the only columns instance_update ever wrote. Some("") for a string field explicitly clears it.

Enums

InstanceStatus

Instance lifecycle status. Serialised lowercase to match the DB text.

Constants

LAST_RUNTIME_KEYS 🔒

The only keys a remembered runtime may hold, and the longest value of each.

Functions

default_agent_type 🔒

default_agent_working_dir

The working directory agent.open substitutes when an AgentDefinition’s own working_directory is blank — ~/.agentmux/agents/<name-derived-slug>.

default_container_volumes 🔒

default_conversation_visibility

AgentDefinition::conversation_visibility’s serde default — the safe, fail-closed value for any row/context that doesn’t specify one (including every pre-existing row before this column existed).

derive_slug

Derive a filesystem-safe slug from a display name (agentmux_common::slug::definition_slug).

normalize_last_runtime

Validate and canonicalise a remembered runtime before it is stored: '' clears; otherwise a JSON object of non-empty strings under the known keys only (permissionMode, model, effort), each bounded. Anything else is rejected, so the column can only ever hold something the launch path knows how to read.