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

package/script/message/user.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserMessage = void 0;
+const task_js_1 = require("./task.js");
+class UserMessage extends task_js_1.TaskMessage {
+    /**
+     * The message as text sent.
+     *
+     * @property {string} text
+     */
+    get text() {
+        return this.message.content.text;
+    }
+    /**
+     * Returns if the message triggered a subject.
+     *
+     * @returns {boolean}
+     */
+    isTrigger() {
+        return this.message.content.is_trigger_message;
+    }
+}
+exports.UserMessage = UserMessage;

package/script/mod.d.ts

@@ -0,0 +1,10 @@
+export { Agent } from "./agent.js";
+export { Client, createClient } from "./client.js";
+export { Key } from "./key.js";
+export { type Region, REGION_AU, REGION_EU, REGION_US } from "./region.js";
+export { Task, type TaskStatus } from "./task.js";
+export type { AgentErrorMessage } from "./message/agent-error.js";
+export type { AgentMessage } from "./message/agent.js";
+export type { ToolMessage } from "./message/tool.js";
+export type { UserMessage } from "./message/user.js";
+export type { AnyTaskMessage } from "./message/task.js";

package/script/mod.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Task = exports.REGION_US = exports.REGION_EU = exports.REGION_AU = exports.Key = exports.createClient = exports.Client = exports.Agent = void 0;
+var agent_js_1 = require("./agent.js");
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return agent_js_1.Agent; } });
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_js_1.Client; } });
+Object.defineProperty(exports, "createClient", { enumerable: true, get: function () { return client_js_1.createClient; } });
+var key_js_1 = require("./key.js");
+Object.defineProperty(exports, "Key", { enumerable: true, get: function () { return key_js_1.Key; } });
+var region_js_1 = require("./region.js");
+Object.defineProperty(exports, "REGION_AU", { enumerable: true, get: function () { return region_js_1.REGION_AU; } });
+Object.defineProperty(exports, "REGION_EU", { enumerable: true, get: function () { return region_js_1.REGION_EU; } });
+Object.defineProperty(exports, "REGION_US", { enumerable: true, get: function () { return region_js_1.REGION_US; } });
+var task_js_1 = require("./task.js");
+Object.defineProperty(exports, "Task", { enumerable: true, get: function () { return task_js_1.Task; } });

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/script/region.d.ts

@@ -0,0 +1,5 @@
+export type Region = "bcbe5a" | "d7b62b" | "f1db6c";
+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;

package/script/region.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGION_AU = exports.REGION_EU = exports.REGION_US = void 0;
+exports.regionBaseURL = regionBaseURL;
+exports.REGION_US = "bcbe5a";
+exports.REGION_EU = "d7b62b";
+exports.REGION_AU = "f1db6c";
+function regionBaseURL(region) {
+    return `https://api-${region}.stack.tryrelevance.com`;
+}

package/script/task.d.ts

@@ -0,0 +1,57 @@
+import { Agent } from "./agent.js";
+import { Client } from "./client.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";
+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;
+    static get(id: string, agentOrAgentId: Agent | string, client?: Client): Promise<Task>;
+    readonly agent: Agent;
+    protected readonly client: Client;
+    protected constructor(metadata: TaskMetadata, agent: Agent, client?: Client);
+    get id(): string;
+    get title(): string;
+    get status(): TaskStatus;
+    isRunning(): boolean;
+    getMessages({ from }?: {
+        from?: Date;
+    }): 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/script/task.js

@@ -0,0 +1,263 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Task = exports.resetSubscribeBackoff = void 0;
+const agent_js_1 = require("./agent.js");
+const client_js_1 = require("./client.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");
+/**
+ * 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;
+    constructor(metadata, agent, client = client_js_1.Client.default()) {
+        super();
+        this.#metadata = metadata;
+        this.agent = agent;
+        this.client = client;
+    }
+    get id() {
+        return this.#metadata.knowledge_set;
+    }
+    get title() {
+        return this.#metadata.conversation.title ?? "";
+    }
+    get status() {
+        return stateToStatus(this.#metadata.conversation.state);
+    }
+    isRunning() {
+        switch (this.status) {
+            case "queued":
+            case "running":
+                return true;
+            default:
+                return false;
+        }
+    }
+    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.#controller = new AbortController();
+        const signal = this.#controller.signal;
+        let currentStatus = this.status;
+        const messagesCursor = new Date(0);
+        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,
+                            ])),
+                        ]);
+                    }
+                }
+            }
+        })();
+    }
+    isSubscribed() {
+        return this.#controller !== undefined;
+    }
+    unsubscribe() {
+        this.#delayController?.abort();
+        this.#controller?.abort();
+        this.#delayController = undefined;
+        this.#controller = undefined;
+    }
+    addEventListener(type, listener, options) {
+        this.subscribe();
+        const signal = AbortSignal.any([
+            ...(options && typeof options === "object" && options.signal
+                ? [options.signal]
+                : []),
+            this.#controller.signal,
+        ]);
+        const capture = typeof options === "boolean"
+            ? options
+            : Boolean(options?.capture);
+        const addOptions = Object.assign({}, options, { signal, capture });
+        super.addEventListener(type, listener, addOptions);
+    }
+}
+exports.Task = Task;

package/script/utils.d.ts

@@ -0,0 +1,4 @@
+export declare function abortPromise(signal: AbortSignal, reject?: 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

@@ -0,0 +1,56 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.abortPromise = abortPromise;
+exports.delay = delay;
+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, typeof timeout === "number" ? timeout : timeout()));
+}
+function cleanPath(path, version = "latest") {
+    return `/${version}/${path.trim().replace(/^\/+/, "")}`;
+}
+async function randomUUID() {
+    if (typeof crypto !== "undefined") {
+        return crypto.randomUUID();
+    }
+    // @ts-ignore allow this import for node builds
+    const cryptoModule = await Promise.resolve().then(() => __importStar(require("node:crypto")));
+    return cryptoModule.randomUUID();
+}

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;
-    }
-}