Problem
Current main (c6846f6) already has the correct runtime primitive: st2 agents reads the first non-empty line of <agent-dir>/name on every invocation and exposes it as name in human and JSON output. Editing that file is therefore display-only and takes effect without touching the declaration, stable identity, inbox routing, task ID, or live process.
The missing piece is a supported authoring surface. Today an operator has to know the private catalog layout and edit or remove name by hand; no CLI verb writes or clears it.
Required contract
- Add an explicit command that sets or clears the optional display name for one exact catalog agent.
- Resolve the target by the Agent Spec's explicit host and identity, independent of folder spelling, and fail closed on missing or ambiguous targets.
- Atomically write only
<agent-dir>/name, or remove only that file when clearing. Preserve agent.kdl, status, resources, inbox, archive, context, and links.
- A successful change is visible on the next
st2 agents read. It does not reconcile, restart, rename a PTY, mutate a task fingerprint, or notify the live agent.
- The bus identity remains the only routing, addressing, state-anchor, and lifecycle identity. A display name is never an alias and need not be unique.
- Define stable validation for empty input, control characters, line breaks, and a bounded length; emit machine-readable changed/unchanged/error output.
- Keep the operation complete with an ordinary local or synchronized catalog folder; no CAS service is required.
Acceptance
- Set, replace, clear, and idempotent-repeat cases are covered against a plain temporary catalog.
- Human and
--json roster output change while identity, task IDs, declaration bytes, and all durable resource bytes remain unchanged.
- A live synthetic agent is not restarted or signaled.
- Missing, retired, remote, and ambiguous target behavior is explicit and fail-closed.
Relationship to existing work
Problem
Current main (
c6846f6) already has the correct runtime primitive:st2 agentsreads the first non-empty line of<agent-dir>/nameon every invocation and exposes it asnamein human and JSON output. Editing that file is therefore display-only and takes effect without touching the declaration, stable identity, inbox routing, task ID, or live process.The missing piece is a supported authoring surface. Today an operator has to know the private catalog layout and edit or remove
nameby hand; no CLI verb writes or clears it.Required contract
<agent-dir>/name, or remove only that file when clearing. Preserveagent.kdl, status, resources, inbox, archive, context, and links.st2 agentsread. It does not reconcile, restart, rename a PTY, mutate a task fingerprint, or notify the live agent.Acceptance
--jsonroster output change while identity, task IDs, declaration bytes, and all durable resource bytes remain unchanged.Relationship to existing work