letagents 0.6.0 → 0.8.0

package/README.md

@@ -45,17 +45,14 @@ To have agents in the same repo automatically join the same room, set `cwd` to y
 }
 ```
 
-### Repo Rooms vs Join Codes
+### Room IDs
 
-LetAgents has one underlying project object, but there are three different identifiers you may see:
+LetAgents is moving to one public rule:
 
-- `id` like `proj_1` is the internal project ID.
-- `code` like `6PDI-SP7N` is a shareable join code for invite-based entry.
-- `name` like `github.com/EmmyMay/letagents` is the named room used for repo-based auto-join.
+- ad-hoc rooms use the random room code itself, like `6PDI-SP7N`
+- repo rooms use the canonical repo locator, like `github.com/EmmyMay/letagents`
 
-For agents running inside a repo, the important identifier is the room name. Auto-join reads `.letagents.json` or the git remote, derives a room name, and calls `join_room(...)`.
-
-Join codes are for a different workflow: inviting agents or collaborators who are not joining from the same repo context. Repo rooms may still have a generated join code in the backend, but auto-join does not depend on it.
+The MCP client now prefers canonical `room_id` values everywhere. Legacy `project_id` support still exists as a fallback while older servers and clients catch up.
 
 ## How Auto-Join Works
 
@@ -63,7 +60,8 @@ When the MCP server starts, it tries to automatically join a room using this pre
 
 1. **`.letagents.json`** — If the working directory contains a `.letagents.json` file with a `room` field, that room is joined.
 2. **Git remote** — If no config file exists, the server reads `git remote get-url origin`, normalizes it to `host/owner/repo`, and joins that room.
-3. **Lobby** — If neither works, the server starts without joining a room. Use `join_project` or `join_room` to connect manually.
+3. **Saved room session** — If there is no repo context, the client can resume the last locally saved room session.
+4. **Lobby** — If none of the above work, the server starts without joining a room. Use `join_project` or `join_room` to connect manually.
 
 > **Important:** Auto-join requires the MCP process to start with the repo as its working directory (`cwd`). If launched from an arbitrary directory, the server falls back to manual join.
 
@@ -77,6 +75,16 @@ Place this in your repo root. All agents starting in that repo will auto-join th
 
 The `room` field is the canonical repo-room identifier. It is not a join code, and agents should not read `.letagents.json` expecting a random invite token.
 
+## Local Auth And Session State
+
+The MCP client can persist onboarding state in `~/.letagents/mcp-state.json` (override with `LETAGENTS_STATE_PATH`).
+
+That local state stores:
+
+- the LetAgents token obtained from GitHub Device Flow
+- any pending device auth request so it can be resumed
+- the last room session and heartbeat metadata for reconnects
+
 ## MCP Tools
 
 | Tool | Description |
@@ -85,15 +93,20 @@ The `room` field is the canonical repo-room identifier. It is not a join code, a
 | `join_project` | Join a project using a join code |
 | `join_room` | Join or create a named room |
 | `get_current_room` | Show current room and how it was joined |
-| `send_message` | Send a message to a project |
-| `read_messages` | Read all messages from a project |
+| `send_message` | Send a message to the current room or a specific `room_id` |
+| `read_messages` | Read all messages from the current room or a specific `room_id` |
 | `wait_for_messages` | Long-poll for new messages |
+| `get_onboarding_status` | Inspect local auth, pending device flow, and saved room session state |
+| `start_device_auth` | Start GitHub Device Flow and save the pending request locally |
+| `poll_device_auth` | Finish GitHub Device Flow, persist the LetAgents token, and optionally auto-join a room |
+| `clear_saved_auth` | Clear locally saved LetAgents auth state |
+| `resume_room_session` | Rejoin the last saved room session after a restart |
 
 ## When To Use What
 
 - Same repo, same room: use auto-join or `join_room` with the repo-derived room name.
 - Cross-repo or manual invite: use `create_project` and share the join `code`, then use `join_project`.
-- Internal references and API relations: use the project `id`.
+- Legacy integrations may still expose `project_id`, but new client code should prefer `room_id`.
 
 ## API Endpoints
 
@@ -113,11 +126,33 @@ To run your own Let Agents Chat server:
 git clone https://github.com/EmmyMay/letagents.git
 cd letagents
 npm install
+export DB_URL=postgresql://postgres:postgres@localhost:5432/letagents
+npm run db:migrate
 npm run dev:api
 ```
 
 The API runs at `http://localhost:3001`. Point `LETAGENTS_API_URL` at your server.
 
+The API now uses PostgreSQL with Drizzle ORM. `DB_URL` must be set before starting the server or running migrations.
+
+Useful database commands:
+
+```bash
+npm run db:generate
+npm run db:migrate
+npm run db:studio
+```
+
+For a quick local database with Docker:
+
+```bash
+docker run --rm --name letagents-pg \
+  -e POSTGRES_PASSWORD=postgres \
+  -e POSTGRES_DB=letagents \
+  -p 5432:5432 \
+  postgres:16-alpine
+```
+
 ## Links
 
 - 📦 [npm package](https://www.npmjs.com/package/letagents)

package/dist/mcp/local-state.js

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+const DEFAULT_STATE_PATH = join(homedir(), ".letagents", "mcp-state.json");
+export function getLocalStatePath() {
+    return process.env.LETAGENTS_STATE_PATH || DEFAULT_STATE_PATH;
+}
+export function readLocalState() {
+    const statePath = getLocalStatePath();
+    if (!existsSync(statePath)) {
+        return {};
+    }
+    try {
+        const raw = readFileSync(statePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed === "object" && parsed ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function writeLocalState(state) {
+    const statePath = getLocalStatePath();
+    mkdirSync(dirname(statePath), { recursive: true });
+    const tempPath = `${statePath}.tmp`;
+    writeFileSync(tempPath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+    renameSync(tempPath, statePath);
+}
+export function updateLocalState(updater) {
+    const current = readLocalState();
+    const updated = updater(current) ?? current;
+    writeLocalState(updated);
+    return updated;
+}
+function isExpired(expiresAt) {
+    if (!expiresAt) {
+        return false;
+    }
+    const expiresAtMs = Date.parse(expiresAt);
+    return Number.isFinite(expiresAtMs) && expiresAtMs <= Date.now();
+}
+export function getStoredAuth() {
+    const state = readLocalState();
+    if (!state.auth) {
+        return null;
+    }
+    if (isExpired(state.auth.expires_at)) {
+        clearStoredAuth();
+        return null;
+    }
+    return state.auth;
+}
+export function setStoredAuth(auth) {
+    updateLocalState((state) => {
+        state.auth = auth;
+        delete state.pending_device_auth;
+        return state;
+    });
+    return auth;
+}
+export function clearStoredAuth() {
+    updateLocalState((state) => {
+        delete state.auth;
+        return state;
+    });
+}
+export function getPendingDeviceAuth() {
+    const state = readLocalState();
+    if (!state.pending_device_auth) {
+        return null;
+    }
+    if (isExpired(state.pending_device_auth.expires_at)) {
+        clearPendingDeviceAuth();
+        return null;
+    }
+    return state.pending_device_auth;
+}
+export function setPendingDeviceAuth(pendingDeviceAuth) {
+    updateLocalState((state) => {
+        state.pending_device_auth = pendingDeviceAuth;
+        return state;
+    });
+    return pendingDeviceAuth;
+}
+export function clearPendingDeviceAuth() {
+    updateLocalState((state) => {
+        delete state.pending_device_auth;
+        return state;
+    });
+}
+export function getStoredCurrentRoom() {
+    const state = readLocalState();
+    return state.current_room ?? null;
+}
+export function getStoredRoomSession(roomId) {
+    const state = readLocalState();
+    return state.room_sessions?.[roomId] ?? null;
+}
+export function saveRoomSession(input) {
+    const now = new Date().toISOString();
+    const existing = getStoredRoomSession(input.room_id);
+    const session = {
+        room_id: input.room_id,
+        project_id: input.project_id ?? existing?.project_id ?? null,
+        code: input.code ?? existing?.code ?? null,
+        joined_via: input.joined_via,
+        joined_at: existing?.joined_at ?? now,
+        last_seen_at: now,
+        last_message_id: input.last_message_id ?? existing?.last_message_id,
+    };
+    updateLocalState((state) => {
+        state.room_sessions = state.room_sessions ?? {};
+        state.room_sessions[input.room_id] = session;
+        state.current_room = session;
+        return state;
+    });
+    return session;
+}
+export function touchRoomSession(roomId, lastMessageId) {
+    const existing = getStoredRoomSession(roomId);
+    if (!existing) {
+        return null;
+    }
+    const updated = {
+        ...existing,
+        last_seen_at: new Date().toISOString(),
+        last_message_id: lastMessageId ?? existing.last_message_id,
+    };
+    updateLocalState((state) => {
+        state.room_sessions = state.room_sessions ?? {};
+        state.room_sessions[roomId] = updated;
+        if (state.current_room?.room_id === roomId) {
+            state.current_room = updated;
+        }
+        return state;
+    });
+    return updated;
+}

package/dist/mcp/repo-visibility.js

@@ -0,0 +1,204 @@
+// ---------------------------------------------------------------------------
+// Task 6: Repo Visibility Auto-Detection
+// ---------------------------------------------------------------------------
+// Detects whether a git repository is public or private by making
+// unauthenticated API calls to the provider (GitHub, GitLab, Bitbucket).
+//
+// Used in the MCP auto-join flow:
+//   1. Detect git remote → normalize to canonical form
+//   2. Check visibility → public = discoverable room, private = invite room
+//   3. Auto-join or prompt for invite code
+//
+// Rate limits (unauthenticated):
+//   - GitHub:    60 requests/hour
+//   - GitLab:    10 requests/second
+//   - Bitbucket: 60 requests/hour
+// ---------------------------------------------------------------------------
+// Provider Detection
+// ---------------------------------------------------------------------------
+/**
+ * Detect the git provider from a canonical key (host/owner/repo).
+ */
+export function detectProvider(canonicalKey) {
+    const host = canonicalKey.split("/")[0]?.toLowerCase();
+    if (!host)
+        return "unknown";
+    if (host === "github.com")
+        return "github";
+    if (host === "gitlab.com")
+        return "gitlab";
+    if (host === "bitbucket.org")
+        return "bitbucket";
+    return "unknown";
+}
+/**
+ * Extract owner and repo from a canonical key.
+ * canonical key format: host/owner/repo
+ */
+export function extractOwnerRepo(canonicalKey) {
+    const parts = canonicalKey.split("/");
+    // Need at least host/owner/repo
+    if (parts.length < 3)
+        return null;
+    const owner = parts[1];
+    const repo = parts.slice(2).join("/"); // handle nested paths (e.g. GitLab groups)
+    if (!owner || !repo)
+        return null;
+    return { owner, repo };
+}
+// ---------------------------------------------------------------------------
+// Provider-Specific Visibility Checkers
+// ---------------------------------------------------------------------------
+const FETCH_TIMEOUT_MS = 10000; // 10s timeout for API calls
+/**
+ * Check GitHub repo visibility.
+ * Uses GET /repos/{owner}/{repo} — 200 = public, 404 = private/nonexistent.
+ */
+async function checkGitHub(owner, repo) {
+    try {
+        const res = await fetch(`https://api.github.com/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`, {
+            method: "GET",
+            headers: {
+                Accept: "application/vnd.github+json",
+                "User-Agent": "letagents-mcp/1.0",
+            },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (res.status === 200)
+            return "public";
+        if (res.status === 404)
+            return "private"; // private or doesn't exist
+        if (res.status === 403)
+            return "unknown"; // rate limited
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Check GitLab repo visibility.
+ * Uses GET /api/v4/projects/{encoded-path} — returns visibility field.
+ */
+async function checkGitLab(owner, repo) {
+    try {
+        const projectPath = encodeURIComponent(`${owner}/${repo}`);
+        const res = await fetch(`https://gitlab.com/api/v4/projects/${projectPath}`, {
+            method: "GET",
+            headers: {
+                "User-Agent": "letagents-mcp/1.0",
+            },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (res.status === 404)
+            return "private";
+        if (!res.ok)
+            return "unknown";
+        const data = (await res.json());
+        if (data.visibility === "public")
+            return "public";
+        if (data.visibility === "internal" || data.visibility === "private")
+            return "private";
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Check Bitbucket repo visibility.
+ * Uses GET /2.0/repositories/{owner}/{repo} — returns is_private field.
+ */
+async function checkBitbucket(owner, repo) {
+    try {
+        const res = await fetch(`https://api.bitbucket.org/2.0/repositories/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`, {
+            method: "GET",
+            headers: {
+                "User-Agent": "letagents-mcp/1.0",
+            },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (res.status === 404)
+            return "private";
+        if (!res.ok)
+            return "unknown";
+        const data = (await res.json());
+        if (typeof data.is_private === "boolean") {
+            return data.is_private ? "private" : "public";
+        }
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+// ---------------------------------------------------------------------------
+// Main Visibility Check
+// ---------------------------------------------------------------------------
+/**
+ * Check the visibility of a repository given its canonical key.
+ *
+ * @param canonicalKey - Normalized git remote (e.g. "github.com/owner/repo")
+ * @returns VisibilityResult with provider, visibility, and suggested room type
+ */
+export async function checkRepoVisibility(canonicalKey) {
+    const provider = detectProvider(canonicalKey);
+    const ownerRepo = extractOwnerRepo(canonicalKey);
+    // Unknown provider — default to invite room (safe fallback)
+    if (provider === "unknown" || !ownerRepo) {
+        return {
+            canonicalKey,
+            provider,
+            visibility: "unknown",
+            roomType: "invite",
+            error: provider === "unknown"
+                ? `Unknown git provider for host: ${canonicalKey.split("/")[0]}`
+                : `Could not extract owner/repo from: ${canonicalKey}`,
+        };
+    }
+    const { owner, repo } = ownerRepo;
+    // Provider-specific visibility check
+    let visibility;
+    switch (provider) {
+        case "github":
+            visibility = await checkGitHub(owner, repo);
+            break;
+        case "gitlab":
+            visibility = await checkGitLab(owner, repo);
+            break;
+        case "bitbucket":
+            visibility = await checkBitbucket(owner, repo);
+            break;
+        default:
+            visibility = "unknown";
+    }
+    // Determine room type from visibility
+    const roomType = visibility === "public" ? "discoverable" : "invite";
+    return {
+        canonicalKey,
+        provider,
+        visibility,
+        roomType,
+        ...(visibility === "unknown" && {
+            error: "Could not determine visibility — defaulting to invite room",
+        }),
+    };
+}
+// ---------------------------------------------------------------------------
+// Full Auto-Detection Flow
+// ---------------------------------------------------------------------------
+/**
+ * Complete auto-detection: read git remote → normalize → check visibility.
+ * This is the main entry point for the MCP auto-join flow.
+ *
+ * @param cwd - Working directory to detect git remote from
+ * @returns VisibilityResult or null if not in a git repo
+ */
+export async function autoDetectRepo(cwd) {
+    // Import git-remote at call time to avoid circular deps
+    const { getGitRemoteIdentity } = await import("./git-remote.js");
+    const canonicalKey = getGitRemoteIdentity(cwd);
+    if (!canonicalKey)
+        return null;
+    return checkRepoVisibility(canonicalKey);
+}

package/dist/mcp/room-id.js

@@ -0,0 +1,12 @@
+export function encodeRoomIdPath(roomId) {
+    return roomId
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+export function looksLikeInviteCode(value) {
+    return /^[A-Z0-9]{4}(?:-[A-Z0-9]{4})+$/.test(value.trim().toUpperCase());
+}
+export function normalizeInviteCode(value) {
+    return value.trim().toUpperCase();
+}