clinch-core 0.6.2 → 0.7.1

package/README.md

@@ -11,7 +11,7 @@
 The Agent Negotiation Protocol (ANP) governs how two autonomous software agents establish identity, declare capabilities, and reach a cryptographically verifiable agreement on price and terms.
 
 ### 1.1 Address Formatting & Routing
-All destination routing in Clinch relies on strict, structured addressing:
+All destination routing in Clinch relies on structured, prefixed addresses:
 
 $$\text{PROTOCOL\_MODE} \mathbin{.} \text{domain} \mathbin{.} \text{TLD}$$
 
@@ -36,9 +36,10 @@ The SDK maintains an isolated, turn-based state machine for each active session.
 *   `OFFLINE`: Client is completely disconnected.
 *   `CONNECTING`: Authenticating identity and performing local Proof-of-Work (PoW) verification.
 *   `IDLE`: Connected and authenticated. Ready to initialize new sessions.
+*   `RECONNECTING`: Socket connection lost; executing exponential backoff.
 *   `NEGOTIATING`: Active, turn-based bargaining sequence in progress.
 *   `CONVERGED`: Mathematical convergence reached; agreement co-signed.
-*   `STALEMATE`: Handshake or negotiation sequence aborted or timed out.
+*   `STALEMATE`: Negotiation terminated; max turns reached without convergence.
 *   `ERROR`: Internal network, compilation, or cryptographic validation failure.
 
 ### Developer Event Subscriptions
@@ -114,7 +115,7 @@ async function runAutonomousSession() {
 runAutonomousSession();
 ```
 
-### 4.2 Cloud Webhook & Horizontal Scale Pattern
+### 4.2 Webhook & Horizontal Scale Pattern
 For enterprise cloud environments where processes must remain stateless or scale horizontally across server pods, you must serialize and rehydrate active sessions dynamically. This ensures that when an asynchronous callback arrives, any pod can load the session state and use the matching ephemeral key to sign the next turn.
 
 ```javascript
@@ -167,11 +168,51 @@ webhookCore.on('callback_received', async (event) => {
 });
 ```
 
+### 4.3 Cascading Multi-Seller Squeeze and Races
+To implement market discovery, the SDK supports cascading negotiations across multiple matching sellers. The Core orchestrates two distinct optimization strategies:
+
+#### Sequential Squeeze (Default)
+Useful for high-value items where time is secondary to price. The SDK negotiates sequentially with each seller, using the converged deal price of the previous seller as the strict, maximum budget ceiling for the next. This dynamically forces sellers to underbid one another.
+
+#### Parallel Race
+Necessary for real-time services like ride-hailing or logistics. The SDK handshakes and conducts negotiations with all selected sellers concurrently in parallel. Once all sessions finish, it selects the absolute lowest price converged under your budget.
+
+```javascript
+// Triggers the cascading loop
+const bestDeal = await core.negotiateCascade(
+    'domain_name',          // Category to discover
+    { intent: 'purchase', item: 'mybrand.io', max_budget: 150.00 },
+    3,                      // Max sellers to target
+    'sequential'            // 'sequential' | 'parallel'
+);
+
+if (bestDeal) {
+    console.log(`🏆 Optimal deal secured with ${bestDeal.sellerId} at $${bestDeal.finalPrice}`);
+}
+```
+
+### 4.4 Blind Key Pass (Credential Injection)
+For sessions with services that require authorization tokens or API keys to operate (such as platform execution nodes), you can register these credentials locally.
+
+The Core library securely stores these secrets and silently injects them into the handshake transport layer during session initialization. This prevents the API keys from ever being exposed to the AI model's context window, safeguarding you against prompt injection attacks.
+
+```javascript
+// Register the API credential locally bound to the domain namespace
+core.registerSecret('apify.anp', 'apify_sec_key_xyz987', 'Apify Production Token');
+
+// Handshaking with this address now automatically injects the credential silently
+const sessionId = await core.negotiate('ANP/C.apify.anp', {
+    intent: 'purchase',
+    item: 'actor-scraper-run',
+    max_budget: 5.00
+});
+```
+
 ---
 
 ## 5. Integration Guide: Seller Nodes
 
-Sellers use the `ClinchSeller` class to build compliant, automated endpoints. 
+Sellers use the `ClinchSeller` class to build compliant, automated endpoints.
 
 ### 5.1 Decoupled Routing Architecture
 To prevent centralized token expiration failures, Clinch separates ownership from routing:
@@ -241,6 +282,13 @@ Initializes the cryptographic handshake with a seller. Returns `sessionId`.
 #### `exportSessionState(sessionId)` / `importSessionState(serializedData)`
 Serializes or de-serializes all in-flight state for a given session, including ephemeral Ed25519 keys, state metrics, and local sandbox parameters, into an exchangeable JSON string.
 
+#### `registerSecret(domain, key, name?)` / `clearSecret(domain)`
+Saves or clears an API secret locally. The key is never visible to the AI agent and is silently passed in handshake payloads to the designated domain.
+
+#### `async negotiateCascade(category, constraints, maxSellers?, strategy?)`
+Queries the discovery register and cascade-negotiates with matching nodes.
+*   `strategy`: `'sequential'` (Sequential Squeeze) or `'parallel'` (Concurrent Race). Default: `'sequential'`.
+
 #### `buildAgentPrompt(sessionId, incomingMessage)`
 Assembles a contextual, structure-compliant system prompt for external LLMs to ensure compliant JSON execution.
 

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export interface SessionState {
     constraints: ConstraintVector;
     currentTurn: number;
     lastKnownPrice: number;
+    sellerInstructions?: string | null;
     sandboxSequence?: any;
     sandboxSession?: any;
 }
@@ -48,12 +49,15 @@ export declare class ClinchCore extends EventEmitter {
     identityPubKey: string;
     private activeSessions;
     private ws;
+    private localSecrets;
     private isSandboxMode;
     private sandboxModelContext;
     private sandboxMaxTurns;
     get activeNegotiationId(): string | null;
     constructor(config?: ClinchConfig);
     private setStatus;
+    registerSecret(domain: string, key: string, name?: string): void;
+    clearSecret(domain: string): void;
     initialize(cachedToken?: string): Promise<void>;
     private getRegistryUrl;
     private networkRequest;
@@ -69,6 +73,12 @@ export declare class ClinchCore extends EventEmitter {
     negotiate(address: string, constraints: ConstraintVector): Promise<string>;
     sendCounter(sessionId: string, price: number, reason: string): Promise<void>;
     exitSession(sessionId: string): Promise<string>;
+    negotiateCascade(category: string, constraints: ConstraintVector, maxSellers?: number, strategy?: 'sequential' | 'parallel'): Promise<{
+        sessionId: string;
+        sellerId: string;
+        finalPrice: number;
+    } | null>;
+    private waitForSession;
     sandbox(config?: SandboxConfig): Promise<void>;
     private setupSandbox;
     private handleAutomaticSandboxTurn;
@@ -85,6 +95,7 @@ export interface SellerRecord {
     categories: string[];
     capabilities: string[];
     display_name?: string;
+    custom_instructions?: string;
 }
 export declare class ClinchSeller extends EventEmitter {
     private config;

package/dist/index.js

@@ -47,7 +47,7 @@ const ws_1 = __importDefault(require("ws"));
 const PROTOCOL_VERSION = "0.1.0";
 const FIREBASE_CONFIG_URL = "https://clinchprotocol.web.app/network-config.json";
 function toHex(arr) {
-    return Array.from(arr).map(b => b.toString(16).padStart(2, '0')).join('');
+    return Array.from(arr).map((b) => b.toString(16).padStart(2, '0')).join('');
 }
 function fromHex(hex) {
     // Strips all spaces, newlines, and rogue quotes from .env strings
@@ -55,7 +55,7 @@ function fromHex(hex) {
     const match = clean.match(/.{1,2}/g);
     if (!match)
         return new Uint8Array(0);
-    return new Uint8Array(match.map(byte => parseInt(byte, 16)));
+    return new Uint8Array(match.map((byte) => parseInt(byte, 16)));
 }
 // ============================================================================
 // THE CLINCH CORE LIBRARY (Buyer)
@@ -71,6 +71,8 @@ class ClinchCore extends events_1.EventEmitter {
     identityPubKey;
     activeSessions = new Map();
     ws = null;
+    // Blind Key Pass Local Secret Store
+    localSecrets = new Map();
     isSandboxMode = false;
     sandboxModelContext = null;
     sandboxMaxTurns = 6;
@@ -99,6 +101,18 @@ class ClinchCore extends events_1.EventEmitter {
                 this.emit('log', `🟡 [State] ${this.status}`);
         }
     }
+    // --------------------------------------------------------------------------
+    // BLIND KEY PASS MANAGERS (Silent API Key Handshake)
+    // --------------------------------------------------------------------------
+    registerSecret(domain, key, name) {
+        const normalizedDomain = domain.toLowerCase().trim();
+        this.localSecrets.set(normalizedDomain, { key, name });
+        this.emit('log', `[Security] Blind key registered for ${normalizedDomain} (${name || 'Unnamed'})`);
+    }
+    clearSecret(domain) {
+        const normalizedDomain = domain.toLowerCase().trim();
+        this.localSecrets.delete(normalizedDomain);
+    }
     async initialize(cachedToken) {
         if (this.status === 'IDLE' || this.status === 'CONNECTING')
             return;
@@ -243,7 +257,8 @@ class ClinchCore extends events_1.EventEmitter {
             constraints: session.constraints,
             currentTurn: session.currentTurn,
             lastKnownPrice: session.lastKnownPrice,
-            ephemeralSecretKeyHex: toHex(session.keyPair.secretKey)
+            ephemeralSecretKeyHex: toHex(session.keyPair.secretKey),
+            sellerInstructions: session.sellerInstructions
         };
         return JSON.stringify(exportable);
     }
@@ -259,7 +274,8 @@ class ClinchCore extends events_1.EventEmitter {
             constraints: data.constraints,
             currentTurn: data.currentTurn,
             lastKnownPrice: data.lastKnownPrice,
-            keyPair: keyPair
+            keyPair: keyPair,
+            sellerInstructions: data.sellerInstructions
         });
         this.emit('log', `[State] Rehydrated session ${data.sessionId} pointing at ${data.sellerId}`);
     }
@@ -272,6 +288,9 @@ class ClinchCore extends events_1.EventEmitter {
             throw new Error("Cannot build prompt: Session not found.");
         const gap = session.lastKnownPrice - session.constraints.max_budget;
         const gapText = gap > 0 ? `-$${gap} (Over budget)` : `+$${Math.abs(gap)} (Under budget)`;
+        const customInstructionsBlock = session.sellerInstructions
+            ? `\nCUSTOM INSTRUCTIONS DIRECT FROM TARGET DOMAIN (${session.sellerId}):\n"""\n${session.sellerInstructions}\n"""\n`
+            : "";
         return `You are a professional AI purchasing agent negotiating via the Clinch Protocol.
 Your only goal is to secure the requested item below the maximum budget.
 
@@ -282,7 +301,7 @@ NEGOTIATION STATE:
 - Current turn: ${session.currentTurn}
 - Last seller price: $${session.lastKnownPrice}
 - Gap to budget: ${gapText}
-
+${customInstructionsBlock}
 SELLER'S LATEST MESSAGE:
 "${incomingMessage}"
 
@@ -307,10 +326,11 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         return await this.networkRequest(url);
     }
     async negotiate(address, constraints) {
-        this.emit('log', `[Protocol] Initiating handshake with ${address}...`);
+        this.emit('log', `[Protocol] Handshaking with ${address}...`);
         const parsed = this.parseAddress(address);
         const ephemeralKeys = tweetnacl_1.default.sign.keyPair();
         const ephemeralPubHex = toHex(ephemeralKeys.publicKey);
+        const blindSecret = this.localSecrets.get(parsed.domain);
         const initPayload = {
             clinch_version: PROTOCOL_VERSION,
             mode: parsed.mode,
@@ -318,6 +338,10 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             session_pub_key: ephemeralPubHex,
             timestamp_utc: new Date().toISOString()
         };
+        if (blindSecret) {
+            initPayload.blind_auth_token = blindSecret.key;
+            this.emit('log', `[Security] Silently injected blind token for ${parsed.domain} at transport layer`);
+        }
         const msgUint8 = new TextEncoder().encode(JSON.stringify(initPayload));
         const signature = toHex(tweetnacl_1.default.sign.detached(msgUint8, ephemeralKeys.secretKey));
         const response = await this.networkRequest(`/api/route/${parsed.domain}/handshake`, {
@@ -325,6 +349,7 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ ...initPayload, sig: signature })
         });
+        const instructions = response.custom_instructions || null;
         this.activeSessions.set(response.session_id, {
             sessionId: response.session_id,
             sellerId: parsed.domain,
@@ -332,7 +357,8 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             status: 'ACTIVE',
             constraints,
             currentTurn: 1,
-            lastKnownPrice: 0
+            lastKnownPrice: 0,
+            sellerInstructions: instructions
         });
         this.setStatus('NEGOTIATING');
         this.emit('session_started', { sessionId: response.session_id, sellerId: parsed.domain });
@@ -368,6 +394,95 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         session.exitTokenHash = res.token_hash;
         return res.token_hash;
     }
+    async negotiateCascade(category, constraints, maxSellers = 3, strategy = 'sequential') {
+        this.emit('log', `[Cascade] Querying registry for matching sellers under "${category}"...`);
+        const discovery = await this.search(category);
+        const sellers = (discovery.results || []).slice(0, maxSellers);
+        if (sellers.length === 0) {
+            this.emit('log', `[Cascade] No matching sellers found for category: "${category}"`);
+            return null;
+        }
+        if (strategy === 'parallel') {
+            this.emit('log', `[Cascade] ⚡ Running PARALLEL RACE simultaneously across ${sellers.length} seller nodes...`);
+            const sessionPromises = sellers.map(async (seller) => {
+                const targetAddress = `ANP/C.${seller.agent_id}`;
+                try {
+                    const sessionId = await this.negotiate(targetAddress, constraints);
+                    const result = await this.waitForSession(sessionId);
+                    return { sellerId: seller.agent_id, sessionId, ...result };
+                }
+                catch (e) {
+                    this.emit('log', `[Cascade] ⚠️ Connection failed for parallel channel ${seller.agent_id}: ${e.message}`);
+                    return { sellerId: seller.agent_id, sessionId: '', outcome: 'stalemate', price: Infinity };
+                }
+            });
+            const results = await Promise.all(sessionPromises);
+            const successfulDeals = results.filter((r) => r.outcome === 'deal' && r.price <= constraints.max_budget);
+            if (successfulDeals.length === 0) {
+                this.emit('log', `[Cascade] ✗ Parallel race completed. No successful deals reached.`);
+                return null;
+            }
+            successfulDeals.sort((a, b) => a.price - b.price);
+            const winner = successfulDeals[0];
+            this.emit('log', `[Cascade] 🏆 Parallel race complete! Lowest offer: $${winner.price} from ${winner.sellerId}`);
+            return {
+                sessionId: winner.sessionId,
+                sellerId: winner.sellerId,
+                finalPrice: winner.price
+            };
+        }
+        this.emit('log', `[Cascade] ➔ Running SEQUENTIAL SQUEEZE across ${sellers.length} seller nodes...`);
+        let bestDeal = null;
+        let currentBudgetCeiling = constraints.max_budget;
+        for (const seller of sellers) {
+            const targetAddress = `ANP/C.${seller.agent_id}`;
+            this.emit('log', `\n[Cascade] Squeezing target: ${targetAddress} | Squeeze Ceiling: $${currentBudgetCeiling}`);
+            const sessionConstraints = {
+                ...constraints,
+                max_budget: currentBudgetCeiling
+            };
+            try {
+                const sessionId = await this.negotiate(targetAddress, sessionConstraints);
+                const result = await this.waitForSession(sessionId);
+                if (result.outcome === 'deal' && result.price < currentBudgetCeiling) {
+                    this.emit('log', `[Cascade] ✓ Better deal clinched at $${result.price} from ${seller.agent_id}!`);
+                    bestDeal = {
+                        sessionId,
+                        sellerId: seller.agent_id,
+                        finalPrice: result.price
+                    };
+                    currentBudgetCeiling = result.price;
+                }
+                else {
+                    this.emit('log', `[Cascade] ✗ Seller ${seller.agent_id} failed to beat current best offer of $${currentBudgetCeiling}`);
+                }
+            }
+            catch (e) {
+                this.emit('log', `[Cascade] ⚠️ Dynamic session error with ${seller.agent_id}: ${e.message}`);
+            }
+        }
+        return bestDeal;
+    }
+    waitForSession(sessionId) {
+        return new Promise((resolve) => {
+            const onClosed = (event) => {
+                if (event.sessionId === sessionId) {
+                    this.off('session_closed', onClosed);
+                    this.off('status_changed', onStatus);
+                    resolve({ outcome: 'deal', price: event.finalPrice });
+                }
+            };
+            const onStatus = (status) => {
+                if (status === 'STALEMATE') {
+                    this.off('session_closed', onClosed);
+                    this.off('status_changed', onStatus);
+                    resolve({ outcome: 'stalemate', price: Infinity });
+                }
+            };
+            this.on('session_closed', onClosed);
+            this.on('status_changed', onStatus);
+        });
+    }
     async sandbox(config = {}) {
         this.isSandboxMode = true;
         this.sandboxMaxTurns = config.maxTurns || 6;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clinch-core",
-  "version": "0.6.2",
+  "version": "0.7.1",
 
   "description": "Clinch Protocol Edge Client",
   "main": "dist/index.js",

package/src/index.ts

@@ -10,7 +10,7 @@ const PROTOCOL_VERSION = "0.1.0";
 const FIREBASE_CONFIG_URL = "https://clinchprotocol.web.app/network-config.json";
 
 function toHex(arr: Uint8Array | number[]): string {
-    return Array.from(arr).map(b => b.toString(16).padStart(2, '0')).join('');
+    return Array.from(arr).map((b: number) => b.toString(16).padStart(2, '0')).join('');
 }
 
 function fromHex(hex: string): Uint8Array {
@@ -18,7 +18,7 @@ function fromHex(hex: string): Uint8Array {
     const clean = hex.replace(/[^0-9a-fA-F]/g, '');
     const match = clean.match(/.{1,2}/g);
     if (!match) return new Uint8Array(0);
-    return new Uint8Array(match.map(byte => parseInt(byte, 16)));
+    return new Uint8Array(match.map((byte: string) => parseInt(byte, 16)));
 }
 
 // ============================================================================
@@ -63,6 +63,9 @@ export interface SessionState {
     currentTurn: number;
     lastKnownPrice: number;
 
+    // Direct, dynamic instructions injected by the target domain
+    sellerInstructions?: string | null;
+
     sandboxSequence?: any; 
     sandboxSession?: any;
 }
@@ -97,6 +100,9 @@ export class ClinchCore extends EventEmitter {
     private activeSessions = new Map<string, SessionState>();
     private ws: WebSocket | null = null;
 
+    // Blind Key Pass Local Secret Store
+    private localSecrets = new Map<string, { key: string, name?: string }>();
+
     private isSandboxMode = false;
     private sandboxModelContext: any = null;
     private sandboxMaxTurns = 6;
@@ -129,6 +135,20 @@ export class ClinchCore extends EventEmitter {
         }
     }
 
+    // --------------------------------------------------------------------------
+    // BLIND KEY PASS MANAGERS (Silent API Key Handshake)
+    // --------------------------------------------------------------------------
+    public registerSecret(domain: string, key: string, name?: string): void {
+        const normalizedDomain = domain.toLowerCase().trim();
+        this.localSecrets.set(normalizedDomain, { key, name });
+        this.emit('log', `[Security] Blind key registered for ${normalizedDomain} (${name || 'Unnamed'})`);
+    }
+
+    public clearSecret(domain: string): void {
+        const normalizedDomain = domain.toLowerCase().trim();
+        this.localSecrets.delete(normalizedDomain);
+    }
+
     async initialize(cachedToken?: string): Promise<void> {
         if (this.status === 'IDLE' || this.status === 'CONNECTING') return;
         this.setStatus('CONNECTING');
@@ -278,7 +298,8 @@ export class ClinchCore extends EventEmitter {
             constraints: session.constraints,
             currentTurn: session.currentTurn,
             lastKnownPrice: session.lastKnownPrice,
-            ephemeralSecretKeyHex: toHex(session.keyPair.secretKey)
+            ephemeralSecretKeyHex: toHex(session.keyPair.secretKey),
+            sellerInstructions: session.sellerInstructions
         };
 
         return JSON.stringify(exportable);
@@ -297,7 +318,8 @@ export class ClinchCore extends EventEmitter {
             constraints: data.constraints,
             currentTurn: data.currentTurn,
             lastKnownPrice: data.lastKnownPrice,
-            keyPair: keyPair
+            keyPair: keyPair,
+            sellerInstructions: data.sellerInstructions
         });
 
         this.emit('log', `[State] Rehydrated session ${data.sessionId} pointing at ${data.sellerId}`);
@@ -314,6 +336,10 @@ export class ClinchCore extends EventEmitter {
         const gap = session.lastKnownPrice - session.constraints.max_budget;
         const gapText = gap > 0 ? `-$${gap} (Over budget)` : `+$${Math.abs(gap)} (Under budget)`;
 
+        const customInstructionsBlock = session.sellerInstructions
+            ? `\nCUSTOM INSTRUCTIONS DIRECT FROM TARGET DOMAIN (${session.sellerId}):\n"""\n${session.sellerInstructions}\n"""\n`
+            : "";
+
         return `You are a professional AI purchasing agent negotiating via the Clinch Protocol.
 Your only goal is to secure the requested item below the maximum budget.
 
@@ -324,7 +350,7 @@ NEGOTIATION STATE:
 - Current turn: ${session.currentTurn}
 - Last seller price: $${session.lastKnownPrice}
 - Gap to budget: ${gapText}
-
+${customInstructionsBlock}
 SELLER'S LATEST MESSAGE:
 "${incomingMessage}"
 
@@ -350,13 +376,15 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
     }
 
     async negotiate(address: string, constraints: ConstraintVector): Promise<string> {
-        this.emit('log', `[Protocol] Initiating handshake with ${address}...`);
+        this.emit('log', `[Protocol] Handshaking with ${address}...`);
         const parsed = this.parseAddress(address);
 
         const ephemeralKeys = nacl.sign.keyPair();
         const ephemeralPubHex = toHex(ephemeralKeys.publicKey);
 
-        const initPayload = {
+        const blindSecret = this.localSecrets.get(parsed.domain);
+
+        const initPayload: any = {
             clinch_version: PROTOCOL_VERSION,
             mode: parsed.mode,
             constraints,
@@ -364,6 +392,11 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             timestamp_utc: new Date().toISOString()
         };
 
+        if (blindSecret) {
+            initPayload.blind_auth_token = blindSecret.key;
+            this.emit('log', `[Security] Silently injected blind token for ${parsed.domain} at transport layer`);
+        }
+
         const msgUint8 = new TextEncoder().encode(JSON.stringify(initPayload));
         const signature = toHex(nacl.sign.detached(msgUint8, ephemeralKeys.secretKey));
 
@@ -373,6 +406,8 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             body: JSON.stringify({ ...initPayload, sig: signature })
         });
 
+        const instructions = response.custom_instructions || null;
+
         this.activeSessions.set(response.session_id, {
             sessionId: response.session_id,
             sellerId: parsed.domain,
@@ -380,7 +415,8 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             status: 'ACTIVE',
             constraints,
             currentTurn: 1,
-            lastKnownPrice: 0
+            lastKnownPrice: 0,
+            sellerInstructions: instructions
         });
 
         this.setStatus('NEGOTIATING');
@@ -426,6 +462,112 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         return res.token_hash;
     }
 
+    public async negotiateCascade(
+        category: string, 
+        constraints: ConstraintVector, 
+        maxSellers = 3,
+        strategy: 'sequential' | 'parallel' = 'sequential'
+    ): Promise<{ sessionId: string, sellerId: string, finalPrice: number } | null> {
+        this.emit('log', `[Cascade] Querying registry for matching sellers under "${category}"...`);
+        const discovery = await this.search(category);
+        const sellers: any[] = (discovery.results || []).slice(0, maxSellers);
+
+        if (sellers.length === 0) {
+            this.emit('log', `[Cascade] No matching sellers found for category: "${category}"`);
+            return null;
+        }
+
+        if (strategy === 'parallel') {
+            this.emit('log', `[Cascade] ⚡ Running PARALLEL RACE simultaneously across ${sellers.length} seller nodes...`);
+            
+            const sessionPromises = sellers.map(async (seller: any) => {
+                const targetAddress = `ANP/C.${seller.agent_id}`;
+                try {
+                    const sessionId = await this.negotiate(targetAddress, constraints);
+                    const result = await this.waitForSession(sessionId);
+                    return { sellerId: seller.agent_id, sessionId, ...result };
+                } catch (e: any) {
+                    this.emit('log', `[Cascade] ⚠️ Connection failed for parallel channel ${seller.agent_id}: ${e.message}`);
+                    return { sellerId: seller.agent_id, sessionId: '', outcome: 'stalemate' as const, price: Infinity };
+                }
+            });
+
+            const results = await Promise.all(sessionPromises);
+            const successfulDeals = results.filter((r: any) => r.outcome === 'deal' && r.price <= constraints.max_budget);
+
+            if (successfulDeals.length === 0) {
+                this.emit('log', `[Cascade] ✗ Parallel race completed. No successful deals reached.`);
+                return null;
+            }
+
+            successfulDeals.sort((a: any, b: any) => a.price - b.price);
+            const winner = successfulDeals[0];
+
+            this.emit('log', `[Cascade] 🏆 Parallel race complete! Lowest offer: $${winner.price} from ${winner.sellerId}`);
+            return {
+                sessionId: winner.sessionId,
+                sellerId: winner.sellerId,
+                finalPrice: winner.price
+            };
+        }
+
+        this.emit('log', `[Cascade] ➔ Running SEQUENTIAL SQUEEZE across ${sellers.length} seller nodes...`);
+        let bestDeal: { sessionId: string, sellerId: string, finalPrice: number } | null = null;
+        let currentBudgetCeiling = constraints.max_budget;
+
+        for (const seller of sellers) {
+            const targetAddress = `ANP/C.${seller.agent_id}`;
+            this.emit('log', `\n[Cascade] Squeezing target: ${targetAddress} | Squeeze Ceiling: $${currentBudgetCeiling}`);
+
+            const sessionConstraints = {
+                ...constraints,
+                max_budget: currentBudgetCeiling
+            };
+
+            try {
+                const sessionId = await this.negotiate(targetAddress, sessionConstraints);
+                const result = await this.waitForSession(sessionId);
+
+                if (result.outcome === 'deal' && result.price < currentBudgetCeiling) {
+                    this.emit('log', `[Cascade] ✓ Better deal clinched at $${result.price} from ${seller.agent_id}!`);
+                    bestDeal = {
+                        sessionId,
+                        sellerId: seller.agent_id,
+                        finalPrice: result.price
+                    };
+                    currentBudgetCeiling = result.price; 
+                } else {
+                    this.emit('log', `[Cascade] ✗ Seller ${seller.agent_id} failed to beat current best offer of $${currentBudgetCeiling}`);
+                }
+            } catch (e: any) {
+                this.emit('log', `[Cascade] ⚠️ Dynamic session error with ${seller.agent_id}: ${e.message}`);
+            }
+        }
+
+        return bestDeal;
+    }
+
+    private waitForSession(sessionId: string): Promise<{ outcome: 'deal' | 'stalemate', price: number }> {
+        return new Promise((resolve) => {
+            const onClosed = (event: any) => {
+                if (event.sessionId === sessionId) {
+                    this.off('session_closed', onClosed);
+                    this.off('status_changed', onStatus);
+                    resolve({ outcome: 'deal', price: event.finalPrice });
+                }
+            };
+            const onStatus = (status: CoreStatus) => {
+                if (status === 'STALEMATE') {
+                    this.off('session_closed', onClosed);
+                    this.off('status_changed', onStatus);
+                    resolve({ outcome: 'stalemate', price: Infinity });
+                }
+            };
+            this.on('session_closed', onClosed);
+            this.on('status_changed', onStatus);
+        });
+    }
+
     async sandbox(config: SandboxConfig = {}): Promise<void> {
         this.isSandboxMode = true;
         this.sandboxMaxTurns = config.maxTurns || 6;
@@ -600,12 +742,13 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
 // THE CLINCH SELLER LIBRARY (Server-Side)
 // ============================================================================
 export interface SellerRecord {
-  agent_id:        string;
-  endpoint:        string;
-  supported_modes: string[];
-  categories:      string[];
-  capabilities:    string[];
-  display_name?:   string; 
+  agent_id:            string;
+  endpoint:            string;
+  supported_modes:     string[];
+  categories:          string[];
+  capabilities:        string[];
+  display_name?:       string; 
+  custom_instructions?: string; // Strictly typed dynamic record instructions mapping
 }
 
 export class ClinchSeller extends EventEmitter {