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

package/esm/mod.js

@@ -2,3 +2,4 @@ export { Agent } from "./agent.js";
 export { Client, createClient } from "./client.js";
 export { Key } from "./key.js";
 export { REGION_AU, REGION_EU, REGION_US } from "./region.js";
+export { Task } from "./task.js";

package/esm/task.d.ts

@@ -1,25 +1,57 @@
+import { Agent } from "./agent.js";
 import { Client } from "./client.js";
-import type { TaskMessage } from "./message.js";
+import { Emitter } from "./emitter.js";
+import { AgentMessage } from "./message/agent.js";
+import type { AnyTaskMessage } from "./message/task.js";
+import { ToolMessage } from "./message/tool.js";
+import { UserMessage } from "./message/user.js";
+export type TaskState = "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";
 export type TaskStatus = "not-started" | "idle" | "queued" | "running" | "action" | "complete" | "error";
-export declare abstract class Task<S, E extends Record<string, unknown>> extends EventTarget {
+type TaskMetadata = {
+    knowledge_set: string;
+    insert_date: string;
+    update_date: string;
+    conversation: {
+        created_by_user_id: string;
+        state: TaskState;
+        title: string;
+    };
+};
+type TaskEventMap = {
+    start: {
+        status: TaskStatus;
+    };
+    status: {
+        status: TaskStatus;
+    };
+    message: {
+        message: AgentMessage | UserMessage;
+    };
+    update: {
+        message: ToolMessage;
+    };
+};
+export declare const resetSubscribeBackoff: unique symbol;
+export declare class Task extends Emitter<TaskEventMap> {
     #private;
-    readonly subject: S;
+    static get(id: string, agentOrAgentId: Agent | string, client?: Client): Promise<Task>;
+    readonly agent: Agent;
     protected readonly client: Client;
-    private listenController;
-    abstract fetchMessages(fetchOptions?: {
+    protected constructor(metadata: TaskMetadata, agent: Agent, client?: Client);
+    get id(): string;
+    get title(): string;
+    get status(): TaskStatus;
+    isRunning(): boolean;
+    getMessages({ from }?: {
         from?: Date;
-    }): Promise<TaskMessage[]>;
-    abstract fetchStatus(): Promise<TaskStatus>;
-    constructor(subject: S, id?: string | undefined, client?: Client);
-    get id(): string | undefined;
-    protected setId(id: string, status?: TaskStatus): void;
-    listen(): void;
-    isListening(): boolean;
-    stopListening(): void;
-    addEventListener<K extends keyof E>(type: Extract<K, string>, listener: ((event: CustomEvent<E[K]>) => void) | {
-        handleEvent: (event: CustomEvent<E[K]>) => void;
-    } | null, options?: boolean | AddEventListenerOptions): void;
-    removeEventListener<K extends keyof E>(type: Extract<K, string>, listener: ((event: CustomEvent<E[K]>) => void) | {
-        handleEvent: (event: CustomEvent<E[K]>) => void;
+    }): Promise<AnyTaskMessage[]>;
+    protected refresh(): Promise<void>;
+    [resetSubscribeBackoff](): void;
+    subscribe(): void;
+    protected isSubscribed(): boolean;
+    unsubscribe(): void;
+    addEventListener<K extends keyof TaskEventMap>(type: Extract<K, string>, listener: ((event: CustomEvent<TaskEventMap[K]>) => void) | {
+        handleEvent: (event: CustomEvent<TaskEventMap[K]>) => void;
     } | null, options?: boolean | AddEventListenerOptions): void;
 }
+export {};

package/esm/task.js

@@ -1,88 +1,254 @@
+import { Agent } from "./agent.js";
 import { Client } from "./client.js";
-import { TaskErrorEvent, TaskMessageEvent, TaskStartEvent, TaskStatusEvent, TaskUpdateEvent, } from "./events.js";
-import { runInterval } from "./utils.js";
-export class Task extends EventTarget {
-    subject;
+import { Emitter } from "./emitter.js";
+import { TaskErrorEvent, TaskMessageEvent, TaskStatusEvent, TaskUpdateEvent, } from "./event.js";
+import { AgentErrorMessage, } from "./message/agent-error.js";
+import { AgentMessage } from "./message/agent.js";
+import { ToolMessage } from "./message/tool.js";
+import { UserMessage } from "./message/user.js";
+import { abortPromise, delay } from "./utils.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}`);
+    }
+}
+export const resetSubscribeBackoff = Symbol("resetSubscribeBackoff");
+export class Task extends Emitter {
+    static async get(id, agentOrAgentId, client = Client.default()) {
+        const agent = typeof agentOrAgentId === "string"
+            ? await 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.default()) {
+    constructor(metadata, agent, client = 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 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 AgentErrorMessage(data);
+                case "agent-message":
+                    return new AgentMessage(data);
+                case "tool-run":
+                    return new ToolMessage(data);
+                case "user-message":
+                    return new UserMessage(data);
+                default:
+                    throw new Error("unknown message response");
+            }
+        });
+    }
+    async refresh() {
+        this.#metadata = await Task.#fetchMetadata(this.id, this.agent.id, this.client);
+    }
+    [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 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 TaskStatusEvent(status));
-            }
-            if (messages.length) {
-                for (const message of messages) {
-                    switch (message.type) {
-                        case "agent-error":
-                            this.dispatchEvent(new TaskErrorEvent(message));
-                            break;
-                        case "tool-run":
-                            this.dispatchEvent(new TaskUpdateEvent(message));
-                            break;
-                        case "agent-message":
-                        case "user-message":
-                            this.dispatchEvent(new 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 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 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 TaskUpdateEvent(message));
+                                    break;
+                                }
+                                case "agent-message":
+                                case "user-message":
+                                    this.dispatchEvent(new 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([
+                            delay(this.#backoffMs),
+                            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
@@ -90,7 +256,4 @@ export 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);
-    }
 }

package/esm/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/esm/utils.js

@@ -2,19 +2,7 @@ export function abortPromise(signal, reject) {
     return new Promise((res, rej) => signal.addEventListener("abort", () => reject ? rej() : res()));
 }
 export function delay(timeout) {
-    return new Promise((done) => setTimeout(done, timeout));
-}
-export 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()));
 }
 export function cleanPath(path, version = "latest") {
     return `/${version}/${path.trim().replace(/^\/+/, "")}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relevanceai/sdk",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.4",
   "license": "MIT",
   "main": "./script/mod.js",
   "module": "./esm/mod.js",

package/script/agent.d.ts

@@ -1,17 +1,29 @@
-import type { AgentTaskState } from "./agent-task.js";
 import { Client } from "./client.js";
+import type { Region } from "./region.js";
+import { Task } from "./task.js";
+interface AgentConfig {
+    agent_id: string;
+    public: boolean;
+    name?: string;
+    description?: string;
+    emoji?: string;
+    insert_date_: string;
+    update_date_: string;
+}
 export declare class Agent {
     #private;
     private readonly client;
-    static fetch(agentId: string, cli?: Client): Promise<Agent>;
-    private constructor();
+    static get(id: string, client?: Client): Promise<Agent>;
+    constructor(config: AgentConfig, client: Client);
     get id(): string;
     get name(): string | undefined;
     get description(): string | undefined;
     get avatar(): string | undefined;
-    isPublic(): boolean;
-    trigger(message: string, taskId?: string): Promise<{
-        id: string;
-        state: AgentTaskState;
-    }>;
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    get region(): Region;
+    get project(): string;
+    getTask(taskId: string): Promise<Task>;
+    sendMessage(message: string, task?: Task): Promise<Task>;
 }
+export {};

package/script/agent.js

@@ -2,18 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Agent = void 0;
 const client_js_1 = require("./client.js");
+const task_js_1 = require("./task.js");
 const utils_js_1 = require("./utils.js");
 const taskPrefixDelimiter = "_-_";
 class Agent {
     #config;
     client;
-    static async fetch(agentId, cli = client_js_1.Client.default()) {
-        const config = await cli.fetch(`/agents/${agentId}/get`);
-        return new Agent(config.agent, cli);
+    static async get(id, client = client_js_1.Client.default()) {
+        const config = await Agent.#fetchConfig(id, client);
+        return new Agent(config, client);
+    }
+    static #fetchConfig(agentId, client = client_js_1.Client.default()) {
+        return client.fetch(`/agents/${agentId}/get`).then(({ agent }) => agent);
     }
     constructor(config, client) {
-        this.#config = config;
         this.client = client;
+        this.#config = config;
     }
     get id() {
         return this.#config.agent_id;
@@ -27,14 +31,30 @@ class Agent {
     get avatar() {
         return this.#config.emoji;
     }
-    isPublic() {
-        return this.#config.public;
+    get createdAt() {
+        return new Date(this.#config.insert_date_);
+    }
+    get updatedAt() {
+        return new Date(this.#config.update_date_);
+    }
+    get region() {
+        return this.client.region;
     }
-    async trigger(message, taskId) {
+    get project() {
+        return this.client.project;
+    }
+    getTask(taskId) {
+        return task_js_1.Task.get(taskId, this, this.client);
+    }
+    async sendMessage(message, task) {
+        let taskId;
         // embed keys require a task prefixing for new tasks
-        if (!taskId && this.client.isEmbedKey()) {
+        if (!task && this.client.isEmbedKey()) {
             taskId = [this.client.key.taskPrefix, await (0, utils_js_1.randomUUID)()].join(taskPrefixDelimiter);
         }
+        else if (task) {
+            taskId = task.id;
+        }
         const res = await this.client.fetch("/agents/trigger", {
             method: "POST",
             body: JSON.stringify({
@@ -47,10 +67,10 @@ class Agent {
                 },
             }),
         });
-        return {
-            id: res.conversation_id,
-            state: res.state,
-        };
+        if (task) {
+            task[task_js_1.resetSubscribeBackoff]();
+        }
+        return task ?? this.getTask(res.conversation_id);
     }
 }
 exports.Agent = Agent;

package/script/client.d.ts

@@ -1,6 +1,4 @@
-import { Agent } from "./agent.js";
 import { type Region } from "./region.js";
-import { AgentTask } from "./agent-task.js";
 import { Key } from "./key.js";
 type CreateClientOptions = {
     apiKey: string;
@@ -11,7 +9,7 @@ type CreateClientOptions = {
  * Creates and returns the _default_ client instance.
  *
  * @throws {Error} if a default client already exists.
- * @see {Client.default}
+ * @see {@link Client.default}
  */
 export declare function createClient(keyOrOptions: Key | CreateClientOptions): Client;
 export declare class Client {
@@ -19,7 +17,7 @@ export declare class Client {
      * Returns the _default_ client instance.
      *
      * @throws {Error} if there is no default client.
-     * @see {createClient}
+     * @see {@link createClient}
      */
     static default(): Client;
     readonly key: Key;
@@ -28,9 +26,7 @@ export declare class Client {
     get region(): Region;
     get project(): string;
     isEmbedKey(): boolean;
-    createTask({ agent }: {
-        agent: string | Agent;
-    }): Promise<AgentTask>;
-    fetch<T>(input: `/agents/trigger` | `/agents/${string}/get` | `/agents/${string}/tasks/${string}/metadata` | `/agents/${string}/tasks/${string}/view`, init?: RequestInit): Promise<T>;
+    fetch<T>(input: "/agents/trigger" | `/agents/${string}/get` | `/agents/${string}/tasks/${string}/metadata` | `/agents/${string}/tasks/${string}/view` | "/agents/conversations/list", init?: RequestInit): Promise<T>;
+    url(path: string): URL;
 }
 export {};

package/script/client.js

@@ -2,9 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Client = void 0;
 exports.createClient = createClient;
-const agent_js_1 = require("./agent.js");
 const region_js_1 = require("./region.js");
-const agent_task_js_1 = require("./agent-task.js");
 const utils_js_1 = require("./utils.js");
 const key_js_1 = require("./key.js");
 let defaultClient;
@@ -12,7 +10,7 @@ let defaultClient;
  * Creates and returns the _default_ client instance.
  *
  * @throws {Error} if a default client already exists.
- * @see {Client.default}
+ * @see {@link Client.default}
  */
 function createClient(keyOrOptions) {
     if (defaultClient) {
@@ -31,7 +29,7 @@ class Client {
      * Returns the _default_ client instance.
      *
      * @throws {Error} if there is no default client.
-     * @see {createClient}
+     * @see {@link createClient}
      */
     static default() {
         if (!defaultClient) {
@@ -54,21 +52,22 @@ class Client {
     isEmbedKey() {
         return this.key.isEmbed();
     }
-    async createTask({ agent }) {
-        if (agent) {
-            return new agent_task_js_1.AgentTask(typeof agent === "string" ? await agent_js_1.Agent.fetch(agent) : agent, undefined, this);
-        }
-        throw new Error("task not implemented");
-    }
     async fetch(input, init) {
-        const url = new URL((0, utils_js_1.cleanPath)(input), this.baseURL);
+        const url = this.url(input);
         const headers = new Headers(this.key.fetchHeaders());
         const response = await fetch(url, Object.assign({ headers }, init));
         if (!response.ok) {
-            console.error(url, init, headers);
+            const body = await response.text();
+            console.error(url, init, headers, body);
             throw new Error(response.statusText);
         }
         return response.json();
     }
+    url(path) {
+        if (/^https?:\/\//.test(path)) {
+            return new URL(path);
+        }
+        return new URL((0, utils_js_1.cleanPath)(path), this.baseURL);
+    }
 }
 exports.Client = Client;