feat: [PRO-474] implement invoke command with API, webhook, and local options

[dudutwizer]

Summary

This PR implements explicit invocation methods for the invoke command with API as the default, removing automatic fallbacks between methods.

Key Changes

1. API Invocation (New Default)

What: Uses /v1/agents/<agent-id>/invoke REST API endpoint
How: Sends {"input": {"text": "message"}} payload with API key and org ID headers
Why: More reliable and consistent than webhook, better for production use

2. Explicit Invocation Options

• --api: API invocation (default - no flag needed)
• --webhook: Webhook invocation (explicit flag required)
• --local: Local handler invocation (explicit flag required)

3. Removed Fallback Logic

Before: Local → Webhook fallback chain
After: Each method is independent, fails immediately if unavailable
Why: Makes behavior predictable and errors clear

4. Top-Level Command Alias

Added: xpander invoke as alias for xpander agent invoke
Why: Convenience and consistency with other top-level commands

Files Modified

• src/commands/agent/commands/invoke.ts - Updated invoke logic with three methods
• src/commands/invoke.ts - New top-level command registration
• src/index.ts - Registered invoke command

Examples

# API invocation (default)
xpander invoke "MyAgent" "Hello world"

# Webhook invocation (explicit)
xpander invoke --webhook "MyAgent" "Hello world"

# Local handler invocation (explicit)
xpander invoke --local "MyAgent" "Hello world"

# Also works with agent subcommand
xpander agent invoke "MyAgent" "Hello world"

Breaking Changes

⚠️ Default behavior changed:

• Old: Local handler with webhook fallback
• New: API invocation by default

Migration: Add --local flag if you need local handler behavior

Test plan

• Test API invocation works by default
• Test webhook invocation with --webhook flag
• Test local invocation with --local flag
• Test top-level xpander invoke command
• Verify no fallbacks occur between methods
• Test with various agent types

🤖 Generated with Claude Code

---

Note

Adds explicit API (default), webhook, and local invocation modes to agent invoke, enhances message/agent resolution (including .env), and introduces a top‑level xpander invoke alias.

• CLI – agent invoke
  • Invocation modes: Add explicit --api (default), --webhook, and --local paths; remove automatic fallbacks.
  • API path: Calls POST /v1/agents/{agentId}/invoke with {"input": {"text": message}}, using x-api-key and x-organization-id headers.
  • Input parsing: Add --message; support .env agent auto-detection; maintain legacy --agent/--agent-id/--agent-name; improved interactive prompts.
  • UX: Updated help examples; show selected agent; spinners and response-time display; better JSON output extraction for local runs.
  • Errors: Clear failures per mode; enhanced handling for billing (429), 401/404, and timeouts.
• Top-level alias
  • Add xpander invoke via configureInvokeCommand and register it in src/index.ts.

^{Written by Cursor Bugbot for commit 54f7cd6. This will update automatically on new commits. Configure here.}

[notion-workspace]

CLI Local test , change to API

[cursor]

Bug: Silent fallback to .env agent when explicit agent fails

When a user explicitly provides an agent name that doesn't exist, getAgentIdFromEnvOrSelection silently falls back to using the agent_id from the .env file. This contradicts the PR's stated goal of removing fallback logic and making errors clear. A user who types xpander invoke "WrongAgentName" "message" might unknowingly invoke a completely different agent from their .env file. The invoke command's error handling at lines 101-108 never triggers because the function returns the env agent ID instead of null.