hiloop-sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,1181 @@
+/** Hiloop SDK client for agents to interact with the Hiloop platform. */
+import { CryptoContext, decryptAes, deriveWrappingKey, encryptAes, generateKeyPair } from "./crypto.js";
+import { parseChannel, parseChannelMessage, parseChannelParticipant, parseConvSession, parseConvSessionMessage, parseGuestToken, parseInteraction, parseMessage, } from "./types.js";
+export class HiloopError extends Error {
+    constructor(statusCode, message) {
+        super(`HTTP ${statusCode}: ${message}`);
+        this.statusCode = statusCode;
+        this.name = "HiloopError";
+    }
+}
+export class HiloopClient {
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? "http://localhost:8000").replace(/\/$/, "");
+        this.timeout = options.timeout ?? 30000;
+        this.secretKeyB64 = options.secretKey ?? "";
+        this.publicKeyB64 = options.publicKey ?? "";
+        this.crypto = new CryptoContext(options.secretKey ?? "", options.publicKey ?? "", options.spacePublicKey ?? "", options.spaceKeyId ?? "", options.serverKeyId);
+    }
+    encryptField(text) {
+        return this.crypto.encryptForApi(text);
+    }
+    /**
+     * Encrypt multiple fields with a SINGLE shared content key (AES-256-GCM).
+     * The content key is wrapped once using ECDH + HKDF + AES-GCM.
+     *
+     * This avoids the DB unique constraint issue where per-field wrappings
+     * with the same (scope, recipientKeyId) are silently dropped.
+     */
+    async encryptFields(fields) {
+        const encrypted = {};
+        const entries = Object.entries(fields).filter(([, v]) => v !== undefined);
+        if (entries.length === 0)
+            return { encrypted, contentWrappings: [] };
+        // 1. Generate ONE random content key for all fields
+        const contentKeyBytes = globalThis.crypto.getRandomValues(new Uint8Array(32));
+        const contentKeyB64 = this.bytesToBase64(contentKeyBytes);
+        // 2. Encrypt each field with the shared content key
+        for (const [key, value] of entries) {
+            encrypted[key] = await encryptAes(value, contentKeyB64);
+        }
+        // 3. Wrap the content key using ECDH + HKDF (same derivation as MCP + frontend)
+        const sharedSecret = this.crypto.getSharedSecret();
+        const wrappingKey = await deriveWrappingKey(sharedSecret, "space");
+        const wrappedContentKey = await encryptAes(contentKeyB64, wrappingKey);
+        return {
+            encrypted,
+            contentWrappings: [{
+                    scope: "space",
+                    recipientKeyId: this.crypto.getSpaceKeyId(),
+                    wrappedContentKey,
+                }],
+        };
+    }
+    bytesToBase64(bytes) {
+        let binary = "";
+        for (let i = 0; i < bytes.length; i++)
+            binary += String.fromCharCode(bytes[i]);
+        return btoa(binary);
+    }
+    async request(method, path, options) {
+        let url = `${this.baseUrl}/v1${path}`;
+        if (options?.params !== undefined) {
+            const qs = new URLSearchParams(options.params).toString();
+            url += `?${qs}`;
+        }
+        const controller = new AbortController();
+        const timeoutMs = options?.timeout ?? this.timeout;
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(url, {
+                method,
+                headers: {
+                    "X-API-Key": this.apiKey,
+                    "Content-Type": "application/json",
+                },
+                body: options?.body !== undefined ? JSON.stringify(options.body) : undefined,
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                throw new HiloopError(res.status, text);
+            }
+            return (await res.json());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Fetch binary content (e.g. file download). Returns raw ArrayBuffer. */
+    async requestBinary(path) {
+        const url = `${this.baseUrl}/v1${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(url, {
+                method: "GET",
+                headers: { "X-API-Key": this.apiKey },
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                throw new HiloopError(res.status, text);
+            }
+            return await res.arrayBuffer();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // -- Interactions -----------------------------------------------------------
+    async createInteraction(opts) {
+        // Validate form schema before encrypting
+        if (opts.type === "form" && opts.formSchema === undefined) {
+            throw new Error("Form interactions require a formSchema with at least one field.");
+        }
+        if (opts.formSchema !== undefined) {
+            validateFormSchema(opts.formSchema);
+        }
+        // Encrypt all fields with a SINGLE shared content key to avoid
+        // DB unique constraint on (interaction_id, scope, recipient_key_id).
+        const { encrypted, contentWrappings } = await this.encryptFields({
+            encryptedTitle: opts.title,
+            encryptedDescription: opts.description,
+            encryptedOptions: opts.options,
+            encryptedContext: opts.context,
+            encryptedFormSchema: opts.formSchema,
+        });
+        const body = {
+            type: opts.type,
+            priority: opts.priority ?? "normal",
+            contentWrappings,
+            ...encrypted,
+        };
+        if (opts.routeToUser !== undefined)
+            body.routeToUser = opts.routeToUser;
+        if (opts.routeToTeam !== undefined)
+            body.routeToTeam = opts.routeToTeam;
+        if (opts.deadlineMinutes !== undefined)
+            body.deadlineMinutes = opts.deadlineMinutes;
+        if (opts.callbackUrl !== undefined)
+            body.callbackUrl = opts.callbackUrl;
+        if (opts.convSessionId !== undefined)
+            body.convSessionId = opts.convSessionId;
+        if (opts.presentation !== undefined)
+            body.presentation = opts.presentation;
+        const data = await this.request("POST", "/agent/interactions", { body });
+        return parseInteraction(data);
+    }
+    async getInteraction(interactionId) {
+        const data = await this.request("GET", `/agent/interactions/${interactionId}`);
+        return this.decryptInteractionFields(parseInteraction(data), data);
+    }
+    /** Try to decrypt encrypted interaction fields using content wrappings. */
+    async decryptInteractionFields(interaction, raw) {
+        const wrappings = raw.contentWrappings;
+        if (!wrappings?.length)
+            return interaction;
+        const tryDecrypt = async (ciphertext) => {
+            if (!ciphertext)
+                return undefined;
+            const plain = await this.crypto.decryptWrappedContent(ciphertext, wrappings);
+            return plain ?? ciphertext;
+        };
+        return {
+            ...interaction,
+            title: (await tryDecrypt(interaction.title)) ?? "",
+            description: await tryDecrypt(interaction.description),
+            options: await tryDecrypt(interaction.options),
+            context: await tryDecrypt(interaction.context),
+            formSchema: await tryDecrypt(interaction.formSchema),
+            response: await tryDecrypt(interaction.response),
+            comment: await tryDecrypt(interaction.comment),
+        };
+    }
+    async cancelInteraction(interactionId) {
+        const data = await this.request("POST", `/agent/interactions/${interactionId}/cancel`);
+        return parseInteraction(data);
+    }
+    /** Update description/context on an interaction. Accepts plaintext — auto-encrypts. */
+    async updateInteractionContext(interactionId, opts) {
+        const { encrypted, contentWrappings } = await this.encryptFields({
+            encryptedDescription: opts.description,
+            encryptedContext: opts.context,
+        });
+        return await this.request("PATCH", `/agent/interactions/${interactionId}/context`, { body: { contentWrappings, ...encrypted } });
+    }
+    async acknowledgeInteraction(interactionId) {
+        const data = await this.request("POST", `/agent/interactions/${interactionId}/acknowledge`);
+        return parseInteraction(data);
+    }
+    /** AG-018/019: Update priority, deadline, or context metadata on a pending interaction. */
+    async updateInteractionMetadata(interactionId, opts) {
+        return await this.request("PATCH", `/agent/interactions/${interactionId}/metadata`, { body: opts });
+    }
+    /** Get the transition log for an interaction. */
+    async getInteractionTransitions(interactionId) {
+        return await this.request("GET", `/agent/interactions/${interactionId}/transitions`);
+    }
+    /** HU-073 (agent side): Read pending task control signal (pause/resume/cancel). */
+    async getTaskControl(interactionId) {
+        return await this.request("GET", `/agent/interactions/${interactionId}/task-control`);
+    }
+    /** HU-073 (agent side): Acknowledge task control signal, clearing it. */
+    async ackTaskControl(interactionId) {
+        return await this.request("POST", `/agent/interactions/${interactionId}/task-control/ack`);
+    }
+    /** Single long-poll for a response (server-side timeout, max ~30s). */
+    async awaitResponse(interactionId, timeout = 30) {
+        const data = await this.request("GET", `/agent/interactions/${interactionId}/await`, { params: { timeout: String(timeout) }, timeout: (timeout + 5) * 1000 });
+        return parseInteraction(data);
+    }
+    /**
+     * Wait for a human to respond to an interaction, polling repeatedly.
+     * Returns the interaction once it has a response (status is responded/completed),
+     * or throws after the timeout expires.
+     *
+     * @param interactionId - The interaction to wait for
+     * @param timeoutSeconds - Maximum wait time in seconds (default 300, max 3600)
+     */
+    async waitForResponse(interactionId, timeoutSeconds = 300) {
+        const deadline = Date.now() + timeoutSeconds * 1000;
+        const pollInterval = Math.min(30, timeoutSeconds); // server long-poll max 30s
+        while (Date.now() < deadline) {
+            const remaining = Math.ceil((deadline - Date.now()) / 1000);
+            if (remaining <= 0)
+                break;
+            const pollTimeout = Math.min(pollInterval, remaining);
+            const interaction = await this.awaitResponse(interactionId, pollTimeout);
+            // Check if the human has responded
+            if (interaction.status === "responded" ||
+                interaction.status === "completed" ||
+                interaction.status === "cancelled" ||
+                interaction.status === "expired") {
+                return interaction;
+            }
+            // Still pending — loop and poll again
+        }
+        // Final check before timeout
+        const final = await this.getInteraction(interactionId);
+        if (final.status !== "created" && final.status !== "pending" && final.status !== "viewed") {
+            return final;
+        }
+        throw new HiloopError(408, `Timed out waiting for response after ${timeoutSeconds}s`);
+    }
+    async listInteractions(filters) {
+        const params = {};
+        if (filters?.status !== undefined)
+            params.status = filters.status;
+        if (filters?.type !== undefined)
+            params.type = filters.type;
+        params.page = String(filters?.page ?? 1);
+        params.pageSize = String(filters?.pageSize ?? 20);
+        const data = await this.request("GET", "/agent/interactions", { params });
+        return {
+            items: data.items.map((i) => parseInteraction(i)),
+            total: data.total,
+            page: data.page,
+            pageSize: data.pageSize,
+        };
+    }
+    // -- Messages ---------------------------------------------------------------
+    async sendMessage(interactionId, content) {
+        const { encrypted, contentWrappings } = await this.encryptFields({
+            encryptedContent: content,
+        });
+        const data = await this.request("POST", `/agent/interactions/${interactionId}/messages`, { body: { contentWrappings, ...encrypted } });
+        return parseMessage(data);
+    }
+    /** Push content blocks to an interaction. */
+    async pushContentBlocks(interactionId, blocks) {
+        const encryptedBlocks = await Promise.all(blocks.map(async (block) => {
+            const plaintext = JSON.stringify(block.data);
+            const wrapped = await this.crypto.encryptWithWrapping(plaintext);
+            return {
+                blockType: block.blockType,
+                encryptedData: wrapped.ciphertext,
+                contentWrappings: wrapped.wrappings,
+                position: block.position,
+            };
+        }));
+        return await this.request("POST", `/agent/interactions/${interactionId}/blocks`, { body: { blocks: encryptedBlocks } });
+    }
+    /** List content blocks for an interaction. */
+    async listContentBlocks(interactionId) {
+        return await this.request("GET", `/agent/interactions/${interactionId}/blocks`);
+    }
+    /** Update a content block. */
+    async updateContentBlock(interactionId, blockId, data) {
+        return await this.request("PUT", `/agent/interactions/${interactionId}/blocks/${blockId}`, { body: { data } });
+    }
+    /** Delete a content block. */
+    async deleteContentBlock(interactionId, blockId) {
+        return await this.request("DELETE", `/agent/interactions/${interactionId}/blocks/${blockId}`);
+    }
+    /** Upload a file attachment to an interaction (base64-encoded). */
+    async uploadAttachment(interactionId, opts) {
+        return await this.request("POST", `/agent/interactions/${interactionId}/attachments`, { body: opts });
+    }
+    /** List attachments for an interaction, optionally filtered by messageId. */
+    async listAttachments(interactionId, messageId) {
+        const qs = messageId ? `?messageId=${encodeURIComponent(messageId)}` : "";
+        return await this.request("GET", `/agent/interactions/${interactionId}/attachments${qs}`);
+    }
+    /** Download raw binary content of a specific attachment. */
+    async getAttachment(interactionId, fileId) {
+        return await this.requestBinary(`/agent/interactions/${interactionId}/attachments/${fileId}`);
+    }
+    /** List all reactions for messages in an interaction. */
+    async listInteractionReactions(interactionId) {
+        return await this.request("GET", `/agent/interactions/${interactionId}/reactions`);
+    }
+    /** Add a reaction emoji to a message in an interaction. */
+    async addInteractionReaction(interactionId, messageId, emoji) {
+        return await this.request("POST", `/agent/interactions/${interactionId}/messages/${messageId}/reactions`, { body: { emoji } });
+    }
+    /** Remove a reaction emoji from a message in an interaction. */
+    async removeInteractionReaction(interactionId, messageId, emoji) {
+        return await this.request("DELETE", `/agent/interactions/${interactionId}/messages/${messageId}/reactions/${encodeURIComponent(emoji)}`);
+    }
+    /** Mark all messages in an interaction as read by this agent. */
+    async markInteractionRead(interactionId) {
+        return await this.request("POST", `/agent/interactions/${interactionId}/messages/read`);
+    }
+    /** Send a typing indicator for an interaction. */
+    async sendInteractionTyping(interactionId, isTyping) {
+        return await this.request("POST", `/agent/interactions/${interactionId}/typing`, { body: { isTyping } });
+    }
+    async listMessages(interactionId, page = 1, pageSize = 50) {
+        const params = { page: String(page), pageSize: String(pageSize) };
+        const data = await this.request("GET", `/agent/interactions/${interactionId}/messages`, { params });
+        const rawItems = data.messages ?? data.items ?? [];
+        const items = rawItems.map((m) => parseMessage(m));
+        // Try to decrypt messages using content wrappings
+        await Promise.all(items.map(async (msg, i) => {
+            const raw = rawItems[i];
+            const wrappings = raw.contentWrappings;
+            if (wrappings?.length && msg.content) {
+                const plain = await this.crypto.decryptWrappedContent(msg.content, wrappings);
+                if (plain !== null)
+                    msg.content = plain;
+            }
+        }));
+        return { items, total: data.total, page: data.page, pageSize: data.pageSize };
+    }
+    /** AD-060: Push agent telemetry activity status + plan to the platform. */
+    async pushTelemetry(opts) {
+        return await this.request("POST", "/agent/activity", { body: opts });
+    }
+    /** AG-041: List webhook delivery history for the agent. */
+    async listWebhookDeliveries(limit = 50) {
+        return await this.request("GET", `/agent/webhooks/deliveries?limit=${limit}`);
+    }
+    /** AG-041: Get webhook delivery statistics for the agent. */
+    async getWebhookDeliveryStats() {
+        return await this.request("GET", "/agent/webhooks/deliveries/stats");
+    }
+    /** AG-041: Manually retry a failed webhook delivery. */
+    async retryWebhookDelivery(deliveryId) {
+        return await this.request("POST", `/agent/webhooks/deliveries/${deliveryId}/retry`);
+    }
+    /** BL-042: Check remaining plan quota for this space. */
+    async getQuota() {
+        return await this.request("GET", "/agent/quota");
+    }
+    /** AD-060: Log an inter-agent communication event for monitoring. */
+    async logComm(opts) {
+        return await this.request("POST", "/agent/comms", { body: opts });
+    }
+    /** Get space encryption info (space public key). */
+    async getEncryptionInfo() {
+        return await this.request("GET", "/agent/encryption-info");
+    }
+    /** Get this agent's currently registered public key. */
+    async getAgentPublicKey() {
+        return await this.request("GET", "/agent/keys/me");
+    }
+    /** Register (or confirm) this agent's public key (idempotent). */
+    async putAgentPublicKey(publicKey, fingerprint) {
+        return await this.request("PUT", "/agent/keys/me", { body: { publicKey, fingerprint } });
+    }
+    /** List space teams for this agent's space. */
+    async listSpaceTeams() {
+        return await this.request("GET", "/agent/space/teams");
+    }
+    /** Get availability status for a specific space user. */
+    async getUserAvailability(userId) {
+        return await this.request("GET", `/agent/space/users/${userId}/availability`);
+    }
+    /** List space users visible to this agent. */
+    async listSpaceUsers(opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts?.offset !== undefined)
+            params.set("offset", String(opts.offset));
+        const qs = params.toString();
+        return await this.request("GET", `/agent/space/users${qs ? `?${qs}` : ""}`);
+    }
+    // -- Conversation Sessions -------------------------------------------------
+    async createConvSession(opts) {
+        const body = {
+            sessionType: opts.sessionType ?? "direct",
+            isPublic: opts.isPublic ?? false,
+        };
+        if (opts.maxGuests !== undefined)
+            body.maxGuests = opts.maxGuests;
+        if (opts.participantIds !== undefined)
+            body.participantIds = opts.participantIds;
+        if (opts.publicMode !== undefined)
+            body.publicMode = opts.publicMode;
+        // If a plaintext title is provided, encrypt it with content wrapping
+        if (opts.title !== undefined) {
+            const result = await this.crypto.encryptWithWrapping(opts.title, opts.spaceKeyId);
+            body.encryptedTitle = result.ciphertext;
+            if (result.wrappings.length > 0) {
+                body.titleContentWrappings = result.wrappings;
+            }
+        }
+        else if (opts.encryptedTitle !== undefined) {
+            body.encryptedTitle = opts.encryptedTitle;
+            if (opts.titleContentWrappings !== undefined) {
+                body.titleContentWrappings = opts.titleContentWrappings;
+            }
+        }
+        const data = await this.request("POST", "/agent/sessions", { body });
+        return parseConvSession(data);
+    }
+    async getConvSession(sessionId) {
+        const data = await this.request("GET", `/agent/sessions/${sessionId}`);
+        return parseConvSession(data);
+    }
+    async listConvSessions(opts) {
+        const params = {};
+        if (opts?.status !== undefined)
+            params.status = opts.status;
+        if (opts?.isPublic !== undefined)
+            params.isPublic = String(opts.isPublic);
+        if (opts?.limit !== undefined)
+            params.limit = String(opts.limit);
+        if (opts?.offset !== undefined)
+            params.offset = String(opts.offset);
+        if (opts?.page !== undefined)
+            params.page = String(opts.page);
+        const data = await this.request("GET", "/agent/sessions", { params });
+        return data.sessions.map((s) => parseConvSession(s));
+    }
+    async closeConvSession(sessionId) {
+        const data = await this.request("POST", `/agent/sessions/${sessionId}/close`);
+        return parseConvSession(data);
+    }
+    /**
+     * Send a message to a conversation session.
+     * The content must be pre-encrypted using encryptAes() with the shared session key.
+     */
+    /**
+     * Send a message in a conv session. Accepts plaintext — encrypts automatically
+     * using the session message key (`{agentPub}:{AES-GCM ciphertext}` format).
+     */
+    async sendConvSessionMessage(sessionId, content) {
+        const encryptedContent = await this.crypto.encryptSessionMessage(content);
+        const data = await this.request("POST", `/agent/sessions/${sessionId}/messages`, { body: { encryptedContent } });
+        return parseConvSessionMessage(data);
+    }
+    /** Send a typing indicator to a conv session (HU-034). */
+    async sendConvSessionTyping(sessionId, typing) {
+        await this.request("POST", `/agent/sessions/${sessionId}/typing`, { body: { typing } });
+    }
+    /** Edit a previously sent conv session message. */
+    async editConvSessionMessage(sessionId, msgId, encryptedContent) {
+        const data = await this.request("PATCH", `/agent/sessions/${sessionId}/messages/${msgId}`, { body: { encryptedContent } });
+        return parseConvSessionMessage(data);
+    }
+    /** Soft-delete a conv session message. */
+    async deleteConvSessionMessage(sessionId, msgId) {
+        return await this.request("DELETE", `/agent/sessions/${sessionId}/messages/${msgId}`);
+    }
+    async listConvSessionTimeline(sessionId, opts) {
+        const params = {};
+        if (opts?.limit !== undefined)
+            params.limit = String(opts.limit);
+        if (opts?.before !== undefined)
+            params.before = opts.before;
+        const result = await this.request("GET", `/agent/sessions/${sessionId}/timeline`, { params });
+        // Decrypt timeline items (session messages + interaction fields)
+        if (Array.isArray(result.items)) {
+            await Promise.all(result.items.map(async (item) => {
+                if (item.kind === "message" && typeof item.encryptedContent === "string") {
+                    const plain = await this.crypto.decryptSessionMessage(item.encryptedContent);
+                    if (plain !== null)
+                        item.content = plain;
+                    else
+                        item.content = "[Encrypted]";
+                }
+                if (item.kind === "interaction") {
+                    const wrappings = item.contentWrappings;
+                    if (wrappings?.length) {
+                        for (const field of ["encryptedTitle", "encryptedDescription", "encryptedOptions", "encryptedFormSchema", "encryptedContext"]) {
+                            if (typeof item[field] === "string") {
+                                const plain = await this.crypto.decryptWrappedContent(item[field], wrappings);
+                                if (plain !== null) {
+                                    const readableKey = field.replace(/^encrypted/, "").replace(/^./, (c) => c.toLowerCase());
+                                    item[readableKey] = plain;
+                                }
+                            }
+                        }
+                    }
+                }
+            }));
+        }
+        return result;
+    }
+    async addConvSessionParticipant(sessionId, userId, role = "member") {
+        const data = await this.request("POST", `/agent/sessions/${sessionId}/participants`, { body: { userId, role } });
+        return data.participant;
+    }
+    async removeConvSessionParticipant(sessionId, userId) {
+        await this.request("DELETE", `/agent/sessions/${sessionId}/participants/${userId}`);
+    }
+    /** Update a participant's role in a conversation session. */
+    async updateConvSessionParticipantRole(sessionId, userId, role) {
+        return await this.request("PATCH", `/agent/sessions/${sessionId}/participants/${userId}`, { body: { role } });
+    }
+    async listConvSessionParticipants(sessionId) {
+        const data = await this.request("GET", `/agent/sessions/${sessionId}/participants`);
+        return data.participants;
+    }
+    async createGuestToken(sessionId, opts) {
+        const data = await this.request("POST", `/agent/sessions/${sessionId}/guest-tokens`, { body: opts ?? {} });
+        return parseGuestToken(data);
+    }
+    async listGuestTokens(sessionId) {
+        const data = await this.request("GET", `/agent/sessions/${sessionId}/guest-tokens`);
+        return data.tokens.map((t) => parseGuestToken(t));
+    }
+    async revokeGuestToken(sessionId, tokenId) {
+        await this.request("DELETE", `/human/sessions/${sessionId}/guest-tokens/${tokenId}`);
+    }
+    /** AG-060: Create multiple interactions in a single API call. */
+    async createInteractionBatch(interactions) {
+        const items = await Promise.all(interactions.map(async (opts) => {
+            const { encrypted, contentWrappings } = await this.encryptFields({
+                encryptedTitle: opts.title,
+                encryptedDescription: opts.description,
+                encryptedOptions: opts.options,
+                encryptedContext: opts.context,
+            });
+            const body = {
+                type: opts.type,
+                priority: opts.priority ?? "normal",
+                contentWrappings,
+                ...encrypted,
+            };
+            if (opts.routeToUser !== undefined)
+                body.routeToUser = opts.routeToUser;
+            if (opts.routeToTeam !== undefined)
+                body.routeToTeam = opts.routeToTeam;
+            if (opts.deadlineMinutes !== undefined)
+                body.deadlineMinutes = opts.deadlineMinutes;
+            if (opts.convSessionId !== undefined)
+                body.convSessionId = opts.convSessionId;
+            return body;
+        }));
+        return this.request("POST", "/agent/interactions/batch", { body: { interactions: items } });
+    }
+    /** Archive a conversation session. */
+    async archiveConvSession(sessionId) {
+        const data = await this.request("POST", `/agent/sessions/${sessionId}/archive`);
+        return parseConvSession(data);
+    }
+    /** Create a group interaction involving multiple participants (AG-061). */
+    async createGroupInteraction(opts, participants) {
+        const { encrypted, contentWrappings } = await this.encryptFields({
+            encryptedTitle: opts.title,
+            encryptedDescription: opts.description,
+            encryptedContext: opts.context,
+        });
+        const body = {
+            type: opts.type,
+            priority: opts.priority ?? "normal",
+            participants,
+            contentWrappings,
+            ...encrypted,
+        };
+        if (opts.routeToUser !== undefined)
+            body.routeToUser = opts.routeToUser;
+        if (opts.routeToTeam !== undefined)
+            body.routeToTeam = opts.routeToTeam;
+        if (opts.deadlineMinutes !== undefined)
+            body.deadlineMinutes = opts.deadlineMinutes;
+        if (opts.callbackUrl !== undefined)
+            body.callbackUrl = opts.callbackUrl;
+        return this.request("POST", "/agent/interactions/group", { body });
+    }
+    /** Add a reference from one interaction to another (AG-062). */
+    async addInteractionReference(interactionId, targetInteractionId, opts) {
+        return this.request("POST", `/agent/interactions/${interactionId}/references`, {
+            body: { targetInteractionId, referenceType: opts?.referenceType, note: opts?.note },
+        });
+    }
+    /** List all references for an interaction (AG-062). */
+    async listInteractionReferences(interactionId) {
+        return this.request("GET", `/agent/interactions/${interactionId}/references`);
+    }
+    /** Remove an interaction reference by its ID (AG-062). */
+    async removeInteractionReference(interactionId, refId) {
+        return this.request("DELETE", `/agent/interactions/${interactionId}/references/${refId}`);
+    }
+    // -- Public agent routes (no auth required) ---------------------------------
+    /** Get public metadata for a public agent by slug. */
+    async getPublicAgentInfo(slug) {
+        return this.request("GET", `/public/${slug}/info`);
+    }
+    /** Create an interaction as a public (anonymous) user on a public agent. */
+    async createPublicInteraction(slug, opts) {
+        return this.request("POST", `/public/${slug}/interactions`, { body: opts });
+    }
+    /** Get the status of a public interaction by slug + ID. */
+    async getPublicInteraction(slug, interactionId) {
+        return this.request("GET", `/public/${slug}/interactions/${interactionId}`);
+    }
+    /** Long-poll for a response on a public interaction (returns when responded/completed/cancelled/expired). */
+    async awaitPublicInteraction(slug, interactionId, timeoutMs = 30000) {
+        return this.request("GET", `/public/${slug}/interactions/${interactionId}/await`, {
+            params: { timeout: String(timeoutMs) },
+            timeout: timeoutMs + 5000,
+        });
+    }
+    /** Send a message to a public interaction as an anonymous user. */
+    async sendPublicMessage(slug, interactionId, encryptedContent) {
+        return this.request("POST", `/public/${slug}/interactions/${interactionId}/messages`, { body: { encryptedContent } });
+    }
+    /** List interactions created on a public agent (paginated). */
+    async listPublicInteractions(slug, opts) {
+        const params = {};
+        if (opts?.page !== undefined)
+            params.page = String(opts.page);
+        if (opts?.pageSize !== undefined)
+            params.pageSize = String(opts.pageSize);
+        return this.request("GET", `/public/${slug}/interactions`, Object.keys(params).length > 0 ? { params } : undefined);
+    }
+    /** Cancel a public interaction (anonymous user side). */
+    async cancelPublicInteraction(slug, interactionId) {
+        return this.request("DELETE", `/public/${slug}/interactions/${interactionId}`);
+    }
+    /** Get the transition log for a public interaction. */
+    async getPublicInteractionTransitions(slug, interactionId) {
+        return this.request("GET", `/public/${slug}/interactions/${interactionId}/transitions`);
+    }
+    /** Look up a public session by its public token (no auth required). */
+    async getPublicSession(publicToken) {
+        return this.request("GET", `/public/sessions/${publicToken}`);
+    }
+    /** Join a public session as a guest using its public token. */
+    async joinPublicSession(publicToken, displayName) {
+        return this.request("POST", `/public/sessions/${publicToken}/join`, { body: { displayName } });
+    }
+    // -- Human Interaction Detail -----------------------------------------------
+    /** Get a human-facing interaction detail view. */
+    async getHumanInteraction(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}`);
+    }
+    /** Mark an interaction as viewed by the authenticated user. */
+    async viewInteraction(interactionId) {
+        return this.request("POST", `/human/interactions/${interactionId}/view`);
+    }
+    /** Submit a response to an interaction. */
+    async respondToHumanInteraction(interactionId, opts) {
+        return this.request("POST", `/human/interactions/${interactionId}/respond`, { body: opts });
+    }
+    /** Snooze an interaction until a given ISO datetime. */
+    async snoozeInteraction(interactionId, snoozedUntil) {
+        return this.request("POST", `/human/interactions/${interactionId}/snooze`, { body: { snoozedUntil } });
+    }
+    /** Toggle the pinned state of an interaction. */
+    async pinInteraction(interactionId, pinned) {
+        return this.request("POST", `/human/interactions/${interactionId}/pin`, { body: { pinned } });
+    }
+    // -- Human Inbox / Feed ----------------------------------------------------
+    // getInbox removed -- use getFeed with view param
+    /** Get the human user's activity feed (all interactions). */
+    async getFeed(opts) {
+        const params = new URLSearchParams();
+        if (opts?.page)
+            params.set("page", String(opts.page));
+        if (opts?.pageSize)
+            params.set("pageSize", String(opts.pageSize));
+        if (opts?.view)
+            params.set("view", opts.view);
+        if (opts?.q)
+            params.set("q", opts.q);
+        if (opts?.type)
+            params.set("type", opts.type);
+        if (opts?.priority)
+            params.set("priority", opts.priority);
+        if (opts?.pinned !== undefined)
+            params.set("pinned", String(opts.pinned));
+        if (opts?.agentId)
+            params.set("agentId", opts.agentId);
+        const qs = params.toString() ? `?${params.toString()}` : "";
+        return this.request("GET", `/human/feed${qs}`);
+    }
+    // searchInteractions removed -- use getFeed with q param
+    // getHistory removed -- use getFeed with view param
+    /** Get badge counts (e.g. open interactions) for the authenticated user. */
+    async getBadges() {
+        return this.request("GET", "/human/badges");
+    }
+    // -- Account ----------------------------------------------------------------
+    /** Get the authenticated user's current availability status. */
+    async getMyAvailability() {
+        return this.request("GET", "/human/availability");
+    }
+    /** Update the authenticated user's availability status. */
+    async updateMyAvailability(status) {
+        return this.request("PATCH", "/human/availability", { body: { status } });
+    }
+    /** List delegation rules for the authenticated user. */
+    async listDelegations() {
+        return this.request("GET", "/human/delegations");
+    }
+    /** Create a delegation rule for the authenticated user. */
+    async createDelegation(opts) {
+        return this.request("POST", "/human/delegations", { body: opts });
+    }
+    /** Remove a delegation rule by delegateId. */
+    async deleteDelegation(delegateId) {
+        return this.request("DELETE", `/human/delegations/${delegateId}`);
+    }
+    // -- Notifications ----------------------------------------------------------
+    /** List sent notifications for the authenticated user. */
+    async listNotifications() {
+        return this.request("GET", "/human/notifications");
+    }
+    /** Get notification preferences for the authenticated user. */
+    async getNotificationPreferences() {
+        return this.request("GET", "/human/notifications/preferences");
+    }
+    /** Update notification preference for a specific channel. */
+    async updateNotificationPreference(channel, opts) {
+        return this.request("PUT", `/human/notifications/preferences/${channel}`, { body: opts });
+    }
+    /** Register a push token for the authenticated user's device. */
+    async registerPushToken(opts) {
+        return this.request("POST", "/human/notifications/push-tokens", { body: opts });
+    }
+    /** Remove the push token for the authenticated user's device. */
+    async deletePushToken(opts) {
+        return this.request("DELETE", "/human/notifications/push-tokens", { body: opts });
+    }
+    /** Save (upsert) a response draft for an interaction. */
+    async saveDraft(interactionId, encryptedDraft) {
+        return this.request("PUT", `/human/interactions/${interactionId}/draft`, { body: { encryptedDraft } });
+    }
+    /** Get the saved response draft for an interaction. */
+    async getDraft(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/draft`);
+    }
+    /** Delete the saved response draft for an interaction. */
+    async deleteDraft(interactionId) {
+        return this.request("DELETE", `/human/interactions/${interactionId}/draft`);
+    }
+    /** Unsnooze an interaction before its scheduled snooze time. */
+    async unsnoozeInteraction(interactionId) {
+        return this.request("POST", `/human/interactions/${interactionId}/unsnooze`);
+    }
+    // -- Collaboration (milestone alerts + approval chain) -----------------------
+    /** Create a milestone alert for an interaction. */
+    async createMilestoneAlert(interactionId, opts) {
+        return this.request("POST", `/human/interactions/${interactionId}/milestone-alerts`, { body: opts });
+    }
+    /** List milestone alerts for an interaction. */
+    async listMilestoneAlerts(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/milestone-alerts`);
+    }
+    /** Delete a milestone alert. */
+    async deleteMilestoneAlert(interactionId, alertId) {
+        return this.request("DELETE", `/human/interactions/${interactionId}/milestone-alerts/${alertId}`);
+    }
+    /** Get the approval chain for an interaction. */
+    async getApprovalChain(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/approval-chain`);
+    }
+    /** Respond to an approval chain step. */
+    async respondToApprovalChain(interactionId, opts) {
+        return this.request("POST", `/human/interactions/${interactionId}/approval-chain/respond`, { body: opts });
+    }
+    // -- Phase 628: Comments + review feedback ------------------------------------
+    /** List comments on an interaction. */
+    async listInteractionComments(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/comments`);
+    }
+    /** Post a comment on an interaction. */
+    async createInteractionComment(interactionId, opts) {
+        return this.request("POST", `/human/interactions/${interactionId}/comments`, { body: opts });
+    }
+    /** Mark a comment as resolved. */
+    async resolveInteractionComment(interactionId, commentId) {
+        return this.request("PATCH", `/human/interactions/${interactionId}/comments/${commentId}/resolve`);
+    }
+    /** Delete a comment. */
+    async deleteInteractionComment(interactionId, commentId) {
+        return this.request("DELETE", `/human/interactions/${interactionId}/comments/${commentId}`);
+    }
+    /** Submit review feedback for an interaction. */
+    async submitReviewFeedback(interactionId, opts) {
+        return this.request("POST", `/human/interactions/${interactionId}/review-feedback`, { body: opts });
+    }
+    // -- Phase 629: Voting + tags --------------------------------------------------
+    /** Cast a vote on an interaction. */
+    async voteOnInteraction(interactionId, opts) {
+        return this.request("POST", `/human/interactions/${interactionId}/vote`, { body: opts });
+    }
+    /** Get aggregate vote results for an interaction. */
+    async getVoteResults(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/vote/results`);
+    }
+    /** Get the current user's vote on an interaction. */
+    async getMyVote(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/vote/mine`);
+    }
+    /** List tags on an interaction. */
+    async getInteractionTags(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/tags`);
+    }
+    /** Add a tag to an interaction. */
+    async addInteractionTag(interactionId, tag) {
+        return this.request("POST", `/human/interactions/${interactionId}/tags`, { body: { tag } });
+    }
+    // -- Phase 630: More tags + response templates ---------------------------------
+    /** Remove a tag from an interaction. */
+    async deleteInteractionTag(interactionId, tag) {
+        return this.request("DELETE", `/human/interactions/${interactionId}/tags/${encodeURIComponent(tag)}`);
+    }
+    /** List all space-wide tags. */
+    async listSpaceTags() {
+        return this.request("GET", "/human/tags");
+    }
+    /** List response templates for the current user. */
+    async listResponseTemplates() {
+        return this.request("GET", "/human/response-templates");
+    }
+    /** Create a response template. */
+    async createResponseTemplate(opts) {
+        return this.request("POST", "/human/response-templates", { body: opts });
+    }
+    /** Delete a response template. */
+    async deleteResponseTemplate(templateId) {
+        return this.request("DELETE", `/human/response-templates/${templateId}`);
+    }
+    // -- Phase 631: Review feedback + template use + message routes ----------------
+    /** Get review feedback for an interaction. */
+    async getReviewFeedback(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/review-feedback`);
+    }
+    /** Use a response template (increments usage count). */
+    async useResponseTemplate(templateId) {
+        return this.request("POST", `/human/response-templates/${templateId}/use`);
+    }
+    /** List messages for a human interaction. */
+    async listInteractionMessages(interactionId, opts) {
+        const params = {};
+        if (opts?.before !== undefined)
+            params.before = opts.before;
+        if (opts?.limit !== undefined)
+            params.limit = String(opts.limit);
+        return this.request("GET", `/human/interactions/${interactionId}/messages`, { params });
+    }
+    /** Send a message to a human interaction thread. */
+    async sendInteractionMessage(interactionId, opts) {
+        return this.request("POST", `/human/interactions/${interactionId}/messages`, { body: opts });
+    }
+    /** Mark messages as read for an interaction. */
+    async markMessagesRead(interactionId) {
+        return this.request("POST", `/human/interactions/${interactionId}/messages/read`);
+    }
+    // -- Phase 632: Reactions + agent activity + references ------------------------
+    /** Get aggregated reactions for all messages in an interaction. */
+    async getInteractionReactions(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/reactions`);
+    }
+    /** Add a reaction to a specific message. */
+    async addMessageReaction(interactionId, messageId, emoji) {
+        return this.request("POST", `/human/interactions/${interactionId}/messages/${messageId}/reactions`, { body: { emoji } });
+    }
+    /** Remove a reaction from a specific message. */
+    async removeMessageReaction(interactionId, messageId, emoji) {
+        return this.request("DELETE", `/human/interactions/${interactionId}/messages/${messageId}/reactions/${encodeURIComponent(emoji)}`);
+    }
+    /** Get agent activity data for the space (for human dashboard). */
+    async getAgentActivity() {
+        return this.request("GET", "/human/agents/activity");
+    }
+    /** List interaction references for a human interaction. */
+    async listHumanInteractionReferences(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/references`);
+    }
+    // -- Phase 633: References + usage + feature gates + presence ------------------
+    /** Add a reference link between two interactions. */
+    async addHumanInteractionReference(interactionId, opts) {
+        return this.request("POST", `/human/interactions/${interactionId}/references`, { body: opts });
+    }
+    /** Get current usage and quota for the space. */
+    async getUsage() {
+        return this.request("GET", "/human/usage");
+    }
+    /** Get feature gate flags for the current user. */
+    async getFeatureGates() {
+        return this.request("GET", "/human/feature-gates");
+    }
+    /** Track that the current user is viewing an interaction. */
+    async trackInteractionViewing(interactionId) {
+        return this.request("POST", `/human/interactions/${interactionId}/viewing`);
+    }
+    /** Get who is currently viewing an interaction. */
+    async getInteractionViewers(interactionId) {
+        return this.request("GET", `/human/interactions/${interactionId}/viewers`);
+    }
+    // -- Phase 634: More account routes + inbox grouped + members ------------------
+    /** Stop tracking viewing presence for an interaction. */
+    async stopTrackingViewing(interactionId) {
+        return this.request("DELETE", `/human/interactions/${interactionId}/viewing`);
+    }
+    /** Get human-assigned tasks (interactions requiring action). */
+    async getHumanTasks(opts) {
+        const params = {};
+        if (opts?.page !== undefined)
+            params.page = String(opts.page);
+        if (opts?.pageSize !== undefined)
+            params.pageSize = String(opts.pageSize);
+        return this.request("GET", "/human/tasks", { params });
+    }
+    // getInboxGrouped removed -- use getFeed with view param
+    /** List space members (humans). */
+    async getHumanMembers(opts) {
+        const params = {};
+        if (opts?.page !== undefined)
+            params.page = String(opts.page);
+        if (opts?.pageSize !== undefined)
+            params.pageSize = String(opts.pageSize);
+        return this.request("GET", "/human/members", { params });
+    }
+    /** Get aggregated notification digest for the current user. */
+    async getNotificationDigest(opts) {
+        const params = {};
+        if (opts?.since !== undefined)
+            params.since = opts.since;
+        return this.request("GET", "/human/notifications/digest", { params });
+    }
+    // -- Channels ---------------------------------------------------------------
+    /** Create a new agent-to-agent channel. */
+    async createChannel(opts) {
+        const body = {};
+        if (opts.name !== undefined) {
+            const w = await this.crypto.encryptWithWrapping(opts.name);
+            body.encryptedName = w.ciphertext;
+            if (w.wrappings.length > 0)
+                body.nameContentWrappings = w.wrappings;
+        }
+        if (opts.description !== undefined) {
+            const w = await this.crypto.encryptWithWrapping(opts.description);
+            body.encryptedDescription = w.ciphertext;
+            if (w.wrappings.length > 0)
+                body.descriptionContentWrappings = w.wrappings;
+        }
+        if (opts.externalId !== undefined)
+            body.externalId = opts.externalId;
+        if (opts.participantAgentIds !== undefined)
+            body.participantAgentIds = opts.participantAgentIds;
+        const data = await this.request("POST", "/agent/channels", { body });
+        return parseChannel(data.channel);
+    }
+    /** Get a channel by ID. */
+    async getChannel(channelId) {
+        const data = await this.request("GET", `/agent/channels/${channelId}`);
+        return parseChannel(data.channel);
+    }
+    /** List channels with optional filters. */
+    async listChannels(filters) {
+        const params = {};
+        if (filters?.status !== undefined)
+            params.status = filters.status;
+        params.page = String(filters?.page ?? 1);
+        params.pageSize = String(filters?.pageSize ?? 20);
+        const data = await this.request("GET", "/agent/channels", { params });
+        return {
+            items: data.items.map((i) => parseChannel(i)),
+            total: data.total,
+            page: data.page,
+            pageSize: data.pageSize,
+        };
+    }
+    /** Close a channel. */
+    async closeChannel(channelId) {
+        const data = await this.request("POST", `/agent/channels/${channelId}/close`);
+        return parseChannel(data.channel);
+    }
+    /** Add a participant to a channel. */
+    async addChannelParticipant(channelId, agentId) {
+        const data = await this.request("POST", `/agent/channels/${channelId}/participants`, { body: { agentId } });
+        return parseChannelParticipant(data.participant);
+    }
+    /** Remove a participant from a channel. */
+    async removeChannelParticipant(channelId, agentId) {
+        return this.request("DELETE", `/agent/channels/${channelId}/participants/${agentId}`);
+    }
+    /** Send a message in a channel. */
+    async sendChannelMessage(channelId, content) {
+        const wrapped = await this.crypto.encryptWithWrapping(content);
+        const body = {
+            encryptedContent: wrapped.ciphertext,
+        };
+        if (wrapped.wrappings.length > 0)
+            body.contentWrappings = wrapped.wrappings;
+        const data = await this.request("POST", `/agent/channels/${channelId}/messages`, { body });
+        return parseChannelMessage(data.message);
+    }
+    /** List messages in a channel. */
+    async listChannelMessages(channelId, opts) {
+        const params = {};
+        if (opts?.page !== undefined)
+            params.page = String(opts.page);
+        if (opts?.pageSize !== undefined)
+            params.pageSize = String(opts.pageSize);
+        if (opts?.before !== undefined)
+            params.before = opts.before;
+        if (opts?.after !== undefined)
+            params.after = opts.after;
+        const data = await this.request("GET", `/agent/channels/${channelId}/messages`, { params });
+        const items = data.items.map((m) => parseChannelMessage(m));
+        // Try to decrypt each message using content wrappings
+        await Promise.all(items.map(async (msg) => {
+            const raw = msg.raw;
+            const wrappings = raw.contentWrappings;
+            if (wrappings?.length && msg.encryptedContent) {
+                const plain = await this.crypto.decryptWrappedContent(msg.encryptedContent, wrappings);
+                if (plain !== null)
+                    msg.content = plain;
+            }
+        }));
+        return { items, total: data.total, page: data.page, pageSize: data.pageSize };
+    }
+    /** Log a detailed activity entry visible to the human (thinking, tool calls, decisions). */
+    async logActivity(entry) {
+        return this.request("POST", "/agent/activity/log", { body: entry });
+    }
+    /** List participants in a channel. */
+    async listChannelParticipants(channelId) {
+        const data = await this.request("GET", `/agent/channels/${channelId}/participants`);
+        return { participants: data.participants.map((p) => parseChannelParticipant(p)) };
+    }
+    // -- Agent Commands ----------------------------------------------------------
+    /** Register or update commands for this agent (batch, max 50). */
+    async registerCommands(commands) {
+        const items = await Promise.all(commands.map(async (cmd) => {
+            const { encrypted, contentWrappings } = await this.encryptFields({
+                encryptedDescription: cmd.description,
+                encryptedArgumentHint: cmd.argumentHint,
+                encryptedParameters: cmd.parameters ? JSON.stringify(cmd.parameters) : undefined,
+            });
+            return { name: cmd.name, contentWrappings, annotations: cmd.annotations, ...encrypted };
+        }));
+        return this.request("POST", "/agent/commands", { body: { commands: items } });
+    }
+    /** List all commands registered by this agent. */
+    async listCommands() {
+        return this.request("GET", "/agent/commands");
+    }
+    /** Update a registered command by name. */
+    async updateCommand(name, updates) {
+        const fields = {};
+        if (updates.description !== undefined)
+            fields.encryptedDescription = updates.description;
+        if (updates.argumentHint !== undefined)
+            fields.encryptedArgumentHint = updates.argumentHint;
+        if (updates.parameters !== undefined)
+            fields.encryptedParameters = JSON.stringify(updates.parameters);
+        const { encrypted, contentWrappings } = await this.encryptFields(fields);
+        const body = { contentWrappings, ...encrypted };
+        if (updates.annotations !== undefined)
+            body.annotations = updates.annotations;
+        return this.request("PUT", `/agent/commands/${name}`, { body });
+    }
+    /** Remove a registered command by name. */
+    async removeCommand(name) {
+        return this.request("DELETE", `/agent/commands/${name}`);
+    }
+    /** Poll for pending command invocations. */
+    async getInvocations(opts) {
+        const params = {};
+        if (opts?.status)
+            params.status = opts.status;
+        if (opts?.convSessionId)
+            params.convSessionId = opts.convSessionId;
+        if (opts?.limit !== undefined)
+            params.limit = String(opts.limit);
+        if (opts?.offset !== undefined)
+            params.offset = String(opts.offset);
+        return this.request("GET", "/agent/commands/invocations", Object.keys(params).length > 0 ? { params } : undefined);
+    }
+    /** Acknowledge a command invocation (pending -> running). */
+    async ackInvocation(invocationId) {
+        return this.request("POST", `/agent/commands/invocations/${invocationId}/ack`);
+    }
+    /** Mark an invocation as completed. */
+    async completeInvocation(invocationId, opts) {
+        const body = {};
+        if (opts?.result) {
+            const { encrypted, contentWrappings } = await this.encryptFields({ encryptedResult: opts.result });
+            Object.assign(body, encrypted);
+            body.resultWrappings = contentWrappings;
+        }
+        return this.request("POST", `/agent/commands/invocations/${invocationId}/complete`, { body });
+    }
+    /** Mark an invocation as failed. */
+    async failInvocation(invocationId, opts) {
+        const body = {};
+        if (opts?.error) {
+            const { encrypted, contentWrappings } = await this.encryptFields({ encryptedResult: opts.error });
+            Object.assign(body, encrypted);
+            body.resultWrappings = contentWrappings;
+        }
+        return this.request("POST", `/agent/commands/invocations/${invocationId}/fail`, { body });
+    }
+    // -- Crypto -----------------------------------------------------------------
+    static generateKeyPair() {
+        return generateKeyPair();
+    }
+    /** Encrypt plaintext with AES-256-GCM for session messages. */
+    static encryptAes(plaintext, keyBase64) {
+        return encryptAes(plaintext, keyBase64);
+    }
+    /** Decrypt AES-256-GCM ciphertext from session messages. */
+    static decryptAes(ciphertextBase64, keyBase64) {
+        return decryptAes(ciphertextBase64, keyBase64);
+    }
+}
+/**
+ * Validate a form schema JSON string before encrypting.
+ * - Must be valid JSON with a non-empty `fields` array.
+ * - select / multi-select / radio fields must have at least 2 options.
+ */
+function validateFormSchema(schemaJson) {
+    if (schemaJson === undefined || schemaJson.trim() === "") {
+        throw new Error("formSchema must not be empty.");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(schemaJson);
+    }
+    catch {
+        throw new Error("formSchema must be valid JSON.");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("formSchema must be a JSON object.");
+    }
+    const schema = parsed;
+    const fields = schema["fields"];
+    if (!Array.isArray(fields) || fields.length === 0) {
+        throw new Error("formSchema must contain a non-empty 'fields' array. " +
+            "A form requires at least one input field.");
+    }
+    for (const field of fields) {
+        if (typeof field !== "object" || field === null)
+            continue;
+        const f = field;
+        const type = f["type"];
+        if (type === "select" || type === "multi-select" || type === "radio") {
+            const options = f["options"];
+            if (!Array.isArray(options) || options.length < 2) {
+                const name = f["name"] ?? "(unnamed)";
+                throw new Error(`Form field '${name}' of type '${type}' must have at least 2 options.`);
+            }
+        }
+    }
+}
+/**
+ * Return all wrappings as-is. Each encrypted field has its own random content
+ * key, so every wrapping is unique even when scope + recipientKeyId match.
+ * The frontend tries each wrapping until one successfully decrypts.
+ */