letagents 0.12.8 → 0.12.10

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

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { getRoomFromConfig } from "../../../config-reader.js";
+import { buildActiveGitRoomContext, getGitCurrentBranch, getGitDefaultBranch, getGitRoomContext, } from "../../../git-remote.js";
+import { resolveGitRoot } from "../../repo-context.js";
+import { API_URL, currentAgentIdentity, currentAgentIdentityKey, currentRoom, getLocalStatePath, getPendingDeviceAuth, getStoredAgentIdentity, getStoredAuth, getStoredCurrentRoom, toPublicAgentIdentity, toPublicRoomState, toPublicStoredRoomSession, } from "../../runtime.js";
+import { jsonTextResponse } from "./responses.js";
+export async function checkOnboardingApiHealth(apiUrl = API_URL, fetchImpl = globalThis.fetch, timeoutMs = 1500) {
+    const url = `${apiUrl.replace(/\/+$/, "")}/api/health`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(url, { signal: controller.signal });
+        return {
+            url,
+            reachable: response.ok,
+            status: response.status,
+            error: response.ok ? null : `HTTP ${response.status}`,
+        };
+    }
+    catch (error) {
+        return {
+            url,
+            reachable: false,
+            status: null,
+            error: error instanceof Error ? error.message : "fetch failed",
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function apiUrlHint(health) {
+    if (health.reachable) {
+        return null;
+    }
+    const localApi = /^https?:\/\/(?:localhost|127\.0\.0\.1)(?::|\/|$)/i.test(API_URL);
+    if (localApi) {
+        return "The MCP server is configured for a local LetAgents API, but the health check failed. Start the local API, or set LETAGENTS_API_URL=https://letagents.chat and restart the MCP server.";
+    }
+    return "The configured LetAgents API did not pass the health check. join_room and auth tools may fail until the backend is reachable.";
+}
+function authHint(authenticated) {
+    return authenticated
+        ? null
+        : "Public Git Rooms and ad-hoc rooms can be joined without auth. Private Git Rooms require start_device_auth, browser verification, then poll_device_auth to persist a LetAgents token.";
+}
+export function registerGetOnboardingStatusTool(server) {
+    server.tool("get_onboarding_status", "Inspect local Let Agents MCP auth and room-session state so a user can finish onboarding without guessing what is missing.", {
+        cwd: z
+            .string()
+            .optional()
+            .describe("Working directory to inspect for repo context. Defaults to the current process directory."),
+    }, async ({ cwd }) => {
+        const workingDir = cwd || process.cwd();
+        const repoRoot = resolveGitRoot(workingDir);
+        const configRoom = getRoomFromConfig(workingDir);
+        const gitContext = repoRoot ? getGitRoomContext(repoRoot) : null;
+        const configGitContext = configRoom
+            ? buildActiveGitRoomContext({
+                repoRoom: configRoom,
+                currentBranch: repoRoot ? getGitCurrentBranch(repoRoot) : null,
+                defaultBranch: repoRoot ? getGitDefaultBranch(repoRoot) : null,
+            })
+            : null;
+        const storedAuth = getStoredAuth();
+        const pendingAuth = getPendingDeviceAuth();
+        const savedCurrentRoom = getStoredCurrentRoom();
+        const detectedRoom = configGitContext?.activeRoom ?? gitContext?.activeRoom ?? null;
+        const api_health = await checkOnboardingApiHealth();
+        const authenticated = Boolean(process.env.LETAGENTS_TOKEN || storedAuth);
+        let nextStep = "join_room";
+        if (!storedAuth && pendingAuth) {
+            nextStep = "poll_device_auth";
+        }
+        else if (savedCurrentRoom && !currentRoom) {
+            nextStep = "resume_room_session";
+        }
+        return jsonTextResponse({
+            api_url: API_URL,
+            api_health,
+            api_url_hint: apiUrlHint(api_health),
+            local_state_path: getLocalStatePath(),
+            authenticated,
+            auth_source: process.env.LETAGENTS_TOKEN
+                ? "env"
+                : storedAuth
+                    ? "local_state"
+                    : "none",
+            auth_hint: authHint(authenticated),
+            account: storedAuth?.account ?? null,
+            token_expires_at: storedAuth?.expires_at ?? null,
+            pending_device_auth: pendingAuth,
+            agent_identity: toPublicAgentIdentity(currentAgentIdentity ?? getStoredAgentIdentity(currentAgentIdentityKey)),
+            current_room: toPublicRoomState(currentRoom),
+            saved_current_room: toPublicStoredRoomSession(savedCurrentRoom),
+            detected_room_from_context: detectedRoom,
+            configured_room_from_file: configRoom,
+            configured_active_room_from_context: configGitContext?.activeRoom ?? null,
+            derived_repo_room_from_git: gitContext?.repoRoom ?? null,
+            derived_active_git_room: gitContext?.activeRoom ?? null,
+            derived_branch_room_from_git: gitContext?.activeRefRoom ?? null,
+            git_current_branch: gitContext?.currentBranch ?? configGitContext?.currentBranch ?? null,
+            git_default_branch: gitContext?.defaultBranch ?? configGitContext?.defaultBranch ?? null,
+            repo_root: repoRoot,
+            next_step: nextStep,
+        });
+    });
+}

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

@@ -0,0 +1,8 @@
+import { registerDeviceAuthTools } from "./onboarding/device-auth-tools.js";
+import { registerSetAgentNameTool } from "./onboarding/name-tool.js";
+import { registerGetOnboardingStatusTool } from "./onboarding/status-tool.js";
+export function registerOnboardingTools(server) {
+    registerGetOnboardingStatusTool(server);
+    registerDeviceAuthTools(server);
+    registerSetAgentNameTool(server);
+}

package/dist/mcp/server/tools/rental/activity-tools.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { rentalCancel, rentalComplete, rentalEmitActivity, } from "../../../rental-tools.js";
+import { rentalTextResponse } from "./response.js";
+export function registerRentalActivityTools({ server, deps, }) {
+    server.tool("rental_emit_activity", "Emit an activity event into a rental session's event log (rental_activity_events table). The event is unverified by default per §9.4 — only tool-mediated event types are auto-verified server-side. Use this to record agent notes, progress updates, or custom milestones visible to the renter.", {
+        session_id: z.string().describe("Rental session id."),
+        event_type: z
+            .string()
+            .describe("Activity event type from §9.4 taxonomy (e.g. 'agent.note', 'edit.proposed'). Must be a known type."),
+        source: z
+            .string()
+            .optional()
+            .describe("Event source: 'agent', 'tool', 'patch_gate', 'system', 'renter', 'provider'. Defaults to 'agent'."),
+        payload: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Arbitrary JSON payload for the event. Defaults to {}."),
+        verified: z
+            .boolean()
+            .optional()
+            .describe("Override verification status. If omitted, the server resolves from the event type set."),
+    }, async ({ session_id, event_type, source, payload, verified }) => rentalTextResponse(await rentalEmitActivity(deps, {
+        session_id,
+        event_type,
+        source,
+        payload,
+        verified,
+    })));
+    server.tool("rental_complete", "Mark a rental session as completed. Transitions the session to terminal state 'completed', records ended_at, and triggers §18.4 teardown (activity event emission, resource cleanup). Either the renter or the provider can mark completion; the caller's role is recorded in the activity event.", {
+        session_id: z.string().describe("Rental session id to complete."),
+        summary: z
+            .string()
+            .optional()
+            .describe("Optional completion summary describing what was accomplished during the session."),
+    }, async ({ session_id, summary }) => rentalTextResponse(await rentalComplete(deps, { session_id, summary })));
+    server.tool("rental_cancel", "Cancel a rental session. Transitions the session to terminal state 'cancelled', records ended_at, and triggers §18.4 teardown. Either the renter or the provider can cancel. Use this when the session needs to be aborted — e.g. renter revokes access, provider encounters an unrecoverable error, or budget is fully exhausted.", {
+        session_id: z.string().describe("Rental session id to cancel."),
+        reason: z
+            .string()
+            .optional()
+            .describe("Optional reason for cancellation (e.g. 'budget_exhausted', 'renter_revoked')."),
+    }, async ({ session_id, reason }) => rentalTextResponse(await rentalCancel(deps, { session_id, reason })));
+}

package/dist/mcp/server/tools/rental/context-tools.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { rentalReadFile, rentalSearch } from "../../../rental-tools.js";
+import { rentalTextResponse } from "./response.js";
+export function registerRentalContextTools({ server, deps, }) {
+    server.tool("rental_read_file", "Read one repo-relative file from the scoped rental workspace through the Context Broker. The server applies the Secret Firewall, records an Exposure Ledger entry, and returns redacted content when needed. This is the only approved file-read path for provider agents in scoped mode.", {
+        session_id: z.string().describe("Rental session id whose scoped workspace to read."),
+        path: z.string().describe("Repo-relative file path inside the materialized rental workspace."),
+        max_bytes: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional maximum file size to return. Defaults server-side to 256 KiB."),
+    }, async ({ session_id, path, max_bytes }) => rentalTextResponse(await rentalReadFile(deps, { session_id, path, max_bytes })));
+    server.tool("rental_search", "Search literal text across the scoped rental workspace through the Context Broker. Matching snippets are Secret Firewall scanned and recorded as search_result exposures, but search results alone do not authorize Patch Gate edits.", {
+        session_id: z.string().describe("Rental session id whose scoped workspace to search."),
+        query: z.string().describe("Literal text query to search for."),
+        max_results: z
+            .number()
+            .int()
+            .positive()
+            .max(100)
+            .optional()
+            .describe("Maximum snippets to return. Defaults server-side to 20, capped at 100."),
+        case_sensitive: z
+            .boolean()
+            .optional()
+            .describe("Set true for case-sensitive literal search. Defaults to false."),
+    }, async ({ session_id, query, max_results, case_sensitive }) => rentalTextResponse(await rentalSearch(deps, {
+        session_id,
+        query,
+        max_results,
+        case_sensitive,
+    })));
+}

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

@@ -0,0 +1,17 @@
+import { apiCall } from "../../runtime.js";
+import { registerRentalActivityTools } from "./activity-tools.js";
+import { registerRentalContextTools } from "./context-tools.js";
+import { registerRentalMeteringTools } from "./metering-tools.js";
+import { registerRentalPatchTools } from "./patch-tools.js";
+import { registerRentalProviderTools } from "./provider-tools.js";
+export function registerRentalTools(server) {
+    const context = {
+        server,
+        deps: { apiCall },
+    };
+    registerRentalProviderTools(context);
+    registerRentalMeteringTools(context);
+    registerRentalContextTools(context);
+    registerRentalPatchTools(context);
+    registerRentalActivityTools(context);
+}

package/dist/mcp/server/tools/rental/metering-tools.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { rentalHeartbeat, rentalRefreshQuota, rentalReportUsage, rentalRequestBudgetExtension, } from "../../../rental-tools.js";
+import { rentalTextResponse } from "./response.js";
+export function registerRentalMeteringTools({ server, deps, }) {
+    server.tool("rental_heartbeat", "Beat the heart of an active Rent an Agent provider session. Records last_heartbeat_at and transitions provisioning → active on the first beat. Provider-only; the server returns not_provider when the caller does not own the lane. Call on a 30s cadence per spec §18.3.", {
+        session_id: z.string().describe("Rental session id to heartbeat."),
+    }, async ({ session_id }) => rentalTextResponse(await rentalHeartbeat(deps, { session_id })));
+    server.tool("rental_refresh_quota", "Read the most recent native quota snapshot recorded for a rental session (POST /api/rental/sessions/:id/refresh-quota). V1 returns the snapshot already stored on the session row by the desktop meter adapter pipeline; the server cannot push-poll a provider's adapter from here, so `refreshed` is false. Use this when the rented agent (or a renter UI) needs the freshest provider-side quota state visible to the server.", {
+        session_id: z
+            .string()
+            .describe("Rental session id whose latest quota snapshot to read."),
+        provider: z
+            .string()
+            .optional()
+            .describe("Optional provider hint (e.g. 'antigravity', 'cursor'). Used only for an audit trail; the server returns whatever snapshot it has regardless."),
+    }, async ({ session_id, provider }) => rentalTextResponse(await rentalRefreshQuota(deps, { session_id, provider })));
+    server.tool("rental_report_usage", "Forward an already-built IngestUsageReport to the rental usage ingest endpoint (POST /api/rental/sessions/:id/usage). The desktop meter adapter is the canonical source of these reports, so MCP-side use should be limited to tool-mediated steps the desktop adapter pipeline does not observe. See spec §17.7 / §19.6 for the report shape; the server validates and rejects malformed input. SCOPE: this tool ONLY persists to rental_usage_meters; it does NOT advance Budget Sentinel state. Callers that need budget gates to update (e.g. trigger budget.reconciled / budget.exhausted events) must separately invoke the Budget Sentinel reconcile endpoint (POST /api/rental/sessions/:id/budget/reconcile — p2.8b) or a future rental_reconcile_budget MCP tool.", {
+        session_id: z.string().describe("Rental session id to report against."),
+        report: z
+            .record(z.string(), z.unknown())
+            .describe("Pre-built IngestUsageReport object (source, snapshot, delta, lrt, idempotencyKey, etc.). Forwarded verbatim."),
+    }, async ({ session_id, report }) => rentalTextResponse(await rentalReportUsage(deps, { session_id, report })));
+    server.tool("rental_request_budget_extension", "Request additional LRT for a Rent an Agent session. This creates a pending budget.extension_requested activity event only; it does not grant budget and cannot approve itself. A renter must approve the request through the renter-side budget-extension approval route before the session lrt_limit changes.", {
+        session_id: z.string().describe("Rental session id that needs more LRT."),
+        requested_additional_lrt: z
+            .number()
+            .int()
+            .positive()
+            .describe("Positive amount of additional LRT requested."),
+        reason: z
+            .string()
+            .optional()
+            .describe("Optional short reason shown to the renter."),
+    }, async ({ session_id, requested_additional_lrt, reason }) => rentalTextResponse(await rentalRequestBudgetExtension(deps, {
+        session_id,
+        requested_additional_lrt,
+        reason,
+    })));
+}

package/dist/mcp/server/tools/rental/patch-tools.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { rentalProposeEdit, rentalProposePatch, rentalRunCommand, } from "../../../rental-tools.js";
+import { rentalTextResponse } from "./response.js";
+export function registerRentalPatchTools({ server, deps, }) {
+    server.tool("rental_propose_edit", "Append one whole-file edit to the Signed Change Journal for a rental session. This records an idempotent, tool-mediated edit and returns the reconstructed diff; Patch Gate validation happens through rental_propose_patch.", {
+        session_id: z.string().describe("Rental session id."),
+        idempotency_key: z.string().describe("Unique key for this edit request."),
+        path: z.string().describe("Repo-relative file path being edited."),
+        before_content: z.string().describe("Original file content the agent saw."),
+        after_content: z.string().describe("Proposed full replacement content."),
+        summary: z.string().optional().describe("Optional edit summary."),
+    }, async ({ session_id, idempotency_key, path, before_content, after_content, summary }) => rentalTextResponse(await rentalProposeEdit(deps, {
+        session_id,
+        idempotency_key,
+        path,
+        before_content,
+        after_content,
+        summary,
+    })));
+    server.tool("rental_propose_patch", "Submit a full-content patch proposal for Patch Gate validation. Every file must have been exposed through the Context Broker; the server applies path checks, Secret Firewall scanning, and records the gate result for renter review.", {
+        session_id: z.string().describe("Rental session id."),
+        idempotency_key: z.string().describe("Unique key for this patch proposal."),
+        files: z
+            .array(z.object({
+            path: z.string(),
+            operation: z.enum(["modify", "create", "delete"]),
+            content: z.string().optional(),
+            diff: z.string().optional(),
+        }))
+            .nonempty()
+            .describe("Patch files. modify/create require full content; diff-only proposals are rejected server-side."),
+        summary: z.string().optional().describe("Optional patch summary."),
+    }, async ({ session_id, idempotency_key, files, summary }) => rentalTextResponse(await rentalProposePatch(deps, {
+        session_id,
+        idempotency_key,
+        files,
+        summary,
+    })));
+    server.tool("rental_run_command", "Run a policy-checked test or verification command in the scoped rental workspace. Input must be an argv array; shell syntax, install/network/publish commands, and non-test commands are blocked.", {
+        session_id: z.string().describe("Rental session id."),
+        argv: z
+            .array(z.string())
+            .nonempty()
+            .describe("Command argv, e.g. [\"npm\", \"test\"] or [\"node\", \"--test\", \"src/api/__tests__/foo.test.ts\"]."),
+        timeout_ms: z
+            .number()
+            .int()
+            .positive()
+            .max(120_000)
+            .optional()
+            .describe("Optional timeout in milliseconds. Defaults server-side to 60000, capped at 120000."),
+    }, async ({ session_id, argv, timeout_ms }) => rentalTextResponse(await rentalRunCommand(deps, { session_id, argv, timeout_ms })));
+}

package/dist/mcp/server/tools/rental/provider-tools.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { rentalAccept, rentalDecline, rentalListRequests, rentalProvision, } from "../../../rental-tools.js";
+import { rentalTextResponse } from "./response.js";
+export function registerRentalProviderTools({ server, deps, }) {
+    server.tool("rental_list_requests", "List incoming Rent an Agent session requests for the authenticated provider. Returns an array of session objects in the 'requested' state. Use this to poll while you are available to host renters.", {}, async () => rentalTextResponse(await rentalListRequests(deps)));
+    server.tool("rental_accept", "Accept a pending Rent an Agent session request. Transitions the session from 'requested' to 'accepted' per spec §18.2. An optional idempotency_key is forwarded to the server for future idempotency support.", {
+        session_id: z
+            .string()
+            .describe("Rental session id (e.g. 'rsess_*'). Get this from rental_list_requests."),
+        idempotency_key: z
+            .string()
+            .optional()
+            .describe("Optional caller-chosen idempotency key. Forwarded to the server when provided."),
+    }, async ({ session_id, idempotency_key }) => rentalTextResponse(await rentalAccept(deps, { session_id, idempotency_key })));
+    server.tool("rental_provision", "Provision an accepted Rent an Agent session into a rental room. Creates the provider-visible rental room, moves the session to 'provisioning', and returns the room id. Call this after rental_accept and before rental_heartbeat.", {
+        session_id: z.string().describe("Rental session id to provision."),
+        parent_room_id: z
+            .string()
+            .describe("Parent room id/identifier where the renter started the session."),
+        provider_display_name: z
+            .string()
+            .optional()
+            .describe("Optional display name for the provider participant in the rental room."),
+    }, async ({ session_id, parent_room_id, provider_display_name }) => rentalTextResponse(await rentalProvision(deps, {
+        session_id,
+        parent_room_id,
+        provider_display_name,
+    })));
+    server.tool("rental_decline", "Decline a pending Rent an Agent session request. Transitions the session from 'requested' to 'cancelled' per spec §18.2. An optional reason is forwarded in the request body.", {
+        session_id: z.string().describe("Rental session id to decline."),
+        idempotency_key: z
+            .string()
+            .optional()
+            .describe("Optional caller-chosen idempotency key. Forwarded to the server when provided."),
+        reason: z
+            .string()
+            .optional()
+            .describe("Optional short reason forwarded in the decline body (e.g. 'busy', 'out of quota')."),
+    }, async ({ session_id, idempotency_key, reason }) => rentalTextResponse(await rentalDecline(deps, {
+        session_id,
+        idempotency_key,
+        reason,
+    })));
+}

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

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

package/dist/mcp/server/tools/rental/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export { registerRentalTools } from "./rental/index.js";

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

@@ -0,0 +1,5 @@
+export { registerRoomJoinTools } from "./join-tools.js";
+export { registerRoomInspectionTools } from "./inspection-tools.js";
+export { registerRepoInitializationTool } from "./repo-initialization-tool.js";
+export { registerRoomResumeTool } from "./resume-tool.js";
+export { registerRepoVisibilityTool } from "./repo-visibility-tool.js";

package/dist/mcp/server/tools/rooms/inspection-tools.js

@@ -0,0 +1,124 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { z } from "zod";
+import { getRoomFromConfig } from "../../../config-reader.js";
+import { buildActiveGitRoomContext, getGitCurrentBranch, getGitDefaultBranch, getGitRoomContext, } from "../../../git-remote.js";
+import { currentAgentIdentity, currentAgentIdentityKey, currentRoom, getConversationIdentity, getCurrentLiveSessionPayload, getStoredAgentIdentity, getStoredAuth, listStoredCodexLiveSessions, toPublicAgentIdentity, toPublicRoomState, withJoinRoomAgentPrompt, } from "../../runtime.js";
+import { findExistingConfig, resolveGitRoot, } from "../../repo-context.js";
+import { jsonToolResponse } from "./response.js";
+export function registerRoomInspectionTools(server) {
+    server.tool("get_current_room", "Get information about the currently joined room, including how it was joined.", {
+        conversation_id: z
+            .string()
+            .optional()
+            .describe("Optional conversation ID to report the conversation-scoped identity instead of the global one."),
+    }, async ({ conversation_id }) => jsonToolResponse(getCurrentRoomPayload(conversation_id)));
+    server.tool("check_repo", "Inspect the current repository context for Let Agents Chat. " +
+        "Shows the git repo root, detected .letagents.json path, auto-derived Git Room from git remote and active branch, " +
+        "and current room state. Useful for troubleshooting auto-join issues.", {
+        cwd: z
+            .string()
+            .optional()
+            .describe("Directory to inspect. Defaults to the current process directory."),
+    }, async ({ cwd: targetDir }) => jsonToolResponse(getRepoInspectionPayload(targetDir)));
+}
+function getCurrentRoomPayload(conversationId) {
+    if (!currentRoom) {
+        return {
+            connected: false,
+            message: "Not currently in any room",
+            current_local_codex_session: getCurrentLiveSessionPayload(),
+            local_codex_session_count: listStoredCodexLiveSessions().length,
+        };
+    }
+    const auth = getStoredAuth();
+    return withJoinRoomAgentPrompt({
+        connected: true,
+        ...toPublicRoomState(currentRoom),
+        current_local_codex_session: getCurrentLiveSessionPayload(currentRoom.room_id),
+        local_codex_session_count: listStoredCodexLiveSessions().length,
+        agent_identity: toPublicAgentIdentity(getConversationIdentity(conversationId)
+            ?? currentAgentIdentity
+            ?? getStoredAgentIdentity(currentAgentIdentityKey)),
+        auth: auth
+            ? {
+                source: process.env.LETAGENTS_TOKEN ? "env" : "local_state",
+                expires_at: auth.expires_at ?? null,
+                account: auth.account ?? null,
+            }
+            : null,
+    });
+}
+function getRepoInspectionPayload(targetDir) {
+    const startDir = targetDir || process.cwd();
+    const repoRoot = resolveGitRoot(startDir);
+    const configDir = repoRoot ? findExistingConfig(startDir) : null;
+    const configPath = configDir ? join(configDir, ".letagents.json") : null;
+    const configuredRoom = repoRoot ? getRoomFromConfig(startDir) : null;
+    const gitContext = repoRoot ? getGitRoomContext(repoRoot) : null;
+    const configGitContext = configuredRoom
+        ? buildActiveGitRoomContext({
+            repoRoom: configuredRoom,
+            currentBranch: repoRoot ? getGitCurrentBranch(repoRoot) : null,
+            defaultBranch: repoRoot ? getGitDefaultBranch(repoRoot) : null,
+        })
+        : null;
+    const detectedRoom = configGitContext?.activeRoom ?? gitContext?.activeRoom ?? null;
+    const currentRoomMatchesContext = Boolean(currentRoom && detectedRoom && currentRoom.room_id === detectedRoom);
+    return {
+        cwd: startDir,
+        repo_context_status: repoRoot ? "git_repo_detected" : "not_inside_git_repo",
+        git_repo_root: repoRoot ?? null,
+        config_file: configPath ?? null,
+        config_contents: readConfigContents(configPath),
+        configured_room_from_file: configuredRoom ?? null,
+        configured_active_room_from_context: configGitContext?.activeRoom ?? null,
+        derived_room_from_git: gitContext?.activeRoom ?? null,
+        derived_repo_room_from_git: gitContext?.repoRoom ?? null,
+        derived_branch_room_from_git: gitContext?.activeRefRoom ?? null,
+        git_current_branch: gitContext?.currentBranch ?? configGitContext?.currentBranch ?? null,
+        git_default_branch: gitContext?.defaultBranch ?? configGitContext?.defaultBranch ?? null,
+        detected_room_from_context: detectedRoom ?? null,
+        current_room: toPublicRoomState(currentRoom),
+        current_room_scope: currentRoomScope(currentRoomMatchesContext, detectedRoom),
+        warning: repoWarning({ repoRoot, detectedRoom, currentRoomMatchesContext }),
+        join_hint: joinHint({ repoRoot, detectedRoom, currentRoomMatchesContext }),
+    };
+}
+function readConfigContents(configPath) {
+    if (!configPath || !existsSync(configPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        return "<parse error>";
+    }
+}
+function currentRoomScope(currentRoomMatchesContext, detectedRoom) {
+    if (!currentRoom)
+        return "none";
+    return currentRoomMatchesContext && detectedRoom
+        ? "matches_detected_repo_context"
+        : "existing_joined_session_not_derived_from_inspected_cwd";
+}
+function repoWarning(input) {
+    if (!input.repoRoot && currentRoom) {
+        return "The inspected cwd is not inside a git repo. current_room is only the previously joined MCP room session, not a room derived from this cwd.";
+    }
+    if (input.repoRoot && currentRoom && input.detectedRoom && !input.currentRoomMatchesContext) {
+        return "The current joined room differs from the room detected for this repo context.";
+    }
+    return null;
+}
+function joinHint(input) {
+    if (!input.repoRoot) {
+        return "Not inside a git repo. Use create_room, join_code, or join_room to connect manually.";
+    }
+    if (!input.detectedRoom) {
+        return "Run initialize_repo to set up .letagents.json, or use join_room/join_code to connect.";
+    }
+    return input.currentRoomMatchesContext
+        ? null
+        : "Use join_room with detected_room_from_context to switch this MCP session to the detected Git Room.";
+}

package/dist/mcp/server/tools/rooms/join-tools.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { RepoRoomAuthRequiredError, createInviteRoom, joinInviteCode, joinNamedRoom, normalizeJoinSessionMode, toRepoRoomAuthRequiredResult, withJoinRoomAgentPrompt, } from "../../runtime.js";
+import { jsonToolResponse } from "./response.js";
+const joinSessionModeSchema = z
+    .enum(["live", "current"])
+    .optional()
+    .describe("Use 'current' (default) for a normal inline join. Use 'live' to start/reuse a detached local Codex room worker.");
+async function createInviteRoomResponse() {
+    const created = await createInviteRoom();
+    return jsonToolResponse(withJoinRoomAgentPrompt(created.response));
+}
+export function registerRoomJoinTools(server) {
+    server.tool("create_room", "Create a new invite room on Let Agents Chat. Returns the room ID and join code.", {}, async () => createInviteRoomResponse());
+    server.tool("create_project", "Legacy alias for create_room. Creates a new invite room and returns its join code.", {}, async () => createInviteRoomResponse());
+    server.tool("join_code", "Join an existing room using an invite code.", {
+        code: z.string().describe("The invite code shared for the room (e.g. 'ABCX-7291')"),
+        session_mode: joinSessionModeSchema,
+    }, async ({ code, session_mode }) => jsonToolResponse(await joinInviteCode(code, normalizeJoinSessionMode(session_mode))));
+    server.tool("join_project", "Legacy alias for join_code. Join an existing room using an invite code.", {
+        code: z.string().describe("The invite code shared for the room (e.g. 'ABCX-7291')"),
+        session_mode: joinSessionModeSchema,
+    }, async ({ code, session_mode }) => jsonToolResponse(await joinInviteCode(code, normalizeJoinSessionMode(session_mode))));
+    server.tool("join_room", "Join a named room on Let Agents Chat. Creates the room if it doesn't exist. Use this for repo-based room joining.", {
+        name: z.string().describe("The room name to join (e.g. 'github.com/owner/repo')"),
+        session_mode: joinSessionModeSchema,
+    }, async ({ name, session_mode }) => {
+        try {
+            return jsonToolResponse(await joinNamedRoom(name, normalizeJoinSessionMode(session_mode)));
+        }
+        catch (error) {
+            if (error instanceof RepoRoomAuthRequiredError) {
+                return jsonToolResponse(toRepoRoomAuthRequiredResult(error));
+            }
+            throw error;
+        }
+    });
+}