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. db_agents is the authoritative consolidated read table; db_agent_definitions and db_agent_instances remain the write targets with dual-write mirrors.

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().

GitHubContext

Optional context describing which GitHub-side unit of work a specific instance is operating on. Stored as JSON in db_agent_instances.github_context (empty string when unset).

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.

Functions

default_agent_type 🔒

default_container_volumes 🔒

derive_slug

Derive a filesystem-safe slug from a display name. Lowercase, ASCII alphanumeric + dash/underscore, consecutive dashes collapsed, trimmed to 64 chars. Returns "agent" if the input has no valid characters (defensive fallback).

map_agent_definition_row 🔒

Row mapper for db_agents rows projected back into the AgentDefinition shape. The column order MUST match the SELECT in agent_def_list. parent_template_id maps to parent_id because the consolidated table renamed the field to clarify its semantics (template lineage), but the wire shape kept the old name.

map_instance_row 🔒