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

package/esm/agent.d.ts

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

package/esm/agent.js

@@ -1,16 +1,20 @@
 import { Client } from "./client.js";
+import { resetSubscribeBackoff, Task } from "./task.js";
 import { randomUUID } from "./utils.js";
 const taskPrefixDelimiter = "_-_";
 export class Agent {
     #config;
     client;
-    static async fetch(agentId, cli = Client.default()) {
-        const config = await cli.fetch(`/agents/${agentId}/get`);
-        return new Agent(config.agent, cli);
+    static async get(id, client = Client.default()) {
+        const config = await Agent.#fetchConfig(id, client);
+        return new Agent(config, client);
+    }
+    static #fetchConfig(agentId, client = Client.default()) {
+        return client.fetch(`/agents/${agentId}/get`).then(({ agent }) => agent);
     }
     constructor(config, client) {
-        this.#config = config;
         this.client = client;
+        this.#config = config;
     }
     get id() {
         return this.#config.agent_id;
@@ -24,14 +28,30 @@ export class Agent {
     get avatar() {
         return this.#config.emoji;
     }
-    isPublic() {
-        return this.#config.public;
+    get createdAt() {
+        return new Date(this.#config.insert_date_);
+    }
+    get updatedAt() {
+        return new Date(this.#config.update_date_);
+    }
+    get region() {
+        return this.client.region;
     }
-    async trigger(message, taskId) {
+    get project() {
+        return this.client.project;
+    }
+    getTask(taskId) {
+        return Task.get(taskId, this, this.client);
+    }
+    async sendMessage(message, task) {
+        let taskId;
         // embed keys require a task prefixing for new tasks
-        if (!taskId && this.client.isEmbedKey()) {
+        if (!task && this.client.isEmbedKey()) {
             taskId = [this.client.key.taskPrefix, await randomUUID()].join(taskPrefixDelimiter);
         }
+        else if (task) {
+            taskId = task.id;
+        }
         const res = await this.client.fetch("/agents/trigger", {
             method: "POST",
             body: JSON.stringify({
@@ -44,9 +64,9 @@ export class Agent {
                 },
             }),
         });
-        return {
-            id: res.conversation_id,
-            state: res.state,
-        };
+        if (task) {
+            task[resetSubscribeBackoff]();
+        }
+        return task ?? this.getTask(res.conversation_id);
     }
 }

package/esm/client.d.ts

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

package/esm/client.js

@@ -1,6 +1,4 @@
-import { Agent } from "./agent.js";
 import { regionBaseURL } from "./region.js";
-import { AgentTask } from "./agent-task.js";
 import { cleanPath } from "./utils.js";
 import { Key } from "./key.js";
 let defaultClient;
@@ -8,7 +6,7 @@ let defaultClient;
  * Creates and returns the _default_ client instance.
  *
  * @throws {Error} if a default client already exists.
- * @see {Client.default}
+ * @see {@link Client.default}
  */
 export function createClient(keyOrOptions) {
     if (defaultClient) {
@@ -27,7 +25,7 @@ export class Client {
      * Returns the _default_ client instance.
      *
      * @throws {Error} if there is no default client.
-     * @see {createClient}
+     * @see {@link createClient}
      */
     static default() {
         if (!defaultClient) {
@@ -50,20 +48,21 @@ export class Client {
     isEmbedKey() {
         return this.key.isEmbed();
     }
-    async createTask({ agent }) {
-        if (agent) {
-            return new AgentTask(typeof agent === "string" ? await Agent.fetch(agent) : agent, undefined, this);
-        }
-        throw new Error("task not implemented");
-    }
     async fetch(input, init) {
-        const url = new URL(cleanPath(input), this.baseURL);
+        const url = this.url(input);
         const headers = new Headers(this.key.fetchHeaders());
         const response = await fetch(url, Object.assign({ headers }, init));
         if (!response.ok) {
-            console.error(url, init, headers);
+            const body = await response.text();
+            console.error(url, init, headers, body);
             throw new Error(response.statusText);
         }
         return response.json();
     }
+    url(path) {
+        if (/^https?:\/\//.test(path)) {
+            return new URL(path);
+        }
+        return new URL(cleanPath(path), this.baseURL);
+    }
 }

package/esm/emitter.d.ts

@@ -0,0 +1,16 @@
+export type EventMap = Record<string, unknown>;
+/**
+ * Emitter
+ *
+ * Abstraction for type-assisting event targets.
+ *
+ * @internal
+ */
+export declare abstract class Emitter<M extends EventMap = Record<string, never>> extends EventTarget {
+    addEventListener<K extends keyof M>(type: Extract<K, string>, listener: ((event: CustomEvent<M[K]>) => void) | {
+        handleEvent: (event: CustomEvent<M[K]>) => void;
+    } | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener<K extends keyof M>(type: Extract<K, string>, listener: ((event: CustomEvent<M[K]>) => void) | {
+        handleEvent: (event: CustomEvent<M[K]>) => void;
+    } | null, options?: boolean | AddEventListenerOptions): void;
+}

package/esm/emitter.js

@@ -0,0 +1,15 @@
+/**
+ * Emitter
+ *
+ * Abstraction for type-assisting event targets.
+ *
+ * @internal
+ */
+export class Emitter extends EventTarget {
+    addEventListener(type, listener, options) {
+        super.addEventListener(type, listener, options);
+    }
+    removeEventListener(type, listener, options) {
+        super.removeEventListener(type, listener, options);
+    }
+}

package/{script/events.d.ts → esm/event.d.ts}

@@ -1,4 +1,7 @@
-import type { TaskMessage } from "./message.js";
+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;
@@ -14,27 +17,21 @@ export declare class TaskStatusEvent extends CustomEvent<{
     constructor(status: TaskStatus);
 }
 export declare class TaskMessageEvent extends CustomEvent<{
-    message: TaskMessage;
+    message: AgentMessage | UserMessage;
 }> {
     readonly type = "message";
-    constructor(message: TaskMessage);
+    constructor(message: AgentMessage | UserMessage);
     isUserMessage(): boolean;
 }
 export declare class TaskUpdateEvent extends CustomEvent<{
-    message: TaskMessage;
+    message: ToolMessage;
 }> {
     readonly type = "update";
-    constructor(message: TaskMessage);
-}
-export declare class TaskActionEvent extends CustomEvent<{
-    message: TaskMessage;
-}> {
-    readonly type = "action";
-    constructor(message: TaskMessage);
+    constructor(message: ToolMessage);
 }
 export declare class TaskErrorEvent extends CustomEvent<{
-    message: TaskMessage;
+    message: AgentErrorMessage;
 }> {
     readonly type = "error";
-    constructor(message: TaskMessage);
+    constructor(message: AgentErrorMessage);
 }

package/esm/{events.js → event.js}

@@ -25,12 +25,6 @@ export class TaskUpdateEvent extends CustomEvent {
         super("update", { detail: { message } });
     }
 }
-export class TaskActionEvent extends CustomEvent {
-    type = "action";
-    constructor(message) {
-        super("action", { detail: { message } });
-    }
-}
 export class TaskErrorEvent extends CustomEvent {
     type = "error";
     constructor(message) {

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

@@ -0,0 +1,6 @@
+import { TaskMessage } from "./task.js";
+export interface AgentErrorMessageContent {
+    type: "agent-error";
+}
+export declare class AgentErrorMessage extends TaskMessage<AgentErrorMessageContent> {
+}

package/esm/message/agent-error.js

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

package/esm/message/agent.d.ts

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

package/esm/message/agent.js

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

package/esm/message/task.d.ts

@@ -0,0 +1,42 @@
+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;
+interface MessageContent {
+    type: AnyTaskMessage["type"];
+}
+export interface TaskMessageData<C extends MessageContent = MessageContent> {
+    item_id: string;
+    insert_date_: string;
+    content: C;
+}
+export declare abstract class TaskMessage<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"}
+     */
+    get type(): C["type"];
+    /**
+     * The task message ID. Used for referencing the message.
+     *
+     * @property {string}
+     */
+    get id(): string;
+    /**
+     * The time the task was created.
+     *
+     * @property {Date}
+     */
+    get createdAt(): Date;
+    /**
+     * Returns if the message was sent from the agent.
+     *
+     * @returns {boolean}
+     */
+    isAgent(): boolean;
+}
+export {};

package/esm/message/task.js

@@ -0,0 +1,38 @@
+export class TaskMessage {
+    message;
+    constructor(message) {
+        this.message = message;
+    }
+    /**
+     * The task's message type.
+     *
+     * @property {"agent-error" | "agent-message" | "tool-run" | "user-message"}
+     */
+    get type() {
+        return this.message.content.type;
+    }
+    /**
+     * The task message ID. Used for referencing the message.
+     *
+     * @property {string}
+     */
+    get id() {
+        return this.message.item_id;
+    }
+    /**
+     * The time the task was created.
+     *
+     * @property {Date}
+     */
+    get createdAt() {
+        return new Date(this.message.insert_date_);
+    }
+    /**
+     * Returns if the message was sent from the agent.
+     *
+     * @returns {boolean}
+     */
+    isAgent() {
+        return this.type === "agent-message";
+    }
+}

package/esm/message/tool.d.ts

@@ -0,0 +1,108 @@
+import type { Region } from "../region.js";
+import { TaskMessage } from "./task.js";
+export interface ToolMessageContent {
+    type: "tool-run";
+    tool_run_state: "cancelled" | "error" | "finished" | "pending" | "running";
+    output: Record<string, unknown> & {
+        _agent_conversation_details?: {
+            agent_id: string;
+            conversation_id: string;
+        };
+    };
+    params: {
+        resolved?: Record<string, unknown>;
+        valid: boolean;
+    };
+    errors: {
+        body: string;
+        raw: string;
+        step_name: string;
+    }[];
+    tool_config: {
+        id: string;
+        type: "tool" | "agent";
+        region: Region;
+        project: string;
+    };
+}
+export declare class ToolMessage extends TaskMessage<ToolMessageContent> {
+    /**
+     * The tool status for _this_ message.
+     *
+     * @property {"cancelled" | "error" | "finished" | "pending" | "running"}
+     */
+    get status(): "cancelled" | "error" | "finished" | "pending" | "running";
+    /**
+     * Parameters used to call the tool.
+     *
+     * @property {object}
+     */
+    get params(): Record<string, unknown> | null;
+    /**
+     * The tool's output. Will be `null` if the status is **not** "finished".
+     *
+     * @property {object|null}
+     */
+    get output(): Record<string, unknown> | null;
+    /**
+     * Tool errors.
+     *
+     * @property {array}
+     * @see {@link ToolMessage#hasErrors}
+     */
+    get errors(): {
+        stepName: string;
+        message: string;
+    }[];
+    /**
+     * The tool's ID.
+     *
+     * @property {string}
+     */
+    get toolId(): string;
+    /**
+     * The agent's ID, if a sub-agent.
+     *
+     * @property {string}
+     * @see {@link ToolMessage.isSubAgent}
+     */
+    get agentId(): string | null;
+    /**
+     * The tool/agent's corresponding project.
+     *
+     * @property {string}
+     */
+    get project(): string;
+    /**
+     * The tool/agent's corresponding region.
+     *
+     * @property {Region}
+     */
+    get region(): Region;
+    /**
+     * The task ID the sub-agent ran. Will be `null` if the tool message is not
+     * a sub-agent.
+     *
+     * @property {string}
+     * @see {@link ToolMessage.isSubAgent}
+     */
+    get subAgentTaskId(): string | null;
+    /**
+     * Checks if the tool message came from a sub-agent.
+     *
+     * @returns {boolean}
+     */
+    isSubAgent(): boolean;
+    /**
+     * Checks if the tool call parameters where valid.
+     *
+     * @returns {boolean}
+     */
+    areParamsValid(): boolean;
+    /**
+     * Returns if the tool message has any errors.
+     *
+     * @returns {boolean}
+     */
+    hasErrors(): boolean;
+}

package/esm/message/tool.js

@@ -0,0 +1,109 @@
+import { TaskMessage } from "./task.js";
+export class ToolMessage extends TaskMessage {
+    /**
+     * The tool status for _this_ message.
+     *
+     * @property {"cancelled" | "error" | "finished" | "pending" | "running"}
+     */
+    get status() {
+        return this.message.content.tool_run_state;
+    }
+    /**
+     * Parameters used to call the tool.
+     *
+     * @property {object}
+     */
+    get params() {
+        return this.message.content.params.resolved ?? null;
+    }
+    /**
+     * The tool's output. Will be `null` if the status is **not** "finished".
+     *
+     * @property {object|null}
+     */
+    get output() {
+        return this.status === "finished" ? this.message.content.output : null;
+    }
+    /**
+     * Tool errors.
+     *
+     * @property {array}
+     * @see {@link ToolMessage#hasErrors}
+     */
+    get errors() {
+        return this.message.content.errors.map((e) => ({
+            stepName: e.step_name,
+            message: e.body,
+        }));
+    }
+    /**
+     * The tool's ID.
+     *
+     * @property {string}
+     */
+    get toolId() {
+        return this.message.content.tool_config.id;
+    }
+    /**
+     * The agent's ID, if a sub-agent.
+     *
+     * @property {string}
+     * @see {@link ToolMessage.isSubAgent}
+     */
+    get agentId() {
+        return this.isSubAgent()
+            ? this.message.content.output._agent_conversation_details?.agent_id
+            : null;
+    }
+    /**
+     * The tool/agent's corresponding project.
+     *
+     * @property {string}
+     */
+    get project() {
+        return this.message.content.tool_config.project;
+    }
+    /**
+     * The tool/agent's corresponding region.
+     *
+     * @property {Region}
+     */
+    get region() {
+        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.
+     *
+     * @property {string}
+     * @see {@link ToolMessage.isSubAgent}
+     */
+    get subAgentTaskId() {
+        return this.message.content.output._agent_conversation_details
+            ?.conversation_id ?? null;
+    }
+    /**
+     * Checks if the tool message came from a sub-agent.
+     *
+     * @returns {boolean}
+     */
+    isSubAgent() {
+        return this.message.content.tool_config.type === "agent";
+    }
+    /**
+     * Checks if the tool call parameters where valid.
+     *
+     * @returns {boolean}
+     */
+    areParamsValid() {
+        return this.message.content.params.valid;
+    }
+    /**
+     * Returns if the tool message has any errors.
+     *
+     * @returns {boolean}
+     */
+    hasErrors() {
+        return this.message.content.errors.length > 0;
+    }
+}

package/esm/message/user.d.ts

@@ -0,0 +1,20 @@
+import { TaskMessage } from "./task.js";
+export interface UserMessageContent {
+    type: "user-message";
+    text: string;
+    is_trigger_message: boolean;
+}
+export declare class UserMessage extends TaskMessage<UserMessageContent> {
+    /**
+     * The message as text sent.
+     *
+     * @property {string} text
+     */
+    get text(): string;
+    /**
+     * Returns if the message triggered a subject.
+     *
+     * @returns {boolean}
+     */
+    isTrigger(): boolean;
+}

package/esm/message/user.js

@@ -0,0 +1,19 @@
+import { TaskMessage } from "./task.js";
+export class UserMessage extends 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;
+    }
+}

package/esm/mod.d.ts

@@ -2,6 +2,9 @@ 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 type { AgentTask } from "./agent-task.js";
-export type { TaskMessage } from "./message.js";
-export type { Task, TaskStatus } from "./task.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";