@adcp/sdk 5.23.0

package/dist/lib/core/ConfigurationManager.js

@@ -0,0 +1,249 @@
+"use strict";
+// Enhanced configuration manager for easy ADCP client setup
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigurationManager = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const errors_1 = require("../errors");
+/**
+ * Enhanced configuration manager with multiple loading strategies
+ */
+class ConfigurationManager {
+    static CONFIG_FILES = ['adcp.config.json', 'adcp.json', '.adcp.json', 'agents.json'];
+    static ENV_VARS = ['SALES_AGENTS_CONFIG', 'ADCP_AGENTS_CONFIG', 'ADCP_CONFIG'];
+    /**
+     * Load agent configurations using auto-discovery
+     * Tries multiple sources in order:
+     * 1. Environment variables
+     * 2. Config files in current directory
+     * 3. Config files in project root
+     */
+    static loadAgents() {
+        // Try environment variables first
+        const envAgents = this.loadAgentsFromEnv();
+        if (envAgents.length > 0) {
+            return envAgents;
+        }
+        // Try config files
+        const configAgents = this.loadAgentsFromConfig();
+        if (configAgents.length > 0) {
+            return configAgents;
+        }
+        // No configuration found
+        console.warn('⚠️  No ADCP agent configuration found');
+        console.log('💡 To configure agents, you can:');
+        console.log('   1. Set SALES_AGENTS_CONFIG environment variable');
+        console.log('   2. Create an adcp.config.json file');
+        console.log('   3. Pass agents directly to the constructor');
+        console.log('\n📖 See documentation for configuration examples');
+        return [];
+    }
+    /**
+     * Load agents from environment variables
+     */
+    static loadAgentsFromEnv() {
+        for (const envVar of this.ENV_VARS) {
+            const configEnv = process.env[envVar];
+            if (configEnv) {
+                try {
+                    const config = JSON.parse(configEnv);
+                    const agents = this.extractAgents(config);
+                    if (agents.length > 0) {
+                        console.log(`📡 Loaded ${agents.length} agents from ${envVar}`);
+                        this.logAgents(agents);
+                        return agents;
+                    }
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    console.error(`❌ Failed to parse ${envVar}:`, errorMessage);
+                    throw new errors_1.ConfigurationError(`Invalid JSON in ${envVar}: ${errorMessage}`, envVar);
+                }
+            }
+        }
+        return [];
+    }
+    /**
+     * Load agents from config file
+     */
+    static loadAgentsFromConfig(configPath) {
+        const filesToTry = configPath ? [configPath] : this.CONFIG_FILES;
+        for (const file of filesToTry) {
+            const fullPath = (0, path_1.resolve)(file);
+            if ((0, fs_1.existsSync)(fullPath)) {
+                try {
+                    const content = (0, fs_1.readFileSync)(fullPath, 'utf8');
+                    const config = JSON.parse(content);
+                    const agents = this.extractAgents(config);
+                    if (agents.length > 0) {
+                        console.log(`📁 Loaded ${agents.length} agents from ${file}`);
+                        this.logAgents(agents);
+                        return agents;
+                    }
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    console.error(`❌ Failed to load config from ${file}:`, errorMessage);
+                    throw new errors_1.ConfigurationError(`Invalid config file ${file}: ${errorMessage}`, 'configFile');
+                }
+            }
+        }
+        return [];
+    }
+    /**
+     * Extract agents array from various config formats
+     */
+    static extractAgents(config) {
+        // Handle different config formats
+        if (Array.isArray(config)) {
+            return config; // Direct agent array
+        }
+        if (config.agents && Array.isArray(config.agents)) {
+            return config.agents; // Standard format: { agents: [...] }
+        }
+        if (config.data?.agents && Array.isArray(config.data.agents)) {
+            return config.data.agents; // Nested format: { data: { agents: [...] } }
+        }
+        return [];
+    }
+    /**
+     * Log configured agents in a user-friendly way
+     */
+    static logAgents(agents) {
+        agents.forEach(agent => {
+            const protocolIcon = agent.protocol === 'mcp' ? '🔗' : '⚡';
+            const authIcon = agent.auth_token ? '🔐' : '🌐';
+            console.log(`  ${protocolIcon}${authIcon} ${agent.name} (${agent.protocol.toUpperCase()}) at ${agent.agent_uri}`);
+        });
+        const useRealAgents = process.env.USE_REAL_AGENTS === 'true';
+        console.log(`🔧 Real agents mode: ${useRealAgents ? 'ENABLED' : 'DISABLED'}`);
+    }
+    /**
+     * Validate agent configuration
+     */
+    static validateAgentConfig(agent) {
+        const required = ['id', 'name', 'agent_uri', 'protocol'];
+        for (const field of required) {
+            if (!agent[field]) {
+                throw new errors_1.ConfigurationError(`Agent configuration missing required field: ${field}`, field);
+            }
+        }
+        if (!['mcp', 'a2a'].includes(agent.protocol)) {
+            throw new errors_1.ConfigurationError(`Invalid protocol "${agent.protocol}". Must be "mcp" or "a2a"`, 'protocol');
+        }
+        // Basic URL validation
+        try {
+            new URL(agent.agent_uri);
+        }
+        catch {
+            throw new errors_1.ConfigurationError(`Invalid agent_uri "${agent.agent_uri}". Must be a valid URL`, 'agent_uri');
+        }
+    }
+    /**
+     * Validate multiple agent configurations
+     */
+    static validateAgentsConfig(agents) {
+        if (!Array.isArray(agents)) {
+            throw new errors_1.ConfigurationError('Agents configuration must be an array');
+        }
+        if (agents.length === 0) {
+            throw new errors_1.ConfigurationError('At least one agent must be configured');
+        }
+        // Check for duplicate IDs
+        const ids = agents.map(a => a.id);
+        const duplicates = ids.filter((id, index) => ids.indexOf(id) !== index);
+        if (duplicates.length > 0) {
+            throw new errors_1.ConfigurationError(`Duplicate agent IDs found: ${duplicates.join(', ')}`, 'duplicateIds');
+        }
+        // Validate each agent
+        agents.forEach(agent => this.validateAgentConfig(agent));
+    }
+    /**
+     * Create a sample configuration file
+     */
+    static createSampleConfig() {
+        return {
+            agents: [
+                {
+                    id: 'premium-network',
+                    name: 'Premium Ad Network',
+                    agent_uri: 'https://premium-ads.example.com/mcp/',
+                    protocol: 'mcp',
+                    auth_token: process.env.PREMIUM_AGENT_TOKEN,
+                },
+                {
+                    id: 'budget-network',
+                    name: 'Budget Ad Network',
+                    agent_uri: 'https://budget-ads.example.com/a2a/',
+                    protocol: 'a2a',
+                },
+            ],
+            defaults: {
+                protocol: 'mcp',
+                timeout: 30000,
+                maxClarifications: 3,
+                debug: false,
+            },
+        };
+    }
+    /**
+     * Get configuration file paths that would be checked
+     */
+    static getConfigPaths() {
+        return this.CONFIG_FILES.map(file => (0, path_1.resolve)(file));
+    }
+    /**
+     * Get environment variables that would be checked
+     */
+    static getEnvVars() {
+        return this.ENV_VARS;
+    }
+    /**
+     * Generate configuration help text
+     */
+    static getConfigurationHelp() {
+        return `
+🔧 ADCP Agent Configuration
+
+The ADCP client can load agents from multiple sources:
+
+1️⃣  Environment Variables:
+   Set any of: ${this.ENV_VARS.join(', ')}
+   
+   Example:
+   export SALES_AGENTS_CONFIG='{"agents":[{"id":"my-agent","name":"My Agent","agent_uri":"https://agent.example.com","protocol":"mcp"}]}'
+
+2️⃣  Configuration Files:
+   Create any of: ${this.CONFIG_FILES.join(', ')}
+   
+   Example adcp.config.json:
+   {
+     "agents": [
+       {
+         "id": "premium-agent",
+         "name": "Premium Ad Network",
+         "agent_uri": "https://premium.example.com",
+         "protocol": "mcp",
+         "auth_token": "your-token-here"
+       },
+       {
+         "id": "dev-agent",
+         "name": "Development Agent",
+         "agent_uri": "https://dev.example.com",
+         "protocol": "a2a"
+       }
+     ]
+   }
+
+3️⃣  Programmatic Configuration:
+   const client = new ADCPMultiAgentClient([
+     { id: 'agent', agent_uri: 'https://...', protocol: 'mcp',
+       auth_token: process.env.MY_TOKEN }
+   ]);
+
+📖 For more examples, see the documentation.
+`;
+    }
+}
+exports.ConfigurationManager = ConfigurationManager;
+//# sourceMappingURL=ConfigurationManager.js.map

package/dist/lib/core/ConfigurationManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigurationManager.js","sourceRoot":"","sources":["../../../src/lib/core/ConfigurationManager.ts"],"names":[],"mappings":";AAAA,4DAA4D;;;AAE5D,2BAA8C;AAC9C,+BAAqC;AAErC,sCAA+C;AAyB/C;;GAEG;AACH,MAAa,oBAAoB;IACvB,MAAM,CAAU,YAAY,GAAG,CAAC,kBAAkB,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,CAAC,CAAC;IAE9F,MAAM,CAAU,QAAQ,GAAG,CAAC,qBAAqB,EAAE,oBAAoB,EAAE,aAAa,CAAC,CAAC;IAEhG;;;;;;OAMG;IACH,MAAM,CAAC,UAAU;QACf,kCAAkC;QAClC,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3C,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,mBAAmB;QACnB,MAAM,YAAY,GAAG,IAAI,CAAC,oBAAoB,EAAE,CAAC;QACjD,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,OAAO,YAAY,CAAC;QACtB,CAAC;QAED,yBAAyB;QACzB,OAAO,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,oDAAoD,CAAC,CAAC;QAClE,OAAO,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;QACrD,OAAO,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;QAC7D,OAAO,CAAC,GAAG,CAAC,mDAAmD,CAAC,CAAC;QAEjE,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,iBAAiB;QACtB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,SAAS,EAAE,CAAC;gBACd,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;oBACrC,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;oBAE1C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACtB,OAAO,CAAC,GAAG,CAAC,aAAa,MAAM,CAAC,MAAM,gBAAgB,MAAM,EAAE,CAAC,CAAC;wBAChE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;wBACvB,OAAO,MAAM,CAAC;oBAChB,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBAC5E,OAAO,CAAC,KAAK,CAAC,qBAAqB,MAAM,GAAG,EAAE,YAAY,CAAC,CAAC;oBAC5D,MAAM,IAAI,2BAAkB,CAAC,mBAAmB,MAAM,KAAK,YAAY,EAAE,EAAE,MAAM,CAAC,CAAC;gBACrF,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,UAAmB;QAC7C,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC;QAEjE,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,MAAM,QAAQ,GAAG,IAAA,cAAO,EAAC,IAAI,CAAC,CAAC;YAE/B,IAAI,IAAA,eAAU,EAAC,QAAQ,CAAC,EAAE,CAAC;gBACzB,IAAI,CAAC;oBACH,MAAM,OAAO,GAAG,IAAA,iBAAY,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;oBAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;oBACnC,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;oBAE1C,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACtB,OAAO,CAAC,GAAG,CAAC,aAAa,MAAM,CAAC,MAAM,gBAAgB,IAAI,EAAE,CAAC,CAAC;wBAC9D,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;wBACvB,OAAO,MAAM,CAAC;oBAChB,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;oBAC5E,OAAO,CAAC,KAAK,CAAC,gCAAgC,IAAI,GAAG,EAAE,YAAY,CAAC,CAAC;oBACrE,MAAM,IAAI,2BAAkB,CAAC,uBAAuB,IAAI,KAAK,YAAY,EAAE,EAAE,YAAY,CAAC,CAAC;gBAC7F,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,aAAa,CAAC,MAAW;QACtC,kCAAkC;QAClC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,OAAO,MAAM,CAAC,CAAC,qBAAqB;QACtC,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,qCAAqC;QAC7D,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,6CAA6C;QAC1E,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,SAAS,CAAC,MAAqB;QAC5C,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE;YACrB,MAAM,YAAY,GAAG,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;YAC3D,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;YAChD,OAAO,CAAC,GAAG,CAAC,KAAK,YAAY,GAAG,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE,QAAQ,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QACpH,CAAC,CAAC,CAAC;QAEH,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,MAAM,CAAC;QAC7D,OAAO,CAAC,GAAG,CAAC,wBAAwB,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAkB;QAC3C,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;QAEzD,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,KAA0B,CAAC,EAAE,CAAC;gBACvC,MAAM,IAAI,2BAAkB,CAAC,+CAA+C,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;QAED,IAAI,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,2BAAkB,CAAC,qBAAqB,KAAK,CAAC,QAAQ,2BAA2B,EAAE,UAAU,CAAC,CAAC;QAC3G,CAAC;QAED,uBAAuB;QACvB,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,2BAAkB,CAAC,sBAAsB,KAAK,CAAC,SAAS,wBAAwB,EAAE,WAAW,CAAC,CAAC;QAC3G,CAAC;IACH,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,oBAAoB,CAAC,MAAqB;QAC/C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,2BAAkB,CAAC,uCAAuC,CAAC,CAAC;QACxE,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,2BAAkB,CAAC,uCAAuC,CAAC,CAAC;QACxE,CAAC;QAED,0BAA0B;QAC1B,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,KAAK,CAAC,CAAC;QACxE,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,2BAAkB,CAAC,8BAA8B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC;QACtG,CAAC;QAED,sBAAsB;QACtB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,kBAAkB;QACvB,OAAO;YACL,MAAM,EAAE;gBACN;oBACE,EAAE,EAAE,iBAAiB;oBACrB,IAAI,EAAE,oBAAoB;oBAC1B,SAAS,EAAE,sCAAsC;oBACjD,QAAQ,EAAE,KAAK;oBACf,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB;iBAC5C;gBACD;oBACE,EAAE,EAAE,gBAAgB;oBACpB,IAAI,EAAE,mBAAmB;oBACzB,SAAS,EAAE,qCAAqC;oBAChD,QAAQ,EAAE,KAAK;iBAChB;aACF;YACD,QAAQ,EAAE;gBACR,QAAQ,EAAE,KAAK;gBACf,OAAO,EAAE,KAAK;gBACd,iBAAiB,EAAE,CAAC;gBACpB,KAAK,EAAE,KAAK;aACb;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,cAAc;QACnB,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAA,cAAO,EAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,UAAU;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,oBAAoB;QACzB,OAAO;;;;;;iBAMM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;oBAMrB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4B/C,CAAC;IACA,CAAC;;AAvQH,oDAwQC"}

package/dist/lib/core/ConversationTypes.d.ts

@@ -0,0 +1,422 @@
+/**
+ * Represents a single message in a conversation with an agent
+ */
+export interface Message {
+    /** Unique identifier for this message */
+    id: string;
+    /** Role of the message sender */
+    role: 'user' | 'agent' | 'system';
+    /** Message content - can be structured or text */
+    content: any;
+    /** Timestamp when message was created */
+    timestamp: string;
+    /** Optional metadata about the message */
+    metadata?: {
+        /** Tool/task name if this message is tool-related */
+        toolName?: string;
+        /** Message type (request, response, clarification, etc.) */
+        type?: string;
+        /** Additional context data */
+        [key: string]: any;
+    };
+}
+/**
+ * Request for input from the agent - sent when clarification is needed
+ */
+export interface InputRequest {
+    /** Human-readable question or prompt */
+    question: string;
+    /** Specific field being requested (if applicable) */
+    field?: string;
+    /** Expected type of response */
+    expectedType?: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** Suggested values or options */
+    suggestions?: any[];
+    /** Whether this input is required */
+    required?: boolean;
+    /** Validation rules for the input */
+    validation?: {
+        min?: number;
+        max?: number;
+        pattern?: string;
+        enum?: any[];
+    };
+    /** Additional context about why this input is needed */
+    context?: string;
+}
+/**
+ * Different types of responses an input handler can provide
+ */
+export type InputHandlerResponse = any | Promise<any> | {
+    defer: true;
+    token: string;
+} | {
+    abort: true;
+    reason?: string;
+} | never;
+/**
+ * Function signature for input handlers
+ */
+export type InputHandler = (context: ConversationContext) => InputHandlerResponse;
+/**
+ * Complete conversation context provided to input handlers
+ */
+export interface ConversationContext {
+    /** Full conversation history for this task */
+    messages: Message[];
+    /** Current input request from the agent */
+    inputRequest: InputRequest;
+    /** Unique task identifier */
+    taskId: string;
+    /** Agent configuration */
+    agent: {
+        id: string;
+        name: string;
+        protocol: 'mcp' | 'a2a';
+    };
+    /** Current clarification attempt number (1-based) */
+    attempt: number;
+    /** Maximum allowed clarification attempts */
+    maxAttempts: number;
+    /** Helper method to defer task to human */
+    deferToHuman(): Promise<{
+        defer: true;
+        token: string;
+    }>;
+    /** Helper method to abort the task */
+    abort(reason?: string): never;
+    /** Get conversation summary for context */
+    getSummary(): string;
+    /** Check if a field was previously discussed */
+    wasFieldDiscussed(field: string): boolean;
+    /** Get previous response for a field */
+    getPreviousResponse(field: string): any;
+}
+/**
+ * Status of a task execution
+ */
+export type TaskStatus = 'pending' | 'running' | 'working' | 'needs_input' | 'input-required' | 'auth-required' | 'completed' | 'failed' | 'rejected' | 'canceled' | 'deferred' | 'aborted' | 'submitted' | 'governance-denied';
+/**
+ * Options for task execution
+ */
+export interface TaskOptions {
+    /** Timeout for entire task (ms) */
+    timeout?: number;
+    /** Maximum clarification rounds before failing */
+    maxClarifications?: number;
+    /**
+     * A2A `contextId` that binds this call to a server-side conversation.
+     * When set, the client sends it on the A2A Message envelope so the server
+     * can route to the existing session instead of starting a new one.
+     * Retained automatically across calls on the same `AgentClient`.
+     */
+    contextId?: string;
+    /**
+     * A2A `taskId` of a non-terminal task to resume (HITL / approval flows).
+     * When set, the client sends it on the A2A Message envelope so the server
+     * continues the same task rather than opening a new one.
+     */
+    taskId?: string;
+    /** Enable debug logging for this task */
+    debug?: boolean;
+    /** Additional metadata to include */
+    metadata?: Record<string, any>;
+}
+/**
+ * Internal task state for tracking execution
+ */
+export interface TaskState {
+    /** Unique task identifier */
+    taskId: string;
+    /** Task name (tool name) */
+    taskName: string;
+    /** Original parameters */
+    params: any;
+    /** Current status */
+    status: TaskStatus;
+    /** Message history */
+    messages: Message[];
+    /** Current input request (if waiting for input) */
+    pendingInput?: InputRequest;
+    /** Start time */
+    startTime: number;
+    /** Current attempt number */
+    attempt: number;
+    /** Maximum attempts allowed */
+    maxAttempts: number;
+    /** Task options */
+    options: TaskOptions;
+    /** Agent configuration */
+    agent: {
+        id: string;
+        name: string;
+        protocol: 'mcp' | 'a2a';
+    };
+    /**
+     * Idempotency key for this task, when the tool is mutating. Tracked on
+     * state so internal retries reuse the same key (the whole point of the
+     * envelope — a re-generated key defeats retry safety).
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Task tracking information from tasks/get endpoint (PR #78)
+ */
+export interface TaskInfo {
+    /** Task ID */
+    taskId: string;
+    /** Current status */
+    status: string;
+    /** Task type/name */
+    taskType: string;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last update timestamp */
+    updatedAt: number;
+    /** Task result (if completed) */
+    result?: any;
+    /** Error message (if failed) */
+    error?: string;
+    /** Human-readable message from agent (alternative to error field) */
+    message?: string;
+    /** Webhook URL (if applicable) */
+    webhookUrl?: string;
+}
+/**
+ * Continuation for deferred client tasks (client needs time)
+ */
+export interface DeferredContinuation<T> {
+    /** Token for resuming the task */
+    token: string;
+    /** Question that triggered the deferral */
+    question?: string;
+    /** Resume the task with user input */
+    resume: (input: any) => Promise<TaskResult<T>>;
+}
+/**
+ * Continuation for submitted server tasks (server needs time).
+ *
+ * Returned in `TaskResult.submitted` when the seller signals an AdCP
+ * `submitted` arm (long-running work that won't complete inside the
+ * transport call). The buyer either polls via {@link waitForCompletion}
+ * / {@link track} or waits for the seller's webhook callback at
+ * {@link webhookUrl}.
+ */
+export interface SubmittedContinuation<T> {
+    /**
+     * Server-assigned task handle — the value the seller emitted in
+     * `response.task_id` (AdCP submitted-arm wire field) or surfaced via
+     * the A2A response Task. This is the identifier the seller knows; it
+     * is what the SDK passes to subsequent `tasks/get` polling calls.
+     *
+     * NOT the same as the SDK's runner-side correlation id (`TaskState.taskId`,
+     * a local UUID generated at request time and used internally for
+     * `activeTasks` map indexing and the `{operation_id}` webhook URL macro).
+     * The runner-side id never reaches the seller.
+     *
+     * If the seller violated the spec and didn't include a task handle on
+     * the submitted-arm response, this falls back to the runner-side
+     * correlation id — pollers won't be able to locate the work, but
+     * callers at least get a non-undefined value to log.
+     */
+    taskId: string;
+    /** Webhook URL where server will notify completion */
+    webhookUrl?: string;
+    /** Get current task status */
+    track: () => Promise<TaskInfo>;
+    /** Wait for completion with polling */
+    waitForCompletion: (pollInterval?: number) => Promise<TaskResult<T>>;
+}
+/**
+ * Structured AdCP error information extracted from a failed task response.
+ * Present on `TaskResult.adcpError` when the agent returns a recognized error.
+ */
+export interface AdcpErrorInfo {
+    /** AdCP error code (e.g., 'RATE_LIMITED', 'PRODUCT_NOT_FOUND') */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Recovery classification: retry, fix the request, or give up */
+    recovery?: 'transient' | 'correctable' | 'terminal';
+    /** Field that caused the error */
+    field?: string;
+    /** Suggested fix from the agent. Untrusted — sanitize before rendering in HTML. */
+    suggestion?: string;
+    /** Seconds to wait before retrying (transient errors). See also `retryAfterMs`. */
+    retry_after?: number;
+    /** Milliseconds to wait before retrying — convenience conversion of `retry_after * 1000`. */
+    retryAfterMs?: number;
+    /** Additional error details. Untrusted agent-controlled content — sanitize before rendering. */
+    details?: Record<string, unknown>;
+    /** True when the SDK inferred this error from unstructured text (L1 compliance) */
+    synthetic?: boolean;
+}
+/**
+ * Task execution metadata, shared across all result variants.
+ */
+export interface TaskResultMetadata {
+    /**
+     * Client-minted correlation id for this specific request attempt. Used
+     * for internal tracking (activeTasks map, webhook URL macros, debug
+     * logs) and retried/refired across attempts — NOT the A2A task id the
+     * server is tracking. For the server-side id, use {@link serverTaskId}.
+     */
+    taskId: string;
+    /**
+     * Server-returned A2A `contextId` / AdCP `context_id` that binds this
+     * response to a server-side conversation. Present when the server surfaced
+     * one; `undefined` otherwise (e.g., fire-and-forget MCP completions).
+     *
+     * Buyers who persist conversation across process restarts should save this
+     * and seed it into `AgentClient.resetContext(id)` on rehydration.
+     */
+    contextId?: string;
+    /**
+     * A2A `taskId` of the server-tracked task for this response. Populated
+     * from A2A Task / Message responses; `undefined` for MCP and for A2A
+     * responses that carry no task binding. Distinct from {@link taskId},
+     * which is the client-minted correlation id.
+     */
+    serverTaskId?: string;
+    taskName: string;
+    agent: {
+        id: string;
+        name: string;
+        protocol: 'mcp' | 'a2a';
+    };
+    /** Total execution time in milliseconds */
+    responseTimeMs: number;
+    /** ISO timestamp of completion */
+    timestamp: string;
+    /** Number of clarification rounds */
+    clarificationRounds: number;
+    /** Final status */
+    status: TaskStatus;
+    /** Input request details (for input-required status) */
+    inputRequest?: InputRequest;
+    /**
+     * Idempotency key used for this request, when the tool is mutating. Auto-
+     * generated by the SDK when the caller doesn't supply one. Surfaced for
+     * logging, correlation, and BYOK flows where the caller persists the key
+     * alongside the resource it creates.
+     */
+    idempotency_key?: string;
+    /**
+     * True when the response was a cached replay from the seller's idempotency
+     * store (i.e., an earlier request with the same key already succeeded).
+     *
+     * Callers with side effects on response — "campaign created!" notifications,
+     * LLM memory writes, downstream tool calls — MUST check this flag before
+     * acting, or retries will re-fire side effects.
+     */
+    replayed?: boolean;
+}
+/** Fields shared across all TaskResult variants. */
+interface TaskResultBase<T = any> {
+    metadata: TaskResultMetadata;
+    /** Governance check result (present when governance is configured) */
+    governance?: import('./GovernanceTypes').GovernanceCheckResult;
+    /** Governance outcome (present after successful execution with governance) */
+    governanceOutcome?: import('./GovernanceTypes').GovernanceOutcome;
+    /** Error message when governance outcome reporting failed */
+    governanceOutcomeError?: string;
+    /** Full conversation history */
+    conversation?: Message[];
+    /** Debug logs (if debug enabled) */
+    debug_logs?: any[];
+    /**
+     * Exhaustive pattern match on the result's `status`. Prefer this method
+     * form — it autocompletes alongside the other `TaskResult` accessors.
+     *
+     * The free function {@link import('./match').match} is also exported for
+     * compositional use (e.g., point-free style or when the result type is
+     * not yet narrowed).
+     *
+     * Attached non-enumerably by the client when the result is returned
+     * from `executeTask`. Results constructed by hand (e.g., in test
+     * fixtures or custom middleware) will not have this method — use the
+     * free function, or call `attachMatch(result)` first.
+     */
+    match?: <R>(handlers: import('./match').MatchHandlers<T, R> | import('./match').PartialMatchHandlers<T, R>) => R;
+}
+/** Successful completion — `data` is always present. */
+export interface TaskResultCompleted<T> extends TaskResultBase<T> {
+    success: true;
+    status: 'completed';
+    data: T;
+    error?: undefined;
+    adcpError?: undefined;
+    errorInstance?: undefined;
+    correlationId?: undefined;
+    deferred?: undefined;
+    submitted?: undefined;
+}
+/** Task is still progressing (working, submitted, input-required, deferred). */
+export interface TaskResultIntermediate<T> extends TaskResultBase<T> {
+    success: true;
+    /**
+     * Task is progressing but not yet final. `'auth-required'` and
+     * `'input-required'` are paused states surfaced by the polling
+     * cycle (`pollTaskCompletion`) — the buyer must satisfy the
+     * paused condition (refresh auth / supply input) and retry the
+     * original tool call. Polling alone won't advance them.
+     */
+    status: 'working' | 'submitted' | 'input-required' | 'auth-required' | 'deferred';
+    data?: T;
+    error?: undefined;
+    adcpError?: undefined;
+    errorInstance?: undefined;
+    correlationId?: undefined;
+    /** Deferred continuation (client needs time for input) */
+    deferred?: DeferredContinuation<T>;
+    /** Submitted continuation (server needs time for processing) */
+    submitted?: SubmittedContinuation<T>;
+}
+/** Task failed — `error` is always present. */
+export interface TaskResultFailure<T> extends TaskResultBase<T> {
+    success: false;
+    status: 'failed' | 'governance-denied';
+    /** Response payload with structured error details (adcp_error, context, ext) */
+    data?: T;
+    /** Human-readable error message */
+    error: string;
+    /** Structured AdCP error (code, recovery, suggestion, retryAfterMs) */
+    adcpError?: AdcpErrorInfo;
+    /**
+     * Typed `ADCPError` subclass instance when the seller's error code has a
+     * dedicated class — currently `IdempotencyConflictError` and
+     * `IdempotencyExpiredError`. Lets callers write
+     * `if (result.errorInstance instanceof IdempotencyConflictError)` instead of
+     * switching on `adcpError.code` strings. Absent for codes without a typed
+     * mapping.
+     */
+    errorInstance?: import('../errors').ADCPError;
+    /** Correlation ID from the error response context, for tracing across agents */
+    correlationId?: string;
+    deferred?: undefined;
+    submitted?: undefined;
+}
+/**
+ * Result of a task execution.
+ *
+ * Discriminated union on `success`:
+ * - `success: true` + `status: 'completed'` → `data` is `T`
+ * - `success: true` + intermediate status → task is progressing, `data` may be partial
+ * - `success: false` → `error` is always a string, `adcpError` has structured details
+ */
+export type TaskResult<T = any> = TaskResultCompleted<T> | TaskResultIntermediate<T> | TaskResultFailure<T>;
+/**
+ * Configuration for conversation management
+ */
+export interface ConversationConfig {
+    /** Maximum messages to keep in history */
+    maxHistorySize?: number;
+    /** Whether to persist conversations */
+    persistConversations?: boolean;
+    /** Timeout for 'working' status (max 120s per PR #78) */
+    workingTimeout?: number;
+    /** Default max clarifications */
+    defaultMaxClarifications?: number;
+}
+export {};
+//# sourceMappingURL=ConversationTypes.d.ts.map