hiloop-sdk 0.8.5 → 0.8.7

package/dist/client.d.ts

@@ -5,6 +5,16 @@ export declare class HiloopError extends Error {
     statusCode: number;
     constructor(statusCode: number, message: string);
 }
+export interface SendOptions {
+    agentName?: string;
+    priority?: string;
+    deadlineMinutes?: number;
+    replyToMessageId?: string;
+    /** Client-supplied correlation key (e.g. tool_use_id). Unique per session. */
+    referenceId?: string;
+    /** Resolve a referenceId to a message and set replyToMessageId automatically. */
+    replyToReferenceId?: string;
+}
 export interface HiloopClientOptions {
     apiKey: string;
     /** Agent name. Auto-creates the agent if it doesn't exist (space API keys only). */
@@ -137,19 +147,19 @@ export declare class HiloopClient {
         page?: number;
     }): Promise<ConvSession[]>;
     closeConvSession(sessionId: string): Promise<ConvSession>;
+    /** Options for send / sendText. */
+    private sendComponents;
     /**
-     * Send a message to a session. Accepts plaintext content and optional
-     * rich components. Encrypts content and components automatically.
-     *
-     * This is the primary method for agent-to-human communication.
+     * Send a plain text message. Wraps the text in a `{ type: "text" }` component.
+     * Agent and session are auto-created if they don't exist.
      */
-    sendMessage(sessionId: string, content: string, opts?: {
-        components?: ComponentNode[];
-        priority?: string;
-        deadlineMinutes?: number;
-        replyToMessageId?: string;
-        agentName?: string;
-    }): Promise<SessionMessage>;
+    sendText(sessionId: string, text: string, opts?: SendOptions): Promise<SessionMessage>;
+    /**
+     * Send a message composed of components. Everything is encrypted in the
+     * component tree — no separate content field.
+     * Agent and session are auto-created if they don't exist.
+     */
+    send(sessionId: string, components: ComponentNode[], opts?: SendOptions): Promise<SessionMessage>;
     /**
      * Long-poll for a response to a specific message.
      * Returns the updated message once the human has responded, or after timeout.
@@ -340,11 +350,12 @@ export declare class HiloopClient {
     decryptSessionMessage(encryptedContent: string): Promise<string | null>;
     /**
      * Decrypt a webhook payload in place.
-     * Decrypts encryptedContent from session messages.
-     * Returns the payload with an added `content` field.
+     * Decrypts encryptedComponents (and legacy encryptedContent) from session messages.
+     * Returns the payload with added `content` and `components` fields.
      */
     decryptWebhookPayload<T extends Record<string, unknown>>(payload: T): Promise<T & {
         content?: string;
+        components?: ComponentNode[];
     }>;
     static generateKeyPair(): KeyPair;
     /** Encrypt plaintext with AES-256-GCM for session messages. */

package/dist/client.js

@@ -317,25 +317,17 @@ export class HiloopClient {
         return parseConvSession(data);
     }
     // -- Unified Message API ----------------------------------------------------
-    /**
-     * Send a message to a session. Accepts plaintext content and optional
-     * rich components. Encrypts content and components automatically.
-     *
-     * This is the primary method for agent-to-human communication.
-     */
-    async sendMessage(sessionId, content, opts) {
+    /** Options for send / sendText. */
+    async sendComponents(sessionId, components, opts) {
         await this.ensureInitialized(opts?.agentName);
-        const encryptedContent = await this.crypto.encryptSessionMessage(content);
-        const body = { encryptedContent };
-        if (opts?.components && opts.components.length > 0) {
-            body.encryptedComponents = await this.crypto.encryptSessionMessage(JSON.stringify(opts.components));
-            // Extract metadata from components for server-side routing
-            const hasResponseRequired = opts.components.some((n) => n.type === "button_group" &&
-                n.data?.responseRequired === true);
-            if (hasResponseRequired) {
-                body.responseRequired = true;
-                body.category = "decide";
-            }
+        const encryptedComponents = await this.crypto.encryptSessionMessage(JSON.stringify(components));
+        const body = { encryptedComponents };
+        // Extract metadata from components for server-side routing
+        const hasResponseRequired = components.some((n) => n.type === "button_group" &&
+            n.data?.responseRequired === true);
+        if (hasResponseRequired) {
+            body.responseRequired = true;
+            body.category = "decide";
         }
         if (opts?.priority)
             body.priority = opts.priority;
@@ -343,9 +335,28 @@ export class HiloopClient {
             body.deadlineMinutes = opts.deadlineMinutes;
         if (opts?.replyToMessageId)
             body.replyToMessageId = opts.replyToMessageId;
+        if (opts?.referenceId)
+            body.referenceId = opts.referenceId;
+        if (opts?.replyToReferenceId)
+            body.replyToReferenceId = opts.replyToReferenceId;
         const data = await this.request("POST", `/agent/sessions/${sessionId}/messages`, { body, agentName: opts?.agentName });
         return parseSessionMessage(data);
     }
+    /**
+     * Send a plain text message. Wraps the text in a `{ type: "text" }` component.
+     * Agent and session are auto-created if they don't exist.
+     */
+    async sendText(sessionId, text, opts) {
+        return this.sendComponents(sessionId, [{ type: "text", data: { content: text } }], opts);
+    }
+    /**
+     * Send a message composed of components. Everything is encrypted in the
+     * component tree — no separate content field.
+     * Agent and session are auto-created if they don't exist.
+     */
+    async send(sessionId, components, opts) {
+        return this.sendComponents(sessionId, components, opts);
+    }
     /**
      * Long-poll for a response to a specific message.
      * Returns the updated message once the human has responded, or after timeout.
@@ -396,7 +407,25 @@ export class HiloopClient {
         // Decrypt timeline items (session messages)
         if (Array.isArray(result.items)) {
             await Promise.all(result.items.map(async (item) => {
-                if (typeof item.encryptedContent === "string") {
+                // Decrypt components (new format)
+                if (typeof item.encryptedComponents === "string") {
+                    const plain = await this.crypto.decryptSessionMessage(item.encryptedComponents);
+                    if (plain !== null) {
+                        try {
+                            const nodes = JSON.parse(plain);
+                            item.components = nodes;
+                            // Extract text from first text component for convenience
+                            const textNode = nodes.find((n) => n.type === "text");
+                            if (textNode)
+                                item.content = textNode.data?.content ?? null;
+                        }
+                        catch {
+                            item.components = [];
+                        }
+                    }
+                }
+                // Fall back to legacy encryptedContent
+                if (item.content === undefined && typeof item.encryptedContent === "string") {
                     const plain = await this.crypto.decryptSessionMessage(item.encryptedContent);
                     if (plain !== null)
                         item.content = plain;
@@ -660,14 +689,28 @@ export class HiloopClient {
     }
     /**
      * Decrypt a webhook payload in place.
-     * Decrypts encryptedContent from session messages.
-     * Returns the payload with an added `content` field.
+     * Decrypts encryptedComponents (and legacy encryptedContent) from session messages.
+     * Returns the payload with added `content` and `components` fields.
      */
     async decryptWebhookPayload(payload) {
         await this.ensureInitialized();
         const result = { ...payload };
-        // Session message
-        if (typeof payload.encryptedContent === "string") {
+        // New format: components
+        if (typeof payload.encryptedComponents === "string") {
+            const plain = await this.crypto.decryptSessionMessage(payload.encryptedComponents);
+            if (plain !== null) {
+                try {
+                    const nodes = JSON.parse(plain);
+                    result.components = nodes;
+                    const textNode = nodes.find((n) => n.type === "text");
+                    if (textNode)
+                        result.content = textNode.data?.content ?? undefined;
+                }
+                catch { /* ignore */ }
+            }
+        }
+        // Legacy: encryptedContent
+        if (result.content === undefined && typeof payload.encryptedContent === "string") {
             const plain = await this.crypto.decryptSessionMessage(payload.encryptedContent);
             if (plain !== null)
                 result.content = plain;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { HiloopClient, HiloopError } from "./client.js";
-export type { HiloopClientOptions } from "./client.js";
+export type { HiloopClientOptions, SendOptions } from "./client.js";
 export { HiloopWsClient } from "./ws.js";
 export type { HiloopWsClientOptions, WsEventType, WsEventHandler } from "./ws.js";
 export { generateKeyPair, deriveKeyPairFromApiKey, computeFingerprint, encrypt, decrypt, encryptAes, decryptAes, deriveWrappingKey, CryptoContext } from "./crypto.js";

package/dist/types.d.ts

@@ -139,6 +139,7 @@ export interface SessionMessage {
     priority?: string | null;
     status?: string | null;
     deadlineAt?: string | null;
+    referenceId?: string | null;
     replyToMessageId?: string | null;
     respondedAt?: string | null;
     viewedAt?: string | null;

package/dist/types.js

@@ -100,6 +100,7 @@ export function parseSessionMessage(data) {
         priority: m.priority ?? null,
         status: m.status ?? null,
         deadlineAt: m.deadlineAt ?? null,
+        referenceId: m.referenceId ?? null,
         replyToMessageId: m.replyToMessageId ?? null,
         respondedAt: m.respondedAt ?? null,
         viewedAt: m.viewedAt ?? null,

package/dist/ws.d.ts

@@ -46,7 +46,7 @@ export declare class HiloopWsClient {
     subscribe(topic: string): void;
     /** Unsubscribe from a topic. */
     unsubscribe(topic: string): void;
-    /** Send a session message (auto-encrypts). */
+    /** Send a text session message (auto-encrypts as component). */
     sendSessionMessage(sessionId: string, content: string): Promise<void>;
     /** Send a typing indicator. */
     sendTyping(sessionId: string, isTyping: boolean): void;

package/dist/ws.js

@@ -101,10 +101,26 @@ export class HiloopWsClient {
                             }
                         }
                         // Auto-decrypt session messages
-                        if (data.type === "session.message.new" && data.encryptedContent && this.crypto) {
-                            const plain = await this.crypto.decryptSessionMessage(data.encryptedContent);
-                            if (plain !== null)
-                                data.content = plain;
+                        if (data.type === "session.message.new" && this.crypto) {
+                            // New format: components
+                            if (data.encryptedComponents) {
+                                const plain = await this.crypto.decryptSessionMessage(data.encryptedComponents);
+                                if (plain !== null) {
+                                    try {
+                                        data.components = JSON.parse(plain);
+                                        const textNode = data.components?.find((n) => n.type === "text");
+                                        if (textNode)
+                                            data.content = textNode.data?.content ?? null;
+                                    }
+                                    catch { /* ignore */ }
+                                }
+                            }
+                            // Legacy: encryptedContent
+                            if (data.content === undefined && data.encryptedContent) {
+                                const plain = await this.crypto.decryptSessionMessage(data.encryptedContent);
+                                if (plain !== null)
+                                    data.content = plain;
+                            }
                         }
                         this.emit(data.type, data);
                     }
@@ -143,11 +159,12 @@ export class HiloopWsClient {
     unsubscribe(topic) {
         this.send({ type: "unsubscribe", topic });
     }
-    /** Send a session message (auto-encrypts). */
+    /** Send a text session message (auto-encrypts as component). */
     async sendSessionMessage(sessionId, content) {
         await this.ensureCrypto();
-        const encryptedContent = await this.crypto.encryptSessionMessage(content);
-        this.send({ type: "session.send", sessionId, encryptedContent });
+        const components = [{ type: "text", data: { content } }];
+        const encryptedComponents = await this.crypto.encryptSessionMessage(JSON.stringify(components));
+        this.send({ type: "session.send", sessionId, encryptedComponents });
     }
     /** Send a typing indicator. */
     sendTyping(sessionId, isTyping) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hiloop-sdk",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "TypeScript SDK for Hiloop — zero-trust human-AI agent interaction platform",
   "type": "module",
   "main": "dist/index.js",