Developer SpecBeta

Integration Guide & SDK Spec

Deterministic Execution Barrier & Tamper-Evident Audit Ledger for Autonomous AI Agents.

1. Quickstart & installation

Package status: The @sonnevhq/gate SDK is published to npm. For integration assistance or support questions, reach our team at contact.sonnev.com or ask Sonnev.

# Install via npm or pnpm:

npm install @sonnevhq/gate

pnpm add @sonnevhq/gate

2. Guarding agent tools

Wrap sensitive agent tool functions with gate.wrap(). If a policy requires approval, the call blocks safely until an authorized operator decides in the dashboard:

import { SonnevGate } from "@sonnevhq/gate";

const gate = new SonnevGate({
  endpoint: process.env.SONNEV_GATE_URL || "https://gate.sonnev.com",
  apiKey: process.env.SONNEV_GATE_API_KEY, // Agent API Key starting with sg_...
});

// Wrap tool with fail-closed deterministic boundary
export const sendPayment = gate.wrap(
  async (params: { amount: number; recipient: string }) => {
    return await stripe.transfers.create({
      amount: params.amount,
      currency: "usd",
      destination: params.recipient,
    });
  },
  {
    tool: "send_payment",
    action: "create_transfer",
    pollIntervalMs: 2000,
    approvalTimeoutMs: 15 * 60 * 1000, // 15 minute operator approval window
  }
);

3. Boundary architecture

Client boundary mode

Available

Wraps function calls directly in the agent runtime process using the official SDK. Sub-millisecond local evaluation with a fail-closed guarantee if the gateway is unreachable.

Inline HTTP & MCP proxy

Available

Run sonnev-gate proxy --upstream <url> or connect MCP clients directly to /api/v1/mcp. Every forwarded call checks Gate first: blocked on deny, held on approval, forwarded only on allow.

4. Tamper evident SHA 256 ledger

Every action and approval is linked into a cryptographically chained SHA-256 ledger. Writes are serialized using PostgreSQL transaction advisory locks, guaranteeing monotonic sequence numbers without chain forking under concurrency.

// Verify ledger endpoint

GET /api/v1/audit/verify

{ "valid": true, "eventCount": 97, "headHash": "3bf674..." }

Note: The audit chain is a tamper-evident cryptographic hash ledger (SHA-256 links with periodic HMAC checkpoints), not a distributed blockchain. It provides mathematically verifiable tamper-evidence with minimal storage and zero gas costs.

5. Latency & Performance Transparency

We are precise about performance claims. Gate operates in two distinct execution environments with different latency characteristics:

In-Process Local Engine

When using the @sonnevhq/core engine or SDK offline evaluation, rules evaluate in memory with sub-millisecond latency:

10 rules: ~9 µs median (0.009 ms)
100 rules: ~25 µs median (0.025 ms)
1,000 rules: ~260 µs median (0.26 ms)

Reproducible benchmark: pnpm --filter @sonnevhq/core exec tsx scripts/benchmark.ts

Hosted Gateway API

Network requests to the hosted Gateway (POST /api/v1/actions/check) incur real Internet transmission round-trips:

Local server compute: ~2–5 ms
Edge network round-trip: ~15–40 ms (depending on operator/agent proximity)
Fail-closed client timeout: configurable (default 2,500 ms)

Need help setting up custom policy schemas or have general questions?

Gate FAQ →Ask Sonnev →Contact engineering →