v0.1.0 MIT 0 dependencies

`@h33/agent`

Cryptographic attestation runtime for AI agents, tools, and autonomous systems. Every action replayable. Every tool attested. Every proof independently verifiable. Wrap any existing agent in five minutes and the entire execution trace becomes a first-class governance object.

$ npm install @h33/agent

1. Quick Start

        TypeScript
import { H33Agent } from '@h33/agent';

// 1. Create an auto-attested agent
const agent = new H33Agent({
  name: 'Claims Review Agent',
  canonicalName: 'h33.agent.acme.claims.review.prod.001',
  tenantId: 'acme-corp',
});

// 2. Start session (registers identity + opens attested session)
await agent.start();

// 3. Every tool call is automatically attested
const search = agent.tool('h33.tool.acme.search.v1', async (query: string) => {
  return await database.search(query);
});
const { result, receipt } = await search('open claims');

// 4. Verify any receipt -- publicly, no API key needed
const proof = await agent.verify(receipt);
console.log(proof.valid);   // true

// 5. Close session with H33-74 commitment
await agent.stop();
    

That is the complete integration. The H33Agent class handles registration, session management, DAG chaining, PQ signing, memory checkpointing, and session closure. Every receipt is independently verifiable at the public proof endpoint.

2. Key Concepts

Concept	Description
Agent	A registered identity with a canonical name, PQ key pair, and set of capabilities. The agent is the subject of every receipt. Registration produces the first node in the session DAG.
Session	A time-bounded execution context. All actions within a session form a hash-chained DAG. Sessions carry scope constraints: allowed tools, forbidden data classes, jurisdiction limits, and value caps.
Receipt	The universal response type (`AgentReceipt`). Every mutating API call returns a receipt containing the node ID, PQ signature status, H33-74 attestation status, parent hash, and a public verification URL.
Verification	Public, unauthenticated proof retrieval. Anyone with a node ID can verify the Merkle proof path, PQ signature chain, and H33-74 compact attestation. No API key is sent.
H33-74	A 74-byte compact attestation bundle (32 bytes on-chain, 42 bytes Cachee). Three PQ signature families. The final commitment produced when a session closes.
Replay	Deterministic reconstruction of an agent's action chain. Any historical session can be replayed from the governance DAG. Fork replay allows "what-if" analysis against modified policies.

3. Exports

Class

H33Agent

Auto-attested agent wrapper. Handles registration, sessions, tool wrapping, memory, governance, and verification.

Class

H33AgentClient

HTTP client for all 14 API endpoints. Direct access when you need fine-grained control.

Class

H33Session

Convenience wrapper for session lifecycle. Auto-fills session ID on every call.

Class

H33Verifier

Public verification client. No API key required. Verify any receipt or session chain.

Function

attestedTool()

Wraps any async function into an attested tool. Hash, execute, attest, return.

Function

hashToolRequest() / hashToolResponse()

Deterministic SHA-256 hashing with sorted-key canonical JSON serialization.

Function

toolName()

Generate canonical tool names: h33.tool.<provider>.<capability>.<version>

Function

hashMemoryState() / hashContextWindow()

Memory checkpointing helpers. Hash context windows and arbitrary state for attestation.

4. API Reference

4.1. `H33Agent`

The primary integration surface. Wraps registration, sessions, attestation, governance, and verification into a single class with auto-attested mode enabled by default.

Constructor

new H33Agent(config: H33AgentConfig)

Property	Type	Default	Description
`name`	`string`	required	Agent display name
`canonicalName`	`string`	required	Canonical name: `h33.agent.<org>.<domain>.<role>.<env>.<seq>`
`tenantId`	`string`	required	Tenant or organization identifier
`apiKey`	`string`	`H33_API_KEY` env	API key. Falls back to environment variable
`baseUrl`	`string`	`https://api.h33.ai`	API base URL
`attested`	`boolean`	`true`	Enable automatic attestation for all actions
`type`	`AgentType`	`'autonomous'`	Agent classification
`capabilities`	`string[]`	`['execute','use_tools','read_memory']`	Allowed capabilities
`sessionDurationSecs`	`number`	`3600`	Session duration in seconds
`allowedTools`	`string[]`	`[]`	Allowed tools. Empty means all allowed
`forbiddenDataClasses`	`string[]`	`[]`	Data classes the agent must not access
`maxTransactionValue`	`number`	`0`	Maximum value per transaction
`jurisdiction`	`string`	`''`	Jurisdiction restriction
`redactionLevel`	`RedactionLevel`	`'metadata_only'`	How much action detail is recorded
`memoryCheckpointInterval`	`number`	`10`	Auto-checkpoint every N actions. 0 disables

Lifecycle Methods

async start(): Promise<AgentReceipt>

Registers agent identity and opens an attested session. Call once at agent startup.

async stop(): Promise<AgentReceipt>

Closes the session cleanly with an H33-74 commitment. Call when the agent's work is done.

Action Methods

async action(actionType: string, summary: string, inputHash: string, outputHash?: string, metadata?: Record<string, string>): Promise<AgentReceipt>

Attest an arbitrary action. Chains into the session DAG automatically. The inputHash should be a SHA-256 hex of the action input; never send raw content to the API.

function tool<T, R>(name: string, handler: (input: T) => Promise<R>): (input: T) => Promise<{ result: R; receipt: AgentReceipt }>

Wrap a tool handler with automatic attestation. Returns a function that hashes input, executes, hashes output, attests, and returns both the result and the receipt.

async callTool(name: string, request: unknown, response?: unknown, status?: string): Promise<AgentReceipt>

Attest a tool call directly without wrapping. Use when you already have the request and response objects.

Memory

async checkpointMemory(contextWindow: unknown, retrievedDocs?: unknown, sizeBytes?: number): Promise<AgentReceipt>

Create a cryptographic snapshot of the agent's memory state. Hashes the context window and any retrieved documents. Automatic checkpointing is also available via memoryCheckpointInterval.

Governance

async evaluatePolicy(actionType: string, targetResource: string, parameters?: Record<string, unknown>): Promise<AgentReceipt>

Evaluate whether an action is permitted by the current policy. Returns the decision as an attested receipt.

async checkExposure(dataClass: string, operation: string): Promise<AgentReceipt>

Produce a cryptographic attestation of whether data was exposed during an operation.

async requestApproval(summary: string, approvers: string[], threshold?: number, timeoutSecs?: number): Promise<AgentReceipt>

Request human or quorum approval for an action. Defaults to threshold of 1, timeout of 300 seconds.

async delegate(delegateAgentId: string, allowedTools: string[], durationSecs: number, maxValue?: number): Promise<AgentReceipt>

Delegate authority to a sub-agent. Creates a scoped child session with the specified tool permissions and duration.

Verification and Replay

async verify(receipt: AgentReceipt): Promise<{ valid: boolean; integrity: { chain: string; signatures: string; replay: string }; verificationUrl: string; cliCommand: string }>

Verify any receipt publicly. No API key is sent. Returns validity, chain integrity status, and a CLI command for independent verification.

async replay(atTimestamp?: string): Promise<ReplayResponse>

Replay this agent's session chain at a specific timestamp.

async replayFork(forkAtNode: string, modifiedPolicy?: unknown): Promise<ReplayResponse>

Fork replay: reconstruct what would have happened if the policy was different at a given node.

4.2. `H33AgentClient`

Low-level HTTP client for all 14 API endpoints. Use this when you need direct control over the request lifecycle or when building a custom integration that does not use H33Agent.

new H33AgentClient(options?: H33ClientOptions)

Property	Type	Default
`apiKey`	`string`	`H33_API_KEY` env
`baseUrl`	`string`	`https://api.h33.ai`
`timeoutMs`	`number`	`30000`

Method	Endpoint	Returns
`register(req)`	`POST /api/v1/agents/register`	`AgentReceipt`
`startSession(req)`	`POST /api/v1/agents/sessions/start`	`AgentReceipt`
`endSession(id, summary?)`	`POST /api/v1/agents/sessions/end`	`AgentReceipt`
`attestAction(req)`	`POST /api/v1/agents/actions/attest`	`AgentReceipt`
`attestTool(req)`	`POST /api/v1/agents/tools/attest`	`AgentReceipt`
`checkpointMemory(req)`	`POST /api/v1/agents/memory/checkpoint`	`AgentReceipt`
`evaluatePolicy(req)`	`POST /api/v1/agents/policy/evaluate`	`AgentReceipt`
`checkExposure(req)`	`POST /api/v1/agents/exposure/check`	`AgentReceipt`
`requestApproval(req)`	`POST /api/v1/agents/approval/request`	`AgentReceipt`
`delegate(req)`	`POST /api/v1/agents/delegate`	`AgentReceipt`
`getProof(nodeId)`	`GET /api/v1/agents/proof/:id`	`ProofResponse` (public)
`replay(req)`	`POST /api/v1/agents/replay`	`ReplayResponse`
`replayFork(req)`	`POST /api/v1/agents/replay/fork`	`ReplayResponse`
`queryLineage(req)`	`POST /api/v1/agents/lineage/query`	`LineageResponse`

4.3. `H33Session`

Convenience wrapper around a live session. Auto-fills session_id and agent_id on every call and tracks action count.

        TypeScript
const receipt = await client.startSession({ agent_id: agentId, duration_secs: 3600 });
const session = new H33Session(client, receipt);

await session.attestAction('api_call', 'Called weather API', inputHash);
await session.attestTool('h33.tool.weather.v1', requestHash);
await session.checkpointMemory(memHash, ctxHash, 4096);
await session.end();
    

Accessor	Type	Description
`id`	`string`	Session ID
`agentId`	`string`	Owning agent ID
`actions`	`number`	Number of attested actions so far
`ended`	`boolean`	Whether the session has been closed

4.4. `H33Verifier`

Public verification client. No API key is required. This is the endpoint you give to auditors, regulators, and counterparties.

new H33Verifier(baseUrl?: string, timeoutMs?: number)

async verify(nodeId: string): Promise<ProofResponse>

Retrieve the full cryptographic proof for a receipt by node ID. Returns the Merkle proof path, receipt data, validity flag, and H33-74 attestation bytes.

async verifyChain(sessionId: string): Promise<{ intact: boolean; nodes: number }>

Verify an entire session chain. Returns whether the hash chain is intact and the total number of nodes.

        TypeScript
import { H33Verifier } from '@h33/agent';

// No API key needed -- anyone can verify
const verifier = new H33Verifier();

// Verify a single receipt
const proof = await verifier.verify('node_abc123');
console.log(proof.valid);                // true
console.log(proof.h33_74_attestation);     // 74-byte hex

// Verify an entire session chain
const chain = await verifier.verifyChain('session_xyz');
console.log(chain.intact);    // true
console.log(chain.nodes);     // 47
    

4.5. Tool Helpers

`attestedTool(session, name, handler)`

Wraps any async function into an attested tool. The wrapper automatically hashes the input, executes the handler, hashes the output, attests the call via the API, and returns both the result and the receipt. If the handler throws, the failure is attested and the error is re-thrown.

function attestedTool<T, R>(session: H33Session, name: string, handler: (input: T) => Promise<R>): (input: T) => Promise<{ result: R; receipt: AgentReceipt }>

`hashToolRequest(request)` / `hashToolResponse(response)`

Deterministic SHA-256 hashing of tool payloads. Keys are sorted before serialization to ensure identical hashes regardless of property insertion order.

function hashToolRequest(request: unknown): string function hashToolResponse(response: unknown): string

`toolName(provider, capability, version)`

Generate canonical tool names following H33 naming conventions.

import { toolName } from '@h33/agent';

toolName('anthropic', 'claude', 'v1');
// => 'h33.tool.anthropic.claude.v1'
    

4.6. Memory Helpers

`hashMemoryState(state)`

Hash any serializable memory state (context, scratchpad, retrieved documents) into a SHA-256 hex digest.

function hashMemoryState(state: unknown): string

`hashContextWindow(messages)`

Hash a chat message array for attestation. Messages are serialized in order (role:content pairs joined by newline) to produce a deterministic hash.

function hashContextWindow(messages: Array<{ role: string; content: string }>): string

5. Auto-Attested Mode

When attested: true (the default), H33Agent handles the entire attestation lifecycle automatically:

Registration -- start() registers the agent identity with PQ keys and opens an attested session.
DAG chaining -- every action and tool call is automatically linked to the previous node in the session chain via parent_hash.
Tool wrapping -- agent.tool() wraps handlers so that every invocation hashes input, executes, hashes output, and attests the call.
Memory checkpointing -- after every memoryCheckpointInterval actions (default 10), the agent automatically checkpoints the receipt chain hash as the memory state.
Session closure -- stop() seals the session chain and produces an H33-74 commitment.

Auto-attested mode is designed for the common case: wrap an existing agent, get a complete governance trace, change zero application logic. For advanced workflows (custom DAG topology, manual receipt management, cross-session attestation), use H33AgentClient directly.

6. Common Workflows

6.1. Tool Attestation

        TypeScript
const agent = new H33Agent({
  name: 'Trading Agent',
  canonicalName: 'h33.agent.acme.trading.exec.prod.001',
  tenantId: 'acme-corp',
  maxTransactionValue: 50000,
  jurisdiction: 'US',
});
await agent.start();

// Wrap each tool -- handler code is unchanged
const getQuote = agent.tool('h33.tool.acme.quote.v1', async (symbol: string) => {
  return await marketData.quote(symbol);
});

const placeOrder = agent.tool('h33.tool.acme.order.v1', async (order: Order) => {
  return await exchange.submit(order);
});

// Use them normally -- attestation is invisible
const { result: quote } = await getQuote('AAPL');
const { result: fill, receipt } = await placeOrder({ symbol: 'AAPL', qty: 100 });

console.log(receipt.verification_url);  // public proof URL
await agent.stop();
    

6.2. Memory Checkpointing

        TypeScript
import { H33Agent, hashContextWindow } from '@h33/agent';

const agent = new H33Agent({
  name: 'Research Agent',
  canonicalName: 'h33.agent.acme.research.analyst.prod.001',
  tenantId: 'acme-corp',
  memoryCheckpointInterval: 5,  // checkpoint every 5 actions
});
await agent.start();

// Manual checkpoint with full context window
const messages = [
  { role: 'system', content: 'You are a research analyst.' },
  { role: 'user', content: 'Summarize Q1 earnings for AAPL.' },
];
const receipt = await agent.checkpointMemory(messages);

// receipt.verification_url points to the attested snapshot
await agent.stop();
    

6.3. Policy Evaluation

        TypeScript
// Check policy before executing a sensitive action
const policyReceipt = await agent.evaluatePolicy(
  'wire_transfer',
  'account:12345',
  { amount: 25000, currency: 'USD' },
);

// The receipt attests the policy decision itself
console.log(policyReceipt.action_summary);  // "Policy: ALLOWED"
    

6.4. Exposure Check

        TypeScript
// Attest that PII was not exposed during a read operation
const exposure = await agent.checkExposure('PII', 'read');

// The receipt is cryptographic proof of non-exposure
console.log(exposure.verification_url);
    

6.5. Delegation

        TypeScript
// Delegate authority to a sub-agent with scoped permissions
const delegationReceipt = await agent.delegate(
  'sub-agent-id',                  // delegate agent ID
  ['h33.tool.acme.search.v1'],       // allowed tools
  1800,                              // 30-minute delegation
  1000,                              // max $1,000 per transaction
);

// The delegation itself is attested and verifiable
const proof = await agent.verify(delegationReceipt);
console.log(proof.valid);  // true
    

6.6. Replay and Fork

        TypeScript
// Replay the session from a specific point
const replay = await agent.replay('2026-05-23T10:30:00Z');
console.log(replay.chain_intact);  // true
console.log(replay.nodes.length);  // 23 actions since that timestamp

// Fork: "what if the policy was stricter at this node?"
const fork = await agent.replayFork('node_abc123', {
  max_transaction_value: 5000,  // reduced from 50,000
});
console.log(fork.nodes.length);  // actions that would have passed
    

7. Types

7.1. `AgentReceipt`

The universal response type returned by every mutating API call.

Field	Type	Description
`node_id`	`string`	Unique receipt / DAG node identifier
`agent_id`	`string`	Agent that performed the action
`session_id`	`string \| null`	Session this action belongs to (null for register)
`timestamp`	`string`	ISO-8601 timestamp
`action_type`	`string`	What kind of action was attested
`action_summary`	`string`	Human-readable summary
`input_hash`	`string`	SHA-256 hash of the input payload
`output_hash`	`string`	SHA-256 hash of the output payload
`parent_hash`	`string \| null`	Hash of the previous node in the session chain
`signature_status`	`SignatureStatus`	PQ signature verification status
`h33_74_status`	`H3374Status`	H33-74 compact attestation status
`verification_url`	`string`	Public verification URL

7.2. Enums

Type	Values
`AgentType`	`'autonomous'` \| `'supervised'` \| `'tool_only'` \| `'sub_agent'` \| `'human_in_loop'`
`RedactionLevel`	`'full'` \| `'metadata_only'` \| `'hash_only'` \| `'redacted'`
`ToolCallStatus`	`'success'` \| `'failure'` \| `'timeout'` \| `'denied'` \| `'pending'`
`ExposureStatus`	`'clean'` \| `'exposed'` \| `'quarantined'` \| `'unknown'`
`SignatureStatus`	`'valid'` \| `'invalid'` \| `'unsigned'` \| `'expired'`
`H3374Status`	`'anchored'` \| `'pending'` \| `'unavailable'`

8. Related Resources

GitHub Repository Agent Governance Specification Conformance Vectors H33-Chaos Adversarial Validation Full API Reference @h33/mcp SDK Verifier CLI H33 vs Zama H33 vs OAuth Conformance Portal JSON Schemas

@h33/agent

1. Quick Start

2. Key Concepts

3. Exports

H33Agent

H33AgentClient

H33Session

H33Verifier

attestedTool()

hashToolRequest() / hashToolResponse()

toolName()

hashMemoryState() / hashContextWindow()

4. API Reference

4.1. H33Agent

Constructor

Lifecycle Methods

Action Methods

Memory

Governance

Verification and Replay

4.2. H33AgentClient

4.3. H33Session

4.4. H33Verifier

4.5. Tool Helpers

attestedTool(session, name, handler)

hashToolRequest(request) / hashToolResponse(response)

toolName(provider, capability, version)

4.6. Memory Helpers

hashMemoryState(state)

hashContextWindow(messages)

5. Auto-Attested Mode

6. Common Workflows

6.1. Tool Attestation

6.2. Memory Checkpointing

6.3. Policy Evaluation

6.4. Exposure Check

6.5. Delegation

6.6. Replay and Fork

7. Types

7.1. AgentReceipt

7.2. Enums

8. Related Resources

`@h33/agent`

4.1. `H33Agent`

4.2. `H33AgentClient`

4.3. `H33Session`

4.4. `H33Verifier`

`attestedTool(session, name, handler)`

`hashToolRequest(request)` / `hashToolResponse(response)`

`toolName(provider, capability, version)`

`hashMemoryState(state)`

`hashContextWindow(messages)`

7.1. `AgentReceipt`