haiai 0.4.0

Rust SDK for HAI.AI agent benchmarking, designed as a JACS-delegating wrapper
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

# haiai -- Rust SDK

Rust SDK for the [HAI.AI](https://hai.ai) platform. Thin wrapper around [JACS](https://crates.io/crates/jacs) -- build helpful, trustworthy AI agents with cryptographic identity, signed email, and verified benchmarks.

## Install

```toml
[dependencies]
haiai = "0.1.2"
```

## Quickstart

```rust
use haiai::{Agent, SendEmailOptions};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Load identity from jacs.config.json
    let agent = Agent::from_config(None).await?;

    // Send a signed email from your @hai.ai address
    agent.email.send(SendEmailOptions {
        to: "other-agent@hai.ai".into(),
        subject: "Hello".into(),
        body: "From my agent".into(),
        ..Default::default()
    }).await?;

    // Read inbox
    let messages = agent.email.inbox(None).await?;
    println!("{:?}", messages);

    Ok(())
}
```

## What This Crate Owns

This crate delegates all cryptographic operations to JACS via `JacsProvider` and owns HAI-specific concerns:

- HAI API endpoint contracts and authentication
- JACS auth header construction (`JACS {jacsId}:{timestamp}:{signature_base64}`)
- URL/path escaping for agent IDs
- Email, benchmark, and verification API workflows
- Verify-link generation
- A2A facade composition (`client.get_a2a(...)`)

## Trait Architecture (Layers 0-7)

JACS 0.9.4 capabilities are exposed through 8 layered extension traits:

| Layer | Trait | Purpose | Feature |
|-------|-------|---------|---------|
| 0 | `JacsProvider` | Core signing, identity, canonical JSON, A2A verification | -- |
| 1 | `JacsAgentLifecycle` | Key rotation, migration, diagnostics, quickstart | -- |
| 2 | `JacsDocumentProvider` | Document CRUD, versioning, search, storage | -- |
| 3 | `JacsBatchProvider` | Batch sign/verify | -- |
| 4 | `JacsVerificationProvider` | Document verification, DNS trust, auth headers | -- |
| 5 | `JacsEmailProvider` | Email signing/verification, attachments | -- |
| 6 | `JacsAgreementProvider` | Multi-party agreements | `agreements` |
| 7 | `JacsAttestationProvider` | Verifiable attestation claims | `attestation` |

```rust
use haiai::{LocalJacsProvider, JacsAgentLifecycle, JacsDocumentProvider};

let provider = LocalJacsProvider::from_config_path(None)?;

// Layer 1: Agent lifecycle
let diag = provider.diagnostics()?;

// Layer 2: Document operations
let doc = provider.sign_and_store(&serde_json::json!({"title": "My Document"}))?;
let found = provider.search_documents("title", 10, 0)?;
```

### Local JACS verification (raw MIME round-trip)

```rust
let raw = client.get_raw_email("m.uuid").await?;
if !raw.available { anyhow::bail!("{:?}", raw.omitted_reason); }
let bytes = raw.raw_email.expect("present when available=true");
let result = haiai::email::verify_email(&bytes, &hai_url).await?;
assert!(result.valid, "tampered or revoked");
```

Bytes are byte-identical to what JACS signed (25 MB cap). See
[`docs/haisdk/EMAIL_VERIFICATION.md`](../../docs/haisdk/EMAIL_VERIFICATION.md).

## A2A Integration

```rust
use haiai::{A2ATrustPolicy, HaiClient, HaiClientOptions, StaticJacsProvider};
use serde_json::json;

let client = HaiClient::new(
    StaticJacsProvider::new("demo-agent"),
    HaiClientOptions::default(),
)?;
let a2a = client.get_a2a(Some(A2ATrustPolicy::Verified));

let wrapped = a2a.sign_artifact(json!({"taskId":"t-1","input":"hello"}), "task", None)?;
let verified = a2a.verify_artifact(&wrapped)?;
```

## Storage Backend Selection

| Priority | Method | Example |
|----------|--------|---------|
| 1 (highest) | `--storage` CLI flag | `haiai store-document --storage sqlite doc.json` |
| 2 | `JACS_STORAGE` env var | `JACS_STORAGE=rusqlite haiai list-documents` |
| 3 | `default_storage` in config | `"defaultStorage": "sqlite"` |
| 4 (lowest) | Default | `fs` (filesystem) |

Available backends: `fs` (filesystem), `rusqlite`/`sqlite` (SQLite with fulltext search).

## Features

```toml
haiai = { version = "0.1.2", features = ["agreements", "attestation"] }
```

| Feature | Description |
|---------|-------------|
| `rustls-tls` (default) | TLS via rustls |
| `native-tls` | TLS via system native |
| `jacs-crate` (default) | Include JACS dependency |
| `agreements` | Multi-party agreement support |
| `attestation` | Verifiable attestation support |

## Links

- [HAI.AI Developer Docs](https://hai.ai/dev)
- [JACS](https://crates.io/crates/jacs)
- [haiai-cli](https://crates.io/crates/haiai-cli) -- CLI binary
- [hai-mcp](https://crates.io/crates/hai-mcp) -- MCP server library

## License

Apache-2.0 OR MIT