@arinova-ai/agent-sdk 0.0.13 → 0.0.15-staging.0

package/dist/client.js

@@ -82,6 +82,20 @@ export class ArinovaAgent {
             throw new Error(`sendMessage failed (${res.status}): ${body}`);
         }
     }
+    /**
+     * Send a telemetry event to the server.
+     * Silently no-ops if WebSocket is not connected.
+     */
+    sendTelemetry(event, data) {
+        this.send({ type: "agent_telemetry", event, data });
+    }
+    /**
+     * Send HUD data to the server for display in the office HUD bar.
+     * The server forwards this to the agent owner's frontend.
+     */
+    sendHud(data) {
+        this.send({ type: "hud_update", data });
+    }
     emit(event, ...args) {
         for (const listener of this.listeners[event] ?? []) {
             listener(...args);
@@ -228,6 +242,718 @@ export class ArinovaAgent {
         }
         return res.json();
     }
+    /**
+     * Fetch conversation history via the agent messages endpoint.
+     * @param conversationId - The conversation to fetch messages from.
+     * @param options - Pagination options (before, after, around, limit).
+     */
+    async fetchHistory(conversationId, options) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const params = new URLSearchParams();
+        if (options?.before)
+            params.set("before", options.before);
+        if (options?.after)
+            params.set("after", options.after);
+        if (options?.around)
+            params.set("around", options.around);
+        if (options?.limit != null)
+            params.set("limit", String(options.limit));
+        const qs = params.toString();
+        const url = `${httpUrl}/api/agent/messages/${conversationId}${qs ? `?${qs}` : ""}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+            },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`fetchHistory failed (${res.status}): ${body}`);
+        }
+        return res.json();
+    }
+    /**
+     * List notes in a conversation.
+     * @param conversationId - The conversation to list notes from.
+     * @param options - Pagination options (before, limit).
+     */
+    async listNotes(conversationId, options) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const params = new URLSearchParams();
+        if (options?.before)
+            params.set("before", options.before);
+        if (options?.limit != null)
+            params.set("limit", String(options.limit));
+        if (options?.tags?.length)
+            params.set("tags", options.tags.join(","));
+        if (options?.archived)
+            params.set("archived", "true");
+        const qs = params.toString();
+        const url = `${httpUrl}/api/agent/conversations/${conversationId}/notes${qs ? `?${qs}` : ""}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`listNotes failed (${res.status}): ${body}`);
+        }
+        return res.json();
+    }
+    /**
+     * Create a note in a conversation.
+     * @param conversationId - The conversation to create the note in.
+     * @param body - Note title and optional content.
+     */
+    async createNote(conversationId, body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/conversations/${conversationId}/notes`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`createNote failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Update a note in a conversation.
+     * @param conversationId - The conversation the note belongs to.
+     * @param noteId - The note ID to update.
+     * @param body - Fields to update (title and/or content).
+     */
+    async updateNote(conversationId, noteId, body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/conversations/${conversationId}/notes/${noteId}`, {
+            method: "PATCH",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`updateNote failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Delete a note from a conversation.
+     * @param conversationId - The conversation the note belongs to.
+     * @param noteId - The note ID to delete.
+     */
+    async deleteNote(conversationId, noteId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/conversations/${conversationId}/notes/${noteId}`, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`deleteNote failed (${res.status}): ${text}`);
+        }
+    }
+    // ── Kanban API ────────────────────────────────────────────────
+    /**
+     * List the owner's kanban boards.
+     * Returns an array of boards with id, name, and createdAt.
+     */
+    async listBoards() {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/boards`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`listBoards failed (${res.status}): ${body}`);
+        }
+        return res.json();
+    }
+    /**
+     * Create a kanban card on the owner's board.
+     * The card is automatically assigned to the calling agent.
+     * @param body - Card title and optional description, priority, column.
+     */
+    async createCard(body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`createCard failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Update a kanban card.
+     * @param cardId - The card ID to update.
+     * @param body - Fields to update (title, description, priority, columnId, sortOrder).
+     */
+    async updateCard(cardId, body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards/${cardId}`, {
+            method: "PATCH",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`updateCard failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Create a new kanban board.
+     * @param body - Board name and optional initial columns.
+     */
+    async createBoard(body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/boards`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`createBoard failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Update a kanban board.
+     * @param boardId - The board ID to update.
+     * @param body - Fields to update.
+     */
+    async updateBoard(boardId, body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/boards/${boardId}`, {
+            method: "PATCH",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`updateBoard failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Archive a kanban board.
+     * @param boardId - The board ID to archive.
+     */
+    async archiveBoard(boardId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/boards/${boardId}/archive`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`archiveBoard failed (${res.status}): ${text}`);
+        }
+    }
+    /**
+     * List columns for a board.
+     * @param boardId - The board ID.
+     */
+    async listColumns(boardId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/boards/${boardId}/columns`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`listColumns failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Create a column in a board.
+     * @param boardId - The board ID.
+     * @param body - Column name and optional sort order.
+     */
+    async createColumn(boardId, body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/boards/${boardId}/columns`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`createColumn failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Update a column.
+     * @param columnId - The column ID to update.
+     * @param body - Fields to update (name, sortOrder).
+     */
+    async updateColumn(columnId, body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/columns/${columnId}`, {
+            method: "PATCH",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`updateColumn failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Delete a column.
+     * @param columnId - The column ID to delete.
+     */
+    async deleteColumn(columnId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/columns/${columnId}`, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`deleteColumn failed (${res.status}): ${text}`);
+        }
+    }
+    /**
+     * Reorder columns in a board.
+     * @param boardId - The board ID.
+     * @param columnIds - Ordered array of column IDs.
+     */
+    async reorderColumns(boardId, columnIds) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/boards/${boardId}/columns/reorder`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ columnIds }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`reorderColumns failed (${res.status}): ${text}`);
+        }
+    }
+    /**
+     * List all kanban cards for the agent's owner.
+     */
+    async listCards() {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`listCards failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Mark a card as complete (moves it to the Done column).
+     * @param cardId - The card ID to complete.
+     */
+    async completeCard(cardId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards/${cardId}/complete`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`completeCard failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * List archived cards for a board.
+     * @param boardId - The board ID.
+     * @param options - Pagination options (page, limit).
+     */
+    async listArchivedCards(boardId, options) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const params = new URLSearchParams();
+        if (options?.page != null)
+            params.set("page", String(options.page));
+        if (options?.limit != null)
+            params.set("limit", String(options.limit));
+        const qs = params.toString();
+        const url = `${httpUrl}/api/agent/kanban/boards/${boardId}/archived-cards${qs ? `?${qs}` : ""}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`listArchivedCards failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Add a commit link to a card.
+     * @param cardId - The card ID.
+     * @param body - Commit hash and optional message.
+     */
+    async addCardCommit(cardId, body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards/${cardId}/commits`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`addCardCommit failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * List commits linked to a card.
+     * @param cardId - The card ID.
+     */
+    async listCardCommits(cardId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards/${cardId}/commits`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`listCardCommits failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Link a note to a card.
+     * @param cardId - The card ID.
+     * @param noteId - The note ID to link.
+     */
+    async linkCardNote(cardId, noteId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards/${cardId}/notes`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ noteId }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`linkCardNote failed (${res.status}): ${text}`);
+        }
+    }
+    /**
+     * Unlink a note from a card.
+     * @param cardId - The card ID.
+     * @param noteId - The note ID to unlink.
+     */
+    async unlinkCardNote(cardId, noteId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards/${cardId}/notes/${noteId}`, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`unlinkCardNote failed (${res.status}): ${text}`);
+        }
+    }
+    /**
+     * List notes linked to a card.
+     * @param cardId - The card ID.
+     */
+    async listCardNotes(cardId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards/${cardId}/notes`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`listCardNotes failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    // ── Label API ────────────────────────────────────────────────
+    /**
+     * List labels for a board.
+     * @param boardId - The board ID.
+     */
+    async listLabels(boardId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/boards/${boardId}/labels`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`listLabels failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Create a label on a board.
+     * @param boardId - The board ID.
+     * @param body - Label name and optional color.
+     */
+    async createLabel(boardId, body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/boards/${boardId}/labels`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`createLabel failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Update a label.
+     * @param labelId - The label ID to update.
+     * @param body - Fields to update (name, color).
+     */
+    async updateLabel(labelId, body) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/labels/${labelId}`, {
+            method: "PATCH",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`updateLabel failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    /**
+     * Delete a label.
+     * @param labelId - The label ID to delete.
+     */
+    async deleteLabel(labelId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/labels/${labelId}`, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`deleteLabel failed (${res.status}): ${text}`);
+        }
+    }
+    /**
+     * Add a label to a card.
+     * @param cardId - The card ID.
+     * @param labelId - The label ID to add.
+     */
+    async addCardLabel(cardId, labelId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards/${cardId}/labels`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.botToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ labelId }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`addCardLabel failed (${res.status}): ${text}`);
+        }
+    }
+    /**
+     * Remove a label from a card.
+     * @param cardId - The card ID.
+     * @param labelId - The label ID to remove.
+     */
+    async removeCardLabel(cardId, labelId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/kanban/cards/${cardId}/labels/${labelId}`, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`removeCardLabel failed (${res.status}): ${text}`);
+        }
+    }
+    // ── Memory API ───────────────────────────────────────────────
+    /**
+     * Search memories across all memory capsules granted to this agent.
+     * Uses hybrid search (embedding + text) to find relevant memories.
+     * @param options - Query string and optional limit.
+     */
+    async queryMemory(options) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const params = new URLSearchParams();
+        params.set("query", options.query);
+        if (options.limit != null)
+            params.set("limit", String(options.limit));
+        const res = await fetch(`${httpUrl}/api/agent/capsules?${params}`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`queryMemory failed (${res.status}): ${body}`);
+        }
+        // Server returns snake_case, map to camelCase
+        const raw = (await res.json());
+        return raw.map((r) => ({
+            content: r.content,
+            capsuleName: r.capsule_name,
+            capsuleId: r.capsule_id,
+            score: r.score,
+            importance: r.importance,
+        }));
+    }
+    // ── Skill Prompt API ─────────────────────────────────────────
+    /**
+     * Fetch the full prompt content for an installed skill by slug.
+     * Use this when the agent decides to trigger a skill from availableSkills.
+     * @param skillSlug - The skill slug (e.g. "draw", "proactive-agent").
+     */
+    async fetchSkillPrompt(skillSlug) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/skills/${encodeURIComponent(skillSlug)}/prompt`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`fetchSkillPrompt failed (${res.status}): ${body}`);
+        }
+        return (await res.json());
+    }
+    // ── Note Share API ───────────────────────────────────────────
+    /**
+     * Share a note as a message in a conversation.
+     * Creates a rich preview card visible to all conversation members.
+     * @param conversationId - The conversation to share into.
+     * @param noteId - The note ID to share.
+     */
+    async shareNote(conversationId, noteId) {
+        const httpUrl = this.serverUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:");
+        const res = await fetch(`${httpUrl}/api/agent/conversations/${conversationId}/notes/${noteId}/share`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.botToken}` },
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`shareNote failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
     handleTask(data) {
         if (!this.taskHandler)
             return;
@@ -239,6 +965,18 @@ export class ArinovaAgent {
             this.send({ type: "agent_heartbeat", taskId });
         }, TASK_HEARTBEAT_INTERVAL);
         const stopHeartbeat = () => clearInterval(heartbeatTimer);
+        // Guard: ensure sendComplete/sendError only fires once per task.
+        // After cancel_task, the background handler may still call sendComplete
+        // when the LLM finishes — the guard prevents duplicate events.
+        let taskFinished = false;
+        const markFinished = () => {
+            if (taskFinished)
+                return false;
+            taskFinished = true;
+            stopHeartbeat();
+            this.taskAbortControllers.delete(taskId);
+            return true;
+        };
         const ctx = {
             taskId,
             conversationId: data.conversationId,
@@ -250,10 +988,14 @@ export class ArinovaAgent {
             replyTo: data.replyTo,
             history: data.history,
             attachments: data.attachments,
-            sendChunk: (delta) => this.send({ type: "agent_chunk", taskId, chunk: delta }),
+            sendChunk: (delta) => {
+                if (taskFinished)
+                    return;
+                this.send({ type: "agent_chunk", taskId, chunk: delta });
+            },
             sendComplete: (fullContent, options) => {
-                stopHeartbeat();
-                this.taskAbortControllers.delete(taskId);
+                if (!markFinished())
+                    return;
                 this.send({
                     type: "agent_complete",
                     taskId,
@@ -262,15 +1004,21 @@ export class ArinovaAgent {
                 });
             },
             sendError: (error) => {
-                stopHeartbeat();
-                this.taskAbortControllers.delete(taskId);
+                if (!markFinished())
+                    return;
                 this.send({ type: "agent_error", taskId, error });
             },
             signal: abortController.signal,
             uploadFile: (file, fileName, fileType) => this.uploadFile(data.conversationId, file, fileName, fileType),
+            fetchHistory: (options) => this.fetchHistory(data.conversationId, options),
         };
-        // Stop heartbeat if task is aborted (user cancelled)
-        abortController.signal.addEventListener("abort", stopHeartbeat, { once: true });
+        // When task is aborted (user cancelled), immediately send cancellation
+        // error so the server knows this agent is free for new tasks.
+        abortController.signal.addEventListener("abort", () => {
+            if (!markFinished())
+                return;
+            this.send({ type: "agent_error", taskId, error: "cancelled" });
+        }, { once: true });
         Promise.resolve(this.taskHandler(ctx)).catch((err) => {
             const errorMsg = err instanceof Error ? err.message : String(err);
             ctx.sendError(errorMsg);