letagents 0.12.29 → 0.12.31

package/README.md

@@ -212,7 +212,7 @@ The API runs at `http://localhost:3001`. Point `LETAGENTS_API_URL` at your serve
 
 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`).
 
-Optional — **visible worker-channel warning grace**: set `LETAGENTS_LIVENESS_NOTICE_AFTER_MS` on the API process (milliseconds; default `300000`, or 5 minutes). Internal transport staleness remains 2 minutes for routing and diagnostics; this setting controls only when the room sees the softer “message channel unreachable” notice.
+Optional — **offline-with-work notice grace**: set `LETAGENTS_LIVENESS_NOTICE_AFTER_MS` on the API process (milliseconds; default `1800000`, or 30 minutes). The room is told about an unreachable worker only while it holds an active work lease, and only after this grace; ordinary connects and disconnects are never posted (the roster shows presence). Internal transport staleness remains 2 minutes for routing and diagnostics.
 
 The API now uses PostgreSQL with Drizzle ORM. `DB_URL` must be set before starting the server or running migrations.
 

package/dist/mcp/local-state/storage.js

@@ -47,11 +47,6 @@ function writeLocalStateUnlocked(statePath, state) {
 function withStateLock(callback) {
     return withStateFileLock(getLocalStatePath(), callback);
 }
-export function writeLocalState(state) {
-    withStateLock((statePath) => {
-        writeLocalStateUnlocked(statePath, state);
-    });
-}
 export function updateLocalState(updater) {
     return withStateLock((statePath) => {
         const current = readLocalStateFromPath(statePath);

package/dist/mcp/server/runtime/api.js

@@ -1,6 +1,7 @@
 import { clearAuthenticatedAccountCache } from "./auth-cache.js";
 import { currentWorkerCall } from "../../worker-call-context.js";
-import { LETAGENTS_AGENT_SESSION_TOKEN_HEADER } from "../../../shared/request-headers.js";
+import { AGENT_SESSION_ENDED_ERROR, LETAGENTS_AGENT_SESSION_ID_HEADER, LETAGENTS_AGENT_SESSION_TOKEN_HEADER, } from "../../../shared/request-headers.js";
+import { endStoredAgentSession } from "../../local-state/agent-sessions.js";
 import { getDaemonToolExecutionContext } from "./daemon-tool-context.js";
 import { requireValidWorkerBearerRuntime } from "./worker-bearer.js";
 import { borrowCurrentSupervisedWorkerCredential, } from "./supervisor-bridge.js";
@@ -97,6 +98,54 @@ export function resolveApiPath(urlOrPath) {
         return "/auth/device/start";
     }
 }
+/**
+ * The room says the session this request was made for has ended. Record it,
+ * so that the next registration starts a session instead of answering from
+ * the one the room no longer has.
+ */
+function forgetEndedSession(headers, body) {
+    let sessionId = headers.get(LETAGENTS_AGENT_SESSION_ID_HEADER);
+    let sessionToken = headers.get(LETAGENTS_AGENT_SESSION_TOKEN_HEADER);
+    if ((!sessionId || !sessionToken) && typeof body === "string") {
+        try {
+            const sent = JSON.parse(body);
+            if (typeof sent.agent_session_id === "string")
+                sessionId = sent.agent_session_id;
+            if (typeof sent.agent_session_token === "string")
+                sessionToken = sent.agent_session_token;
+        }
+        catch {
+            // Not a request that names a session.
+        }
+    }
+    if (!sessionId || !sessionToken)
+        return;
+    try {
+        endStoredAgentSession(sessionId, new Date().toISOString(), sessionToken);
+    }
+    catch {
+        // The error the agent is about to see tells it what to do.
+    }
+}
+const BUSY_RETRY_DELAYS_MS = [1_000, 2_000];
+/**
+ * For a request the room may turn away only because it is busy for a moment,
+ * and that changed nothing when it was turned away. The room answers 503 when
+ * another registration is still committing; asking again shortly succeeds.
+ */
+export async function apiCallWhenFree(path, options) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            return await apiCall(path, options);
+        }
+        catch (error) {
+            const delay = BUSY_RETRY_DELAYS_MS[attempt];
+            if (!(error instanceof ApiError) || error.status !== 503 || delay === undefined)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+}
 export async function apiCall(path, options) {
     const headers = new Headers(options?.headers);
     if (!headers.has("Content-Type")) {
@@ -134,6 +183,9 @@ export async function apiCall(path, options) {
             clearStoredAuth();
             clearAuthenticatedAccountCache();
         }
+        if (res.status === 401 && body.includes(AGENT_SESSION_ENDED_ERROR)) {
+            forgetEndedSession(headers, options?.body);
+        }
         throw new ApiError(res.status, body);
     }
     const body = await res.text();

package/dist/mcp/server/runtime/identity/liveness.js

@@ -1,4 +1,5 @@
-import { randomUUID } from "crypto";
+import { createHash, randomUUID } from "crypto";
+import { hostname, userInfo } from "os";
 import { readLocalState, updateLocalState, } from "../../../local-state.js";
 import { detectAgentIdeLabel, detectAgentRuntimeLabel, } from "./config.js";
 import { AGENT_INSTANCE_UUID } from "./state.js";
@@ -16,6 +17,23 @@ function getOrCreateLocalHostId() {
     });
     return readLocalState().local_host_id || hostId;
 }
+/**
+ * Names this machine for the room's same-machine reasoning. The stored host
+ * id alone cannot: it lives in a file, and a file that is copied to another
+ * machine, or shared with one, carries it along. This adds what the machine
+ * says of itself, so two machines never report the same value.
+ */
+export function getProcessHostId() {
+    let user = "";
+    try {
+        user = userInfo().username;
+    }
+    catch {
+        // Some systems have no entry for the current user.
+    }
+    const parts = [getOrCreateLocalHostId(), hostname(), user, process.platform, process.arch];
+    return `phost_${createHash("sha256").update(parts.join("\n")).digest("hex").slice(0, 32)}`;
+}
 export function getSessionLivenessRegistration(runtime = detectAgentRuntimeLabel()) {
     const hostId = getOrCreateLocalHostId();
     const ideLabel = detectAgentIdeLabel();

package/dist/mcp/server/runtime/process-connection.js

@@ -0,0 +1,239 @@
+import { AGENT_PROCESS_CONNECTION_SILENT_AFTER_MS, AGENT_PROCESS_RECONNECT_MAX_DELAY_MS, } from "../../../shared/agent-presence.js";
+import { LETAGENTS_AGENT_SESSION_ID_HEADER, LETAGENTS_AGENT_SESSION_TOKEN_HEADER, } from "../../../shared/request-headers.js";
+import { endStoredAgentSession, getStoredAgentSession } from "../../local-state.js";
+import { encodeRoomIdPath } from "../../room-id.js";
+import { getApiUrl, getLetagentsToken } from "./api.js";
+import { requireValidWorkerBearerRuntime } from "./worker-bearer.js";
+/**
+ * This process holds one connection open per worker session for as long as it
+ * runs. The connection carries nothing: that it is open tells the room this
+ * process exists, which nothing else can. What the agent does cannot, because
+ * an agent that is busy or waiting between room calls looks the same as one
+ * whose process has gone.
+ *
+ * The room uses it for one decision. When another of the owner's agents asks
+ * for a name this session holds, the name passes on only if this process is
+ * gone. So a session that holds its connection open is never mistaken for an
+ * abandoned one.
+ *
+ * Nothing here polls. The connection is opened, and reopened only after it
+ * drops.
+ */
+const RECONNECT_DELAYS_MS = [1_000, 2_000, AGENT_PROCESS_RECONNECT_MAX_DELAY_MS];
+// A server that refuses the connection is asked again, but seldom: it will
+// likely refuse again, and the agent's own room calls speak for it meanwhile.
+const REFUSED_DELAYS_MS = [AGENT_PROCESS_RECONNECT_MAX_DELAY_MS, 15_000, 60_000];
+// A server that does not know the route is asked more seldom still. It may
+// be one of several behind the same address, not all of them yet replaced,
+// or be replaced while this process runs. A process that gave up on the
+// first such answer would offer no evidence for the rest of its life.
+const UNKNOWN_DELAYS_MS = [10_000, 60_000, 5 * 60_000];
+const ANSWER_TIMEOUT_MS = 10_000;
+const EXIT_ANNOUNCEMENT_TIMEOUT_MS = 1_500;
+const held = new Map();
+async function authorization(session) {
+    const token = await getLetagentsToken();
+    return {
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        [LETAGENTS_AGENT_SESSION_ID_HEADER]: session.session_id,
+        [LETAGENTS_AGENT_SESSION_TOKEN_HEADER]: session.session_token,
+    };
+}
+function processUrl(session, suffix = "") {
+    return `${getApiUrl()}/rooms/${encodeRoomIdPath(session.room_id)}/agent-sessions/`
+        + `${encodeURIComponent(session.session_id)}/process${suffix}`;
+}
+function discard(response) {
+    void response.body?.cancel().catch(() => undefined);
+}
+async function holdOnce(session, signal, onOpen) {
+    // One attempt, ended by the caller or by a server that has gone quiet. A
+    // connection can die without either end being told, as when a machine
+    // wakes from sleep; the server writes often enough that silence shows it.
+    const attempt = new AbortController();
+    const abort = () => attempt.abort();
+    signal.addEventListener("abort", abort, { once: true });
+    let quiet;
+    const expectWithin = (ms) => {
+        clearTimeout(quiet);
+        quiet = setTimeout(abort, ms);
+        quiet.unref?.();
+    };
+    try {
+        expectWithin(ANSWER_TIMEOUT_MS);
+        const response = await fetch(processUrl(session), {
+            headers: { Accept: "text/event-stream", ...await authorization(session) },
+            signal: attempt.signal,
+        });
+        if (response.status === 410) {
+            discard(response);
+            return "ended";
+        }
+        // A room server that predates this connection has no such route. That
+        // says nothing about the session.
+        if (response.status === 404 || response.status === 405) {
+            discard(response);
+            return "unsupported";
+        }
+        if (response.status >= 500) {
+            discard(response);
+            return "dropped";
+        }
+        if (!response.ok || !response.body
+            || !(response.headers.get("content-type") ?? "").includes("text/event-stream")) {
+            discard(response);
+            return "refused";
+        }
+        onOpen(null);
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let tail = "";
+        for (;;) {
+            expectWithin(AGENT_PROCESS_CONNECTION_SILENT_AFTER_MS);
+            const { done, value } = await reader.read();
+            if (done)
+                return "dropped";
+            // Only the last few bytes are kept: enough to see either event sent.
+            tail = (tail + decoder.decode(value, { stream: true })).slice(-128);
+            const named = /"connection_id":"([0-9a-f-]{36})"/.exec(tail);
+            if (named)
+                onOpen(named[1]);
+            if (tail.includes("event: ended")) {
+                void reader.cancel().catch(() => undefined);
+                return "ended";
+            }
+        }
+    }
+    finally {
+        clearTimeout(quiet);
+        signal.removeEventListener("abort", abort);
+    }
+}
+function stillOurs(session) {
+    try {
+        const stored = getStoredAgentSession(session.session_id);
+        return Boolean(stored && !stored.ended_at && stored.session_token === session.session_token);
+    }
+    catch {
+        // A worker connection that was replaced reads as an error.
+        return false;
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted)
+            return resolve();
+        const timer = setTimeout(done, ms);
+        // Waiting to reconnect is no reason for this process to stay alive.
+        timer.unref?.();
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+        signal.addEventListener("abort", done, { once: true });
+    });
+}
+async function hold(connection) {
+    const { session, controller } = connection;
+    let drops = 0;
+    let refusals = 0;
+    let unknowns = 0;
+    while (!controller.signal.aborted) {
+        let outcome = "dropped";
+        try {
+            outcome = await holdOnce(session, controller.signal, (connectionId) => {
+                drops = 0;
+                refusals = 0;
+                unknowns = 0;
+                connection.connectionId = connectionId;
+            });
+        }
+        catch {
+            // A dropped network or an aborted request. The loop condition tells them apart.
+        }
+        connection.connectionId = null;
+        if (controller.signal.aborted)
+            return;
+        if (outcome === "ended") {
+            // The room ended this session. Say so locally, so the next
+            // registration starts a session instead of reusing this one.
+            endStoredAgentSession(session.session_id, new Date().toISOString(), session.session_token);
+        }
+        if (outcome === "ended") {
+            if (held.get(session.session_id) === connection)
+                held.delete(session.session_id);
+            return;
+        }
+        if (outcome !== "dropped" && !stillOurs(session)) {
+            // The session was registered again with another credential, by this
+            // process or another. Whoever did that holds its connection now.
+            if (held.get(session.session_id) === connection)
+                held.delete(session.session_id);
+            return;
+        }
+        const [delays, attempt] = outcome === "unsupported" ? [UNKNOWN_DELAYS_MS, unknowns]
+            : outcome === "refused" ? [REFUSED_DELAYS_MS, refusals]
+                : [RECONNECT_DELAYS_MS, drops];
+        await sleep(delays[Math.min(attempt, delays.length - 1)], controller.signal);
+        if (outcome === "unsupported")
+            unknowns += 1;
+        else if (outcome === "refused")
+            refusals += 1;
+        else
+            drops += 1;
+    }
+}
+function holdsCredentials(session) {
+    return Boolean(session
+        && session.session_kind === "worker"
+        && !session.ended_at
+        && session.session_token
+        && !session.session_id.startsWith("local_")
+        && requireValidWorkerBearerRuntime().mode === "owner");
+}
+/** Hold the process connection for a session this process has just registered. */
+export function holdProcessConnection(session) {
+    if (!holdsCredentials(session))
+        return;
+    const current = held.get(session.session_id);
+    if (current?.session.session_token === session.session_token)
+        return;
+    current?.controller.abort();
+    const connection = { session, controller: new AbortController(), connectionId: null };
+    held.set(session.session_id, connection);
+    void hold(connection);
+}
+/** Stop holding it, because this process ended the session itself. */
+export function releaseProcessConnection(sessionId) {
+    held.get(sessionId)?.controller.abort();
+    held.delete(sessionId);
+}
+/**
+ * Tell the room this process is exiting. A connection that merely closes may
+ * reopen, so the room waits before it concludes anything; a process that says
+ * it is leaving spares its successor that wait. Best effort and bounded: an
+ * exit is never held up by a room that does not answer.
+ */
+export async function announceProcessExit() {
+    const connections = [...held.values()];
+    held.clear();
+    if (connections.length === 0)
+        return;
+    const timeout = AbortSignal.timeout(EXIT_ANNOUNCEMENT_TIMEOUT_MS);
+    await Promise.allSettled(connections.map(async ({ session, controller, connectionId }) => {
+        // Closed first, so nothing the room sends in answer is read as news
+        // about the session.
+        controller.abort();
+        await fetch(processUrl(session, "/exit"), {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...await authorization(session) },
+            body: JSON.stringify({
+                agent_session_id: session.session_id,
+                agent_session_token: session.session_token,
+                process_connection_id: connectionId,
+            }),
+            signal: timeout,
+        });
+    }));
+}

package/dist/mcp/server/runtime/worker-bearer.js

@@ -1,6 +1,5 @@
 import { isLocalRoomApi } from "../../../../shared/room-api-origin.mjs";
 import { getDaemonToolExecutionContext } from "./daemon-tool-context.js";
-export const LETAGENTS_AGENT_SESSION_BEARER_ENV = "LETAGENTS_AGENT_SESSION_BEARER";
 export const LETAGENTS_SUPERVISED_BOUNDED_TURNS_ENV = "LETAGENTS_SUPERVISED_BOUNDED_TURNS";
 export class WorkerBearerRuntimeConfigurationError extends Error {
     constructor(message) {
@@ -75,9 +74,6 @@ export function requireValidWorkerBearerRuntime() {
     }
     return runtime;
 }
-export function isSupervisedBoundedTurn() {
-    return hasSupervisedWorkerAuthority() && !isCustodialPolling();
-}
 export function isCustodialPolling() {
     return process.env.LETAGENTS_EXECUTION_PROFILE?.trim() === "supervised_mcp_polling";
 }

package/dist/mcp/server/runtime/worker-handles.js

@@ -1,17 +1,21 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { getLocalStatePath, readLocalStateSnapshot, updateLocalState, } from "../../local-state/storage.js";
 import { isLocalRoomStorageEnabled, resolveLocalRoomStorageIdentifiers } from "../../local-state.js";
-import { assertWorkerConnection, pinWorkerConnection, pinnedWorkerConnection, withWorkerCall } from "../../worker-call-context.js";
+import { assertWorkerConnection, heldWorkerConnection, pinWorkerConnection, pinnedWorkerConnection, withWorkerCall } from "../../worker-call-context.js";
 import { isMcpWorkerId } from "../../../shared/mcp-worker.js";
-import { pickLocalCodename } from "../../../shared/codenames.js";
+import { AGENT_CODENAME_SPACE, pickLocalCodename } from "../../../shared/codenames.js";
 import { buildAgentActorLabel } from "../../../shared/agent-identity.js";
+import { normalizeRoutingHandle, normalizeRoutingSender } from "../../../../shared/routing-aliases.mjs";
 import { encodeRoomIdPath } from "../../room-id.js";
 import { getGitCurrentBranch } from "../../git-remote.js";
-import { apiCall, getApiUrl, getLetagentsToken } from "./api.js";
+import { apiCall, apiCallWhenFree, getApiUrl, getLetagentsToken } from "./api.js";
 import { resolveOwnerContext } from "./identity/directory.js";
 import { detectAgentIdeLabel, detectAgentRuntimeLabel } from "./identity/config.js";
-import { getSessionLivenessRegistration } from "./identity/liveness.js";
+import { getProcessHostId, getSessionLivenessRegistration } from "./identity/liveness.js";
 import { requireValidWorkerBearerRuntime } from "./worker-bearer.js";
+import { holdProcessConnection } from "./process-connection.js";
+// What the room said of the registration just made, kept for its caller.
+const adoptedBySession = new Map();
 const connecting = new Map();
 function snapshot() {
     const result = readLocalStateSnapshot();
@@ -37,16 +41,88 @@ function getWorker(workerId, scope) {
     }
     return worker;
 }
+export function readAdoptedTaskLeases(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        const lease = entry;
+        return lease && typeof lease.lease_id === "string" && typeof lease.task_id === "string"
+            && typeof lease.kind === "string"
+            ? [{ lease_id: lease.lease_id, task_id: lease.task_id, kind: lease.kind }] : [];
+    });
+}
+/**
+ * The workers this process holds in a room under a name.
+ *
+ * A chat that has lost its worker_id registers as if it were new, and asks
+ * for the name it knows itself by. This process still holds the worker it
+ * registered as, so the room sees that name held by an agent that is there,
+ * and gives the chat another. It is then a second agent, under a name it
+ * does not know, with none of its tasks.
+ *
+ * A worker_id is what lets a chat act as a worker, so it is not given to
+ * every chat that asks for a worker's name: two chats served by one process
+ * may ask for the same name, and each is its own worker. A chat is told only
+ * that the name is held here, and how to say that it is the one holding it.
+ */
+function workersThisProcessHoldsUnder(displayName, scope, roomId) {
+    const asked = displayName?.trim();
+    if (!asked)
+        return [];
+    const nameKey = (name) => normalizeRoutingHandle(name) || normalizeRoutingSender(name);
+    const state = snapshot();
+    return Object.values(state.mcp_workers ?? {}).flatMap((worker) => {
+        if (worker.scope !== scope)
+            return [];
+        const sessionId = worker.rooms[roomId]?.session_id;
+        const session = sessionId ? state.agent_sessions?.[sessionId] : undefined;
+        if (!sessionId || !session || session.ended_at)
+            return [];
+        const held = heldWorkerConnection(getLocalStatePath(), sessionId);
+        if (!held || held.session_token !== session.session_token)
+            return [];
+        // The name it lives under, which is the name it knows itself by. A
+        // worker that asked for this name and was given another is not it.
+        if (nameKey(session.display_name) !== nameKey(asked))
+            return [];
+        return [{ worker_id: worker.worker_id, display_name: session.display_name }];
+    });
+}
+/**
+ * A chat says that it registered under this name and has lost its handle. If
+ * this process holds one worker under the name in the room, that is the
+ * worker, and the chat has it back.
+ */
+export async function recoverMcpWorker(input) {
+    const scope = await workerScope();
+    const identifiers = await resolveLocalRoomStorageIdentifiers(input.roomId);
+    const held = workersThisProcessHoldsUnder(input.displayName, scope, identifiers.cloudRoomId || input.roomId);
+    if (held.length === 0) {
+        throw new Error(`This MCP server holds no worker named "${input.displayName.trim()}" in this room, so there is nothing to recover. `
+            + "Register as a new worker with a registration_key.");
+    }
+    if (held.length > 1) {
+        throw new Error(`This MCP server holds more than one worker named "${input.displayName.trim()}" in this room and cannot tell `
+            + "which one this chat is. Register as a new worker with a registration_key.");
+    }
+    return registerMcpWorker({ roomId: input.roomId, workerId: held[0].worker_id, runtime: input.runtime, cwd: input.cwd });
+}
 export async function registerMcpWorker(input) {
     const scope = await workerScope();
     if (input.workerId && input.registrationKey)
         throw new Error("Use worker_id to resume or registration_key to create, not both.");
     let workerId = input.workerId;
+    let nameHeldHere = null;
+    const identifiers = await resolveLocalRoomStorageIdentifiers(input.roomId);
+    const roomId = identifiers.cloudRoomId || input.roomId;
     if (!workerId) {
         if (!input.registrationKey?.trim())
             throw new Error("A new chat must supply its own registration_key and retain the returned worker_id.");
         const keyHash = createHash("sha256").update(`${scope}\n${input.registrationKey}`).digest("hex");
-        snapshot();
+        const known = Object.values(snapshot().mcp_workers ?? {})
+            .some((worker) => worker.scope === scope && worker.registration_key_hash === keyHash);
+        if (!known)
+            nameHeldHere = workersThisProcessHoldsUnder(input.displayName, scope, roomId)[0]?.display_name ?? null;
         updateLocalState((state) => {
             state.mcp_workers ??= {};
             const prior = Object.values(state.mcp_workers).find((w) => w.scope === scope && w.registration_key_hash === keyHash);
@@ -59,8 +135,6 @@ export async function registerMcpWorker(input) {
         });
     }
     const worker = getWorker(workerId, scope);
-    const identifiers = await resolveLocalRoomStorageIdentifiers(input.roomId);
-    const roomId = identifiers.cloudRoomId || input.roomId;
     const local = await isLocalRoomStorageEnabled(input.roomId);
     const key = `${getLocalStatePath()}\n${worker.worker_id}\n${roomId}`;
     const inFlight = connecting.get(key);
@@ -69,7 +143,14 @@ export async function registerMcpWorker(input) {
     const result = connectWorker(input, worker, scope, roomId, local);
     connecting.set(key, result);
     try {
-        return await result;
+        const connection = await result;
+        const adopted = adoptedBySession.get(connection.session.session_id);
+        adoptedBySession.delete(connection.session.session_id);
+        return {
+            ...connection,
+            ...(nameHeldHere ? { name_held_here: nameHeldHere } : {}),
+            ...(adopted?.length ? { adopted_task_leases: adopted } : {}),
+        };
     }
     finally {
         connecting.delete(key);
@@ -80,8 +161,11 @@ async function connectWorker(input, worker, scope, roomId, local) {
     const current = currentId ? snapshot().agent_sessions?.[currentId] : undefined;
     const pinned = currentId ? pinnedWorkerConnection(getLocalStatePath(), currentId) : null;
     if (pinned && current && !current.ended_at && pinned.session_token === current.session_token
-        && !worker.rooms[roomId]?.pending)
+        && !worker.rooms[roomId]?.pending) {
+        if (!local)
+            holdProcessConnection(pinned);
         return { worker, session: pinned };
+    }
     const owner = await resolveOwnerContext();
     if (!local && !owner.login)
         throw new Error("Sign in before registering a worker in a hosted room.");
@@ -114,13 +198,14 @@ async function connectWorker(input, worker, scope, roomId, local) {
             };
         }
         else {
-            const created = await apiCall(`/rooms/${encodeRoomIdPath(roomId)}/agent-sessions`, {
+            const created = await apiCallWhenFree(`/rooms/${encodeRoomIdPath(roomId)}/agent-sessions`, {
                 method: "POST", body: JSON.stringify({
                     actor_key: agent.canonical_key, agent_instance_id: worker.worker_id,
                     display_name: worker.display_name, requested_base_display_name: worker.display_name,
                     session_kind: "worker", runtime: input.runtime || detectAgentRuntimeLabel(), ide_label: ide,
                     repo_branch: getGitCurrentBranch(input.cwd),
                     registration_liveness: getSessionLivenessRegistration(input.runtime || detectAgentRuntimeLabel()),
+                    process_host_id: getProcessHostId(),
                     connection_token: operation.connection_token,
                     replace_agent_session_id: operation.predecessor_id ?? null,
                     replace_agent_session_token: operation.predecessor_token ?? null,
@@ -132,8 +217,11 @@ async function connectWorker(input, worker, scope, roomId, local) {
                 throw new Error("The server did not confirm this worker connection. Upgrade the API before using durable worker handles.");
             }
             // Keep only the session credential; the server's optional bearer is not used here.
-            const { assigned_base_display_name, worker_bearer: _unusedBearer, ...record } = created;
+            const { assigned_base_display_name, worker_bearer: _unusedBearer, adopted_task_leases, ...record } = created;
             session = { ...record, requested_base_display_name: assigned_base_display_name ?? worker.display_name };
+            const adopted = readAdoptedTaskLeases(adopted_task_leases);
+            if (adopted.length > 0)
+                adoptedBySession.set(session.session_id, adopted);
         }
         updateLocalState((state) => {
             const target = state.mcp_workers?.[worker.worker_id]?.rooms[roomId];
@@ -141,12 +229,16 @@ async function connectWorker(input, worker, scope, roomId, local) {
                 throw new Error("Worker registration was superseded; retry explicitly.");
             state.agent_sessions ??= {};
             if (local && !target.session_id) {
+                // Mirror the hosted allocator: names are compared the way mentions
+                // are, and a held name receives its own codename, never a numbered
+                // variant that cannot be mentioned as typed.
+                const nameKey = (name) => normalizeRoutingHandle(name) || normalizeRoutingSender(name);
                 const used = new Set(Object.values(state.agent_sessions)
                     .filter((other) => other.room_id === roomId && other.session_id !== session.session_id)
-                    .map((other) => other.display_name));
-                let suffix = 1;
-                while (used.has(session.display_name))
-                    session.display_name = `${worker.display_name} ${suffix++}`;
+                    .map((other) => nameKey(other.display_name)));
+                for (let offset = 1; used.has(nameKey(session.display_name)) && offset <= AGENT_CODENAME_SPACE; offset += 1) {
+                    session.display_name = pickLocalCodename(`${agent.canonical_key}:${offset}`).display_name;
+                }
                 session.actor_label = buildAgentActorLabel({ display_name: session.display_name, owner_label: owner.label, ide_label: ide });
             }
             state.agent_sessions[session.session_id] = session;
@@ -174,6 +266,8 @@ async function connectWorker(input, worker, scope, roomId, local) {
     });
     const session = await finish(operation);
     pinWorkerConnection(getLocalStatePath(), session);
+    if (!local)
+        holdProcessConnection(session);
     return { worker: getWorker(worker.worker_id, scope), session };
 }
 export async function runMcpWorkerCall(workerId, roomId, callback, allowEnded = false) {

package/dist/mcp/server/runtime-contract.js

@@ -1,5 +1,6 @@
 import { registerTools } from "./register-tools.js";
 export const LETAGENTS_RUNTIME_CONTRACT_ARG = "--letagents-runtime-contract";
+export const LETAGENTS_RUNTIME_READINESS_URI = "letagents://runtime/readiness";
 /**
  * Discover through the production registration path rather than maintaining a
  * second capability list that can drift from the MCP server.
@@ -15,6 +16,16 @@ export function registeredToolNames(profile, supervisedProvider = null, apiUrl =
     registerTools(recorder, profile, supervisedProvider, { apiUrl });
     return [...names].sort();
 }
+/** Public capability metadata only; reading it grants no room or tool authority. */
+export function registerRuntimeReadinessResource(server, profile, supervisedProvider, apiUrl = process.env.LETAGENTS_API_URL) {
+    const text = JSON.stringify({
+        format: 1, profile, provider: supervisedProvider,
+        tools: registeredToolNames(profile, supervisedProvider, apiUrl),
+    });
+    server.resource("runtime_readiness", LETAGENTS_RUNTIME_READINESS_URI, { mimeType: "application/json" }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: "application/json", text }],
+    }));
+}
 export function letAgentsRuntimeContract(apiUrl = process.env.LETAGENTS_API_URL) {
     return {
         format: 1,

package/dist/mcp/server/runtime.js

@@ -22,4 +22,4 @@ export { getRememberedRoomPresence, heartbeatRoomPresence, syncRoomPresence, } f
 export { roomScopedApiCall } from "./runtime/room-api.js";
 export { borrowSupervisedWorkerCredential, borrowCurrentSupervisedWorkerCredential, bindSupervisedWorkerSession, checkpointSupervisedWorkerCursor, isRetryableSupervisorBridgeError, scheduleSupervisedWorkerCursorCheckpoint, resolveCurrentSupervisedWorkerSession, } from "./runtime/supervisor-bridge.js";
 export { autoJoinFromContext, buildJoinResponse, createInviteRoom, getCurrentLiveSessionPayload, joinInviteCode, joinNamedRoom, joinRoomIdentifier, joinRoomIdentifierWithoutImplicitGitRefCreate, normalizeJoinSessionMode, } from "./runtime/rooms.js";
-export { clearPendingDeviceAuth, clearStoredAuth, clearStoredAuth as clearStoredAuthorization, endStoredAgentSession, getCurrentAgentSession, getLocalStatePath, getPendingDeviceAuth, getStoredAgentIdentity, getStoredAgentSession, getCurrentAgentSessionSnapshot, getStoredAgentSessionsForRoomIdentity, getStoredActiveAgentSessionsForRoom, getStoredAgentRoutingStateSnapshot, getStoredAuth, getStoredCurrentRoom, getStoredRoomSession, listStoredCodexLiveSessions, saveAgentSession, setPendingDeviceAuth, setStoredAuth, setStoredAgentIdentity, addLocalChatMessage, addLocalTask, claimLocalTaskReviewLease, getLatestLocalChatMessages, getLocalImportedRoutingAuthority, getLocalChatMessages, getLocalChatThreadRoutingMembership, getLocalTask, listLocalActiveTaskOwnerLeases, listLocalTasks, isLocalChatStorageEnabled, resolveLocalRoomStorageIdentifiers, releaseLocalTaskReviewLease, updateLocalTask, waitForLocalChatMessages, } from "../local-state.js";
+export { clearPendingDeviceAuth, clearStoredAuth, endStoredAgentSession, getCurrentAgentSession, getLocalStatePath, getPendingDeviceAuth, getStoredAgentIdentity, getStoredAgentSession, getCurrentAgentSessionSnapshot, getStoredAgentSessionsForRoomIdentity, getStoredActiveAgentSessionsForRoom, getStoredAgentRoutingStateSnapshot, getStoredAuth, getStoredCurrentRoom, getStoredRoomSession, listStoredCodexLiveSessions, saveAgentSession, setPendingDeviceAuth, setStoredAuth, setStoredAgentIdentity, addLocalChatMessage, addLocalTask, claimLocalTaskReviewLease, getLatestLocalChatMessages, getLocalImportedRoutingAuthority, getLocalChatMessages, getLocalChatThreadRoutingMembership, getLocalTask, listLocalActiveTaskOwnerLeases, listLocalTasks, isLocalChatStorageEnabled, resolveLocalRoomStorageIdentifiers, releaseLocalTaskReviewLease, updateLocalTask, waitForLocalChatMessages, } from "../local-state.js";

package/dist/mcp/server/supervised-tool-facade.js

@@ -9,7 +9,7 @@ const READ_TOOLS = new Set([
     "wait_for_messages",
     "get_board",
     "get_board_settings",
-    "get_room_memory", "get_human_requests",
+    "get_room_memory", "get_human_requests", "get_room_guidelines",
     "get_room_artifacts",
     "get_room_events",
     "list_board_intents",