letagents 0.12.9 → 0.12.11

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

@@ -0,0 +1,403 @@
+import { z } from "zod";
+import { getPollTimeoutCapMs } from "../../../../shared/poll-timeout-cap.js";
+import { encodeRoomIdPath } from "../../../room-id.js";
+import { appendIncludePromptOnly, buildAgentDeliveryHeaders, currentRoom, ensureAgentIdentity, getFallbackProjectId, getLatestLocalChatMessages, getLocalChatMessages, getLastMessageId, getRememberedRoomPresence, getTargetRoomId, identityFromAgentSession, isLocalRoomStorageEnabled, listLocalTasks, resolveLocalRoomStorageIdentifiers, resolveAgentSession, roomScopedApiCall, syncRoomPresence, toAgentReadableMessages, touchRoomSession, WORKER_BEARER_AGENT_SESSION_ID, waitForLocalChatMessages, } from "../../runtime.js";
+import { requireValidWorkerBearerRuntime } from "../../runtime/worker-bearer.js";
+import { attachAgentMessageActivations } from "../../../../shared/activation-routing.js";
+import { findLocalMessageById, findRemoteMessageById } from "./message-lookup.js";
+import { fetchRecentRemoteMessages } from "./read-tool.js";
+import { jsonToolResponse } from "./response.js";
+const DEFAULT_POLL_TIMEOUT_MS = 30000;
+// When wait_for_messages is called WITHOUT an after_message_id cursor, it must
+// catch up on only the most RECENT messages instead of replaying the entire
+// room history (busy rooms archive millions of characters, which blows the
+// tool's token budget). This bounds that no-cursor catch-up to a recent tail.
+export const DEFAULT_WAIT_CATCHUP_LIMIT = 100;
+// Decide how the initial fetch should behave. With a cursor we return
+// everything after it (genuine "new since I last polled", already bounded);
+// without one we fetch only the bounded recent tail.
+export function planWaitForMessagesFetch(input) {
+    if (input.effectiveAfterMessageId) {
+        return { mode: "after_cursor", after: input.effectiveAfterMessageId };
+    }
+    return {
+        mode: "catch_up_tail",
+        limit: input.catchupLimit ?? DEFAULT_WAIT_CATCHUP_LIMIT,
+    };
+}
+const LOCAL_TASK_OWNER_STATUSES = new Set(["assigned", "in_progress", "blocked", "in_review"]);
+export function buildWaitForMessagesRequestOptions(input) {
+    return {
+        ...(input.signal ? { signal: input.signal } : {}),
+        headers: input.deliveryHeaders,
+    };
+}
+export function buildWaitForMessagesHistoryPageRequest(input) {
+    const querySuffix = input.queryString ? `?${input.queryString}` : "";
+    return {
+        room_id: input.targetRoomId,
+        project_id: input.targetProjectId,
+        room_path: (targetRoomId) => appendIncludePromptOnly(`/rooms/${encodeRoomIdPath(targetRoomId)}/messages${querySuffix}`),
+        project_path: (targetProjectId) => appendIncludePromptOnly(`/projects/${encodeURIComponent(targetProjectId)}/messages${querySuffix}`),
+        options: buildWaitForMessagesRequestOptions({ deliveryHeaders: input.deliveryHeaders }),
+    };
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object");
+}
+function messageId(message) {
+    return typeof message.id === "string" && message.id.trim() ? message.id : null;
+}
+export function resolveEffectiveAfterMessageId(input) {
+    const requested = input.requestedAfterMessageId?.trim();
+    return requested || undefined;
+}
+function replyReferenceId(message) {
+    const reply = message.reply_to ?? message.replyTo ?? null;
+    if (typeof reply === "string" && reply.trim()) {
+        return reply;
+    }
+    if (isRecord(reply) && typeof reply.id === "string" && reply.id.trim()) {
+        return reply.id;
+    }
+    return null;
+}
+function activationDecision(message) {
+    if (!isRecord(message))
+        return null;
+    const activation = message.activation;
+    if (!isRecord(activation))
+        return null;
+    const forCurrentAgent = activation.for_current_agent;
+    if (!isRecord(forCurrentAgent))
+        return null;
+    return typeof forCurrentAgent.decision === "string" ? forCurrentAgent.decision : null;
+}
+export function filterSilentActivationMessages(messages) {
+    const visibleMessages = [];
+    const skippedMessageIds = [];
+    let lastObservedMessageId = null;
+    for (const message of messages) {
+        if (isRecord(message)) {
+            lastObservedMessageId = messageId(message) ?? lastObservedMessageId;
+        }
+        if (activationDecision(message) === "silent") {
+            if (isRecord(message)) {
+                const id = messageId(message);
+                if (id)
+                    skippedMessageIds.push(id);
+            }
+            continue;
+        }
+        visibleMessages.push(message);
+    }
+    return {
+        messages: visibleMessages,
+        skipped_message_ids: skippedMessageIds,
+        last_observed_message_id: lastObservedMessageId,
+    };
+}
+function addActivationRoutingTelemetry(output, routing) {
+    if (routing.last_observed_message_id) {
+        output.last_observed_message_id = routing.last_observed_message_id;
+    }
+    if (routing.skipped_message_ids.length > 0) {
+        output.skipped_message_ids = routing.skipped_message_ids;
+        output.skipped_message_count = routing.skipped_message_ids.length;
+    }
+    return output;
+}
+export function resolveWaitAgentSession(roomId, agentSessionId) {
+    if (requireValidWorkerBearerRuntime().mode === "worker" &&
+        (!agentSessionId?.trim() || agentSessionId === WORKER_BEARER_AGENT_SESSION_ID)) {
+        return null;
+    }
+    if (!agentSessionId?.trim()) {
+        return null;
+    }
+    return resolveAgentSession(roomId, agentSessionId);
+}
+export async function localActivationContext(roomId) {
+    const result = await listLocalTasks(roomId, { openOnly: true });
+    return {
+        activeTaskLeases: result.tasks
+            .flatMap((task) => {
+            const agentKey = task.assignee_agent_key?.trim();
+            if (!LOCAL_TASK_OWNER_STATUSES.has(task.status) || !agentKey) {
+                return [];
+            }
+            return [{
+                    kind: "work",
+                    status: "active",
+                    actor_label: task.assignee || agentKey,
+                    agent_key: agentKey,
+                    agent_instance_id: task.assignee_agent_instance_id,
+                    agent_session_id: task.assignee_agent_session_id,
+                }];
+        }),
+    };
+}
+async function attachLocalActivationMetadata(roomId, messages, agentSession, options = {}) {
+    if (!agentSession || agentSession.session_kind !== "worker") {
+        return messages;
+    }
+    const records = messages.filter(isRecord);
+    const activationContext = options.includeTaskOwnerLeases === false
+        ? undefined
+        : await localActivationContext(roomId);
+    return attachAgentMessageActivations(records, {
+        actor_label: agentSession.actor_label,
+        agent_key: agentSession.agent_key,
+        agent_instance_id: agentSession.agent_instance_id ?? null,
+        agent_session_id: agentSession.session_id,
+        display_name: agentSession.display_name,
+        session_kind: agentSession.session_kind,
+    }, activationContext);
+}
+// Resolving an out-of-window parent costs a lookup (a by-id fetch, or a
+// page-by-page history scan against older APIs), so resolved (and observed)
+// messages are cached per process to keep repeat polls from re-resolving the
+// same thread roots. Message ids are
+// room-scoped, so the key includes the room scope. Message records are treated
+// as immutable once posted; a bounded insertion-ordered map keeps memory flat
+// for long-running workers.
+const THREAD_CONTEXT_CACHE_MAX = 500;
+const threadContextCache = new Map();
+function threadContextCacheKey(scopeId, targetMessageId) {
+    return `${scopeId}:${targetMessageId}`;
+}
+export function rememberThreadContextMessages(scopeId, records) {
+    for (const record of records) {
+        if (!isRecord(record))
+            continue;
+        const id = messageId(record);
+        if (!id)
+            continue;
+        const key = threadContextCacheKey(scopeId, id);
+        threadContextCache.delete(key);
+        threadContextCache.set(key, record);
+    }
+    while (threadContextCache.size > THREAD_CONTEXT_CACHE_MAX) {
+        const oldest = threadContextCache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        threadContextCache.delete(oldest);
+    }
+}
+export function resetThreadContextCacheForTests() {
+    threadContextCache.clear();
+}
+export async function collectThreadContextMessages(input) {
+    const records = input.messages.filter(isRecord);
+    const knownIds = new Set(records.map(messageId).filter((id) => Boolean(id)));
+    const seenIds = new Set(knownIds);
+    const pendingIds = records
+        .map(replyReferenceId)
+        .filter((id) => Boolean(id && !knownIds.has(id)));
+    const scopeId = input.roomId ?? input.localRoomId ?? input.projectId ?? "";
+    rememberThreadContextMessages(scopeId, records);
+    if (pendingIds.length === 0) {
+        // Nothing quotes an out-of-window message (idle polls land here), so skip
+        // storage-mode resolution entirely.
+        return [];
+    }
+    const contextMessages = [];
+    const useLocalStorage = Boolean(input.localRoomId && await isLocalRoomStorageEnabled(input.localRoomId));
+    const localIdentifiers = useLocalStorage
+        ? await resolveLocalRoomStorageIdentifiers(input.localRoomId)
+        : { localRoomId: input.localRoomId };
+    const sqliteRoomId = localIdentifiers.localRoomId || input.localRoomId;
+    while (pendingIds.length > 0) {
+        const nextId = pendingIds.shift();
+        if (!nextId || seenIds.has(nextId))
+            continue;
+        seenIds.add(nextId);
+        const cached = threadContextCache.get(threadContextCacheKey(scopeId, nextId));
+        const message = cached
+            ?? (useLocalStorage && input.localRoomId
+                ? await findLocalMessageById(sqliteRoomId || input.localRoomId, nextId)
+                : await findRemoteMessageById({
+                    roomId: input.roomId,
+                    projectId: input.projectId,
+                    messageId: nextId,
+                }));
+        if (!message)
+            continue;
+        if (!cached) {
+            rememberThreadContextMessages(scopeId, [message]);
+        }
+        contextMessages.push(message);
+        const parentId = replyReferenceId(message);
+        if (parentId && !seenIds.has(parentId)) {
+            pendingIds.push(parentId);
+        }
+    }
+    return contextMessages;
+}
+export function registerWaitForMessagesTool(server) {
+    server.tool("wait_for_messages", "Wait for new messages in a Let Agents Chat room (HTTP long-poll). Messages labeled activation.for_current_agent.decision=\"silent\" are skipped for the current worker; when last_observed_message_id is present, use it as cursor progress even if messages is empty. Threaded replies include thread_parent_id/thread.root_message_id; use send_thread_message with that id to keep focused side discussion out of the main room. For multi-hour runs, call in a loop: always pass after_message_id from the last message you processed or last_observed_message_id so an empty result means 'nothing new yet', not 'stop working'. If someone posted a premature 'I will wait' closing line, use send_message with a brief continue instruction. Per-call wait is capped (default max 180s unless LETAGENTS_POLL_MAX_MS is set on API and MCP).", {
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to the current room."),
+        after_message_id: z
+            .string()
+            .optional()
+            .describe(`Only return messages after this message ID (e.g. 'msg_3'). If omitted, returns just the most recent ${DEFAULT_WAIT_CATCHUP_LIMIT} messages (bounded recent tail) instead of the full room history, and advances the session cursor to the newest message.`),
+        timeout: z
+            .number()
+            .optional()
+            .describe("Maximum wait time in milliseconds (min 1000, capped by LETAGENTS_POLL_MAX_MS / server). If set to 0, the default timeout will be used."),
+        agent_session_id: z
+            .string()
+            .optional()
+            .describe("Registered agent session to use. Without this, the MCP transport is treated as controller traffic and is hidden from connected-agent activity."),
+    }, async ({ room_id, after_message_id, timeout, agent_session_id }) => {
+        const targetRoomId = getTargetRoomId(room_id);
+        const targetProjectId = getFallbackProjectId();
+        const localRoomId = targetRoomId ?? currentRoom?.room_id ?? targetProjectId;
+        const identity = await ensureAgentIdentity();
+        const sessionRoomId = targetRoomId ?? currentRoom?.room_id ?? localRoomId ?? null;
+        const agentSession = resolveWaitAgentSession(sessionRoomId, agent_session_id);
+        const maxPollMs = getPollTimeoutCapMs();
+        const serverTimeout = Math.min(Math.max(timeout || DEFAULT_POLL_TIMEOUT_MS, 1000), maxPollMs);
+        if (localRoomId && await isLocalRoomStorageEnabled(localRoomId)) {
+            const { localRoomId: sqliteRoomId } = await resolveLocalRoomStorageIdentifiers(localRoomId);
+            const effectiveLocalRoomId = sqliteRoomId || localRoomId;
+            const effectiveAfterMessageId = resolveEffectiveAfterMessageId({
+                requestedAfterMessageId: after_message_id,
+            });
+            const fetchPlan = planWaitForMessagesFetch({ effectiveAfterMessageId });
+            // Without a cursor, page BACKWARDS from the tail (getLatest…) so we
+            // return the most-recent messages, not the oldest N; with a cursor we
+            // keep the unchanged forward "everything after the cursor" behavior.
+            const existing = fetchPlan.mode === "catch_up_tail"
+                ? await getLatestLocalChatMessages(effectiveLocalRoomId, {
+                    limit: fetchPlan.limit,
+                    include_prompt_only: true,
+                })
+                : await getLocalChatMessages(effectiveLocalRoomId, {
+                    after: effectiveAfterMessageId,
+                    include_prompt_only: true,
+                });
+            const replayingExistingMessages = existing.messages.length > 0;
+            const result = replayingExistingMessages
+                ? existing
+                : await waitForLocalChatMessages(effectiveLocalRoomId, {
+                    after: effectiveAfterMessageId,
+                    timeoutMs: serverTimeout,
+                    include_prompt_only: true,
+                });
+            const messages = await attachLocalActivationMetadata(effectiveLocalRoomId, result.messages, agentSession, {
+                includeTaskOwnerLeases: !replayingExistingMessages,
+            });
+            const routing = filterSilentActivationMessages(messages);
+            touchRoomSession(effectiveLocalRoomId, routing.last_observed_message_id ?? getLastMessageId(result));
+            const threadContext = await collectThreadContextMessages({
+                messages: routing.messages,
+                localRoomId: effectiveLocalRoomId,
+                roomId: targetRoomId,
+                projectId: targetProjectId,
+            });
+            return jsonToolResponse({
+                room_id: effectiveLocalRoomId,
+                ...addActivationRoutingTelemetry({
+                    messages: toAgentReadableMessages(routing.messages, threadContext),
+                }, routing),
+            });
+        }
+        await syncRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity, getRememberedRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, agentSession ? identityFromAgentSession(agentSession) : identity), agentSession);
+        const clientTimeout = serverTimeout + (serverTimeout > 120_000 ? 120_000 : 5_000);
+        const effectiveAfterMessageId = resolveEffectiveAfterMessageId({
+            requestedAfterMessageId: after_message_id,
+        });
+        const fetchPlan = planWaitForMessagesFetch({ effectiveAfterMessageId });
+        const deliveryHeaders = buildAgentDeliveryHeaders(agentSession);
+        const allMessages = [];
+        let roomIdFromResponse;
+        // Long-poll the server (blocks up to serverTimeout for new messages),
+        // optionally seeded with a cursor. Shared by the cursor path and by the
+        // no-cursor empty-tail fallback so a quiet room still blocks instead of
+        // busy-spinning. When `after` is provided this also catches up any backlog
+        // after the cursor via forward pagination.
+        const longPollFromCursor = async (after) => {
+            const params = new URLSearchParams();
+            if (after)
+                params.set("after", after);
+            params.set("timeout", String(serverTimeout));
+            const queryString = params.toString();
+            const firstResult = await roomScopedApiCall({
+                room_id: targetRoomId,
+                project_id: targetProjectId,
+                room_path: (targetRoomId) => appendIncludePromptOnly(`/rooms/${encodeRoomIdPath(targetRoomId)}/messages/poll?${queryString}`),
+                project_path: (targetProjectId) => appendIncludePromptOnly(`/projects/${encodeURIComponent(targetProjectId)}/messages/poll?${queryString}`),
+                options: buildWaitForMessagesRequestOptions({
+                    deliveryHeaders,
+                    signal: AbortSignal.timeout(clientTimeout),
+                }),
+            });
+            allMessages.push(...(firstResult.messages ?? []));
+            roomIdFromResponse = roomIdFromResponse || firstResult.room_id || firstResult.project_id;
+            if (firstResult.has_more && allMessages.length > 0) {
+                let afterCursor = allMessages[allMessages.length - 1]?.id;
+                while (afterCursor) {
+                    const pageParams = new URLSearchParams();
+                    pageParams.set("after", afterCursor);
+                    const qs = pageParams.toString();
+                    const page = await roomScopedApiCall(buildWaitForMessagesHistoryPageRequest({
+                        targetRoomId,
+                        targetProjectId,
+                        queryString: qs,
+                        deliveryHeaders,
+                    }));
+                    const msgs = page.messages ?? [];
+                    allMessages.push(...msgs);
+                    if (!page.has_more || msgs.length === 0)
+                        break;
+                    afterCursor = msgs[msgs.length - 1]?.id;
+                }
+            }
+        };
+        if (fetchPlan.mode === "catch_up_tail") {
+            // No cursor: catch up on only the bounded recent tail. Mirror
+            // read_messages by paging BACKWARDS from the tail (before=latest) so we
+            // return the newest N and never walk the full room history. This also
+            // advances the session cursor to the newest message returned.
+            const recent = await fetchRecentRemoteMessages({
+                targetRoomId,
+                targetProjectId,
+                limit: fetchPlan.limit,
+            });
+            if (recent.messages.length > 0) {
+                allMessages.push(...recent.messages);
+                roomIdFromResponse = recent.roomIdFromResponse;
+            }
+            else {
+                // Empty tail => the room is effectively empty, so there is nothing to
+                // dump. Fall through to the long-poll (no cursor) so a worker looping
+                // in a quiet room blocks up to the timeout instead of busy-spinning,
+                // exactly as the local path does via waitForLocalChatMessages.
+                roomIdFromResponse = recent.roomIdFromResponse;
+                await longPollFromCursor();
+            }
+        }
+        else {
+            await longPollFromCursor(fetchPlan.after);
+        }
+        const routing = filterSilentActivationMessages(allMessages);
+        const threadContext = await collectThreadContextMessages({
+            messages: routing.messages,
+            localRoomId,
+            roomId: targetRoomId,
+            projectId: targetProjectId,
+        });
+        const output = addActivationRoutingTelemetry({
+            messages: toAgentReadableMessages(routing.messages, threadContext),
+        }, routing);
+        if (roomIdFromResponse) {
+            output[targetRoomId ? "room_id" : "project_id"] = roomIdFromResponse;
+        }
+        if (targetRoomId) {
+            touchRoomSession(targetRoomId, routing.last_observed_message_id ?? getLastMessageId(output));
+        }
+        await syncRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity, getRememberedRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, agentSession ? identityFromAgentSession(agentSession) : identity), agentSession);
+        return jsonToolResponse(output);
+    });
+}

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

@@ -0,0 +1 @@
+export { registerMessageTools, registerStatusTools } from "./messages/index.js";

package/dist/mcp/server/tools/onboarding/device-auth-tools.js

@@ -0,0 +1,158 @@
+import { z } from "zod";
+import { getRoomFromConfig } from "../../../config-reader.js";
+import { looksLikeInviteCode } from "../../../room-id.js";
+import { apiCall, clearAuthenticatedAccountCache, clearPendingDeviceAuth, clearStoredAuth, currentRoom, ensureAgentIdentity, getPendingDeviceAuth, joinRoomIdentifierWithoutImplicitGitRefCreate, setAuthenticatedAccountCache, setPendingDeviceAuth, setStoredAuth, toPublicAgentIdentity, withCanonicalRoomLink, } from "../../runtime.js";
+import { jsonTextResponse } from "./responses.js";
+import { workerModeDisabledToolResult } from "../../runtime/worker-bearer.js";
+export function registerDeviceAuthTools(server) {
+    registerStartDeviceAuthTool(server);
+    registerPollDeviceAuthTool(server);
+    registerClearSavedAuthTool(server);
+}
+function registerStartDeviceAuthTool(server) {
+    server.tool("start_device_auth", "Start GitHub Device Flow for Let Agents Chat and persist the pending request locally. Use this when private repo access or explicit LetAgents auth is needed.", {
+        room_id: z
+            .string()
+            .optional()
+            .describe("Optional room to associate with this auth request for later auto-join."),
+        force: z
+            .boolean()
+            .optional()
+            .describe("If true, replaces any existing pending device auth request."),
+    }, async ({ room_id, force }) => {
+        const disabled = workerModeDisabledToolResult();
+        if (disabled)
+            return jsonTextResponse(disabled);
+        const existing = getPendingDeviceAuth();
+        if (existing && !force) {
+            return jsonTextResponse({
+                success: true,
+                reused_existing_request: true,
+                ...existing,
+            });
+        }
+        const response = await apiCall("/auth/device/start", {
+            method: "POST",
+        });
+        const pendingAuth = setPendingDeviceAuth({
+            request_id: response.request_id,
+            user_code: response.user_code,
+            verification_uri: response.verification_uri,
+            interval_seconds: response.interval,
+            expires_at: new Date(Date.now() + response.expires_in * 1000).toISOString(),
+            started_at: new Date().toISOString(),
+            suggested_room_id: room_id ?? currentRoom?.room_id ?? getRoomFromConfig() ?? undefined,
+        });
+        return jsonTextResponse({
+            success: true,
+            ...pendingAuth,
+        });
+    });
+}
+function registerPollDeviceAuthTool(server) {
+    server.tool("poll_device_auth", "Poll a pending GitHub Device Flow request. On success this stores the LetAgents token locally and can optionally join a room immediately.", {
+        request_id: z
+            .string()
+            .optional()
+            .describe("The device auth request to poll. Defaults to the locally saved pending request."),
+        room_id: z
+            .string()
+            .optional()
+            .describe("Optional room to auto-join after authorization succeeds."),
+        auto_join: z
+            .boolean()
+            .optional()
+            .describe("If true, tries to join the room immediately after the auth succeeds."),
+    }, async ({ request_id, room_id, auto_join }) => {
+        const disabled = workerModeDisabledToolResult();
+        if (disabled)
+            return jsonTextResponse(disabled);
+        const pendingAuth = request_id
+            ? getPendingDeviceAuth()?.request_id === request_id
+                ? getPendingDeviceAuth()
+                : null
+            : getPendingDeviceAuth();
+        if (!pendingAuth && !request_id) {
+            return jsonTextResponse({
+                success: false,
+                error: "No pending device auth request found.",
+            });
+        }
+        const requestId = request_id || pendingAuth?.request_id;
+        if (!requestId) {
+            return jsonTextResponse({
+                success: false,
+                error: "A request_id is required when nothing is saved locally.",
+            });
+        }
+        const result = await apiCall(`/auth/device/poll/${encodeURIComponent(requestId)}`);
+        if (result.status === "pending" || result.status === "slow_down") {
+            if (pendingAuth) {
+                setPendingDeviceAuth({
+                    ...pendingAuth,
+                    interval_seconds: result.interval ?? pendingAuth.interval_seconds,
+                    expires_at: result.expires_in !== undefined
+                        ? new Date(Date.now() + result.expires_in * 1000).toISOString()
+                        : pendingAuth.expires_at,
+                });
+            }
+            return jsonTextResponse({ success: true, ...result });
+        }
+        if (result.status === "denied" || result.status === "expired") {
+            clearPendingDeviceAuth();
+            clearStoredAuth();
+            clearAuthenticatedAccountCache();
+            return jsonTextResponse({ success: false, ...result });
+        }
+        if (!result.letagents_token) {
+            throw new Error("Device auth completed without a LetAgents token.");
+        }
+        clearPendingDeviceAuth();
+        const storedAuth = setStoredAuth({
+            token: result.letagents_token,
+            expires_at: result.expires_at,
+            account: result.account,
+            stored_at: new Date().toISOString(),
+            source: "device_flow",
+        });
+        setAuthenticatedAccountCache(storedAuth.account ?? undefined, storedAuth.account ? "stored" : null, null);
+        let joinedRoom = null;
+        const roomToJoin = room_id ||
+            pendingAuth?.suggested_room_id ||
+            currentRoom?.room_id ||
+            getRoomFromConfig() ||
+            undefined;
+        if (auto_join && roomToJoin) {
+            const joinedVia = looksLikeInviteCode(roomToJoin) ? "join_code" : "join_room";
+            const joined = await joinRoomIdentifierWithoutImplicitGitRefCreate(roomToJoin, joinedVia, { fallbackToRepo: true });
+            joinedRoom = joined.room;
+        }
+        const agentIdentity = await ensureAgentIdentity();
+        return jsonTextResponse({
+            success: true,
+            status: "authorized",
+            account: storedAuth.account ?? null,
+            expires_at: storedAuth.expires_at ?? null,
+            auto_joined_room: joinedRoom,
+            ...(joinedRoom?.room_id
+                ? withCanonicalRoomLink(joinedRoom.room_id, {})
+                : {}),
+            agent_identity: toPublicAgentIdentity(agentIdentity),
+            hint: "You can change your agent's display name anytime using the set_agent_name tool.",
+        });
+    });
+}
+function registerClearSavedAuthTool(server) {
+    server.tool("clear_saved_auth", "Clear any locally saved LetAgents auth token and pending device auth request.", {}, async () => {
+        const disabled = workerModeDisabledToolResult();
+        if (disabled)
+            return jsonTextResponse(disabled);
+        clearPendingDeviceAuth();
+        clearStoredAuth();
+        clearAuthenticatedAccountCache();
+        return jsonTextResponse({
+            success: true,
+            env_token_still_present: Boolean(process.env.LETAGENTS_TOKEN),
+        });
+    });
+}

package/dist/mcp/server/tools/onboarding/name-tool.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { buildAgentActorLabel, formatOwnerAttribution } from "../../../../shared/agent-identity.js";
+import { normalizeAgentBaseName } from "../../../../shared/codenames.js";
+import { apiCall, currentAgentIdentity, currentAgentIdentityKey, detectAgentIdeLabel, getConversationIdentity, getLetagentsToken, resolveOwnerContext, setConversationIdentity, storeCurrentAgentIdentity, toPublicAgentIdentity, } from "../../runtime.js";
+import { jsonTextResponse } from "./responses.js";
+import { workerModeDisabledToolResult } from "../../runtime/worker-bearer.js";
+export function registerSetAgentNameTool(server) {
+    server.tool("set_agent_name", "Set or change the agent's display name. The agent will be known by this name in the room. Use this to pick a custom name instead of the auto-generated codename.", {
+        name: z
+            .string()
+            .min(2)
+            .max(64)
+            .describe("The desired display name for this agent (2-64 characters)."),
+        conversation_id: z
+            .string()
+            .optional()
+            .describe("Optional conversation ID to scope this name change. When provided, only this conversation uses the new name; other conversations keep their own identity."),
+    }, async ({ name: desiredName, conversation_id }) => {
+        const disabled = workerModeDisabledToolResult();
+        if (disabled)
+            return jsonTextResponse(disabled);
+        const trimmedName = desiredName.trim();
+        if (trimmedName.length < 2 || trimmedName.length > 64) {
+            return jsonTextResponse({
+                success: false,
+                error: "Name must be between 2 and 64 characters.",
+            });
+        }
+        const authAvailable = Boolean(await getLetagentsToken());
+        if (!authAvailable) {
+            return jsonTextResponse({
+                success: false,
+                error: "Authentication required. Run start_device_auth first.",
+            });
+        }
+        const slugName = normalizeAgentBaseName(trimmedName);
+        try {
+            const owner = await resolveOwnerContext();
+            const ideLabel = detectAgentIdeLabel();
+            const ownerAttribution = formatOwnerAttribution(owner.label);
+            const actorLabel = buildAgentActorLabel({
+                display_name: trimmedName,
+                owner_label: owner.label,
+                ide_label: ideLabel,
+            });
+            let canonicalKey = owner.login ? `${owner.login}/${slugName}` : null;
+            if (!conversation_id) {
+                const registered = await apiCall("/agents", {
+                    method: "POST",
+                    body: JSON.stringify({
+                        name: slugName,
+                        display_name: trimmedName,
+                        owner_label: owner.label,
+                    }),
+                });
+                if (typeof registered.canonical_key === "string") {
+                    canonicalKey = registered.canonical_key;
+                }
+            }
+            const updatedIdentity = {
+                name: slugName,
+                display_name: trimmedName,
+                owner_label: owner.label,
+                owner_attribution: ownerAttribution,
+                ide_label: ideLabel,
+                actor_label: actorLabel,
+                canonical_key: canonicalKey,
+                runtime_key: currentAgentIdentityKey,
+                source: conversation_id ? "local" : "api",
+                resolved_at: new Date().toISOString(),
+            };
+            if (conversation_id) {
+                setConversationIdentity(conversation_id, updatedIdentity);
+            }
+            else {
+                storeCurrentAgentIdentity(updatedIdentity, currentAgentIdentityKey);
+            }
+            return jsonTextResponse({
+                success: true,
+                message: `Agent name changed to "${trimmedName}".`,
+                agent_identity: toPublicAgentIdentity(conversation_id
+                    ? getConversationIdentity(conversation_id)
+                    : currentAgentIdentity),
+            });
+        }
+        catch (error) {
+            return jsonTextResponse({
+                success: false,
+                error: `Failed to set name: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    });
+}

package/dist/mcp/server/tools/onboarding/responses.js

@@ -0,0 +1,10 @@
+export function jsonTextResponse(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}