agent-clinch 0.1.0 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@
 
 The Clinch CLI is the official reference implementation of a Clinch Protocol buyer agent. It allows you to discover sellers, negotiate deals interactively, or dispatch an autonomous local AI agent ("Agent Q") to haggle on your behalf—right from your terminal.
 
-By keeping the execution edge-first, all cryptographic keys, session transcripts, downloaded models, and deal artifacts are stored strictly on your local machine.
+By keeping the execution edge-first, all cryptographic keys, session transcripts, downloaded models, and deal artifacts are stored strictly on your local machine. With robust state serialization, you can even close your terminal and resume dropped or asynchronous negotiations later.
 
 ---
 
@@ -44,7 +44,7 @@ The easiest way to use Clinch is to simply type:
 clinch negotiate
 ```
 
-Instead of memorizing flags and seller domains, the CLI boots a local LLM to ask what you want in plain English. 
+Instead of memorizing flags and routing prefixes, the CLI boots a local LLM to ask what you want in plain English.
 
 ```text
 💬 Clinch Onboarding Wizard — Tell me what you're looking for.
@@ -63,14 +63,14 @@ Instead of memorizing flags and seller domains, the CLI boots a local LLM to ask
   - Must Haves:  warranty, fast shipping
 ```
 
-Agent Q parses your natural language into a strict JSON `ConstraintVector`, queries the Clinch Registry to find matching sellers, and lets you select your target. It then seamlessly transitions into the negotiation phase.
+Agent Q parses your natural language into a strict JSON constraint vector, queries the Clinch Registry to find matching sellers, and lets you select your target. It then seamlessly transitions into the negotiation phase.
 
 ### 3. Explicit Negotiation (Manual or Auto Mode)
-If you already know the seller's address and want to bypass the wizard, you can pass arguments directly:
+If you already know the seller's address and want to bypass the wizard, you can pass arguments directly. **Note: Clinch Protocol requires strict routing prefixes (e.g., `ANP/C.`) on all addresses.**
 
 **Manual Mode:** Open an interactive terminal where you manually input counter-offers.
 ```bash
-clinch negotiate ANP/A.amazon.anp --category "electronics" --item "Ninja Blender" --budget 85.00
+clinch negotiate ANP/C.amazon.anp --budget 85.00
 ```
 *   Type a number (e.g., `45.50`) to send a counter-offer.
 *   Type `accept` to seal the deal.
@@ -78,7 +78,20 @@ clinch negotiate ANP/A.amazon.anp --category "electronics" --item "Ninja Blender
 
 **Auto Mode:** Add the `--auto` flag to hand control over to the local LLM Sandbox (Qwen 2.5 1.5B). The agent will evaluate the seller's offers and negotiate autonomously up to your strict max budget.
 ```bash
-clinch negotiate ANP/A.cloudflare.anp --category "domain" --item "my-startup.io" --budget 50.00 --auto
+clinch negotiate ANP/C.cloudflare.anp --budget 50.00 --auto
+```
+
+### 4. Resuming Asynchronous Sessions
+If you exit a negotiation before it concludes, or a seller places your offer in an asynchronous callback queue, the CLI automatically saves your exact session state and cryptographic session keys to disk.
+
+List your saved sessions:
+```bash
+clinch sessions
+```
+
+Resume a specific session and listen for webhooks/callbacks:
+```bash
+clinch resume sess_a1b2c3d4 --auto
 ```
 
 ---
@@ -87,43 +100,25 @@ clinch negotiate ANP/A.cloudflare.anp --category "domain" --item "my-startup.io"
 
 ### `clinch init [options]`
 Initializes the agent and performs network registration.
-*   `--registry <url>`: Override the default dynamic router.
+*   `--registry <url>`: Override the default dynamic router (Useful for local testing).
 *   `--model <path>`: Specify a custom path for the `.gguf` model file.
 
 ### `clinch query <category> [options]`
 Queries the registry for seller nodes.
-*   `--mode <mode>`: Filter by agent protocol mode (e.g., `ANP/A`, `ANP/C`).
-*   `--json`: Output raw JSON for scripting.
+*   `--mode <mode>`: Filter by agent protocol mode (e.g., `ANP/C`).
 
 ### `clinch negotiate [address] [options]`
-Opens a session with a target seller address. If `address` or `--budget` are omitted, launches the conversational wizard.
+Opens a session with a target seller address. If `address` or `--budget` are omitted, launches the conversational wizard. 
+*   `[address]`: The target seller address MUST include the protocol prefix (e.g., `ANP/C.seller_domain`).
 *   `--budget <n>`: Your absolute maximum budget in USD.
-*   `--item <name>`: The specific item being negotiated.
-*   `--category <name>`: The market category.
-*   `--intent <intent>`: e.g., `purchase`, `lease`.
 *   `--auto`: Delegates turn-based negotiation to the local AI sandbox.
 
-### `clinch sessions [options]`
-Lists historical and active negotiation sessions.
-*   `--last <n>`: Number of recent sessions to show (Default: 20).
-*   `--outcome <s>`: Filter by `ACTIVE`, `CONVERGED`, or `STALEMATE`.
-
-### `clinch deals [options]`
-Lists successfully converged, cryptographically signed deal artifacts.
-*   `--verify <id>`: Fetches the deal artifact from the network and validates the cryptographic chain, Registry signature, and Seller signature.
-
-### `clinch callbacks [options]`
-Connects to the WebSocket queue and listens for incoming, asynchronous counter-offers from sellers you previously `exit`ed on.
-*   `--pending`: Only show unread callbacks.
-
-### `clinch config [options]`
-View or update your agent's local configuration variables.
-*   `--mode <mode>`: Update default handshake mode.
-*   `--registry <url>`: Point CLI to a new registry network.
-*   `--local-only <bool>`: Opt-out of anonymous session reporting.
+### `clinch sessions`
+Lists all historical and active negotiation sessions stored on your machine, displaying the session ID, target seller, current turn, and status.
 
-### `clinch status`
-Pings the active Registry network to check health and latency.
+### `clinch resume <sessionId> [options]`
+Rehydrates a specific session's state and cryptographic keys into memory to continue negotiating or wait for remote seller callbacks.
+*   `--auto`: Immediately hands the resumed session back to the local AI sandbox to evaluate incoming callbacks.
 
 ---
 
@@ -132,6 +127,5 @@ Pings the active Registry network to check health and latency.
 The Clinch CLI operates on a strict zero-trust, edge-first model. Your data never leaves your machine unless explicitly sent as a constraint during a session.
 
 All state is stored locally in your home directory (`~/.clinch/`):
-*   `config.json`: Your identity keys, JWT token, and preferences. **Do not share this file.**
-*   `sessions.json`: Local transcripts of your negotiations.
-*   `deals.json`: Your cryptographic deal artifacts.
+*   `config.json`: Your identity keys and JWT token. **Do not share this file.**
+*   `sessions.json`: Local transcripts, current turns, constraint vectors, and the ephemeral Ed25519 session keys necessary to prove your identity during resumed negotiations.

package/cli.js

@@ -13,9 +13,8 @@ const readline = require('readline');
 const CONFIG_DIR  = path.join(os.homedir(), '.clinch');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 const SESSIONS_FILE = path.join(CONFIG_DIR, 'sessions.json');
-const DEALS_FILE  = path.join(CONFIG_DIR, 'deals.json');
 
-// ── Config helpers ────────────────────────────────────────────
+// ── Persistence Helpers ───────────────────────────────────────
 function loadConfig() {
   if (!fs.existsSync(CONFIG_FILE)) return null;
   return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
@@ -27,12 +26,22 @@ function saveConfig(config) {
 }
 
 function loadSessions() {
-  if (!fs.existsSync(SESSIONS_FILE)) return [];
+  if (!fs.existsSync(SESSIONS_FILE)) return {};
   return JSON.parse(fs.readFileSync(SESSIONS_FILE, 'utf8'));
 }
 
-function saveSessions(sessions) {
-  fs.writeFileSync(SESSIONS_FILE, JSON.stringify(sessions, null, 2));
+function saveSessionState(sessionId, core) {
+  try {
+    const serialized = core.exportSessionState(sessionId);
+    const sessions = loadSessions();
+    sessions[sessionId] = {
+      updatedAt: new Date().toISOString(),
+      state: serialized
+    };
+    fs.writeFileSync(SESSIONS_FILE, JSON.stringify(sessions, null, 2));
+  } catch (e) {
+    // Session might be deleted or errored, ignore gracefully in CLI
+  }
 }
 
 function requireConfig() {
@@ -46,9 +55,8 @@ function requireConfig() {
 
 function getClinchCore(cfg) {
   let ClinchCoreModule;
-  try {
-    ClinchCoreModule = require('clinch-core');
-  } catch {
+  try { ClinchCoreModule = require('clinch-core'); } 
+  catch {
     console.error('clinch-core not found. Ensure it is linked or installed.');
     process.exit(1);
   }
@@ -57,12 +65,11 @@ function getClinchCore(cfg) {
 
   core.on('log', msg => console.log(msg));
   core.on('error', err => console.error('Error:', err.message));
-  core.on('status_changed', s => process.stdout.write(`\r[${s}]          \r`));
-
+  
   return core;
 }
 
-// ── Prompt helper ─────────────────────────────────────────────
+// ── Prompt Helper ─────────────────────────────────────────────
 function prompt(question) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise(resolve => {
@@ -73,11 +80,9 @@ function prompt(question) {
 // ── Conversational AI Intent Parser (CLI Layer) ───────────────
 async function parseIntentWithLLM(userInput, modelPath) {
   console.log(c.dim("\n[Agent Q] Booting local parser model to analyze your request..."));
-  
   let nodeLlama;
-  try {
-    nodeLlama = await import('node-llama-cpp');
-  } catch (e) {
+  try { nodeLlama = await import('node-llama-cpp'); } 
+  catch (e) {
     console.error(c.red("\nError: node-llama-cpp is required for conversational parsing."));
     console.error("Please run: npm install -g node-llama-cpp\n");
     process.exit(1);
@@ -86,16 +91,12 @@ async function parseIntentWithLLM(userInput, modelPath) {
   const resolvedPath = path.resolve(modelPath);
   if (!fs.existsSync(resolvedPath)) {
     console.error(c.red(`\nError: Model not found at ${resolvedPath}`));
-    console.error("Please run 'clinch init' again or specify the model path.\n");
     process.exit(1);
   }
 
   const llama = await nodeLlama.getLlama();
   const model = await llama.loadModel({ modelPath: resolvedPath });
-  const context = await model.createContext({
-    contextSize: 2048,
-    threads: Math.max(1, os.cpus().length - 1)
-  });
+  const context = await model.createContext({ contextSize: 2048, threads: Math.max(1, os.cpus().length - 1) });
 
   const systemPrompt = `You are a structured data extractor. Convert the user's conversational intent into a strict JSON schema.
 Your response MUST be ONLY valid JSON matching this schema exactly. Do not output conversational text.
@@ -116,10 +117,7 @@ JSON Schema:
   });
 
   let responseText = "";
-  await session.prompt(userInput, {
-    maxTokens: 1500,
-    onTextChunk: (chunk) => { responseText += chunk; }
-  });
+  await session.prompt(userInput, { maxTokens: 1500, onTextChunk: (chunk) => { responseText += chunk; } });
 
   try {
     const cleanJson = responseText.replace(/```json|```/g, "").trim();
@@ -168,9 +166,7 @@ program
     const existing = loadConfig();
     if (existing) {
       const overwrite = await prompt('Config already exists. Overwrite? (y/N): ');
-      if (overwrite.toLowerCase() !== 'y') {
-        console.log('Aborted.'); return;
-      }
+      if (overwrite.toLowerCase() !== 'y') { console.log('Aborted.'); return; }
     }
 
     const registryUrl = opts.registry || 'https://everydaytok-agentq-core-logics.hf.space';
@@ -219,13 +215,15 @@ program
     sellers.forEach((s, i) => {
       const tier = s.verification_tier === 'verified' ? c.green('✓ Verified') : c.dim('Unverified');
       console.log(`  ${c.bold((i+1) + '.')} ${c.cyan(s.agent_id)} (${tier})`);
+      console.log(`     ANP address: ${c.yellow('ANP/C.' + s.agent_id)}`);
+      console.log(`     Modes: ${(s.supported_modes || []).join(', ')}`);
     });
   });
 
 program
   .command('negotiate')
   .description('Start a negotiation with a seller agent')
-  .argument('[address]', 'Seller address (optional, triggers wizard if omitted)')
+  .argument('[address]', 'ANP address — format: MODE.domain.anp (e.g. ANP/A.amazon.anp)')
   .option('--budget <n>', 'Max budget (USD)')
   .option('--auto', 'Run sandbox auto-negotiation')
   .action(async (address, opts) => {
@@ -234,18 +232,17 @@ program
     let budget = opts.budget;
     let constraints = {};
 
-    // ── WIZARD MODE: Leverage CLI-layer Agent Q ──
+    // ── WIZARD MODE ──
     if (!targetAddress || !budget) {
       banner();
       console.log(c.bold("💬 Clinch Onboarding Wizard — Tell me what you're looking for.\n"));
 
       const naturalIntent = await prompt("👉 Describe what you want to negotiate\n" +
-        c.dim("   (e.g., 'Get me the domain cartpost.shop under 80 dollars, must have WHOIS privacy')\n\n💬: "));
+        c.dim("   (e.g., 'Get me the domain cartpost.shop under 80 dollars')\n\n💬: "));
 
       if (!naturalIntent) process.exit(1);
 
       const parsed = await parseIntentWithLLM(naturalIntent, cfg.modelPath);
-      
       if (!parsed) {
         console.error(c.red("✗ Error parsing constraints. Please try manual entry."));
         process.exit(1);
@@ -254,8 +251,7 @@ program
       console.log(c.bold("\n📊 Extracted Intention Context:"));
       console.log(`  - Category:   ${c.cyan(parsed.category)}`);
       console.log(`  - Target Item: ${c.cyan(parsed.item)}`);
-      console.log(`  - Max Budget:  ${c.green("$" + parsed.max_budget)}`);
-      console.log(`  - Must Haves:  ${c.yellow(parsed.must_haves.join(', ') || 'none')}\n`);
+      console.log(`  - Max Budget:  ${c.green("$" + parsed.max_budget)}\n`);
 
       const confirm = await prompt("👉 Is this correct? (Y/n): ");
       if (confirm.toLowerCase() === 'n') process.exit(0);
@@ -263,8 +259,7 @@ program
       constraints = parsed;
       budget = parsed.max_budget;
 
-      // ── Seller Discovery ──
-      console.log(c.dim(`\nQuerying registry to find compatible sellers for "${parsed.category}"...`));
+      console.log(c.dim(`\nQuerying registry for category "${parsed.category}"...`));
       const coreDiscovery = getClinchCore(cfg);
       await coreDiscovery.initialize(cfg.token);
       const results = await coreDiscovery.search(parsed.category);
@@ -272,30 +267,35 @@ program
 
       const sellers = results.results || [];
       if (sellers.length === 0) {
-        console.log(c.yellow(`\nNo certified sellers found on the network for category "${parsed.category}".`));
-        targetAddress = await prompt("👉 Please enter a seller address manually (e.g. amazon.anp): ");
+        console.log(c.yellow(`\nNo sellers found for "${parsed.category}".`));
+        targetAddress = await prompt("👉 Enter address manually (e.g. ANP/A.amazon.anp): ");
       } else {
-        console.log(c.bold(`\nAvailable certified sellers on the network:`));
-        sellers.forEach((s, idx) => console.log(`  ${idx + 1}. ${c.cyan(s.agent_id)} (${s.display_name})`));
-        const selection = await prompt(`\n👉 Select a seller to target (1-${sellers.length}): `);
-        targetAddress = `ANP/A.${sellers[parseInt(selection) - 1].agent_id}`;
+        console.log(c.bold(`\nAvailable sellers:`));
+        sellers.forEach((s, idx) => console.log(`  ${idx + 1}. ${c.cyan(s.agent_id)}`));
+        const selection = await prompt(`\n👉 Select a seller (1-${sellers.length}): `);
+        targetAddress = `ANP/C.${sellers[parseInt(selection) - 1].agent_id}`;
       }
     } else {
       constraints = { intent: 'purchase', item: 'Item', max_budget: parseFloat(budget) };
     }
 
-    // ── INITIATE CORE PROTOCOL NEGOTIATION ──
-    console.log(c.cyan(`\nStarting negotiation with ${c.bold(targetAddress)}...`));
-    const core = getClinchCore(cfg);
+    if (!targetAddress.startsWith('ANP/')) {
+        console.error(c.red(`\n✗ Invalid Address: ${targetAddress}`));
+        console.error("  Address MUST include the protocol mode prefix.");
+        console.error("  Example: ANP/C.amazon.anp\n");
+        process.exit(1);
+    }
 
+    const core = getClinchCore(cfg);
     let runAuto = opts.auto;
+    
     if (runAuto === undefined) {
       const autoInput = await prompt("\n👉 Let Agent Q negotiate autonomously? (Y/n): ");
       runAuto = autoInput.toLowerCase() !== 'n';
     }
 
     if (runAuto) {
-      console.log(c.yellow('🤖 Auto-mode: Local LLM sandbox is taking the wheel...\n'));
+      console.log(c.yellow('🤖 Auto-mode: Local LLM sandbox active.\n'));
       await core.sandbox({ modelPath: cfg.modelPath });
     } else {
       await core.initialize(cfg.token);
@@ -303,11 +303,24 @@ program
 
     core.on('session_started', ({ sessionId }) => {
       console.log(c.green(`\n✓ Session started: ${c.bold(sessionId)}`));
+      saveSessionState(sessionId, core); // Initial save
+    });
+
+    core.on('callback_received', ({ sessionId }) => saveSessionState(sessionId, core));
+    
+    core.on('session_closed', ({ sessionId, outcome, finalPrice }) => {
+      saveSessionState(sessionId, core);
+      if (outcome === 'deal') {
+        console.log(c.green(c.bold(`\n🎉 DEAL SECURED at $${finalPrice}`)));
+        process.exit(0);
+      }
     });
 
     core.on('status_changed', status => {
-      if (status === 'CONVERGED') console.log(c.green(`\n✓ DEAL REACHED at $${core.lastKnownPrice}`));
-      if (status === 'STALEMATE') console.log(c.red('\n✗ No deal reached (stalemate)'));
+      if (status === 'STALEMATE') {
+          console.log(c.red('\n✗ Stalemate. Exiting.'));
+          process.exit(0);
+      }
     });
 
     const sessionId = await core.negotiate(targetAddress, constraints);
@@ -316,19 +329,79 @@ program
       console.log(c.bold('\nManual mode — type a price to counter, or "exit" / "accept":\n'));
       const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
       rl.on('line', async (cmd) => {
-        if (cmd === 'exit') { await core.exitSession(sessionId); process.exit(0); }
+        if (cmd === 'exit') { 
+          await core.exitSession(sessionId); 
+          saveSessionState(sessionId, core);
+          process.exit(0); 
+        }
         else if (cmd === 'accept') { console.log(c.green(`Accepting...`)); rl.close(); }
         else {
           const price = parseFloat(cmd);
-          if (!isNaN(price)) await core.sendCounter(sessionId, price, 'Counter offer');
+          if (!isNaN(price)) {
+              await core.sendCounter(sessionId, price, 'Counter offer');
+              saveSessionState(sessionId, core);
+          }
         }
       });
     }
   });
 
+program
+  .command('sessions')
+  .description('List saved negotiation sessions')
+  .action(() => {
+    const sessions = loadSessions();
+    const ids = Object.keys(sessions);
+    if (ids.length === 0) return console.log(c.yellow('No saved sessions found.'));
+    
+    console.log(c.bold(`Found ${ids.length} session(s):\n`));
+    ids.forEach(id => {
+      const s = JSON.parse(sessions[id].state);
+      console.log(`  ${c.cyan(id)} - Target: ${s.sellerId} | Status: ${c.bold(s.status)} | Turn: ${s.currentTurn}`);
+    });
+  });
+
+program
+  .command('resume')
+  .description('Resume a dropped or asynchronous negotiation session')
+  .argument('<sessionId>', 'The session ID to resume')
+  .option('--auto', 'Resume with auto-negotiation')
+  .action(async (sessionId, opts) => {
+    const cfg = requireConfig();
+    const sessions = loadSessions();
+    
+    if (!sessions[sessionId]) {
+      console.error(c.red(`Session ${sessionId} not found in local store.`));
+      process.exit(1);
+    }
+
+    console.log(c.yellow(`\nRehydrating Session ${c.bold(sessionId)}...\n`));
+    const core = getClinchCore(cfg);
+
+    if (opts.auto) {
+        await core.sandbox({ modelPath: cfg.modelPath });
+    } else {
+        await core.initialize(cfg.token);
+    }
+
+    core.importSessionState(sessions[sessionId].state);
+
+    core.on('callback_received', ({ id }) => saveSessionState(id, core));
+    core.on('session_closed', ({ outcome, finalPrice }) => {
+      saveSessionState(sessionId, core);
+      if (outcome === 'deal') console.log(c.green(c.bold(`\n🎉 DEAL SECURED at $${finalPrice}`)));
+      process.exit(0);
+    });
+
+    console.log(c.green('✓ State rehydrated. Listening for webhooks/callbacks...\n'));
+    if (!opts.auto) {
+        console.log(c.dim('Awaiting remote updates. Press Ctrl+C to detach.'));
+    }
+  });
+
 program
   .name('clinch')
   .description('Clinch Protocol — Agent Negotiation CLI')
-  .version('0.1.0');
+  .version('0.2.0');
 
 program.parse();

package/package.json

@@ -6,7 +6,7 @@
 
 
   "name": "agent-clinch",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Clinch Protocol CLI — agent negotiation from your terminal",
   "main": "cli.js",
   "bin": {
@@ -19,6 +19,6 @@
   "dependencies": {
     "commander": "^14.0.3",
     "node-llama-cpp": "^3.18.1",
-    "clinch-core": "0.1.0"
+    "clinch-core": "0.2.0"
   }
 }