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

package/esm/message/tool.js

@@ -1,12 +1,33 @@
-import { TaskMessage } from "./task.js";
-export class ToolMessage extends TaskMessage {
+import { GenericMessage } from "./task.js";
+import { Tool } from "../tool.js";
+export class ToolMessage extends GenericMessage {
+    tool;
+    constructor(message) {
+        super(message);
+        if (message.content.tool_config.type === "tool") {
+            const { id, ...config } = message.content.tool_config;
+            this.tool = new Tool({ studio_id: id, ...config });
+        }
+        // @todo: subagent
+    }
     /**
      * 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 +43,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.
@@ -37,18 +58,18 @@ export class ToolMessage extends TaskMessage {
         }));
     }
     /**
-     * The tool's ID.
+     * The tool or agent ID.
      *
      * @property {string}
      */
-    get toolId() {
+    get toolOrAgentId() {
         return this.message.content.tool_config.id;
     }
     /**
      * The agent's ID, if a sub-agent.
      *
      * @property {string}
-     * @see {@link ToolMessage.isSubAgent}
+     * @see {@link ToolMessage#isSubAgent}
      */
     get agentId() {
         return this.isSubAgent()
@@ -72,8 +93,8 @@ export class ToolMessage extends TaskMessage {
         return this.message.content.tool_config.region;
     }
     /**
-     * The task ID the sub-agent ran. Will be `null` if the tool message is not
-     * a sub-agent.
+     * The task ID the subagent ran. Will be `null` if the tool message is not
+     * a subagent.
      *
      * @property {string}
      * @see {@link ToolMessage.isSubAgent}
@@ -106,4 +127,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,15 @@
-import { TaskMessage } from "./task.js";
+import type { Attachment } from "../client.js";
+import { GenericMessage } from "./task.js";
 export interface UserMessageContent {
+    attachments?: {
+        file_url: string;
+        file_name: string;
+    }[];
     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.
      *
@@ -17,4 +22,16 @@ export declare class UserMessage extends TaskMessage<UserMessageContent> {
      * @returns {boolean}
      */
     isTrigger(): boolean;
+    /**
+     * The attachments sent with the message.
+     *
+     * @property {Attachment[]}
+     */
+    get attachments(): Attachment[];
+    /**
+     * Returns if the message has attachments.
+     *
+     * @returns {boolean}
+     */
+    hasAttachments(): boolean;
 }

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.
      *
@@ -16,4 +16,23 @@ export class UserMessage extends TaskMessage {
     isTrigger() {
         return this.message.content.is_trigger_message;
     }
+    /**
+     * The attachments sent with the message.
+     *
+     * @property {Attachment[]}
+     */
+    get attachments() {
+        return (this.message.content.attachments?.map(({ file_name, file_url }) => ({
+            fileName: file_name,
+            fileUrl: file_url,
+        })) ?? []);
+    }
+    /**
+     * Returns if the message has attachments.
+     *
+     * @returns {boolean}
+     */
+    hasAttachments() {
+        return this.attachments.length > 0;
+    }
 }

package/esm/message/workforce-agent-handover.d.ts

@@ -0,0 +1,23 @@
+import { GenericMessage } from "./task.js";
+export interface WorkforceAgentHandoverMessageContent {
+    type: "workforce-agent-handover";
+    task_details?: {
+        project: string;
+        region: string;
+        conversation_id: string;
+    };
+    agent_details: {
+        agent_id: string;
+        project: string;
+        region: string;
+        name?: string;
+        emoji?: string;
+        description?: string;
+        deleted_reason?: "entity_deleted";
+    };
+    trigger: {
+        message: string;
+    };
+}
+export declare class WorkforceAgentHandoverMessage extends GenericMessage<WorkforceAgentHandoverMessageContent> {
+}

package/esm/message/workforce-agent-handover.js

@@ -0,0 +1,3 @@
+import { GenericMessage } from "./task.js";
+export class WorkforceAgentHandoverMessage extends GenericMessage {
+}

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

@@ -0,0 +1,23 @@
+import type { AgentTaskState } from "../agent.js";
+import { GenericMessage } from "./task.js";
+export interface WorkforceAgentMessageContent {
+    type: "workforce-agent-run";
+    task_details: {
+        project: string;
+        region: string;
+        conversation_id: string;
+        finished_state?: AgentTaskState;
+        current_state?: AgentTaskState;
+    };
+    agent_details?: {
+        agent_id: string;
+        project: string;
+        region: string;
+        name?: string;
+        emoji?: string;
+        description?: string;
+        deleted_reason?: "entity_deleted";
+    };
+}
+export declare class WorkforceAgentMessage extends GenericMessage<WorkforceAgentMessageContent> {
+}

package/esm/message/workforce-agent.js

@@ -0,0 +1,3 @@
+import { GenericMessage } from "./task.js";
+export class WorkforceAgentMessage extends GenericMessage {
+}

package/esm/mod.d.ts

@@ -1,10 +1,6 @@
 export { Agent } from "./agent.js";
-export { Client, createClient } from "./client.js";
+export { type Attachment, 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";
+export { Workforce } from "./workforce.js";
+export type { Task } from "./task/task.js";

package/esm/mod.js

@@ -2,4 +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";
+export { Workforce } from "./workforce.js";

package/esm/task/agent-strategy.d.ts

@@ -0,0 +1,26 @@
+import { type Agent, type AgentTaskState } from "../agent.js";
+import { Client } from "../client.js";
+import type { AnyTaskMessage } from "../message/task.js";
+import { Task, type TaskMetadata, type TaskStrategy } from "./task.js";
+export type AgentTaskMetadata = {
+    knowledge_set: string;
+    insert_date: string;
+    update_date: string;
+    conversation: {
+        created_by_user_id: string;
+        state: AgentTaskState;
+        title: string;
+    };
+};
+export declare class AgentStrategy implements TaskStrategy<Agent> {
+    static get(id: string, agent: Agent, client?: Client): Promise<Task<Agent>>;
+    private readonly id;
+    private readonly agent;
+    private readonly client;
+    constructor(id: string, agent: Agent, client: Client);
+    get subject(): Agent;
+    getMetadata(): Promise<TaskMetadata>;
+    getMessages({ after }?: {
+        after?: Date;
+    }): Promise<AnyTaskMessage[]>;
+}

package/esm/task/agent-strategy.js

@@ -0,0 +1,63 @@
+import { stateToStatus } from "../agent.js";
+import { Client } from "../client.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 { Task } from "./task.js";
+export class AgentStrategy {
+    static async get(id, agent, client = Client.default()) {
+        const subject = new this(id, agent, client);
+        return new Task(await subject.getMetadata(), subject);
+    }
+    id;
+    agent;
+    client;
+    constructor(id, agent, client) {
+        this.id = id;
+        this.agent = agent;
+        this.client = client;
+    }
+    get subject() {
+        return this.agent;
+    }
+    async getMetadata() {
+        const { metadata } = await this.client.fetch(`/agents/${this.agent.id}/tasks/${this.id}/metadata`);
+        return {
+            id: this.id,
+            region: this.client.region,
+            project: this.client.project,
+            name: metadata.conversation.title,
+            status: stateToStatus(metadata.conversation.state),
+            createdAt: new Date(metadata.insert_date),
+            updatedAt: new Date(metadata.update_date),
+        };
+    }
+    async getMessages({ after = 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: after.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");
+            }
+        });
+    }
+}

package/esm/task/task.d.ts

@@ -0,0 +1,59 @@
+import { Emitter } from "../emitter.js";
+import type { AnyTaskMessage } from "../message/task.js";
+import type { Region } from "../region.js";
+import type { Workforce } from "../workforce.js";
+import type { Agent } from "../agent.js";
+import type { AgentErrorMessage } from "../message/agent-error.js";
+export type TaskStatus = "not-started" | "idle" | "paused" | "queued" | "running" | "action" | "completed" | "cancelled" | "error";
+export interface TaskMetadata {
+    id: string;
+    region: Region;
+    project: string;
+    status: TaskStatus;
+    name: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+type TaskEventMap = {
+    updated: undefined;
+    message: {
+        message: AnyTaskMessage;
+    };
+    error: {
+        message: AgentErrorMessage;
+    };
+};
+export interface TaskStrategy<S> {
+    subject: S;
+    getMessages(options?: {
+        after?: Date;
+    }): Promise<AnyTaskMessage[]>;
+    getMetadata(): Promise<TaskMetadata>;
+}
+export declare const resetBackoffDuration: unique symbol;
+export declare class Task<S extends Agent | Workforce, E extends TaskEventMap = TaskEventMap> extends Emitter<E> {
+    #private;
+    private subscribed;
+    private backoff;
+    private backoffDuration;
+    private readonly strategy;
+    constructor(metadata: TaskMetadata, strategy: TaskStrategy<S>);
+    get subject(): S;
+    get id(): string;
+    get region(): Region;
+    get project(): string;
+    get name(): string;
+    get status(): TaskStatus;
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    getMessages(options?: {
+        after?: Date;
+    }): Promise<AnyTaskMessage[]>;
+    isRunning(): boolean;
+    unsubscribe(): void;
+    [resetBackoffDuration](): 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;
+}
+export {};

package/esm/task/task.js

@@ -0,0 +1,166 @@
+import { Emitter } from "../emitter.js";
+import { abortPromise, delay } from "../utils.js";
+import { TaskErrorEvent, TaskMessageEvent, TaskUpdateEvent, } from "../event.js";
+export const resetBackoffDuration = Symbol("resetBackoffDuration");
+const backoffStartingDuration = 1_000;
+const backoffMaxDuration = 60_000;
+export class Task extends Emitter {
+    subscribed = null;
+    backoff = null;
+    backoffDuration = 0;
+    strategy;
+    #metadata;
+    constructor(metadata, strategy) {
+        super();
+        this.strategy = strategy;
+        this.#metadata = metadata;
+    }
+    get subject() {
+        return this.strategy.subject;
+    }
+    get id() {
+        return this.#metadata.id;
+    }
+    get region() {
+        return this.#metadata.region;
+    }
+    get project() {
+        return this.#metadata.project;
+    }
+    get name() {
+        return this.#metadata.name;
+    }
+    get status() {
+        return this.#metadata.status;
+    }
+    get createdAt() {
+        return this.#metadata.createdAt;
+    }
+    get updatedAt() {
+        return this.#metadata.updatedAt;
+    }
+    getMessages(options) {
+        return this.strategy.getMessages(options);
+    }
+    isRunning() {
+        switch (this.status) {
+            case "queued":
+            case "running":
+                return true;
+            default:
+                return false;
+        }
+    }
+    #subscribe() {
+        if (this.subscribed) {
+            return;
+        }
+        const subscribed = new AbortController();
+        this.subscribed = subscribed; // subscribed ref
+        const isSubscribed = () => !subscribed.signal.aborted;
+        this.backoffDuration = backoffStartingDuration;
+        const cursor = new Date(0);
+        const emitted = new Set();
+        const pending = new Map();
+        void (async () => {
+            while (isSubscribed()) {
+                try {
+                    const [metadata, messages] = await Promise.all([
+                        this.strategy.getMetadata(),
+                        this.strategy.getMessages({ after: cursor }),
+                    ]);
+                    if (!isSubscribed()) {
+                        break;
+                    }
+                    let hasChanges = false;
+                    if (metadata.updatedAt > this.updatedAt) {
+                        this.dispatchEvent(new TaskUpdateEvent());
+                        hasChanges = true;
+                    }
+                    this.#metadata = metadata;
+                    if (messages.length) {
+                        for (const message of messages) {
+                            if (emitted.has(message.id)) {
+                                continue;
+                            }
+                            switch (message.type) {
+                                case "agent-error":
+                                    emitted.add(message.id);
+                                    this.dispatchEvent(new TaskErrorEvent(message));
+                                    break;
+                                case "tool-run": {
+                                    const { status } = message;
+                                    if (pending.get(message.id)?.status == status) {
+                                        // no change to the tool status
+                                        continue;
+                                    }
+                                    if (["pending", "running"].includes(status)) {
+                                        pending.set(message.id, message);
+                                    }
+                                    else {
+                                        emitted.add(message.id);
+                                        pending.delete(message.id);
+                                    }
+                                    this.dispatchEvent(new TaskMessageEvent(message));
+                                    break;
+                                }
+                                case "agent-message":
+                                case "user-message":
+                                    hasChanges = true;
+                                    emitted.add(message.id);
+                                    this.dispatchEvent(new TaskMessageEvent(message));
+                            }
+                        }
+                        let latest = messages.at(-1).createdAt;
+                        for (const message of pending.values()) {
+                            if (latest > message.createdAt) {
+                                latest = message.createdAt;
+                            }
+                        }
+                        cursor.setTime(latest.getTime());
+                    }
+                    if (hasChanges) {
+                        this.backoffDuration = backoffStartingDuration;
+                    }
+                    else if (!this.isRunning()) {
+                        this.backoffDuration = Math.min(this.backoffDuration * 2, backoffMaxDuration);
+                    }
+                }
+                finally {
+                    if (isSubscribed()) {
+                        const backoff = new AbortController();
+                        this.backoff = backoff;
+                        await Promise.race([
+                            delay(this.backoffDuration),
+                            abortPromise(AbortSignal.any([subscribed.signal, backoff.signal])),
+                        ]);
+                    }
+                }
+            }
+        })();
+    }
+    unsubscribe() {
+        this.subscribed?.abort();
+        this.subscribed = null;
+        this.backoff?.abort();
+        this.backoff = null;
+        this.backoffDuration = 0;
+    }
+    [resetBackoffDuration]() {
+        this.backoffDuration = backoffStartingDuration;
+    }
+    addEventListener(type, listener, options) {
+        this.#subscribe();
+        const signal = AbortSignal.any([
+            ...(options && typeof options === "object" && options.signal
+                ? [options.signal]
+                : []),
+            ...(this.subscribed ? [this.subscribed.signal] : []),
+        ]);
+        const capture = typeof options === "boolean"
+            ? options
+            : Boolean(options?.capture);
+        const addOptions = Object.assign({}, options, { signal, capture });
+        super.addEventListener(type, listener, addOptions);
+    }
+}

package/esm/task/workforce-strategy.d.ts

@@ -0,0 +1,17 @@
+import type { AnyTaskMessage } from "../message/task.js";
+import { Client } from "../client.js";
+import { Task, type TaskMetadata, type TaskStatus, type TaskStrategy } from "./task.js";
+import type { Workforce } from "../workforce.js";
+export declare class WorkforceStrategy implements TaskStrategy<Workforce> {
+    static get(id: string, workforce: Workforce, client?: Client): Promise<Task<Workforce>>;
+    static convertStatus(): TaskStatus;
+    private readonly id;
+    private readonly workforce;
+    private readonly client;
+    private constructor();
+    get subject(): Workforce;
+    getMessages({ after: _after }: {
+        after?: Date;
+    }): Promise<AnyTaskMessage[]>;
+    getMetadata(): Promise<TaskMetadata>;
+}

package/esm/task/workforce-strategy.js

@@ -0,0 +1,68 @@
+import { Client } from "../client.js";
+import { Task, } from "./task.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 { WorkforceAgentMessage, } from "../message/workforce-agent.js";
+import { WorkforceAgentHandoverMessage, } from "../message/workforce-agent-handover.js";
+export class WorkforceStrategy {
+    static async get(id, workforce, client = Client.default()) {
+        const subject = new this(id, workforce, client);
+        const metadata = await subject.getMetadata();
+        return new Task(metadata, subject);
+    }
+    static convertStatus() {
+        return "not-implemented";
+    }
+    id;
+    workforce;
+    client;
+    constructor(id, workforce, client) {
+        this.id = id;
+        this.workforce = workforce;
+        this.client = client;
+    }
+    get subject() {
+        return this.workforce;
+    }
+    async getMessages({ after: _after }) {
+        const { results } = await this.client.fetch(`/workforce/items/${this.workforce.id}/tasks/${this.id}/messages`, {
+            method: "POST",
+            body: JSON.stringify({
+                page_size: 1_000, // @todo: pagination
+                // @todo: cursor "before" :S
+            }),
+        });
+        return results.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);
+                case "workforce-agent-run":
+                    return new WorkforceAgentMessage(data);
+                case "workforce-agent-handover":
+                    return new WorkforceAgentHandoverMessage(data);
+                default:
+                    throw new Error("unknown message response");
+            }
+        });
+    }
+    async getMetadata() {
+        const { metadata } = await this.client.fetch(`/workforce/tasks/${this.id}/metadata`);
+        return {
+            id: this.id,
+            region: this.client.region,
+            project: this.client.project,
+            name: metadata.title,
+            status: WorkforceStrategy.convertStatus(), // @todo: not implemented
+            createdAt: new Date(metadata.insert_date),
+            updatedAt: new Date(metadata.update_date),
+        };
+    }
+}

package/esm/tool.d.ts

@@ -0,0 +1,22 @@
+import type { Region } from "./region.js";
+import type { JSONSchema4 } from "json-schema";
+export type ToolConfig = {
+    region: Region;
+    project: string;
+    studio_id: string;
+    title: string;
+    description: string;
+    emoji?: string;
+    params_schema: JSONSchema4;
+};
+export declare class Tool {
+    #private;
+    constructor(config: ToolConfig);
+    get id(): string;
+    get region(): Region;
+    get project(): string;
+    get name(): string;
+    get avatar(): string | undefined;
+    get description(): string | undefined;
+    get parametersSchema(): JSONSchema4;
+}