@relevanceai/sdk 3.0.0-alpha.2 → 3.0.0-alpha.3

package/script/task.js

@@ -1,91 +1,257 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Task = void 0;
+exports.Task = exports.resetSubscribeBackoff = void 0;
+const agent_js_1 = require("./agent.js");
 const client_js_1 = require("./client.js");
-const events_js_1 = require("./events.js");
+const emitter_js_1 = require("./emitter.js");
+const event_js_1 = require("./event.js");
+const agent_error_js_1 = require("./message/agent-error.js");
+const agent_js_2 = require("./message/agent.js");
+const tool_js_1 = require("./message/tool.js");
+const user_js_1 = require("./message/user.js");
 const utils_js_1 = require("./utils.js");
-class Task extends EventTarget {
-    subject;
+/**
+ * Converts an AgentTaskState to a simplified TaskStatus.
+ *
+ * @internal
+ *
+ * @param {AgentTaskState} state The agent task state to convert.
+ * @returns {TaskStatus} The simplified task status.
+ */
+function stateToStatus(state) {
+    switch (state) {
+        case "paused":
+        case "idle":
+            return "idle";
+        case "starting-up":
+        case "waiting-for-capacity":
+        case "queued-for-approval":
+        case "queued-for-rerun":
+            return "queued";
+        case "running":
+            return "running";
+        case "pending-approval":
+        case "escalated":
+            return "action";
+        case "timed-out":
+            return "error";
+        case "cancelled":
+        case "completed":
+            return "complete";
+        case "unrecoverable":
+        case "errored-pending-approval":
+            return "error";
+        default:
+            throw new Error(`unhandled task state: ${state}`);
+    }
+}
+exports.resetSubscribeBackoff = Symbol("resetSubscribeBackoff");
+class Task extends emitter_js_1.Emitter {
+    static async get(id, agentOrAgentId, client = client_js_1.Client.default()) {
+        const agent = typeof agentOrAgentId === "string"
+            ? await agent_js_1.Agent.get(agentOrAgentId, client)
+            : agentOrAgentId;
+        const metadata = await Task.#fetchMetadata(id, agent.id, client);
+        return new Task(metadata, agent, client);
+    }
+    static #fetchMetadata(id, agentId, client) {
+        return client.fetch(`/agents/${agentId}/tasks/${id}/metadata`).then(({ metadata }) => metadata);
+    }
+    #controller;
+    #backoffMs = 1000;
+    #lastUpdatedAt;
+    #delayController;
+    #metadata;
+    agent;
     client;
-    #id;
-    listenController;
-    constructor(subject, id = undefined, client = client_js_1.Client.default()) {
+    constructor(metadata, agent, client = client_js_1.Client.default()) {
         super();
-        this.subject = subject;
+        this.#metadata = metadata;
+        this.agent = agent;
         this.client = client;
-        this.#id = id;
     }
     get id() {
-        return this.#id;
+        return this.#metadata.knowledge_set;
+    }
+    get title() {
+        return this.#metadata.conversation.title ?? "";
+    }
+    get status() {
+        return stateToStatus(this.#metadata.conversation.state);
     }
-    setId(id, status = "not-started") {
-        if (this.#id) {
-            throw new Error("task id is already set");
+    isRunning() {
+        switch (this.status) {
+            case "queued":
+            case "running":
+                return true;
+            default:
+                return false;
         }
-        // @ts-ignore: allow assignment to readonly in this special case
-        this.#id = id;
-        this.dispatchEvent(new events_js_1.TaskStartEvent(id, status));
     }
-    listen() {
-        if (this.isListening()) {
+    async getMessages({ from = new Date(0) } = {}) {
+        const url = `/agents/${this.agent.id}/tasks/${this.id}/view`;
+        const res = await this.client.fetch(url, {
+            method: "POST",
+            body: JSON.stringify({
+                page_size: 1_000, // @todo: pagination
+                cursor: {
+                    after: from.toISOString(),
+                },
+            }),
+        });
+        // message should be in ascending order
+        return res.results.reverse().map((data) => {
+            switch (data.content.type) {
+                case "agent-error":
+                    return new agent_error_js_1.AgentErrorMessage(data);
+                case "agent-message":
+                    return new agent_js_2.AgentMessage(data);
+                case "tool-run":
+                    return new tool_js_1.ToolMessage(data);
+                case "user-message":
+                    return new user_js_1.UserMessage(data);
+                default:
+                    throw new Error("unknown message response");
+            }
+        });
+    }
+    async refresh() {
+        this.#metadata = await Task.#fetchMetadata(this.id, this.agent.id, this.client);
+    }
+    [exports.resetSubscribeBackoff]() {
+        this.#backoffMs = 1000;
+        this.#delayController?.abort();
+    }
+    subscribe() {
+        if (this.isSubscribed()) {
             return;
         }
-        this.listenController = new AbortController();
-        const signal = this.listenController.signal;
-        let currentStatus = null;
+        this.#controller = new AbortController();
+        const signal = this.#controller.signal;
+        let currentStatus = this.status;
         const messagesCursor = new Date(0);
-        void (0, utils_js_1.runInterval)(async () => {
-            // no task, yet
-            if (!this.id) {
-                return;
-            }
-            const [status, messages] = await Promise.all([
-                this.fetchStatus(),
-                this.fetchMessages({
-                    from: messagesCursor,
-                }),
-            ]);
-            if (!this.isListening()) {
-                return;
-            }
-            if (status !== currentStatus) {
-                currentStatus = status;
-                this.dispatchEvent(new events_js_1.TaskStatusEvent(status));
-            }
-            if (messages.length) {
-                for (const message of messages) {
-                    switch (message.type) {
-                        case "agent-error":
-                            this.dispatchEvent(new events_js_1.TaskErrorEvent(message));
-                            break;
-                        case "tool-run":
-                            this.dispatchEvent(new events_js_1.TaskUpdateEvent(message));
-                            break;
-                        case "agent-message":
-                        case "user-message":
-                            this.dispatchEvent(new events_js_1.TaskMessageEvent(message));
+        const emitted = new Set();
+        let lastMessage = null;
+        const pendingTools = new Map();
+        // Initialize backoff and tracking
+        this.#backoffMs = 1000;
+        this.#lastUpdatedAt = this.#metadata.update_date;
+        void (async () => {
+            while (this.isSubscribed() && !signal.aborted) {
+                try {
+                    const [, result] = await Promise.allSettled([
+                        this.refresh(),
+                        this.getMessages({ from: messagesCursor }),
+                    ]);
+                    if (!this.isSubscribed() || signal.aborted) {
+                        break;
+                    }
+                    const messages = result.status === "fulfilled" ? result.value : [];
+                    // Track if any changes occurred
+                    let hasChanges = false;
+                    // Check for status changes
+                    if (this.status !== currentStatus) {
+                        currentStatus = this.status;
+                        this.dispatchEvent(new event_js_1.TaskStatusEvent(this.status));
+                        hasChanges = true;
+                    }
+                    // Check for metadata update_date changes
+                    if (this.#metadata.update_date !== this.#lastUpdatedAt) {
+                        this.#lastUpdatedAt = this.#metadata.update_date;
+                        hasChanges = true;
+                    }
+                    // Process messages
+                    if (messages.length) {
+                        hasChanges = true;
+                        for (const message of messages) {
+                            if (emitted.has(message.id)) {
+                                switch (message.type) {
+                                    case "agent-error":
+                                    case "agent-message":
+                                    case "user-message":
+                                        // don't re-fire
+                                        continue;
+                                }
+                            }
+                            emitted.add(message.id);
+                            switch (message.type) {
+                                case "agent-error":
+                                    this.dispatchEvent(new event_js_1.TaskErrorEvent(message));
+                                    break;
+                                case "tool-run": {
+                                    const { status } = message;
+                                    if (pendingTools.get(message.id)?.status == status) {
+                                        // no change to the tool status
+                                        continue;
+                                    }
+                                    if (["pending", "running"].includes(status)) {
+                                        pendingTools.set(message.id, message);
+                                    }
+                                    else {
+                                        pendingTools.delete(message.id);
+                                    }
+                                    this.dispatchEvent(new event_js_1.TaskUpdateEvent(message));
+                                    break;
+                                }
+                                case "agent-message":
+                                case "user-message":
+                                    this.dispatchEvent(new event_js_1.TaskMessageEvent(message));
+                            }
+                            lastMessage = message;
+                        }
+                        // +1 the api treats after inclusively
+                        let nextCursor = messages.at(-1).createdAt.getTime() + 1;
+                        // set the cursor as the earliest pending tool
+                        for (const pending of pendingTools.values()) {
+                            if (nextCursor > pending.createdAt.getTime()) {
+                                nextCursor = pending.createdAt.getTime();
+                            }
+                        }
+                        messagesCursor.setTime(nextCursor);
+                    }
+                    // Apply backoff logic
+                    if (hasChanges) {
+                        // Reset backoff on any changes
+                        this.#backoffMs = 1000;
+                    }
+                    else if (!this.isRunning() && lastMessage?.isAgent()) {
+                        // Apply exponential backoff when idle with last message from agent
+                        this.#backoffMs = Math.min(this.#backoffMs * 2, 60000);
+                    }
+                }
+                finally {
+                    // Wait for the backoff period or abort signal
+                    if (!signal.aborted) {
+                        // Create a new controller for this delay that can be aborted independently
+                        this.#delayController = new AbortController();
+                        await Promise.race([
+                            (0, utils_js_1.delay)(this.#backoffMs),
+                            (0, utils_js_1.abortPromise)(AbortSignal.any([
+                                signal,
+                                this.#delayController.signal,
+                            ])),
+                        ]);
                     }
                 }
-                messagesCursor.setTime(
-                // +1 the api treats after inclusively
-                messages.at(-1).createdAt.getTime() + 1);
             }
-        }, 15_000, { signal });
+        })();
     }
-    isListening() {
-        return this.listenController !== undefined;
+    isSubscribed() {
+        return this.#controller !== undefined;
     }
-    stopListening() {
-        this.listenController?.abort();
-        this.listenController = undefined;
+    unsubscribe() {
+        this.#delayController?.abort();
+        this.#controller?.abort();
+        this.#delayController = undefined;
+        this.#controller = undefined;
     }
     addEventListener(type, listener, options) {
-        this.listen();
+        this.subscribe();
         const signal = AbortSignal.any([
             ...(options && typeof options === "object" && options.signal
                 ? [options.signal]
                 : []),
-            this.listenController.signal,
+            this.#controller.signal,
         ]);
         const capture = typeof options === "boolean"
             ? options
@@ -93,8 +259,5 @@ class Task extends EventTarget {
         const addOptions = Object.assign({}, options, { signal, capture });
         super.addEventListener(type, listener, addOptions);
     }
-    removeEventListener(type, listener, options) {
-        super.removeEventListener(type, listener, options);
-    }
 }
 exports.Task = Task;

package/script/utils.d.ts

@@ -1,8 +1,4 @@
 export declare function abortPromise(signal: AbortSignal, reject?: boolean): Promise<void>;
-export declare function delay(timeout: number): Promise<void>;
-export declare function runInterval(runner: () => Promise<void> | void, interval: number, { signal, }?: {
-    signal?: AbortSignal;
-    immediate?: boolean;
-}): Promise<void>;
+export declare function delay(timeout: number | (() => number)): Promise<void>;
 export declare function cleanPath(path: string, version?: string): string;
 export declare function randomUUID(): Promise<any>;

package/script/utils.js

@@ -35,26 +35,13 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.abortPromise = abortPromise;
 exports.delay = delay;
-exports.runInterval = runInterval;
 exports.cleanPath = cleanPath;
 exports.randomUUID = randomUUID;
 function abortPromise(signal, reject) {
     return new Promise((res, rej) => signal.addEventListener("abort", () => reject ? rej() : res()));
 }
 function delay(timeout) {
-    return new Promise((done) => setTimeout(done, timeout));
-}
-async function runInterval(runner, interval, { signal, } = {}) {
-    while (true) {
-        if (signal?.aborted) {
-            break;
-        }
-        await runner();
-        await Promise.race([
-            delay(interval),
-            signal ? abortPromise(signal) : new Promise(() => { }),
-        ]);
-    }
+    return new Promise((done) => setTimeout(done, typeof timeout === "number" ? timeout : timeout()));
 }
 function cleanPath(path, version = "latest") {
     return `/${version}/${path.trim().replace(/^\/+/, "")}`;

package/esm/agent-task.d.ts

@@ -1,61 +0,0 @@
-import type { Agent } from "./agent.js";
-import { TaskMessage } from "./message.js";
-import { Task, type TaskStatus } from "./task.js";
-type AgentTaskEvents = {
-    start: {
-        status: TaskStatus;
-    };
-    status: {
-        status: TaskStatus;
-    };
-    message: {
-        message: TaskMessage<"agent-message" | "user-message">;
-    };
-    update: {
-        message: TaskMessage<"tool-run">;
-    };
-};
-export type AgentTaskState = "idle" | "starting-up" | "running" | "pending-approval" | "waiting-for-capacity" | "cancelled" | "timed-out" | "escalated" | "unrecoverable" | "paused" | "completed" | "errored-pending-approval" | "queued-for-approval" | "queued-for-rerun";
-/**
- * AgentTask represents a conversation task with an AI agent. It extends the
- * base Task class with agent-specific functionality for sending messages and
- * retrieving conversation history.
- *
- * @see {@link Task} for the base task functionality.
- * @see {@link Agent} for the agent this task is associated with.
- *
- * @class AgentTask
- * @extends Task<Agent, AgentTaskEvents>
- */
-export declare class AgentTask extends Task<Agent, AgentTaskEvents> {
-    /**
-     * Sends a message to the agent. This method triggers the agent with the
-     * message and updates the task ID if this is the first message.
-     *
-     * Note: This method is asynchronous but doesn't return a promise. Use event
-     * listeners to track the response.
-     *
-     * @param {string} message
-     */
-    sendMessage(message: string): void;
-    /**
-     * Fetches the current status of the task from the API.
-     *
-     * @returns {Promise<TaskStatus>} The current task status.
-     * @throws {Error} if the agent or task ID is missing.
-     */
-    fetchStatus(): Promise<TaskStatus>;
-    /**
-     * Fetches messages from the conversation.
-     *
-     * @param {Object} [options] Optional fetch options.
-     * @param {Date} [options.from] Fetch messages after this timestamp.
-     *
-     * @returns {Promise<TaskMessage[]>} Array of messages in ascending order.
-     * @throws {Error} if the agent or task ID is missing.
-     */
-    fetchMessages({ from }?: {
-        from?: Date;
-    }): Promise<TaskMessage[]>;
-}
-export {};

package/esm/agent-task.js

@@ -1,112 +0,0 @@
-import { TaskMessage } from "./message.js";
-import { Task } from "./task.js";
-/**
- * Converts an AgentTaskState to a simplified TaskStatus.
- *
- * @internal
- *
- * @param {AgentTaskState} state The agent task state to convert.
- * @returns {TaskStatus} The simplified task status.
- */
-function stateToStatus(state) {
-    switch (state) {
-        case "paused":
-        case "idle":
-            return "idle";
-        case "starting-up":
-        case "waiting-for-capacity":
-        case "queued-for-approval":
-        case "queued-for-rerun":
-            return "queued";
-        case "running":
-            return "running";
-        case "pending-approval":
-        case "escalated":
-            return "action";
-        case "timed-out":
-            return "error";
-        case "cancelled":
-        case "completed":
-            return "complete";
-        case "unrecoverable":
-        case "errored-pending-approval":
-            return "error";
-        default:
-            throw new Error(`unhandled task state: ${state}`);
-    }
-}
-/**
- * AgentTask represents a conversation task with an AI agent. It extends the
- * base Task class with agent-specific functionality for sending messages and
- * retrieving conversation history.
- *
- * @see {@link Task} for the base task functionality.
- * @see {@link Agent} for the agent this task is associated with.
- *
- * @class AgentTask
- * @extends Task<Agent, AgentTaskEvents>
- */
-export class AgentTask extends Task {
-    /**
-     * Sends a message to the agent. This method triggers the agent with the
-     * message and updates the task ID if this is the first message.
-     *
-     * Note: This method is asynchronous but doesn't return a promise. Use event
-     * listeners to track the response.
-     *
-     * @param {string} message
-     */
-    sendMessage(message) {
-        this.subject.trigger(message, this.id || undefined).then(({ id, state }) => {
-            // started
-            if (!this.id) {
-                this.setId(id, stateToStatus(state));
-            }
-        });
-    }
-    /**
-     * Fetches the current status of the task from the API.
-     *
-     * @returns {Promise<TaskStatus>} The current task status.
-     * @throws {Error} if the agent or task ID is missing.
-     */
-    async fetchStatus() {
-        if (!this.subject.id) {
-            throw new Error("expecting agent id");
-        }
-        if (!this.id) {
-            return "not-started";
-        }
-        const url = `/agents/${this.subject.id}/tasks/${this.id}/metadata`;
-        const res = await this.client.fetch(url);
-        return stateToStatus(res.metadata.conversation.state);
-    }
-    /**
-     * Fetches messages from the conversation.
-     *
-     * @param {Object} [options] Optional fetch options.
-     * @param {Date} [options.from] Fetch messages after this timestamp.
-     *
-     * @returns {Promise<TaskMessage[]>} Array of messages in ascending order.
-     * @throws {Error} if the agent or task ID is missing.
-     */
-    async fetchMessages({ from = new Date(0) } = {}) {
-        if (!this.subject.id) {
-            throw new Error("expecting agent id");
-        }
-        if (!this.id) {
-            throw new Error("expecting task id");
-        }
-        const url = `/agents/${this.subject.id}/tasks/${this.id}/view`;
-        const res = await this.client.fetch(url, {
-            method: "POST",
-            body: JSON.stringify({
-                cursor: {
-                    after: from.toISOString(),
-                },
-            }),
-        });
-        // message should be in ascending order
-        return res.results.reverse().map((data) => new TaskMessage(data));
-    }
-}

package/esm/message.d.ts

@@ -1,18 +0,0 @@
-type TaskMessageType = "user-message" | "agent-message" | "tool-run" | "agent-error";
-export type MessageData = {
-    item_id: string;
-    insert_date_: string;
-    content: {
-        type: TaskMessageType;
-        text: string;
-    };
-};
-export declare class TaskMessage<T extends TaskMessageType = TaskMessageType> {
-    #private;
-    constructor(data: MessageData);
-    get id(): string;
-    get type(): T;
-    get createdAt(): Date;
-    get text(): string;
-}
-export {};

package/esm/message.js

@@ -1,18 +0,0 @@
-export class TaskMessage {
-    #data;
-    constructor(data) {
-        this.#data = data;
-    }
-    get id() {
-        return this.#data.item_id;
-    }
-    get type() {
-        return this.#data.content.type;
-    }
-    get createdAt() {
-        return new Date(this.#data.insert_date_);
-    }
-    get text() {
-        return this.#data.content.text;
-    }
-}

package/script/agent-task.d.ts

@@ -1,61 +0,0 @@
-import type { Agent } from "./agent.js";
-import { TaskMessage } from "./message.js";
-import { Task, type TaskStatus } from "./task.js";
-type AgentTaskEvents = {
-    start: {
-        status: TaskStatus;
-    };
-    status: {
-        status: TaskStatus;
-    };
-    message: {
-        message: TaskMessage<"agent-message" | "user-message">;
-    };
-    update: {
-        message: TaskMessage<"tool-run">;
-    };
-};
-export type AgentTaskState = "idle" | "starting-up" | "running" | "pending-approval" | "waiting-for-capacity" | "cancelled" | "timed-out" | "escalated" | "unrecoverable" | "paused" | "completed" | "errored-pending-approval" | "queued-for-approval" | "queued-for-rerun";
-/**
- * AgentTask represents a conversation task with an AI agent. It extends the
- * base Task class with agent-specific functionality for sending messages and
- * retrieving conversation history.
- *
- * @see {@link Task} for the base task functionality.
- * @see {@link Agent} for the agent this task is associated with.
- *
- * @class AgentTask
- * @extends Task<Agent, AgentTaskEvents>
- */
-export declare class AgentTask extends Task<Agent, AgentTaskEvents> {
-    /**
-     * Sends a message to the agent. This method triggers the agent with the
-     * message and updates the task ID if this is the first message.
-     *
-     * Note: This method is asynchronous but doesn't return a promise. Use event
-     * listeners to track the response.
-     *
-     * @param {string} message
-     */
-    sendMessage(message: string): void;
-    /**
-     * Fetches the current status of the task from the API.
-     *
-     * @returns {Promise<TaskStatus>} The current task status.
-     * @throws {Error} if the agent or task ID is missing.
-     */
-    fetchStatus(): Promise<TaskStatus>;
-    /**
-     * Fetches messages from the conversation.
-     *
-     * @param {Object} [options] Optional fetch options.
-     * @param {Date} [options.from] Fetch messages after this timestamp.
-     *
-     * @returns {Promise<TaskMessage[]>} Array of messages in ascending order.
-     * @throws {Error} if the agent or task ID is missing.
-     */
-    fetchMessages({ from }?: {
-        from?: Date;
-    }): Promise<TaskMessage[]>;
-}
-export {};