Add diagnostic helpers: checkConnection and validateTools

[bokelley]

Summary

Add helper methods to the ADCP client for connection checking and tool validation. These would be useful for any ADCP consumer to validate agent health and compliance.

Motivation

Consumers of the ADCP client need to validate that agents are reachable and implement the expected tools. Currently this requires manual implementation. Adding these helpers to the client library makes diagnostics consistent and reusable.

Proposed API

// New types
type ADCPAgentType = 'SALES' | 'SIGNAL' | 'OUTCOME'

interface ConnectionStatus {
  reachable: boolean
  latencyMs: number
  error?: string
}

interface ToolValidationResult {
  status: 'pass' | 'fail' | 'warning'
  availableTools: string[]
  required: Array<{ name: string; present: boolean }>
  recommended: Array<{ name: string; present: boolean }>
  extra: string[]  // Tools not in required or recommended lists
}

// New methods on SingleAgentClient
class SingleAgentClient {
  /**
   * Check if the agent endpoint is reachable
   * Returns connection status with latency measurement
   */
  async checkConnection(): Promise<ConnectionStatus>

  /**
   * Validate that the agent has the expected tools for its type
   * @param agentType - The type of agent (determines required/recommended tools)
   */
  async validateTools(agentType: ADCPAgentType): Promise<ToolValidationResult>
}

Tool Requirements by Agent Type

The client should define the required and recommended tools per agent type:

SALES

Required: get_products, create_media_buy, update_media_buy, sync_creatives
Recommended: list_authorized_properties, list_creative_formats, list_creatives, get_media_buy_delivery

SIGNAL

Required: get_signals, activate_signal
Recommended: (none currently)

OUTCOME

Required: accept_proposal, get_outcome_status
Recommended: (none currently)

Implementation Notes

1. checkConnection() should:

   • Call getAgentInfo() with a short timeout
   • Measure and return latency
   • Catch and return errors gracefully (don't throw)

2. validateTools(agentType) should:

   • Call getAgentInfo() to discover available tools
   • Look up required/recommended tools for the given agentType
   • Compare against available tools
   • Return structured result with pass/fail/warning status

3. Consider also normalizing response extraction (the client currently returns varying response shapes that consumers have to handle - e.g., data.response.products vs data.products)

Benefits

• Provides standard diagnostics for all ADCP consumers
• Centralizes agent type → tool requirements mapping in the protocol library
• Client can evolve tool requirements as ADCP spec changes
• Reduces boilerplate in consuming applications