feat: SETUP_AGENT - unified agent setup with create and connect modes

[pcarranzav]

Summary

Consolidate agent setup into a single flow. Instead of separate requestAgentCreation() and requestConnectAgentKey() methods, requestAgentCreation() now accepts optional fields to control the mode:

• No extra flags → create new agent (default for new users)
• agent_address → connect key to specific existing agent
• connect_to_existing → connect mode, user picks agent in dashboard

Changes

• CreateAgentApprovalRequest: added optional agent_address, connect_to_existing, key_name fields
• Removed ConnectAgentKeyApprovalRequest and requestConnectAgentKey()
• requestAgentCreation() passes through agent_address, connect_to_existing, key_name when present
• CLI setup start: new --agent <address>, --connect-to-existing, --key-name <name> flags
• CLI outputs verificationCode (6-digit keccak256-derived) for MITM prevention
• SKILL.md updated with all three setup modes and verification code instructions

CLI usage

# Create new agent (default)
ampersend setup start --name "my-agent"

# Connect to specific existing agent
ampersend setup start --agent 0xAgentAddress --key-name "my-key"

# Connect mode, user picks agent in dashboard
ampersend setup start --connect-to-existing

Test plan

• All 168 tests pass
• TypeScript type-check and build pass
• Prettier/ESLint pass
• E2E: create new agent via setup start --name
• E2E: connect to existing via setup start --agent 0x...
• E2E: connect mode via setup start --connect-to-existing
• Verification codes match between CLI and dashboard

🤖 Generated with Claude Code

[matiasedgeandnode]

I would suggest you consider the following:

TL;DR: Replace --connect-to-existing with --mode <create|connect> (default: create). Add cross-flag validation. Add tests for the new flags.

Why: The three new flags (--agent, --connect-to-existing, --key-name) have no mutual exclusion validation, so contradictory combinations like --agent 0x... --connect-to-existing or --name "foo" --connect-to-existing silently pass through. A --mode flag makes intent explicit and validation trivial.

Design:

• --mode create (default): current behavior. --agent is invalid.
• --mode connect: connects a key to an existing agent. --agent is optional (omit = user picks in dashboard). --name and spend config flags (--daily-limit, etc.) are invalid since the agent already exists.
• --key-name is valid in both modes.
• --connect-to-existing flag goes away entirely — it's just --mode connect without --agent.

Validation to add (in executeSetupStart, before the API call):

• --mode connect + --name → error
• --mode connect + any spend config flag → error
• --mode create + --agent → error

Other:

• Group related flags in CreateAgentApprovalRequest by mode.
• Add tests for: connect mode with/without --agent, invalid address, --key-name passthrough, and the three validation errors above. The existing test infra (mockRequestAgentCreation,
  ExitError pattern) makes this straightforward.
• Update SKILL.md examples to use --mode connect instead of --connect-to-existing.

[matiasedgeandnode]

lgtm - nits:

1. requestAgentCreation naming — method + JSDoc still say "create" but now handles connect flows too. Consider requestAgentApproval.
2. Missing test: invalid --agent address — the INVALID_ADDRESS error path (setup.ts:66-69) has no test coverage.
3. Missing test: --auto-topup alone in connect mode — existing test triggers rejection via dailyLimit with autoTopup: false. No test that autoTopup: true alone is rejected.
4. key_name uses Schema.optional(NullOr(String)) but null is never sent — CLI does options.keyName ?? undefined. Could simplify to Schema.optional(String) to match agent_address / mode pattern.
5. Payload building in approval.ts — four sequential if (x !== undefined) blocks. Works, but fragile as fields grow.