electric-ax agents CLI reports "No entity types found" for freshly-registered types (default Electric-Principal has no visibility)

[andresberrios]

Summary

After following the agents walkthrough and registering an entity type, electric-ax agents types prints No entity types found, even though the type is registered and visible in the dev UI. The same mismatch affects other agents read commands. The cause is that the CLI sends a default Electric-Principal that the server has no visibility grants for.

Steps to reproduce

1. Follow the agents walkthrough so an assistant (or any) entity type is registered against a local server at http://localhost:4437.
2. Confirm it registered — the dev UI at https://localhost:4438 lists it, and:

   curl -s http://localhost:4437/_electric/entity-types | jq '.[].name'
   # => "assistant", "principal"

3. Run the CLI:

   pnpx electric-ax@latest agents types
   # => No entity types found

Expected

Immediately after registering a type and following the walkthrough, agents types lists it.

Actual

No entity types found, which reads as "registration failed" and sends you debugging the wrong thing.

Root cause

GET /_electric/entity-types is scoped by the Electric-Principal request header:

• No header (plain curl) → returns everything (assistant, principal).
• Electric-Principal: system:dev-local (what the dev UI uses) → returns the registered types.
• Electric-Principal: user:<whoami>@<hostname> → returns [].

getElectricCliEnv defaults the principal to user:${ELECTRIC_AGENTS_IDENTITY} where the identity is ${os.userInfo().username}@${os.hostname()} (packages/electric-ax). That principal has no grants for the walkthrough-registered types, so the server correctly returns an empty list — and the CLI prints No entity types found.

Demonstration:

# empty (CLI default principal)
curl -s -H "Electric-Principal: user:$(whoami)@$(hostname)" \
  http://localhost:4437/_electric/entity-types | jq length            # => 0

# populated (dev UI principal)
curl -s -H "Electric-Principal: system:dev-local" \
  http://localhost:4437/_electric/entity-types | jq 'map(.name)'      # => ["assistant","principal"]

Workaround

ELECTRIC_AGENTS_PRINCIPAL=system:dev-local electric-ax agents types

Why this is confusing / suggested fixes

The inconsistency is that an unauthenticated request sees all types while the CLI's "authenticated" default sees none, and the walkthrough implies the plain agents types command lists what you just registered. Some options:

• Have the local dev flow default the CLI to the same principal the dev server/UI uses (system:dev-local), or grant the default user:<identity> principal visibility of types it can spawn.
• If empty-because-of-permissions is intended, distinguish it in the CLI output (e.g. No entity types visible to principal <p> with a hint about ELECTRIC_AGENTS_PRINCIPAL) instead of the flat No entity types found.
• At minimum, document the principal scoping in the walkthrough next to the agents types step.

Environment

• electric-ax CLI 0.2.23 (and @latest), agents server image 0.6.3, @electric-ax/agents-runtime 0.6.3.
• macOS, local Docker dev stack (electric-ax agents start).