letagents 0.12.9 → 0.12.11

package/dist/mcp/server/tools/agent-sessions.js

@@ -0,0 +1,415 @@
+import { z } from "zod";
+import { scheduleCodexRuntimeStreamBridgeBind, } from "../../codex-session.js";
+import { getManagedAgentProvider, toManagedAgentStartResponse, } from "../../managed-agent-providers.js";
+import { encodeRoomIdPath, looksLikeInviteCode, normalizeInviteCode } from "../../room-id.js";
+import { AGENT_INSTANCE_UUID, RepoRoomAuthRequiredError, apiCall, agentSessionCredentials, currentRoom, detectAgentIdeLabel, detectAgentRuntimeLabel, endStoredAgentSession, ensureAgentIdentity, getSessionLivenessRegistration, getAgentSessionRepoBranch, getStoredAgentSession, getTargetRoomId, ensureLocalWorkerAgentSession, isLocalRoomStorageEnabled, joinRoomIdentifier, resolveLocalRoomStorageIdentifiers, saveAgentSession, toPublicAgentSession, toPublicRoomState, toRepoRoomAuthRequiredResult, withAgentIdentity, resolveWorkerToolIdentity, } from "../runtime.js";
+import { requireValidWorkerBearerRuntime, workerModeDisabledToolResult, } from "../runtime/worker-bearer.js";
+import { bindSupervisedWorkerSession } from "../runtime/supervisor-bridge.js";
+export function registerAgentSessionTools(server) {
+    // -- register_agent_session -------------------------------------------------
+    server.tool("register_agent_session", "Register this MCP client as an explicit room agent session. Unregistered MCP traffic is treated as controller traffic and stays out of the connected-agent roster.", {
+        room_id: z
+            .string()
+            .optional()
+            .describe("Canonical room ID. Defaults to the current room."),
+        session_kind: z
+            .enum(["worker", "controller"])
+            .optional()
+            .describe("Agent session kind. Workers appear in connected agent activity; controllers do not. Defaults to worker."),
+        runtime: z
+            .string()
+            .optional()
+            .describe("Runtime label such as codex, antigravity, or custom harness name."),
+        display_name: z
+            .string()
+            .optional()
+            .describe("Human-readable label for this worker session. Use distinct labels when one MCP process controls multiple workers."),
+        cwd: z
+            .string()
+            .optional()
+            .describe("Working directory used to detect the worker's active git branch. Defaults to the MCP server's working directory."),
+    }, async ({ room_id, session_kind, runtime, display_name, cwd }) => {
+        const targetRoomId = getTargetRoomId(room_id);
+        if (!targetRoomId) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "No room_id provided and not currently in a room.",
+                            hint: "Join a room first, or pass room_id explicitly.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const requestedRuntime = runtime?.trim() || detectAgentRuntimeLabel();
+        const repoBranch = getAgentSessionRepoBranch(cwd);
+        if (await isLocalRoomStorageEnabled(targetRoomId)) {
+            const session = await ensureLocalWorkerAgentSession(targetRoomId, {
+                sessionKind: session_kind ?? "worker",
+                runtime: requestedRuntime,
+                displayName: display_name,
+                repoBranch,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            local: true,
+                            agent_session: toPublicAgentSession(session),
+                            agent_session_id: session.session_id,
+                            use_agent_session_id: "Pass this exact local agent_session_id to wait_for_messages, send_message, send_thread_message, post_status, and task tools for this same-machine local room.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const { cloudRoomId } = await resolveLocalRoomStorageIdentifiers(targetRoomId);
+        const apiRoomId = cloudRoomId || targetRoomId;
+        if (requireValidWorkerBearerRuntime().mode === "worker") {
+            // The supplied bearer is issued for an existing server-side agent
+            // session. Do not call the owner-only registration endpoint or write
+            // any session credential to local storage.
+            const { agentSession } = await resolveWorkerToolIdentity({ roomId: apiRoomId });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            worker_bearer_mode: true,
+                            agent_session: toPublicAgentSession(agentSession),
+                            agent_session_id: agentSession.session_id,
+                            use_agent_session_id: "This local worker-bearer session marker may be passed to room tools. The supplied bearer remains the only server credential.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const identity = await ensureAgentIdentity();
+        if (!identity.canonical_key) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "Authenticated agent identity is required before registering an agent session.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const created = await apiCall(`/rooms/${encodeRoomIdPath(apiRoomId)}/agent-sessions`, {
+            method: "POST",
+            body: JSON.stringify({
+                actor_key: identity.canonical_key,
+                actor_label: identity.actor_label,
+                ide_label: identity.ide_label ?? detectAgentIdeLabel(),
+                agent_instance_id: AGENT_INSTANCE_UUID,
+                display_name: display_name?.trim() || identity.display_name,
+                session_kind: session_kind ?? "worker",
+                runtime: requestedRuntime,
+                repo_branch: repoBranch,
+                registration_liveness: getSessionLivenessRegistration(requestedRuntime),
+            }),
+        });
+        const sessionId = typeof created.session_id === "string" ? created.session_id : "";
+        const sessionToken = typeof created.session_token === "string" ? created.session_token : "";
+        if (!sessionId || !sessionToken) {
+            throw new Error("Agent session registration response was missing session credentials.");
+        }
+        const session = saveAgentSession({
+            session_id: sessionId,
+            session_token: sessionToken,
+            room_id: typeof created.room_id === "string" ? created.room_id : apiRoomId,
+            session_kind: created.session_kind === "controller" ? "controller" : "worker",
+            runtime: typeof created.runtime === "string" ? created.runtime : "unknown",
+            host_id: typeof created.host_id === "string" ? created.host_id : null,
+            host_kind: typeof created.host_kind === "string" ? created.host_kind : null,
+            host_label: typeof created.host_label === "string" ? created.host_label : null,
+            liveness_capability: typeof created.liveness_capability === "string" ? created.liveness_capability : null,
+            tool_bridge_id: typeof created.tool_bridge_id === "string" ? created.tool_bridge_id : null,
+            actor_label: typeof created.actor_label === "string" ? created.actor_label : identity.actor_label,
+            agent_key: typeof created.agent_key === "string" ? created.agent_key : identity.canonical_key,
+            agent_instance_id: typeof created.agent_instance_id === "string" ? created.agent_instance_id : AGENT_INSTANCE_UUID,
+            display_name: typeof created.display_name === "string" ? created.display_name : identity.display_name,
+            owner_label: typeof created.owner_label === "string" ? created.owner_label : identity.owner_label,
+            ide_label: typeof created.ide_label === "string" ? created.ide_label : identity.ide_label ?? detectAgentIdeLabel(),
+            repo_branch: typeof created.repo_branch === "string" ? created.repo_branch : repoBranch,
+            created_at: typeof created.created_at === "string" ? created.created_at : new Date().toISOString(),
+            updated_at: typeof created.updated_at === "string" ? created.updated_at : new Date().toISOString(),
+            last_seen_at: typeof created.last_seen_at === "string" ? created.last_seen_at : new Date().toISOString(),
+            ended_at: typeof created.ended_at === "string" ? created.ended_at : null,
+        });
+        await bindSupervisedWorkerSession(session);
+        scheduleCodexRuntimeStreamBridgeBind(session);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        agent_session: toPublicAgentSession(session),
+                        agent_session_id: session.session_id,
+                        use_agent_session_id: "Pass this exact agent_session_id to wait_for_messages, send_message, send_thread_message, post_status, and task tools for this specific worker. Do not rely on a shared current session.",
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // -- disconnect_agent_session ----------------------------------------------
+    server.tool("disconnect_agent_session", "Disconnect/end a registered worker session from a room. Pass the exact agent_session_id for the worker to disconnect.", {
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to the current room or the stored session room."),
+        agent_session_id: z.string().optional().describe("Registered agent session to disconnect."),
+    }, async ({ room_id, agent_session_id }) => {
+        let targetRoomId = getTargetRoomId(room_id);
+        const localSession = agent_session_id
+            ? getStoredAgentSession(agent_session_id)
+            : null;
+        if (!targetRoomId && localSession) {
+            targetRoomId = localSession.room_id;
+        }
+        if (!targetRoomId) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "No room_id provided and not currently in a room.",
+                            hint: "Join a room first, pass room_id, or pass a locally stored agent_session_id.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const targetSessionId = agent_session_id || localSession?.session_id;
+        if (!targetSessionId) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "agent_session_id is required to disconnect a worker session.",
+                            hint: "Pass the exact agent_session_id returned by register_agent_session.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        if (localSession?.ended_at) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            already_ended: true,
+                            agent_session: toPublicAgentSession(localSession),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const requestBody = localSession?.session_id === targetSessionId && localSession.session_kind === "worker"
+            ? agentSessionCredentials(localSession)
+            : {};
+        if (await isLocalRoomStorageEnabled(targetRoomId)) {
+            const endedSession = endStoredAgentSession(targetSessionId);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            local: true,
+                            agent_session: toPublicAgentSession(endedSession),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const { cloudRoomId } = await resolveLocalRoomStorageIdentifiers(targetRoomId);
+        const apiRoomId = cloudRoomId || targetRoomId;
+        const result = await apiCall(`/rooms/${encodeRoomIdPath(apiRoomId)}/agent-sessions/${encodeURIComponent(targetSessionId)}/disconnect`, {
+            method: "POST",
+            body: JSON.stringify(requestBody),
+        });
+        const endedAt = result.agent_session && typeof result.agent_session === "object" && "ended_at" in result.agent_session
+            ? String(result.agent_session.ended_at ?? new Date().toISOString())
+            : new Date().toISOString();
+        const endedLocalSession = localSession?.session_id === targetSessionId
+            ? endStoredAgentSession(targetSessionId, endedAt)
+            : null;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        room_id: targetRoomId,
+                        agent_session_id: targetSessionId,
+                        agent_session: result.agent_session ?? toPublicAgentSession(endedLocalSession),
+                        delivery_session: result.delivery_session ?? null,
+                        local_state: endedLocalSession ? "ended" : "unchanged",
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // -- local Codex live sessions ---------------------------------------------
+    server.tool("start_local_codex_session", "Start or reuse a detached local Codex live session for a LetAgents room. The worker will join the room, keep polling, contribute in discussion, and do repo work from the current working directory when asked.", {
+        room: z
+            .string()
+            .describe("Invite code or room name to run as a detached local Codex worker."),
+        cwd: z
+            .string()
+            .optional()
+            .describe("Working directory for repo work. Defaults to the current process directory."),
+        stop_phrase: z
+            .string()
+            .optional()
+            .describe("Exact room message text that tells the worker to stop. Defaults to /stop-codex-room."),
+        max_minutes: z
+            .number()
+            .optional()
+            .describe("Optional hard stop in minutes. Defaults to 0, which means run until stopped."),
+    }, async ({ room, cwd, stop_phrase, max_minutes }) => {
+        const disabled = workerModeDisabledToolResult("Local Codex session orchestration");
+        if (disabled) {
+            return {
+                content: [{ type: "text", text: JSON.stringify(disabled, null, 2) }],
+            };
+        }
+        const joinedVia = looksLikeInviteCode(room) ? "join_code" : "join_room";
+        try {
+            const joined = await joinRoomIdentifier(room, joinedVia);
+            const provider = getManagedAgentProvider("codex");
+            const liveSession = await provider.startLocalSession({
+                room_id: joined.room.room_id,
+                room_identifier: joinedVia === "join_code" ? normalizeInviteCode(room) : room.trim(),
+                room_code: joined.room.code ?? null,
+                room_display_name: joined.room.display_name ?? null,
+                joined_via: joinedVia,
+                cwd: cwd || process.cwd(),
+                stop_phrase,
+                max_minutes,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(await withAgentIdentity({
+                            success: true,
+                            room: toPublicRoomState(joined.room),
+                            ...toManagedAgentStartResponse(provider, liveSession),
+                        }), null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error instanceof RepoRoomAuthRequiredError) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(toRepoRoomAuthRequiredResult(error), null, 2),
+                        },
+                    ],
+                };
+            }
+            throw error;
+        }
+    });
+    server.tool("status_local_codex_session", "Inspect the current detached local Codex live session, or a specific one by session_id.", {
+        session_id: z
+            .string()
+            .optional()
+            .describe("Optional session id. Defaults to the current local Codex live session."),
+    }, async ({ session_id }) => {
+        const disabled = workerModeDisabledToolResult("Local Codex session orchestration");
+        if (disabled) {
+            return {
+                content: [{ type: "text", text: JSON.stringify(disabled, null, 2) }],
+            };
+        }
+        const provider = getManagedAgentProvider("codex");
+        const status = await provider.inspectLocalSession(session_id, currentRoom?.room_id);
+        if (!status) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: false, error: "No local Codex live session found." }, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        session: provider.toPublicLiveSession(status.session),
+                        server_reachable: status.server_reachable,
+                        thread_status: status.thread_status,
+                        turn_status: status.turn_status,
+                        recent_items: status.recent_items,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("stop_local_codex_session", "Stop the current detached local Codex live session, or a specific one by session_id.", {
+        session_id: z
+            .string()
+            .optional()
+            .describe("Optional session id. Defaults to the current local Codex live session."),
+        shutdown_server: z
+            .boolean()
+            .optional()
+            .describe("If true, also terminate the spawned codex app-server process when possible."),
+    }, async ({ session_id, shutdown_server }) => {
+        const disabled = workerModeDisabledToolResult("Local Codex session orchestration");
+        if (disabled) {
+            return {
+                content: [{ type: "text", text: JSON.stringify(disabled, null, 2) }],
+            };
+        }
+        const provider = getManagedAgentProvider("codex");
+        const stopped = await provider.stopLocalSession({
+            session_id,
+            room_id: currentRoom?.room_id,
+            shutdown_server,
+        });
+        if (!stopped) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: false, error: "No local Codex live session found." }, null, 2),
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        session: provider.toPublicLiveSession(stopped),
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

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

@@ -0,0 +1,14 @@
+import { registerReadMessagesTool } from "./read-tool.js";
+import { registerPostReasoningTool } from "./reasoning-tool.js";
+import { registerSendMessageTool } from "./send-tool.js";
+import { registerPostStatusTool } from "./status-tool.js";
+import { registerWaitForMessagesTool } from "./wait-tool.js";
+export function registerStatusTools(server) {
+    registerPostStatusTool(server);
+    registerPostReasoningTool(server);
+}
+export function registerMessageTools(server) {
+    registerSendMessageTool(server);
+    registerReadMessagesTool(server);
+    registerWaitForMessagesTool(server);
+}

package/dist/mcp/server/tools/messages/message-lookup.js

@@ -0,0 +1,75 @@
+import { encodeRoomIdPath } from "../../../room-id.js";
+import { ApiError, appendIncludePromptOnly, getLocalChatMessages, isMissingRouteError, roomScopedApiCall, } from "../../runtime.js";
+function isRecord(value) {
+    return Boolean(value && typeof value === "object");
+}
+export async function findLocalMessageById(roomId, messageId) {
+    let afterCursor;
+    for (;;) {
+        const result = await getLocalChatMessages(roomId, {
+            after: afterCursor,
+            include_prompt_only: true,
+        });
+        const messages = (result.messages ?? []).filter(isRecord);
+        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;
+    }
+}
+export async function findRemoteMessageById(input) {
+    if (input.roomId) {
+        try {
+            const result = await roomScopedApiCall({
+                room_id: input.roomId,
+                room_path: (roomId) => appendIncludePromptOnly(`/rooms/${encodeRoomIdPath(roomId)}/messages/${encodeURIComponent(input.messageId)}`),
+                project_path: () => "",
+                // Context lookups must not advance the room session cursor.
+                preserve_session_cursor: true,
+            });
+            return isRecord(result.message) ? result.message : null;
+        }
+        catch (error) {
+            if (isMissingRouteError(error)) {
+                // Older API without the by-id route: fall back to scanning history.
+            }
+            else if (error instanceof ApiError && error.status === 404) {
+                return null;
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    return scanRemoteMessageHistoryById(input);
+}
+async function scanRemoteMessageHistoryById(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 ?? []).filter(isRecord);
+        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;
+    }
+}

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

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import { encodeRoomIdPath } from "../../../room-id.js";
+import { appendIncludePromptOnly, currentRoom, ensureAgentIdentity, getFallbackProjectId, getLatestLocalChatMessages, getLocalChatMessages, getTargetRoomId, heartbeatRoomPresence, touchRoomSession, isLocalRoomStorageEnabled, resolveLocalRoomStorageIdentifiers, roomScopedApiCall, toAgentReadableMessages, } from "../../runtime.js";
+import { jsonToolResponse } from "./response.js";
+export const DEFAULT_READ_MESSAGES_LIMIT = 100;
+// Both the API and the local store clamp a single page to 500 messages.
+const MAX_MESSAGES_PER_PAGE = 500;
+export function selectRecentMessages(messages, limit) {
+    const total = messages.length;
+    const selected = limit > 0 && total > limit ? messages.slice(total - limit) : messages;
+    return {
+        messages: selected,
+        total_message_count: total,
+        omitted_message_count: total - selected.length,
+    };
+}
+function withRecencyTelemetry(output, selection) {
+    output.total_message_count = selection.total_message_count;
+    if (selection.omitted_message_count > 0) {
+        output.omitted_message_count = selection.omitted_message_count;
+        output.truncated = true;
+    }
+    return output;
+}
+// Fetch the most recent messages by paging BACKWARDS from the tail
+// (before=latest), so a limited read never walks the full room history.
+export async function fetchRecentRemoteMessages(input) {
+    const collected = [];
+    let beforeCursor = "latest";
+    let truncated = false;
+    let roomIdFromResponse;
+    let newestMessageId;
+    for (;;) {
+        const params = new URLSearchParams();
+        params.set("before", beforeCursor);
+        params.set("limit", String(Math.min(input.limit - collected.length, MAX_MESSAGES_PER_PAGE)));
+        const qs = params.toString();
+        const result = await roomScopedApiCall({
+            room_id: input.targetRoomId,
+            project_id: input.targetProjectId,
+            room_path: (targetRoomId) => appendIncludePromptOnly(`/rooms/${encodeRoomIdPath(targetRoomId)}/messages?${qs}`),
+            project_path: (targetProjectId) => appendIncludePromptOnly(`/projects/${encodeURIComponent(targetProjectId)}/messages?${qs}`),
+            // Pages after the first end on progressively OLDER messages; letting each
+            // page touch the session would walk last_message_id backwards and make
+            // resume_room_session replay already-read history.
+            preserve_session_cursor: true,
+        });
+        roomIdFromResponse = roomIdFromResponse || result.room_id || result.project_id;
+        const msgs = result.messages ?? [];
+        if (newestMessageId === undefined) {
+            const newest = msgs[msgs.length - 1]?.id;
+            if (typeof newest === "string" && newest)
+                newestMessageId = newest;
+        }
+        collected.unshift(...msgs);
+        const hasOlder = Boolean(result.has_older ?? result.has_more);
+        if (!hasOlder || msgs.length === 0)
+            break;
+        if (collected.length >= input.limit) {
+            truncated = true;
+            break;
+        }
+        const oldestId = msgs[0]?.id;
+        if (typeof oldestId !== "string" || !oldestId) {
+            truncated = true;
+            break;
+        }
+        beforeCursor = oldestId;
+    }
+    if (input.targetRoomId && newestMessageId) {
+        touchRoomSession(input.targetRoomId, newestMessageId);
+    }
+    return { messages: collected, truncated, roomIdFromResponse };
+}
+export function registerReadMessagesTool(server) {
+    server.tool("read_messages", "Read recent messages from a Let Agents Chat room (most recent `limit`, default 100; pass limit: 0 for the full history — expensive in busy rooms). Threaded replies include thread_parent_id/thread.root_message_id; use send_thread_message with that id to continue focused side discussion without polluting the main room. For long-running work, prefer wait_for_messages with after_message_id so you only process new lines and do not treat an empty poll as the end of the mission.", {
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to the current room."),
+        limit: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe(`Return only the most recent N messages (default ${DEFAULT_READ_MESSAGES_LIMIT}). Pass 0 for the full history. When older messages are omitted, the response carries truncated=true.`),
+    }, async ({ room_id, limit }) => {
+        const effectiveLimit = limit ?? DEFAULT_READ_MESSAGES_LIMIT;
+        const targetRoomId = getTargetRoomId(room_id);
+        const targetProjectId = getFallbackProjectId();
+        const localRoomId = targetRoomId ?? currentRoom?.room_id ?? targetProjectId;
+        if (localRoomId && await isLocalRoomStorageEnabled(localRoomId)) {
+            const { localRoomId: sqliteRoomId } = await resolveLocalRoomStorageIdentifiers(localRoomId);
+            const effectiveLocalRoomId = sqliteRoomId || localRoomId;
+            if (effectiveLimit > 0 && effectiveLimit <= MAX_MESSAGES_PER_PAGE) {
+                const result = await getLatestLocalChatMessages(effectiveLocalRoomId, {
+                    limit: effectiveLimit,
+                    include_prompt_only: true,
+                });
+                const output = {
+                    room_id: effectiveLocalRoomId,
+                    messages: toAgentReadableMessages(result.messages ?? []),
+                };
+                if (result.has_more)
+                    output.truncated = true;
+                return jsonToolResponse(output);
+            }
+            const allMessages = [];
+            let afterCursor;
+            for (;;) {
+                const result = await getLocalChatMessages(effectiveLocalRoomId, {
+                    after: afterCursor,
+                    include_prompt_only: true,
+                });
+                const msgs = result.messages ?? [];
+                allMessages.push(...msgs);
+                if (!result.has_more || msgs.length === 0)
+                    break;
+                const lastMsg = msgs[msgs.length - 1];
+                if (!lastMsg?.id)
+                    break;
+                afterCursor = lastMsg.id;
+            }
+            const selection = selectRecentMessages(allMessages, effectiveLimit);
+            return jsonToolResponse(withRecencyTelemetry({
+                room_id: effectiveLocalRoomId,
+                messages: toAgentReadableMessages(selection.messages),
+            }, selection));
+        }
+        if (effectiveLimit > 0) {
+            const recent = await fetchRecentRemoteMessages({
+                targetRoomId,
+                targetProjectId,
+                limit: effectiveLimit,
+            });
+            await heartbeatRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, await ensureAgentIdentity());
+            const output = {
+                messages: toAgentReadableMessages(recent.messages),
+            };
+            if (recent.truncated)
+                output.truncated = true;
+            if (recent.roomIdFromResponse) {
+                output[targetRoomId ? "room_id" : "project_id"] = recent.roomIdFromResponse;
+            }
+            return jsonToolResponse(output);
+        }
+        const allMessages = [];
+        let afterCursor;
+        let roomIdFromResponse;
+        for (;;) {
+            const query = new URLSearchParams();
+            if (afterCursor)
+                query.set("after", afterCursor);
+            const qs = query.toString();
+            const result = await roomScopedApiCall({
+                room_id: targetRoomId,
+                project_id: targetProjectId,
+                room_path: (targetRoomId) => appendIncludePromptOnly(`/rooms/${encodeRoomIdPath(targetRoomId)}/messages${qs ? `?${qs}` : ""}`),
+                project_path: (targetProjectId) => appendIncludePromptOnly(`/projects/${encodeURIComponent(targetProjectId)}/messages${qs ? `?${qs}` : ""}`),
+            });
+            roomIdFromResponse = roomIdFromResponse || result.room_id || result.project_id;
+            const msgs = result.messages ?? [];
+            allMessages.push(...msgs);
+            if (!result.has_more || msgs.length === 0)
+                break;
+            const lastMsg = msgs[msgs.length - 1];
+            if (!lastMsg?.id)
+                break;
+            afterCursor = lastMsg.id;
+        }
+        await heartbeatRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, await ensureAgentIdentity());
+        const selection = selectRecentMessages(allMessages, effectiveLimit);
+        const output = withRecencyTelemetry({ messages: toAgentReadableMessages(selection.messages) }, selection);
+        if (roomIdFromResponse) {
+            output[targetRoomId ? "room_id" : "project_id"] = roomIdFromResponse;
+        }
+        return jsonToolResponse(output);
+    });
+}