letagents 0.12.13 → 0.12.15

package/README.md

@@ -84,6 +84,36 @@ 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
+- durable MCP worker handles and their private connection credentials
+
+Each independent chat registers once with its own random `registration_key`:
+
+```text
+register_agent_session(room_id="room_example", registration_key="<random UUID for this chat>", display_name="Juniper")
+→ worker_id="worker_..."
+send_message(worker_id="worker_...", room_id="room_example", text="Working on the task")
+```
+
+Keep that `worker_id` with the chat. After the MCP process restarts, reconnect
+with `register_agent_session(worker_id="worker_...", room_id="room_example")`.
+The worker keeps its routing identity, assigned room name, and session row;
+its private connection credential rotates and the previous connection stops
+working. Retry an uncertain first registration with the same `registration_key`.
+Never share a key between chats or derive it from a name, room, or repository.
+
+Room tools accept the handle so a shared MCP process can serve multiple chats
+without selecting a global current worker. Pass `room_id` when a worker belongs
+to multiple rooms. `disconnect_agent_session(worker_id="worker_...", room_id="...")`
+ends its connection; the same handle can reconnect later. Distinct workers may
+receive different name suffixes, but reconnecting does not allocate a new name.
+Choose the name on first registration; `set_agent_name` changes only the legacy
+process identity. Hosted rooms require an API version supporting worker handles.
+
+The handle is a reference, not a credential. Keep the local state file private
+and retain it across restarts. If the handle or its saved credentials are lost,
+restore them explicitly; MCP never guesses another chat's identity. Existing
+integrations using `agent_session_id` and supervisor-managed workers keep their
+existing registration flow. The MCP server still runs locally through `npx`.
 
 ## MCP Tools
 
@@ -93,6 +123,8 @@ 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 |
+| `register_agent_session` | Create a chat's durable worker handle or explicitly reconnect it |
+| `disconnect_agent_session` | End a worker connection while retaining its handle for reconnects |
 | `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` |

package/dist/mcp/local-state/agent-sessions.js

@@ -1,10 +1,21 @@
-import { readLocalState, readLocalStateSnapshot, updateLocalState } from "./storage.js";
+import { getLocalStatePath, readLocalState, readLocalStateSnapshot, updateLocalState } from "./storage.js";
+import { isMcpWorkerId } from "../../shared/mcp-worker.js";
+import { pinnedWorkerConnection } from "../worker-call-context.js";
 export function getStoredAgentSession(sessionId) {
     if (!sessionId) {
         return null;
     }
     const state = readLocalState();
-    return state.agent_sessions?.[sessionId] ?? null;
+    const stored = state.agent_sessions?.[sessionId] ?? null;
+    if (stored && isMcpWorkerId(stored.agent_instance_id)) {
+        // A replaced process must never borrow its successor's credential from disk.
+        const pinned = pinnedWorkerConnection(getLocalStatePath(), sessionId);
+        if (!pinned || stored.session_token !== pinned.session_token) {
+            throw new Error("This worker connection was replaced. Reconnect explicitly with its worker_id.");
+        }
+        return { ...pinned, ended_at: stored.ended_at };
+    }
+    return stored;
 }
 export function getCurrentAgentSession(roomId) {
     return getCurrentAgentSessionSnapshot(roomId).session;
@@ -111,13 +122,17 @@ export function replaceLocalWorkerAgentSession(session) {
     });
     return session;
 }
-export function endStoredAgentSession(sessionId, endedAt = new Date().toISOString()) {
+export function endStoredAgentSession(sessionId, endedAt = new Date().toISOString(), expectedConnectionToken) {
     let endedSession = null;
     updateLocalState((state) => {
         const session = state.agent_sessions?.[sessionId];
         if (!session) {
             return state;
         }
+        if (isMcpWorkerId(session.agent_instance_id)
+            && expectedConnectionToken !== session.session_token) {
+            return state;
+        }
         endedSession = {
             ...session,
             ended_at: endedAt,

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

@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
 import { mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { withWorkerStateFence } from "../worker-call-context.js";
 import { ensureLocalThreadRoutingProjectionSchemaAsync, getLocalThreadRoutingAgentKeysForRoots, projectLocalThreadRoutingMessage, runLocalSqliteWriteTransactionAsync, scheduleLocalThreadRoutingBackfill, } from "../../../shared/sqlite-thread-routing.mjs";
 import { MESSAGE_SENDER_MAX_CODE_POINTS, MESSAGE_SENDER_MAX_UTF8_BYTES, POSTGRES_INTEGER_MAX, isMessageSenderWithinBounds, parseAccountAgentRoutingEnvelope, parsePositivePgIntegerScopedId, } from "../../../shared/message-contracts.mjs";
 const localImportedRoutingAuthority = Symbol("localImportedRoutingAuthority");
@@ -367,17 +368,6 @@ async function hydrateRows(database, rows) {
     }
     return rows.map((row) => toMessage(row, row.reply_to_number ? replies.get(row.reply_to_number) ?? null : null, attachmentsByMessageNumber.get(row.number) || []));
 }
-function beginImmediate(database) {
-    database.exec("BEGIN IMMEDIATE");
-}
-function rollback(database) {
-    try {
-        database.exec("ROLLBACK");
-    }
-    catch {
-        // The transaction may already be closed by SQLite after an error.
-    }
-}
 function allocateLocalMessageNumber(database, roomId) {
     database
         .prepare(`
@@ -537,7 +527,7 @@ export async function addLocalChatMessage(roomId, input) {
         }
     }
     const timestamp = new Date().toISOString();
-    const row = await runLocalSqliteWriteTransactionAsync(database, () => {
+    const row = await runLocalSqliteWriteTransactionAsync(database, () => withWorkerStateFence(() => {
         const number = allocateLocalMessageNumber(database, trimmedRoomId);
         const insertedRow = {
             room_id: trimmedRoomId,
@@ -570,7 +560,7 @@ export async function addLocalChatMessage(roomId, input) {
             .run(insertedRow.room_id, insertedRow.number, insertedRow.reply_to_number, insertedRow.thread_root_number, insertedRow.sender, insertedRow.text, insertedRow.agent_prompt_kind, insertedRow.source, insertedRow.publisher_agent_key, insertedRow.publisher_agent_session_id, insertedRow.timestamp);
         projectLocalThreadRoutingMessage(database, insertedRow);
         return insertedRow;
-    });
+    }));
     return {
         room_id: trimmedRoomId,
         ...toMessage(row, replyTarget),
@@ -731,8 +721,7 @@ export async function addLocalTask(roomId, input) {
     const database = await getDb();
     const now = new Date().toISOString();
     let taskId = "";
-    beginImmediate(database);
-    try {
+    await runLocalSqliteWriteTransactionAsync(database, () => withWorkerStateFence(() => {
         taskId = allocateLocalTaskId(database, trimmedRoomId);
         database
             .prepare(`
@@ -745,12 +734,7 @@ export async function addLocalTask(roomId, input) {
         VALUES (?, ?, ?, ?, 'proposed', NULL, NULL, NULL, NULL, ?, NULL, NULL, NULL, NULL, ?, NULL, 1, ?, ?)
       `)
             .run(trimmedRoomId, taskId, title, input.description?.trim() || null, input.created_by || "agent", `local-task:${trimmedRoomId}:${taskId}`, now, now);
-        database.exec("COMMIT");
-    }
-    catch (error) {
-        rollback(database);
-        throw error;
-    }
+    }));
     const task = await getLocalTask(trimmedRoomId, taskId);
     if (!task)
         throw new Error("Local task could not be created.");
@@ -856,7 +840,7 @@ export async function updateLocalTask(roomId, taskId, patch) {
         : JSON.stringify(Array.isArray(patch.workflow_artifacts) ? patch.workflow_artifacts : []);
     const now = new Date().toISOString();
     const database = await getDb();
-    database
+    await runLocalSqliteWriteTransactionAsync(database, () => withWorkerStateFence(() => database
         .prepare(`
       UPDATE local_tasks
       SET status = ?,
@@ -870,7 +854,7 @@ export async function updateLocalTask(roomId, taskId, patch) {
           updated_at = ?
       WHERE room_id = ? AND task_id = ?
     `)
-        .run(nextStatus, patch.assignee === undefined ? current.assignee : patch.assignee || null, assigneeAgentKey, assigneeAgentInstanceId, assigneeAgentSessionId, patch.pr_url === undefined ? current.pr_url : patch.pr_url || null, workflowArtifacts, now, roomId, taskId);
+        .run(nextStatus, patch.assignee === undefined ? current.assignee : patch.assignee || null, assigneeAgentKey, assigneeAgentInstanceId, assigneeAgentSessionId, patch.pr_url === undefined ? current.pr_url : patch.pr_url || null, workflowArtifacts, now, roomId, taskId)));
     const updated = await getLocalTask(roomId, taskId);
     if (!updated)
         throw new Error("Task not found.");
@@ -895,7 +879,7 @@ export async function claimLocalTaskReviewLease(roomId, taskId, input) {
     const database = await getDb();
     const now = new Date().toISOString();
     const leaseId = currentReviewLease?.id || `local_review_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-    database
+    await runLocalSqliteWriteTransactionAsync(database, () => withWorkerStateFence(() => database
         .prepare(`
       UPDATE local_tasks
       SET review_lease_id = ?,
@@ -906,7 +890,7 @@ export async function claimLocalTaskReviewLease(roomId, taskId, input) {
           updated_at = ?
       WHERE room_id = ? AND task_id = ?
     `)
-        .run(leaseId, input.holder_label?.trim() || actorKey || "Local reviewer", actorKey, input.agent_session_id?.trim() || null, now, now, roomId, taskId);
+        .run(leaseId, input.holder_label?.trim() || actorKey || "Local reviewer", actorKey, input.agent_session_id?.trim() || null, now, now, roomId, taskId)));
     const task = await getLocalTask(roomId, taskId);
     const lease = task?.active_leases?.find((entry) => entry.id === leaseId);
     if (!task || !lease)
@@ -925,7 +909,7 @@ export async function releaseLocalTaskReviewLease(roomId, taskId, input = {}) {
     }
     const database = await getDb();
     const now = new Date().toISOString();
-    database
+    await runLocalSqliteWriteTransactionAsync(database, () => withWorkerStateFence(() => database
         .prepare(`
       UPDATE local_tasks
       SET review_lease_id = NULL,
@@ -936,7 +920,7 @@ export async function releaseLocalTaskReviewLease(roomId, taskId, input = {}) {
           updated_at = ?
       WHERE room_id = ? AND task_id = ?
     `)
-        .run(now, roomId, taskId);
+        .run(now, roomId, taskId)));
     const task = await getLocalTask(roomId, taskId);
     if (!task)
         throw new Error("Task not found.");

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

@@ -33,6 +33,10 @@ export function readLocalStateSnapshot() {
 export function readLocalState() {
     return readLocalStateSnapshot().state;
 }
+/** Hold the existing state lock through a short synchronous local effect. */
+export function withLocalStateReadLock(callback) {
+    return withStateLock((statePath) => callback(readLocalStateSnapshotFromPath(statePath)));
+}
 function sleepSync(ms) {
     if (ms > 0) {
         Atomics.wait(STATE_LOCK_SLEEP_BUFFER, 0, 0, ms);
@@ -41,7 +45,7 @@ function sleepSync(ms) {
 function writeLocalStateUnlocked(statePath, state) {
     const tempPath = `${statePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
     try {
-        writeFileSync(tempPath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+        writeFileSync(tempPath, JSON.stringify(state, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
         renameSync(tempPath, statePath);
     }
     finally {

package/dist/mcp/server/register-tools.js

@@ -7,10 +7,13 @@ import { registerTaskTools } from "./tools/tasks.js";
 import { registerSupervisedRoomTurnTools } from "./tools/supervised-room-turn.js";
 import { toolSurfaceForExecutionProfile } from "./runtime/tool-surface-policy.js";
 import { profileAwareToolServer } from "./supervised-tool-facade.js";
+import { workerAwareToolServer } from "./worker-tool-facade.js";
 export function registerTools(server, profile = "autonomous_mcp_worker", supervisedProvider = process.env.LETAGENTS_SUPERVISOR_PROVIDER?.trim() || null, options = {}) {
-    const tools = options.executionOwner === "daemon"
+    const profileTools = options.executionOwner === "daemon"
         ? server
         : profileAwareToolServer(server, profile, undefined, supervisedProvider);
+    const tools = profile === "autonomous_mcp_worker" || profile === "interactive_desktop"
+        ? workerAwareToolServer(profileTools) : profileTools;
     const surface = toolSurfaceForExecutionProfile(profile);
     registerRoomJoinTools(tools);
     if (surface.agentSessionLifecycle)

package/dist/mcp/server/runtime/agent-sessions.js

@@ -5,7 +5,7 @@ import { normalizeAgentBaseName } from "../../../shared/codenames.js";
 import { formatOwnerAttribution } from "../../../shared/agent-identity.js";
 import { LETAGENTS_AGENT_SESSION_ID_HEADER, LETAGENTS_AGENT_SESSION_TOKEN_HEADER, } from "../../../shared/request-headers.js";
 import { AGENT_INSTANCE_UUID, detectAgentIdeLabel, detectAgentRuntimeLabel, ensureAgentIdentity, } from "./identity.js";
-import { isSupervisedBoundedTurn, requireValidWorkerBearerRuntime } from "./worker-bearer.js";
+import { hasSupervisedWorkerAuthority, requireValidWorkerBearerRuntime } from "./worker-bearer.js";
 import { resolveCurrentSupervisedWorkerSession } from "./supervisor-bridge.js";
 import { getDaemonToolExecutionContext, getRuntimeWorkingDirectory } from "./daemon-tool-context.js";
 // A worker bearer already represents a server-side worker session. This local
@@ -166,7 +166,7 @@ export async function resolveWorkerToolIdentity(input) {
     }
     const agentSession = input.agentSessionId
         ? requireWorkerAgentSession(input.roomId, input.agentSessionId)
-        : input.roomId && !isSupervisedBoundedTurn() && await isLocalRoomStorageEnabled(input.roomId)
+        : input.roomId && !hasSupervisedWorkerAuthority() && await isLocalRoomStorageEnabled(input.roomId)
             ? await ensureLocalWorkerAgentSession(input.roomId)
             : requireWorkerAgentSession(input.roomId, input.agentSessionId);
     return {

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

@@ -1,4 +1,6 @@
 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 { getDaemonToolExecutionContext } from "./daemon-tool-context.js";
 import { requireValidWorkerBearerRuntime } from "./worker-bearer.js";
 import { borrowCurrentSupervisedWorkerCredential, } from "./supervisor-bridge.js";
@@ -123,7 +125,9 @@ export async function apiCall(path, options) {
     });
     if (!res.ok) {
         const body = await res.text();
-        if (res.status === 401 && requireValidWorkerBearerRuntime().mode === "owner") {
+        const hasWorkerCredential = currentWorkerCall() || headers.has(LETAGENTS_AGENT_SESSION_TOKEN_HEADER)
+            || (typeof options?.body === "string" && /"(?:agent_session_token|replace_agent_session_token|connection_token)"\s*:/.test(options.body));
+        if (res.status === 401 && requireValidWorkerBearerRuntime().mode === "owner" && !hasWorkerCredential) {
             // Only clear on 401 (invalid/expired credential), NOT on 403
             // (valid credential but insufficient permissions, e.g., private repo access)
             const { clearStoredAuth } = await ownerAuthStoreLoader();

package/dist/mcp/server/runtime/execution-profile.js

@@ -1,5 +1,6 @@
 export const EXECUTION_PROFILES = [
     "supervised_room_turn",
+    "supervised_mcp_polling",
     "autonomous_mcp_worker",
     "interactive_desktop",
 ];

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

@@ -1,6 +1,8 @@
 import { buildAgentActorLabel, formatOwnerAttribution, } from "../../../shared/agent-identity.js";
 import { apiCall, getLetagentsToken, } from "./api.js";
 import { requireValidWorkerBearerRuntime } from "./worker-bearer.js";
+import { currentWorkerCall } from "../../worker-call-context.js";
+import { identityFromAgentSession } from "./agent-sessions.js";
 import { detectAgentIdeLabel, detectAgentRuntimeLabel, } from "./identity/config.js";
 import { resolveOwnerContext } from "./identity/directory.js";
 import { getSessionLivenessRegistration } from "./identity/liveness.js";
@@ -9,6 +11,9 @@ import { toPublicAgentIdentity } from "./identity/public.js";
 import { currentAgentIdentity, currentAgentIdentityKey, ensureAgentIdentityKey, getConversationIdentity, setConversationIdentity, storeCurrentAgentIdentity, AGENT_INSTANCE_UUID, } from "./identity/state.js";
 export { AGENT_INSTANCE_UUID, currentAgentIdentity, currentAgentIdentityKey, detectAgentIdeLabel, detectAgentRuntimeLabel, getConversationIdentity, getSessionLivenessRegistration, resolveOwnerContext, setConversationIdentity, storeCurrentAgentIdentity, toPublicAgentIdentity, };
 export async function ensureAgentIdentity() {
+    const worker = currentWorkerCall();
+    if (worker)
+        return identityFromAgentSession(worker);
     const owner = await resolveOwnerContext();
     const authAvailable = requireValidWorkerBearerRuntime().mode === "owner" && Boolean(await getLetagentsToken());
     const ideLabel = detectAgentIdeLabel();

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

@@ -4,7 +4,7 @@ import { isLocalRoomStorageEnabled, resolveLocalRoomStorageIdentifiers, touchRoo
 import { apiCall, isMissingRouteError } from "./api.js";
 import { agentSessionCredentials, identityFromAgentSession } from "./agent-sessions.js";
 import { getSessionLivenessRegistration } from "./identity.js";
-import { isSupervisedBoundedTurn } from "./worker-bearer.js";
+import { hasSupervisedWorkerAuthority } from "./worker-bearer.js";
 const roomPresenceByIdentity = new Map();
 export function getRememberedRoomPresence(roomId, identity) {
     if (!roomId || !identity) {
@@ -19,7 +19,7 @@ export async function syncRoomPresence(roomId, identity, presence, agentSession)
     }
     roomPresenceByIdentity.set(getRoomIdentityPresenceCacheKey(roomId, resolvedIdentity.actor_label), presence);
     const { localRoomId, cloudRoomId } = await resolveLocalRoomStorageIdentifiers(roomId);
-    if (!isSupervisedBoundedTurn() && await isLocalRoomStorageEnabled(roomId)) {
+    if (!hasSupervisedWorkerAuthority() && await isLocalRoomStorageEnabled(roomId)) {
         touchRoomSession(localRoomId || roomId);
         return;
     }
@@ -39,7 +39,7 @@ export async function syncRoomPresence(roomId, identity, presence, agentSession)
                 ...agentSessionCredentials(agentSession),
             }),
         });
-        if (!isSupervisedBoundedTurn())
+        if (!hasSupervisedWorkerAuthority())
             touchRoomSession(apiRoomId);
     }
     catch (error) {

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

@@ -4,9 +4,10 @@ import { apiCall, isMissingRouteError, } from "./api.js";
 import { maybeHandleRepoRoomAuthRequired } from "./device-auth.js";
 import { getLastMessageId } from "./messages.js";
 import { currentRoom, getCurrentSupervisedRoomAuthority } from "./room-state.js";
-import { isSupervisedBoundedTurn } from "./worker-bearer.js";
+import { hasSupervisedWorkerAuthority } from "./worker-bearer.js";
+import { currentWorkerCall } from "../../worker-call-context.js";
 export async function roomScopedApiCall(input) {
-    const supervised = isSupervisedBoundedTurn();
+    const supervised = hasSupervisedWorkerAuthority();
     const exactRoomAuthority = supervised ? getCurrentSupervisedRoomAuthority() : null;
     if (supervised && (!exactRoomAuthority || input.room_id !== exactRoomAuthority)) {
         throw new Error("The daemon-supervised API request is missing its exact per-call room authority.");
@@ -20,8 +21,8 @@ export async function roomScopedApiCall(input) {
             delete headers[originHeaderKey];
         headers[LETAGENTS_ORIGIN_ROOM_ID_HEADER] = exactRoomAuthority;
     }
-    else if (currentRoom?.room_id && !originHeaderKey) {
-        headers[LETAGENTS_ORIGIN_ROOM_ID_HEADER] = currentRoom.room_id;
+    else if ((currentWorkerCall()?.room_id || currentRoom?.room_id) && !originHeaderKey) {
+        headers[LETAGENTS_ORIGIN_ROOM_ID_HEADER] = currentWorkerCall()?.room_id ?? currentRoom.room_id;
     }
     const options = {
         ...input.options,

package/dist/mcp/server/runtime/room-state.js

@@ -3,7 +3,7 @@ import { getStoredAgentIdentity, saveRoomSession, touchRoomSession, } from "../.
 import { getCanonicalRoomWebPath, } from "../../room-id.js";
 import { getApiUrl, getLetagentsToken } from "./api.js";
 import { AGENT_INSTANCE_UUID, currentAgentIdentity, currentAgentIdentityKey, } from "./identity.js";
-import { isSupervisedBoundedTurn } from "./worker-bearer.js";
+import { hasSupervisedWorkerAuthority } from "./worker-bearer.js";
 import { getCurrentSupervisedRoomAuthority, runWithSupervisedRoomAuthority, } from "./supervised-room-authority.js";
 let mcpServer = null;
 let sseClient = null;
@@ -92,7 +92,7 @@ export function toPublicRoomResponse(response, fallbackRoomId) {
 }
 export function rememberRoom(state, lastMessageId) {
     currentRoom = state;
-    if (isSupervisedBoundedTurn())
+    if (hasSupervisedWorkerAuthority())
         return state;
     saveRoomSession({
         room_id: state.room_id,
@@ -123,7 +123,7 @@ export function rememberRoom(state, lastMessageId) {
     return state;
 }
 export function touchCurrentRoom(lastMessageId) {
-    if (isSupervisedBoundedTurn())
+    if (hasSupervisedWorkerAuthority())
         return;
     if (!currentRoom) {
         return;
@@ -131,7 +131,7 @@ export function touchCurrentRoom(lastMessageId) {
     touchRoomSession(currentRoom.room_id, lastMessageId);
 }
 export function getTargetRoomId(roomId) {
-    if (isSupervisedBoundedTurn()) {
+    if (hasSupervisedWorkerAuthority()) {
         const exactRoomAuthority = getCurrentSupervisedRoomAuthority();
         if (!exactRoomAuthority) {
             throw new Error("The daemon-supervised tool has not received its exact room authority.");
@@ -162,7 +162,7 @@ export function toPublicCurrentRoomState() {
  * repository inspection and can safely rebind after a durable room move.
  */
 export function runWithCurrentSupervisedRoom(roomId, callback) {
-    if (!isSupervisedBoundedTurn()) {
+    if (!hasSupervisedWorkerAuthority()) {
         throw new Error("Only a daemon-supervised bounded turn can bind supervisor room authority.");
     }
     const normalized = roomId.trim();
@@ -172,7 +172,7 @@ export function runWithCurrentSupervisedRoom(roomId, callback) {
     return runWithSupervisedRoomAuthority(normalized, callback);
 }
 export function getFallbackProjectId() {
-    if (isSupervisedBoundedTurn())
+    if (hasSupervisedWorkerAuthority())
         return null;
     return currentRoom?.project_id ?? null;
 }

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

@@ -9,7 +9,7 @@ import { ensureAgentIdentity, toPublicAgentIdentity, withAgentIdentity, } from "
 import { withJoinRoomAgentPrompt } from "./messages.js";
 import { syncRoomPresence } from "./presence.js";
 import { rememberRoom, toPublicRoomResponse, toRoomState, } from "./room-state.js";
-import { isSupervisedBoundedTurn, requireValidWorkerBearerRuntime } from "./worker-bearer.js";
+import { hasSupervisedWorkerAuthority, requireValidWorkerBearerRuntime } from "./worker-bearer.js";
 export function normalizeJoinSessionMode(value) {
     return String(value || "").trim().toLowerCase() === "live" ? "live" : "current";
 }
@@ -30,7 +30,7 @@ function parseGeneratedGitRefRoomIdentifier(identifier) {
     };
 }
 export async function joinRoomIdentifier(identifier, joinedVia, options = {}) {
-    if (isSupervisedBoundedTurn()) {
+    if (hasSupervisedWorkerAuthority()) {
         throw new Error("Room joins and creation are disabled during a daemon-supervised bounded turn.");
     }
     const roomId = joinedVia === "join_code" ? normalizeInviteCode(identifier) : identifier.trim();
@@ -191,7 +191,7 @@ export async function joinRoomIdentifierWithoutImplicitGitRefCreate(identifier,
     }));
 }
 export async function createInviteRoom() {
-    if (isSupervisedBoundedTurn()) {
+    if (hasSupervisedWorkerAuthority()) {
         throw new Error("Room joins and creation are disabled during a daemon-supervised bounded turn.");
     }
     const project = await apiCall("/projects", { method: "POST" });

package/dist/mcp/server/runtime/supervisor-bridge.js

@@ -6,12 +6,86 @@ import { join } from "node:path";
 import { parsePositivePgIntegerScopedId } from "../../../../shared/message-contracts.mjs";
 import { getCurrentSupervisedRoomAuthority } from "./supervised-room-authority.js";
 const NEGOTIATION_PROTOCOL_VERSION = 1;
-const SUPPORTED_SUPERVISOR_PROTOCOL_VERSIONS = new Set([1, 2]);
+const SUPPORTED_SUPERVISOR_PROTOCOL_VERSIONS = new Set([1, 2, 3]);
 const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
 const CONFIRMED_BINDING_VERIFY_TIMEOUT_MS = 250;
 const SUPERVISOR_CONTEXT_FILE = ".letagents-supervisor-context.json";
 const WORK_ATTEMPT_MARKER_FILE = ".letagents-work-attempt.json";
 const MAX_SUPERVISOR_CONTEXT_BYTES = 4 * 1024;
+// An SDK request id is unique only within this MCP process lifetime.
+const CUSTODIAL_POLLING_PROCESS_INCARNATION_ID = randomUUID();
+/** Release reuses BEFORE's exact generation; it never authorizes against a successor. */
+export async function authorizeCustodialPolling(toolName, prior, env = process.env, options = {}, waitRequest) {
+    const wait = waitRequest ? { ...waitRequest } : undefined;
+    if (toolName === "wait_for_messages") {
+        if (!wait || !(typeof wait.mcpRequestId === "string" || Number.isSafeInteger(wait.mcpRequestId))) {
+            throw new Error("Custodial wait is missing its exact MCP request id.");
+        }
+        if (!(wait.roomCursor === null || (typeof wait.roomCursor === "string" && parseRoomMessageNumber(wait.roomCursor) !== null))
+            || (prior && (!prior.wait || prior.wait.processIncarnationId !== CUSTODIAL_POLLING_PROCESS_INCARNATION_ID
+                || prior.wait.mcpRequestId !== wait.mcpRequestId || typeof wait.offeredFrontier !== "string"
+                || parseRoomMessageNumber(wait.offeredFrontier) === null || prior.roomCursor === null
+                || parseRoomMessageNumber(wait.offeredFrontier) < parseRoomMessageNumber(prior.roomCursor)))) {
+            throw new Error("Custodial wait receipt does not match its original invocation and cursor.");
+        }
+    }
+    else if (wait || prior?.wait)
+        throw new Error("Only custodial wait may acknowledge or offer a cursor.");
+    if (env.LETAGENTS_EXECUTION_PROFILE?.trim() !== "supervised_mcp_polling")
+        throw new Error("Custodial polling profile required.");
+    if (env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() === "1"
+        || env.LETAGENTS_TOKEN?.trim() || env.LETAGENTS_AGENT_SESSION_BEARER?.trim()) {
+        throw new Error("Custodial polling refuses bounded flags and environment credentials.");
+    }
+    const coordinates = prior?.coordinates ?? await resolveSupervisorCoordinates(supervisedContextSession(env), env, options);
+    if (!coordinates?.roomId || !coordinates.agentSessionId)
+        throw new Error("Custodial polling lacks exact worker coordinates.");
+    if ((wait?.requestedRoomId && wait.requestedRoomId !== coordinates.roomId)
+        || (wait?.requestedAgentSessionId && wait.requestedAgentSessionId !== coordinates.agentSessionId)) {
+        throw new Error("Custodial wait room or worker identity does not match its exact authority.");
+    }
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const negotiated = prior?.negotiated ?? await negotiateSupervisor(coordinates.socketPath, timeoutMs);
+    if (!negotiated.custodialPollingV1 || negotiated.generation === null)
+        throw new Error("Daemon does not support custodial_polling_v1.");
+    if (wait && !negotiated.custodialPollingOffersV1)
+        throw new Error("Daemon does not support custodialPollingOffersV1; refusing an unjournaled wait.");
+    const apiUrl = prior?.apiUrl ?? env.LETAGENTS_API_URL?.trim();
+    if (!apiUrl)
+        throw new Error("Custodial polling requires an explicit API URL.");
+    const response = await supervisorRequest(coordinates.socketPath, {
+        version: negotiated.protocolVersion, id: randomUUID(), method: "supervisor.authorize_custodial_polling",
+        params: {
+            entry_id: coordinates.entryId, room_id: coordinates.roomId, work_attempt_id: coordinates.workAttemptId,
+            execution_generation_id: coordinates.executionGenerationId, agent_session_id: coordinates.agentSessionId,
+            daemon_generation: negotiated.generation, api_url: apiUrl, contract: "custodial_polling_v1",
+            phase: prior ? "release" : "before", tool_name: toolName,
+            ...(prior ? { expected_configuration_revision: prior.configurationRevision } : {}),
+            ...(wait ? {
+                process_incarnation_id: CUSTODIAL_POLLING_PROCESS_INCARNATION_ID, mcp_request_id: wait.mcpRequestId,
+                ...(prior ? { expected_activation_id: prior.wait.activationId, expected_binding_epoch: prior.wait.bindingEpoch,
+                    input_cursor: prior.roomCursor, offered_frontier: wait.offeredFrontier } : { room_cursor: wait.roomCursor }),
+            } : {}),
+        },
+    }, timeoutMs);
+    const result = response.result;
+    if (!response.ok || response.version !== negotiated.protocolVersion || !result || result.status !== "authorized" || result.contract !== "custodial_polling_v1"
+        || result.room_id !== coordinates.roomId || result.agent_session_id !== coordinates.agentSessionId
+        || !Number.isSafeInteger(result.configuration_revision) || Number(result.configuration_revision) < 1
+        || (prior && result.configuration_revision !== prior.configurationRevision)
+        || (wait && (typeof result.activation_id !== "string" || !result.activation_id.trim()
+            || !Number.isSafeInteger(result.binding_epoch) || Number(result.binding_epoch) < 1
+            || typeof result.room_cursor !== "string"
+            || (prior && (result.activation_id !== prior.wait.activationId || result.binding_epoch !== prior.wait.bindingEpoch
+                || result.room_cursor !== prior.roomCursor))))
+        || !(result.room_cursor === null || (typeof result.room_cursor === "string" && parseRoomMessageNumber(result.room_cursor) !== null))) {
+        throw new Error("Custodial polling authority was rejected or became stale.");
+    }
+    return { coordinates, negotiated, apiUrl, roomId: coordinates.roomId, agentSessionId: coordinates.agentSessionId,
+        roomCursor: result.room_cursor, configurationRevision: Number(result.configuration_revision),
+        ...(wait ? { wait: { processIncarnationId: CUSTODIAL_POLLING_PROCESS_INCARNATION_ID, mcpRequestId: wait.mcpRequestId,
+                activationId: String(result.activation_id), bindingEpoch: Number(result.binding_epoch) } } : {}) };
+}
 const confirmedBindingsBySession = new Map();
 const confirmedRequestsBySession = new Map();
 const confirmedProtocolsBySession = new Map();
@@ -184,7 +258,8 @@ async function requireCurrentSupervisedCoordinates(env, options) {
  * authority for the exact worker session identity.
  */
 export async function borrowCurrentSupervisedWorkerCredential(env = process.env, options = {}) {
-    if (env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() !== "1") {
+    if (env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() !== "1"
+        && env.LETAGENTS_EXECUTION_PROFILE?.trim() !== "supervised_mcp_polling") {
         return { state: "not_supervised" };
     }
     const seed = supervisedContextSession(env);
@@ -728,7 +803,9 @@ async function negotiateSupervisor(socketPath, timeoutMs) {
     const daemonIdentity = hasCompleteIdentity
         ? [result.generation, result.pid, result.started_at].join(":")
         : null;
-    return { protocolVersion, daemonIdentity, generation: hasCompleteIdentity ? Number(result.generation) : null };
+    return { protocolVersion, daemonIdentity, generation: hasCompleteIdentity ? Number(result.generation) : null,
+        custodialPollingV1: result.capabilities?.custodialPollingV1 === true,
+        custodialPollingOffersV1: result.capabilities?.custodialPollingOffersV1 === true };
 }
 function supervisorRequest(socketPath, request, timeoutMs) {
     return new Promise((resolve, reject) => {

package/dist/mcp/server/runtime/tool-surface-policy.js

@@ -1,4 +1,11 @@
 const TOOL_SURFACE_BY_PROFILE = {
+    supervised_mcp_polling: {
+        agentSessionLifecycle: false,
+        deliveryLoop: true,
+        onboarding: false,
+        rental: false,
+        roomResume: false,
+    },
     supervised_room_turn: {
         agentSessionLifecycle: false,
         deliveryLoop: false,

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

@@ -13,13 +13,17 @@ export function getWorkerBearerRuntime() {
     const bearer = process.env.LETAGENTS_AGENT_SESSION_BEARER?.trim();
     const supervised = process.env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() === "1";
     const profile = process.env.LETAGENTS_EXECUTION_PROFILE?.trim();
+    const polling = profile === "supervised_mcp_polling";
     if (supervised !== (profile === "supervised_room_turn")) {
         return {
             mode: "invalid",
             error: "LETAGENTS_EXECUTION_PROFILE=supervised_room_turn and LETAGENTS_SUPERVISED_BOUNDED_TURNS=1 must be configured together.",
         };
     }
-    if (!bearer && !supervised)
+    if (polling && (bearer || process.env.LETAGENTS_TOKEN?.trim())) {
+        return { mode: "invalid", error: "Custodial polling refuses environment credentials; borrow exact daemon worker authority." };
+    }
+    if (!bearer && !supervised && !polling)
         return { mode: "owner" };
     if (bearer && supervised) {
         return {
@@ -69,6 +73,13 @@ export function requireValidWorkerBearerRuntime() {
     return runtime;
 }
 export function isSupervisedBoundedTurn() {
+    return hasSupervisedWorkerAuthority() && !isCustodialPolling();
+}
+export function isCustodialPolling() {
+    return process.env.LETAGENTS_EXECUTION_PROFILE?.trim() === "supervised_mcp_polling";
+}
+/** Credential custody is independent of who owns room delivery. */
+export function hasSupervisedWorkerAuthority() {
     return requireValidWorkerBearerRuntime().mode === "supervised";
 }
 export function workerModeDisabledToolResult(toolDescription = "This owner-auth onboarding tool") {