@adcp/client 4.21.0 → 4.22.0

package/AGENTS.md

@@ -0,0 +1,278 @@
+# AI Coding Assistant Instructions for AdCP Client
+
+This document contains essential guidelines for AI coding assistants (Claude, Copilot, etc.) working on the AdCP Client project.
+
+## Start Here
+
+**Protocol overview** — Read `docs/llms.txt` for a single-file summary of AdCP: all 46 tools, key types, error codes, common flows, and test scenarios. Also available at https://adcontextprotocol.github.io/adcp-client/llms.txt
+
+**Type reference** — Read `docs/TYPE-SUMMARY.md` for curated type signatures (AgentConfig, TaskResult, ConversationContext, and all tool request/response shapes).
+
+**Do NOT read these files** — they are large generated files that waste context:
+- `src/lib/types/tools.generated.ts` (~13,000 lines) — use TYPE-SUMMARY.md instead
+- `src/lib/types/core.generated.ts` (~2,000 lines) — use TYPE-SUMMARY.md instead
+- `src/lib/types/schemas.generated.ts` (~8,000 lines) — Zod runtime schemas, rarely needed directly
+- `src/lib/agents/index.generated.ts` — generated Agent classes, use the client API instead
+
+**Building a server-side agent?** — Read `docs/guides/BUILD-AN-AGENT.md` and the `storyboards/` directory for expected tool call sequences.
+
+## Project Overview
+
+**@adcp/client** is the official TypeScript client library for the Ad Context Protocol (AdCP), documented at [docs.adcontextprotocol.org](https://docs.adcontextprotocol.org/docs/).
+
+**Components:**
+
+1. **Library** (`src/lib/`) - NPM package for AdCP agent communication
+2. **CLI** (`bin/`) - Command-line tooling for testing agents
+
+## 🚨 CRITICAL REQUIREMENTS - MUST FOLLOW 🚨
+
+### 1. ALWAYS USE OFFICIAL PROTOCOL CLIENTS
+
+- **A2A Protocol**: ALWAYS use the official `@a2a-js/sdk` client
+- **MCP Protocol**: ALWAYS use the official `@modelcontextprotocol/sdk` client
+- **NEVER** implement custom HTTP fallbacks or protocol implementations
+- **NEVER** parse SSE responses manually
+- **NEVER** make direct fetch() calls to agent endpoints
+- If an official client fails to import, FIX THE IMPORT - don't create workarounds
+
+### 2. NEVER USE MOCK DATA
+
+- **NEVER** inject mock products, formats, or any other fake data
+- **NEVER** provide fallback data when agents return empty responses
+- **ALWAYS** return exactly what the agents provide
+- If an agent returns empty arrays or errors, show that to the user
+- Real data only - no exceptions
+
+### 3. MCP CLIENT AUTHENTICATION - CRITICAL
+
+The MCP SDK automatically handles initialization. Authentication must be provided via headers:
+
+```javascript
+const transport = new StreamableHTTPClientTransport(url, {
+  requestInit: {
+    headers: {
+      'x-adcp-auth': authToken,
+    },
+  },
+});
+await client.connect(transport); // This automatically calls initialize internally
+```
+
+## Critical Architecture Patterns
+
+### Protocol Abstraction Layer
+
+The library supports both **A2A** and **MCP** protocols via unified interface:
+
+```typescript
+import { ProtocolClient } from './src/lib/protocols';
+// Routes to: callA2ATool() or callMCPTool() based on agent.protocol
+```
+
+**🚨 CRITICAL: A2A Protocol Implementation Requirements**
+
+The A2A protocol has specific implementation requirements that differ from MCP:
+
+**1. Artifact Field Names**
+
+A2A artifacts use `artifactId` per @a2a-js/sdk Artifact interface, NOT `name`:
+
+```typescript
+// Correct (per @a2a-js/sdk)
+if (!artifact.artifactId) {
+  warnings.push('A2A artifact missing artifactId field');
+}
+
+// Incorrect - 'name' doesn't exist in A2A SDK
+if (!artifact.name) { ... }
+```
+
+**2. Two Types of Webhooks - Do Not Confuse!**
+
+**1. `push_notification_config` - For Async Task Status Updates**
+
+Used for receiving task completion/progress notifications. Placement differs by protocol:
+
+- **A2A Protocol**: Goes in `params.configuration.pushNotificationConfig` (camelCase)
+
+  ```typescript
+  await a2aClient.sendMessage({
+    message: { /* task content */ },
+    configuration: {
+      pushNotificationConfig: {  // ← For async task status
+        url: webhookUrl,
+        token?: clientToken,
+        authentication: { schemes: ['HMAC-SHA256'], credentials: secret }
+      }
+    }
+  });
+  ```
+
+- **MCP Protocol**: Goes in tool arguments as `push_notification_config` (snake_case)
+  ```typescript
+  await mcpClient.callTool('create_media_buy', {
+    buyer_ref: '...',
+    packages: [...],
+    push_notification_config: {  // ← For async task status
+      url: webhookUrl,
+      token?: clientToken,
+      authentication: { schemes: ['HMAC-SHA256'], credentials: secret }
+    }
+  });
+  ```
+
+**2. `reporting_webhook` - For Reporting Data Delivery**
+
+Used for receiving periodic performance metrics. **Always stays in skill parameters** (both A2A and MCP):
+
+```typescript
+// Both protocols - reporting_webhook in skill parameters
+{
+  buyer_ref: '...',
+  packages: [...],
+  reporting_webhook: {  // ← Stays in parameters for BOTH protocols
+    url: reportingUrl,
+    token?: clientToken,
+    authentication: { schemes: ['HMAC-SHA256'], credentials: secret },
+    reporting_frequency: 'daily',  // Additional fields specific to reporting
+    requested_metrics: ['impressions', 'spend', 'clicks']
+  }
+}
+```
+
+Schema: https://adcontextprotocol.org/schemas/v1/core/push-notification-config.json
+
+The `ProtocolClient.callTool()` method in `src/lib/protocols/index.ts` handles this routing automatically.
+
+### Async Operation Patterns (AdCP PR 78)
+
+All operations follow 5 status patterns based on agent response:
+
+- `completed` - Sync completion with result
+- `working` - Long-running, poll with `tasks/get`
+- `submitted` - Webhook delivery required
+- `input_required` - Agent needs clarification via input handlers
+- `deferred` - Client defers decision to human/external system
+
+```typescript
+// Core flow in src/lib/core/TaskExecutor.ts
+const result = await executor.executeTask(agent, 'get_products', params, inputHandler);
+// Status determines next steps: polling, webhook wait, or input handling
+```
+
+### Conversation-Aware Input Handling
+
+Agents may need clarifications during execution. Use input handlers:
+
+```typescript
+const client = new AdCPClient(agent, {
+  handlers: {
+    onGetProductsStatusChange: (response, metadata) => {
+      // Fires for ALL status changes: sync completion, webhook delivery, etc.
+    },
+  },
+});
+
+// Input handler pattern for clarifications
+const handler = async context => {
+  return context.inputRequest.field === 'budget' ? 50000 : context.deferToHuman();
+};
+```
+
+## Build & Release Process
+
+### Changesets-Based Releases
+
+**🚨 NEVER manually edit `package.json` version** - Use changesets:
+
+```bash
+npm run changeset          # Create changeset for changes
+# Merge PR to main → Auto Release PR created
+# Merge Release PR → Auto publish to npm
+```
+
+**The correct separation:**
+
+- `package.json` version = **Library version** (managed by changesets)
+- `src/lib/version.ts` ADCP_VERSION = **AdCP schema version** (can differ from library version)
+
+### Schema Generation Workflow
+
+Library types auto-generated from AdCP schemas:
+
+```bash
+npm run sync-schemas       # Download from protocol repo
+npm run generate-types     # Generate TypeScript types
+npm run generate-zod-schemas  # Generate runtime validation
+```
+
+## Testing Strategies
+
+### Protocol-Level Mocking
+
+Test TaskExecutor patterns by mocking `ProtocolClient.callTool()`:
+
+```javascript
+ProtocolClient.callTool = mock.fn(async (agent, taskName, params) => {
+  if (taskName === 'tasks/get') return { task: { status: 'working' } };
+  return { status: 'submitted' };
+});
+```
+
+### Test Commands
+
+```bash
+npm test                   # Unit tests
+npm run test:protocols     # Protocol compliance tests
+npm run test:e2e          # End-to-end against live server
+npm run test:all          # Full test suite
+```
+
+## File Organization
+
+- `docs/llms.txt` - **Start here**: protocol overview, all tools, types, flows (generated)
+- `docs/TYPE-SUMMARY.md` - Curated type reference (generated)
+- `src/lib/core/` - Main client classes (AdCPClient, TaskExecutor)
+- `src/lib/protocols/` - A2A/MCP protocol implementations
+- `src/lib/types/` - Generated TypeScript types from schemas (prefer TYPE-SUMMARY.md)
+- `storyboards/` - YAML definitions of tool call sequences for each agent type
+- `test/lib/` - Library unit tests
+- `test/e2e/` - Integration tests
+- `examples/` - Usage examples and demos
+
+## Backwards Compatibility
+
+**This is a published npm library. Callers on older versions must not break when we add new required fields.**
+
+When adding a new required field to a request schema:
+
+1. **Infer it from existing fields** in `SingleAgentClient.normalizeRequestParams()` so callers that don't send it still work
+2. **Update all internal callers** (testing scenarios) to send the field explicitly
+3. **Add tests** verifying the inference works and that explicit values are preserved
+
+Example: `buying_mode` was added as required on `get_products`. The client infers it from `brief` presence — callers that only sent `{ brief: '...' }` keep working.
+
+The pattern:
+
+- `normalizeRequestParams()` runs before validation, filling in derivable fields
+- `validateRequest()` runs Zod schemas after normalization
+- `adaptRequestForServerVersion()` handles v3→v2 downgrades for older servers
+
+**Never add a required field without a backwards-compatible default or inference path.**
+
+## Common Gotchas
+
+1. **Protocol clients**: Always use official `@a2a-js/sdk` and `@modelcontextprotocol/sdk`
+2. **Mock data**: Never inject fallback data when agents return empty responses
+3. **Version management**: Let changesets handle package.json, edit ADCP_VERSION separately
+4. **Backwards compatibility**: New required schema fields need inference in `normalizeRequestParams()`
+
+## References
+
+- [Protocol overview (llms.txt)](https://adcontextprotocol.github.io/adcp-client/llms.txt)
+- [API Documentation](https://adcontextprotocol.github.io/adcp-client/api/index.html)
+- [AdCP Specification](https://adcontextprotocol.org)
+- [A2A SDK](https://github.com/a2a/a2a-js-sdk)
+- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)
+- [Changesets Documentation](https://github.com/changesets/changesets)

package/README.md

@@ -9,9 +9,16 @@
 
 Official TypeScript/JavaScript client for the **Ad Context Protocol (AdCP)**. Build distributed advertising operations that work synchronously OR asynchronously with the same code.
 
+## For AI Agents
+
+Start with [`docs/llms.txt`](./docs/llms.txt) — the full protocol spec in one file (tools, types, error codes, examples). Building a server? See [`docs/guides/BUILD-AN-AGENT.md`](./docs/guides/BUILD-AN-AGENT.md). For type signatures, use [`docs/TYPE-SUMMARY.md`](./docs/TYPE-SUMMARY.md). Skip `src/lib/types/*.generated.ts` — they're machine-generated and will burn context.
+
+These docs are also available in `node_modules/@adcp/client/docs/` after install.
+
 ## The Core Concept
 
 AdCP operations are **distributed and asynchronous by default**. An agent might:
+
 - Complete your request **immediately** (synchronous)
 - Need time to process and **send results via webhook** (asynchronous)
 - Ask for **clarifications** before proceeding
@@ -31,44 +38,47 @@ npm install @adcp/client
 import { ADCPMultiAgentClient } from '@adcp/client';
 
 // Configure agents and handlers
-const client = new ADCPMultiAgentClient([
-  {
-    id: 'agent_x',
-    agent_uri: 'https://agent-x.com',
-    protocol: 'a2a'
-  },
+const client = new ADCPMultiAgentClient(
+  [
+    {
+      id: 'agent_x',
+      agent_uri: 'https://agent-x.com',
+      protocol: 'a2a',
+    },
+    {
+      id: 'agent_y',
+      agent_uri: 'https://agent-y.com/mcp/',
+      protocol: 'mcp',
+    },
+  ],
   {
-    id: 'agent_y',
-    agent_uri: 'https://agent-y.com/mcp/',
-    protocol: 'mcp'
-  }
-], {
-  // Webhook URL template (macros: {agent_id}, {task_type}, {operation_id})
-  webhookUrlTemplate: 'https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}',
-
-  // Activity callback - fires for ALL events (requests, responses, status changes, webhooks)
-  onActivity: (activity) => {
-    console.log(`[${activity.type}] ${activity.task_type} - ${activity.operation_id}`);
-    // Log to monitoring, update UI, etc.
-  },
-
-  // Status change handlers - called for ALL status changes (completed, failed, input-required, working, etc)
-  handlers: {
-    onGetProductsStatusChange: (response, metadata) => {
-      // Called for sync completion, async webhook, AND status changes
-      console.log(`[${metadata.status}] Got products for ${metadata.operation_id}`);
-
-      if (metadata.status === 'completed') {
-        db.saveProducts(metadata.operation_id, response.products);
-      } else if (metadata.status === 'failed') {
-        db.markFailed(metadata.operation_id, metadata.message);
-      } else if (metadata.status === 'input-required') {
-        // Handle clarification needed
-        console.log('Needs input:', metadata.message);
-      }
-    }
+    // Webhook URL template (macros: {agent_id}, {task_type}, {operation_id})
+    webhookUrlTemplate: 'https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}',
+
+    // Activity callback - fires for ALL events (requests, responses, status changes, webhooks)
+    onActivity: activity => {
+      console.log(`[${activity.type}] ${activity.task_type} - ${activity.operation_id}`);
+      // Log to monitoring, update UI, etc.
+    },
+
+    // Status change handlers - called for ALL status changes (completed, failed, input-required, working, etc)
+    handlers: {
+      onGetProductsStatusChange: (response, metadata) => {
+        // Called for sync completion, async webhook, AND status changes
+        console.log(`[${metadata.status}] Got products for ${metadata.operation_id}`);
+
+        if (metadata.status === 'completed') {
+          db.saveProducts(metadata.operation_id, response.products);
+        } else if (metadata.status === 'failed') {
+          db.markFailed(metadata.operation_id, metadata.message);
+        } else if (metadata.status === 'input-required') {
+          // Handle clarification needed
+          console.log('Needs input:', metadata.message);
+        }
+      },
+    },
   }
-});
+);
 
 // Execute operation - library handles operation IDs, webhook URLs, context management
 const agent = client.agent('agent_x');
@@ -132,7 +142,7 @@ const client = new ADCPMultiAgentClient(agents, {
   webhookUrlTemplate: 'https://myapp.com/api/v1/adcp/{agent_id}?operation={operation_id}',
 
   // OR namespace to avoid conflicts
-  webhookUrlTemplate: 'https://myapp.com/adcp-webhooks/{agent_id}/{task_type}/{operation_id}'
+  webhookUrlTemplate: 'https://myapp.com/adcp-webhooks/{agent_id}/{task_type}/{operation_id}',
 });
 ```
 
@@ -172,21 +182,22 @@ Get observability into everything happening:
 
 ```typescript
 const client = new ADCPMultiAgentClient(agents, {
-  onActivity: (activity) => {
+  onActivity: activity => {
     console.log({
-      type: activity.type,              // 'protocol_request', 'webhook_received', etc.
+      type: activity.type, // 'protocol_request', 'webhook_received', etc.
       operation_id: activity.operation_id,
       agent_id: activity.agent_id,
-      status: activity.status
+      status: activity.status,
     });
 
     // Stream to UI, save to database, send to monitoring
     eventStream.send(activity);
-  }
+  },
 });
 ```
 
 Activity types:
+
 - `protocol_request` - Request sent to agent
 - `protocol_response` - Response received from agent
 - `status_change` - Task status changed
@@ -200,7 +211,7 @@ Activity types:
 // When creating a media buy, agent registers for delivery notifications
 const result = await agent.createMediaBuy({
   campaign_id: 'camp_123',
-  budget: { amount: 10000, currency: 'USD' }
+  budget: { amount: 10000, currency: 'USD' },
   // Agent internally sets up recurring delivery_report notifications
 });
 
@@ -220,12 +231,13 @@ const client = new ADCPMultiAgentClient(agents, {
       if (metadata.notification_type === 'final') {
         db.markOperationComplete(metadata.operation_id);
       }
-    }
-  }
+    },
+  },
 });
 ```
 
 Notifications use the **same webhook URL pattern** as regular operations:
+
 ```
 POST https://myapp.com/webhook/media_buy_delivery/agent_x/delivery_report_agent_x_2025-10
 ```
@@ -257,7 +269,7 @@ handlers: {
     if (metadata.status === 'completed') {
       const buyId = (response as CreateMediaBuyResponse).media_buy_id; // Typed!
     }
-  }
+  };
 }
 ```
 
@@ -266,11 +278,7 @@ handlers: {
 Building a server that receives AdCP tool calls? Import request types for handler signatures and Zod schemas for validation:
 
 ```typescript
-import {
-  CreateMediaBuyRequest,
-  CreateMediaBuyResponse,
-  CreateMediaBuyRequestSchema,
-} from '@adcp/client';
+import { CreateMediaBuyRequest, CreateMediaBuyResponse, CreateMediaBuyRequestSchema } from '@adcp/client';
 
 function handleCreateMediaBuy(rawParams: unknown): CreateMediaBuyResponse {
   const request: CreateMediaBuyRequest = CreateMediaBuyRequestSchema.parse(rawParams);
@@ -309,7 +317,7 @@ results.forEach((result, i) => {
 
 ```typescript
 const client = new ADCPMultiAgentClient(agents, {
-  webhookSecret: process.env.WEBHOOK_SECRET
+  webhookSecret: process.env.WEBHOOK_SECRET,
 });
 
 // Signatures verified automatically on handleWebhook()
@@ -319,13 +327,15 @@ const client = new ADCPMultiAgentClient(agents, {
 ### Authentication
 
 ```typescript
-const agents = [{
-  id: 'agent_x',
-  name: 'Agent X',
-  agent_uri: 'https://agent-x.com',
-  protocol: 'a2a',
-  auth_token: process.env.AGENT_X_TOKEN // ✅ Secure - load from env
-}];
+const agents = [
+  {
+    id: 'agent_x',
+    name: 'Agent X',
+    agent_uri: 'https://agent-x.com',
+    protocol: 'a2a',
+    auth_token: process.env.AGENT_X_TOKEN, // ✅ Secure - load from env
+  },
+];
 ```
 
 ## Environment Configuration
@@ -356,6 +366,7 @@ const client = ADCPMultiAgentClient.fromEnv();
 All AdCP tools with full type safety:
 
 **Media Buy Lifecycle:**
+
 - `getProducts()` - Discover advertising products
 - `listCreativeFormats()` - Get supported creative formats
 - `createMediaBuy()` - Create new media buy
@@ -365,11 +376,13 @@ All AdCP tools with full type safety:
 - `getMediaBuyDelivery()` - Get delivery performance
 
 **Audience & Targeting:**
+
 - `getSignals()` - Get audience signals
 - `activateSignal()` - Activate audience signals
 - `providePerformanceFeedback()` - Send performance feedback
 
 **Protocol:**
+
 - `getAdcpCapabilities()` - Get agent capabilities (v3)
 
 ## Property Discovery (AdCP v2.2.0)
@@ -391,7 +404,7 @@ import { PropertyCrawler, getPropertyIndex } from '@adcp/client';
 const crawler = new PropertyCrawler();
 await crawler.crawlAgents([
   { agent_url: 'https://agent-x.com', protocol: 'a2a' },
-  { agent_url: 'https://agent-y.com/mcp/', protocol: 'mcp' }
+  { agent_url: 'https://agent-y.com/mcp/', protocol: 'mcp' },
 ]);
 
 const index = getPropertyIndex();
@@ -418,7 +431,7 @@ const crawler = new PropertyCrawler();
 // Crawl agents - gets publisher_domains from each, then fetches adagents.json
 const result = await crawler.crawlAgents([
   { agent_url: 'https://sales.cnn.com' },
-  { agent_url: 'https://sales.espn.com' }
+  { agent_url: 'https://sales.espn.com' },
 ]);
 
 console.log(`✅ ${result.successfulAgents} agents`);
@@ -441,6 +454,7 @@ Supports 18 identifier types: `domain`, `subdomain`, `ios_bundle`, `android_pack
 ### Use Case
 
 Build a registry service that:
+
 - Periodically crawls agents with `PropertyCrawler`
 - Persists discovered properties to a database
 - Exposes fast query APIs using the in-memory index patterns
@@ -600,6 +614,7 @@ npm start
 ```
 
 Features:
+
 - Configure multiple agents (test agents + your own)
 - Execute ONE operation across all agents
 - See live activity stream (protocol requests, webhooks, handlers)
@@ -609,11 +624,13 @@ Features:
 ## Examples
 
 ### Basic Operation
+
 ```typescript
 const result = await agent.getProducts({ brief: 'Coffee brands' });
 ```
 
 ### With Clarification Handler
+
 ```typescript
 const result = await agent.createMediaBuy(
   { buyer_ref: 'campaign-123', account_id: 'acct-456', packages: [...] },
@@ -628,6 +645,7 @@ const result = await agent.createMediaBuy(
 ```
 
 ### With Webhook for Long-Running Operations
+
 ```typescript
 const operationId = createOperationId();
 
@@ -636,7 +654,7 @@ const result = await agent.syncCreatives(
   null, // No clarification handler = webhook mode
   {
     contextId: operationId,
-    webhookUrl: agent.getWebhookUrl('sync_creatives', operationId)
+    webhookUrl: agent.getWebhookUrl('sync_creatives', operationId),
   }
 );
 
@@ -644,6 +662,23 @@ const result = await agent.syncCreatives(
 // Handler fires when webhook received
 ```
 
+## Building an Agent (Server)
+
+The examples above show client-side usage — calling existing agents. To build your own agent that serves AdCP tools:
+
+```typescript
+import { createTaskCapableServer, taskToolResponse, GetSignalsRequestSchema } from '@adcp/client';
+
+const server = createTaskCapableServer('My Signals Agent', '1.0.0');
+
+server.tool('get_signals', 'Discover audience segments.', GetSignalsRequestSchema.shape, async args => {
+  const signals = queryYourDatabase(args.signal_spec);
+  return taskToolResponse({ signals, sandbox: true }, `Found ${signals.length} segment(s)`);
+});
+```
+
+See the [Build an Agent guide](docs/guides/BUILD-AN-AGENT.md) for the full walkthrough, and [`examples/signals-agent.ts`](examples/signals-agent.ts) for a complete runnable example.
+
 ## Contributing
 
 Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.