Hermes Agent + Signbee: Persistent Agents That Sign Contracts

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.zshrc  # or ~/.bashrc
hermes setup     # interactive setup wizard

{
  "mcpServers": {
    "signbee": {
      "command": "npx",
      "args": ["-y", "signbee-mcp"],
      "env": {
        "SIGNBEE_API_KEY": "sb_live_your_key_here"
      }
    }
  }
}

{
  "name": "send_document",
  "description": "Send a document for two-party e-signing. Converts markdown to PDF, verifies the sender, emails the recipient a signing link, and delivers a SHA-256 certified signed copy to both parties.",
  "parameters": {
    "type": "object",
    "properties": {
      "markdown": {
        "type": "string",
        "description": "Document content in markdown format. Must be at least 10 characters and will be converted to a professional PDF."
      },
      "title": {
        "type": "string",
        "description": "Document title. If omitted, extracted from the first markdown heading."
      },
      "sender_name": {
        "type": "string",
        "description": "Full name of the document sender"
      },
      "sender_email": {
        "type": "string",
        "description": "Email address of the sender"
      },
      "recipient_name": {
        "type": "string",
        "description": "Full name of the document recipient"
      },
      "recipient_email": {
        "type": "string",
        "description": "Email address of the recipient"
      },
      "expires_in_days": {
        "type": "integer",
        "description": "Days until the signing link expires (1-30). Default is 7."
      }
    },
    "required": [
      "markdown",
      "sender_name",
      "sender_email",
      "recipient_name",
      "recipient_email"
    ]
  }
}

{
  "name": "send_document_pdf",
  "description": "Send an existing PDF document for two-party e-signing. Use this when you already have a PDF URL instead of markdown content.",
  "parameters": {
    "type": "object",
    "properties": {
      "pdf_url": {
        "type": "string",
        "description": "Publicly accessible URL to the PDF document. Must be a valid HTTPS URL."
      },
      "title": {
        "type": "string",
        "description": "Document title."
      },
      "sender_name": {
        "type": "string",
        "description": "Full name of the document sender"
      },
      "sender_email": {
        "type": "string",
        "description": "Email address of the sender"
      },
      "recipient_name": {
        "type": "string",
        "description": "Full name of the document recipient"
      },
      "recipient_email": {
        "type": "string",
        "description": "Email address of the recipient"
      },
      "expires_in_days": {
        "type": "integer",
        "description": "Days until the signing link expires (1-30). Default is 7."
      }
    },
    "required": [
      "pdf_url",
      "title",
      "sender_name",
      "sender_email",
      "recipient_name",
      "recipient_email"
    ]
  }
}

You are Hermes, a persistent, autonomous agent equipped with e-signature capabilities via the Signbee Model Context Protocol (MCP) server. Your goal is to manage the contract lifecycle, drafting agreements and dispatching them for signing when terms are finalized.

CRITICAL SECURITY & BEHAVIORAL PROTOCOLS:
1. CONTRACT DRAFTING:
   - Always draft contracts using clean, professional markdown format.
   - Include a clear title as the first H1 header (e.g., "# Mutual Non-Disclosure Agreement").
   - Clearly define the parties (Sender and Recipient), their official names, and contact details in an introductory clause.
   - Maintain professional legal wording and formatting (e.g., numbered sections, clear clauses, and execution blocks).

2. HUMAN-IN-THE-LOOP (HITL) GATE:
   - You are NEVER allowed to call the send_document or send_document_pdf tools without explicit confirmation from the human sender.
   - Once a contract draft is created in the conversation, present it to the user and ask: "Please review the draft above. If you approve, respond with 'APPROVE' or 'SEND' to dispatch it for e-signing."
   - Only execute the tool call AFTER the user provides this explicit confirmation.

3. PARAMETER VERIFICATION:
   - Ensure you have the exact recipient name, recipient email, sender name, and sender email before calling the tool.
   - If any required field is missing or ambiguous, ask the user to clarify before drafting.

4. ERROR HANDLING & FOLLOW-UP:
   - If a tool call fails (e.g., due to rate limits or invalid emails), explain the error to the user and suggest corrective actions.
   - Log the document_id returned by the tool in your persistent memory context.
   - Offer to track the status of the sent document and check back with the user or set a schedule to follow up.

  +------------------+     1. Instruction     +-----------------------+
  |   User Intent    | ---------------------> |  Hermes Agent Memory  |
  +------------------+                        +-----------------------+
           ^                                              |
           | 6. Confirmation Notification                 | 2. Analyze & Draft
           |                                              v
  +------------------+                        +-----------------------+
  |   Telegram /     | <--------------------- |  Markdown Contract    |
  |   Slack Client   |    5. Approved (HITL)  +-----------------------+
  +------------------+                                    |
           ^                                              | 3. Call send_document
           |                                              v
           | 9. Status Event Callback         +-----------------------+
           |                                  |  Signbee MCP Tool     |
           |                                  +-----------------------+
           |                                              |
           |                                              | 4. REST Call
           |                                              v
  +------------------+     8. Event Posted    +-----------------------+
  | Agent Webhook    | <--------------------- |  Signbee API Gateway  |
  | Callback Listener|                        +-----------------------+
  +------------------+                                    |
           |                                              | 7. Signing Ceremony
           v                                              v
  +------------------+                        +-----------------------+
  | Memory Update &  |                        |  Recipient Signer     |
  | Database Sealing |                        +-----------------------+
  +------------------+

const express = require("express");
const crypto = require("crypto");
const bodyParser = require("body-parser");

const app = express();
const PORT = process.env.PORT || 8080;
// SHARED_SECRET is obtained when you register your webhook in the Signbee dashboard
const WEBHOOK_SECRET = process.env.SIGNBEE_WEBHOOK_SECRET || "sb_wh_secret_key";

// We need the raw body to verify the signature accurately
app.use(bodyParser.json({
  verify: (req, res, buf) => {
    req.rawBody = buf;
  }
}));

app.post("/webhooks/signbee", (req, res) => {
  const signature = req.headers["x-signbee-signature"];
  
  if (!signature) {
    return res.status(401).json({ error: "Missing signature header" });
  }

  if (!req.rawBody) {
    return res.status(400).json({ error: "Missing payload body" });
  }

  // Calculate HMAC SHA-256 signature
  const hmac = crypto.createHmac("sha256", WEBHOOK_SECRET);
  hmac.update(req.rawBody);
  const calculatedSignature = hmac.digest("hex");

  // Constant-time comparison to prevent timing attacks
  const isSignatureValid = crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(calculatedSignature, "hex")
  );

  if (!isSignatureValid) {
    console.error("Invalid signature. Payload verification failed.");
    return res.status(401).json({ error: "Invalid cryptographic signature" });
  }

  const { event, document_id, recipient_email, signed_at, blob_url } = req.body;
  console.log(`Received authenticated event ${event} for document ${document_id}`);

  // Handle specific document lifecycle events
  switch (event) {
    case "document.signed":
      console.log(`Document ${document_id} signed by ${recipient_email} at ${signed_at}.`);
      console.log(`Finalized PDF accessible at: ${blob_url}`);
      // TODO: Call your Hermes Agent webhook handler to update its memory database
      // e.g., await hermesAgent.updateMemory(document_id, { status: "signed", pdf: blob_url });
      break;

    case "document.viewed":
      console.log(`Recipient viewed the document: ${document_id}`);
      break;

    case "document.declined":
      console.log(`Recipient declined to sign document ${document_id}`);
      break;

    default:
      console.log(`Unhandled event state: ${event}`);
  }

  // Return 200 OK immediately
  res.status(200).json({ received: true });
});

app.listen(PORT, () => {
  console.log(`Webhook listener running on port ${PORT}`);
});

import hmac
import hashlib
import os
from fastapi import FastAPI, Request, HTTPException, Header
from pydantic import BaseModel, HttpUrl
from typing import Optional

app = FastAPI(title="Signbee Agent Webhook Listener")

WEBHOOK_SECRET = os.getenv("SIGNBEE_WEBHOOK_SECRET", "sb_wh_secret_key").encode("utf-8")

class SignbeeWebhookPayload(BaseModel):
    event: str
    document_id: str
    recipient_email: str
    recipient_name: str
    sender_email: str
    status: str
    blob_url: Optional[HttpUrl] = None
    signed_at: Optional[str] = None

@app.post("/webhooks/signbee")
async def handle_signbee_webhook(
    request: Request,
    x_signbee_signature: str = Header(None)
):
    if not x_signbee_signature:
        raise HTTPException(status_code=401, detail="Signature header missing")

    # Retrieve raw body bytes for HMAC computation
    raw_body = await request.body()
    
    # Calculate signature
    computed_hmac = hmac.new(WEBHOOK_SECRET, raw_body, hashlib.sha256).hexdigest()

    # Compare signatures using constant-time comparison
    if not hmac.compare_digest(x_signbee_signature, computed_hmac):
        raise HTTPException(status_code=401, detail="Invalid signature")

    # Parse JSON body
    try:
        body_json = await request.json()
        payload = SignbeeWebhookPayload(**body_json)
    except Exception as e:
        raise HTTPException(status_code=400, detail=f"Invalid payload format: {str(e)}")

    print(f"Verified event: {payload.event} for document: {payload.document_id}")

    if payload.event == "document.signed":
        # Process signature completion
        # Trigger downstream agent tasks (e.g. database updates, vector stores updates)
        print(f"Triggering contract closure. Signed PDF: {payload.blob_url}")
        
    elif payload.event == "document.viewed":
        print(f"Document {payload.document_id} was opened by signer.")
        
    elif payload.event == "document.declined":
        print(f"Document {payload.document_id} was declined.")

    return {"status": "success", "processed": True}