@relevanceai/sdk 3.0.2 → 3.1.0

package/esm/agent.js

@@ -201,6 +201,10 @@ export class Agent {
             body: JSON.stringify({
                 agent_id: this.#config.agent_id,
                 conversation_id: taskId,
+                // @todo: embed keys cannot have streaming enabled due to override permissions
+                ...(!this.client.isEmbedKey()
+                    ? { agent_override: { ...this.#config, use_streaming: true } }
+                    : {}),
                 message: {
                     role: "user",
                     content: message,

package/esm/client.d.ts

@@ -30,7 +30,7 @@ export declare class Client {
     get region(): Region;
     get project(): string;
     isEmbedKey(): boolean;
-    fetch<T>(input: "/agents/trigger" | `/agents/${string}/get` | `/agents/${string}/tasks/${string}/metadata` | `/agents/${string}/tasks/${string}/view` | "/agents/conversations/list" | "/services/get_temporary_file_upload_url" | `/workforce/items/${string}` | `/workforce/tasks/${string}/metadata` | `/workforce/items/${string}/tasks/${string}/messages` | "/workforce/trigger" | "/workforce/tasks/list" | "/agents/list", init?: RequestInit): Promise<T>;
+    fetch<T>(input: string, init?: RequestInit): Promise<T>;
     url(path: string): URL;
     uploadTempFile(file: File): Promise<Attachment>;
 }

package/esm/message/agent.d.ts

@@ -3,6 +3,8 @@ import { GenericMessage, type TaskMessageData } from "./task.js";
 export interface AgentMessageContent {
     type: "agent-message";
     text: string;
+    generating?: boolean;
+    thinking?: string[];
     thought_about_tool_calls?: boolean;
 }
 export declare class AgentMessage extends GenericMessage<AgentMessageContent> {
@@ -10,5 +12,15 @@ export declare class AgentMessage extends GenericMessage<AgentMessageContent> {
     constructor(message: TaskMessageData<AgentMessageContent>, agent?: Agent);
     get text(): string;
     get agentId(): string;
+    get thoughts(): string[];
+    isGenerating(): boolean;
+    /**
+     * @deprecated
+     * Do not use this method as it is not a reliable indicator of whether the
+     * agent is thinking. It only indicates whether the message content includes
+     * a flag that suggests the agent is considering tool calls, but this may
+     * not always be present or accurate. This method will be removed in next
+     * major release.
+     */
     isThought(): boolean;
 }

package/esm/message/agent.js

@@ -11,6 +11,20 @@ export class AgentMessage extends GenericMessage {
     get agentId() {
         return this.agent?.id ?? "";
     }
+    get thoughts() {
+        return this.message.content.thinking ?? [];
+    }
+    isGenerating() {
+        return this.message.content.generating ?? false;
+    }
+    /**
+     * @deprecated
+     * Do not use this method as it is not a reliable indicator of whether the
+     * agent is thinking. It only indicates whether the message content includes
+     * a flag that suggests the agent is considering tool calls, but this may
+     * not always be present or accurate. This method will be removed in next
+     * major release.
+     */
     isThought() {
         return this.message.content.thought_about_tool_calls ?? false;
     }

package/esm/message/stream.d.ts

@@ -0,0 +1,15 @@
+import { GenericMessage } from "./task.js";
+export type ThinkingMessageContent = {
+    type: "agent-thinking";
+    text: string;
+};
+export type TypingMessageContent = {
+    type: "agent-typing";
+    text: string;
+};
+export declare class ThinkingMessage extends GenericMessage<ThinkingMessageContent> {
+    get text(): string;
+}
+export declare class TypingMessage extends GenericMessage<TypingMessageContent> {
+    get text(): string;
+}

package/esm/message/stream.js

@@ -0,0 +1,11 @@
+import { GenericMessage } from "./task.js";
+export class ThinkingMessage extends GenericMessage {
+    get text() {
+        return this.message.content.text;
+    }
+}
+export class TypingMessage extends GenericMessage {
+    get text() {
+        return this.message.content.text;
+    }
+}

package/esm/message/task.d.ts

@@ -4,9 +4,11 @@ import type { ToolMessage } from "./tool.js";
 import type { UserMessage } from "./user.js";
 import type { WorkforceAgentMessage } from "./workforce-agent.js";
 import type { WorkforceAgentHandoverMessage } from "./workforce-agent-handover.js";
-export type AnyTaskMessage = AgentMessage | AgentErrorMessage | ToolMessage | UserMessage | WorkforceAgentMessage | WorkforceAgentHandoverMessage;
+import type { ThinkingMessage } from "./stream.js";
+import type { TypingMessage } from "./stream.js";
+export type AnyTaskMessage = AgentMessage | AgentErrorMessage | ThinkingMessage | TypingMessage | ToolMessage | UserMessage | WorkforceAgentMessage | WorkforceAgentHandoverMessage;
 export type TaskMessageType = AnyTaskMessage["type"];
-interface MessageContent {
+export interface MessageContent {
     type: AnyTaskMessage["type"];
 }
 export interface TaskMessageData<C extends MessageContent = MessageContent> {
@@ -54,10 +56,15 @@ export declare abstract class GenericMessage<C extends MessageContent = MessageC
      */
     isUser(): this is UserMessage;
     /**
-     * Returns if the message was an error sent by the agent.
+     * Returns if the message is agent thinking.
      *
      * @returns {boolean}
      */
-    isAgentError(): this is AgentErrorMessage;
+    isThinking(): this is ThinkingMessage;
+    /**
+     * Returns if the message is agent typing.
+     *
+     * @returns {boolean}
+     */
+    isTyping(): this is TypingMessage;
 }
-export {};

package/esm/message/task.js

@@ -52,11 +52,19 @@ export class GenericMessage {
         return this.type === "user-message";
     }
     /**
-     * Returns if the message was an error sent by the agent.
+     * Returns if the message is agent thinking.
      *
      * @returns {boolean}
      */
-    isAgentError() {
-        return this.type === "agent-error";
+    isThinking() {
+        return this.type === "agent-thinking";
+    }
+    /**
+     * Returns if the message is agent typing.
+     *
+     * @returns {boolean}
+     */
+    isTyping() {
+        return this.type === "agent-typing";
     }
 }

package/esm/region.d.ts

@@ -3,3 +3,4 @@ export declare const REGION_US = "bcbe5a";
 export declare const REGION_EU = "d7b62b";
 export declare const REGION_AU = "f1db6c";
 export declare function regionBaseURL(region: Region): string;
+export declare function regionStreamingURL(region: Region, token: string): string;

package/esm/region.js

@@ -4,3 +4,6 @@ export const REGION_AU = "f1db6c";
 export function regionBaseURL(region) {
     return `https://api-${region}.stack.tryrelevance.com`;
 }
+export function regionStreamingURL(region, token) {
+    return `https://${region}.streaming.tryrelevance.com/v1/stream?authorization=Bearer+${token}`;
+}

package/esm/task/agent-strategy.js

@@ -22,15 +22,22 @@ export class AgentStrategy {
         return this.agent;
     }
     async getMetadata() {
-        const { metadata } = await this.client.fetch(`/agents/${this.agent.id}/tasks/${this.id}/metadata`);
+        const url = `/agents/${this.agent.id}/tasks/${this.id}/metadata?include_streaming_token=true`;
+        const res = await this.client.fetch(url);
         return {
             id: this.id,
             region: this.client.region,
             project: this.client.project,
-            name: metadata.conversation.title,
-            status: stateToStatus(metadata.conversation.state),
-            createdAt: new Date(metadata.insert_date),
-            updatedAt: new Date(metadata.update_date),
+            name: res.metadata.conversation.title,
+            status: stateToStatus(res.metadata.conversation.state),
+            createdAt: new Date(res.metadata.insert_date),
+            updatedAt: new Date(res.metadata.update_date),
+            streamingToken: res.streaming_token
+                ? {
+                    token: res.streaming_token.token,
+                    expiresAt: res.streaming_token.expiry_time_ms,
+                }
+                : undefined,
         };
     }
     async getMessages({ after = new Date(0) } = {}) {

package/esm/task/stream.d.ts

@@ -0,0 +1,24 @@
+import { Emitter } from "../emitter.js";
+import { type Region } from "../region.js";
+import type { TaskStrategy } from "./task.js";
+export type StreamingToken = {
+    token: string;
+    expiresAt: number;
+};
+export type StreamDetail = {
+    content: string;
+    documentId: string;
+};
+type TaskStreamEventMap = {
+    thinking: StreamDetail;
+    typing: StreamDetail;
+};
+export declare class TaskStream extends Emitter<TaskStreamEventMap> {
+    #private;
+    constructor(strategy: TaskStrategy<any>, metadata: {
+        region: Region;
+        streamingToken: StreamingToken;
+    });
+    close(): void;
+}
+export {};

package/esm/task/stream.js

@@ -0,0 +1,151 @@
+import { Emitter } from "../emitter.js";
+import { regionStreamingURL } from "../region.js";
+export class TaskStream extends Emitter {
+    #strategy;
+    #region;
+    #token;
+    #closed = false;
+    #refreshTimer = null;
+    #source = null;
+    #fetchController = null;
+    constructor(strategy, metadata) {
+        super();
+        this.#strategy = strategy;
+        this.#region = metadata.region;
+        this.#token = metadata.streamingToken;
+        this.#connect();
+    }
+    close() {
+        this.#closed = true;
+        this.#clearRefreshTimer();
+        this.#disconnect();
+    }
+    #connect() {
+        if (this.#closed)
+            return;
+        this.#scheduleRefresh();
+        if (typeof EventSource !== "undefined") {
+            this.#connectEventSource();
+        }
+        else {
+            this.#connectFetch();
+        }
+    }
+    #disconnect() {
+        this.#clearRefreshTimer();
+        if (this.#source) {
+            this.#source.close();
+            this.#source = null;
+        }
+        if (this.#fetchController) {
+            this.#fetchController.abort();
+            this.#fetchController = null;
+        }
+    }
+    #connectEventSource() {
+        const url = regionStreamingURL(this.#region, this.#token.token);
+        const source = new EventSource(url);
+        this.#source = source;
+        source.addEventListener("message", (event) => {
+            this.#handleData(event.data);
+        });
+    }
+    #connectFetch() {
+        const url = regionStreamingURL(this.#region, this.#token.token);
+        const controller = new AbortController();
+        this.#fetchController = controller;
+        void (async () => {
+            try {
+                const response = await fetch(url, {
+                    headers: { Accept: "text/event-stream" },
+                    signal: controller.signal,
+                });
+                if (!response.ok || !response.body)
+                    return;
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = "";
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buffer += decoder.decode(value, { stream: true });
+                    const { events, remainder } = this.#parseSSE(buffer);
+                    buffer = remainder;
+                    for (const data of events) {
+                        this.#handleData(data);
+                    }
+                }
+            }
+            catch {
+                // aborted or network error — ignore if closed
+            }
+        })();
+    }
+    #parseSSE(buffer) {
+        const events = [];
+        const blocks = buffer.split("\n\n");
+        const remainder = blocks.pop(); // last chunk may be incomplete
+        for (const block of blocks) {
+            for (const line of block.split("\n")) {
+                if (line.startsWith("data:")) {
+                    events.push(line.slice(5).trimStart());
+                }
+            }
+        }
+        return { events, remainder };
+    }
+    #handleData(raw) {
+        try {
+            const data = JSON.parse(raw);
+            switch (data.type) {
+                case "thinking":
+                    this.dispatchEvent(new CustomEvent("thinking", {
+                        detail: { content: data.content, documentId: data.documentId },
+                    }));
+                    break;
+                case "text":
+                    this.dispatchEvent(new CustomEvent("typing", {
+                        detail: { content: data.content, documentId: data.documentId },
+                    }));
+                    break;
+            }
+        }
+        catch {
+            // ignore malformed JSON
+        }
+    }
+    #scheduleRefresh() {
+        this.#clearRefreshTimer();
+        const delay = this.#token.expiresAt - Date.now() - 30_000;
+        if (delay <= 0)
+            return; // already expired or about to
+        this.#refreshTimer = setTimeout(() => this.#refresh(), delay);
+    }
+    #clearRefreshTimer() {
+        if (this.#refreshTimer !== null) {
+            clearTimeout(this.#refreshTimer);
+            this.#refreshTimer = null;
+        }
+    }
+    async #refresh() {
+        if (this.#closed)
+            return;
+        try {
+            const metadata = await this.#strategy.getMetadata();
+            if (this.#closed)
+                return;
+            if (!metadata.streamingToken) {
+                this.close();
+                return;
+            }
+            this.#region = metadata.region;
+            this.#token = metadata.streamingToken;
+            this.#disconnect();
+            this.#connect();
+        }
+        catch {
+            // refresh failed — try again on next schedule
+        }
+    }
+}

package/esm/task/task.d.ts

@@ -4,7 +4,9 @@ import type { Region } from "../region.js";
 import type { Workforce } from "../workforce.js";
 import type { Agent } from "../agent.js";
 import type { AgentErrorMessage } from "../message/agent-error.js";
+import { type StreamingToken } from "./stream.js";
 export type TaskStatus = "not-started" | "idle" | "paused" | "queued" | "running" | "action" | "completed" | "cancelled" | "error";
+export type { StreamingToken };
 export interface TaskMetadata {
     id: string;
     region: Region;
@@ -13,6 +15,7 @@ export interface TaskMetadata {
     name: string;
     createdAt: Date;
     updatedAt: Date;
+    streamingToken?: StreamingToken;
 }
 type TaskEventMap = {
     updated: undefined;
@@ -56,4 +59,3 @@ export declare class Task<S extends Agent | Workforce, E extends TaskEventMap =
         handleEvent: (event: CustomEvent<E[K]>) => void;
     } | null, options?: boolean | AddEventListenerOptions): void;
 }
-export {};

package/esm/task/task.js

@@ -1,6 +1,8 @@
 import { Emitter } from "../emitter.js";
 import { abortPromise, delay } from "../utils.js";
 import { TaskErrorEvent, TaskMessageEvent, TaskUpdateEvent } from "../event.js";
+import { ThinkingMessage, TypingMessage } from "../message/stream.js";
+import { TaskStream } from "./stream.js";
 export const resetBackoffDuration = Symbol("resetBackoffDuration");
 const backoffStartingDuration = 1_000;
 const backoffMaxDuration = 60_000;
@@ -10,6 +12,7 @@ export class Task extends Emitter {
     backoffDuration = 0;
     strategy;
     #metadata;
+    #stream = null;
     constructor(metadata, strategy) {
         super();
         this.strategy = strategy;
@@ -51,6 +54,33 @@ export class Task extends Emitter {
                 return false;
         }
     }
+    #connectStream() {
+        const stream = new TaskStream(this.strategy, {
+            region: this.#metadata.region,
+            streamingToken: this.#metadata.streamingToken,
+        });
+        stream.addEventListener("thinking", (event) => {
+            this.dispatchEvent(new TaskMessageEvent(new ThinkingMessage({
+                item_id: event.detail.documentId,
+                insert_date_: new Date().toISOString(),
+                content: {
+                    type: "agent-thinking",
+                    text: event.detail.content,
+                },
+            })));
+        });
+        stream.addEventListener("typing", (event) => {
+            this.dispatchEvent(new TaskMessageEvent(new TypingMessage({
+                item_id: event.detail.documentId,
+                insert_date_: new Date().toISOString(),
+                content: {
+                    type: "agent-typing",
+                    text: event.detail.content,
+                },
+            })));
+        });
+        this.#stream = stream;
+    }
     #subscribe() {
         if (this.subscribed) {
             return;
@@ -59,9 +89,12 @@ export class Task extends Emitter {
         this.subscribed = subscribed; // subscribed ref
         const isSubscribed = () => !subscribed.signal.aborted;
         this.backoffDuration = backoffStartingDuration;
-        const cursor = new Date();
+        const cursor = new Date(this.#metadata.createdAt);
         const emitted = new Set();
         const pending = new Map();
+        if (this.#metadata.streamingToken) {
+            this.#connectStream();
+        }
         void (async () => {
             while (isSubscribed()) {
                 try {
@@ -78,6 +111,9 @@ export class Task extends Emitter {
                         hasChanges = true;
                     }
                     this.#metadata = metadata;
+                    if (!this.#stream && metadata.streamingToken) {
+                        this.#connectStream();
+                    }
                     if (messages.length) {
                         for (const message of messages) {
                             if (emitted.has(message.id)) {
@@ -104,7 +140,17 @@ export class Task extends Emitter {
                                     this.dispatchEvent(new TaskMessageEvent(message));
                                     break;
                                 }
-                                case "agent-message":
+                                case "agent-message": {
+                                    if (message.isAgent() && message.isGenerating()) {
+                                        pending.set(message.id, message);
+                                        break;
+                                    }
+                                    emitted.add(message.id);
+                                    pending.delete(message.id);
+                                    hasChanges = true;
+                                    this.dispatchEvent(new TaskMessageEvent(message));
+                                    break;
+                                }
                                 case "user-message":
                                     hasChanges = true;
                                     emitted.add(message.id);
@@ -140,6 +186,8 @@ export class Task extends Emitter {
         })();
     }
     unsubscribe() {
+        this.#stream?.close();
+        this.#stream = null;
         this.subscribed?.abort();
         this.subscribed = null;
         this.backoff?.abort();

package/esm/task/workforce-strategy.js

@@ -77,15 +77,22 @@ export class WorkforceStrategy {
         });
     }
     async getMetadata() {
-        const { metadata } = await this.client.fetch(`/workforce/tasks/${this.id}/metadata`);
+        const url = `/workforce/tasks/${this.id}/metadata?include_streaming_token=true`;
+        const res = await this.client.fetch(url);
         return {
             id: this.id,
             region: this.client.region,
             project: this.client.project,
-            name: metadata.title,
-            status: WorkforceStrategy.convertStatus(metadata.state),
-            createdAt: new Date(metadata.insert_date),
-            updatedAt: new Date(metadata.update_date),
+            name: res.metadata.title,
+            status: WorkforceStrategy.convertStatus(res.metadata.state),
+            createdAt: new Date(res.metadata.insert_date),
+            updatedAt: new Date(res.metadata.update_date),
+            streamingToken: res.streaming_token
+                ? {
+                    token: res.streaming_token.token,
+                    expiresAt: res.streaming_token.expiry_time_ms,
+                }
+                : undefined,
         };
     }
 }

package/esm/workforce.js

@@ -69,6 +69,7 @@ export class Workforce {
                 workforce_id: this.id,
                 workforce_task_id: taskId,
                 trigger: {
+                    use_streaming: true,
                     message: {
                         role: "user",
                         content: message,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relevanceai/sdk",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "license": "MIT",
   "main": "./script/mod.js",
   "module": "./esm/mod.js",

package/script/agent.js

@@ -205,6 +205,10 @@ class Agent {
             body: JSON.stringify({
                 agent_id: this.#config.agent_id,
                 conversation_id: taskId,
+                // @todo: embed keys cannot have streaming enabled due to override permissions
+                ...(!this.client.isEmbedKey()
+                    ? { agent_override: { ...this.#config, use_streaming: true } }
+                    : {}),
                 message: {
                     role: "user",
                     content: message,

package/script/client.d.ts

@@ -30,7 +30,7 @@ export declare class Client {
     get region(): Region;
     get project(): string;
     isEmbedKey(): boolean;
-    fetch<T>(input: "/agents/trigger" | `/agents/${string}/get` | `/agents/${string}/tasks/${string}/metadata` | `/agents/${string}/tasks/${string}/view` | "/agents/conversations/list" | "/services/get_temporary_file_upload_url" | `/workforce/items/${string}` | `/workforce/tasks/${string}/metadata` | `/workforce/items/${string}/tasks/${string}/messages` | "/workforce/trigger" | "/workforce/tasks/list" | "/agents/list", init?: RequestInit): Promise<T>;
+    fetch<T>(input: string, init?: RequestInit): Promise<T>;
     url(path: string): URL;
     uploadTempFile(file: File): Promise<Attachment>;
 }

package/script/message/agent.d.ts

@@ -3,6 +3,8 @@ import { GenericMessage, type TaskMessageData } from "./task.js";
 export interface AgentMessageContent {
     type: "agent-message";
     text: string;
+    generating?: boolean;
+    thinking?: string[];
     thought_about_tool_calls?: boolean;
 }
 export declare class AgentMessage extends GenericMessage<AgentMessageContent> {
@@ -10,5 +12,15 @@ export declare class AgentMessage extends GenericMessage<AgentMessageContent> {
     constructor(message: TaskMessageData<AgentMessageContent>, agent?: Agent);
     get text(): string;
     get agentId(): string;
+    get thoughts(): string[];
+    isGenerating(): boolean;
+    /**
+     * @deprecated
+     * Do not use this method as it is not a reliable indicator of whether the
+     * agent is thinking. It only indicates whether the message content includes
+     * a flag that suggests the agent is considering tool calls, but this may
+     * not always be present or accurate. This method will be removed in next
+     * major release.
+     */
     isThought(): boolean;
 }

package/script/message/agent.js

@@ -14,6 +14,20 @@ class AgentMessage extends task_js_1.GenericMessage {
     get agentId() {
         return this.agent?.id ?? "";
     }
+    get thoughts() {
+        return this.message.content.thinking ?? [];
+    }
+    isGenerating() {
+        return this.message.content.generating ?? false;
+    }
+    /**
+     * @deprecated
+     * Do not use this method as it is not a reliable indicator of whether the
+     * agent is thinking. It only indicates whether the message content includes
+     * a flag that suggests the agent is considering tool calls, but this may
+     * not always be present or accurate. This method will be removed in next
+     * major release.
+     */
     isThought() {
         return this.message.content.thought_about_tool_calls ?? false;
     }

package/script/message/stream.d.ts

@@ -0,0 +1,15 @@
+import { GenericMessage } from "./task.js";
+export type ThinkingMessageContent = {
+    type: "agent-thinking";
+    text: string;
+};
+export type TypingMessageContent = {
+    type: "agent-typing";
+    text: string;
+};
+export declare class ThinkingMessage extends GenericMessage<ThinkingMessageContent> {
+    get text(): string;
+}
+export declare class TypingMessage extends GenericMessage<TypingMessageContent> {
+    get text(): string;
+}

package/script/message/stream.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypingMessage = exports.ThinkingMessage = void 0;
+const task_js_1 = require("./task.js");
+class ThinkingMessage extends task_js_1.GenericMessage {
+    get text() {
+        return this.message.content.text;
+    }
+}
+exports.ThinkingMessage = ThinkingMessage;
+class TypingMessage extends task_js_1.GenericMessage {
+    get text() {
+        return this.message.content.text;
+    }
+}
+exports.TypingMessage = TypingMessage;