clinch-core 0.1.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 Clinch is a modular, edge-first protocol designed to mediate autonomous negotiations between a buyer AI agent and a seller AI agent. It allows agents to negotiate price and terms to a mutual, mathematically converged agreement without a human in the loop, and without the seller ever seeing the buyer's full profile.
 
-Once an agreement is reached, Clinch issues a **cryptographically co-signed deal artifact** held by both parties. This SDK provides the complete network client, state machine, cryptographic signing engine, an optional out-of-the-box local LLM bargaining sandbox, and the server-side Seller SDK.
+Once an agreement is reached, Clinch issues a **cryptographically co-signed deal artifact** held by both parties. This SDK provides the complete network client, state-isolated session management, cryptographic signing engines, an optional out-of-the-box local LLM bargaining sandbox, and the server-side Seller SDK.
 
 ---
 
@@ -14,8 +14,8 @@ In the modern web, purchasing, SaaS licensing, transport, and commodity procurem
 
 *   **Buyer Anonymity First**: The seller receives a simplified constraint vector (e.g., budget bracket, target category) rather than the buyer’s identity, private data, or raw history. All counter-offers are routed through the Registry proxy, guaranteeing 100% IP anonymity for the buyer.
 *   **Edge-First Execution**: The buyer agent runs locally on-device. This SDK supports dynamically importing and running optimized 1.5B 4-bit quantized models in under **1.3 GB of RAM**, making it compatible with consumer hardware.
-*   **Cryptographic Accountability**: Identity is proven via an Ed25519 identity key and Proof-of-Work (PoW). Every session uses throwaway, ephemeral session keys. The final co-signed deal artifact is self-verifying against the Registry's daily rotating key chain.
-*   **Deterministic Hybrid Architecture**: The SDK decouples conversational language from protocol math. The LLM strictly generates persuasive copy while the core SDK evaluates numerical convergence, preventing AI hallucination or rule-bypassing.
+*   **Enterprise Concurrency**: Complete session isolation allows scaling horizontally. You can run hundreds of concurrent negotiations on a single server, serialize state, and resume negotiations across pod restarts or delayed webhooks.
+*   **Cryptographic Accountability**: Identity is proven via Ed25519 keys and Proof-of-Work (PoW). The final co-signed deal artifact is self-verifying against the Registry's daily rotating key chain. Zero-trust machine-to-machine updates are enforced without centralized JWT expirations.
 
 ---
 
@@ -54,16 +54,16 @@ core.on('status_changed', (status: CoreStatus) => {
     console.log(`State transitioned to: ${status}`);
 });
 
-core.on('log', (message: string) => {
-    console.log(`[LOG] ${message}`);
+core.on('session_started', ({ sessionId, sellerId }) => {
+    console.log(`Negotiation initiated with ${sellerId} (Session: ${sessionId})`);
 });
 
-core.on('callback_received', (data: { sessionId: string, payload: any }) => {
-    // Fired when the seller routes a callback counter-offer via the Registry WS
+core.on('session_closed', ({ sessionId, outcome, finalPrice }) => {
+    console.log(`Session ${sessionId} closed. Outcome: ${outcome} at $${finalPrice}`);
 });
 
-core.on('token_issued', (data: { token: string }) => {
-    // Fired when PoW completes. Save this JWT to disk to skip PoW on next boot!
+core.on('callback_received', ({ sessionId, payload }) => {
+    // Fired when the seller routes a callback counter-offer via the Registry WS
 });
 ```
 
@@ -80,13 +80,13 @@ async function startLocalAgent() {
     const core = new ClinchCore();
 
     core.on('log', (msg) => console.log(msg));
-    core.on('status_changed', (status) => console.log(`👉 State: ${status}`));
+    core.on('session_closed', ({ finalPrice }) => console.log(`Deal secured at $${finalPrice}!`));
 
     // 1. Initialize Sandbox: Handles network auth, downloads GGUF, & registers auto-listeners
     await core.sandbox({ downloadLLM: true });
 
     // 2. Initiate Negotiation: Session automatically transitions to 'NEGOTIATING'
-    const sessionId = await core.negotiate('ANP/A.amazon.anp', {
+    const sessionId = await core.negotiate('ANP/C.amazon.anp', {
         intent: 'purchase',
         category: 'electronics',
         item: 'Ninja Blender',
@@ -101,11 +101,9 @@ startLocalAgent();
 
 ---
 
-## 🔌 Quickstart: Bring Your Own AI (Universal Prompt Builder)
-
-If you are running in a cloud environment and want to leverage high-end hosted APIs (e.g. Claude 3.5 Sonnet or OpenAI GPT-4o), bypass the sandbox. 
+## 🔌 Quickstart: Bring Your Own AI & Webhook Persistence
 
-`clinch-core` includes a **Universal Prompt Builder** (`buildAgentPrompt`) that automatically injects the current negotiation state, budget gaps, and strict JSON output schemas into a perfect system prompt for any LLM.
+If you are running in a cloud environment (e.g., handling webhooks) and want to leverage high-end hosted APIs (e.g. Claude 3.5 Sonnet or OpenAI GPT-4o), bypass the sandbox. The Core provides **State Serialization** to survive server restarts.
 
 ```javascript
 import { ClinchCore } from 'clinch-core';
@@ -114,36 +112,42 @@ import Anthropic from '@anthropic-ai/sdk';
 const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 const core = new ClinchCore();
 
-await core.initialize(); // Completes PoW and connects to WS
+await core.initialize(); 
 
+// 1. Start session and save state to DB
 const sessionId = await core.negotiate('ANP/C.amazon.anp', {
     intent: 'purchase',
     item: 'Ninja Blender',
     max_budget: 85.00
 });
+const savedState = core.exportSessionState(sessionId);
+await db.save(sessionId, savedState);
+
+// --- LATER, ON A DIFFERENT SERVER OR WEBHOOK --- //
+
+const webhookCore = new ClinchCore();
+webhookCore.importSessionState(savedState);
 
-core.on('callback_received', async (event) => {
-    const sellerCounter = event.payload;
+webhookCore.on('callback_received', async (event) => {
+    // 2. Let the Core build the perfect state-aware protocol prompt
+    const systemPrompt = webhookCore.buildAgentPrompt(event.sessionId, event.payload.message);
 
-    // 1. Let the Core build the perfect state-aware protocol prompt
-    const systemPrompt = core.buildAgentPrompt(sessionId, sellerCounter.message);
-    
-    // 2. Feed it to Claude/OpenAI
+    // 3. Feed it to Claude/OpenAI
     const msg = await anthropic.messages.create({
       model: "claude-3-5-sonnet-20241022",
-      max_tokens: 150,
+      maxTokens: 150,
       system: systemPrompt,
       messages: [{ role: "user", content: "Determine our next protocol move." }]
     });
 
     const aiDecision = JSON.parse(msg.content[0].text);
 
-    // 3. Act on the deterministic JSON response
+    // 4. Act on the deterministic JSON response
     if (aiDecision.action === 'accept') {
         console.log("Deal reached!");
-        // Proceed to /commit
     } else {
-        await core.sendCounter(sessionId, aiDecision.price, aiDecision.message);
+        await webhookCore.sendCounter(event.sessionId, aiDecision.price, aiDecision.message);
+        await db.update(event.sessionId, webhookCore.exportSessionState(event.sessionId));
     }
 });
 ```
@@ -152,7 +156,9 @@ core.on('callback_received', async (event) => {
 
 ## 🏪 Quickstart: Building a Seller Node
 
-`clinch-core` exports the `ClinchSeller` class to make building an Adapter Node or native seller server seamless. It handles dashboard authentication, endpoint registration, and cryptographic signature verification of buyer requests.
+`clinch-core` exports the `ClinchSeller` class to make building a native seller server seamless.
+
+**Architecture Note:** Seller Nodes do not use JWTs. You generate a permanent Ed25519 Keypair in the Clinch Dashboard, claim your domain, and pass the private key to your Node. The node securely self-publishes its endpoint and capabilities on boot.
 
 ```javascript
 import { ClinchSeller } from 'clinch-core';
@@ -161,35 +167,36 @@ import express from 'express';
 const app = express();
 app.use(express.json());
 
-const seller = new ClinchSeller();
+// Initialize with your permanent Dashboard-generated Private Key
+const seller = new ClinchSeller({ privateKeyHex: process.env.SELLER_PRIVATE_KEY });
 
-// Authenticate with your dashboard token and register your endpoint
-await seller.authenticate('your-supabase-seller-jwt');
+// Publish your routing endpoint to the network on boot
 await seller.registerEndpoint({
     agent_id: 'amazon.anp',
-    display_name: 'Amazon Adapter',
-    endpoint: 'https://your-seller-api.com/anp',
-    supported_modes: ['ANP/A', 'ANP/C'],
+    endpoint: 'https://your-seller-api.com/anp/v1',
+    supported_modes: ['ANP/C'],
     categories: ['electronics'],
     capabilities: ['price_flex']
 });
 
 // Create your counter-offer route
-app.post('/anp/counter', (req, res) => {
+app.post('/anp/v1/counter', (req, res) => {
     const { session_id, turn, price, reason, buyer_sig } = req.body;
-    
+
     // Verify the payload actually came from the buyer who holds the session key
     const isValid = seller.verifyBuyerSignature(
-        { session_id, turn, price, reason }, 
-        buyer_sig, 
+        { session_id, turn, price, reason },
+        buyer_sig,
         req.headers['x-buyer-pubkey']
     );
 
     if (!isValid) return res.status(401).send("Invalid signature");
 
     // Process logic and return standard counter JSON...
-    res.json({ action: 'counter', price: 95.00, message: "Best I can do is $95." });
+    res.json({ msg_type: 'counter', price: 95.00, reason: "Best I can do is $95." });
 });
+
+app.listen(8080);
 ```
 
 ---
@@ -204,13 +211,15 @@ app.post('/anp/counter', (req, res) => {
 
 #### `async initialize(cachedToken?)`
 Authenticates the node, completes Identity-Bound PoW, and connects the WebSocket.
-*   `cachedToken` *(string)*: Saved JWT to skip PoW and restore connectivity instantly.
 
 #### `async negotiate(address, constraints)`
 Launches a cryptographic session handshake. Returns `sessionId`.
-*   `address` *(string)*: e.g. `ANP/A.cloudflare.anp`.
+*   `address` *(string)*: e.g. `ANP/C.cloudflare.anp`. (Must include mode prefix).
 *   `constraints` *(ConstraintVector)*: Must include `max_budget` (number).
 
+#### `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.
+
 #### `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.
 
@@ -222,16 +231,14 @@ 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.
-*   `config.downloadLLM` *(boolean)*: Default `true`.
-*   `config.maxTurns` *(number)*: Turn limit threshold. Default `6`.
 
 ### Seller Client (`ClinchSeller`)
 
-#### `async authenticate(authToken)`
-Logs the seller node into the registry using a Dashboard JWT.
+#### `new ClinchSeller(config)`
+*   `config.privateKeyHex` *(string)*: The Ed25519 private key generated from the Clinch Dashboard. Used to cryptographically authenticate endpoint updates.
 
 #### `async registerEndpoint(record)`
-Publishes the seller's DNS-style record to the Registry so buyers can discover and route to it.
+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.
 
 #### `verifyBuyerSignature(payload, signatureHex, pubKeyHex)`
 Returns `boolean`. Cryptographically verifies that incoming counter-offers were signed by the exact ephemeral session key generated by the buyer during the handshake.
@@ -239,7 +246,8 @@ Returns `boolean`. Cryptographically verifies that incoming counter-offers were
 ---
 
 ## 🔏 Cryptographic Guarantees
-Clinch operates on a strictly zero-trust model. 
-1. **Identity-Bound PoW**: Challenge hashes include the client's `pubKey`, making outsourcing/bot-farming mathematically impossible.
-2. **Ephemeral Sessions**: `negotiate()` generates an ephemeral Session Key (`nacl.sign.keyPair()`). This key signs every individual message. If a session key is compromised, your global identity remains secure, and historical session logs remain completely un-linkable.
-3. **Anonymity Proxy**: Counter-offers are routed strictly through the Registry. The seller never logs the buyer's IP address.
+Clinch operates on a strictly zero-trust model.
+1. **Identity-Bound PoW**: Buyer challenge hashes include the client's `pubKey`, making outsourcing/bot-farming mathematically impossible.
+2. **Ed25519 Seller Authority**: Seller endpoints and capabilities are updated via Ed25519 signatures, completely decoupling the control plane (Dashboard) from the data plane (Server).
+3. **Ephemeral Sessions**: `negotiate()` generates an ephemeral Session Key. This key signs every individual message. If a session key is compromised, your global identity remains secure, and historical session logs remain completely un-linkable.
+4. **Anonymity Proxy**: Counter-offers are routed strictly through the Registry. The seller never logs the buyer's IP address.

package/dist/index.d.ts

@@ -23,6 +23,10 @@ export interface SessionState {
     status: 'ACTIVE' | 'EXITED' | 'CLOSED';
     exitTokenHash?: string;
     constraints: ConstraintVector;
+    currentTurn: number;
+    lastKnownPrice: number;
+    sandboxSequence?: any;
+    sandboxSession?: any;
 }
 export interface SandboxConfig {
     downloadLLM?: boolean;
@@ -45,13 +49,8 @@ export declare class ClinchCore extends EventEmitter {
     private activeSessions;
     private ws;
     private isSandboxMode;
-    private sandboxContext;
-    private sandboxSequence;
-    private sandboxSession;
+    private sandboxModelContext;
     private sandboxMaxTurns;
-    currentTurn: number;
-    lastKnownPrice: number;
-    activeNegotiationId: string | null;
     constructor(config?: ClinchConfig);
     private setStatus;
     initialize(cachedToken?: string): Promise<void>;
@@ -61,10 +60,9 @@ export declare class ClinchCore extends EventEmitter {
     private connectWebSocket;
     private handleReconnect;
     disconnect(): void;
-    /**
-     * Generates a universally formatted System Prompt for external LLMs (Claude, OpenAI, Gemini).
-     * Developers can pass this string directly to their AI to ensure protocol-compliant negotiation.
-     */
+    exportSessionState(sessionId: string): string;
+    importSessionState(serializedData: string): void;
+    getSession(sessionId: string): SessionState | undefined;
     buildAgentPrompt(sessionId: string, incomingMessage: string): string;
     search(query: string, mode?: string): Promise<any>;
     negotiate(address: string, constraints: ConstraintVector): Promise<string>;
@@ -81,7 +79,6 @@ export declare class ClinchCore extends EventEmitter {
 }
 export interface SellerRecord {
     agent_id: string;
-    display_name: string;
     endpoint: string;
     supported_modes: string[];
     categories: string[];
@@ -90,12 +87,12 @@ export interface SellerRecord {
 export declare class ClinchSeller extends EventEmitter {
     private config;
     private cachedRegistryUrl;
-    sellerAuthToken: string | null;
     private identityPrivKey;
     identityPubKey: string;
-    constructor(config?: ClinchConfig);
-    authenticate(authToken: string): Promise<void>;
+    constructor(config?: ClinchConfig & {
+        privateKeyHex?: string;
+    });
+    private resolveRegistry;
     registerEndpoint(record: SellerRecord): Promise<any>;
-    verifyBuyerSignature(payload: any, signatureHex: string, buyerSessionPubKeyHex: string): boolean;
-    private signData;
+    verifyBuyerSignature(payload: any, signatureHex: string, buyerPubKeyHex: string): boolean;
 }

package/dist/index.js

@@ -49,6 +49,9 @@ 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('');
 }
+function fromHex(hex) {
+    return new Uint8Array(hex.match(/.{1,2}/g).map(byte => parseInt(byte, 16)));
+}
 // ============================================================================
 // THE CLINCH CORE LIBRARY (Buyer)
 // ============================================================================
@@ -63,15 +66,10 @@ class ClinchCore extends events_1.EventEmitter {
     identityPubKey;
     activeSessions = new Map();
     ws = null;
-    // Sandbox Engine
+    // Sandbox Engine Base (Model/Context are global, Sequences are per-session)
     isSandboxMode = false;
-    sandboxContext = null;
-    sandboxSequence = null;
-    sandboxSession = null;
+    sandboxModelContext = null;
     sandboxMaxTurns = 6;
-    currentTurn = 0;
-    lastKnownPrice = 0;
-    activeNegotiationId = null;
     constructor(config = {}) {
         super();
         this.config = { timeoutMs: 5000, ...config };
@@ -90,8 +88,6 @@ class ClinchCore extends events_1.EventEmitter {
                 this.emit('log', `🟢 [State] ONLINE & IDLE`);
             else if (this.status === 'ERROR')
                 this.emit('log', `🔴 [State] ERROR`);
-            else if (this.status === 'NEGOTIATING')
-                this.emit('log', `⚡ [State] NEGOTIATING (Turn ${this.currentTurn})`);
             else
                 this.emit('log', `🟡 [State] ${this.status}`);
         }
@@ -229,17 +225,51 @@ class ClinchCore extends events_1.EventEmitter {
         }
     }
     // --------------------------------------------------------------------------
+    // SESSION STATE MANAGEMENT (For Enterprise Horizontal Scaling & Reconnects)
+    // --------------------------------------------------------------------------
+    exportSessionState(sessionId) {
+        const session = this.activeSessions.get(sessionId);
+        if (!session)
+            throw new Error("Session not found");
+        const exportable = {
+            sessionId: session.sessionId,
+            sellerId: session.sellerId,
+            status: session.status,
+            exitTokenHash: session.exitTokenHash,
+            constraints: session.constraints,
+            currentTurn: session.currentTurn,
+            lastKnownPrice: session.lastKnownPrice,
+            ephemeralSecretKeyHex: toHex(session.keyPair.secretKey)
+        };
+        return JSON.stringify(exportable);
+    }
+    importSessionState(serializedData) {
+        const data = JSON.parse(serializedData);
+        const secretKey = fromHex(data.ephemeralSecretKeyHex);
+        const keyPair = tweetnacl_1.default.sign.keyPair.fromSecretKey(secretKey);
+        this.activeSessions.set(data.sessionId, {
+            sessionId: data.sessionId,
+            sellerId: data.sellerId,
+            status: data.status,
+            exitTokenHash: data.exitTokenHash,
+            constraints: data.constraints,
+            currentTurn: data.currentTurn,
+            lastKnownPrice: data.lastKnownPrice,
+            keyPair: keyPair
+        });
+        this.emit('log', `[State] Rehydrated session ${data.sessionId} pointing at ${data.sellerId}`);
+    }
+    getSession(sessionId) {
+        return this.activeSessions.get(sessionId);
+    }
+    // --------------------------------------------------------------------------
     // UNIVERSAL PROMPT BUILDER
     // --------------------------------------------------------------------------
-    /**
-     * Generates a universally formatted System Prompt for external LLMs (Claude, OpenAI, Gemini).
-     * Developers can pass this string directly to their AI to ensure protocol-compliant negotiation.
-     */
     buildAgentPrompt(sessionId, incomingMessage) {
         const session = this.activeSessions.get(sessionId);
         if (!session)
             throw new Error("Cannot build prompt: Session not found.");
-        const gap = this.lastKnownPrice - session.constraints.max_budget;
+        const gap = session.lastKnownPrice - session.constraints.max_budget;
         const gapText = gap > 0 ? `-$${gap} (Over budget)` : `+$${Math.abs(gap)} (Under budget)`;
         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.
@@ -248,8 +278,8 @@ NEGOTIATION STATE:
 - Item: ${session.constraints.item}
 - Category: ${session.constraints.category || 'General'}
 - Your absolute max budget: $${session.constraints.max_budget}
-- Current turn: ${this.currentTurn}
-- Last seller price: $${this.lastKnownPrice}
+- Current turn: ${session.currentTurn}
+- Last seller price: $${session.lastKnownPrice}
 - Gap to budget: ${gapText}
 
 SELLER'S LATEST MESSAGE:
@@ -302,24 +332,31 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             sellerId: parsed.domain,
             keyPair: ephemeralKeys,
             status: 'ACTIVE',
-            constraints
+            constraints,
+            currentTurn: 1,
+            lastKnownPrice: 0
         });
-        this.activeNegotiationId = response.session_id;
-        this.currentTurn = 1;
         this.setStatus('NEGOTIATING');
+        this.emit('session_started', { sessionId: response.session_id, sellerId: parsed.domain });
         return response.session_id;
     }
     async sendCounter(sessionId, price, reason) {
         const session = this.activeSessions.get(sessionId);
         if (!session)
             throw new Error("Active session not found");
-        const payload = { session_id: sessionId, turn: this.currentTurn, price, reason };
+        const payload = { session_id: sessionId, turn: session.currentTurn, price, reason };
         const buyer_sig = toHex(tweetnacl_1.default.sign.detached(new TextEncoder().encode(JSON.stringify(payload)), session.keyPair.secretKey));
-        await this.networkRequest(`/api/route/${session.sellerId}/counter`, {
+        const response = await this.networkRequest(`/api/route/${session.sellerId}/counter`, {
             method: 'POST',
             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;
+            this.emit('session_closed', { sessionId, outcome: 'deal', finalPrice: session.lastKnownPrice });
+        }
     }
     async exitSession(sessionId) {
         const session = this.activeSessions.get(sessionId);
@@ -350,13 +387,14 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         this.emit('log', "⚙️ [Sandbox] Auto-Negotiation engine bound and active.");
     }
     async setupSandbox(config = {}) {
+        if (this.sandboxModelContext)
+            return; // Already initialized
         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",
             modelPath: "./qwen2.5-1.5b-instruct-q4_k_m.gguf",
             ...config
         };
-        // DYNAMIC IMPORTS: Won't break Webpack/Metro unless sandbox() is actually called!
         let nodeLlama;
         try {
             nodeLlama = await Promise.resolve().then(() => __importStar(require('node-llama-cpp')));
@@ -374,7 +412,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             this.emit('log', `[Sandbox] Downloading Qwen 1.5B Q4_K_M (1.1GB)...`);
             const { pipeline } = await Promise.resolve().then(() => __importStar(require('stream/promises')));
             const { Readable } = await Promise.resolve().then(() => __importStar(require('stream')));
-            // @ts-ignore
             const response = await fetch(settings.modelUrl);
             if (!response.ok)
                 throw new Error("Fetch failed: " + response.statusText);
@@ -384,7 +421,7 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         }
         const llama = await nodeLlama.getLlama();
         const model = await llama.loadModel({ modelPath: resolvedPath });
-        this.sandboxContext = await model.createContext({
+        this.sandboxModelContext = await model.createContext({
             contextSize: 2048,
             threads: Math.min(4, Math.max(1, os.cpus().length - 1)),
             batchSize: 512
@@ -392,46 +429,60 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
     }
     async handleAutomaticSandboxTurn(sessionId, payload) {
         const session = this.activeSessions.get(sessionId);
-        if (!session)
+        if (!session || session.status !== 'ACTIVE')
             return;
-        this.currentTurn++;
+        session.currentTurn++;
         this.setStatus('NEGOTIATING');
+        this.emit('log', `⚡ [Sandbox] Analyzing Turn ${session.currentTurn} for ${sessionId}`);
         const incomingPrice = this.extractPrice(payload.message || JSON.stringify(payload), 'Counter');
         if (incomingPrice !== null)
-            this.lastKnownPrice = incomingPrice;
-        if (this.lastKnownPrice <= session.constraints.max_budget) {
-            this.setStatus('CONVERGED');
-            this.activeSessions.delete(sessionId);
+            session.lastKnownPrice = incomingPrice;
+        if (session.lastKnownPrice > 0 && session.lastKnownPrice <= session.constraints.max_budget) {
+            this.emit('log', `🎉 [Sandbox] Seller met budget conditions! Closing deal.`);
+            await this.sendCounter(sessionId, session.lastKnownPrice, "I accept this offer.");
             return;
         }
-        if (this.currentTurn > this.sandboxMaxTurns) {
+        if (session.currentTurn > this.sandboxMaxTurns) {
             this.setStatus('STALEMATE');
+            this.emit('log', `🛑 [Sandbox] Max turns reached. Exiting.`);
             await this.exitSession(sessionId);
             return;
         }
-        const modelResponse = await this.sandboxEvaluate(session, payload.message || `The price is $${this.lastKnownPrice}`);
-        const parsedOffer = this.extractPrice(modelResponse, 'Offer');
-        const reasonLine = modelResponse.split('\n').find(l => l.startsWith('Reason:'));
-        const reason = reasonLine ? reasonLine.replace('Reason:', '').trim() : "Suggesting a fair counter-offer.";
+        const modelResponse = await this.sandboxEvaluate(session, payload.message || `The price is $${session.lastKnownPrice}`);
+        const parsedOffer = this.extractPrice(modelResponse, 'Offer') || this.extractPrice(modelResponse, 'price');
+        let reason = "Suggesting a fair counter-offer.";
+        try {
+            const parsedJson = JSON.parse(modelResponse.replace(/```json|```/g, "").trim());
+            if (parsedJson.message)
+                reason = parsedJson.message;
+            else if (parsedJson.reason)
+                reason = parsedJson.reason;
+        }
+        catch (e) { }
         if (parsedOffer !== null) {
             const finalOffer = Math.min(parsedOffer, session.constraints.max_budget);
             await this.sendCounter(sessionId, finalOffer, reason);
         }
+        else {
+            this.emit('log', `⚠️ [Sandbox] Failed to parse offer. Generating safe counter.`);
+            await this.sendCounter(sessionId, session.lastKnownPrice * 0.9, "Can you do slightly better?");
+        }
     }
     async sandboxEvaluate(session, incomingOffer) {
         const { LlamaChatSession, ChatMLChatWrapper } = await Promise.resolve().then(() => __importStar(require('node-llama-cpp')));
         const systemPrompt = this.buildAgentPrompt(session.sessionId, incomingOffer);
-        if (this.sandboxSequence)
-            this.sandboxSequence.dispose();
-        this.sandboxSequence = this.sandboxContext.getSequence();
-        this.sandboxSession = new LlamaChatSession({
-            contextSequence: this.sandboxSequence,
-            systemPrompt: systemPrompt,
-            chatWrapper: new ChatMLChatWrapper()
-        });
+        // State Isolation: Bind sequence to the session, not the global class!
+        if (!session.sandboxSequence) {
+            session.sandboxSequence = this.sandboxModelContext.getSequence();
+            session.sandboxSession = new LlamaChatSession({
+                contextSequence: session.sandboxSequence,
+                systemPrompt: systemPrompt,
+                chatWrapper: new ChatMLChatWrapper()
+            });
+        }
         let responseText = "";
-        await this.sandboxSession.prompt(incomingOffer, {
-            maxTokens: 80,
+        await session.sandboxSession.prompt(incomingOffer, {
+            maxTokens: 120,
             onTextChunk: (chunk) => { responseText += chunk; }
         });
         return responseText;
@@ -449,10 +500,14 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         return fallbackMatch ? parseFloat(fallbackMatch[1]) : null;
     }
     parseAddress(address) {
-        const parts = address.split('.');
-        if (parts.length < 2)
-            throw new Error("Invalid Address Format");
-        return { mode: parts[0], domain: parts.slice(1).join('.').toLowerCase(), route: '/' };
+        if (!address.includes('.'))
+            throw new Error("Invalid Address Format. Expected MODE.domain (e.g. ANP/C.amazon.anp)");
+        const firstDotIdx = address.indexOf('.');
+        const mode = address.substring(0, firstDotIdx);
+        const domain = address.substring(firstDotIdx + 1).toLowerCase();
+        if (!mode.startsWith("ANP/"))
+            throw new Error(`Invalid protocol mode '${mode}'. Must start with 'ANP/'`);
+        return { mode, domain, route: '/' };
     }
     async solvePoW(nonce, difficultyBits) {
         let counter = 0;
@@ -485,60 +540,65 @@ exports.ClinchCore = ClinchCore;
 class ClinchSeller extends events_1.EventEmitter {
     config;
     cachedRegistryUrl = null;
-    sellerAuthToken = null;
     identityPrivKey;
     identityPubKey;
     constructor(config = {}) {
         super();
-        this.config = { timeoutMs: 5000, ...config };
-        const keyPair = tweetnacl_1.default.sign.keyPair();
-        this.identityPrivKey = keyPair.secretKey;
-        this.identityPubKey = toHex(keyPair.publicKey);
-        if (this.config.registryUrl)
+        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)}...`);
+        }
+        else {
+            const kp = tweetnacl_1.default.sign.keyPair();
+            this.identityPrivKey = kp.secretKey;
+            this.identityPubKey = toHex(kp.publicKey);
+            console.warn('[Seller] ⚠️  No privateKeyHex provided — using ephemeral key. Registry will reject updates unless this key is pre-registered.');
+        }
+        if (this.config.registryUrl) {
             this.cachedRegistryUrl = this.config.registryUrl;
-    }
-    async authenticate(authToken) {
-        this.sellerAuthToken = authToken;
-        if (!this.cachedRegistryUrl) {
-            const res = await fetch(FIREBASE_CONFIG_URL);
-            const config = JSON.parse(await res.text());
-            this.cachedRegistryUrl = config.registry_nodes[PROTOCOL_VERSION];
         }
     }
+    async resolveRegistry() {
+        if (this.cachedRegistryUrl)
+            return this.cachedRegistryUrl;
+        const res = await fetch(FIREBASE_CONFIG_URL);
+        const cfg = JSON.parse(await res.text());
+        this.cachedRegistryUrl = cfg.registry_nodes[PROTOCOL_VERSION];
+        return this.cachedRegistryUrl;
+    }
     async registerEndpoint(record) {
-        if (!this.sellerAuthToken)
-            throw new Error("Must call authenticate() first.");
-        const payload = {
-            ...record,
-            public_key: this.identityPubKey,
-            record_sig: this.signData(record)
-        };
-        const res = await fetch(`${this.cachedRegistryUrl}/api/dashboard/sellers/register`, {
+        const registry = await this.resolveRegistry();
+        const payload = { ...record, timestamp: Date.now() };
+        const msgUint8 = new TextEncoder().encode(JSON.stringify(payload));
+        const signature = toHex(tweetnacl_1.default.sign.detached(msgUint8, this.identityPrivKey));
+        const res = await fetch(`${registry}/api/sellers/update-endpoint`, {
             method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${this.sellerAuthToken}`
-            },
-            body: JSON.stringify(payload)
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                payload,
+                public_key: this.identityPubKey,
+                signature
+            })
         });
         if (!res.ok)
-            throw new Error(`Registration failed: ${await res.text()}`);
-        return await res.json();
+            throw new Error(`Endpoint registration failed: ${await res.text()}`);
+        const data = await res.json();
+        this.emit('log', `[Seller] Registered: ${record.agent_id} → ${record.endpoint}`);
+        return data;
     }
-    verifyBuyerSignature(payload, signatureHex, buyerSessionPubKeyHex) {
+    verifyBuyerSignature(payload, signatureHex, buyerPubKeyHex) {
         try {
-            const msgUint8 = new TextEncoder().encode(JSON.stringify(payload));
-            const sigUint8 = new Uint8Array(signatureHex.match(/.{1,2}/g).map(byte => parseInt(byte, 16)));
-            const pubKeyUint8 = new Uint8Array(buyerSessionPubKeyHex.match(/.{1,2}/g).map(byte => parseInt(byte, 16)));
-            return tweetnacl_1.default.sign.detached.verify(msgUint8, sigUint8, pubKeyUint8);
+            const msg = new TextEncoder().encode(JSON.stringify(payload));
+            const sig = fromHex(signatureHex);
+            const pubKey = fromHex(buyerPubKeyHex);
+            return tweetnacl_1.default.sign.detached.verify(msg, sig, pubKey);
         }
-        catch (e) {
+        catch {
             return false;
         }
     }
-    signData(data) {
-        const msgUint8 = new TextEncoder().encode(JSON.stringify(data));
-        return toHex(tweetnacl_1.default.sign.detached(msgUint8, this.identityPrivKey));
-    }
 }
 exports.ClinchSeller = ClinchSeller;

package/package.json

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

package/src/index.ts

@@ -13,18 +13,22 @@ function toHex(arr: Uint8Array | number[]): string {
     return Array.from(arr).map(b => b.toString(16).padStart(2, '0')).join('');
 }
 
+function fromHex(hex: string): Uint8Array {
+    return new Uint8Array(hex.match(/.{1,2}/g)!.map(byte => parseInt(byte, 16)));
+}
+
 // ============================================================================
 // TYPES & INTERFACES
 // ============================================================================
 export type CoreStatus =
     | 'OFFLINE'
     | 'CONNECTING'
-    | 'IDLE'            
+    | 'IDLE'
     | 'RECONNECTING'
     | 'ERROR'
-    | 'NEGOTIATING'     
-    | 'CONVERGED'       
-    | 'STALEMATE';      
+    | 'NEGOTIATING'
+    | 'CONVERGED'
+    | 'STALEMATE';
 
 export interface ParsedAddress {
     mode: string;
@@ -51,6 +55,14 @@ export interface SessionState {
     status: 'ACTIVE' | 'EXITED' | 'CLOSED';
     exitTokenHash?: string;
     constraints: ConstraintVector;
+    
+    // Isolated State Tracking (Crucial for concurrency)
+    currentTurn: number;
+    lastKnownPrice: number;
+
+    // Local LLM Context Tracking
+    sandboxSequence?: any; 
+    sandboxSession?: any;
 }
 
 export interface SandboxConfig {
@@ -83,17 +95,11 @@ export class ClinchCore extends EventEmitter {
     private activeSessions = new Map<string, SessionState>();
     private ws: WebSocket | null = null;
 
-    // Sandbox Engine
+    // Sandbox Engine Base (Model/Context are global, Sequences are per-session)
     private isSandboxMode = false;
-    private sandboxContext: any = null;
-    private sandboxSequence: any = null;
-    private sandboxSession: any = null;
+    private sandboxModelContext: any = null;
     private sandboxMaxTurns = 6;
 
-    public currentTurn = 0;
-    public lastKnownPrice = 0;
-    public activeNegotiationId: string | null = null;
-
     constructor(config: ClinchConfig = {}) {
         super();
         this.config = { timeoutMs: 5000, ...config };
@@ -114,7 +120,6 @@ export class ClinchCore extends EventEmitter {
 
             if (this.status === 'IDLE') this.emit('log', `🟢 [State] ONLINE & IDLE`);
             else if (this.status === 'ERROR') this.emit('log', `🔴 [State] ERROR`);
-            else if (this.status === 'NEGOTIATING') this.emit('log', `⚡ [State] NEGOTIATING (Turn ${this.currentTurn})`);
             else this.emit('log', `🟡 [State] ${this.status}`);
         }
     }
@@ -256,18 +261,59 @@ 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");
+
+        const exportable = {
+            sessionId: session.sessionId,
+            sellerId: session.sellerId,
+            status: session.status,
+            exitTokenHash: session.exitTokenHash,
+            constraints: session.constraints,
+            currentTurn: session.currentTurn,
+            lastKnownPrice: session.lastKnownPrice,
+            ephemeralSecretKeyHex: toHex(session.keyPair.secretKey)
+        };
+
+        return JSON.stringify(exportable);
+    }
+
+    public importSessionState(serializedData: string): void {
+        const data = JSON.parse(serializedData);
+        
+        const secretKey = fromHex(data.ephemeralSecretKeyHex);
+        const keyPair = nacl.sign.keyPair.fromSecretKey(secretKey);
+
+        this.activeSessions.set(data.sessionId, {
+            sessionId: data.sessionId,
+            sellerId: data.sellerId,
+            status: data.status,
+            exitTokenHash: data.exitTokenHash,
+            constraints: data.constraints,
+            currentTurn: data.currentTurn,
+            lastKnownPrice: data.lastKnownPrice,
+            keyPair: keyPair
+        });
+
+        this.emit('log', `[State] Rehydrated session ${data.sessionId} pointing at ${data.sellerId}`);
+    }
+
+    public getSession(sessionId: string): SessionState | undefined {
+        return this.activeSessions.get(sessionId);
+    }
+
     // --------------------------------------------------------------------------
     // UNIVERSAL PROMPT BUILDER
     // --------------------------------------------------------------------------
-    /**
-     * Generates a universally formatted System Prompt for external LLMs (Claude, OpenAI, Gemini).
-     * Developers can pass this string directly to their AI to ensure protocol-compliant negotiation.
-     */
     public buildAgentPrompt(sessionId: string, incomingMessage: string): string {
         const session = this.activeSessions.get(sessionId);
         if (!session) throw new Error("Cannot build prompt: Session not found.");
 
-        const gap = this.lastKnownPrice - session.constraints.max_budget;
+        const gap = session.lastKnownPrice - session.constraints.max_budget;
         const gapText = gap > 0 ? `-$${gap} (Over budget)` : `+$${Math.abs(gap)} (Under budget)`;
 
         return `You are a professional AI purchasing agent negotiating via the Clinch Protocol.
@@ -277,8 +323,8 @@ NEGOTIATION STATE:
 - Item: ${session.constraints.item}
 - Category: ${session.constraints.category || 'General'}
 - Your absolute max budget: $${session.constraints.max_budget}
-- Current turn: ${this.currentTurn}
-- Last seller price: $${this.lastKnownPrice}
+- Current turn: ${session.currentTurn}
+- Last seller price: $${session.lastKnownPrice}
 - Gap to budget: ${gapText}
 
 SELLER'S LATEST MESSAGE:
@@ -337,12 +383,13 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             sellerId: parsed.domain,
             keyPair: ephemeralKeys,
             status: 'ACTIVE',
-            constraints
+            constraints,
+            currentTurn: 1,
+            lastKnownPrice: 0
         });
 
-        this.activeNegotiationId = response.session_id;
-        this.currentTurn = 1;
         this.setStatus('NEGOTIATING');
+        this.emit('session_started', { sessionId: response.session_id, sellerId: parsed.domain });
         return response.session_id;
     }
 
@@ -350,17 +397,24 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         const session = this.activeSessions.get(sessionId);
         if (!session) throw new Error("Active session not found");
 
-        const payload = { session_id: sessionId, turn: this.currentTurn, price, reason };
+        const payload = { session_id: sessionId, turn: session.currentTurn, price, reason };
         const buyer_sig = toHex(nacl.sign.detached(
             new TextEncoder().encode(JSON.stringify(payload)),
             session.keyPair.secretKey
         ));
 
-        await this.networkRequest(`/api/route/${session.sellerId}/counter`, {
+        const response = await this.networkRequest(`/api/route/${session.sellerId}/counter`, {
             method: 'POST',
             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;
+            this.emit('session_closed', { sessionId, outcome: 'deal', finalPrice: session.lastKnownPrice });
+        }
     }
 
     async exitSession(sessionId: string): Promise<string> {
@@ -396,6 +450,8 @@ 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
+
         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",
@@ -403,7 +459,6 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             ...config
         };
 
-        // DYNAMIC IMPORTS: Won't break Webpack/Metro unless sandbox() is actually called!
         let nodeLlama;
         try { nodeLlama = await import('node-llama-cpp'); }
         catch (e) { throw new Error("Sandbox requires 'node-llama-cpp'. Run: npm install node-llama-cpp"); }
@@ -419,8 +474,7 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
             this.emit('log', `[Sandbox] Downloading Qwen 1.5B Q4_K_M (1.1GB)...`);
             const { pipeline } = await import('stream/promises');
             const { Readable } = await import('stream');
-            
-            // @ts-ignore
+
             const response = await fetch(settings.modelUrl);
             if (!response.ok) throw new Error("Fetch failed: " + response.statusText);
 
@@ -432,7 +486,7 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         const llama = await nodeLlama.getLlama();
         const model = await llama.loadModel({ modelPath: resolvedPath });
 
-        this.sandboxContext = await model.createContext({
+        this.sandboxModelContext = await model.createContext({
             contextSize: 2048,
             threads: Math.min(4, Math.max(1, os.cpus().length - 1)),
             batchSize: 512
@@ -441,34 +495,44 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
 
     private async handleAutomaticSandboxTurn(sessionId: string, payload: any) {
         const session = this.activeSessions.get(sessionId);
-        if (!session) return;
+        if (!session || session.status !== 'ACTIVE') return;
 
-        this.currentTurn++;
+        session.currentTurn++;
         this.setStatus('NEGOTIATING');
+        this.emit('log', `⚡ [Sandbox] Analyzing Turn ${session.currentTurn} for ${sessionId}`);
 
         const incomingPrice = this.extractPrice(payload.message || JSON.stringify(payload), 'Counter');
-        if (incomingPrice !== null) this.lastKnownPrice = incomingPrice;
+        if (incomingPrice !== null) session.lastKnownPrice = incomingPrice;
 
-        if (this.lastKnownPrice <= session.constraints.max_budget) {
-            this.setStatus('CONVERGED');
-            this.activeSessions.delete(sessionId);
+        if (session.lastKnownPrice > 0 && session.lastKnownPrice <= session.constraints.max_budget) {
+            this.emit('log', `🎉 [Sandbox] Seller met budget conditions! Closing deal.`);
+            await this.sendCounter(sessionId, session.lastKnownPrice, "I accept this offer.");
             return;
         }
 
-        if (this.currentTurn > this.sandboxMaxTurns) {
+        if (session.currentTurn > this.sandboxMaxTurns) {
             this.setStatus('STALEMATE');
+            this.emit('log', `🛑 [Sandbox] Max turns reached. Exiting.`);
             await this.exitSession(sessionId);
             return;
         }
 
-        const modelResponse = await this.sandboxEvaluate(session, payload.message || `The price is $${this.lastKnownPrice}`);
-        const parsedOffer = this.extractPrice(modelResponse, 'Offer');
-        const reasonLine = modelResponse.split('\n').find(l => l.startsWith('Reason:'));
-        const reason = reasonLine ? reasonLine.replace('Reason:', '').trim() : "Suggesting a fair counter-offer.";
+        const modelResponse = await this.sandboxEvaluate(session, payload.message || `The price is $${session.lastKnownPrice}`);
+        const parsedOffer = this.extractPrice(modelResponse, 'Offer') || this.extractPrice(modelResponse, 'price');
+        
+        let reason = "Suggesting a fair counter-offer.";
+        try {
+            const parsedJson = JSON.parse(modelResponse.replace(/```json|```/g, "").trim());
+            if (parsedJson.message) reason = parsedJson.message;
+            else if (parsedJson.reason) reason = parsedJson.reason;
+        } catch(e) {}
 
         if (parsedOffer !== null) {
             const finalOffer = Math.min(parsedOffer, session.constraints.max_budget);
             await this.sendCounter(sessionId, finalOffer, reason);
+        } else {
+            this.emit('log', `⚠️ [Sandbox] Failed to parse offer. Generating safe counter.`);
+            await this.sendCounter(sessionId, session.lastKnownPrice * 0.9, "Can you do slightly better?");
         }
     }
 
@@ -477,18 +541,19 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
 
         const systemPrompt = this.buildAgentPrompt(session.sessionId, incomingOffer);
 
-        if (this.sandboxSequence) this.sandboxSequence.dispose();
-        this.sandboxSequence = this.sandboxContext.getSequence();
-
-        this.sandboxSession = new LlamaChatSession({
-            contextSequence: this.sandboxSequence,
-            systemPrompt: systemPrompt,
-            chatWrapper: new ChatMLChatWrapper()
-        });
+        // State Isolation: Bind sequence to the session, not the global class!
+        if (!session.sandboxSequence) {
+            session.sandboxSequence = this.sandboxModelContext.getSequence();
+            session.sandboxSession = new LlamaChatSession({
+                contextSequence: session.sandboxSequence,
+                systemPrompt: systemPrompt,
+                chatWrapper: new ChatMLChatWrapper()
+            });
+        }
 
         let responseText = "";
-        await this.sandboxSession.prompt(incomingOffer, {
-            maxTokens: 80,
+        await session.sandboxSession.prompt(incomingOffer, {
+            maxTokens: 120,
             onTextChunk: (chunk: string) => { responseText += chunk; }
         });
 
@@ -502,16 +567,22 @@ You MUST respond ONLY in valid JSON matching this exact schema. Do not include m
         const regex = new RegExp(`${prefix}\\s*\\:?\\s*\\$?(\\d+(?:\\.\\d{2})?)`, 'i');
         const match = text.match(regex);
         if (match) return parseFloat(match[1]);
-        
+
         const fallbackRegex = /"price"\s*:\s*(\d+(?:\.\d{2})?)/i;
         const fallbackMatch = text.match(fallbackRegex);
         return fallbackMatch ? parseFloat(fallbackMatch[1]) : null;
     }
 
     public parseAddress(address: string): ParsedAddress {
-        const parts = address.split('.');
-        if (parts.length < 2) throw new Error("Invalid Address Format");
-        return { mode: parts[0], domain: parts.slice(1).join('.').toLowerCase(), route: '/' };
+        if (!address.includes('.')) throw new Error("Invalid Address Format. Expected MODE.domain (e.g. ANP/C.amazon.anp)");
+        
+        const firstDotIdx = address.indexOf('.');
+        const mode = address.substring(0, firstDotIdx);
+        const domain = address.substring(firstDotIdx + 1).toLowerCase();
+        
+        if (!mode.startsWith("ANP/")) throw new Error(`Invalid protocol mode '${mode}'. Must start with 'ANP/'`);
+
+        return { mode, domain, route: '/' };
     }
 
     private async solvePoW(nonce: string, difficultyBits: number): Promise<string> {
@@ -542,71 +613,79 @@ 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;
-    display_name: string;
-    endpoint: string;
-    supported_modes: string[];
-    categories: string[];
-    capabilities: string[];
+  agent_id:        string;
+  endpoint:        string;
+  supported_modes: string[];
+  categories:      string[];
+  capabilities:    string[];
 }
 
 export class ClinchSeller extends EventEmitter {
-    private config: ClinchConfig;
-    private cachedRegistryUrl: string | null = null;
-    public sellerAuthToken: string | null = null;
-    private identityPrivKey: Uint8Array;
-    public identityPubKey: string;
-
-    constructor(config: ClinchConfig = {}) {
-        super();
-        this.config = { timeoutMs: 5000, ...config };
-        const keyPair = nacl.sign.keyPair();
-        this.identityPrivKey = keyPair.secretKey;
-        this.identityPubKey = toHex(keyPair.publicKey);
-        if (this.config.registryUrl) this.cachedRegistryUrl = this.config.registryUrl;
-    }
-
-    async authenticate(authToken: string): Promise<void> {
-        this.sellerAuthToken = authToken;
-        if (!this.cachedRegistryUrl) {
-            const res = await fetch(FIREBASE_CONFIG_URL);
-            const config = JSON.parse(await res.text());
-            this.cachedRegistryUrl = config.registry_nodes[PROTOCOL_VERSION];
-        }
-    }
-
-    async registerEndpoint(record: SellerRecord): Promise<any> {
-        if (!this.sellerAuthToken) throw new Error("Must call authenticate() first.");
-        const payload = {
-            ...record,
-            public_key: this.identityPubKey,
-            record_sig: this.signData(record)
-        };
-        const res = await fetch(`${this.cachedRegistryUrl}/api/dashboard/sellers/register`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'Authorization': `Bearer ${this.sellerAuthToken}`
-            },
-            body: JSON.stringify(payload)
-        });
-        if (!res.ok) throw new Error(`Registration failed: ${await res.text()}`);
-        return await res.json();
+  private config:           ClinchConfig;
+  private cachedRegistryUrl: string | null = null;
+  private identityPrivKey:  Uint8Array;
+  public  identityPubKey:   string;
+
+  constructor(config: ClinchConfig & { privateKeyHex?: string } = {}) {
+    super();
+    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)}...`);
+    } else {
+      const kp = nacl.sign.keyPair();
+      this.identityPrivKey = kp.secretKey;
+      this.identityPubKey  = toHex(kp.publicKey);
+      console.warn('[Seller] ⚠️  No privateKeyHex provided — using ephemeral key. Registry will reject updates unless this key is pre-registered.');
     }
 
-    verifyBuyerSignature(payload: any, signatureHex: string, buyerSessionPubKeyHex: string): boolean {
-        try {
-            const msgUint8 = new TextEncoder().encode(JSON.stringify(payload));
-            const sigUint8 = new Uint8Array(signatureHex.match(/.{1,2}/g)!.map(byte => parseInt(byte, 16)));
-            const pubKeyUint8 = new Uint8Array(buyerSessionPubKeyHex.match(/.{1,2}/g)!.map(byte => parseInt(byte, 16)));
-            return nacl.sign.detached.verify(msgUint8, sigUint8, pubKeyUint8);
-        } catch (e) {
-            return false;
-        }
+    if (this.config.registryUrl) {
+      this.cachedRegistryUrl = this.config.registryUrl;
     }
-
-    private signData(data: any): string {
-        const msgUint8 = new TextEncoder().encode(JSON.stringify(data));
-        return toHex(nacl.sign.detached(msgUint8, this.identityPrivKey));
+  }
+
+  private async resolveRegistry(): Promise<string> {
+    if (this.cachedRegistryUrl) return this.cachedRegistryUrl;
+    const res = await fetch(FIREBASE_CONFIG_URL);
+    const cfg = JSON.parse(await res.text());
+    this.cachedRegistryUrl = cfg.registry_nodes[PROTOCOL_VERSION];
+    return this.cachedRegistryUrl!;
+  }
+
+  async registerEndpoint(record: SellerRecord): Promise<any> {
+    const registry = await this.resolveRegistry();
+
+    const payload = { ...record, timestamp: Date.now() };
+    const msgUint8 = new TextEncoder().encode(JSON.stringify(payload));
+    const signature = toHex(nacl.sign.detached(msgUint8, this.identityPrivKey));
+
+    const res = await fetch(`${registry}/api/sellers/update-endpoint`, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body:    JSON.stringify({
+        payload,
+        public_key: this.identityPubKey,
+        signature
+      })
+    });
+
+    if (!res.ok) throw new Error(`Endpoint registration failed: ${await res.text()}`);
+    const data = await res.json();
+    this.emit('log', `[Seller] Registered: ${record.agent_id} → ${record.endpoint}`);
+    return data;
+  }
+
+  verifyBuyerSignature(payload: any, signatureHex: string, buyerPubKeyHex: string): boolean {
+    try {
+      const msg    = new TextEncoder().encode(JSON.stringify(payload));
+      const sig    = fromHex(signatureHex);
+      const pubKey = fromHex(buyerPubKeyHex);
+      return nacl.sign.detached.verify(msg, sig, pubKey);
+    } catch {
+      return false;
     }
+  }
 }