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

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

@@ -2,9 +2,4 @@ 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";
+export { Workforce } from "./workforce.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, TaskUpdatedEvent, } 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 TaskUpdatedEvent());
+                        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/utils.d.ts

@@ -2,3 +2,4 @@ export declare function abortPromise(signal: AbortSignal, reject?: boolean): Pro
 export declare function delay(timeout: number | (() => number)): Promise<void>;
 export declare function cleanPath(path: string, version?: string): string;
 export declare function randomUUID(): Promise<any>;
+export declare function getFileExtension(filename: string): string;

package/esm/utils.js

@@ -15,3 +15,7 @@ export async function randomUUID() {
     const cryptoModule = await import("node:crypto");
     return cryptoModule.randomUUID();
 }
+export function getFileExtension(filename) {
+    const dot = filename.lastIndexOf(".");
+    return dot >= 0 ? filename.slice(dot + 1) : "";
+}

package/esm/workforce.d.ts

@@ -0,0 +1,22 @@
+import { Client } from "./client.js";
+import type { Region } from "./region.js";
+import { type Task } from "./task/task.js";
+type WorkforceConfig = {
+    id: string;
+    workforce_metadata: {
+        name: string;
+    };
+};
+export declare class Workforce {
+    #private;
+    static get(id: string, client?: Client): Promise<Workforce>;
+    private readonly client;
+    constructor(config: WorkforceConfig, client: Client);
+    get id(): string;
+    get region(): Region;
+    get project(): string;
+    get name(): string;
+    getTask(id: string): Promise<Task<Workforce>>;
+    sendMessage(message: string, task?: Task<Workforce>): Promise<Task<Workforce>>;
+}
+export {};

package/esm/workforce.js

@@ -0,0 +1,50 @@
+import { Client } from "./client.js";
+import { resetBackoffDuration } from "./task/task.js";
+import { WorkforceStrategy } from "./task/workforce-strategy.js";
+export class Workforce {
+    static async get(id, client = Client.default()) {
+        const config = await client.fetch(`/workforce/items/${id}`);
+        return new Workforce(config, client);
+    }
+    client;
+    #config;
+    constructor(config, client) {
+        this.#config = config;
+        this.client = client;
+    }
+    get id() {
+        return this.#config.id;
+    }
+    get region() {
+        return this.client.region;
+    }
+    get project() {
+        return this.client.project;
+    }
+    get name() {
+        return this.#config.workforce_metadata.name;
+    }
+    async getTask(id) {
+        return await WorkforceStrategy.get(id, this, this.client);
+    }
+    async sendMessage(message, task) {
+        const { workforce_task_id: taskId } = await this.client.fetch("/workforce/trigger", {
+            method: "POST",
+            body: JSON.stringify({
+                workforce_id: this.id,
+                workforce_task_id: task?.id,
+                trigger: {
+                    message: {
+                        role: "user",
+                        content: message,
+                        attachments: [],
+                    },
+                },
+            }),
+        });
+        if (task) {
+            task[resetBackoffDuration]();
+        }
+        return task ?? this.getTask(taskId);
+    }
+}

package/package.json

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

package/script/agent.d.ts

@@ -1,7 +1,7 @@
-import { Client } from "./client.js";
+import { type Attachment, Client } from "./client.js";
 import type { Region } from "./region.js";
-import { Task } from "./task.js";
-interface AgentConfig {
+import { Task, type TaskStatus } from "./task/task.js";
+export interface AgentConfig {
     agent_id: string;
     public: boolean;
     name?: string;
@@ -9,21 +9,54 @@ interface AgentConfig {
     emoji?: string;
     insert_date_: string;
     update_date_: string;
+    model: string;
 }
+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";
+/**
+ * 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 declare function stateToStatus(state: AgentTaskState): TaskStatus;
+type SortDirection = "asc" | "desc";
+type GetTaskOptionSort = {
+    createdAt: SortDirection;
+} | {
+    updatedAt: SortDirection;
+};
+type GetTaskOptions = {
+    pageSize?: number;
+    page?: number;
+    sort?: GetTaskOptionSort;
+    search?: string;
+    filter?: {
+        status?: TaskStatus[];
+    };
+};
 export declare class Agent {
     #private;
-    private readonly client;
     static get(id: string, client?: Client): Promise<Agent>;
+    private readonly client;
     constructor(config: AgentConfig, client: Client);
     get id(): string;
+    get region(): Region;
+    get project(): string;
     get name(): string | undefined;
     get description(): string | undefined;
     get avatar(): string | undefined;
     get createdAt(): Date;
     get updatedAt(): Date;
-    get region(): Region;
-    get project(): string;
-    getTask(taskId: string): Promise<Task>;
-    sendMessage(message: string, task?: Task): Promise<Task>;
+    getTask(taskId: string): Promise<Task<Agent>>;
+    getTasks({ sort, pageSize, page, search, filter, }?: GetTaskOptions): Promise<Task<Agent>[]>;
+    sendMessage(message: string): Promise<Task<Agent>>;
+    sendMessage(message: string, task: Task<Agent>): Promise<Task<Agent>>;
+    sendMessage(message: string, attachments: (Attachment | File)[]): Promise<Task<Agent>>;
+    sendMessage(message: string, attachments: (Attachment | File)[], task: Task<Agent>): Promise<Task<Agent>>;
 }
 export {};