letagents 0.12.10 → 0.12.12

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

@@ -0,0 +1,26 @@
+const TOOL_SURFACE_BY_PROFILE = {
+    supervised_room_turn: {
+        agentSessionLifecycle: false,
+        deliveryLoop: false,
+        onboarding: false,
+        rental: false,
+        roomResume: false,
+    },
+    autonomous_mcp_worker: {
+        agentSessionLifecycle: true,
+        deliveryLoop: true,
+        onboarding: true,
+        rental: true,
+        roomResume: true,
+    },
+    interactive_desktop: {
+        agentSessionLifecycle: true,
+        deliveryLoop: true,
+        onboarding: true,
+        rental: true,
+        roomResume: true,
+    },
+};
+export function toolSurfaceForExecutionProfile(profile) {
+    return TOOL_SURFACE_BY_PROFILE[profile];
+}

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

@@ -0,0 +1,101 @@
+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) {
+        super(message);
+        this.name = "WorkerBearerRuntimeConfigurationError";
+    }
+}
+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();
+    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)
+        return { mode: "owner" };
+    if (bearer && supervised) {
+        return {
+            mode: "invalid",
+            error: "Daemon-supervised bounded turns refuse LETAGENTS_AGENT_SESSION_BEARER; credentials must be borrowed from the exact supervisor generation.",
+        };
+    }
+    const apiUrl = process.env.LETAGENTS_API_URL?.trim();
+    if (!apiUrl) {
+        return {
+            mode: "invalid",
+            error: "Worker bearer mode requires an explicit LETAGENTS_API_URL.",
+        };
+    }
+    try {
+        const parsed = new URL(apiUrl);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            throw new Error("unsupported protocol");
+        }
+        const loopbackHosts = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+        if (parsed.protocol === "http:" && !loopbackHosts.has(parsed.hostname.toLowerCase())) {
+            return {
+                mode: "invalid",
+                error: "Worker bearer mode requires HTTPS unless LETAGENTS_API_URL uses an exact loopback host.",
+            };
+        }
+    }
+    catch {
+        return {
+            mode: "invalid",
+            error: "Worker bearer mode requires LETAGENTS_API_URL to be a valid HTTP(S) URL.",
+        };
+    }
+    if (bearer && process.env.LETAGENTS_TOKEN?.trim()) {
+        return {
+            mode: "invalid",
+            error: "Worker bearer mode refuses LETAGENTS_TOKEN. Remove the owner token from this process before starting the worker.",
+        };
+    }
+    return bearer ? { mode: "worker", bearer } : { mode: "supervised" };
+}
+export function requireValidWorkerBearerRuntime() {
+    const runtime = getWorkerBearerRuntime();
+    if (runtime.mode === "invalid") {
+        throw new WorkerBearerRuntimeConfigurationError(runtime.error);
+    }
+    return runtime;
+}
+export function isSupervisedBoundedTurn() {
+    return requireValidWorkerBearerRuntime().mode === "supervised";
+}
+export function workerModeDisabledToolResult(toolDescription = "This owner-auth onboarding tool") {
+    const runtime = getWorkerBearerRuntime();
+    if (runtime.mode === "invalid") {
+        return { success: false, error: "worker_bearer_configuration_invalid", message: runtime.error };
+    }
+    if (runtime.mode === "worker" || runtime.mode === "supervised") {
+        return {
+            success: false,
+            error: runtime.mode === "worker" ? "worker_bearer_mode" : "supervised_bounded_mode",
+            message: runtime.mode === "worker"
+                ? `${toolDescription} is disabled while LETAGENTS_AGENT_SESSION_BEARER is configured.`
+                : `${toolDescription} is disabled during a daemon-supervised bounded turn.`,
+        };
+    }
+    return null;
+}
+/**
+ * Supervised room delivery belongs to the desktop daemon. A bounded provider
+ * turn must never recreate the permanent MCP polling loop, even if its prompt
+ * asks it to do so.
+ */
+export function supervisedBoundedDeliveryDisabledToolResult(toolName = "wait_for_messages") {
+    if (process.env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() !== "1") {
+        return null;
+    }
+    return {
+        success: false,
+        error: "supervised_bounded_delivery",
+        message: `${toolName} is disabled because supervised room delivery is owned by the desktop daemon.`,
+    };
+}

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

@@ -0,0 +1,27 @@
+import { registerTools } from "./register-tools.js";
+export const LETAGENTS_RUNTIME_CONTRACT_ARG = "--letagents-runtime-contract";
+/**
+ * Discover through the production registration path rather than maintaining a
+ * second capability list that can drift from the MCP server.
+ */
+export function registeredToolNames(profile, supervisedProvider = null) {
+    const names = new Set();
+    const recorder = {
+        tool(name) {
+            names.add(name);
+            return {};
+        },
+    };
+    registerTools(recorder, profile, supervisedProvider);
+    return [...names].sort();
+}
+export function letAgentsRuntimeContract() {
+    return {
+        format: 1,
+        profiles: {
+            cursor_supervised_room_turn: {
+                tools: registeredToolNames("supervised_room_turn", "cursor"),
+            },
+        },
+    };
+}

package/dist/mcp/server/runtime.js

@@ -1,14 +1,25 @@
 // Compatibility facade for MCP server runtime helpers. The implementation lives
 // 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";
+/** A daemon-supervised turn must always use its exact cloud worker route. */
+export async function isLocalRoomStorageEnabled(roomId) {
+    return !isSupervisedBoundedTurn() && isStoredLocalRoomStorageEnabled(roomId);
+}
+export function touchRoomSession(roomId, lastMessageId) {
+    if (!isSupervisedBoundedTurn())
+        touchStoredRoomSession(roomId, lastMessageId);
+}
 export { API_URL, ApiError, apiCall, getAuthorizationHeader, getLetagentsToken, isMissingRouteError, parseApiErrorPayload, resolveApiPath, } from "./runtime/api.js";
 export { clearAuthenticatedAccountCache, getAuthenticatedAccountCache, setAuthenticatedAccountCache, } from "./runtime/auth-cache.js";
 export { RepoRoomAuthRequiredError, maybeHandleRepoRoomAuthRequired, startPendingDeviceAuth, toRepoRoomAuthRequiredResult, } from "./runtime/device-auth.js";
 export { AGENT_INSTANCE_UUID, currentAgentIdentity, currentAgentIdentityKey, detectAgentIdeLabel, detectAgentRuntimeLabel, ensureAgentIdentity, getConversationIdentity, getSessionLivenessRegistration, resolveOwnerContext, setConversationIdentity, storeCurrentAgentIdentity, toPublicAgentIdentity, withAgentIdentity, } from "./runtime/identity.js";
-export { agentSessionCredentials, buildAgentDeliveryHeaders, ensureLocalWorkerAgentSession, getAgentSessionRepoBranch, identityFromAgentSession, requireWorkerAgentSession, resolveAgentSession, resolveWorkerToolIdentity, toPublicAgentSession, } from "./runtime/agent-sessions.js";
+export { agentSessionCredentials, buildAgentDeliveryHeaders, ensureLocalWorkerAgentSession, getAgentSessionRepoBranch, identityFromAgentSession, requireWorkerAgentSession, resolveAgentSession, resolveClientRequestedBase, resolveWorkerToolIdentity, toPublicAgentSession, WORKER_BEARER_AGENT_SESSION_ID, } from "./runtime/agent-sessions.js";
 export { appendIncludePromptOnly, getLastMessageId, normalizeOptionalToolString, toAgentReadableMessages, withJoinRoomAgentPrompt, } from "./runtime/messages.js";
-export { currentRoom, attachMcpServer, getFallbackProjectId, getTargetRoomId, rememberRoom, shutdownRuntime, toPublicRoomResponse, toPublicRoomState, toPublicStoredRoomSession, toRoomState, touchCurrentRoom, withCanonicalRoomLink, } from "./runtime/room-state.js";
+export { currentRoom, attachMcpServer, getCurrentSupervisedRoomAuthority, getFallbackProjectId, getTargetRoomId, rememberRoom, runWithCurrentSupervisedRoom, shutdownRuntime, toPublicRoomResponse, toPublicCurrentRoomState, toPublicRoomState, toPublicStoredRoomSession, toRoomState, touchCurrentRoom, withCanonicalRoomLink, } from "./runtime/room-state.js";
 export { getRememberedRoomPresence, heartbeatRoomPresence, syncRoomPresence, } from "./runtime/presence.js";
 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, getStoredAuth, getStoredCurrentRoom, getStoredRoomSession, listStoredCodexLiveSessions, saveAgentSession, setPendingDeviceAuth, setStoredAuth, setStoredAgentIdentity, touchRoomSession, addLocalChatMessage, addLocalTask, claimLocalTaskReviewLease, getLatestLocalChatMessages, getLocalChatMessages, getLocalTask, listLocalTasks, isLocalChatStorageEnabled, isLocalRoomStorageEnabled, resolveLocalRoomStorageIdentifiers, releaseLocalTaskReviewLease, updateLocalTask, waitForLocalChatMessages, } from "../local-state.js";
+export { clearPendingDeviceAuth, clearStoredAuth, clearStoredAuth as clearStoredAuthorization, endStoredAgentSession, getCurrentAgentSession, getLocalStatePath, getPendingDeviceAuth, getStoredAgentIdentity, getStoredAgentSession, getStoredAgentSessionsForRoomIdentity, getStoredAuth, getStoredCurrentRoom, getStoredRoomSession, listStoredCodexLiveSessions, saveAgentSession, setPendingDeviceAuth, setStoredAuth, setStoredAgentIdentity, addLocalChatMessage, addLocalTask, claimLocalTaskReviewLease, getLatestLocalChatMessages, getLocalChatMessages, getLocalTask, listLocalTasks, isLocalChatStorageEnabled, resolveLocalRoomStorageIdentifiers, releaseLocalTaskReviewLease, updateLocalTask, waitForLocalChatMessages, } from "../local-state.js";

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

@@ -0,0 +1,105 @@
+import { runWithCurrentSupervisedRoom } from "./runtime/room-state.js";
+import { completeCurrentSupervisedEffect, prepareCurrentSupervisedEffect, } from "./runtime/supervisor-bridge.js";
+const READ_TOOLS = new Set([
+    "get_current_room",
+    "check_repo",
+    "check_repo_visibility",
+    "read_messages",
+    "wait_for_messages",
+    "get_board",
+    "get_board_settings",
+    "get_room_artifacts",
+    "get_room_events",
+    "list_board_intents",
+    "get_onboarding_status",
+    "status_local_codex_session",
+    "rental_list_requests",
+]);
+function instruction(text, data = {}) {
+    const payload = { ...data, instruction: text };
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+    };
+}
+const productionDependencies = {
+    prepareEffect: prepareCurrentSupervisedEffect,
+    completeEffect: completeCurrentSupervisedEffect,
+    withRoom: runWithCurrentSupervisedRoom,
+};
+export function profileAwareToolServer(server, profile, dependencies = productionDependencies, supervisedProvider = process.env.LETAGENTS_SUPERVISOR_PROVIDER?.trim() || null) {
+    if (profile !== "supervised_room_turn")
+        return 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, ...registration) => {
+                const callback = registration.at(-1);
+                if (typeof callback !== "function")
+                    throw new Error(`Tool ${name} has no callback.`);
+                const wrapped = async (...call) => {
+                    const extra = (call.at(-1) ?? {});
+                    const input = call.length > 1 ? call[0] : {};
+                    if (extra.requestId === undefined || extra.requestId === null || String(extra.requestId).trim() === "") {
+                        throw new Error(`Supervised tool ${name} is missing its MCP request id; refusing an effect that cannot be deduplicated safely.`);
+                    }
+                    const prepared = await dependencies.prepareEffect({
+                        toolName: name,
+                        input,
+                        mcpRequestId: String(extra.requestId),
+                        mutation: !READ_TOOLS.has(name),
+                    });
+                    return dependencies.withRoom(prepared.roomId, async () => {
+                        if (prepared.state === "completed")
+                            return prepared.result;
+                        if (prepared.state === "uncertain") {
+                            return instruction("This mutating tool may already have completed, but its result was not durably checkpointed. Verify the external state before issuing a new request; this exact request will not be repeated automatically.", {
+                                code: "SUPERVISED_EFFECT_OUTCOME_UNCERTAIN",
+                                effect_id: prepared.effectId,
+                                detail: prepared.error,
+                            });
+                        }
+                        if (prepared.action === "use_final_answer") {
+                            return instruction(supervisedProvider === "cursor"
+                                ? "Do not send the activating room reply with a message tool. Keep working, then record the one public answer with complete_room_turn; Cursor's aggregate final text is live evidence only."
+                                : "Do not send the activating room reply with a message tool. Return it as your final answer; the daemon will publish it exactly once.", {
+                                code: "USE_FINAL_ANSWER",
+                                source_message_id: prepared.sourceMessageId,
+                            });
+                        }
+                        if (prepared.action === "room_move_prepared") {
+                            return instruction(supervisedProvider === "cursor"
+                                ? "The room move is prepared. Finish the work, then call complete_room_turn with the public response; the daemon will publish that proposal and then move the agent."
+                                : "The room move is prepared. Finish this turn normally; the daemon will publish the activating response and then move the agent.", {
+                                code: "ROOM_MOVE_PREPARED",
+                                destination_room: prepared.destinationRoom,
+                            });
+                        }
+                        let result;
+                        try {
+                            result = await callback(...call);
+                        }
+                        catch (error) {
+                            try {
+                                await dependencies.completeEffect({ effectId: prepared.effectId, error: error instanceof Error ? error.message : String(error) });
+                            }
+                            catch {
+                                // Preserve the callback error. An unacknowledged journal entry
+                                // remains executing, which is safer than repeating the effect.
+                            }
+                            throw error;
+                        }
+                        // Completion transport is deliberately outside the callback catch.
+                        // A reporting failure must never relabel a successful action failed.
+                        await dependencies.completeEffect({ effectId: prepared.effectId, result });
+                        return result;
+                    });
+                };
+                return target.tool.call(target, name, ...registration.slice(0, -1), wrapped);
+            };
+        },
+    });
+}

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

@@ -2,7 +2,9 @@ import { z } from "zod";
 import { scheduleCodexRuntimeStreamBridgeBind, } from "../../codex-session.js";
 import { getManagedAgentProvider, toManagedAgentStartResponse, } from "../../managed-agent-providers.js";
 import { encodeRoomIdPath, looksLikeInviteCode, normalizeInviteCode } from "../../room-id.js";
-import { AGENT_INSTANCE_UUID, RepoRoomAuthRequiredError, apiCall, agentSessionCredentials, currentRoom, detectAgentIdeLabel, detectAgentRuntimeLabel, endStoredAgentSession, ensureAgentIdentity, getSessionLivenessRegistration, getAgentSessionRepoBranch, getStoredAgentSession, getTargetRoomId, ensureLocalWorkerAgentSession, isLocalRoomStorageEnabled, joinRoomIdentifier, resolveLocalRoomStorageIdentifiers, saveAgentSession, toPublicAgentSession, toPublicRoomState, toRepoRoomAuthRequiredResult, withAgentIdentity, } from "../runtime.js";
+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";
 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.", {
@@ -25,8 +27,29 @@ export function registerAgentSessionTools(server) {
         cwd: z
             .string()
             .optional()
-            .describe("Working directory used to detect the worker's active git branch. Defaults to the MCP server's working directory."),
+            .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 }) => {
+        const workerRuntime = requireValidWorkerBearerRuntime();
+        if (workerRuntime.mode === "supervised") {
+            // Resolve before currentRoom, config, branch, or local storage. The
+            // daemon context is the only authority for a bounded worker's room.
+            const { agentSession } = await resolveWorkerToolIdentity({ roomId: room_id?.trim() || null });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            worker_bearer_mode: false,
+                            supervised_bounded_mode: true,
+                            agent_session: toPublicAgentSession(agentSession),
+                            agent_session_id: agentSession.session_id,
+                            use_agent_session_id: "This exact daemon-supervised agent_session_id may be passed to room tools. The credential remains daemon-private.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
         const targetRoomId = getTargetRoomId(room_id);
         if (!targetRoomId) {
             return {
@@ -66,6 +89,29 @@ export function registerAgentSessionTools(server) {
                 ],
             };
         }
+        const { cloudRoomId } = await resolveLocalRoomStorageIdentifiers(targetRoomId);
+        const apiRoomId = cloudRoomId || targetRoomId;
+        if (workerRuntime.mode === "worker") {
+            // The supplied bearer is issued for an existing server-side agent
+            // session. Do not call the owner-only registration endpoint or write
+            // any session credential to local storage.
+            const { agentSession } = await resolveWorkerToolIdentity({ roomId: apiRoomId });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            worker_bearer_mode: workerRuntime.mode === "worker",
+                            supervised_bounded_mode: false,
+                            agent_session: toPublicAgentSession(agentSession),
+                            agent_session_id: agentSession.session_id,
+                            use_agent_session_id: "This local worker-bearer session marker may be passed to room tools. The supplied bearer remains the only server credential.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
         const identity = await ensureAgentIdentity();
         if (!identity.canonical_key) {
             return {
@@ -80,8 +126,22 @@ export function registerAgentSessionTools(server) {
                 ],
             };
         }
-        const { cloudRoomId } = await resolveLocalRoomStorageIdentifiers(targetRoomId);
-        const apiRoomId = cloudRoomId || targetRoomId;
+        // Stable-base signal (task_66): declare the intent behind display_name
+        // so the server can converge a replayed decorated label without ever
+        // guessing from numeric shape.
+        const priorRoomSessions = getStoredAgentSessionsForRoomIdentity(apiRoomId, identity.canonical_key);
+        const requestedSessionKind = session_kind ?? "worker";
+        const requestedBaseDisplayName = resolveClientRequestedBase({
+            explicitDisplayName: display_name,
+            identityDisplayName: identity.display_name,
+            priorSessions: priorRoomSessions,
+        });
+        const replacementSession = requestedSessionKind === "worker"
+            ? priorRoomSessions.find((session) => !session.ended_at
+                && session.session_kind === "worker"
+                && session.agent_instance_id === AGENT_INSTANCE_UUID
+                && Boolean(session.session_token)) ?? null
+            : null;
         const created = await apiCall(`/rooms/${encodeRoomIdPath(apiRoomId)}/agent-sessions`, {
             method: "POST",
             body: JSON.stringify({
@@ -90,10 +150,13 @@ export function registerAgentSessionTools(server) {
                 ide_label: identity.ide_label ?? detectAgentIdeLabel(),
                 agent_instance_id: AGENT_INSTANCE_UUID,
                 display_name: display_name?.trim() || identity.display_name,
+                requested_base_display_name: requestedBaseDisplayName,
                 session_kind: session_kind ?? "worker",
                 runtime: requestedRuntime,
                 repo_branch: repoBranch,
                 registration_liveness: getSessionLivenessRegistration(requestedRuntime),
+                replace_agent_session_id: replacementSession?.session_id ?? null,
+                replace_agent_session_token: replacementSession?.session_token ?? null,
             }),
         });
         const sessionId = typeof created.session_id === "string" ? created.session_id : "";
@@ -101,7 +164,10 @@ export function registerAgentSessionTools(server) {
         if (!sessionId || !sessionToken) {
             throw new Error("Agent session registration response was missing session credentials.");
         }
-        const session = saveAgentSession({
+        if (replacementSession) {
+            endStoredAgentSession(replacementSession.session_id, typeof created.created_at === "string" ? created.created_at : new Date().toISOString());
+        }
+        let session = saveAgentSession({
             session_id: sessionId,
             session_token: sessionToken,
             room_id: typeof created.room_id === "string" ? created.room_id : apiRoomId,
@@ -116,6 +182,11 @@ export function registerAgentSessionTools(server) {
             agent_key: typeof created.agent_key === "string" ? created.agent_key : identity.canonical_key,
             agent_instance_id: typeof created.agent_instance_id === "string" ? created.agent_instance_id : AGENT_INSTANCE_UUID,
             display_name: typeof created.display_name === "string" ? created.display_name : identity.display_name,
+            // Prefer the server-recorded allocation base; fall back to the base we
+            // declared so a later resume still replays a stable signal.
+            requested_base_display_name: (typeof created.assigned_base_display_name === "string" && created.assigned_base_display_name.trim())
+                || requestedBaseDisplayName
+                || null,
             owner_label: typeof created.owner_label === "string" ? created.owner_label : identity.owner_label,
             ide_label: typeof created.ide_label === "string" ? created.ide_label : identity.ide_label ?? detectAgentIdeLabel(),
             repo_branch: typeof created.repo_branch === "string" ? created.repo_branch : repoBranch,
@@ -124,6 +195,13 @@ export function registerAgentSessionTools(server) {
             last_seen_at: typeof created.last_seen_at === "string" ? created.last_seen_at : new Date().toISOString(),
             ended_at: typeof created.ended_at === "string" ? created.ended_at : null,
         });
+        const supervisorBinding = await bindSupervisedWorkerSessionWithContext(session, process.env, { cwd: cwd?.trim() || process.cwd() });
+        if (supervisorBinding.supervisorContextCwd) {
+            session = saveAgentSession({
+                ...session,
+                supervisor_context_cwd: supervisorBinding.supervisorContextCwd,
+            });
+        }
         scheduleCodexRuntimeStreamBridgeBind(session);
         return {
             content: [
@@ -144,6 +222,18 @@ export function registerAgentSessionTools(server) {
         room_id: z.string().optional().describe("Canonical room ID. Defaults to the current room or the stored session room."),
         agent_session_id: z.string().optional().describe("Registered agent session to disconnect."),
     }, async ({ room_id, agent_session_id }) => {
+        if (requireValidWorkerBearerRuntime().mode === "supervised") {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "supervised_bounded_mode",
+                            message: "Agent-session disconnection is owned by the desktop supervisor during a bounded turn.",
+                        }, null, 2),
+                    }],
+            };
+        }
         let targetRoomId = getTargetRoomId(room_id);
         const localSession = agent_session_id
             ? getStoredAgentSession(agent_session_id)
@@ -258,6 +348,12 @@ export function registerAgentSessionTools(server) {
             .optional()
             .describe("Optional hard stop in minutes. Defaults to 0, which means run until stopped."),
     }, async ({ room, cwd, stop_phrase, max_minutes }) => {
+        const disabled = workerModeDisabledToolResult("Local Codex session orchestration");
+        if (disabled) {
+            return {
+                content: [{ type: "text", text: JSON.stringify(disabled, null, 2) }],
+            };
+        }
         const joinedVia = looksLikeInviteCode(room) ? "join_code" : "join_room";
         try {
             const joined = await joinRoomIdentifier(room, joinedVia);
@@ -305,6 +401,12 @@ export function registerAgentSessionTools(server) {
             .optional()
             .describe("Optional session id. Defaults to the current local Codex live session."),
     }, async ({ session_id }) => {
+        const disabled = workerModeDisabledToolResult("Local Codex session orchestration");
+        if (disabled) {
+            return {
+                content: [{ type: "text", text: JSON.stringify(disabled, null, 2) }],
+            };
+        }
         const provider = getManagedAgentProvider("codex");
         const status = await provider.inspectLocalSession(session_id, currentRoom?.room_id);
         if (!status) {
@@ -343,6 +445,12 @@ export function registerAgentSessionTools(server) {
             .optional()
             .describe("If true, also terminate the spawned codex app-server process when possible."),
     }, async ({ session_id, shutdown_server }) => {
+        const disabled = workerModeDisabledToolResult("Local Codex session orchestration");
+        if (disabled) {
+            return {
+                content: [{ type: "text", text: JSON.stringify(disabled, null, 2) }],
+            };
+        }
         const provider = getManagedAgentProvider("codex");
         const stopped = await provider.stopLocalSession({
             session_id,

package/dist/mcp/server/tools/messages/index.js

@@ -7,8 +7,9 @@ export function registerStatusTools(server) {
     registerPostStatusTool(server);
     registerPostReasoningTool(server);
 }
-export function registerMessageTools(server) {
+export function registerMessageTools(server, options = {}) {
     registerSendMessageTool(server);
     registerReadMessagesTool(server);
-    registerWaitForMessagesTool(server);
+    if (options.includeDeliveryLoop !== false)
+        registerWaitForMessagesTool(server);
 }

package/dist/mcp/server/tools/messages/message-lookup.js

@@ -0,0 +1,75 @@
+import { encodeRoomIdPath } from "../../../room-id.js";
+import { ApiError, appendIncludePromptOnly, getLocalChatMessages, isMissingRouteError, roomScopedApiCall, } from "../../runtime.js";
+function isRecord(value) {
+    return Boolean(value && typeof value === "object");
+}
+export async function findLocalMessageById(roomId, messageId) {
+    let afterCursor;
+    for (;;) {
+        const result = await getLocalChatMessages(roomId, {
+            after: afterCursor,
+            include_prompt_only: true,
+        });
+        const messages = (result.messages ?? []).filter(isRecord);
+        const match = messages.find((message) => message.id === messageId);
+        if (match)
+            return match;
+        if (!result.has_more || messages.length === 0)
+            return null;
+        const lastMessage = messages[messages.length - 1];
+        afterCursor = typeof lastMessage?.id === "string" ? lastMessage.id : undefined;
+        if (!afterCursor)
+            return null;
+    }
+}
+export async function findRemoteMessageById(input) {
+    if (input.roomId) {
+        try {
+            const result = await roomScopedApiCall({
+                room_id: input.roomId,
+                room_path: (roomId) => appendIncludePromptOnly(`/rooms/${encodeRoomIdPath(roomId)}/messages/${encodeURIComponent(input.messageId)}`),
+                project_path: () => "",
+                // Context lookups must not advance the room session cursor.
+                preserve_session_cursor: true,
+            });
+            return isRecord(result.message) ? result.message : null;
+        }
+        catch (error) {
+            if (isMissingRouteError(error)) {
+                // Older API without the by-id route: fall back to scanning history.
+            }
+            else if (error instanceof ApiError && error.status === 404) {
+                return null;
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    return scanRemoteMessageHistoryById(input);
+}
+async function scanRemoteMessageHistoryById(input) {
+    let afterCursor;
+    for (;;) {
+        const query = new URLSearchParams();
+        if (afterCursor)
+            query.set("after", afterCursor);
+        const qs = query.toString();
+        const result = await roomScopedApiCall({
+            room_id: input.roomId,
+            project_id: input.projectId,
+            room_path: (roomId) => appendIncludePromptOnly(`/rooms/${encodeRoomIdPath(roomId)}/messages${qs ? `?${qs}` : ""}`),
+            project_path: (projectId) => appendIncludePromptOnly(`/projects/${encodeURIComponent(projectId)}/messages${qs ? `?${qs}` : ""}`),
+        });
+        const messages = (result.messages ?? []).filter(isRecord);
+        const match = messages.find((message) => message.id === input.messageId);
+        if (match)
+            return match;
+        if (!result.has_more || messages.length === 0)
+            return null;
+        const lastMessage = messages[messages.length - 1];
+        afterCursor = typeof lastMessage?.id === "string" ? lastMessage.id : undefined;
+        if (!afterCursor)
+            return null;
+    }
+}

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

@@ -24,7 +24,7 @@ function withRecencyTelemetry(output, selection) {
 }
 // Fetch the most recent messages by paging BACKWARDS from the tail
 // (before=latest), so a limited read never walks the full room history.
-async function fetchRecentRemoteMessages(input) {
+export async function fetchRecentRemoteMessages(input) {
     const collected = [];
     let beforeCursor = "latest";
     let truncated = false;