letagents 0.12.13 → 0.12.15

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

@@ -0,0 +1,190 @@
+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 { isMcpWorkerId } from "../../../shared/mcp-worker.js";
+import { pickLocalCodename } from "../../../shared/codenames.js";
+import { buildAgentActorLabel } from "../../../shared/agent-identity.js";
+import { encodeRoomIdPath } from "../../room-id.js";
+import { getGitCurrentBranch } from "../../git-remote.js";
+import { apiCall, getApiUrl } from "./api.js";
+import { resolveOwnerContext } from "./identity/directory.js";
+import { detectAgentIdeLabel, detectAgentRuntimeLabel } from "./identity/config.js";
+import { getSessionLivenessRegistration } from "./identity/liveness.js";
+import { requireValidWorkerBearerRuntime } from "./worker-bearer.js";
+const connecting = new Map();
+function snapshot() {
+    const result = readLocalStateSnapshot();
+    if (!result.complete)
+        throw new Error("Worker state is unavailable; restore it before reconnecting.");
+    return result.state;
+}
+async function workerScope() {
+    if (requireValidWorkerBearerRuntime().mode !== "owner") {
+        throw new Error("Worker handles are for independent MCP chats; supervised identity is supplied by its supervisor.");
+    }
+    const owner = await resolveOwnerContext();
+    return `${getApiUrl()}\n${owner.login?.toLowerCase() ?? `local:${owner.slug}`}`;
+}
+function getWorker(workerId, scope) {
+    const worker = snapshot().mcp_workers?.[workerId];
+    if (!isMcpWorkerId(workerId) || !worker || worker.scope !== scope) {
+        throw new Error("Unknown worker_id for this account and API. Create a worker for this chat or explicitly resume its saved handle.");
+    }
+    return worker;
+}
+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;
+    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();
+        updateLocalState((state) => {
+            state.mcp_workers ??= {};
+            const prior = Object.values(state.mcp_workers).find((w) => w.scope === scope && w.registration_key_hash === keyHash);
+            workerId = prior?.worker_id ?? `worker_${randomUUID().replaceAll("-", "")}`;
+            state.mcp_workers[workerId] ??= {
+                worker_id: workerId, scope, registration_key_hash: keyHash,
+                display_name: input.displayName?.trim() || pickLocalCodename(workerId).display_name,
+                rooms: {},
+            };
+        });
+    }
+    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);
+    if (inFlight)
+        return inFlight;
+    const result = connectWorker(input, worker, scope, roomId, local);
+    connecting.set(key, result);
+    try {
+        return await result;
+    }
+    finally {
+        connecting.delete(key);
+    }
+}
+async function connectWorker(input, worker, scope, roomId, local) {
+    const currentId = worker.rooms[roomId]?.session_id;
+    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)
+        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.");
+    const ide = detectAgentIdeLabel();
+    // An opaque per-chat key prevents two chats choosing the same visible name
+    // from collapsing into the same routing identity.
+    const agentName = worker.worker_id.replace("_", "-");
+    const agent = local ? { canonical_key: `${owner.login ?? owner.slug}/${agentName}` }
+        : await apiCall("/agents", {
+            method: "POST", body: JSON.stringify({ name: agentName, display_name: worker.display_name, owner_label: owner.label }),
+        });
+    if (!agent.canonical_key)
+        throw new Error("Worker identity registration returned no canonical identity.");
+    async function finish(operation) {
+        let session;
+        if (local) {
+            const prior = operation.predecessor_id ? snapshot().agent_sessions?.[operation.predecessor_id] : undefined;
+            if (prior && prior.session_token !== operation.predecessor_token
+                && prior.session_token !== operation.connection_token)
+                throw new Error("Worker registration was superseded.");
+            const now = new Date().toISOString();
+            session = {
+                session_id: prior?.session_id ?? `local_${createHash("sha256").update(`${worker.worker_id}\n${roomId}`).digest("hex")}`, session_token: operation.connection_token,
+                room_id: roomId, session_kind: "worker", agent_instance_id: worker.worker_id,
+                agent_key: agent.canonical_key, display_name: prior?.display_name ?? worker.display_name,
+                actor_label: prior?.actor_label ?? buildAgentActorLabel({ display_name: worker.display_name, owner_label: owner.label, ide_label: ide }),
+                owner_label: owner.label, ide_label: ide, runtime: input.runtime || detectAgentRuntimeLabel(),
+                requested_base_display_name: worker.display_name,
+                created_at: prior?.created_at ?? now, updated_at: now, last_seen_at: now, ended_at: null,
+            };
+        }
+        else {
+            const created = await apiCall(`/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()),
+                    connection_token: operation.connection_token,
+                    replace_agent_session_id: operation.predecessor_id ?? null,
+                    replace_agent_session_token: operation.predecessor_token ?? null,
+                }),
+            });
+            if (!created.session_id || created.session_token !== operation.connection_token
+                || created.agent_instance_id !== worker.worker_id || created.agent_key !== agent.canonical_key
+                || created.room_id !== roomId || created.ended_at) {
+                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;
+            session = { ...record, requested_base_display_name: assigned_base_display_name ?? worker.display_name };
+        }
+        updateLocalState((state) => {
+            const target = state.mcp_workers?.[worker.worker_id]?.rooms[roomId];
+            if (target?.pending?.operation_id !== operation.operation_id)
+                throw new Error("Worker registration was superseded; retry explicitly.");
+            state.agent_sessions ??= {};
+            if (local && !target.session_id) {
+                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++}`;
+                session.actor_label = buildAgentActorLabel({ display_name: session.display_name, owner_label: owner.label, ide_label: ide });
+            }
+            state.agent_sessions[session.session_id] = session;
+            target.session_id = session.session_id;
+            delete target.pending;
+        });
+        return session;
+    }
+    // Recover a response lost by an earlier process using its prepared credential.
+    // Then rotate once more for this process; never silently share that connection.
+    const pending = getWorker(worker.worker_id, scope).rooms[roomId]?.pending;
+    if (pending)
+        await finish(pending);
+    const operation = { operation_id: randomUUID(), connection_token: randomBytes(32).toString("base64url") };
+    updateLocalState((state) => {
+        const target = state.mcp_workers[worker.worker_id].rooms;
+        target[roomId] ??= {};
+        if (target[roomId].pending)
+            throw new Error("Another registration is in progress for this worker; retry explicitly.");
+        const priorId = target[roomId].session_id;
+        const prior = priorId ? state.agent_sessions?.[priorId] : undefined;
+        operation.predecessor_id = prior?.session_id;
+        operation.predecessor_token = prior?.session_token;
+        target[roomId].pending = operation;
+    });
+    const session = await finish(operation);
+    pinWorkerConnection(getLocalStatePath(), session);
+    return { worker: getWorker(worker.worker_id, scope), session };
+}
+export async function runMcpWorkerCall(workerId, roomId, callback, allowEnded = false) {
+    const worker = getWorker(workerId, await workerScope());
+    const rooms = Object.keys(worker.rooms);
+    const targetRoom = roomId || (rooms.length === 1 ? rooms[0] : null);
+    const entry = targetRoom ? worker.rooms[targetRoom] : null;
+    const session = entry?.session_id ? pinnedWorkerConnection(getLocalStatePath(), entry.session_id) : null;
+    const stored = entry?.session_id ? snapshot().agent_sessions?.[entry.session_id] : null;
+    if (!session || !stored || entry?.pending || stored.ended_at || session.session_token !== stored.session_token) {
+        throw new Error("This worker has no current connection in this process. Reconnect explicitly with register_agent_session(worker_id, room_id).");
+    }
+    return await withWorkerCall(session, async () => {
+        const result = await callback(session);
+        assertWorkerConnection(session, allowEnded);
+        return result;
+    });
+}

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

@@ -19,6 +19,7 @@ export function letAgentsRuntimeContract() {
     return {
         format: 1,
         profiles: {
+            supervised_mcp_polling: { contract: "custodial_polling_v1", tools: registeredToolNames("supervised_mcp_polling", "codex") },
             cursor_supervised_room_turn: {
                 tools: registeredToolNames("supervised_room_turn", "cursor"),
             },

package/dist/mcp/server/runtime.js

@@ -2,13 +2,13 @@
 // in src/mcp/server/runtime/* so tool modules can import focused responsibilities
 // without turning this file back into the runtime god module.
 import { isLocalRoomStorageEnabled as isStoredLocalRoomStorageEnabled, touchRoomSession as touchStoredRoomSession, } from "../local-state.js";
-import { isSupervisedBoundedTurn } from "./runtime/worker-bearer.js";
+import { hasSupervisedWorkerAuthority } from "./runtime/worker-bearer.js";
 /** A daemon-supervised turn must always use its exact cloud worker route. */
 export async function isLocalRoomStorageEnabled(roomId) {
-    return !isSupervisedBoundedTurn() && isStoredLocalRoomStorageEnabled(roomId);
+    return !hasSupervisedWorkerAuthority() && isStoredLocalRoomStorageEnabled(roomId);
 }
 export function touchRoomSession(roomId, lastMessageId) {
-    if (!isSupervisedBoundedTurn())
+    if (!hasSupervisedWorkerAuthority())
         touchStoredRoomSession(roomId, lastMessageId);
 }
 export { API_URL, ApiError, apiCall, getAuthorizationHeader, getLetagentsToken, isMissingRouteError, parseApiErrorPayload, resolveApiPath, } from "./runtime/api.js";

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

@@ -1,5 +1,6 @@
+import { parsePositivePgIntegerScopedId } from "../../../shared/message-contracts.mjs";
 import { runWithCurrentSupervisedRoom } from "./runtime/room-state.js";
-import { completeCurrentSupervisedEffect, executeCurrentSupervisedTool, prepareCurrentSupervisedEffect, } from "./runtime/supervisor-bridge.js";
+import { completeCurrentSupervisedEffect, authorizeCustodialPolling, executeCurrentSupervisedTool, prepareCurrentSupervisedEffect, } from "./runtime/supervisor-bridge.js";
 const READ_TOOLS = new Set([
     "get_current_room",
     "check_repo",
@@ -22,6 +23,40 @@ export function supervisedToolIsMutation(toolName) {
 // frames. A read result can be returned live to the provider without copying
 // the entire payload into the durable effect journal.
 const MAX_DURABLE_READ_RESULT_BYTES = 16 * 1024;
+/** Receipt only the bounded page actually returned by wait, never an API tail
+ * beyond that page or a cursor inferred from its last visible message. */
+function custodialWaitFrontier(result, inputCursor, roomId) {
+    const content = result.content;
+    if (result.isError || content.length !== 1 || content[0]?.type !== "text")
+        throw new Error("Custodial wait returned no valid bounded page.");
+    let output;
+    try {
+        output = JSON.parse(content[0].text);
+    }
+    catch {
+        throw new Error("Custodial wait returned no valid bounded page.");
+    }
+    if (!output || Array.isArray(output) || !Array.isArray(output.messages)
+        || (output.room_id !== undefined && output.room_id !== roomId))
+        throw new Error("Custodial wait returned no valid bounded page.");
+    const noProgress = output.messages.length === 0 && (output.truncated === undefined || output.truncated === false)
+        && (output.omitted_message_count === undefined || output.omitted_message_count === 0)
+        && (output.skipped_message_count === undefined || output.skipped_message_count === 0)
+        && (output.skipped_message_ids === undefined || (Array.isArray(output.skipped_message_ids) && output.skipped_message_ids.length === 0));
+    const frontier = output.last_observed_message_id;
+    if (frontier === undefined || frontier === null) {
+        if (!noProgress) {
+            throw new Error("Custodial wait is missing its bounded observed frontier.");
+        }
+        return inputCursor;
+    }
+    const number = parsePositivePgIntegerScopedId(frontier, "msg");
+    const inputNumber = parsePositivePgIntegerScopedId(inputCursor, "msg");
+    if (number === null || inputNumber === null || number < inputNumber || (number === inputNumber && !noProgress)) {
+        throw new Error("Custodial wait returned an invalid observed frontier.");
+    }
+    return String(frontier);
+}
 function instruction(text, data = {}) {
     const payload = { ...data, instruction: text };
     return {
@@ -47,7 +82,7 @@ const productionDependencies = {
     withRoom: runWithCurrentSupervisedRoom,
 };
 export function profileAwareToolServer(server, profile, dependencies = productionDependencies, supervisedProvider = process.env.LETAGENTS_SUPERVISOR_PROVIDER?.trim() || null) {
-    if (profile !== "supervised_room_turn")
+    if (profile !== "supervised_room_turn" && profile !== "supervised_mcp_polling")
         return server;
     return new Proxy(server, {
         get(target, property, receiver) {
@@ -61,6 +96,43 @@ export function profileAwareToolServer(server, profile, dependencies = productio
                 if (typeof callback !== "function")
                     throw new Error(`Tool ${name} has no callback.`);
                 const wrapped = async (...call) => {
+                    if (profile === "supervised_mcp_polling") {
+                        const authorize = dependencies.authorizePolling ?? ((toolName, prior, wait) => authorizeCustodialPolling(toolName, prior, process.env, {}, wait));
+                        const input = call[0];
+                        const extra = (call.length > 1 ? call.at(-1) : undefined);
+                        let wait;
+                        if (name === "wait_for_messages") {
+                            const requestId = extra?.requestId;
+                            if (!(typeof requestId === "string" || (typeof requestId === "number" && Number.isSafeInteger(requestId)))) {
+                                throw new Error("Custodial wait is missing its exact MCP request id.");
+                            }
+                            if (input?.after_message_id != null && typeof input.after_message_id !== "string")
+                                throw new Error("Custodial wait requires a valid requested cursor.");
+                            if ((input?.room_id != null && typeof input.room_id !== "string")
+                                || (input?.agent_session_id != null && typeof input.agent_session_id !== "string"))
+                                throw new Error("Custodial wait requires valid requested identity.");
+                            wait = { mcpRequestId: requestId, roomCursor: input?.after_message_id ?? null,
+                                ...(typeof input?.room_id === "string" ? { requestedRoomId: input.room_id } : {}),
+                                ...(typeof input?.agent_session_id === "string" ? { requestedAgentSessionId: input.agent_session_id } : {}) };
+                        }
+                        const authority = await authorize(name, undefined, wait);
+                        return dependencies.withRoom(authority.roomId, async () => {
+                            if (input?.room_id && input.room_id !== authority.roomId)
+                                throw new Error("Custodial tool room does not match its exact authority.");
+                            if (name === "wait_for_messages") {
+                                if (!authority.roomCursor)
+                                    throw new Error("Custodial polling has no durable cursor; refusing a tail fallback.");
+                                call[0] = { ...input, after_message_id: authority.roomCursor };
+                            }
+                            const result = await callback(...call);
+                            if (wait)
+                                await authorize(name, authority, { ...wait,
+                                    offeredFrontier: custodialWaitFrontier(result, authority.roomCursor, authority.roomId) });
+                            else if (name === "read_messages")
+                                await authorize(name, authority);
+                            return result;
+                        });
+                    }
                     const extra = (call.at(-1) ?? {});
                     const input = call.length > 1 ? call[0] : {};
                     if (extra.requestId === undefined || extra.requestId === null || String(extra.requestId).trim() === "") {

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

@@ -5,13 +5,16 @@ import { encodeRoomIdPath, looksLikeInviteCode, normalizeInviteCode } from "../.
 import { AGENT_INSTANCE_UUID, RepoRoomAuthRequiredError, apiCall, agentSessionCredentials, currentRoom, detectAgentIdeLabel, detectAgentRuntimeLabel, endStoredAgentSession, ensureAgentIdentity, getSessionLivenessRegistration, getAgentSessionRepoBranch, getStoredAgentSession, getStoredAgentSessionsForRoomIdentity, getTargetRoomId, ensureLocalWorkerAgentSession, isLocalRoomStorageEnabled, joinRoomIdentifier, resolveLocalRoomStorageIdentifiers, resolveClientRequestedBase, saveAgentSession, toPublicAgentSession, toPublicRoomState, toRepoRoomAuthRequiredResult, withAgentIdentity, resolveWorkerToolIdentity, } from "../runtime.js";
 import { requireValidWorkerBearerRuntime, workerModeDisabledToolResult, } from "../runtime/worker-bearer.js";
 import { bindSupervisedWorkerSessionWithContext } from "../runtime/supervisor-bridge.js";
+import { registerMcpWorker } from "../runtime/worker-handles.js";
 export function registerAgentSessionTools(server) {
     // -- register_agent_session -------------------------------------------------
-    server.tool("register_agent_session", "Register this MCP client as an explicit room agent session. Unregistered MCP traffic is treated as controller traffic and stays out of the connected-agent roster.", {
+    server.tool("register_agent_session", "Connect a worker to a room. For an independent chat, supply a unique registration_key once, keep the returned worker_id, and use worker_id on room tools. After an MCP restart, reconnect with that worker_id. Separate chats must use separate registration keys. Unregistered traffic remains controller traffic. Legacy agent_session_id registration is retained for existing integrations.", {
+        worker_id: z.string().optional().describe("Resume this chat's saved worker handle. Never select another chat's handle automatically."),
+        registration_key: z.string().min(1).max(200).optional().describe("Create a worker using a random key generated once for this chat; reuse the exact key if the first registration needs retrying. Do not use a shared name, room, or repository as the key."),
         room_id: z
             .string()
             .optional()
-            .describe("Canonical room ID. Defaults to the current room."),
+            .describe("Canonical room ID. Required for durable worker handles; legacy registration defaults to the current room."),
         session_kind: z
             .enum(["worker", "controller"])
             .optional()
@@ -28,7 +31,21 @@ export function registerAgentSessionTools(server) {
             .string()
             .optional()
             .describe("Worker working directory used for branch detection and exact supervised Codex binding. Defaults to the MCP server's working directory."),
-    }, async ({ room_id, session_kind, runtime, display_name, cwd }) => {
+    }, async ({ room_id, session_kind, runtime, display_name, cwd, worker_id, registration_key }) => {
+        if (worker_id !== undefined || registration_key !== undefined) {
+            if (session_kind === "controller")
+                throw new Error("Durable handles identify workers, not controllers.");
+            const roomId = room_id?.trim();
+            if (!roomId)
+                throw new Error("Pass room_id explicitly when registering or reconnecting this chat's worker.");
+            const result = await registerMcpWorker({ roomId, workerId: worker_id, registrationKey: registration_key,
+                displayName: display_name, runtime, cwd });
+            return { content: [{ type: "text", text: JSON.stringify({
+                            success: true, worker_id: result.worker.worker_id,
+                            agent_session: toPublicAgentSession(result.session),
+                            instruction: "Keep worker_id for this chat and pass it to room tools. After an MCP restart, reconnect with register_agent_session(worker_id, room_id). A separate chat needs its own registration_key. Credentials stay private to MCP.",
+                        }) }] };
+        }
         const workerRuntime = requireValidWorkerBearerRuntime();
         if (workerRuntime.mode === "supervised") {
             // Resolve before currentRoom, config, branch, or local storage. The
@@ -288,7 +305,7 @@ export function registerAgentSessionTools(server) {
             ? agentSessionCredentials(localSession)
             : {};
         if (await isLocalRoomStorageEnabled(targetRoomId)) {
-            const endedSession = endStoredAgentSession(targetSessionId);
+            const endedSession = endStoredAgentSession(targetSessionId, undefined, localSession?.session_token);
             return {
                 content: [
                     {
@@ -312,7 +329,7 @@ export function registerAgentSessionTools(server) {
             ? String(result.agent_session.ended_at ?? new Date().toISOString())
             : new Date().toISOString();
         const endedLocalSession = localSession?.session_id === targetSessionId
-            ? endStoredAgentSession(targetSessionId, endedAt)
+            ? endStoredAgentSession(targetSessionId, endedAt, localSession.session_token)
             : null;
         return {
             content: [

package/dist/mcp/server/tools/messages/read-tool.js

@@ -3,6 +3,7 @@ import { encodeRoomIdPath } from "../../../room-id.js";
 import { AGENT_MESSAGE_BODY_MAX_BYTES, appendIncludePromptOnly, boundAgentMessageOutput, buildAgentDeliveryHeaders, currentRoom, ensureAgentIdentity, getFallbackProjectId, getLatestLocalChatMessages, getCurrentAgentSessionSnapshot, getTargetRoomId, heartbeatRoomPresence, touchRoomSession, isLocalRoomStorageEnabled, resolveLocalRoomStorageIdentifiers, roomScopedApiCall, toAgentReadableMessages, } from "../../runtime.js";
 import { requireValidWorkerBearerRuntime } from "../../runtime/worker-bearer.js";
 import { jsonToolResponse } from "./response.js";
+import { currentWorkerCall } from "../../../worker-call-context.js";
 export const DEFAULT_READ_MESSAGES_LIMIT = 100;
 // Both the API and the local store clamp a single page to 500 messages.
 export const MAX_MESSAGES_PER_PAGE = 500;
@@ -77,7 +78,8 @@ export function registerReadMessagesTool(server) {
         const localRoomId = targetRoomId ?? currentRoom?.room_id ?? targetProjectId;
         const sessionRoomId = targetRoomId ?? currentRoom?.room_id ?? null;
         const workerRuntime = requireValidWorkerBearerRuntime();
-        const agentSessionSnapshot = workerRuntime.mode === "owner"
+        const boundWorker = currentWorkerCall();
+        const agentSessionSnapshot = boundWorker ? { complete: true, session: boundWorker } : workerRuntime.mode === "owner"
             ? getCurrentAgentSessionSnapshot(sessionRoomId)
             : { complete: true, session: null };
         const agentSession = agentSessionSnapshot.session;
@@ -115,7 +117,9 @@ export function registerReadMessagesTool(server) {
             limit: effectiveLimit,
             deliveryHeaders,
         });
-        await heartbeatRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, await ensureAgentIdentity());
+        if (!boundWorker) {
+            await heartbeatRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, await ensureAgentIdentity());
+        }
         const bounded = boundAgentMessageOutput(toAgentReadableMessages(recent.messages), { direction: "suffix", maxBytes: AGENT_MESSAGE_BODY_MAX_BYTES });
         const output = {
             messages: bounded.messages,

package/dist/mcp/server/tools/messages/wait-tool.js

@@ -1,8 +1,10 @@
+import { assertWorkerConnection } from "../../../worker-call-context.js";
 import { z } from "zod";
 import { getPollTimeoutCapMs } from "../../../../shared/poll-timeout-cap.js";
 import { encodeRoomIdPath } from "../../../room-id.js";
 import { agentSessionCredentials, AGENT_MESSAGE_BODY_MAX_BYTES, appendIncludePromptOnly, boundAgentMessageOutput, buildAgentDeliveryHeaders, bindSupervisedWorkerSession, scheduleSupervisedWorkerCursorCheckpoint, currentRoom, ensureAgentIdentity, getFallbackProjectId, getLatestLocalChatMessages, getLocalImportedRoutingAuthority, getLocalChatMessages, getLocalChatThreadRoutingMembership, getLastMessageId, getRememberedRoomPresence, getStoredAgentRoutingStateSnapshot, getTargetRoomId, identityFromAgentSession, isLocalRoomStorageEnabled, listLocalActiveTaskOwnerLeases, resolveLocalRoomStorageIdentifiers, resolveAgentSession, roomScopedApiCall, syncRoomPresence, toAgentReadableMessages, touchRoomSession, WORKER_BEARER_AGENT_SESSION_ID, waitForLocalChatMessages, } from "../../runtime.js";
-import { requireValidWorkerBearerRuntime, supervisedBoundedDeliveryDisabledToolResult, } from "../../runtime/worker-bearer.js";
+import { requireValidWorkerBearerRuntime, isCustodialPolling, supervisedBoundedDeliveryDisabledToolResult, } from "../../runtime/worker-bearer.js";
+import { resolveWorkerToolIdentity } from "../../runtime/agent-sessions.js";
 import { attachAgentMessageActivations, createGlobalAgentAddressResolver, decideAgentMessageActivation, isTaskOwnerFollowUpMessageText, } from "../../../../shared/activation-routing.js";
 import { normalizeRoutingSender } from "../../../../../shared/routing-aliases.mjs";
 import { findLocalMessageById, findRemoteMessageById } from "./message-lookup.js";
@@ -462,14 +464,20 @@ export function registerWaitForMessagesTool(server) {
         const targetProjectId = getFallbackProjectId();
         const localRoomId = targetRoomId ?? currentRoom?.room_id ?? targetProjectId;
         const sessionRoomId = targetRoomId ?? currentRoom?.room_id ?? localRoomId ?? null;
-        const routingStateSnapshot = getStoredAgentRoutingStateSnapshot(sessionRoomId ?? "");
+        const custodial = isCustodialPolling();
+        const routingStateSnapshot = custodial ? { complete: true } : getStoredAgentRoutingStateSnapshot(sessionRoomId ?? "");
         const localStorageEnabled = Boolean(localRoomId && await isLocalRoomStorageEnabled(localRoomId));
         if (localStorageEnabled && !routingStateSnapshot.complete) {
             throw new Error("Local agent routing state is unavailable; retry after restoring the state file.");
         }
-        const identity = await ensureAgentIdentity();
-        const agentSession = resolveWaitAgentSession(sessionRoomId, agent_session_id);
-        if (agentSession) {
+        const exactIdentity = custodial ? await resolveWorkerToolIdentity({ roomId: sessionRoomId, agentSessionId: agent_session_id }) : null;
+        const identity = exactIdentity?.identity ?? await ensureAgentIdentity();
+        const agentSession = exactIdentity?.agentSession ?? resolveWaitAgentSession(sessionRoomId, agent_session_id);
+        if (custodial) {
+            if (!agentSession || !after_message_id)
+                throw new Error("Custodial polling requires exact worker identity and durable cursor.");
+        }
+        else if (agentSession) {
             // Registration (or a successor generation) must bind strictly once.
             // Later waits use a read-only exact verification capped at 250ms, so a
             // wedged daemon cannot consume the room-poll budget and an old worker
@@ -513,6 +521,7 @@ export function registerWaitForMessagesTool(server) {
                     limit: MAX_WAIT_MESSAGES_PER_CALL,
                     include_prompt_only: true,
                 });
+            assertWorkerConnection(agentSession ?? undefined);
             const messages = await attachLocalActivationMetadata(effectiveLocalRoomId, result.messages, agentSession, {
                 includeTaskOwnerLeases: !replayingExistingMessages,
                 activeSessionRoomId: cloudRoomId || sessionRoomId,
@@ -570,6 +579,7 @@ export function registerWaitForMessagesTool(server) {
                 project_id: targetProjectId,
                 room_path: (targetRoomId) => appendIncludePromptOnly(`/rooms/${encodeRoomIdPath(targetRoomId)}/messages/poll?${queryString}`),
                 project_path: (targetProjectId) => appendIncludePromptOnly(`/projects/${encodeURIComponent(targetProjectId)}/messages/poll?${queryString}`),
+                preserve_session_cursor: true,
                 options: buildWaitForMessagesRequestOptions({
                     deliveryHeaders,
                     signal: AbortSignal.timeout(clientTimeout),
@@ -633,12 +643,14 @@ export function registerWaitForMessagesTool(server) {
         if (bounded.omittedMessageCount > 0) {
             output.omitted_message_count = bounded.omittedMessageCount;
         }
-        if (apiObservedCursor)
-            output.last_observed_message_id = apiObservedCursor;
+        // The API cursor can cover concealed messages, but not visible messages
+        // omitted by our own byte bound. Resume after the retained page instead.
+        const observedCursor = !bounded.truncated && apiObservedCursor
+            ? apiObservedCursor
+            : routing.last_observed_message_id ?? undefined;
+        if (observedCursor)
+            output.last_observed_message_id = observedCursor;
         if (targetRoomId) {
-            const observedCursor = apiObservedCursor
-                ?? routing.last_observed_message_id
-                ?? getLastMessageId(output);
             touchRoomSession(targetRoomId, observedCursor);
             if (allMessages.length > 0 && agentSession) {
                 const firstMsg = allMessages[0];

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

@@ -5,7 +5,8 @@ import { apiCall, currentAgentIdentity, currentAgentIdentityKey, detectAgentIdeL
 import { jsonTextResponse } from "./responses.js";
 import { workerModeDisabledToolResult } from "../../runtime/worker-bearer.js";
 export function registerSetAgentNameTool(server) {
-    server.tool("set_agent_name", "Set or change the agent's display name. The agent will be known by this name in the room. Use this to pick a custom name instead of the auto-generated codename.", {
+    server.tool("set_agent_name", "Set or change the legacy process identity's display name. Durable MCP workers choose display_name when first registered; this tool cannot rename them.", {
+        worker_id: z.string().optional().describe("Durable worker handles cannot be renamed by this legacy tool."),
         name: z
             .string()
             .min(2)
@@ -15,7 +16,9 @@ export function registerSetAgentNameTool(server) {
             .string()
             .optional()
             .describe("Optional conversation ID to scope this name change. When provided, only this conversation uses the new name; other conversations keep their own identity."),
-    }, async ({ name: desiredName, conversation_id }) => {
+    }, async ({ name: desiredName, conversation_id, worker_id }) => {
+        if (worker_id)
+            throw new Error("Choose display_name when first registering this worker. set_agent_name only changes the legacy process identity.");
         const disabled = workerModeDisabledToolResult();
         if (disabled)
             return jsonTextResponse(disabled);

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

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { runMcpWorkerCall } from "./runtime/worker-handles.js";
+import { getStoredAgentSession } from "../local-state/agent-sessions.js";
+import { isMcpWorkerId } from "../../shared/mcp-worker.js";
+/** One explicit identity path for all worker tools, including shared transports. */
+export function workerAwareToolServer(server) {
+    return new Proxy(server, {
+        get(target, property, receiver) {
+            if (property !== "tool") {
+                const value = Reflect.get(target, property, receiver);
+                return typeof value === "function" ? value.bind(target) : value;
+            }
+            return (name, description, schema, callback) => {
+                // assign_board_manager's session id names the target, not the caller.
+                if (name === "register_agent_session" || name === "assign_board_manager"
+                    || !schema.room_id) {
+                    return target.tool(name, description, schema, callback);
+                }
+                return target.tool(name, description, {
+                    ...schema,
+                    worker_id: z.string().optional().describe("Stable handle returned by register_agent_session for this chat. Use worker_id or legacy agent_session_id, not both. Reconnect the handle after an MCP process restart."),
+                }, async (input, extra) => {
+                    const { worker_id, ...args } = input;
+                    if (worker_id === undefined) {
+                        const session = typeof args.agent_session_id === "string" ? getStoredAgentSession(args.agent_session_id) : null;
+                        return session && isMcpWorkerId(session.agent_instance_id)
+                            ? runMcpWorkerCall(session.agent_instance_id, args.room_id ?? session.room_id, () => callback(args, extra), name === "disconnect_agent_session")
+                            : callback(args, extra);
+                    }
+                    if (args.agent_session_id !== undefined)
+                        throw new Error("Choose worker_id or agent_session_id, not both.");
+                    return runMcpWorkerCall(String(worker_id), args.room_id, (session) => callback({ ...args, room_id: session.room_id,
+                        ...(schema.agent_session_id ? { agent_session_id: session.session_id } : {}) }, extra), name === "disconnect_agent_session");
+                });
+            };
+        },
+    });
+}

package/dist/mcp/worker-call-context.js

@@ -0,0 +1,39 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { readLocalStateSnapshot, withLocalStateReadLock } from "./local-state/storage.js";
+import { isMcpWorkerId } from "../shared/mcp-worker.js";
+const calls = new AsyncLocalStorage();
+const connections = new Map();
+export function withWorkerCall(session, callback) {
+    return calls.run(session, callback);
+}
+export function currentWorkerCall() {
+    return calls.getStore();
+}
+function checkConnection(snapshot, session, allowEnded) {
+    const current = snapshot.state.agent_sessions?.[session.session_id];
+    if (!snapshot.complete || !current || current.session_token !== session.session_token
+        || (!allowEnded && current.ended_at)
+        || snapshot.state.mcp_workers?.[session.agent_instance_id]?.rooms[session.room_id]?.pending) {
+        throw new Error("This worker connection was replaced or disconnected. Reconnect explicitly with its worker_id.");
+    }
+}
+export function assertWorkerConnection(session = currentWorkerCall(), allowEnded = false) {
+    if (session && isMcpWorkerId(session.agent_instance_id))
+        checkConnection(readLocalStateSnapshot(), session, allowEnded);
+}
+export function withWorkerStateFence(callback) {
+    const session = currentWorkerCall();
+    if (!session || !isMcpWorkerId(session.agent_instance_id))
+        return callback();
+    return withLocalStateReadLock((snapshot) => {
+        checkConnection(snapshot, session, false);
+        return callback();
+    });
+}
+export function pinWorkerConnection(statePath, session) {
+    connections.set(`${statePath}\n${session.session_id}`, structuredClone(session));
+}
+export function pinnedWorkerConnection(statePath, sessionId) {
+    const call = currentWorkerCall();
+    return call?.session_id === sessionId ? call : connections.get(`${statePath}\n${sessionId}`) ?? null;
+}

package/dist/shared/activation-routing.js

@@ -312,7 +312,7 @@ export function resolveGloballyAddressedAgentKeys(message, identities) {
  * Build the room-wide alias authority once, then resolve a page of legacy
  * messages without rebuilding every active worker alias set per message.
  */
-export function createGlobalAgentAddressResolver(identities) {
+export function createGlobalAgentAddressResolver(identities, options = {}) {
     const keysByAlias = new Map();
     for (const identity of identities) {
         const key = normalizedString(identity.agent_key);
@@ -324,6 +324,23 @@ export function createGlobalAgentAddressResolver(identities) {
             keysByAlias.set(alias, keys);
         }
     }
+    const resolveExplicitMentionKey = (keys) => {
+        if (!keys || keys.size === 0)
+            return null;
+        if (keys.size === 1)
+            return keys.values().next().value;
+        const preferredMatches = [...keys].filter((key) => options.preferredExplicitMentionAgentKeys?.has(key));
+        if (preferredMatches.length !== 1)
+            return null;
+        const ownerScopes = new Set();
+        for (const key of keys) {
+            const scope = options.explicitMentionOwnerScopeByAgentKey?.get(key);
+            if (!scope)
+                return null;
+            ownerScopes.add(scope);
+        }
+        return ownerScopes.size === 1 ? preferredMatches[0] : null;
+    };
     return (message) => {
         const mentions = extractMentionHandles(message.text);
         const broadcast = mentions.some(isBroadcastHandle) || hasBroadcastAddress(message.text);
@@ -336,9 +353,9 @@ export function createGlobalAgentAddressResolver(identities) {
             const alias = normalizeMentionIdentityHandle(mention);
             if (!alias)
                 continue;
-            const keys = keysByAlias.get(alias);
-            if (keys?.size === 1)
-                explicitMentionKeys.add(keys.values().next().value);
+            const resolvedKey = resolveExplicitMentionKey(keysByAlias.get(alias));
+            if (resolvedKey)
+                explicitMentionKeys.add(resolvedKey);
         }
         const replyTargetKeys = new Set();
         const replyAliases = normalizedString(message.reply_to?.source) === "agent"