clinch-core 0.4.0 → 0.6.0

package/README.md

@@ -40,7 +40,7 @@ npm install node-llama-cpp
 
 ### Core Statuses (`CoreStatus`)
 *   `OFFLINE`: Client is disconnected.
-*   `CONNECTING`: Resolving registry DNS and performing Proof-of-Work auth.
+*   `CONNECTING`: Resolving registry configuration and performing Proof-of-Work auth.
 *   `IDLE`: Connected and authenticated. Waiting for handshakes or callbacks.
 *   `RECONNECTING`: Socket connection lost; executing exponential backoff.
 *   `NEGOTIATING`: Active turn-based negotiation sequence in progress.
@@ -86,6 +86,7 @@ async function startLocalAgent() {
     await core.sandbox({ downloadLLM: true });
 
     // 2. Initiate Negotiation: Session automatically transitions to 'NEGOTIATING'
+    // Format: PROTOCOL_MODE.domain.anp (e.g., ANP/C.amazon.anp)
     const sessionId = await core.negotiate('ANP/C.amazon.anp', {
         intent: 'purchase',
         category: 'electronics',
@@ -147,6 +148,7 @@ webhookCore.on('callback_received', async (event) => {
         console.log("Deal reached!");
     } else {
         await webhookCore.sendCounter(event.sessionId, aiDecision.price, aiDecision.message);
+        // Reserialize and update DB after turn to maintain state sync
         await db.update(event.sessionId, webhookCore.exportSessionState(event.sessionId));
     }
 });
@@ -168,7 +170,10 @@ const app = express();
 app.use(express.json());
 
 // Initialize with your permanent Dashboard-generated Private Key
-const seller = new ClinchSeller({ privateKeyHex: process.env.SELLER_PRIVATE_KEY });
+const seller = new ClinchSeller({ 
+    privateKeyHex: process.env.SELLER_PRIVATE_KEY 
+    // registryUrl: 'http://localhost:7860' // Optional: Override for local dev
+});
 
 // Publish your routing endpoint to the network on boot
 await seller.registerEndpoint({
@@ -206,19 +211,20 @@ app.listen(8080);
 ### Buyer Client (`ClinchCore`)
 
 #### `new ClinchCore(config)`
-*   `config.registryUrl` *(string)*: Override Firebase dynamic routing.
+*   `config.registryUrl` *(string)*: Override default dynamic configuration resolution for local testing.
 *   `config.timeoutMs` *(number)*: Connection timeout limit (Default: `5000`ms).
 
 #### `async initialize(cachedToken?)`
-Authenticates the node, completes Identity-Bound PoW, and connects the WebSocket.
+Authenticates the node on the network, completes Identity-Bound PoW, and connects the WebSocket.
+*   `cachedToken` *(string)*: Optional. Re-use an existing network token to bypass PoW calculations on restart.
 
 #### `async negotiate(address, constraints)`
 Launches a cryptographic session handshake. Returns `sessionId`.
-*   `address` *(string)*: e.g. `ANP/C.cloudflare.anp`. (Must include mode prefix).
-*   `constraints` *(ConstraintVector)*: Must include `max_budget` (number).
+*   `address` *(string)*: Target seller address. Must include the protocol mode prefix (e.g., `ANP/C.amazon.anp`).
+*   `constraints` *(ConstraintVector)*: Must include `max_budget` (number) and `item` (string).
 
 #### `exportSessionState(sessionId)` / `importSessionState(serializedData)`
-Serializes the active session—including the ephemeral cryptographic keys, current turn, and LLM context parameters—to a JSON string. Used to scale instances horizontally or survive pod restarts.
+Serializes the active session—including the ephemeral cryptographic keys, current turn, and LLM context parameters—to a JSON string. Used to scale instances horizontally, survive pod restarts, or pick up negotiations across async callback windows.
 
 #### `buildAgentPrompt(sessionId, incomingMessage)`
 Returns a highly-optimized, state-aware string to pass to an external LLM as a System Prompt. Ensures the LLM outputs strict JSON matching the protocol rules.
@@ -232,10 +238,13 @@ Closes the active connection and generates a single-use re-engagement Callback t
 #### `async sandbox(config)`
 Initializes the edge-AI execution context, downloads the GGUF, and auto-listens.
 
+---
+
 ### Seller Client (`ClinchSeller`)
 
 #### `new ClinchSeller(config)`
 *   `config.privateKeyHex` *(string)*: The Ed25519 private key generated from the Clinch Dashboard. Used to cryptographically authenticate endpoint updates.
+*   `config.registryUrl` *(string)*: Optional. Overrides Registry configuration resolution for local testing.
 
 #### `async registerEndpoint(record)`
 Publishes the seller's DNS-style record to the Registry so buyers can discover and route to it. Signed locally via the Ed25519 identity key.

package/dist/index.js

@@ -50,7 +50,12 @@ function toHex(arr) {
     return Array.from(arr).map(b => b.toString(16).padStart(2, '0')).join('');
 }
 function fromHex(hex) {
-    return new Uint8Array(hex.match(/.{1,2}/g).map(byte => parseInt(byte, 16)));
+    // Strips all spaces, newlines, and rogue quotes from .env strings
+    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)));
 }
 // ============================================================================
 // THE CLINCH CORE LIBRARY (Buyer)
@@ -66,11 +71,9 @@ class ClinchCore extends events_1.EventEmitter {
     identityPubKey;
     activeSessions = new Map();
     ws = null;
-    // Sandbox Engine Base (Model/Context are global, Sequences are per-session)
     isSandboxMode = false;
     sandboxModelContext = null;
     sandboxMaxTurns = 6;
-    // Legacy support for single-tenant applications checking the last ID
     get activeNegotiationId() {
         return Array.from(this.activeSessions.keys()).pop() || null;
     }
@@ -228,9 +231,6 @@ class ClinchCore extends events_1.EventEmitter {
             this.ws = null;
         }
     }
-    // --------------------------------------------------------------------------
-    // SESSION STATE MANAGEMENT (For Enterprise Horizontal Scaling & Reconnects)
-    // --------------------------------------------------------------------------
     exportSessionState(sessionId) {
         const session = this.activeSessions.get(sessionId);
         if (!session)
@@ -266,9 +266,6 @@ class ClinchCore extends events_1.EventEmitter {
     getSession(sessionId) {
         return this.activeSessions.get(sessionId);
     }
-    // --------------------------------------------------------------------------
-    // UNIVERSAL PROMPT BUILDER
-    // --------------------------------------------------------------------------
     buildAgentPrompt(sessionId, incomingMessage) {
         const session = this.activeSessions.get(sessionId);
         if (!session)
@@ -303,9 +300,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
   "message": "<One concise sentence of negotiation dialogue>"
 }`;
     }
-    // --------------------------------------------------------------------------
-    // PROTOCOL OPERATIONS
-    // --------------------------------------------------------------------------
     async search(query, mode) {
         let url = `/api/discover?category=${encodeURIComponent(query)}`;
         if (mode)
@@ -355,7 +349,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ ...payload, buyer_sig })
         });
-        // Sync state if deal reached
         if (response.msg_type === 'accept' || response.status === 'COMMITTED') {
             session.status = 'CLOSED';
             session.lastKnownPrice = response.price || price;
@@ -375,9 +368,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         session.exitTokenHash = res.token_hash;
         return res.token_hash;
     }
-    // --------------------------------------------------------------------------
-    // OUT-OF-THE-BOX SANDBOX (AUTO-TURN ENGINE)
-    // --------------------------------------------------------------------------
     async sandbox(config = {}) {
         this.isSandboxMode = true;
         this.sandboxMaxTurns = config.maxTurns || 6;
@@ -392,7 +382,7 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
     }
     async setupSandbox(config = {}) {
         if (this.sandboxModelContext)
-            return; // Already initialized
+            return;
         const settings = {
             downloadLLM: true,
             modelUrl: "https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF/resolve/main/qwen2.5-1.5b-instruct-q4_k_m.gguf",
@@ -475,7 +465,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
     async sandboxEvaluate(session, incomingOffer) {
         const { LlamaChatSession, ChatMLChatWrapper } = await Promise.resolve().then(() => __importStar(require('node-llama-cpp')));
         const systemPrompt = this.buildAgentPrompt(session.sessionId, incomingOffer);
-        // State Isolation: Bind sequence to the session, not the global class!
         if (!session.sandboxSequence) {
             session.sandboxSequence = this.sandboxModelContext.getSequence();
             session.sandboxSession = new LlamaChatSession({
@@ -491,9 +480,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         });
         return responseText;
     }
-    // --------------------------------------------------------------------------
-    // UTILITIES
-    // --------------------------------------------------------------------------
     extractPrice(text, prefix) {
         const regex = new RegExp(`${prefix}\\s*\\:?\\s*\\$?(\\d+(?:\\.\\d{2})?)`, 'i');
         const match = text.match(regex);
@@ -550,10 +536,19 @@ class ClinchSeller extends events_1.EventEmitter {
         super();
         this.config = { timeoutMs: 8000, ...config };
         if (config.privateKeyHex) {
-            this.identityPrivKey = fromHex(config.privateKeyHex);
-            const kp = tweetnacl_1.default.sign.keyPair.fromSecretKey(this.identityPrivKey);
-            this.identityPubKey = toHex(kp.publicKey);
-            this.emit('log', `[Seller] Loaded permanent identity. PubKey: ${this.identityPubKey.substring(0, 12)}...`);
+            try {
+                const cleanHex = config.privateKeyHex.replace(/[^0-9a-fA-F]/g, '');
+                if (cleanHex.length !== 128) {
+                    throw new Error(`Expected 128 hex chars (64 bytes), got ${cleanHex.length}`);
+                }
+                this.identityPrivKey = fromHex(cleanHex);
+                const kp = tweetnacl_1.default.sign.keyPair.fromSecretKey(this.identityPrivKey);
+                this.identityPubKey = toHex(kp.publicKey);
+                this.emit('log', `[Seller] Loaded permanent identity. PubKey: ${this.identityPubKey.substring(0, 12)}...`);
+            }
+            catch (e) {
+                throw new Error(`[Seller] Invalid privateKeyHex in constructor: ${e.message}`);
+            }
         }
         else {
             const kp = tweetnacl_1.default.sign.keyPair();

package/package.json

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

package/src/index.ts

@@ -14,7 +14,11 @@ function toHex(arr: Uint8Array | number[]): string {
 }
 
 function fromHex(hex: string): Uint8Array {
-    return new Uint8Array(hex.match(/.{1,2}/g)!.map(byte => parseInt(byte, 16)));
+    // Strips all spaces, newlines, and rogue quotes from .env strings
+    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)));
 }
 
 // ============================================================================
@@ -56,11 +60,9 @@ export interface SessionState {
     exitTokenHash?: string;
     constraints: ConstraintVector;
     
-    // Isolated State Tracking (Crucial for concurrency)
     currentTurn: number;
     lastKnownPrice: number;
 
-    // Local LLM Context Tracking
     sandboxSequence?: any; 
     sandboxSession?: any;
 }
@@ -95,12 +97,10 @@ export class ClinchCore extends EventEmitter {
     private activeSessions = new Map<string, SessionState>();
     private ws: WebSocket | null = null;
 
-    // Sandbox Engine Base (Model/Context are global, Sequences are per-session)
     private isSandboxMode = false;
     private sandboxModelContext: any = null;
     private sandboxMaxTurns = 6;
 
-    // Legacy support for single-tenant applications checking the last ID
     public get activeNegotiationId(): string | null {
         return Array.from(this.activeSessions.keys()).pop() || null;
     }
@@ -266,9 +266,6 @@ export class ClinchCore extends EventEmitter {
         if (this.ws) { this.ws.close(); this.ws = null; }
     }
 
-    // --------------------------------------------------------------------------
-    // SESSION STATE MANAGEMENT (For Enterprise Horizontal Scaling & Reconnects)
-    // --------------------------------------------------------------------------
     public exportSessionState(sessionId: string): string {
         const session = this.activeSessions.get(sessionId);
         if (!session) throw new Error("Session not found");
@@ -289,7 +286,6 @@ export class ClinchCore extends EventEmitter {
 
     public importSessionState(serializedData: string): void {
         const data = JSON.parse(serializedData);
-        
         const secretKey = fromHex(data.ephemeralSecretKeyHex);
         const keyPair = nacl.sign.keyPair.fromSecretKey(secretKey);
 
@@ -311,9 +307,6 @@ export class ClinchCore extends EventEmitter {
         return this.activeSessions.get(sessionId);
     }
 
-    // --------------------------------------------------------------------------
-    // UNIVERSAL PROMPT BUILDER
-    // --------------------------------------------------------------------------
     public buildAgentPrompt(sessionId: string, incomingMessage: string): string {
         const session = this.activeSessions.get(sessionId);
         if (!session) throw new Error("Cannot build prompt: Session not found.");
@@ -350,9 +343,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
 }`;
     }
 
-    // --------------------------------------------------------------------------
-    // PROTOCOL OPERATIONS
-    // --------------------------------------------------------------------------
     async search(query: string, mode?: string): Promise<any> {
         let url = `/api/discover?category=${encodeURIComponent(query)}`;
         if (mode) url += `&mode=${encodeURIComponent(mode)}`;
@@ -414,7 +404,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             body: JSON.stringify({ ...payload, buyer_sig })
         });
 
-        // Sync state if deal reached
         if (response.msg_type === 'accept' || response.status === 'COMMITTED') {
             session.status = 'CLOSED';
             session.lastKnownPrice = response.price || price;
@@ -437,9 +426,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         return res.token_hash;
     }
 
-    // --------------------------------------------------------------------------
-    // OUT-OF-THE-BOX SANDBOX (AUTO-TURN ENGINE)
-    // --------------------------------------------------------------------------
     async sandbox(config: SandboxConfig = {}): Promise<void> {
         this.isSandboxMode = true;
         this.sandboxMaxTurns = config.maxTurns || 6;
@@ -455,7 +441,7 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
     }
 
     private async setupSandbox(config: SandboxConfig = {}): Promise<void> {
-        if (this.sandboxModelContext) return; // Already initialized
+        if (this.sandboxModelContext) return; 
 
         const settings = {
             downloadLLM: true,
@@ -546,7 +532,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
 
         const systemPrompt = this.buildAgentPrompt(session.sessionId, incomingOffer);
 
-        // State Isolation: Bind sequence to the session, not the global class!
         if (!session.sandboxSequence) {
             session.sandboxSequence = this.sandboxModelContext.getSequence();
             session.sandboxSession = new LlamaChatSession({
@@ -565,9 +550,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         return responseText;
     }
 
-    // --------------------------------------------------------------------------
-    // UTILITIES
-    // --------------------------------------------------------------------------
     private extractPrice(text: string, prefix: string): number | null {
         const regex = new RegExp(`${prefix}\\s*\\:?\\s*\\$?(\\d+(?:\\.\\d{2})?)`, 'i');
         const match = text.match(regex);
@@ -623,7 +605,7 @@ export interface SellerRecord {
   supported_modes: string[];
   categories:      string[];
   capabilities:    string[];
-  display_name?:   string; // Optional legacy support
+  display_name?:   string; 
 }
 
 export class ClinchSeller extends EventEmitter {
@@ -637,10 +619,18 @@ export class ClinchSeller extends EventEmitter {
     this.config = { timeoutMs: 8000, ...config };
 
     if (config.privateKeyHex) {
-      this.identityPrivKey = fromHex(config.privateKeyHex);
-      const kp = nacl.sign.keyPair.fromSecretKey(this.identityPrivKey);
-      this.identityPubKey = toHex(kp.publicKey);
-      this.emit('log', `[Seller] Loaded permanent identity. PubKey: ${this.identityPubKey.substring(0, 12)}...`);
+      try {
+        const cleanHex = config.privateKeyHex.replace(/[^0-9a-fA-F]/g, '');
+        if (cleanHex.length !== 128) {
+            throw new Error(`Expected 128 hex chars (64 bytes), got ${cleanHex.length}`);
+        }
+        this.identityPrivKey = fromHex(cleanHex);
+        const kp = nacl.sign.keyPair.fromSecretKey(this.identityPrivKey);
+        this.identityPubKey = toHex(kp.publicKey);
+        this.emit('log', `[Seller] Loaded permanent identity. PubKey: ${this.identityPubKey.substring(0, 12)}...`);
+      } catch (e: any) {
+        throw new Error(`[Seller] Invalid privateKeyHex in constructor: ${e.message}`);
+      }
     } else {
       const kp = nacl.sign.keyPair();
       this.identityPrivKey = kp.secretKey;