Agentd CLI: unify run + persistent agent command domains

t-754·WorkTask·
·
·
Created1 week ago·Updated1 week ago·pipeline runs →

Dependencies

Description

Edit

Current agentd CLI has two overlapping control domains: 1) run-based container workflows (top-level commands: run/status/logs/stop/kill/list-runs/watch/replay/debug) 2) persistent systemd-managed agents (agent subcommands: create/list/status/start/stop/restart/send/logs/rm/purge)

This causes discoverability and ambiguity problems (e.g. agentd status <name> fails for existing persistent agents while agentd agent status <name> succeeds).

Do a design pass that maps overlapping capabilities and proposes a unified, noun-first CLI surface with compatibility aliases. Include migration plan for scripts currently calling top-level run lifecycle commands.

Timeline (13)

🔄[human]Open → InProgress1 week ago
💬[human]1 week ago

Analysis snapshot:

Accurate model: we currently have two different resources hidden behind one CLI.

  • Run domain (ephemeral container runs): top-level run/status/logs/stop/kill/steer/list-runs/watch/replay/debug
  • Persistent agent domain (systemd + DB): agent create/list/status/start/stop/restart/send/logs/rm/purge

Observed overlap:

  • shared lifecycle verbs: list, status, logs, stop, send/steer
  • run-only verbs: kill, watch, replay, debug, validate/images/top
  • agent-only verbs: create config, restart, rm/purge

Concrete ambiguity:

  • agentd status paracoder --json => Run not found: paracoder
  • agentd agent status paracoder works (persistent agent exists)

Unification proposal:

  • make both domains noun-first:
  • agentd runs <verb>
  • agentd agents <verb> (keep agent alias)
  • normalize shared verbs/options (status [id] [--json], logs id [--follow], stop id, send id msg, list)
  • keep top-level legacy aliases (status/logs/stop/list-runs/steer) forwarding to runs ... with deprecation hints.

Migration risk note:

  • repo usage count is still skewed toward legacy run commands (agentd run: 29 refs, agentd status: 9 refs, agentd agent: 1 ref), so aliases are required.
💬[human]1 week ago

User direction: treat runs as one-shot agents and agents as persistent runs that wait for feedback. Design should unify around one execution model with durability/interaction policy, rather than two separate command domains.

💬[human]1 week ago

Implemented first-pass unified top-level session CLI in Omni/Agentd.hs:

  • Added top-level start command with --mode oneshot|persistent.
  • oneshot mode reuses existing run workflow behavior.
  • persistent mode starts existing named agent or creates+starts when missing (requires --name --provider --model --cwd).
  • Unified top-level lifecycle verbs across both domains:
  • status ID [--json] [--mode auto|oneshot|persistent]
  • logs ID [--follow] [--mode ...]
  • send ID MESSAGE [--mode ...]
  • stop ID [--mode ...]
  • rm ID [--mode ...]
  • purge ID [--mode ...]
  • Added target auto-resolution (--mode auto) by ID against persistent DB + oneshot event logs.
  • Kept compatibility aliases:
  • run (legacy alias for oneshot start)
  • steer (legacy oneshot send alias)
  • agent/agents subcommand tree retained as legacy path.
  • Replay/debug behavior clarified for persistent IDs:
  • now fail fast with explicit message that replay/debug traces are oneshot-only for now.

Validation:

  • lint Omni/Agentd.hs
  • typecheck.sh Omni/Agentd.hs
  • bild Omni/Agentd.hs
  • Smoke tests with built binary:
  • persistent flow: start/status/send/stop/rm/purge
  • oneshot flow: start/status/send/rm
  • status paracoder --json now resolves correctly to persistent mode.
🔄[human]InProgress → Review1 week ago
💬[human]1 week ago

Committed in acf1cdd: unified top-level start/status/logs/send/stop/rm/purge with mode auto/oneshot/persistent and compatibility aliases.

💬[human]1 week ago

Ava verified: cited commit confirmed in live history; feature shipped. Moving to Verified.

🔄[human]Review → Verified1 week ago