@haiai/haiai 0.1.2

package/dist/cjs/client.js

@@ -0,0 +1,2168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HaiClient = void 0;
+const errors_js_1 = require("./errors.js");
+const signing_js_1 = require("./signing.js");
+const config_js_1 = require("./config.js");
+const jacs_1 = require("@hai.ai/jacs");
+const sse_js_1 = require("./sse.js");
+const ws_js_1 = require("./ws.js");
+function armorKeyData(raw, blockType) {
+    const base64 = raw.toString('base64');
+    const lines = base64.match(/.{1,64}/g) ?? [];
+    return `-----BEGIN ${blockType}-----\n${lines.join('\n')}\n-----END ${blockType}-----`;
+}
+function normalizeKeyText(raw, blockType) {
+    const text = raw.toString('utf-8').trim();
+    if (text.includes(`BEGIN ${blockType}`)) {
+        return text;
+    }
+    if (blockType === 'PUBLIC KEY' && text.includes('BEGIN RSA PUBLIC KEY')) {
+        return text;
+    }
+    return armorKeyData(raw, blockType);
+}
+/**
+ * HAI platform client.
+ *
+ * Zero-config: `new HaiClient()` auto-discovers jacs.config.json.
+ * All authentication uses JACS-signed headers (no API keys).
+ *
+ * @example
+ * ```typescript
+ * const hai = await HaiClient.create();
+ * const result = await hai.hello();
+ * console.log(result.message);
+ * ```
+ */
+class HaiClient {
+    config;
+    /** JACS native agent for all cryptographic operations. */
+    agent;
+    baseUrl;
+    timeout;
+    maxRetries;
+    _shouldDisconnect = false;
+    _connected = false;
+    _wsConnection = null;
+    _lastEventId = null;
+    serverPublicKeys = {};
+    /** HAI-assigned agent UUID, set after register(). Used for email URL paths. */
+    _haiAgentId = null;
+    /** Agent's @hai.ai email address, set after claimUsername(). */
+    agentEmail;
+    /** Agent key cache: maps cache key -> { value, cachedAt (ms since epoch) }. */
+    keyCache = new Map();
+    /** Agent key cache TTL in milliseconds (5 minutes). */
+    static KEY_CACHE_TTL = 300_000;
+    constructor(options) {
+        this.baseUrl = (options?.url ?? 'https://hai.ai').replace(/\/+$/, '');
+        this.timeout = options?.timeout ?? 30000;
+        this.maxRetries = options?.maxRetries ?? 3;
+    }
+    /**
+     * Create a HaiClient by loading JACS agent config.
+     *
+     * This is the primary constructor. Uses zero-config discovery:
+     * 1. options.configPath
+     * 2. JACS_CONFIG_PATH env var
+     * 3. ./jacs.config.json
+     */
+    static async create(options) {
+        const client = new HaiClient(options);
+        client.config = await (0, config_js_1.loadConfig)(options?.configPath);
+        const configPath = options?.configPath
+            ?? process.env.JACS_CONFIG_PATH
+            ?? './jacs.config.json';
+        const { resolve } = await Promise.resolve().then(() => __importStar(require('node:path')));
+        const resolvedConfigPath = resolve(configPath);
+        client.agent = new jacs_1.JacsAgent();
+        await client.agent.load(resolvedConfigPath);
+        return client;
+    }
+    /**
+     * Create a HaiClient directly from a JACS ID and PEM-encoded private key.
+     * Useful for testing or programmatic setup without config files.
+     *
+     * Creates a temporary JACS agent backed by on-disk key files so that
+     * all cryptographic operations delegate to JACS core.
+     */
+    static async fromCredentials(jacsId, privateKeyPem, options) {
+        const client = new HaiClient(options);
+        // Store the caller's private key PEM for exportKeys/rotateKeys compatibility
+        client._privateKeyPem = privateKeyPem;
+        client.privateKeyPem = privateKeyPem;
+        client._privateKeyPassphrase = options?.privateKeyPassphrase;
+        // Create an ephemeral JACS agent (in-memory keys, no disk I/O required).
+        // The ephemeral agent generates its own key pair — this is appropriate
+        // because fromCredentials is typically followed by register() which sends
+        // the new public key to the server.
+        client.agent = new jacs_1.JacsAgent();
+        const ephResult = JSON.parse(client.agent.ephemeralSync('pq2025'));
+        client.config = {
+            jacsAgentName: jacsId,
+            jacsAgentVersion: ephResult.version || '1.0.0',
+            jacsKeyDir: '',
+            jacsId,
+        };
+        return client;
+    }
+    /** The agent's JACS ID. */
+    get jacsId() {
+        return this.config.jacsId ?? this.config.jacsAgentName;
+    }
+    /** The agent name from config. */
+    get agentName() {
+        return this.config.jacsAgentName;
+    }
+    /** The HAI-assigned agent UUID (set after register()). Falls back to jacsId. */
+    get haiAgentId() {
+        return this._haiAgentId ?? this.jacsId;
+    }
+    /** Whether the client is currently connected to an event stream. */
+    get isConnected() {
+        return this._connected;
+    }
+    /** Get the agent's @hai.ai email address (set after claimUsername). */
+    getAgentEmail() {
+        return this.agentEmail;
+    }
+    /** Set the agent's @hai.ai email address manually. */
+    setAgentEmail(email) {
+        this.agentEmail = email;
+    }
+    // ---------------------------------------------------------------------------
+    // Agent key cache
+    // ---------------------------------------------------------------------------
+    /** Get a cached key if it exists and hasn't expired. */
+    getCachedKey(cacheKey) {
+        const entry = this.keyCache.get(cacheKey);
+        if (!entry)
+            return undefined;
+        if (Date.now() - entry.cachedAt >= HaiClient.KEY_CACHE_TTL) {
+            this.keyCache.delete(cacheKey);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /** Store a key in the cache with the current timestamp. */
+    setCachedKey(cacheKey, value) {
+        this.keyCache.set(cacheKey, { value, cachedAt: Date.now() });
+    }
+    /** Clear the agent key cache, forcing subsequent fetches to hit the API. */
+    clearAgentKeyCache() {
+        this.keyCache.clear();
+    }
+    // ---------------------------------------------------------------------------
+    // Auth helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Build JACS Authorization header.
+     * Format: `JACS {jacsId}:{timestamp}:{signature_base64}`
+     */
+    buildAuthHeaders() {
+        return {
+            'Authorization': this.buildAuthHeader(),
+            'Content-Type': 'application/json',
+        };
+    }
+    /** Sign a UTF-8 message with the agent's private key via JACS. Returns base64. */
+    signMessage(message) {
+        return this.agent.signStringSync(message);
+    }
+    /** Build the JACS Authorization header value string. */
+    buildAuthHeader() {
+        // Prefer JACS binding delegation
+        if ('buildAuthHeaderSync' in this.agent && typeof this.agent.buildAuthHeaderSync === 'function') {
+            return this.agent.buildAuthHeaderSync();
+        }
+        // Fallback: local construction
+        const timestamp = Math.floor(Date.now() / 1000).toString();
+        const message = `${this.jacsId}:${timestamp}`;
+        const signature = this.agent.signStringSync(message);
+        return `JACS ${this.jacsId}:${timestamp}:${signature}`;
+    }
+    makeUrl(path) {
+        const cleanPath = path.startsWith('/') ? path : `/${path}`;
+        return `${this.baseUrl}${cleanPath}`;
+    }
+    encodePathSegment(segment) {
+        return encodeURIComponent(segment);
+    }
+    usernameEndpoint(agentId) {
+        const safeAgentId = this.encodePathSegment(agentId);
+        return this.makeUrl(`/api/v1/agents/${safeAgentId}/username`);
+    }
+    // ---------------------------------------------------------------------------
+    // hello()
+    // ---------------------------------------------------------------------------
+    /**
+     * Perform a hello world exchange with HAI.
+     *
+     * Sends a JACS-signed request to the HAI hello endpoint. HAI responds
+     * with a signed ACK containing the caller's IP and a timestamp.
+     *
+     * @param includeTest - If true, request a test scenario preview
+     * @returns HelloWorldResult with HAI's signed acknowledgment
+     */
+    async hello(includeTest = false) {
+        const url = this.makeUrl('/api/v1/agents/hello');
+        const payload = { agent_id: this.jacsId };
+        if (includeTest) {
+            payload.include_test = true;
+        }
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+            body: JSON.stringify(payload),
+        });
+        const data = await response.json();
+        // Verify HAI's signature on the ACK
+        let haiSigValid = false;
+        const haiSignedAck = data.hai_signed_ack;
+        if (haiSignedAck) {
+            const fingerprint = data.hai_public_key_fingerprint || '';
+            const serverKey = this.serverPublicKeys[fingerprint];
+            if (serverKey) {
+                haiSigValid = this.verifyHaiMessage(JSON.stringify(data), haiSignedAck, serverKey);
+            }
+        }
+        return {
+            success: true,
+            timestamp: data.timestamp || '',
+            clientIp: data.client_ip || '',
+            haiPublicKeyFingerprint: data.hai_public_key_fingerprint || '',
+            message: data.message || '',
+            haiSignedAck: data.hai_signed_ack || '',
+            helloId: data.hello_id || '',
+            testScenario: data.test_scenario,
+            haiSignatureValid: haiSigValid,
+            rawResponse: data,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // verifyHaiMessage()
+    // ---------------------------------------------------------------------------
+    /**
+     * Verify a message signed by HAI via JACS.
+     *
+     * @param message - The message string that was signed
+     * @param signature - The signature to verify (base64-encoded)
+     * @param haiPublicKey - HAI's public key (PEM)
+     * @returns true if signature is valid
+     */
+    verifyHaiMessage(message, signature, haiPublicKey = '') {
+        if (!signature || !message)
+            return false;
+        if (!haiPublicKey)
+            return false;
+        try {
+            return this.agent.verifyStringSync(message, signature, Buffer.from(haiPublicKey, 'utf-8'), 'pem');
+        }
+        catch {
+            return false;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // register()
+    // ---------------------------------------------------------------------------
+    /**
+     * Register this agent with HAI.
+     *
+     * Generates a JACS agent document with the agent's public key and
+     * POSTs to the registration endpoint.
+     *
+     * This is the haiai equivalent of JACS's `registerWithHai()`. Unlike
+     * the JACS version (which uses API-key Bearer auth), this method uses
+     * the self-signed agent document as authentication. See also {@link registerNewAgent}
+     * for a full generate-and-register workflow.
+     *
+     * @param options - Optional registration parameters
+     */
+    async register(options) {
+        const derived = this.exportKeys();
+        const publicKeyPem = options?.publicKeyPem ?? derived.publicKeyPem;
+        let agentJson = options?.agentJson;
+        if (!agentJson) {
+            // Build JACS agent document
+            const agentDoc = {
+                jacsId: this.jacsId,
+                jacsVersion: '1.0.0',
+                jacsSignature: {
+                    agentID: this.jacsId,
+                    date: new Date().toISOString(),
+                },
+                jacsPublicKey: publicKeyPem,
+                name: this.config.jacsAgentName,
+                description: options?.description ?? 'Agent registered via Node SDK',
+                capabilities: ['mediation'],
+                version: this.config.jacsAgentVersion,
+            };
+            if (options?.domain) {
+                agentDoc.domain = options.domain;
+            }
+            // Sign canonical JSON via JACS
+            const canonical = (0, signing_js_1.canonicalJson)(agentDoc);
+            const signature = this.agent.signStringSync(canonical);
+            agentDoc.jacsSignature.signature = signature;
+            agentJson = JSON.stringify(agentDoc);
+        }
+        const url = this.makeUrl('/api/v1/agents/register');
+        const publicKeyB64 = Buffer.from(publicKeyPem, 'utf-8').toString('base64');
+        const body = {
+            agent_json: agentJson,
+            public_key: publicKeyB64,
+        };
+        if (options?.ownerEmail) {
+            body.owner_email = options.ownerEmail;
+        }
+        if (options?.domain) {
+            body.domain = options.domain;
+        }
+        if (options?.description) {
+            body.description = options.description;
+        }
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            // New-agent registration is self-authenticated by the signed agent document.
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        const data = await response.json();
+        // After successful registration, store the HAI-assigned agent_id (UUID).
+        // Email endpoints use this UUID in their URL paths while auth headers
+        // continue to use the original JACS ID string.
+        const assignedAgentId = data.agent_id || data.agentId || '';
+        if (assignedAgentId) {
+            this._haiAgentId = assignedAgentId;
+        }
+        return {
+            success: true,
+            agentId: assignedAgentId,
+            jacsId: data.jacs_id || data.jacsId || this.jacsId,
+            haiSignature: data.hai_signature || data.haiSignature || '',
+            registrationId: data.registration_id || data.registrationId || '',
+            registeredAt: data.registered_at || data.registeredAt || '',
+            rawResponse: data,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // rotateKeys()
+    // ---------------------------------------------------------------------------
+    /**
+     * Rotate the agent's cryptographic keys.
+     *
+     * Archives old keys, generates a new keypair via JACS core, builds a new
+     * self-signed agent document, updates config, and optionally re-registers
+     * with HAI.
+     *
+     * @param options - Rotation options (registerWithHai, haiUrl).
+     * @returns RotationResult with old/new versions and registration status.
+     */
+    async rotateKeys(options) {
+        const { copyFile, mkdtemp, readFile: readF, rename, rm, stat: fsStat, writeFile, } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+        const { randomUUID } = await Promise.resolve().then(() => __importStar(require('node:crypto')));
+        const { join, resolve } = await Promise.resolve().then(() => __importStar(require('node:path')));
+        const { tmpdir } = await Promise.resolve().then(() => __importStar(require('node:os')));
+        const registerWithHai = options?.registerWithHai ?? true;
+        const haiUrl = options?.haiUrl ?? this.baseUrl;
+        if (!this.config.jacsId) {
+            throw new errors_js_1.AuthenticationError('Cannot rotate keys: no jacsId in config. Register first.');
+        }
+        const jacsId = this.config.jacsId;
+        const oldVersion = this.config.jacsAgentVersion;
+        const keyDir = this.config.jacsKeyDir;
+        // Build old-key auth header BEFORE rotation (chain of trust)
+        const oldAuthTimestamp = Math.floor(Date.now() / 1000).toString();
+        const oldAuthMessage = `${jacsId}:${oldVersion}:${oldAuthTimestamp}`;
+        const oldAuthSig = this.agent.signStringSync(oldAuthMessage);
+        const oldAgent = this.agent;
+        // Find existing private key file
+        const candidates = [
+            join(keyDir, 'agent_private_key.pem'),
+            join(keyDir, `${this.config.jacsAgentName}.private.pem`),
+            join(keyDir, 'private_key.pem'),
+        ];
+        let privKeyPath = null;
+        for (const candidate of candidates) {
+            try {
+                await fsStat(candidate);
+                privKeyPath = candidate;
+                break;
+            }
+            catch {
+                // continue
+            }
+        }
+        if (!privKeyPath) {
+            throw new errors_js_1.AuthenticationError(`Cannot rotate keys: private key not found. Searched: ${candidates.join(', ')}`);
+        }
+        // Derive public key path
+        const pubKeyPath = privKeyPath.replace('private', 'public');
+        // 1. Archive old keys
+        const archivePriv = privKeyPath.replace('.pem', `.${oldVersion}.pem`);
+        const archivePub = pubKeyPath.replace('.pem', `.${oldVersion}.pem`);
+        await rename(privKeyPath, archivePriv);
+        try {
+            await fsStat(pubKeyPath);
+            await rename(pubKeyPath, archivePub);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                console.warn('Failed to archive public key:', err);
+            }
+        }
+        // 2. Generate new JACS agent (keys + config) via JACS core
+        const passphrase = this._privateKeyPassphrase
+            ?? process.env.JACS_PRIVATE_KEY_PASSWORD
+            ?? '';
+        const newVersion = randomUUID();
+        const generatedKeyDir = await mkdtemp(join(tmpdir(), 'haiai-rotate-'));
+        let newPublicKeyPem;
+        try {
+            const resultJson = (0, jacs_1.createAgentSync)(this.config.jacsAgentName, passphrase, 'pq2025', null, // data dir
+            generatedKeyDir, null, // config path (don't overwrite main config)
+            null, // agent type
+            this.config.description
+                ?? 'Agent registered via Node SDK', null, // domain
+            null);
+            const result = JSON.parse(resultJson);
+            const newPubKeyPath = result.public_key_path || join(keyDir, 'jacs.public.pem');
+            const newPrivKeyPath = result.private_key_path || join(keyDir, 'jacs.private.pem.enc');
+            const newPublicKeyRaw = await readF(newPubKeyPath);
+            newPublicKeyPem = normalizeKeyText(newPublicKeyRaw, 'PUBLIC KEY');
+            if (newPrivKeyPath !== privKeyPath) {
+                await copyFile(newPrivKeyPath, privKeyPath);
+            }
+            if (newPubKeyPath !== pubKeyPath) {
+                await writeFile(pubKeyPath, `${newPublicKeyPem}\n`);
+            }
+            else {
+                await writeFile(pubKeyPath, `${newPublicKeyPem}\n`);
+            }
+            this._privateKeyPem = (await readF(privKeyPath)).toString('base64');
+            this.privateKeyPem = this._privateKeyPem;
+        }
+        catch (err) {
+            // Rollback: restore archived keys
+            await rename(archivePriv, privKeyPath).catch(() => { });
+            try {
+                await rename(archivePub, pubKeyPath);
+            }
+            catch { /* noop */ }
+            throw new errors_js_1.AuthenticationError(`Key generation failed: ${err}`);
+        }
+        finally {
+            await rm(generatedKeyDir, { recursive: true, force: true }).catch(() => { });
+        }
+        // 3. Build new agent document
+        const agentDoc = {
+            jacsId,
+            jacsVersion: newVersion,
+            jacsPreviousVersion: oldVersion,
+            jacsPublicKey: newPublicKeyPem,
+            name: this.config.jacsAgentName,
+            description: this.config.description
+                ?? this.config.jacsAgentDescription
+                ?? `Agent registered via Node SDK`,
+            jacsSignature: {
+                agentID: jacsId,
+                date: new Date().toISOString(),
+            },
+        };
+        // Reload the agent with new keys for signing
+        const configPath = resolve(process.env.JACS_CONFIG_PATH ?? './jacs.config.json');
+        const reloadedAgent = new jacs_1.JacsAgent();
+        try {
+            await reloadedAgent.load(configPath);
+            this.agent = reloadedAgent;
+        }
+        catch {
+            // Fall back to the currently loaded in-memory agent when the freshly
+            // generated on-disk config cannot be reloaded in this process.
+            this.agent = oldAgent;
+        }
+        const canonical = (0, signing_js_1.canonicalJson)(agentDoc);
+        const signature = this.agent.signStringSync(canonical);
+        agentDoc.jacsSignature.signature = signature;
+        const signedAgentJson = JSON.stringify(agentDoc, null, 2);
+        // 4. Compute new public key hash via JACS
+        const newPublicKeyHash = (0, jacs_1.hashString)(newPublicKeyPem);
+        // 5. Update in-memory state
+        this.config = {
+            ...this.config,
+            jacsAgentVersion: newVersion,
+        };
+        // 6. Update config file
+        try {
+            const raw = JSON.parse(await readF(configPath, 'utf-8'));
+            raw.jacsAgentVersion = newVersion;
+            await writeFile(configPath, JSON.stringify(raw, null, 2) + '\n');
+        }
+        catch {
+            // Config update failure is non-fatal for rotation
+        }
+        // 7. Optionally re-register with HAI using the OLD key for auth
+        let registeredWithHai = false;
+        if (registerWithHai && haiUrl) {
+            try {
+                const authHeader = `JACS ${jacsId}:${oldVersion}:${oldAuthTimestamp}:${oldAuthSig}`;
+                const url = this.makeUrl('/api/v1/agents/register');
+                const publicKeyB64 = Buffer.from(newPublicKeyPem, 'utf-8').toString('base64');
+                const body = JSON.stringify({
+                    agent_json: signedAgentJson,
+                    public_key: publicKeyB64,
+                });
+                const resp = await this.fetchWithRetry(url, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': authHeader,
+                        'Content-Type': 'application/json',
+                    },
+                    body,
+                });
+                if (resp.ok) {
+                    registeredWithHai = true;
+                }
+            }
+            catch {
+                // HAI failure is non-fatal — local rotation is preserved
+            }
+        }
+        return {
+            jacsId,
+            oldVersion,
+            newVersion,
+            newPublicKeyHash,
+            registeredWithHai,
+            signedAgentJson,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // verify()
+    // ---------------------------------------------------------------------------
+    /** Verify the agent's registration status. */
+    async verify() {
+        const safeJacsId = this.encodePathSegment(this.jacsId);
+        const url = this.makeUrl(`/api/v1/agents/${safeJacsId}/verify`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.buildAuthHeaders(),
+        });
+        const data = await response.json();
+        const rawRegistrations = data.registrations || [];
+        const registrations = rawRegistrations.map((r) => ({
+            keyId: r.key_id || '',
+            algorithm: r.algorithm || '',
+            signatureJson: r.signature_json || '',
+            signedAt: r.signed_at || '',
+        }));
+        return {
+            jacsId: data.jacs_id || this.jacsId,
+            registered: data.registered ?? false,
+            registrations,
+            dnsVerified: data.dns_verified ?? false,
+            registeredAt: data.registered_at || '',
+            rawResponse: data,
+        };
+    }
+    /** @deprecated Use verify() instead. */
+    async status() {
+        return this.verify();
+    }
+    // ---------------------------------------------------------------------------
+    // freeChaoticRun()
+    // ---------------------------------------------------------------------------
+    /**
+     * Run a free chaotic benchmark.
+     *
+     * No scoring, returns raw transcript with structural annotations.
+     * Rate limited to 3 runs per JACS keypair per 24 hours.
+     */
+    async freeChaoticRun(options) {
+        const url = this.makeUrl('/api/benchmark/run');
+        const payload = {
+            name: `Free Run - ${this.jacsId.slice(0, 8)}`,
+            tier: 'free',
+            transport: options?.transport ?? 'sse',
+        };
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+            body: JSON.stringify(payload),
+        }, Math.max(this.timeout, 120000));
+        const data = await response.json();
+        return {
+            success: true,
+            runId: data.run_id || data.runId || '',
+            transcript: this.parseTranscript(data.transcript || []),
+            upsellMessage: data.upsell_message || data.upsellMessage || '',
+            rawResponse: data,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // proRun()
+    // ---------------------------------------------------------------------------
+    /**
+     * Run a pro tier benchmark ($20/month).
+     *
+     * Flow: create Stripe checkout -> poll for payment -> run benchmark.
+     */
+    async proRun(options) {
+        const pollIntervalMs = options?.pollIntervalMs ?? 2000;
+        const pollTimeoutMs = options?.pollTimeoutMs ?? 300000;
+        // Step 1: Create Stripe Checkout session
+        const purchaseUrl = this.makeUrl('/api/benchmark/purchase');
+        const purchasePayload = { tier: 'pro', agent_id: this.jacsId };
+        const purchaseResp = await this.fetchWithRetry(purchaseUrl, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+            body: JSON.stringify(purchasePayload),
+        });
+        const purchaseData = await purchaseResp.json();
+        const checkoutUrl = purchaseData.checkout_url || '';
+        const paymentId = purchaseData.payment_id || '';
+        if (!checkoutUrl) {
+            throw new errors_js_1.HaiError('No checkout URL returned from API');
+        }
+        // Step 2: Notify caller of checkout URL
+        if (options?.onCheckoutUrl) {
+            options.onCheckoutUrl(checkoutUrl);
+        }
+        // Step 3: Poll for payment confirmation
+        const paymentStatusUrl = this.makeUrl(`/api/benchmark/payments/${this.encodePathSegment(paymentId)}/status`);
+        const startTime = Date.now();
+        while (Date.now() - startTime < pollTimeoutMs) {
+            try {
+                const statusResp = await this.fetchWithRetry(paymentStatusUrl, {
+                    headers: this.buildAuthHeaders(),
+                });
+                if (statusResp.status === 200) {
+                    const statusData = await statusResp.json();
+                    const paymentStatus = statusData.status || '';
+                    if (paymentStatus === 'paid')
+                        break;
+                    if (['failed', 'expired', 'cancelled'].includes(paymentStatus)) {
+                        throw new errors_js_1.HaiError(`Payment ${paymentStatus}: ${statusData.message || ''}`);
+                    }
+                }
+            }
+            catch (e) {
+                if (e instanceof errors_js_1.HaiError)
+                    throw e;
+                // Ignore transient errors during polling
+            }
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+        }
+        if (Date.now() - startTime >= pollTimeoutMs) {
+            throw new errors_js_1.HaiError('Payment not confirmed within timeout. Complete payment and retry.');
+        }
+        // Step 4: Run the benchmark
+        const runUrl = this.makeUrl('/api/benchmark/run');
+        const runPayload = {
+            name: `Pro Run - ${this.jacsId.slice(0, 8)}`,
+            tier: 'pro',
+            payment_id: paymentId,
+            transport: options?.transport ?? 'sse',
+        };
+        const runResponse = await this.fetchWithRetry(runUrl, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+            body: JSON.stringify(runPayload),
+        }, Math.max(this.timeout, 300000));
+        const data = await runResponse.json();
+        return {
+            success: true,
+            runId: data.run_id || data.runId || '',
+            score: Number(data.score) || 0,
+            transcript: this.parseTranscript(data.transcript || []),
+            paymentId,
+            rawResponse: data,
+        };
+    }
+    /** @deprecated Use proRun instead. The tier was renamed from dns_certified to pro. */
+    async dnsCertifiedRun(options) {
+        return this.proRun(options);
+    }
+    // ---------------------------------------------------------------------------
+    // enterpriseRun()
+    // ---------------------------------------------------------------------------
+    /**
+     * Run an enterprise tier benchmark.
+     *
+     * The enterprise tier is coming soon.
+     * Contact support@hai.ai for early access.
+     */
+    async enterpriseRun(_options) {
+        throw new Error('The enterprise tier is coming soon. ' +
+            'Contact support@hai.ai for early access.');
+    }
+    /** @deprecated Use enterpriseRun instead. The tier was renamed from fully_certified to enterprise. */
+    async certifiedRun(_options) {
+        return this.enterpriseRun(_options);
+    }
+    // ---------------------------------------------------------------------------
+    // submitResponse()
+    // ---------------------------------------------------------------------------
+    /**
+     * Submit a mediation response for a benchmark job.
+     *
+     * @param jobId - The job/run ID from the benchmark_job event
+     * @param message - The mediator's response message
+     * @param options - Optional metadata and processingTimeMs
+     */
+    async submitResponse(jobId, message, options) {
+        const safeJobId = this.encodePathSegment(jobId);
+        const url = this.makeUrl(`/api/v1/agents/jobs/${safeJobId}/response`);
+        const body = {
+            response: {
+                message,
+                metadata: options?.metadata ?? null,
+                processing_time_ms: options?.processingTimeMs ?? 0,
+            },
+        };
+        // Sign the response as a JACS document via JACS
+        const signed = (0, signing_js_1.signResponse)(body, this.agent, this.jacsId);
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+            body: JSON.stringify(signed),
+        });
+        const data = await response.json();
+        return {
+            success: data.success ?? true,
+            jobId: data.job_id || data.jobId || jobId,
+            message: data.message || 'Response accepted',
+            rawResponse: data,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // connect()
+    // ---------------------------------------------------------------------------
+    /**
+     * Connect to HAI event stream via SSE or WebSocket.
+     *
+     * Returns an async generator that yields HaiEvent objects.
+     * Supports automatic reconnection with exponential backoff.
+     */
+    async *connect(options) {
+        const transport = options?.transport ?? 'sse';
+        const onEvent = options?.onEvent;
+        this._shouldDisconnect = false;
+        this._connected = false;
+        if (transport === 'ws') {
+            yield* this.connectWs(onEvent);
+        }
+        else {
+            yield* this.connectSse(onEvent);
+        }
+    }
+    /**
+     * Disconnect from the event stream (SSE or WebSocket).
+     * Safe to call even if not connected.
+     */
+    disconnect() {
+        this._shouldDisconnect = true;
+        if (this._wsConnection) {
+            try {
+                this._wsConnection.close();
+            }
+            catch { /* ignore */ }
+            this._wsConnection = null;
+        }
+        this._connected = false;
+    }
+    // ---------------------------------------------------------------------------
+    // onBenchmarkJob()
+    // ---------------------------------------------------------------------------
+    /**
+     * Convenience wrapper: connect and dispatch benchmark_job events.
+     *
+     * Runs until disconnect() is called.
+     */
+    async onBenchmarkJob(handler, options) {
+        for await (const event of this.connect({ transport: options?.transport })) {
+            if (event.eventType === 'benchmark_job') {
+                const data = (typeof event.data === 'object' && event.data !== null)
+                    ? event.data
+                    : {};
+                const job = {
+                    runId: data.run_id || data.runId || '',
+                    scenario: data.scenario ?? data.prompt ?? data,
+                    data,
+                };
+                await handler(job);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // checkUsername()
+    // ---------------------------------------------------------------------------
+    /**
+     * Check if a username is available for claiming.
+     * This is a public endpoint and does not require authentication.
+     *
+     * @param username - The username to check
+     * @returns Availability result
+     */
+    async checkUsername(username) {
+        const url = this.makeUrl(`/api/v1/agents/username/check?username=${encodeURIComponent(username)}`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        const data = await response.json();
+        return {
+            available: data.available ?? false,
+            username: data.username || username,
+            reason: data.reason || undefined,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // claimUsername()
+    // ---------------------------------------------------------------------------
+    /**
+     * Claim a username for an agent. Requires JACS auth.
+     *
+     * @param agentId - The JACS ID of the agent to claim the username for
+     * @param username - The username to claim
+     * @returns Claim result with the assigned email
+     */
+    async claimUsername(agentId, username) {
+        const url = this.usernameEndpoint(agentId);
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+            body: JSON.stringify({ username }),
+        });
+        const data = await response.json();
+        this.agentEmail = data.email || '';
+        return {
+            username: data.username || username,
+            email: data.email || '',
+            agentId: data.agent_id || data.agentId || agentId,
+        };
+    }
+    /**
+     * Rename a claimed username for an agent. Requires JACS auth.
+     *
+     * @param agentId - The agent ID to update
+     * @param username - The new username
+     */
+    async updateUsername(agentId, username) {
+        const url = this.usernameEndpoint(agentId);
+        const response = await this.fetchWithRetry(url, {
+            method: 'PUT',
+            headers: this.buildAuthHeaders(),
+            body: JSON.stringify({ username }),
+        });
+        const data = await response.json();
+        return {
+            username: data.username || username,
+            email: data.email || '',
+            previousUsername: data.previous_username || '',
+        };
+    }
+    /**
+     * Delete a claimed username for an agent. Requires JACS auth.
+     *
+     * @param agentId - The agent ID to update
+     */
+    async deleteUsername(agentId) {
+        const url = this.usernameEndpoint(agentId);
+        const response = await this.fetchWithRetry(url, {
+            method: 'DELETE',
+            headers: this.buildAuthHeaders(),
+        });
+        const data = await response.json();
+        return {
+            releasedUsername: data.released_username || '',
+            cooldownUntil: data.cooldown_until || '',
+            message: data.message || '',
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // verifyDocument()
+    // ---------------------------------------------------------------------------
+    /**
+     * Verify a signed JACS document via HAI's public verification endpoint.
+     * This endpoint is public and does not require authentication.
+     *
+     * @param document - Signed JACS document JSON (object or string)
+     */
+    async verifyDocument(document) {
+        const url = this.makeUrl('/api/jacs/verify');
+        const rawDocument = typeof document === 'string' ? document : JSON.stringify(document);
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ document: rawDocument }),
+        });
+        const data = await response.json();
+        return {
+            valid: data.valid ?? false,
+            verifiedAt: data.verified_at || '',
+            documentType: data.document_type || '',
+            issuerVerified: data.issuer_verified ?? false,
+            signatureVerified: data.signature_verified ?? false,
+            signerId: data.signer_id || '',
+            signedAt: data.signed_at || '',
+            error: data.error || undefined,
+        };
+    }
+    parseAdvancedVerificationResult(data, fallbackAgentId = '') {
+        const verification = data.verification || {};
+        return {
+            agentId: data.agent_id || fallbackAgentId,
+            verification: {
+                jacsValid: verification.jacs_valid ?? false,
+                dnsValid: verification.dns_valid ?? false,
+                haiRegistered: verification.hai_registered ?? false,
+                badge: verification.badge || 'none',
+            },
+            haiSignatures: (data.hai_signatures || []).map(String),
+            verifiedAt: data.verified_at || '',
+            errors: (data.errors || []).map(String),
+            rawResponse: data,
+        };
+    }
+    /**
+     * Get advanced 3-level verification status for an agent (public endpoint).
+     *
+     * GET /api/v1/agents/{agent_id}/verification
+     */
+    async getVerification(agentId) {
+        const safeAgentId = this.encodePathSegment(agentId);
+        const url = this.makeUrl(`/api/v1/agents/${safeAgentId}/verification`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        const data = await response.json();
+        return this.parseAdvancedVerificationResult(data, agentId);
+    }
+    /**
+     * Verify an agent document via HAI's advanced verification endpoint (public).
+     *
+     * POST /api/v1/agents/verify
+     */
+    async verifyAgentDocumentOnHai(agentJson, options) {
+        const url = this.makeUrl('/api/v1/agents/verify');
+        const payload = {
+            agent_json: typeof agentJson === 'string' ? agentJson : JSON.stringify(agentJson),
+        };
+        if (options?.publicKey) {
+            payload.public_key = options.publicKey;
+        }
+        if (options?.domain) {
+            payload.domain = options.domain;
+        }
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        });
+        const data = await response.json();
+        return this.parseAdvancedVerificationResult(data);
+    }
+    // ---------------------------------------------------------------------------
+    // registerNewAgent()
+    // ---------------------------------------------------------------------------
+    /**
+     * Generate a fresh JACS agent and register it with HAI.
+     *
+     * Convenience method that combines key generation, document building,
+     * signing, and registration in one call.
+     *
+     * @param agentName - Name for the new agent
+     * @param options - Registration options
+     * @returns Registration result
+     */
+    async registerNewAgent(agentName, options) {
+        const { mkdtemp, readFile: readF } = await Promise.resolve().then(() => __importStar(require('node:fs/promises')));
+        const { join } = await Promise.resolve().then(() => __importStar(require('node:path')));
+        const { tmpdir } = await Promise.resolve().then(() => __importStar(require('node:os')));
+        // Generate a new JACS agent with keys via JACS core
+        const tempDir = await mkdtemp(join(tmpdir(), 'haiai-register-'));
+        const keyDir = join(tempDir, 'keys');
+        const dataDir = join(tempDir, 'data');
+        const passphrase = process.env.JACS_PRIVATE_KEY_PASSWORD ?? 'register-temp';
+        const resultJson = (0, jacs_1.createAgentSync)(agentName, passphrase, 'pq2025', dataDir, keyDir, join(tempDir, 'jacs.config.json'), null, options.description ?? 'Agent registered via Node SDK', options.domain ?? null, null);
+        const createResult = JSON.parse(resultJson);
+        const pubKeyPath = createResult.public_key_path || join(keyDir, 'jacs.public.pem');
+        const publicKeyPem = normalizeKeyText(await readF(pubKeyPath), 'PUBLIC KEY');
+        // Load the new agent for signing
+        const tempAgent = new jacs_1.JacsAgent();
+        const tempConfigPath = createResult.config_path || join(tempDir, 'jacs.config.json');
+        const { resolve } = await Promise.resolve().then(() => __importStar(require('node:path')));
+        let signingAgent = tempAgent;
+        try {
+            await tempAgent.load(resolve(tempConfigPath));
+        }
+        catch {
+            tempAgent.ephemeralSync('pq2025');
+            signingAgent = tempAgent;
+        }
+        // Build minimal JACS agent document
+        const agentDoc = {
+            jacsId: agentName,
+            jacsVersion: '1.0.0',
+            jacsSignature: {
+                agentID: agentName,
+                date: new Date().toISOString(),
+            },
+            jacsPublicKey: publicKeyPem,
+            name: agentName,
+            description: options.description ?? 'Agent registered via Node SDK',
+            capabilities: ['mediation'],
+            version: '1.0.0',
+        };
+        // Sign canonical JSON via JACS
+        const canonical = (0, signing_js_1.canonicalJson)(agentDoc);
+        const signature = signingAgent.signStringSync(canonical);
+        agentDoc.jacsSignature.signature = signature;
+        const url = this.makeUrl('/api/v1/agents/register');
+        const publicKeyB64 = Buffer.from(publicKeyPem, 'utf-8').toString('base64');
+        const body = {
+            agent_json: JSON.stringify(agentDoc),
+            public_key: publicKeyB64,
+            owner_email: options.ownerEmail,
+        };
+        if (options.domain) {
+            body.domain = options.domain;
+        }
+        if (options.description) {
+            body.description = options.description;
+        }
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        const data = await response.json();
+        if (!options.quiet) {
+            console.log(`\nAgent created and submitted for registration!`);
+            console.log(`  -> Check your email (${options.ownerEmail}) for a verification link`);
+            console.log(`  -> Click the link and log into hai.ai to complete registration`);
+            console.log(`  -> After verification, claim a @hai.ai username with:`);
+            console.log(`     client.claimUsername('${data.agent_id || ''}', 'my-agent')`);
+            console.log(`  -> Save your config and private key to a secure, access-controlled location`);
+            if (options.domain) {
+                const pubKeyHash = (0, jacs_1.hashString)(publicKeyPem);
+                console.log(`\n--- DNS Setup Instructions ---`);
+                console.log(`Add this TXT record to your domain '${options.domain}':`);
+                console.log(`  Name:  _jacs.${options.domain}`);
+                console.log(`  Type:  TXT`);
+                console.log(`  Value: sha256:${pubKeyHash}`);
+                console.log(`DNS verification enables the pro tier.\n`);
+            }
+            else {
+                console.log();
+            }
+        }
+        return {
+            success: true,
+            agentId: data.agent_id || data.agentId || '',
+            jacsId: data.jacs_id || data.jacsId || agentDoc.jacsId || '',
+            haiSignature: data.hai_signature || data.haiSignature || '',
+            registrationId: data.registration_id || data.registrationId || '',
+            registeredAt: data.registered_at || data.registeredAt || '',
+            rawResponse: data,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // testConnection()
+    // ---------------------------------------------------------------------------
+    /**
+     * Test connectivity to the HAI server.
+     *
+     * Tries multiple health endpoints and returns true if any respond with 2xx.
+     * Does not require authentication.
+     */
+    async testConnection() {
+        const endpoints = ['/api/v1/health', '/health', '/api/health', '/'];
+        const timeoutMs = Math.min(this.timeout, 10000);
+        for (const endpoint of endpoints) {
+            try {
+                const url = this.makeUrl(endpoint);
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+                const resp = await fetch(url, {
+                    signal: controller.signal,
+                    redirect: 'follow',
+                });
+                clearTimeout(timeoutId);
+                if (resp.ok) {
+                    return true;
+                }
+            }
+            catch {
+                // Ignore errors and try next endpoint
+            }
+        }
+        return false;
+    }
+    // ---------------------------------------------------------------------------
+    // Utility: export keys
+    // ---------------------------------------------------------------------------
+    /**
+     * Export the agent's public key.
+     * Reads the public key from the JACS key directory.
+     * Returns { publicKeyPem }.
+     */
+    exportKeys() {
+        const fs = require('node:fs');
+        const path = require('node:path');
+        const explicitPublicKeyPem = this._publicKeyPem;
+        const explicitPrivateKeyPem = this._privateKeyPem;
+        if (typeof explicitPublicKeyPem === 'string' && explicitPublicKeyPem.trim() !== '') {
+            return {
+                publicKeyPem: explicitPublicKeyPem.trim(),
+                privateKeyPem: typeof explicitPrivateKeyPem === 'string' ? explicitPrivateKeyPem : undefined,
+            };
+        }
+        const keyDir = this.config.jacsKeyDir;
+        const candidates = [
+            path.join(keyDir, 'agent_public_key.pem'),
+            path.join(keyDir, `${this.config.jacsAgentName}.public.pem`),
+            path.join(keyDir, 'public_key.pem'),
+            path.join(keyDir, 'jacs.public.pem'),
+        ];
+        for (const candidate of candidates) {
+            try {
+                const content = fs.readFileSync(candidate);
+                return {
+                    publicKeyPem: normalizeKeyText(content, 'PUBLIC KEY'),
+                    privateKeyPem: typeof explicitPrivateKeyPem === 'string' ? explicitPrivateKeyPem : undefined,
+                };
+            }
+            catch {
+                // try next
+            }
+        }
+        throw new errors_js_1.AuthenticationError(`No public key found. Searched: ${candidates.join(', ')}`);
+    }
+    // ---------------------------------------------------------------------------
+    // SSE transport (internal)
+    // ---------------------------------------------------------------------------
+    async *connectSse(onEvent) {
+        const url = this.makeUrl('/api/v1/agents/connect');
+        let reconnectDelay = 1000;
+        const maxReconnectDelay = 60000;
+        while (!this._shouldDisconnect) {
+            try {
+                const headers = {
+                    ...this.buildAuthHeaders(),
+                    'Accept': 'text/event-stream',
+                    'Cache-Control': 'no-cache',
+                };
+                if (this._lastEventId) {
+                    headers['Last-Event-ID'] = this._lastEventId;
+                }
+                const response = await fetch(url, { headers });
+                if (response.status === 401) {
+                    throw new errors_js_1.AuthenticationError('JACS signature rejected by HAI', 401);
+                }
+                if (!response.ok) {
+                    throw new errors_js_1.HaiConnectionError(`SSE connection failed with status ${response.status}`);
+                }
+                if (!response.body) {
+                    throw new errors_js_1.HaiConnectionError('SSE response has no body');
+                }
+                this._connected = true;
+                reconnectDelay = 1000;
+                for await (const event of (0, sse_js_1.parseSseStream)(response.body)) {
+                    if (this._shouldDisconnect)
+                        break;
+                    if (event.id)
+                        this._lastEventId = event.id;
+                    // Unwrap signed events if we have server keys
+                    if (typeof event.data === 'object' && event.data !== null) {
+                        event.data = (0, signing_js_1.unwrapSignedEvent)(event.data, this.serverPublicKeys);
+                    }
+                    if (onEvent)
+                        onEvent(event);
+                    yield event;
+                }
+            }
+            catch (e) {
+                this._connected = false;
+                if (this._shouldDisconnect)
+                    break;
+                if (e instanceof errors_js_1.HaiError)
+                    throw e;
+                await new Promise(resolve => setTimeout(resolve, reconnectDelay));
+                reconnectDelay = Math.min(reconnectDelay * 2, maxReconnectDelay);
+            }
+        }
+        this._connected = false;
+    }
+    // ---------------------------------------------------------------------------
+    // WebSocket transport (internal)
+    // ---------------------------------------------------------------------------
+    async *connectWs(onEvent) {
+        const wsUrl = this.baseUrl
+            .replace(/^https:/, 'wss:')
+            .replace(/^http:/, 'ws:')
+            + '/ws/agent/connect';
+        let reconnectDelay = 1000;
+        const maxReconnectDelay = 60000;
+        while (!this._shouldDisconnect) {
+            try {
+                const headers = {
+                    Authorization: this.buildAuthHeader(),
+                };
+                if (this._lastEventId) {
+                    headers['Last-Event-ID'] = this._lastEventId;
+                }
+                const ws = await (0, ws_js_1.openWebSocket)(wsUrl, headers, this.timeout);
+                this._wsConnection = ws;
+                try {
+                    this._connected = true;
+                    reconnectDelay = 1000;
+                    // Yield connected event
+                    const connEvent = {
+                        eventType: 'connected',
+                        data: null,
+                        raw: '',
+                    };
+                    if (onEvent)
+                        onEvent(connEvent);
+                    yield connEvent;
+                    // Yield all subsequent messages
+                    for await (const event of (0, ws_js_1.wsEventStream)(ws)) {
+                        if (this._shouldDisconnect)
+                            break;
+                        if (event.id)
+                            this._lastEventId = event.id;
+                        // Auto-pong on heartbeat
+                        if (event.eventType === 'heartbeat') {
+                            const data = event.data;
+                            const timestamp = data.timestamp ?? Math.floor(Date.now() / 1000);
+                            ws.send(JSON.stringify({ type: 'pong', timestamp }));
+                        }
+                        if (onEvent)
+                            onEvent(event);
+                        yield event;
+                    }
+                }
+                finally {
+                    try {
+                        ws.close();
+                    }
+                    catch { /* ignore */ }
+                    this._wsConnection = null;
+                }
+            }
+            catch (e) {
+                this._connected = false;
+                if (this._shouldDisconnect)
+                    break;
+                if (e instanceof errors_js_1.HaiError)
+                    throw e;
+                await new Promise(resolve => setTimeout(resolve, reconnectDelay));
+                reconnectDelay = Math.min(reconnectDelay * 2, maxReconnectDelay);
+            }
+        }
+        this._connected = false;
+    }
+    // ---------------------------------------------------------------------------
+    // Fetch with retry and error handling
+    // ---------------------------------------------------------------------------
+    async fetchWithRetry(url, init, timeoutMs) {
+        const effectiveTimeout = timeoutMs ?? this.timeout;
+        let lastError = null;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), effectiveTimeout);
+                const response = await fetch(url, {
+                    ...init,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (response.status === 401) {
+                    throw new errors_js_1.AuthenticationError('JACS signature rejected by HAI', 401);
+                }
+                if (response.status === 429) {
+                    throw new errors_js_1.HaiError('Rate limited', 429);
+                }
+                if (response.ok) {
+                    return response;
+                }
+                let msg = `Request failed with status ${response.status}`;
+                try {
+                    const errBody = await response.json();
+                    if (errBody.error)
+                        msg = String(errBody.error);
+                }
+                catch { /* empty */ }
+                lastError = new errors_js_1.HaiError(msg, response.status);
+            }
+            catch (e) {
+                if (e instanceof errors_js_1.HaiError)
+                    throw e;
+                if (e instanceof Error && e.name === 'AbortError') {
+                    throw new errors_js_1.HaiConnectionError(`Request timed out after ${effectiveTimeout}ms`);
+                }
+                lastError = e instanceof Error ? e : new Error(String(e));
+            }
+            // Exponential backoff
+            if (attempt < this.maxRetries - 1) {
+                await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
+            }
+        }
+        throw lastError ?? new errors_js_1.HaiError('Request failed after all retries');
+    }
+    // ---------------------------------------------------------------------------
+    // Transcript parsing
+    // ---------------------------------------------------------------------------
+    parseEmailMessage(m) {
+        return {
+            id: m.id || '',
+            direction: m.direction || '',
+            fromAddress: m.from_address || '',
+            toAddress: m.to_address || '',
+            subject: m.subject || '',
+            bodyText: m.body_text || '',
+            messageId: m.message_id || '',
+            inReplyTo: m.in_reply_to ?? null,
+            isRead: m.is_read ?? false,
+            deliveryStatus: m.delivery_status || '',
+            createdAt: m.created_at || '',
+            readAt: m.read_at ?? null,
+            jacsVerified: m.jacs_verified ?? false,
+            ccAddresses: m.cc_addresses || [],
+            labels: m.labels || [],
+            folder: m.folder || 'inbox',
+        };
+    }
+    parseTranscript(raw) {
+        return (raw || []).map((msg) => {
+            const m = msg;
+            return {
+                role: m.role || 'system',
+                content: m.content || '',
+                timestamp: m.timestamp || '',
+                annotations: m.annotations || [],
+            };
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Server key management
+    // ---------------------------------------------------------------------------
+    /** Fetch and cache server public keys for signature verification. */
+    async fetchServerKeys() {
+        this.serverPublicKeys = await (0, signing_js_1.getServerKeys)(this.baseUrl);
+    }
+    // ---------------------------------------------------------------------------
+    // getAgentAttestation()
+    // ---------------------------------------------------------------------------
+    /**
+     * Get attestation information for another agent.
+     *
+     * @param agentId - The JACS ID of the agent to query
+     * @returns Attestation status including HAI signatures
+     */
+    async getAgentAttestation(agentId) {
+        const safeAgentId = this.encodePathSegment(agentId);
+        const url = this.makeUrl(`/api/v1/agents/${safeAgentId}/verify`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.buildAuthHeaders(),
+        });
+        const data = await response.json();
+        const rawRegistrations = data.registrations || [];
+        const registrations = rawRegistrations.map((r) => ({
+            keyId: r.key_id || '',
+            algorithm: r.algorithm || '',
+            signatureJson: r.signature_json || '',
+            signedAt: r.signed_at || '',
+        }));
+        return {
+            jacsId: data.jacs_id || agentId,
+            registered: data.registered ?? false,
+            registrations,
+            dnsVerified: data.dns_verified ?? false,
+            registeredAt: data.registered_at || '',
+            rawResponse: data,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // signBenchmarkResult()
+    // ---------------------------------------------------------------------------
+    /**
+     * Sign a benchmark result as a JACS document for independent verification.
+     *
+     * @param benchmarkResult - The benchmark result data to sign
+     * @returns Signed JACS document envelope
+     */
+    signBenchmarkResult(benchmarkResult) {
+        return (0, signing_js_1.signResponse)(benchmarkResult, this.agent, this.jacsId);
+    }
+    // ---------------------------------------------------------------------------
+    // benchmark() -- legacy suite-based
+    // ---------------------------------------------------------------------------
+    /**
+     * Run a benchmark with specified name and tier.
+     *
+     * @param name - Benchmark run name
+     * @param tier - Benchmark tier ("free", "pro", "enterprise"). Default: "free"
+     * @returns Benchmark result with scores
+     */
+    async benchmark(name = 'mediation_basic', tier = 'free') {
+        const url = this.makeUrl('/api/benchmark/run');
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+            body: JSON.stringify({ name, tier }),
+        });
+        const data = await response.json();
+        return data;
+    }
+    // ---------------------------------------------------------------------------
+    // Email CRUD
+    // ---------------------------------------------------------------------------
+    /**
+     * Send an email from the agent's @hai.ai address.
+     *
+     * @param options - Email send options (to, subject, body, optional inReplyTo)
+     * @returns Send result with message ID and status
+     */
+    async sendEmail(options) {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/send`);
+        if (!this.agentEmail) {
+            throw new Error('agent email not set — call claimUsername first');
+        }
+        // Server handles JACS attachment signing (TASK_014/018).
+        // Client only sends content fields.
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        let response;
+        try {
+            const payload = {
+                to: options.to,
+                subject: options.subject,
+                body: options.body,
+                in_reply_to: options.inReplyTo,
+                attachments: options.attachments?.map(a => ({
+                    filename: a.filename,
+                    content_type: a.contentType,
+                    data_base64: a.data.toString('base64'),
+                })),
+            };
+            if (options.cc?.length)
+                payload.cc = options.cc;
+            if (options.bcc?.length)
+                payload.bcc = options.bcc;
+            if (options.labels?.length)
+                payload.labels = options.labels;
+            response = await fetch(url, {
+                method: 'POST',
+                headers: this.buildAuthHeaders(),
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+            });
+        }
+        catch (e) {
+            clearTimeout(timeoutId);
+            if (e instanceof Error && e.name === 'AbortError') {
+                throw new errors_js_1.HaiConnectionError(`Request timed out after ${this.timeout}ms`);
+            }
+            throw e;
+        }
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            const text = await response.text();
+            let errCode = '';
+            let errMsg = text;
+            try {
+                const errData = JSON.parse(text);
+                errCode = errData.error_code || '';
+                errMsg = errData.message || errData.error || text;
+            }
+            catch { /* non-JSON body */ }
+            if (response.status === 401) {
+                throw new errors_js_1.AuthenticationError('JACS signature rejected by HAI', 401);
+            }
+            if (response.status === 403 && (errCode === 'EMAIL_NOT_ACTIVE' || text.toLowerCase().includes('allocated'))) {
+                throw new errors_js_1.EmailNotActiveError(errMsg, response.status, text);
+            }
+            if (response.status === 400 && (errCode === 'RECIPIENT_NOT_FOUND' || text.includes('Invalid recipient'))) {
+                throw new errors_js_1.RecipientNotFoundError(errMsg, response.status, text);
+            }
+            if (response.status === 429) {
+                throw new errors_js_1.RateLimitedError(errMsg, response.status, text);
+            }
+            throw new errors_js_1.HaiApiError(errMsg, response.status, undefined, errCode, text);
+        }
+        const data = await response.json();
+        return {
+            messageId: data.message_id || '',
+            status: data.status || '',
+        };
+    }
+    /**
+     * Sign a raw RFC 5322 email with a JACS attachment via the HAI API.
+     *
+     * The server adds a `jacs-signature.json` MIME attachment containing
+     * the detached JACS signature. The returned Buffer is the signed email.
+     *
+     * @param rawEmail - Raw RFC 5322 email as a Buffer or string.
+     * @returns Signed email bytes with the JACS attachment added.
+     */
+    async signEmail(rawEmail) {
+        const url = this.makeUrl('/api/v1/email/sign');
+        const headers = this.buildAuthHeaders();
+        headers['Content-Type'] = 'message/rfc822';
+        const body = typeof rawEmail === 'string' ? Buffer.from(rawEmail) : rawEmail;
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers,
+            body,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new errors_js_1.HaiApiError(`Email sign failed: HTTP ${response.status}`, response.status, undefined, '', text);
+        }
+        const arrayBuf = await response.arrayBuffer();
+        return Buffer.from(arrayBuf);
+    }
+    /**
+     * Send an agent-signed email.
+     *
+     * @deprecated sendSignedEmail currently delegates to sendEmail. The previous
+     * implementation called /api/v1/email/sign (HAI authority key) then POSTed
+     * to send-signed, which rejects because the signer ID does not match the
+     * authenticated agent. True agent-key local signing will be available when
+     * the Rust SDK core (DevEx TASK_017) ships. Use sendEmail directly.
+     *
+     * @param options - Email options (to, subject, body, attachments, etc.)
+     * @returns SendEmailResult with messageId and status.
+     */
+    async sendSignedEmail(options) {
+        // Deprecated: delegates to sendEmail until local agent-key signing
+        // is available (DevEx TASK_017). Use sendEmail directly.
+        return this.sendEmail(options);
+    }
+    /**
+     * Verify a JACS-signed email via the HAI API.
+     *
+     * The server extracts the `jacs-signature.json` attachment, validates
+     * the cryptographic signature and content hashes, and returns a
+     * detailed verification result.
+     *
+     * @param rawEmail - Raw RFC 5322 email as a Buffer or string.
+     * @returns EmailVerificationResultV2 with field-level verification results.
+     */
+    async verifyEmail(rawEmail) {
+        const url = this.makeUrl('/api/v1/email/verify');
+        const headers = this.buildAuthHeaders();
+        headers['Content-Type'] = 'message/rfc822';
+        const body = typeof rawEmail === 'string' ? Buffer.from(rawEmail) : rawEmail;
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers,
+            body,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new errors_js_1.HaiApiError(`Email verify failed: HTTP ${response.status}`, response.status, undefined, '', text);
+        }
+        const data = await response.json();
+        return {
+            valid: data.valid ?? false,
+            jacsId: data.jacs_id ?? '',
+            algorithm: data.algorithm ?? '',
+            reputationTier: data.reputation_tier ?? '',
+            dnsVerified: data.dns_verified,
+            fieldResults: (data.field_results ?? []).map(fr => ({
+                field: fr.field ?? '',
+                status: fr.status ?? 'unverifiable',
+                originalHash: fr.original_hash,
+                currentHash: fr.current_hash,
+                originalValue: fr.original_value,
+                currentValue: fr.current_value,
+            })),
+            chain: (data.chain ?? []).map(ce => ({
+                signer: ce.signer ?? '',
+                jacsId: ce.jacs_id ?? '',
+                valid: ce.valid ?? false,
+                forwarded: ce.forwarded ?? false,
+            })),
+            error: data.error,
+            agentStatus: data.agent_status,
+            benchmarksCompleted: data.benchmarks_completed ?? [],
+        };
+    }
+    /**
+     * List email messages for this agent.
+     *
+     * @param options - Pagination and direction filter options
+     * @returns Array of email messages
+     */
+    async listMessages(options) {
+        const params = new URLSearchParams();
+        if (options?.limit != null)
+            params.set('limit', String(options.limit));
+        if (options?.offset != null)
+            params.set('offset', String(options.offset));
+        if (options?.direction)
+            params.set('direction', options.direction);
+        if (options?.isRead != null)
+            params.set('is_read', String(options.isRead));
+        if (options?.folder)
+            params.set('folder', options.folder);
+        if (options?.label)
+            params.set('label', options.label);
+        const qs = params.toString();
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/messages${qs ? `?${qs}` : ''}`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.buildAuthHeaders(),
+        });
+        const data = await response.json();
+        const messages = data.messages || [];
+        return messages.map((m) => this.parseEmailMessage(m));
+    }
+    /**
+     * Mark an email message as read.
+     *
+     * @param messageId - The message ID to mark as read
+     */
+    async markRead(messageId) {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const safeMessageId = this.encodePathSegment(messageId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/messages/${safeMessageId}/read`);
+        await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+        });
+    }
+    /**
+     * Get email rate limit and status info for this agent.
+     *
+     * @returns Email status with daily limits and usage
+     */
+    async getEmailStatus() {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/status`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.buildAuthHeaders(),
+        });
+        const data = await response.json();
+        const volumeRaw = data.volume;
+        const deliveryRaw = data.delivery;
+        const reputationRaw = data.reputation;
+        return {
+            email: data.email || '',
+            status: data.status || '',
+            tier: data.tier || '',
+            billingTier: data.billing_tier || '',
+            messagesSent24h: data.messages_sent_24h || 0,
+            dailyLimit: data.daily_limit || 0,
+            dailyUsed: data.daily_used || 0,
+            resetsAt: data.resets_at || '',
+            messagesSentTotal: data.messages_sent_total || 0,
+            externalEnabled: data.external_enabled || false,
+            externalSendsToday: data.external_sends_today || 0,
+            lastTierChange: data.last_tier_change || null,
+            volume: volumeRaw ? {
+                sentTotal: volumeRaw.sent_total || 0,
+                receivedTotal: volumeRaw.received_total || 0,
+                sent24h: volumeRaw.sent_24h || 0,
+            } : null,
+            delivery: deliveryRaw ? {
+                bounceCount: deliveryRaw.bounce_count || 0,
+                spamReportCount: deliveryRaw.spam_report_count || 0,
+                deliveryRate: deliveryRaw.delivery_rate || 0,
+            } : null,
+            reputation: reputationRaw ? {
+                score: reputationRaw.score || 0,
+                tier: reputationRaw.tier || '',
+                emailScore: reputationRaw.email_score || 0,
+                haiScore: reputationRaw.hai_score != null ? reputationRaw.hai_score : null,
+            } : null,
+        };
+    }
+    /**
+     * Get a single email message by ID.
+     *
+     * @param messageId - The message ID to retrieve
+     * @returns The email message
+     */
+    async getMessage(messageId) {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const safeMessageId = this.encodePathSegment(messageId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/messages/${safeMessageId}`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.buildAuthHeaders(),
+        });
+        const m = await response.json();
+        return this.parseEmailMessage(m);
+    }
+    /**
+     * Delete an email message.
+     *
+     * @param messageId - The message ID to delete
+     */
+    async deleteMessage(messageId) {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const safeMessageId = this.encodePathSegment(messageId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/messages/${safeMessageId}`);
+        await this.fetchWithRetry(url, {
+            method: 'DELETE',
+            headers: this.buildAuthHeaders(),
+        });
+    }
+    /**
+     * Mark an email message as unread.
+     *
+     * @param messageId - The message ID to mark as unread
+     */
+    async markUnread(messageId) {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const safeMessageId = this.encodePathSegment(messageId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/messages/${safeMessageId}/unread`);
+        await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+        });
+    }
+    /**
+     * Search email messages.
+     *
+     * @param options - Search query and pagination options
+     * @returns Array of matching email messages
+     */
+    async searchMessages(options) {
+        const params = new URLSearchParams();
+        params.set('q', options.query);
+        if (options.limit != null)
+            params.set('limit', String(options.limit));
+        if (options.offset != null)
+            params.set('offset', String(options.offset));
+        if (options.direction)
+            params.set('direction', options.direction);
+        if (options.fromAddress)
+            params.set('from_address', options.fromAddress);
+        if (options.toAddress)
+            params.set('to_address', options.toAddress);
+        if (options.isRead != null)
+            params.set('is_read', String(options.isRead));
+        if (options.jacsVerified != null)
+            params.set('jacs_verified', String(options.jacsVerified));
+        if (options.folder)
+            params.set('folder', options.folder);
+        if (options.label)
+            params.set('label', options.label);
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/search?${params.toString()}`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.buildAuthHeaders(),
+        });
+        const data = await response.json();
+        const messages = data.messages || [];
+        return messages.map((m) => this.parseEmailMessage(m));
+    }
+    /**
+     * Get the count of unread messages.
+     *
+     * @returns The number of unread messages
+     */
+    async getUnreadCount() {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/unread-count`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.buildAuthHeaders(),
+        });
+        const data = await response.json();
+        return data.count || 0;
+    }
+    /**
+     * Reply to an email message.
+     *
+     * Convenience method that fetches the original message to get the sender
+     * and subject, then sends a reply with proper threading.
+     *
+     * @param messageId - The message ID to reply to
+     * @param body - Reply body text
+     * @param subjectOverride - Optional subject override (defaults to "Re: <original subject>")
+     * @returns Send result with message ID and status
+     */
+    async reply(messageId, body, subjectOverride) {
+        const original = await this.getMessage(messageId);
+        const subject = subjectOverride ?? (original.subject?.startsWith('Re: ') ? original.subject : `Re: ${original.subject}`);
+        return this.sendEmail({
+            to: original.fromAddress,
+            subject,
+            body,
+            inReplyTo: original.messageId ?? messageId,
+        });
+    }
+    /**
+     * Forward an email message to another recipient.
+     *
+     * @param options - Forward options (messageId, to, optional comment)
+     * @returns Send result with message ID and status
+     */
+    async forward(options) {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/forward`);
+        const payload = {
+            message_id: options.messageId,
+            to: options.to,
+        };
+        if (options.comment)
+            payload.comment = options.comment;
+        const response = await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+            body: JSON.stringify(payload),
+        });
+        const data = await response.json();
+        return {
+            messageId: data.message_id || '',
+            status: data.status || '',
+        };
+    }
+    /**
+     * Archive an email message.
+     *
+     * @param messageId - The message ID to archive
+     */
+    async archive(messageId) {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const safeMessageId = this.encodePathSegment(messageId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/messages/${safeMessageId}/archive`);
+        await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+        });
+    }
+    /**
+     * Unarchive (restore) an email message.
+     *
+     * @param messageId - The message ID to unarchive
+     */
+    async unarchive(messageId) {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const safeMessageId = this.encodePathSegment(messageId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/messages/${safeMessageId}/unarchive`);
+        await this.fetchWithRetry(url, {
+            method: 'POST',
+            headers: this.buildAuthHeaders(),
+        });
+    }
+    /**
+     * List contacts derived from email message history.
+     *
+     * @returns Array of Contact objects
+     */
+    async getContacts() {
+        const safeAgentId = this.encodePathSegment(this.haiAgentId);
+        const url = this.makeUrl(`/api/agents/${safeAgentId}/email/contacts`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: this.buildAuthHeaders(),
+        });
+        const data = await response.json();
+        const items = Array.isArray(data) ? data : data.contacts || [];
+        return items.map((c) => ({
+            email: c.email || '',
+            displayName: c.display_name || undefined,
+            lastContact: c.last_contact || '',
+            jacsVerified: c.jacs_verified ?? false,
+            reputationTier: c.reputation_tier || undefined,
+        }));
+    }
+    // ---------------------------------------------------------------------------
+    // fetchRemoteKey()
+    // ---------------------------------------------------------------------------
+    /**
+     * Look up another agent's public key from the HAI key directory.
+     *
+     * @param jacsId - The JACS ID of the agent to look up
+     * @param version - Key version (default: "latest")
+     * @returns Public key information
+     */
+    async fetchRemoteKey(jacsId, version = 'latest') {
+        const cacheKey = `remote:${jacsId}:${version}`;
+        const cached = this.getCachedKey(cacheKey);
+        if (cached)
+            return cached;
+        const safeJacsId = this.encodePathSegment(jacsId);
+        const safeVersion = this.encodePathSegment(version);
+        const url = this.makeUrl(`/jacs/v1/agents/${safeJacsId}/keys/${safeVersion}`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        const warning = response.headers.get('Warning');
+        if (warning) {
+            console.warn(`HAI key service: ${warning}`);
+        }
+        const data = await response.json();
+        const result = {
+            jacsId: data.jacs_id || '',
+            version: data.version || '',
+            publicKey: data.public_key || '',
+            publicKeyRawB64: data.public_key_raw_b64 || '',
+            algorithm: data.algorithm || '',
+            publicKeyHash: data.public_key_hash || '',
+            status: data.status || '',
+            dnsVerified: data.dns_verified ?? false,
+            createdAt: data.created_at || '',
+        };
+        this.setCachedKey(cacheKey, result);
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // fetchKeyByHash()
+    // ---------------------------------------------------------------------------
+    /**
+     * Look up an agent's public key by its SHA-256 hash.
+     *
+     * @param publicKeyHash - Hash in `sha256:<hex>` format
+     * @returns Public key information
+     */
+    async fetchKeyByHash(publicKeyHash) {
+        const cacheKey = `hash:${publicKeyHash}`;
+        const cached = this.getCachedKey(cacheKey);
+        if (cached)
+            return cached;
+        const safeHash = this.encodePathSegment(publicKeyHash);
+        const url = this.makeUrl(`/jacs/v1/keys/by-hash/${safeHash}`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        const data = await response.json();
+        const result = {
+            jacsId: data.jacs_id || '',
+            version: data.version || '',
+            publicKey: data.public_key || '',
+            publicKeyRawB64: data.public_key_raw_b64 || '',
+            algorithm: data.algorithm || '',
+            publicKeyHash: data.public_key_hash || '',
+            status: data.status || '',
+            dnsVerified: data.dns_verified ?? false,
+            createdAt: data.created_at || '',
+        };
+        this.setCachedKey(cacheKey, result);
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // fetchKeyByEmail()
+    // ---------------------------------------------------------------------------
+    /**
+     * Look up an agent's public key by their @hai.ai email address.
+     *
+     * @param email - The agent's email address (e.g., "alice@hai.ai")
+     * @returns Public key information
+     */
+    async fetchKeyByEmail(email) {
+        const cacheKey = `email:${email}`;
+        const cached = this.getCachedKey(cacheKey);
+        if (cached)
+            return cached;
+        const safeEmail = this.encodePathSegment(email);
+        const url = this.makeUrl(`/api/agents/keys/${safeEmail}`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        const data = await response.json();
+        const result = {
+            jacsId: data.jacs_id || '',
+            version: data.version || '',
+            publicKey: data.public_key || '',
+            publicKeyRawB64: data.public_key_raw_b64 || '',
+            algorithm: data.algorithm || '',
+            publicKeyHash: data.public_key_hash || '',
+            status: data.status || '',
+            dnsVerified: data.dns_verified ?? false,
+            createdAt: data.created_at || '',
+        };
+        this.setCachedKey(cacheKey, result);
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // fetchKeyByDomain()
+    // ---------------------------------------------------------------------------
+    /**
+     * Look up the latest DNS-verified agent key for a domain.
+     *
+     * @param domain - DNS domain (e.g., "example.com")
+     * @returns Public key information
+     */
+    async fetchKeyByDomain(domain) {
+        const cacheKey = `domain:${domain}`;
+        const cached = this.getCachedKey(cacheKey);
+        if (cached)
+            return cached;
+        const safeDomain = this.encodePathSegment(domain);
+        const url = this.makeUrl(`/jacs/v1/agents/by-domain/${safeDomain}`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        const data = await response.json();
+        const result = {
+            jacsId: data.jacs_id || '',
+            version: data.version || '',
+            publicKey: data.public_key || '',
+            publicKeyRawB64: data.public_key_raw_b64 || '',
+            algorithm: data.algorithm || '',
+            publicKeyHash: data.public_key_hash || '',
+            status: data.status || '',
+            dnsVerified: data.dns_verified ?? false,
+            createdAt: data.created_at || '',
+        };
+        this.setCachedKey(cacheKey, result);
+        return result;
+    }
+    // ---------------------------------------------------------------------------
+    // fetchAllKeys()
+    // ---------------------------------------------------------------------------
+    /**
+     * Fetch all key versions for an agent, ordered by creation date descending.
+     *
+     * @param jacsId - The JACS ID of the agent to look up
+     * @returns Object with jacs_id, keys array, and total count
+     */
+    async fetchAllKeys(jacsId) {
+        const safeJacsId = this.encodePathSegment(jacsId);
+        const url = this.makeUrl(`/jacs/v1/agents/${safeJacsId}/keys`);
+        const response = await this.fetchWithRetry(url, {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        const data = await response.json();
+        const rawKeys = data.keys || [];
+        const keys = rawKeys.map((k) => ({
+            jacsId: k.jacs_id || '',
+            version: k.version || '',
+            publicKey: k.public_key || '',
+            publicKeyRawB64: k.public_key_raw_b64 || '',
+            algorithm: k.algorithm || '',
+            publicKeyHash: k.public_key_hash || '',
+            status: k.status || '',
+            dnsVerified: k.dns_verified ?? false,
+            createdAt: k.created_at || '',
+        }));
+        return {
+            jacsId: data.jacs_id || '',
+            keys,
+            total: data.total || 0,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // verifyAgent()
+    // ---------------------------------------------------------------------------
+    /**
+     * Verify another agent's JACS document.
+     *
+     * Performs three levels of verification:
+     * 1. Local Ed25519 signature verification
+     * 2. DNS verification (via server attestation)
+     * 3. HAI registration attestation
+     *
+    * @param agentDocument - JACS agent document (object or JSON string)
+    * @returns Verification result with signature validity and trust level
+    */
+    async verifyAgent(agentDocument) {
+        const doc = typeof agentDocument === 'string'
+            ? JSON.parse(agentDocument)
+            : agentDocument;
+        const result = {
+            signatureValid: false,
+            dnsVerified: false,
+            haiRegistered: false,
+            badgeLevel: 'none',
+            jacsId: doc.jacsId || '',
+            version: doc.jacsVersion || '',
+            errors: [],
+        };
+        // Level 1: JACS signature verification
+        try {
+            const publicKeyPem = doc.jacsPublicKey;
+            if (!publicKeyPem) {
+                result.errors.push('No jacsPublicKey in document');
+                return result;
+            }
+            const sig = doc.jacsSignature;
+            const signature = sig?.signature;
+            if (!signature) {
+                result.errors.push('No signature in jacsSignature');
+                return result;
+            }
+            // Remove signature, canonicalize, verify via JACS
+            const verifyDoc = JSON.parse(JSON.stringify(doc));
+            delete verifyDoc.jacsSignature.signature;
+            const canonical = (0, signing_js_1.canonicalJson)(verifyDoc);
+            result.signatureValid = this.agent.verifyStringSync(canonical, signature, Buffer.from(publicKeyPem, 'utf-8'), 'pem');
+        }
+        catch (e) {
+            result.errors.push(`Signature verification failed: ${e.message}`);
+        }
+        // Level 3: Server attestation
+        try {
+            const safeDocJacsId = this.encodePathSegment(String(doc.jacsId || ''));
+            const attestUrl = this.makeUrl(`/api/v1/agents/${safeDocJacsId}/verify`);
+            const resp = await this.fetchWithRetry(attestUrl, {
+                method: 'GET',
+                headers: { 'Content-Type': 'application/json' },
+            });
+            const data = await resp.json();
+            result.haiRegistered = data.registered ?? false;
+            result.dnsVerified = data.dns_verified ?? false;
+            result.badgeLevel = data.badge_level || 'none';
+        }
+        catch (e) {
+            result.errors.push(`Server attestation check failed: ${e.message}`);
+        }
+        return result;
+    }
+}
+exports.HaiClient = HaiClient;
+//# sourceMappingURL=client.js.map