identity-config

Agent Identity And Config

AGENT.IDENTITY.CONFIG.001

Why:

• Agents are durable team members, not throwaway runtime processes. Their role, capabilities, runtime, skills, budget, and permissions define what work Rudder may safely route to them.

Product model:

• An agent belongs to one organization.
• Agent identity includes name, role, title, capabilities, status, runtime type/config, desired skills, budget, and permission/config state.
• The board's New Agent form derives the role from the organization's current agent list: the first agent is submitted with role ceo, and later agents are submitted with role general. This form does not expose a role picker; other explicit creation or hire callers still provide a server-validated role.
• Agent avatar identity uses the existing agents.icon field. Supported persisted generated references are deterministic Oreo oreo:<shape>:<palette>:<uuid> values and DiceBear Notionists values; uploaded asset:<uuid> references remain supported.
• New direct-created and hired agents default to a server-generated Oreo reference when icon is omitted or a legacy named icon is supplied. The persisted UUID is Oreo's stable variant identity across refreshes, restarts, and every shared avatar rendering surface.
• Existing agents are not migrated. Persisted Oreo, DiceBear, uploaded-image, legacy named-icon, and missing-icon display behavior remains intact.
• Agent Detail exposes a compact Oreo/DiceBear avatar picker. Oreo provides its six shapes, 40 palettes, and style-scoped Random; DiceBear retains Notionists Random and six background presets; image upload is shared across both tabs.
• Pending approval, paused, terminated, or revoked-access states constrain whether the agent can be woken or configured.
• A board-originated hire is direct even when the organization enables requireBoardApprovalForNewAgents, because the initiating board actor already holds the approval authority. An agent-originated hire under that policy is created as pending_approval with one governed approval request.
• Config changes are operator-visible product changes when they alter runtime, instruction, skill, budget, or permission behavior.
• External local runtime configuration is a connection identity, not a provider credential dump. It stores the runtime type, normalized transport/endpoint, local ownership mode, and a Rudder secret reference; plaintext OpenClaw device keys, Hermes bearer keys, and provider session IDs do not belong in general Agent config JSON.
• For provider authentication, local-adapter onboarding collects the runtime choice and model name, along with any runtime-owned execution options exposed by that adapter. It does not collect provider API keys or create provider secret bindings as part of the basic Agent config flow. Provider authentication remains configuration owned by the selected agent runtime; Rudder may show runtime-owned setup guidance and probe the environment, while generic environment or secret-reference controls remain an advanced runtime configuration surface.
• V1 local ownership modes are rudder_managed_local and attach_existing_local. Managed mode owns only the recorded process identity and start epoch and binds it to the resolved workspace. Each process identity and start epoch has exactly one lifecycle owner; a second Agent may share a reachable endpoint only in attach mode and cannot restart or stop the managed process. Attach mode records that Rudder does not own lifecycle and is eligible only for the workspace binding that the provider/process can prove.
• An external endpoint/credential tuple is a single-organization trust domain. A secret reference already bound to one organization cannot be attached to a different organization, and provider session mappings are scoped by organization, Agent, and workstream rather than stored as reusable Agent identity fields.