emcli/docs/superpowers/specs/2026-06-23-agent-account-list-design.md

Agent-readable account list — design

Date: 2026-06-23 Status: Approved (brainstorm), ready for implementation plan Author: Steve + Claude

Problem

An agent process is launched with only EMCLI_KEY (the two-key model — see 2026-06-22-two-key-privilege-design.md). Every agent command takes --account NAME, but the agent has no way to discover which accounts exist: account list is classified admin-only and is refused under the agent key. So account names must be supplied to the agent out of band, which is brittle and defeats the point of a self-directed agent.

The two-key spec deliberately gated the whole account command to admin because account add/edit/remove mutate configuration. But account list is read-only and exposes no secrets — store.ListAccounts never decrypts the password (enc_password is scanned and discarded). Gating discovery behind admin is stricter than the threat model requires.

Goal

Let an agent holding only EMCLI_KEY run account list to discover the accounts it may operate on, while:

• keeping account add/edit/remove admin-only (mutation stays gated);
• exposing to the agent only what it needs — account name, the send-as From address, and whether the account can send — and not the IMAP host/port or login username;
• preserving the admin's existing full-detail view unchanged.

Constraints / decisions

Settled during brainstorming:

1. Scope is exactly account list. whitelist list, config get, and audit list stay admin-only. audit in particular is oversight data and must remain invisible to the agent.
2. Privilege-dependent rendering. The admin keeps the current full table (NAME MODE IMAP USER, human-readable). The agent gets a reduced view containing only name, From, and send-capability.
3. Agent output is JSON. The agent is a machine consumer, so its account list emits the standard agent envelope (like list/get/search), not a text table. The admin path stays human-readable text.
4. No secret exposure, no schema change. ListAccounts already avoids decrypting passwords; nothing about the data model changes.

Approach

Reclassify account list to the agent role, and branch rendering on the caller's actual privilege (presence of the admin key).

Routing (internal/cli/run.go)

commandRole becomes subcommand-aware for account:

• account list → RoleAgent
• account add | edit | remove (and bare account) → RoleAdmin
• all other commands unchanged.

commandRole currently takes cmd string; it changes to take the full args []string so it can peek at the account subcommand. Run passes args through. This keeps commandRole the single source of truth for the classification table.

Authorization mechanics are unchanged: openStore(RoleAgent) requires EMCLI_KEY (falling back to the admin key for a human who holds only that and runs account list). account add/edit/remove still hard-require EMCLI_ADMIN_KEY with no fallback.

Rendering (internal/cli/admin.go, the list branch)

Determine privilege from the environment: _, err := crypto.AdminKeyFromEnv(); isAdmin := err == nil. (Holding the admin key is being the admin in this trust model. A human with only the admin key still gets the admin view; an agent with only EMCLI_KEY gets the reduced view.)

• Admin → existing full table, unchanged:

  NAME             MODE IMAP                         USER
  work             RW   imap.example.com:993         me@example.com
  

• Agent → JSON envelope to stdout:

  {"error":false,"error_detail":{},"data":{"accounts":[
    {"name":"work","from":"me@example.com","can_send":true},
    {"name":"alerts","from":"alerts@example.com","can_send":false}
  ]}}
  

  where from = Account.SendFrom() (the configured From address, falling back to the username) and can_send = (Mode == "RW") (RW accounts have SMTP configured; RO cannot send). The IMAP host/port and the raw login username are not emitted (when From falls back to the username it may coincide with it, which is acceptable — the user asked for From specifically).

The reduced view reuses the existing Success(...) envelope and Envelope.Write helper; no new output machinery.

Error handling

• Agent key on account add/edit/remove → unchanged: emcli: this command requires EMCLI_ADMIN_KEY (admin privilege), non-zero.
• Agent account list with neither key set → the agent-command config error (EMCLI_KEY is not set), surfaced the same way other agent commands surface a missing key. Because the agent path now emits JSON, a missing-key failure on account list is a JSON Failure(CodeConfig, …) envelope, consistent with the other agent commands.
• DB/list errors on the agent path → Failure(CodeDB, …) envelope; on the admin path → existing list: <err> text to stderr.

Testing

• Routing: extend the commandRole table test — account list → agent; account add / account edit / account remove → admin.
• Agent view: with only EMCLI_KEY, account list exits 0, emits a valid envelope, and the data.accounts entries carry name/from/can_send — and the output does not contain the IMAP host or the login username.
• Admin view: with EMCLI_ADMIN_KEY, account list still prints the full NAME MODE IMAP USER table (regression guard).
• can_send: an RW account yields can_send:true, an RO account can_send:false; from reflects SendFrom() (explicit From, else username).
• Security invariant (security_invariant_test.go): remove {"account","list"} from the refused-commands set (it is now allowed) and replace it with a mutating account add … attempt, so the "forced agent cannot run admin commands and the DB is byte-for-byte unchanged" invariant still covers the account family.

Documentation updates

• USER-MANUAL: role/command table — account list is agent-readable (reduced JSON view); account add/edit/remove remain admin.
• skills/emcli (SKILL.md / AGENTIC-MANUAL.md): document that the agent discovers accounts via account list, including the JSON shape (name, from, can_send).

Out of scope

• Agent access to whitelist list, config get, or audit list.
• Any change to the admin account list columns or to the data model.
• JSON output for the admin account list path (stays human-readable text).