letagents 0.12.12 → 0.12.14

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

@@ -3,14 +3,89 @@ import { lstat, readFile, realpath } from "node:fs/promises";
 import { createConnection } from "node:net";
 import { homedir } from "node:os";
 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();
@@ -18,6 +93,42 @@ const pendingCursorCheckpoints = new Map();
 const activeCursorCheckpointDrains = new Set();
 const cursorCheckpointRetryTimers = new Map();
 const CURSOR_CHECKPOINT_RETRY_DELAYS_MS = [250, 1_000, 3_000];
+export async function executeCurrentSupervisedTool(input, env = process.env, options = {}) {
+    const coordinates = await requireCurrentSupervisedCoordinates(env, options);
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const negotiated = await negotiateSupervisor(coordinates.socketPath, timeoutMs);
+    if (negotiated.generation === null)
+        throw new Error("The supervised daemon generation is unavailable.");
+    const response = await supervisorRequest(coordinates.socketPath, {
+        version: negotiated.protocolVersion,
+        id: randomUUID(),
+        method: "supervisor.execute_bounded_tool",
+        params: {
+            entry_id: coordinates.entryId,
+            work_attempt_id: coordinates.workAttemptId,
+            execution_generation_id: coordinates.executionGenerationId,
+            ...(coordinates.providerTurnId ? { provider_turn_id: coordinates.providerTurnId } : {}),
+            daemon_generation: negotiated.generation,
+            mcp_request_id: input.mcpRequestId,
+            tool_name: input.toolName,
+            input: input.input,
+        },
+    }, null);
+    if (!response.ok) {
+        if (/Unsupported daemon method:\s*supervisor\.execute_bounded_tool/i.test(response.error ?? "")) {
+            return { state: "unsupported" };
+        }
+        throw new Error(response.error || "The daemon-owned supervised tool was rejected.");
+    }
+    const result = response.result && typeof response.result === "object"
+        ? response.result
+        : {};
+    const roomId = typeof result.room_id === "string" ? result.room_id.trim() : "";
+    if (!roomId || roomId.length > 1_024 || /[\u0000-\u001f\u007f]/.test(roomId)) {
+        throw new Error("The supervised daemon did not return valid exact room authority.");
+    }
+    return { state: "completed", roomId, result: result.result };
+}
 export async function prepareCurrentSupervisedEffect(input, env = process.env, options = {}) {
     const coordinates = await requireCurrentSupervisedCoordinates(env, options);
     const timeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
@@ -147,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);
@@ -412,6 +524,8 @@ export function scheduleSupervisedWorkerCursorCheckpoint(session, roomCursor, en
     });
 }
 async function enqueueSupervisedWorkerCursorCheckpoint(session, roomCursor, env, options) {
+    if (parseRoomMessageNumber(roomCursor) === null)
+        return;
     const coordinates = await resolveSupervisorCoordinates(session, env, options);
     if (!coordinates)
         return;
@@ -509,13 +623,14 @@ function isNewerRoomCursor(candidate, current) {
         return false;
     const candidateNumber = parseRoomMessageNumber(candidate);
     const currentNumber = parseRoomMessageNumber(current);
-    if (candidateNumber !== null && currentNumber !== null)
-        return candidateNumber > currentNumber;
-    return true;
+    if (candidateNumber === null)
+        return false;
+    if (currentNumber === null)
+        return true;
+    return candidateNumber > currentNumber;
 }
 function parseRoomMessageNumber(cursor) {
-    const match = /^msg_(\d+)$/.exec(cursor.trim());
-    return match ? BigInt(match[1]) : null;
+    return parsePositivePgIntegerScopedId(cursor, "msg");
 }
 /** Transport failures are retryable bookkeeping failures, not worker failures. */
 export function isRetryableSupervisorBridgeError(error) {
@@ -688,23 +803,26 @@ 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) => {
         const socket = createConnection(socketPath);
         let buffer = "";
         let finished = false;
-        const timer = setTimeout(() => {
+        const timer = timeoutMs === null ? null : setTimeout(() => {
             socket.destroy();
             finish(() => reject(new Error("Timed out communicating with the supervisor daemon.")));
         }, timeoutMs);
-        timer.unref();
+        timer?.unref();
         const finish = (operation) => {
             if (finished)
                 return;
             finished = true;
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             operation();
         };
         socket.setEncoding("utf8");

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

@@ -1,3 +1,4 @@
+import { getDaemonToolExecutionContext } from "./daemon-tool-context.js";
 export const LETAGENTS_AGENT_SESSION_BEARER_ENV = "LETAGENTS_AGENT_SESSION_BEARER";
 export const LETAGENTS_SUPERVISED_BOUNDED_TURNS_ENV = "LETAGENTS_SUPERVISED_BOUNDED_TURNS";
 export class WorkerBearerRuntimeConfigurationError extends Error {
@@ -7,16 +8,22 @@ export class WorkerBearerRuntimeConfigurationError extends Error {
     }
 }
 export function getWorkerBearerRuntime() {
+    if (getDaemonToolExecutionContext())
+        return { mode: "supervised" };
     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 {
@@ -66,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") {
@@ -90,7 +104,8 @@ export function workerModeDisabledToolResult(toolDescription = "This owner-auth
  * asks it to do so.
  */
 export function supervisedBoundedDeliveryDisabledToolResult(toolName = "wait_for_messages") {
-    if (process.env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() !== "1") {
+    if (!getDaemonToolExecutionContext()
+        && process.env.LETAGENTS_SUPERVISED_BOUNDED_TURNS?.trim() !== "1") {
         return null;
     }
     return {

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";
@@ -16,10 +16,10 @@ export { clearAuthenticatedAccountCache, getAuthenticatedAccountCache, setAuthen
 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, 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, getCurrentSupervisedRoomAuthority, getFallbackProjectId, getTargetRoomId, rememberRoom, runWithCurrentSupervisedRoom, shutdownRuntime, toPublicRoomResponse, toPublicCurrentRoomState, toPublicRoomState, toPublicStoredRoomSession, toRoomState, touchCurrentRoom, withCanonicalRoomLink, } from "./runtime/room-state.js";
+export { appendIncludePromptOnly, AGENT_MESSAGE_BODY_MAX_BYTES, AGENT_MESSAGE_OUTPUT_MAX_BYTES, boundAgentMessageOutput, getLastMessageId, normalizeOptionalToolString, toAgentReadableMessages, withJoinRoomAgentPrompt, } from "./runtime/messages.js";
+export { currentRoom, currentRoomMatchesLocator, 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, 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";
+export { clearPendingDeviceAuth, clearStoredAuth, clearStoredAuth as clearStoredAuthorization, endStoredAgentSession, getCurrentAgentSession, getLocalStatePath, getPendingDeviceAuth, getStoredAgentIdentity, getStoredAgentSession, getCurrentAgentSessionSnapshot, getStoredAgentSessionsForRoomIdentity, getStoredActiveAgentSessionsForRoom, getStoredAgentRoutingStateSnapshot, getStoredAuth, getStoredCurrentRoom, getStoredRoomSession, listStoredCodexLiveSessions, saveAgentSession, setPendingDeviceAuth, setStoredAuth, setStoredAgentIdentity, addLocalChatMessage, addLocalTask, claimLocalTaskReviewLease, getLatestLocalChatMessages, getLocalImportedRoutingAuthority, getLocalChatMessages, getLocalChatThreadRoutingMembership, getLocalTask, listLocalActiveTaskOwnerLeases, listLocalTasks, isLocalChatStorageEnabled, resolveLocalRoomStorageIdentifiers, releaseLocalTaskReviewLease, updateLocalTask, waitForLocalChatMessages, } from "../local-state.js";

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, 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",
@@ -15,6 +16,47 @@ const READ_TOOLS = new Set([
     "status_local_codex_session",
     "rental_list_requests",
 ]);
+export function supervisedToolIsMutation(toolName) {
+    return !READ_TOOLS.has(toolName);
+}
+// The desktop daemon's local control protocol intentionally uses small bounded
+// 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 {
@@ -22,13 +64,25 @@ function instruction(text, data = {}) {
         structuredContent: payload,
     };
 }
+export function durableCompletionResult(result, mutation) {
+    if (mutation)
+        return result;
+    const serializedBytes = Buffer.byteLength(JSON.stringify(result), "utf8");
+    if (serializedBytes <= MAX_DURABLE_READ_RESULT_BYTES)
+        return result;
+    return instruction("The read completed, but its large result was returned live instead of being copied into the durable journal. Issue a fresh read request if this exact request is replayed after a restart.", {
+        code: "SUPERVISED_READ_RESULT_NOT_RETAINED",
+        serialized_bytes: serializedBytes,
+    });
+}
 const productionDependencies = {
+    executeTool: executeCurrentSupervisedTool,
     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")
+    if (profile !== "supervised_room_turn" && profile !== "supervised_mcp_polling")
         return server;
     return new Proxy(server, {
         get(target, property, receiver) {
@@ -37,21 +91,65 @@ export function profileAwareToolServer(server, profile, dependencies = productio
                 return typeof value === "function" ? value.bind(target) : value;
             }
             return (name, ...registration) => {
+                const mutation = supervisedToolIsMutation(name);
                 const callback = registration.at(-1);
                 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() === "") {
                         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({
+                    const executionRequest = {
                         toolName: name,
                         input,
                         mcpRequestId: String(extra.requestId),
-                        mutation: !READ_TOOLS.has(name),
-                    });
+                    };
+                    if (dependencies.executeTool) {
+                        const executed = await dependencies.executeTool(executionRequest);
+                        if (executed.state === "completed") {
+                            return dependencies.withRoom(executed.roomId, () => executed.result);
+                        }
+                    }
+                    const prepared = await dependencies.prepareEffect({ ...executionRequest, mutation });
                     return dependencies.withRoom(prepared.roomId, async () => {
                         if (prepared.state === "completed")
                             return prepared.result;
@@ -94,7 +192,10 @@ export function profileAwareToolServer(server, profile, dependencies = productio
                         }
                         // 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 });
+                        await dependencies.completeEffect({
+                            effectId: prepared.effectId,
+                            result: durableCompletionResult(result, mutation),
+                        });
                         return result;
                     });
                 };