letagents 0.12.8 → 0.12.10

package/dist/mcp/server/tools/messages/reasoning-tool.js

@@ -0,0 +1,179 @@
+import { z } from "zod";
+import { AGENT_PRESENCE_STATUSES } from "../../../../shared/agent-presence.js";
+import { encodeRoomIdPath } from "../../../room-id.js";
+import { addLocalChatMessage, agentSessionCredentials, currentRoom, getFallbackProjectId, getRememberedRoomPresence, getTargetRoomId, isLocalRoomStorageEnabled, normalizeOptionalToolString, resolveLocalRoomStorageIdentifiers, resolveWorkerToolIdentity, roomScopedApiCall, syncRoomPresence, toPublicAgentIdentity, touchCurrentRoom, } from "../../runtime.js";
+import { jsonToolResponse, missingRoomResponse } from "./response.js";
+export function registerPostReasoningTool(server) {
+    server.tool("post_reasoning", "Update a structured, replace-in-place reasoning trace for the current room without spamming chat. " +
+        "Use this for visible thought-process updates such as goal, hypothesis, checks in progress, blockers, " +
+        "and next action. Optionally persist a milestone summary into room history when something durable changed.", {
+        summary: z.string().describe("Short current reasoning summary shown in the room UI."),
+        goal: z.string().optional().describe("What the agent is trying to achieve right now."),
+        checking: z.string().optional().describe("What the agent is verifying or inspecting."),
+        hypothesis: z.string().optional().describe("Current working theory or approach."),
+        blocker: z.string().optional().describe("Current blocker, if any."),
+        next_action: z.string().optional().describe("Immediate next step the agent plans to take."),
+        milestone: z.string().optional().describe("Optional durable milestone summary to append to room history."),
+        confidence: z.number().min(0).max(1).optional().describe("Optional confidence score between 0 and 1."),
+        status: z.enum(AGENT_PRESENCE_STATUSES).optional().describe("Optional explicit presence state override."),
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to the current room."),
+        conversation_id: z
+            .string()
+            .optional()
+            .describe("Deprecated for worker writes; registered worker session identity is used."),
+        agent_session_id: z
+            .string()
+            .optional()
+            .describe("Registered agent session to use for this reasoning update. Required for worker reasoning."),
+    }, async ({ summary, goal, checking, hypothesis, blocker, next_action, milestone, confidence, status, room_id, conversation_id: _conversation_id, agent_session_id, }) => {
+        const targetRoomId = getTargetRoomId(room_id);
+        const targetProjectId = getFallbackProjectId();
+        if (!targetRoomId && !targetProjectId) {
+            return missingRoomResponse();
+        }
+        const normalizedSummary = summary.trim();
+        if (!normalizedSummary) {
+            return jsonToolResponse({ success: false, error: "summary is required" });
+        }
+        const { identity, agentSession } = await resolveWorkerToolIdentity({
+            roomId: targetRoomId ?? currentRoom?.room_id ?? null,
+            agentSessionId: agent_session_id,
+        });
+        const snapshot = {
+            summary: normalizedSummary,
+            goal: normalizeOptionalToolString(goal),
+            checking: normalizeOptionalToolString(checking),
+            hypothesis: normalizeOptionalToolString(hypothesis),
+            blocker: normalizeOptionalToolString(blocker),
+            next_action: normalizeOptionalToolString(next_action),
+            milestone: normalizeOptionalToolString(milestone),
+            confidence,
+            status,
+        };
+        const localRoomId = targetRoomId ?? currentRoom?.room_id ?? targetProjectId;
+        if (localRoomId && await isLocalRoomStorageEnabled(localRoomId)) {
+            const { localRoomId: sqliteRoomId } = await resolveLocalRoomStorageIdentifiers(localRoomId);
+            const effectiveLocalRoomId = sqliteRoomId || localRoomId;
+            let milestoneMessageId = null;
+            const normalizedMilestone = normalizeOptionalToolString(milestone);
+            if (normalizedMilestone) {
+                const milestoneMessage = await addLocalChatMessage(effectiveLocalRoomId, {
+                    sender: identity.actor_label,
+                    text: normalizedMilestone,
+                    source: "agent",
+                });
+                milestoneMessageId = milestoneMessage.id;
+                touchCurrentRoom(milestoneMessageId);
+            }
+            await syncRoomPresence(effectiveLocalRoomId, identity, {
+                status: status ?? getRememberedRoomPresence(effectiveLocalRoomId, identity).status,
+                status_text: normalizedSummary,
+            }, agentSession);
+            const now = new Date().toISOString();
+            return jsonToolResponse({
+                success: true,
+                room_id: effectiveLocalRoomId,
+                local: true,
+                session: {
+                    id: `local_reasoning:${identity.actor_label}`,
+                    actor_label: identity.actor_label,
+                    agent_key: identity.canonical_key,
+                    status: status ?? "working",
+                    summary: normalizedSummary,
+                    latest_payload: snapshot,
+                    updated_at: now,
+                },
+                update: {
+                    id: `local_reasoning_update:${now}`,
+                    payload: snapshot,
+                    created_at: now,
+                },
+                milestone_message_id: milestoneMessageId,
+                agent_identity: toPublicAgentIdentity(identity),
+            });
+        }
+        const query = new URLSearchParams({
+            open: "true",
+            actor_label: identity.actor_label,
+        });
+        const sessionsResult = await roomScopedApiCall({
+            room_id: targetRoomId,
+            project_id: targetProjectId,
+            room_path: (targetRoomId) => `/rooms/${encodeRoomIdPath(targetRoomId)}/reasoning-sessions?${query.toString()}`,
+            project_path: (targetProjectId) => `/projects/${encodeURIComponent(targetProjectId)}/reasoning-sessions?${query.toString()}`,
+        });
+        const existingSession = sessionsResult.sessions?.[0];
+        let result = null;
+        if (existingSession?.id) {
+            result = await roomScopedApiCall({
+                room_id: targetRoomId,
+                project_id: targetProjectId,
+                room_path: (targetRoomId) => `/rooms/${encodeRoomIdPath(targetRoomId)}/reasoning-sessions/${encodeURIComponent(existingSession.id)}/updates`,
+                project_path: (targetProjectId) => `/projects/${encodeURIComponent(targetProjectId)}/reasoning-sessions/${encodeURIComponent(existingSession.id)}/updates`,
+                options: {
+                    method: "POST",
+                    body: JSON.stringify({
+                        actor_label: identity.actor_label,
+                        ...agentSessionCredentials(agentSession),
+                        ...snapshot,
+                    }),
+                },
+            });
+        }
+        else {
+            result = await roomScopedApiCall({
+                room_id: targetRoomId,
+                project_id: targetProjectId,
+                room_path: (targetRoomId) => `/rooms/${encodeRoomIdPath(targetRoomId)}/reasoning-sessions`,
+                project_path: (targetProjectId) => `/projects/${encodeURIComponent(targetProjectId)}/reasoning-sessions`,
+                options: {
+                    method: "POST",
+                    body: JSON.stringify({
+                        actor_label: identity.actor_label,
+                        agent_key: identity.canonical_key,
+                        ...agentSessionCredentials(agentSession),
+                        ...snapshot,
+                    }),
+                },
+            });
+        }
+        let milestoneMessageId = null;
+        const normalizedMilestone = normalizeOptionalToolString(milestone);
+        if (normalizedMilestone) {
+            const milestoneMessage = await roomScopedApiCall({
+                room_id: targetRoomId,
+                project_id: targetProjectId,
+                room_path: (targetRoomId) => `/rooms/${encodeRoomIdPath(targetRoomId)}/messages`,
+                project_path: (targetProjectId) => `/projects/${encodeURIComponent(targetProjectId)}/messages`,
+                options: {
+                    method: "POST",
+                    body: JSON.stringify({
+                        sender: identity.actor_label,
+                        text: normalizedMilestone,
+                        ...agentSessionCredentials(agentSession),
+                    }),
+                },
+            });
+            milestoneMessageId =
+                typeof milestoneMessage.id === "string" ? milestoneMessage.id : null;
+            touchCurrentRoom(milestoneMessageId ?? undefined);
+        }
+        if (status) {
+            await syncRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity, {
+                status,
+                status_text: normalizedSummary,
+            }, agentSession);
+        }
+        else {
+            await syncRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity, getRememberedRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity), agentSession);
+        }
+        return jsonToolResponse({
+            success: true,
+            room_id: result?.room_id ?? targetRoomId ?? targetProjectId ?? null,
+            session: result?.session ?? null,
+            update: result?.update ?? null,
+            milestone_message_id: milestoneMessageId,
+            agent_identity: toPublicAgentIdentity(identity),
+        });
+    });
+}

package/dist/mcp/server/tools/messages/response.js

@@ -0,0 +1,17 @@
+export function jsonToolResponse(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+export function missingRoomResponse() {
+    return jsonToolResponse({
+        success: false,
+        error: "No room_id provided and not currently in a room.",
+        hint: "Join or create a room first, or pass room_id explicitly.",
+    });
+}

package/dist/mcp/server/tools/messages/send-tool.js

@@ -0,0 +1,203 @@
+import { z } from "zod";
+import { encodeRoomIdPath } from "../../../room-id.js";
+import { agentSessionCredentials, addLocalChatMessage, appendIncludePromptOnly, currentRoom, getFallbackProjectId, getLocalChatMessages, getRememberedRoomPresence, getTargetRoomId, isLocalRoomStorageEnabled, resolveLocalRoomStorageIdentifiers, resolveWorkerToolIdentity, roomScopedApiCall, syncRoomPresence, toPublicAgentIdentity, touchCurrentRoom, } from "../../runtime.js";
+import { jsonToolResponse } from "./response.js";
+export function buildSendMessageRequestBody(input) {
+    return {
+        sender: input.sender,
+        text: input.text,
+        reply_to: input.replyTarget,
+        ...(input.resolvedThreadRoot ? { thread_root_id: input.resolvedThreadRoot } : {}),
+        ...input.credentials,
+    };
+}
+function normalizeMessageId(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function explicitThreadRootId(message) {
+    const root = message?.thread_root_id ?? message?.threadRootId;
+    if (typeof root === "string" && root.trim()) {
+        return root;
+    }
+    return null;
+}
+async function findLocalMessageById(roomId, messageId) {
+    let afterCursor;
+    for (;;) {
+        const result = await getLocalChatMessages(roomId, {
+            after: afterCursor,
+            include_prompt_only: true,
+        });
+        const messages = (result.messages ?? []);
+        const match = messages.find((message) => message.id === messageId);
+        if (match)
+            return match;
+        if (!result.has_more || messages.length === 0)
+            return null;
+        const lastMessage = messages[messages.length - 1];
+        afterCursor = typeof lastMessage?.id === "string" ? lastMessage.id : undefined;
+        if (!afterCursor)
+            return null;
+    }
+}
+async function findRemoteMessageById(input) {
+    let afterCursor;
+    for (;;) {
+        const query = new URLSearchParams();
+        if (afterCursor)
+            query.set("after", afterCursor);
+        const qs = query.toString();
+        const result = await roomScopedApiCall({
+            room_id: input.roomId,
+            project_id: input.projectId,
+            room_path: (roomId) => appendIncludePromptOnly(`/rooms/${encodeRoomIdPath(roomId)}/messages${qs ? `?${qs}` : ""}`),
+            project_path: (projectId) => appendIncludePromptOnly(`/projects/${encodeURIComponent(projectId)}/messages${qs ? `?${qs}` : ""}`),
+        });
+        const messages = result.messages ?? [];
+        const match = messages.find((message) => message.id === input.messageId);
+        if (match)
+            return match;
+        if (!result.has_more || messages.length === 0)
+            return null;
+        const lastMessage = messages[messages.length - 1];
+        afterCursor = typeof lastMessage?.id === "string" ? lastMessage.id : undefined;
+        if (!afterCursor)
+            return null;
+    }
+}
+async function findMessageById(input) {
+    if (input.localRoomId && await isLocalRoomStorageEnabled(input.localRoomId)) {
+        const { localRoomId } = await resolveLocalRoomStorageIdentifiers(input.localRoomId);
+        return findLocalMessageById(localRoomId || input.localRoomId, input.messageId);
+    }
+    return findRemoteMessageById({
+        roomId: input.roomId,
+        projectId: input.projectId,
+        messageId: input.messageId,
+    });
+}
+// Resolve the thread root for a send_thread_message target by reading the target's
+// explicit thread_root_id (the authoritative root the message mappers already
+// populate) instead of walking reply_to. This roots a reply AT a top-level
+// quote-reply X (X.thread_root_id === X.id) rather than under the message X quoted.
+// When the target carries no explicit root (not found / hidden / out-of-band), treat
+// it as its own root — matching the prior lenient behavior, so the create-side
+// existence checks fail the same way rather than newly rejecting a valid reply.
+async function resolveThreadRootMessageId(input) {
+    const message = await findMessageById(input);
+    return explicitThreadRootId(message) ?? input.messageId;
+}
+function initialReplyTarget(input) {
+    const replyTo = normalizeMessageId(input.reply_to);
+    const threadParentId = normalizeMessageId(input.thread_parent_id);
+    if (replyTo && threadParentId && replyTo !== threadParentId) {
+        throw new Error("reply_to and thread_parent_id must match when both are provided.");
+    }
+    return {
+        replyTarget: threadParentId || replyTo,
+        shouldResolveThreadRoot: Boolean(threadParentId),
+    };
+}
+async function sendMessageFromTool(input) {
+    const targetRoomId = getTargetRoomId(input.room_id);
+    const targetProjectId = getFallbackProjectId();
+    if (!targetRoomId && !targetProjectId) {
+        throw new Error("No room is currently selected. Join a room first or pass room_id.");
+    }
+    const { identity, agentSession } = await resolveWorkerToolIdentity({
+        roomId: targetRoomId ?? currentRoom?.room_id ?? null,
+        agentSessionId: input.agent_session_id,
+    });
+    const localRoomId = targetRoomId ?? currentRoom?.room_id ?? targetProjectId;
+    const { replyTarget, shouldResolveThreadRoot } = initialReplyTarget(input);
+    // The quote/chip reference stays the literal target the caller pointed at; the
+    // thread root is resolved separately from that target's explicit thread_root_id,
+    // so a reply to a top-level quote-reply roots at it rather than under what it quoted.
+    const resolvedThreadRoot = replyTarget && shouldResolveThreadRoot
+        ? await resolveThreadRootMessageId({
+            localRoomId,
+            roomId: targetRoomId,
+            projectId: targetProjectId,
+            messageId: replyTarget,
+        })
+        : undefined;
+    if (localRoomId && await isLocalRoomStorageEnabled(localRoomId)) {
+        const { localRoomId: sqliteRoomId } = await resolveLocalRoomStorageIdentifiers(localRoomId);
+        const message = await addLocalChatMessage(sqliteRoomId || localRoomId, {
+            sender: identity.actor_label,
+            text: input.text,
+            reply_to: replyTarget,
+            ...(resolvedThreadRoot ? { thread_root_id: resolvedThreadRoot } : {}),
+            source: "agent",
+        });
+        touchCurrentRoom(message.id);
+        return jsonToolResponse({
+            ...message,
+            agent_identity: toPublicAgentIdentity(identity),
+        });
+    }
+    const message = await roomScopedApiCall({
+        room_id: targetRoomId,
+        project_id: targetProjectId,
+        room_path: (targetRoomId) => `/rooms/${encodeRoomIdPath(targetRoomId)}/messages`,
+        project_path: (targetProjectId) => `/projects/${encodeURIComponent(targetProjectId)}/messages`,
+        options: {
+            method: "POST",
+            body: JSON.stringify(buildSendMessageRequestBody({
+                sender: identity.actor_label,
+                text: input.text,
+                replyTarget,
+                resolvedThreadRoot,
+                credentials: agentSessionCredentials(agentSession),
+            })),
+        },
+    });
+    touchCurrentRoom(typeof message.id === "string" ? message.id : undefined);
+    await syncRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity, getRememberedRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity), agentSession);
+    return jsonToolResponse({
+        ...message,
+        agent_identity: toPublicAgentIdentity(identity),
+    });
+}
+export function registerSendMessageTool(server) {
+    server.tool("send_message", "Send a message to a Let Agents Chat room. For focused side discussion, prefer send_thread_message or pass thread_parent_id so the reply stays in that message thread instead of polluting the main room.", {
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to the current room."),
+        sender: z
+            .string()
+            .optional()
+            .describe("Deprecated override. Agent identity is resolved automatically on room entry."),
+        text: z.string().describe("The message text to send"),
+        reply_to: z
+            .string()
+            .optional()
+            .describe("Optional legacy quote-reply message id. For thread continuation, prefer thread_parent_id or send_thread_message."),
+        thread_parent_id: z
+            .string()
+            .optional()
+            .describe("Optional thread parent/root message id. If this points at a reply inside a thread, the tool resolves it to the root where possible."),
+        conversation_id: z
+            .string()
+            .optional()
+            .describe("Deprecated for worker writes; registered worker session identity is used."),
+        agent_session_id: z
+            .string()
+            .optional()
+            .describe("Registered agent session to use for this message. Required for worker messages."),
+    }, async ({ room_id, sender: _sender, text, reply_to, thread_parent_id, conversation_id: _conversation_id, agent_session_id }) => sendMessageFromTool({ room_id, text, reply_to, thread_parent_id, agent_session_id }));
+    server.tool("send_thread_message", "Reply inside an existing message thread without posting a top-level room message. Use this when discussion should drill into one topic and keep the main room clean.", {
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to the current room."),
+        text: z.string().describe("The thread reply text to send."),
+        thread_parent_id: z
+            .string()
+            .describe("Thread parent/root message id. You may pass any message id from the thread; the tool resolves replies to the root where possible."),
+        conversation_id: z
+            .string()
+            .optional()
+            .describe("Deprecated for worker writes; registered worker session identity is used."),
+        agent_session_id: z
+            .string()
+            .optional()
+            .describe("Registered agent session to use for this thread reply. Required for worker messages."),
+    }, async ({ room_id, text, thread_parent_id, conversation_id: _conversation_id, agent_session_id }) => sendMessageFromTool({ room_id, text, thread_parent_id, agent_session_id }));
+}

package/dist/mcp/server/tools/messages/status-tool.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { classifyPresenceStatusText } from "../../../agent-presence.js";
+import { encodeRoomIdPath } from "../../../room-id.js";
+import { agentSessionCredentials, addLocalChatMessage, currentRoom, getFallbackProjectId, getRememberedRoomPresence, getTargetRoomId, isLocalRoomStorageEnabled, resolveLocalRoomStorageIdentifiers, resolveWorkerToolIdentity, roomScopedApiCall, syncRoomPresence, toPublicAgentIdentity, touchCurrentRoom, } from "../../runtime.js";
+import { missingRoomResponse, jsonToolResponse } from "./response.js";
+export function registerPostStatusTool(server) {
+    server.tool("post_status", "Broadcast a lightweight status update to the current room. " +
+        "Use this to let other agents and humans know what you are currently doing, " +
+        "e.g. 'reviewing PR #2', 'waiting for tests', 'writing WISHLIST.md'. " +
+        "Status updates are distinct from chat messages and can be filtered separately.", {
+        sender: z
+            .string()
+            .optional()
+            .describe("Deprecated override. Agent identity is resolved automatically on room entry."),
+        status: z.string().describe("Short status description (e.g. 'reviewing PR #2', 'idle', 'thinking...')"),
+        room_id: z
+            .string()
+            .optional()
+            .describe("Canonical room ID. Defaults to the current room."),
+        conversation_id: z
+            .string()
+            .optional()
+            .describe("Deprecated for worker writes; registered worker session identity is used."),
+        agent_session_id: z
+            .string()
+            .optional()
+            .describe("Registered agent session to use for this status update. Required for worker status."),
+    }, async ({ sender: _sender, status, room_id, conversation_id: _conversation_id, agent_session_id }) => {
+        const targetRoomId = getTargetRoomId(room_id);
+        const targetProjectId = getFallbackProjectId();
+        if (!targetRoomId && !targetProjectId) {
+            return missingRoomResponse();
+        }
+        const { identity, agentSession } = await resolveWorkerToolIdentity({
+            roomId: targetRoomId ?? currentRoom?.room_id ?? null,
+            agentSessionId: agent_session_id,
+        });
+        const sender = identity.actor_label;
+        const statusText = `[status] ${status}`;
+        const localRoomId = targetRoomId ?? currentRoom?.room_id ?? targetProjectId;
+        if (localRoomId && await isLocalRoomStorageEnabled(localRoomId)) {
+            const { localRoomId: sqliteRoomId } = await resolveLocalRoomStorageIdentifiers(localRoomId);
+            const effectiveLocalRoomId = sqliteRoomId || localRoomId;
+            const message = await addLocalChatMessage(effectiveLocalRoomId, {
+                sender,
+                text: statusText,
+                source: "agent",
+            });
+            touchCurrentRoom(message.id);
+            return jsonToolResponse({
+                success: true,
+                status_posted: status,
+                sender,
+                agent_identity: toPublicAgentIdentity(identity),
+                message_id: message.id,
+                timestamp: message.timestamp,
+            });
+        }
+        await syncRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity, {
+            status: classifyPresenceStatusText(status, getRememberedRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity).status),
+            status_text: status,
+        }, agentSession);
+        const message = await roomScopedApiCall({
+            room_id: targetRoomId,
+            project_id: targetProjectId,
+            room_path: (targetRoomId) => `/rooms/${encodeRoomIdPath(targetRoomId)}/messages`,
+            project_path: (targetProjectId) => `/projects/${encodeURIComponent(targetProjectId)}/messages`,
+            options: {
+                method: "POST",
+                body: JSON.stringify({
+                    sender,
+                    text: statusText,
+                    ...agentSessionCredentials(agentSession),
+                }),
+            },
+        });
+        touchCurrentRoom(typeof message.id === "string" ? message.id : undefined);
+        return jsonToolResponse({
+            success: true,
+            status_posted: status,
+            sender,
+            agent_identity: toPublicAgentIdentity(identity),
+            message_id: typeof message.id === "string" ? message.id : null,
+            timestamp: typeof message.timestamp === "string" ? message.timestamp : null,
+        });
+    });
+}