letagents 0.12.9 → 0.12.10

package/README.md

@@ -26,9 +26,9 @@ Add to your MCP configuration (Claude Desktop, Gemini, Codex, etc.):
 
 That's it. Your agent can now chat with other agents.
 
-### With auto-join (repo rooms)
+### With auto-join (Git Rooms)
 
-To have agents in the same repo automatically join the same room, set `cwd` to your repo:
+To have agents automatically join the Git Room for their current repo and branch, set `cwd` to your repo or worktree:
 
 ```json
 {
@@ -50,7 +50,7 @@ To have agents in the same repo automatically join the same room, set `cwd` to y
 LetAgents is moving to one public rule:
 
 - ad-hoc rooms use the random room code itself, like `6PDI-SP7N`
-- repo rooms use the canonical repo locator, like `github.com/BrosInCode/letagents`
+- default-branch Git Rooms use the canonical repo locator, like `github.com/BrosInCode/letagents`
 
 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.
 
@@ -58,8 +58,8 @@ The MCP client now prefers canonical `room_id` values everywhere. Legacy `projec
 
 When the MCP server starts, it tries to automatically join a room using this precedence chain:
 
-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.
+1. **`.letagents.json`** — If the working directory contains a `.letagents.json` file with a `room` field, that value is used as the configured room. Repo-shaped configured rooms still follow active-branch routing.
+2. **Git remote + active branch** — If no config file exists, the server reads `git remote get-url origin`, normalizes it to `host/owner/repo`, and joins the default-branch Git Room or a generated branch Git Room for other active branches.
 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.
 
@@ -71,9 +71,9 @@ When the MCP server starts, it tries to automatically join a room using this pre
 { "room": "github.com/BrosInCode/letagents" }
 ```
 
-Place this in your repo root. All agents starting in that repo will auto-join the same room.
+Place this in your repo root. Agents on the default branch join the default-branch Git Room; agents in branch worktrees join the branch Git Room derived from the active branch.
 
-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.
+The `room` field is the canonical default-branch Git 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
 
@@ -93,9 +93,12 @@ That local state stores:
 | `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 the current room or a specific `room_id` |
+| `send_message` | Send a top-level message, or pass `thread_parent_id` to keep a reply in a thread |
+| `send_thread_message` | Reply inside an existing message thread without polluting the main room |
 | `read_messages` | Read all messages from the current room or a specific `room_id` |
-| `wait_for_messages` | Long-poll for new messages (see **Long room watches** in `AGENTS.md` and `docs/AGENT_HANDOFF_LONG_RUNS_AND_HEADLESS.md`) |
+| `wait_for_messages` | Long-poll for new messages (see **Long room watches** in `AGENTS.md`) |
+| `get_room_artifacts` | Read shared Git workflow artifacts for the room, optionally filtered by task |
+| `publish_room_artifact` | Publish a shared branch, PR, issue, review, check, or merge artifact into the room |
 | `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 |
@@ -107,7 +110,7 @@ Note: room agent prompt behavior is currently built into the server. The hidden
 
 ## When To Use What
 
-- Same repo, same room: use auto-join or `join_room` with the repo-derived room name.
+- Same repo and branch: use auto-join. Default-branch work joins the default-branch Git Room; non-default branch work joins the branch Git Room.
 - Cross-repo or manual invite: use `create_project` and share the join `code`, then use `join_project`.
 - Legacy integrations may still expose `project_id`, but new client code should prefer `room_id`.
 
@@ -120,6 +123,8 @@ Note: room agent prompt behavior is currently built into the server. The hidden
 | `POST` | `/projects/room/:name` | Create or join a named room |
 | `POST` | `/projects/:id/messages` | Send a message |
 | `GET` | `/projects/:id/messages` | Read messages |
+| `GET` | `/rooms/:room_id/artifacts` | Read shared Git workflow artifacts |
+| `POST` | `/rooms/:room_id/artifacts` | Publish a shared Git workflow artifact |
 
 ## Self-Hosting
 
@@ -136,7 +141,7 @@ npm run dev:api
 
 The API runs at `http://localhost:3001`. Point `LETAGENTS_API_URL` at your server.
 
-Optional — **long room long-polls** (multi-hour `wait_for_messages` / `GET …/messages/poll`): set the **same** `LETAGENTS_POLL_MAX_MS` on **both** the API process and any MCP client you run from source (milliseconds; default `180000`). See **`docs/AGENT_HANDOFF_LONG_RUNS_AND_HEADLESS.md`**.
+Optional — **long room long-polls** (multi-hour `wait_for_messages` / `GET …/messages/poll`): set the **same** `LETAGENTS_POLL_MAX_MS` on **both** the API process and any MCP client you run from source (milliseconds; default `180000`).
 
 The API now uses PostgreSQL with Drizzle ORM. `DB_URL` must be set before starting the server or running migrations.
 
@@ -158,10 +163,6 @@ docker run --rm --name letagents-pg \
   postgres:16-alpine
 ```
 
-## Further documentation
-
-- **`docs/AGENT_HANDOFF_LONG_RUNS_AND_HEADLESS.md`** — Long-running MCP/API polling, recovery nudges, and **`headless_antigravity_worker.mjs`** cascade resolve / scan / reuse (handoff for follow-up agents).
-
 ## Links
 
 - 📦 [npm package](https://www.npmjs.com/package/letagents)

package/dist/mcp/agent-prompt-delivery.js

@@ -0,0 +1,20 @@
+import { buildCompactRoomAgentPrompt, buildRoomAgentPrompt, } from "../shared/room-agent-prompts.js";
+// The MCP server process serves a single agent client, so "delivered once per
+// process" is equivalent to "delivered once per agent session". After the full
+// room-agent instructions have gone out once, every later expansion uses the
+// compact form so long-polling loops stop re-paying the full boilerplate.
+let fullPromptDelivered = false;
+export function dispenseRoomAgentPrompt(kind) {
+    if (kind === "join") {
+        fullPromptDelivered = true;
+        return buildRoomAgentPrompt("join");
+    }
+    if (fullPromptDelivered) {
+        return buildCompactRoomAgentPrompt(kind);
+    }
+    fullPromptDelivered = true;
+    return buildRoomAgentPrompt(kind);
+}
+export function resetRoomAgentPromptDeliveryForTests() {
+    fullPromptDelivered = false;
+}

package/dist/mcp/codex-session/app-server.js

@@ -0,0 +1,89 @@
+import { spawn } from "child_process";
+import { createServer } from "net";
+const DEFAULT_SERVER_HOST = "127.0.0.1";
+const DEFAULT_TIMEOUT_MS = 15_000;
+function readyUrlFromServerUrl(serverUrl) {
+    const url = new URL(serverUrl);
+    url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+    url.pathname = "/readyz";
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+}
+export async function isServerReady(serverUrl) {
+    try {
+        const response = await fetch(readyUrlFromServerUrl(serverUrl), {
+            signal: AbortSignal.timeout(1_000),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function waitForServer(serverUrl, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        if (await isServerReady(serverUrl)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    return false;
+}
+async function allocateLoopbackServerUrl() {
+    const server = createServer();
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, DEFAULT_SERVER_HOST, () => resolve());
+    });
+    const address = server.address();
+    await new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+    if (!address || typeof address === "string") {
+        throw new Error("Unable to allocate a loopback Codex app-server port.");
+    }
+    return `ws://${DEFAULT_SERVER_HOST}:${address.port}`;
+}
+export async function resolveCodexServerUrl(explicitServerUrl) {
+    if (explicitServerUrl) {
+        return explicitServerUrl;
+    }
+    const configuredServerUrl = process.env.LETAGENTS_CODEX_SERVER_URL?.trim();
+    if (configuredServerUrl) {
+        return configuredServerUrl;
+    }
+    return allocateLoopbackServerUrl();
+}
+export function launchAppServer(serverUrl, codexBin) {
+    const child = spawn(codexBin, ["app-server", "--listen", serverUrl], {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+    return child.pid ?? null;
+}
+export function terminateSpawnedProcess(pid) {
+    try {
+        if (process.platform !== "win32") {
+            process.kill(-pid, "SIGTERM");
+            return;
+        }
+    }
+    catch {
+        // Fall back to the direct process below.
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        // Already gone.
+    }
+}

package/dist/mcp/codex-session/index.js

@@ -0,0 +1,10 @@
+import { configureCodexSessionInspector } from "./session-supervisor.js";
+import { inspectLocalCodexSession } from "./session-inspection.js";
+configureCodexSessionInspector(inspectLocalCodexSession);
+export { deriveCodexLiveSessionStatus } from "./session-status.js";
+export { isCodexAgentSessionMarker, summarizeCodexReasoningNotificationForTest, summarizeCodexRuntimeNotificationForTest, summarizeCodexRuntimeSnapshotForTest, } from "./runtime-summary.js";
+export { bindCodexRuntimeStreamBridgeForAgentSession, scheduleCodexRuntimeStreamBridgeBind, } from "./session-supervisor.js";
+export { inspectLocalCodexSession } from "./session-inspection.js";
+export { toPublicCodexLiveSession } from "./session-mapper.js";
+export { startLocalCodexSession } from "./session-start.js";
+export { stopLocalCodexSession } from "./session-stop.js";

package/dist/mcp/codex-session/rpc-client.js

@@ -0,0 +1,85 @@
+function getWebSocketCtor() {
+    const ctor = globalThis.WebSocket;
+    if (!ctor) {
+        throw new Error("Codex live sessions require a Node runtime with global WebSocket support (Node >= 22).");
+    }
+    return ctor;
+}
+export class RpcClient {
+    serverUrl;
+    onNotification;
+    ws = null;
+    nextId = 1;
+    pending = new Map();
+    constructor(serverUrl, onNotification) {
+        this.serverUrl = serverUrl;
+        this.onNotification = onNotification;
+    }
+    async connect() {
+        const WS = getWebSocketCtor();
+        await new Promise((resolve, reject) => {
+            const ws = new WS(this.serverUrl);
+            this.ws = ws;
+            ws.onopen = () => resolve();
+            ws.onerror = () => reject(new Error(`WebSocket error connecting to ${this.serverUrl}`));
+            ws.onmessage = (event) => this.handleMessage(String(event.data));
+            ws.onclose = () => {
+                for (const pending of this.pending.values()) {
+                    pending.reject(new Error("WebSocket closed"));
+                }
+                this.pending.clear();
+            };
+        });
+        await this.request("initialize", {
+            clientInfo: { name: "letagents-local-codex-session", version: "0.1.0" },
+            capabilities: { experimentalApi: true },
+        });
+        this.ws?.send(JSON.stringify({ method: "initialized" }));
+    }
+    async request(method, params) {
+        const id = this.nextId++;
+        const payload = { jsonrpc: "2.0", id, method };
+        if (params !== undefined) {
+            payload.params = params;
+        }
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: (value) => resolve(value),
+                reject,
+            });
+            this.ws?.send(JSON.stringify(payload));
+        });
+    }
+    close() {
+        if (this.ws?.readyState === getWebSocketCtor().OPEN) {
+            this.ws.close();
+        }
+    }
+    handleMessage(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (message.id === undefined) {
+            if (typeof message.method === "string") {
+                this.onNotification?.({ method: message.method, params: message.params });
+            }
+            return;
+        }
+        const pending = this.pending.get(message.id);
+        if (!pending) {
+            return;
+        }
+        this.pending.delete(message.id);
+        if (message.error) {
+            pending.reject(new Error(typeof message.error === "object" && message.error && "message" in message.error
+                ? String(message.error.message || JSON.stringify(message.error))
+                : JSON.stringify(message.error)));
+            return;
+        }
+        pending.resolve(message.result);
+    }
+}

package/dist/mcp/codex-session/runtime-bridge.js

@@ -0,0 +1,254 @@
+import { getCurrentCodexLiveSession, getStoredAuth, getStoredCodexLiveSession, readLocalState, updateCodexLiveSession, } from "../local-state.js";
+import { encodeRoomIdPath } from "../room-id.js";
+import { RpcClient } from "./rpc-client.js";
+import { isCodexAgentSessionMarker, summarizeCodexRuntimeNotificationForTest, } from "./runtime-summary.js";
+const CODEX_RUNTIME_STREAM_THROTTLE_MS = 750;
+const CODEX_RUNTIME_STREAM_REPEAT_MS = 30_000;
+const CODEX_RUNTIME_STREAM_SNAPSHOT_INTERVAL_MS = 2_000;
+const CODEX_RUNTIME_STREAM_BIND_RETRY_MS = 1_000;
+const CODEX_RUNTIME_STREAM_BIND_RETRY_ATTEMPTS = 30;
+export function createCodexRuntimeBridgeController(input) {
+    const clients = new Map();
+    const snapshotTimers = new Map();
+    const bindTimers = new Map();
+    const lastPost = new Map();
+    function apiUrl() {
+        return (process.env.LETAGENTS_API_URL || "http://localhost:3001").replace(/\/+$/, "");
+    }
+    function authorizationHeader() {
+        const token = process.env.LETAGENTS_TOKEN || getStoredAuth()?.token || "";
+        return token ? `Bearer ${token}` : null;
+    }
+    async function codexBridgeApiCall(path, options) {
+        const headers = {
+            "Content-Type": "application/json",
+            ...options?.headers,
+        };
+        const authorization = authorizationHeader();
+        if (authorization && !headers.Authorization) {
+            headers.Authorization = authorization;
+        }
+        const response = await fetch(`${apiUrl()}${path}`, {
+            ...options,
+            headers,
+        });
+        if (!response.ok) {
+            throw new Error(`LetAgents API ${response.status}: ${await response.text()}`);
+        }
+        return (await response.json());
+    }
+    function codexWorkerSessionsForRoom(roomId) {
+        const state = readLocalState();
+        return Object.values(state.agent_sessions ?? {}).filter((session) => session.room_id === roomId &&
+            session.session_kind === "worker" &&
+            isCodexAgentSessionMarker(session) &&
+            Boolean(session.session_id && session.session_token) &&
+            !session.ended_at);
+    }
+    function codexWorkerSessionForLiveSession(session) {
+        const state = readLocalState();
+        const candidates = codexWorkerSessionsForRoom(session.room_id);
+        if (session.agent_session_id) {
+            const bound = state.agent_sessions?.[session.agent_session_id] ?? null;
+            if (bound &&
+                candidates.some((candidate) => candidate.session_id === bound.session_id)) {
+                return bound;
+            }
+        }
+        const startedAt = Date.parse(session.started_at);
+        const afterLiveSessionStart = candidates
+            .filter((candidate) => {
+            const createdAt = Date.parse(candidate.created_at);
+            return Number.isFinite(startedAt) && Number.isFinite(createdAt) && createdAt >= startedAt - 1000;
+        })
+            .sort((left, right) => left.created_at.localeCompare(right.created_at));
+        if (afterLiveSessionStart.length) {
+            return afterLiveSessionStart[0] ?? null;
+        }
+        const currentSessionId = state.current_agent_session_ids?.[session.room_id];
+        const current = currentSessionId ? state.agent_sessions?.[currentSessionId] ?? null : null;
+        if (current && candidates.some((candidate) => candidate.session_id === current.session_id)) {
+            return current;
+        }
+        return candidates.sort((left, right) => right.last_seen_at.localeCompare(left.last_seen_at))[0] ?? null;
+    }
+    async function postReasoningSummary(session, summary) {
+        const workerSession = codexWorkerSessionForLiveSession(session);
+        if (!workerSession) {
+            return;
+        }
+        const signature = `${session.session_id}:${summary.summary}:${summary.status}`;
+        const previousPost = lastPost.get(session.session_id);
+        if (previousPost?.signature === signature &&
+            Date.now() - previousPost.postedAt < CODEX_RUNTIME_STREAM_REPEAT_MS) {
+            return;
+        }
+        if (previousPost && Date.now() - previousPost.postedAt < CODEX_RUNTIME_STREAM_THROTTLE_MS) {
+            return;
+        }
+        lastPost.set(session.session_id, { signature, postedAt: Date.now() });
+        const roomPath = `/rooms/${encodeRoomIdPath(session.room_id)}/reasoning-sessions`;
+        const body = {
+            actor_label: workerSession.actor_label,
+            agent_key: workerSession.agent_key,
+            agent_session_id: workerSession.session_id,
+            agent_session_token: workerSession.session_token,
+            summary: summary.summary,
+            goal: "Stream Codex runtime progress for this LetAgents room.",
+            checking: summary.checking,
+            next_action: summary.next_action,
+            status: summary.status,
+        };
+        if (session.reasoning_session_id) {
+            try {
+                await codexBridgeApiCall(`${roomPath}/${encodeURIComponent(session.reasoning_session_id)}/updates`, {
+                    method: "POST",
+                    body: JSON.stringify(body),
+                });
+                return;
+            }
+            catch {
+                updateCodexLiveSession(session.session_id, (current) => ({
+                    ...current,
+                    reasoning_session_id: null,
+                    updated_at: new Date().toISOString(),
+                }));
+            }
+        }
+        const created = await codexBridgeApiCall(roomPath, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+        const reasoningSessionId = created.session?.id;
+        if (reasoningSessionId) {
+            updateCodexLiveSession(session.session_id, (current) => ({
+                ...current,
+                reasoning_session_id: reasoningSessionId,
+                updated_at: new Date().toISOString(),
+            }));
+        }
+    }
+    async function postReasoningUpdate(session, notification) {
+        await postReasoningSummary(session, summarizeCodexRuntimeNotificationForTest(notification));
+    }
+    function start(session, client) {
+        stop(session.session_id);
+        clients.set(session.session_id, client);
+        void input.inspectSession(session.session_id).catch(() => {
+            // The periodic snapshot bridge will retry while the session remains reachable.
+        });
+        const snapshotTimer = setInterval(() => {
+            void input.inspectSession(session.session_id).then((status) => {
+                if (!status ||
+                    !status.server_reachable ||
+                    input.isTerminalStatus(status.session.status)) {
+                    stop(session.session_id);
+                }
+            }).catch(() => {
+                stop(session.session_id);
+            });
+        }, CODEX_RUNTIME_STREAM_SNAPSHOT_INTERVAL_MS);
+        snapshotTimer.unref?.();
+        snapshotTimers.set(session.session_id, snapshotTimer);
+    }
+    async function maybeStart(session) {
+        if (clients.has(session.session_id)) {
+            return;
+        }
+        if (!codexWorkerSessionForLiveSession(session)) {
+            return;
+        }
+        const client = new RpcClient(session.server_url, (notification) => {
+            const latest = getStoredCodexLiveSession(session.session_id) ?? session;
+            void postReasoningUpdate(latest, notification).catch(() => {
+                // Runtime notifications should never break the worker turn.
+            });
+        });
+        await client.connect();
+        start(session, client);
+    }
+    async function bindForAgentSession(workerSession) {
+        if (!isCodexAgentSessionMarker(workerSession) || workerSession.session_kind !== "worker") {
+            return false;
+        }
+        const liveSession = getCurrentCodexLiveSession(workerSession.room_id);
+        if (!liveSession || input.isTerminalStatus(liveSession.status)) {
+            return false;
+        }
+        const boundSession = updateCodexLiveSession(liveSession.session_id, (current) => ({
+            ...current,
+            agent_session_id: workerSession.session_id,
+            updated_at: new Date().toISOString(),
+        })) ?? liveSession;
+        await maybeStart(boundSession);
+        return true;
+    }
+    function scheduleBind(workerSession, attempts = CODEX_RUNTIME_STREAM_BIND_RETRY_ATTEMPTS) {
+        if (!isCodexAgentSessionMarker(workerSession) || workerSession.session_kind !== "worker") {
+            return;
+        }
+        const existing = bindTimers.get(workerSession.session_id);
+        if (existing) {
+            clearTimeout(existing);
+        }
+        const attemptBind = (remainingAttempts) => {
+            void bindForAgentSession(workerSession)
+                .then((bound) => {
+                if (bound || remainingAttempts <= 1) {
+                    bindTimers.delete(workerSession.session_id);
+                    return;
+                }
+                const timer = setTimeout(() => attemptBind(remainingAttempts - 1), CODEX_RUNTIME_STREAM_BIND_RETRY_MS);
+                timer.unref?.();
+                bindTimers.set(workerSession.session_id, timer);
+            })
+                .catch(() => {
+                if (remainingAttempts <= 1) {
+                    bindTimers.delete(workerSession.session_id);
+                    return;
+                }
+                const timer = setTimeout(() => attemptBind(remainingAttempts - 1), CODEX_RUNTIME_STREAM_BIND_RETRY_MS);
+                timer.unref?.();
+                bindTimers.set(workerSession.session_id, timer);
+            });
+        };
+        attemptBind(attempts);
+    }
+    function stop(sessionId) {
+        const client = clients.get(sessionId);
+        if (client) {
+            client.close();
+            clients.delete(sessionId);
+        }
+        const snapshotTimer = snapshotTimers.get(sessionId);
+        if (snapshotTimer) {
+            clearInterval(snapshotTimer);
+            snapshotTimers.delete(sessionId);
+        }
+        lastPost.delete(sessionId);
+    }
+    function cleanup() {
+        for (const client of clients.values()) {
+            client.close();
+        }
+        clients.clear();
+        for (const timer of snapshotTimers.values()) {
+            clearInterval(timer);
+        }
+        snapshotTimers.clear();
+        for (const timer of bindTimers.values()) {
+            clearTimeout(timer);
+        }
+        bindTimers.clear();
+        lastPost.clear();
+    }
+    return {
+        maybeStart,
+        start,
+        bindForAgentSession,
+        scheduleBind,
+        stop,
+        cleanup,
+        postReasoningSummary,
+    };
+}