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

package/esm/agent.js

@@ -1,10 +1,94 @@
 import { Client } from "./client.js";
-import { resetSubscribeBackoff, Task } from "./task.js";
 import { randomUUID } from "./utils.js";
+import { AgentStrategy, } from "./task/agent-strategy.js";
+import { resetBackoffDuration, Task } from "./task/task.js";
+/**
+ * Converts an AgentTaskState to a simplified TaskStatus.
+ *
+ * @dev
+ *   We want to simplify because our states are simplified in the UI and also
+ *   some states have combined reasoning that the consumer does not need to care
+ *   about. i.e. "queued-for-approval" "queued-for-rerun" should just be "queued".
+ *
+ * @param {AgentTaskState} state The agent task state to convert.
+ * @returns {TaskStatus} The simplified task status.
+ */
+export function stateToStatus(state) {
+    switch (state) {
+        case "paused":
+            return "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":
+            return "cancelled";
+        case "completed":
+            return "completed";
+        case "unrecoverable":
+        case "errored-pending-approval":
+            return "error";
+        default:
+            throw new Error(`unhandled task state: ${state}`);
+    }
+}
+/**
+ * Reverses {@link stateToStatus} returning the group of task states a _simplified_
+ * status may relate to.
+ *
+ * @see {stateToStatus}
+ * @param {TaskStatus} status
+ * @returns {AgentTaskState[]}
+ */
+function statusToStates(status) {
+    switch (status) {
+        case "not-started":
+            // a special sdk-only status
+            return [];
+        case "idle":
+            return ["idle"];
+        case "paused":
+            return ["paused"];
+        case "queued":
+            return [
+                "starting-up",
+                "waiting-for-capacity",
+                "queued-for-approval",
+                "queued-for-rerun",
+            ];
+        case "running":
+            return ["running"];
+        case "action":
+            return ["pending-approval", "escalated"];
+        case "completed":
+            return ["completed"];
+        case "cancelled":
+            return ["cancelled"];
+        case "error":
+            return ["errored-pending-approval", "timed-out", "unrecoverable"];
+    }
+}
+function sortOptionsToParam(sort) {
+    if ("createdAt" in sort) {
+        return { insert_date: sort.createdAt };
+    }
+    else if ("updatedAt" in sort) {
+        return { update_date: sort.updatedAt };
+    }
+    throw new Error("invalid sort option");
+}
 const taskPrefixDelimiter = "_-_";
 export class Agent {
-    #config;
-    client;
     static async get(id, client = Client.default()) {
         const config = await Agent.#fetchConfig(id, client);
         return new Agent(config, client);
@@ -12,6 +96,8 @@ export class Agent {
     static #fetchConfig(agentId, client = Client.default()) {
         return client.fetch(`/agents/${agentId}/get`).then(({ agent }) => agent);
     }
+    #config;
+    client;
     constructor(config, client) {
         this.client = client;
         this.#config = config;
@@ -19,6 +105,12 @@ export class Agent {
     get id() {
         return this.#config.agent_id;
     }
+    get region() {
+        return this.client.region;
+    }
+    get project() {
+        return this.client.project;
+    }
     get name() {
         return this.#config.name;
     }
@@ -34,16 +126,54 @@ export class Agent {
     get updatedAt() {
         return new Date(this.#config.update_date_);
     }
-    get region() {
-        return this.client.region;
-    }
-    get project() {
-        return this.client.project;
-    }
     getTask(taskId) {
-        return Task.get(taskId, this, this.client);
+        return AgentStrategy.get(taskId, this, this.client);
+    }
+    async getTasks({ sort = { createdAt: "asc" }, pageSize = 100, page = 1, search, filter, } = {}) {
+        const filtersParam = [{
+                condition: "==",
+                condition_value: [this.id],
+                field: "conversation.agent_id",
+                filter_type: "exact_match",
+            }];
+        if (filter) {
+            for (const [field, value] of Object.entries(filter)) {
+                switch (field) {
+                    case "status":
+                        filtersParam.push({
+                            condition: "==",
+                            condition_value: value.flatMap((s) => statusToStates(s)),
+                            field: "conversation.state",
+                            filter_type: "exact_match",
+                        });
+                }
+            }
+        }
+        const sortParam = sortOptionsToParam(sort);
+        const query = new URLSearchParams([
+            ["filters", JSON.stringify(filtersParam)],
+            ["sort", JSON.stringify([sortParam])],
+            ["page_size", pageSize.toString()],
+            ["page", page.toString()],
+        ]);
+        if (search?.trim()) {
+            query.set("query", search.trim());
+        }
+        const { results } = await this.client.fetch(`/agents/conversations/list?${query.toString()}`);
+        return results.map(({ metadata }) => new Task({
+            id: metadata.knowledge_set,
+            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),
+        }, new AgentStrategy(metadata.knowledge_set, this, this.client)));
     }
-    async sendMessage(message, task) {
+    async sendMessage(message, attachOrTask, maybeTask) {
+        const hasAttachments = Array.isArray(attachOrTask);
+        const attachFiles = hasAttachments ? attachOrTask : [];
+        const task = hasAttachments ? maybeTask : attachOrTask;
         let taskId;
         // embed keys require a task prefixing for new tasks
         if (!task && this.client.isEmbedKey()) {
@@ -52,6 +182,10 @@ export class Agent {
         else if (task) {
             taskId = task.id;
         }
+        const attachments = [];
+        for (const item of attachFiles) {
+            attachments.push(item instanceof File ? await this.client.uploadTempFile(item) : item);
+        }
         const res = await this.client.fetch("/agents/trigger", {
             method: "POST",
             body: JSON.stringify({
@@ -60,12 +194,15 @@ export class Agent {
                 message: {
                     role: "user",
                     content: message,
-                    attachments: [], // @todo
+                    attachments: attachments.map(({ fileName, fileUrl }) => ({
+                        file_name: fileName,
+                        file_url: fileUrl,
+                    })),
                 },
             }),
         });
         if (task) {
-            task[resetSubscribeBackoff]();
+            task[resetBackoffDuration]();
         }
         return task ?? this.getTask(res.conversation_id);
     }

package/esm/client.d.ts

@@ -5,6 +5,10 @@ type CreateClientOptions = {
     region: Region;
     project: string;
 };
+export type Attachment = {
+    fileName: string;
+    fileUrl: string;
+};
 /**
  * Creates and returns the _default_ client instance.
  *
@@ -26,7 +30,8 @@ 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", 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" | "/services/get_temporary_file_upload_url" | `/workforce/items/${string}` | `/workforce/tasks/${string}/metadata` | `/workforce/items/${string}/tasks/${string}/messages` | "/workforce/trigger", init?: RequestInit): Promise<T>;
     url(path: string): URL;
+    uploadTempFile(file: File): Promise<Attachment>;
 }
 export {};

package/esm/client.js

@@ -1,5 +1,5 @@
 import { regionBaseURL } from "./region.js";
-import { cleanPath } from "./utils.js";
+import { cleanPath, getFileExtension } from "./utils.js";
 import { Key } from "./key.js";
 let defaultClient;
 /**
@@ -50,11 +50,16 @@ export class Client {
     }
     async fetch(input, init) {
         const url = this.url(input);
-        const headers = new Headers(this.key.fetchHeaders());
-        const response = await fetch(url, Object.assign({ headers }, init));
+        const reqInit = Object.assign({}, init, {
+            headers: {
+                ...this.key.fetchHeaders(),
+                ...init?.headers,
+            },
+        });
+        const response = await fetch(url, reqInit);
         if (!response.ok) {
             const body = await response.text();
-            console.error(url, init, headers, body);
+            console.error("client#fetch(): request failed.", url, body, reqInit);
             throw new Error(response.statusText);
         }
         return response.json();
@@ -65,4 +70,33 @@ export class Client {
         }
         return new URL(cleanPath(path), this.baseURL);
     }
+    async uploadTempFile(file) {
+        const { upload_url: uploadUrl, download_url: downloadUrl } = await this
+            .fetch("/services/get_temporary_file_upload_url", {
+            method: "POST",
+            body: JSON.stringify({
+                filename: file.name,
+                extension: getFileExtension(file.name),
+            }),
+        });
+        let content = file.type;
+        if (file.type.startsWith("text/")) {
+            content += "; charset=utf-8"; // force utf-8 for text files
+        }
+        const response = await fetch(uploadUrl, {
+            method: "PUT",
+            body: file,
+            headers: {
+                "content-type": content,
+                "x-amz-tagging": "Expire=true",
+            },
+        });
+        if (!response.ok) {
+            throw new Error(response.statusText);
+        }
+        return {
+            fileName: file.name,
+            fileUrl: downloadUrl,
+        };
+    }
 }

package/esm/event.d.ts

@@ -1,33 +1,14 @@
 import type { AgentErrorMessage } from "./message/agent-error.js";
-import type { AgentMessage } from "./message/agent.js";
-import type { ToolMessage } from "./message/tool.js";
-import type { UserMessage } from "./message/user.js";
-import type { TaskStatus } from "./task.js";
-export declare class TaskStartEvent extends CustomEvent<{
-    id: string;
-    status: TaskStatus;
-}> {
-    readonly type = "start";
-    constructor(id: string, status: TaskStatus);
-}
-export declare class TaskStatusEvent extends CustomEvent<{
-    status: TaskStatus;
-}> {
-    readonly type = "status";
-    constructor(status: TaskStatus);
+import type { AnyTaskMessage } from "./message/task.js";
+export declare class TaskUpdatedEvent extends CustomEvent<void> {
+    readonly type = "update";
+    constructor();
 }
 export declare class TaskMessageEvent extends CustomEvent<{
-    message: AgentMessage | UserMessage;
+    message: AnyTaskMessage;
 }> {
     readonly type = "message";
-    constructor(message: AgentMessage | UserMessage);
-    isUserMessage(): boolean;
-}
-export declare class TaskUpdateEvent extends CustomEvent<{
-    message: ToolMessage;
-}> {
-    readonly type = "update";
-    constructor(message: ToolMessage);
+    constructor(message: AnyTaskMessage);
 }
 export declare class TaskErrorEvent extends CustomEvent<{
     message: AgentErrorMessage;

package/esm/event.js

@@ -1,13 +1,7 @@
-export class TaskStartEvent extends CustomEvent {
-    type = "start";
-    constructor(id, status) {
-        super("start", { detail: { id, status } });
-    }
-}
-export class TaskStatusEvent extends CustomEvent {
-    type = "status";
-    constructor(status) {
-        super("status", { detail: { status } });
+export class TaskUpdatedEvent extends CustomEvent {
+    type = "update";
+    constructor() {
+        super("update");
     }
 }
 export class TaskMessageEvent extends CustomEvent {
@@ -15,15 +9,6 @@ export class TaskMessageEvent extends CustomEvent {
     constructor(message) {
         super("message", { detail: { message } });
     }
-    isUserMessage() {
-        return this.detail.message.type === "user-message";
-    }
-}
-export class TaskUpdateEvent extends CustomEvent {
-    type = "update";
-    constructor(message) {
-        super("update", { detail: { message } });
-    }
 }
 export class TaskErrorEvent extends CustomEvent {
     type = "error";

package/esm/key.d.ts

@@ -1,4 +1,4 @@
-import type { Region } from "./mod.js";
+import type { Region } from "./region.js";
 type CreateKeyOptions = {
     key: string;
     region: Region;

package/esm/message/agent-error.d.ts

@@ -1,6 +1,11 @@
-import { TaskMessage } from "./task.js";
+import { GenericMessage } from "./task.js";
 export interface AgentErrorMessageContent {
     type: "agent-error";
+    errors: {
+        body: string;
+    }[];
 }
-export declare class AgentErrorMessage extends TaskMessage<AgentErrorMessageContent> {
+export declare class AgentErrorMessage extends GenericMessage<AgentErrorMessageContent> {
+    get errors(): string[];
+    get lastError(): string;
 }

package/esm/message/agent-error.js

@@ -1,3 +1,9 @@
-import { TaskMessage } from "./task.js";
-export class AgentErrorMessage extends TaskMessage {
+import { GenericMessage } from "./task.js";
+export class AgentErrorMessage extends GenericMessage {
+    get errors() {
+        return this.message.content.errors.map((e) => e.body);
+    }
+    get lastError() {
+        return this.errors.at(-1);
+    }
 }

package/esm/message/agent.d.ts

@@ -1,9 +1,9 @@
-import { TaskMessage } from "./task.js";
+import { GenericMessage } from "./task.js";
 export interface AgentMessageContent {
     type: "agent-message";
     text: string;
 }
-export declare class AgentMessage extends TaskMessage<AgentMessageContent> {
+export declare class AgentMessage extends GenericMessage<AgentMessageContent> {
     get text(): string;
     get agentId(): string;
 }

package/esm/message/agent.js

@@ -1,5 +1,5 @@
-import { TaskMessage } from "./task.js";
-export class AgentMessage extends TaskMessage {
+import { GenericMessage } from "./task.js";
+export class AgentMessage extends GenericMessage {
     get text() {
         return this.message.content.text;
     }

package/esm/message/task.d.ts

@@ -2,7 +2,10 @@ import type { AgentMessage } from "./agent.js";
 import type { AgentErrorMessage } from "./agent-error.js";
 import type { ToolMessage } from "./tool.js";
 import type { UserMessage } from "./user.js";
-export type AnyTaskMessage = AgentMessage | AgentErrorMessage | ToolMessage | UserMessage;
+import type { WorkforceAgentMessage } from "./workforce-agent.js";
+import type { WorkforceAgentHandoverMessage } from "./workforce-agent-handover.js";
+export type AnyTaskMessage = AgentMessage | AgentErrorMessage | ToolMessage | UserMessage | WorkforceAgentMessage | WorkforceAgentHandoverMessage;
+export type TaskMessageType = AnyTaskMessage["type"];
 interface MessageContent {
     type: AnyTaskMessage["type"];
 }
@@ -11,13 +14,13 @@ export interface TaskMessageData<C extends MessageContent = MessageContent> {
     insert_date_: string;
     content: C;
 }
-export declare abstract class TaskMessage<C extends MessageContent = MessageContent> {
+export declare abstract class GenericMessage<C extends MessageContent = MessageContent> {
     protected readonly message: TaskMessageData<C>;
     constructor(message: TaskMessageData<C>);
     /**
      * The task's message type.
      *
-     * @property {"agent-error" | "agent-message" | "tool-run" | "user-message"}
+     * @property {TaskMessageType}
      */
     get type(): C["type"];
     /**
@@ -37,6 +40,24 @@ export declare abstract class TaskMessage<C extends MessageContent = MessageCont
      *
      * @returns {boolean}
      */
-    isAgent(): boolean;
+    isAgent(): this is AgentMessage;
+    /**
+     * Returns if the message is from a tool.
+     *
+     * @returns {boolean}
+     */
+    isTool(): this is ToolMessage;
+    /**
+     * Returns if the message was sent from a user.
+     *
+     * @returns {boolean}
+     */
+    isUser(): this is UserMessage;
+    /**
+     * Returns if the message was an error sent by the agent.
+     *
+     * @returns {boolean}
+     */
+    isAgentError(): this is AgentErrorMessage;
 }
 export {};

package/esm/message/task.js

@@ -1,4 +1,4 @@
-export class TaskMessage {
+export class GenericMessage {
     message;
     constructor(message) {
         this.message = message;
@@ -6,7 +6,7 @@ export class TaskMessage {
     /**
      * The task's message type.
      *
-     * @property {"agent-error" | "agent-message" | "tool-run" | "user-message"}
+     * @property {TaskMessageType}
      */
     get type() {
         return this.message.content.type;
@@ -35,4 +35,28 @@ export class TaskMessage {
     isAgent() {
         return this.type === "agent-message";
     }
+    /**
+     * Returns if the message is from a tool.
+     *
+     * @returns {boolean}
+     */
+    isTool() {
+        return this.type === "tool-run";
+    }
+    /**
+     * Returns if the message was sent from a user.
+     *
+     * @returns {boolean}
+     */
+    isUser() {
+        return this.type === "user-message";
+    }
+    /**
+     * Returns if the message was an error sent by the agent.
+     *
+     * @returns {boolean}
+     */
+    isAgentError() {
+        return this.type === "agent-error";
+    }
 }

package/esm/message/tool.d.ts

@@ -1,8 +1,10 @@
 import type { Region } from "../region.js";
-import { TaskMessage } from "./task.js";
+import { GenericMessage } from "./task.js";
+type ToolState = "cancelled" | "error" | "finished" | "pending" | "running";
+export type ToolStatus = "cancelled" | "error" | "completed" | "pending" | "running";
 export interface ToolMessageContent {
     type: "tool-run";
-    tool_run_state: "cancelled" | "error" | "finished" | "pending" | "running";
+    tool_run_state: ToolState;
     output: Record<string, unknown> & {
         _agent_conversation_details?: {
             agent_id: string;
@@ -25,13 +27,13 @@ export interface ToolMessageContent {
         project: string;
     };
 }
-export declare class ToolMessage extends TaskMessage<ToolMessageContent> {
+export declare class ToolMessage extends GenericMessage<ToolMessageContent> {
     /**
      * The tool status for _this_ message.
      *
-     * @property {"cancelled" | "error" | "finished" | "pending" | "running"}
+     * @property {ToolStatus}
      */
-    get status(): "cancelled" | "error" | "finished" | "pending" | "running";
+    get status(): ToolStatus;
     /**
      * Parameters used to call the tool.
      *
@@ -64,7 +66,7 @@ export declare class ToolMessage extends TaskMessage<ToolMessageContent> {
      * The agent's ID, if a sub-agent.
      *
      * @property {string}
-     * @see {@link ToolMessage.isSubAgent}
+     * @see {@link ToolMessage#isSubAgent}
      */
     get agentId(): string | null;
     /**
@@ -105,4 +107,12 @@ export declare class ToolMessage extends TaskMessage<ToolMessageContent> {
      * @returns {boolean}
      */
     hasErrors(): boolean;
+    /**
+     * Checks if the tool message is currently running. Note that pending tools
+     * are also classified as running as they are just scheduled for running.
+     *
+     * @returns {boolean}
+     */
+    isRunning(): boolean;
 }
+export {};

package/esm/message/tool.js

@@ -1,12 +1,23 @@
-import { TaskMessage } from "./task.js";
-export class ToolMessage extends TaskMessage {
+import { GenericMessage } from "./task.js";
+export class ToolMessage extends GenericMessage {
     /**
      * The tool status for _this_ message.
      *
-     * @property {"cancelled" | "error" | "finished" | "pending" | "running"}
+     * @property {ToolStatus}
      */
+    // deno-lint-ignore getter-return
     get status() {
-        return this.message.content.tool_run_state;
+        const status = this.message.content.tool_run_state;
+        switch (status) {
+            case "cancelled":
+            case "pending":
+            case "running":
+            case "error":
+                return status;
+            // agents and tools have different end statuses, align them
+            case "finished":
+                return "completed";
+        }
     }
     /**
      * Parameters used to call the tool.
@@ -22,7 +33,7 @@ export class ToolMessage extends TaskMessage {
      * @property {object|null}
      */
     get output() {
-        return this.status === "finished" ? this.message.content.output : null;
+        return this.status === "completed" ? this.message.content.output : null;
     }
     /**
      * Tool errors.
@@ -48,7 +59,7 @@ export class ToolMessage extends TaskMessage {
      * The agent's ID, if a sub-agent.
      *
      * @property {string}
-     * @see {@link ToolMessage.isSubAgent}
+     * @see {@link ToolMessage#isSubAgent}
      */
     get agentId() {
         return this.isSubAgent()
@@ -106,4 +117,19 @@ export class ToolMessage extends TaskMessage {
     hasErrors() {
         return this.message.content.errors.length > 0;
     }
+    /**
+     * Checks if the tool message is currently running. Note that pending tools
+     * are also classified as running as they are just scheduled for running.
+     *
+     * @returns {boolean}
+     */
+    isRunning() {
+        switch (this.status) {
+            case "pending":
+            case "running":
+                return true;
+            default:
+                return false;
+        }
+    }
 }

package/esm/message/user.d.ts

@@ -1,10 +1,10 @@
-import { TaskMessage } from "./task.js";
+import { GenericMessage } from "./task.js";
 export interface UserMessageContent {
     type: "user-message";
     text: string;
     is_trigger_message: boolean;
 }
-export declare class UserMessage extends TaskMessage<UserMessageContent> {
+export declare class UserMessage extends GenericMessage<UserMessageContent> {
     /**
      * The message as text sent.
      *

package/esm/message/user.js

@@ -1,5 +1,5 @@
-import { TaskMessage } from "./task.js";
-export class UserMessage extends TaskMessage {
+import { GenericMessage } from "./task.js";
+export class UserMessage extends GenericMessage {
     /**
      * The message as text sent.
      *