Agent Clinch (agent-clinch)

Agent Negotiation Protocol — Terminal Client & Autonomous Agent Integration

The Clinch CLI is the official reference implementation of a Clinch Protocol edge client. It allows you to configure your agent's mode, manage secure credentials, discover sellers on the network, manually or programmatically negotiate deals, and run background daemons or lightweight test server nodes—right from your terminal.

By keeping execution edge-first, your cryptographic keys, session transcripts, credentials, and deal artifacts are kept private. It operates out of a highly secure, passphrase-protected local vault (~/.clinch/vault.enc) to ensure zero-trust operations.

---

📦 Installation

Install the CLI globally via NPM:

npm install -g agent-clinch

Note: When negotiating with plain-English instructions (e.g. "get me a blender under $80"), the CLI automatically attempts to parse your natural intent into structured JSON constraints. To do this locally, ensure you have an Ollama instance running locally on port 11434 with the llama3 model pulled, or pass explicit JSON strings as arguments.

---

🚀 Getting Started

1. Initialize your Agent

Before you can negotiate or register a seller node, you must initialize your secure cryptographic identity vault.

For Buyers:

clinch init

This prompts you to create a secure vault passphrase. It then generates a permanent local Ed25519 identity keypair, encrypts it, and saves it to ~/.clinch/vault.enc.

For Sellers: Claim your .anp domain on the Clinch Dashboard first, retrieve your official private key, and import it into your vault:

clinch init --key <YOUR_DASHBOARD_PRIVATE_KEY_HEX>

2. Configure Your Agent Mode & Webhook

Set up your preferred operating mode (buyer, seller, or both) and bind a webhook URL for processing background daemon events:

clinch config --mode buyer --webhook https://your-orchestrator.com/webhook

3. Setting the Vault Environment Variable

Because the vault is securely encrypted with AES-256-GCM, commands that require keys will prompt you for your passphrase. To run automated flows or headless scripts, export your vault passphrase to the environment:

export CLINCH_PASSPHRASE="your_strong_passphrase_here"

4. Running the Event Daemon

Start the background listener daemon to maintain real-time WebSocket communication with the Clinch Registry. It listens for active turns and triggers callbacks/webhooks when negotiations progress:

clinch start

5. Explicit Negotiation

To start a negotiation with a target seller, pass your plain text intent (or a strict JSON constraints block) alongside the target domain.

Plain Text Intent (Parses via local Ollama):

clinch negotiate "I want a high-speed blender under $100" --target amazon.anp

JSON Constraints Mode (Direct & Deterministic):

clinch negotiate '{"intent":"purchase","item":"Ninja Blender","max_budget":85.00,"terms":{}}' --target amazon.anp

6. Interactive Turn Handling

When negotiating, the CLI acts as a manual turn interface:

• To counter-offer, run:

  clinch counter <sessionId> 75.00 --reason "Let's meet in the middle"

• To cleanly cancel and close a negotiation:

  clinch cancel <sessionId>

• To co-sign and commit a confirmed deal (human gate):

  clinch approve <sessionId>

7. Managing Local Secrets (Blind Key Pass)

To authenticate with seller nodes that require pre-shared keys, API keys, or access credentials, you can map secrets to domain namespaces. The CLI silently injects these tokens into handshakes and counter payloads, completely shielding them from LLM prompts.

# Securely register a token for a domain
clinch key --set apify.anp --value apify_prod_token_xyz987

# List registered credentials
clinch key --list

---

🛠 Command Reference

clinch config [options]

Updates configuration preferences.

• --mode <mode>: Set agent execution state (buyer | seller | both).
• --webhook <url>: Assign the background OpenClaw daemon webhook callback endpoint.

clinch init [options]

Initializes the agent identity vault.

• --key <hex>: Import an official, dashboard-issued seller node private key.

clinch key [options]

Manages third-party API credentials inside the local secure vault.

• --set <domain>: Declare a target namespace to bind a credential to. Requires --value.
• --value <key>: The cryptographic secret token to inject.
• --list: Lists all domains currently mapped inside the vault.
• --remove <domain>: Deletes a credential.

clinch start

Starts the real-time websocket event daemon listener, outputs console logs, and forwards events to your configured webhook.

clinch discover <category> [options]

Queries the Clinch Registry for registered sellers matching a market vertical.

• --direct: Outputs the raw array payload in clean JSON format (ideal for programmatic scripts).

clinch status [options]

Lists all active, in-flight negotiations stored on your machine.

• --direct: Outputs clean JSON.

clinch deals [options]

Lists completed, cryptographically signed, and committed deal artifacts.

• --direct: Outputs clean JSON.

clinch negotiate <intent> [options]

Spins up a handshake session with a target domain.

• <intent>: Your plain-English intent string or a strict constraint JSON block.
• --target <domain>: The target seller agent ID (e.g., amazon.anp).
• --direct: Returns the handshaked SessionState block as raw JSON.

clinch counter <sessionId> <price> [options]

Dispatches a turn-based counter offer.

• --reason <msg>: Brief description/argument for the counter (Default: "Counter offer").
• --direct: Outputs clean JSON.

clinch cancel <sessionId> [options]

Exits a negotiation session and cancels state progression on both endpoints.

• --direct: Outputs clean JSON.

clinch approve <sessionId> [options]

Signs the deal locally, collects the seller's cryptographic co-signature, commits it to the public ledger registry, and prints the finalized deal artifact.

• --direct: Outputs clean JSON.

clinch node register <agentId> <endpoint> [options]

(Seller Command): Cryptographically registers your endpoint URL to your claimed dashboard domain name.

• <agentId>: Your verified dashboard .anp domain (e.g. ginger.anp).
• <endpoint>: Your public web service endpoint url.
• --categories <list>: Comma-separated categories you support (Default: "general").
• --capabilities <list>: Comma-separated feature flags (Default: "http-webhook").
• --modes <list>: Supported protocol mode flags (Default: "ANP/C").

clinch serve [options]

(Seller Command): Boots a lightweight reference seller HTTP server to handle automated, turn-based bargaining loops based on configurable parameters.

• --port <p>: Port to bind to (Default: 8080).
• --config <file>: JSON file configuring merchant logic (defaultFloor, defaultApprove, maxTurns).
• --direct: JSON output mode.

---

📂 Local Storage & Vault Security

The Clinch CLI adheres strictly to zero-trust architecture. Your credentials and secret key material never leave your host device.

All operational configurations are scoped inside ~/.clinch/:

• vault.enc: Passphrase-protected vault. Houses your permanent Ed25519 seed keypair and any registered third-party credentials. Encrypted using hardware-assisted scrypt key derivation and AES-256-GCM authenticated symmetric encryption.
• state.json: Active turn session trees, ephemeral cryptographic keys, and constraints. Used to rehydrate sessions seamlessly when resuming negotiations.
• config.json: Unencrypted daemon configuration settings, token handshakes, and event-routing preferences.