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

package/dist/client.js

@@ -9,8 +9,10 @@ export class ArinovaAgent {
     pingInterval;
     ws = null;
     pingTimer = null;
+    commandHeartbeatTimer = null;
     reconnectTimer = null;
     stopped = false;
+    agentId = null;
     taskHandler = null;
     taskAbortControllers = new Map();
     listeners = {
@@ -69,7 +71,7 @@ export class ArinovaAgent {
         const httpUrl = this.serverUrl
             .replace(/^ws:/, "http:")
             .replace(/^wss:/, "https:");
-        const res = await fetch(`${httpUrl}/api/agent/send`, {
+        const res = await fetch(`${httpUrl}/api/v1/messages/send`, {
             method: "POST",
             headers: {
                 "Authorization": `Bearer ${this.botToken}`,
@@ -82,6 +84,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);
@@ -97,6 +113,10 @@ export class ArinovaAgent {
             clearInterval(this.pingTimer);
             this.pingTimer = null;
         }
+        if (this.commandHeartbeatTimer) {
+            clearInterval(this.commandHeartbeatTimer);
+            this.commandHeartbeatTimer = null;
+        }
         if (this.reconnectTimer) {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
@@ -145,7 +165,27 @@ export class ArinovaAgent {
             try {
                 const data = JSON.parse(String(event.data));
                 if (data.type === "auth_ok") {
+                    this.agentId = data.agentId ?? null;
                     this.emit("connected");
+                    // Register SDK runtime commands from skills
+                    if (this.skills.length > 0 && this.agentId) {
+                        this.send({
+                            type: "register_commands",
+                            agentId: this.agentId,
+                            commands: this.skills.map((s) => ({
+                                name: s.id ?? s.name,
+                                description: s.description ?? "",
+                            })),
+                        });
+                    }
+                    // Start heartbeat to extend Redis TTL every 60s
+                    if (this.commandHeartbeatTimer)
+                        clearInterval(this.commandHeartbeatTimer);
+                    if (this.skills.length > 0 && this.agentId) {
+                        this.commandHeartbeatTimer = setInterval(() => {
+                            this.send({ type: "heartbeat_commands", agentId: this.agentId });
+                        }, 60_000);
+                    }
                     // Resolve the connect() promise on first successful auth
                     if (this.connectResolve) {
                         this.connectResolve();
@@ -215,7 +255,7 @@ export class ArinovaAgent {
         formData.append("conversationId", conversationId);
         const blob = new Blob([new Uint8Array(file)], { type: mime });
         formData.append("file", blob, fileName);
-        const res = await fetch(`${httpUrl}/api/agent/upload`, {
+        const res = await fetch(`${httpUrl}/api/v1/files/upload`, {
             method: "POST",
             headers: {
                 Authorization: `Bearer ${this.botToken}`,
@@ -247,7 +287,7 @@ export class ArinovaAgent {
         if (options?.limit != null)
             params.set("limit", String(options.limit));
         const qs = params.toString();
-        const url = `${httpUrl}/api/agent/messages/${conversationId}${qs ? `?${qs}` : ""}`;
+        const url = `${httpUrl}/api/v1/messages/${conversationId}${qs ? `?${qs}` : ""}`;
         const res = await fetch(url, {
             method: "GET",
             headers: {
@@ -274,8 +314,12 @@ export class ArinovaAgent {
             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 url = `${httpUrl}/api/v1/notes${qs ? `?${qs}` : ""}`;
         const res = await fetch(url, {
             method: "GET",
             headers: { Authorization: `Bearer ${this.botToken}` },
@@ -295,7 +339,7 @@ export class ArinovaAgent {
         const httpUrl = this.serverUrl
             .replace(/^ws:/, "http:")
             .replace(/^wss:/, "https:");
-        const res = await fetch(`${httpUrl}/api/agent/conversations/${conversationId}/notes`, {
+        const res = await fetch(`${httpUrl}/api/v1/notes`, {
             method: "POST",
             headers: {
                 Authorization: `Bearer ${this.botToken}`,
@@ -319,7 +363,7 @@ export class ArinovaAgent {
         const httpUrl = this.serverUrl
             .replace(/^ws:/, "http:")
             .replace(/^wss:/, "https:");
-        const res = await fetch(`${httpUrl}/api/agent/conversations/${conversationId}/notes/${noteId}`, {
+        const res = await fetch(`${httpUrl}/api/v1/notes/${noteId}`, {
             method: "PATCH",
             headers: {
                 Authorization: `Bearer ${this.botToken}`,
@@ -342,7 +386,7 @@ export class ArinovaAgent {
         const httpUrl = this.serverUrl
             .replace(/^ws:/, "http:")
             .replace(/^wss:/, "https:");
-        const res = await fetch(`${httpUrl}/api/agent/conversations/${conversationId}/notes/${noteId}`, {
+        const res = await fetch(`${httpUrl}/api/v1/notes/${noteId}`, {
             method: "DELETE",
             headers: { Authorization: `Bearer ${this.botToken}` },
         });
@@ -351,6 +395,591 @@ export class ArinovaAgent {
             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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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;