clinch-core 0.6.2 → 0.7.0

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

@@ -48,12 +48,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 +72,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;

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;
@@ -311,6 +325,7 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         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 +333,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`, {
@@ -368,6 +387,100 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         session.exitTokenHash = res.token_hash;
         return res.token_hash;
     }
+    // --------------------------------------------------------------------------
+    // CASCADING ITERATIVE NEGOTIATION (Squeeze vs. Parallel Concurrency)
+    // --------------------------------------------------------------------------
+    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;
+        }
+        // ── STRATEGY 1: PARALLEL RACE (High Urgency / Ride Hailing) ──
+        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
+            };
+        }
+        // ── STRATEGY 2: SEQUENTIAL SQUEEZE (Low Urgency / Price Optimization) ──
+        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.0",
 
   "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)));
 }
 
 // ============================================================================
@@ -97,6 +97,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 +132,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');
@@ -356,7 +373,9 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         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 +383,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));
 
@@ -426,6 +450,117 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         return res.token_hash;
     }
 
+    // --------------------------------------------------------------------------
+    // CASCADING ITERATIVE NEGOTIATION (Squeeze vs. Parallel Concurrency)
+    // --------------------------------------------------------------------------
+    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;
+        }
+
+        // ── STRATEGY 1: PARALLEL RACE (High Urgency / Ride Hailing) ──
+        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
+            };
+        }
+
+        // ── STRATEGY 2: SEQUENTIAL SQUEEZE (Low Urgency / Price Optimization) ──
+        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;