@hesohq/sdk

The compliance layer for AI agents, for Node. Verify heso Action Receipts, enforce a minimum trust level, gate a Node agent's actions against policy, and push receipts to the cloud outbox — with the native verifier bundled (zero crypto in TypeScript).

You hold the signing keys. heso's cloud can verify and mirror receipts but can never forge one — so anyone (a customer, an auditor, a court) can check exactly what your agent did, and that it was authorized, without trusting heso at all.

• Site · heso.ca
• Docs · heso.ca/docs
• Verify a receipt (no account) · heso.ca/verify

npm install @hesohq/sdk      # or: pnpm add @hesohq/sdk   (Node 18+)

The native verifier (@hesohq/node) is pulled in automatically — verification runs locally and offline. A cloud API key is needed only for the cloud client (pushReceipt, pollApproval, and friends).

Verify a receipt

import { gate } from '@hesohq/sdk'

const result = gate(receipt, { minTrust: 'L1' })
// → { verdict: 'Valid', trust: 'L1', ... }   re-runs hash + signature math locally

Throw on anything below your bar:

import { assertGate } from '@hesohq/sdk'

assertGate(receipt, { minTrust: 'L1' })   // raises unless Valid and ≥ L1

Or branch on the decision:

import { isDecisionAllowed } from '@hesohq/sdk'
import type { ActionReceipt } from '@hesohq/sdk'

if (isDecisionAllowed(receipt)) { /* ... */ }

Gate a Node agent

import { wrap, pushReceipt } from '@hesohq/sdk'

const guarded = wrap(agentClient, {
  onReceipt: async (receiptJson) => {
    await pushReceipt(JSON.parse(receiptJson))   // server re-verifies before mirroring
  },
})

There are also thin adapters for the AI SDK (aiSdk) and Mastra (mastra), all built on the same engine.gate core.

Push to the cloud outbox

import { configure, pushReceipt } from '@hesohq/sdk'

configure(process.env.HESO_API_KEY!, 'https://api.heso.ca')

const result = await pushReceipt(receipt)   // server re-verifies, then mirrors

pushReceipts takes an array for batches. The cloud holds no signing keys — it only verifies and mirrors what you've already signed.

Trust model

heso proves an action was authorized under policy, and at L1 that an authorized human approved or blocked it. It does not prove the action's outcome was truthful — that's unprovable from the artifact. Trust grades are L0 (operator) and L1 (operator + human approver). The receipt format is specified in ACTION-RECEIPT-1.0.

Proprietary. See heso.ca for licensing and the hosted console.