Skip to content

Add first-class display-name authoring without changing agent identity #108

Description

@myobie

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:catalogCatalog structure, declarations, transactions, and admission · Set: manualarea:identityAgent, session, run, and launch-generation identity · Set: manualtype:featureNew user-visible or system capability · Set: manual

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions